From e5fdb7bf5e5212ee37dd107753967a3c7b3dda68 Mon Sep 17 00:00:00 2001 From: Alan Mond Date: Sat, 4 Oct 2025 11:30:00 -0700 Subject: [PATCH 01/14] add script to process reference docs --- .github/workflows/pull-from-bazel-build.yml | 15 ++- CLAUDE.md | 50 +++++++ .../templates}/hugo_config.yaml.jinja2 | 0 .../templates}/section_index.jinja2 | 0 process-reference-docs.sh | 124 ++++++++++++++++++ 5 files changed, 187 insertions(+), 2 deletions(-) create mode 100644 CLAUDE.md rename {templates => legacy_devsite_to_hugo_converter/templates}/hugo_config.yaml.jinja2 (100%) rename {templates => legacy_devsite_to_hugo_converter/templates}/section_index.jinja2 (100%) create mode 100755 process-reference-docs.sh diff --git a/.github/workflows/pull-from-bazel-build.yml b/.github/workflows/pull-from-bazel-build.yml index fad7bc8..7800919 100644 --- a/.github/workflows/pull-from-bazel-build.yml +++ b/.github/workflows/pull-from-bazel-build.yml @@ -31,17 +31,28 @@ jobs: steps: - uses: actions/checkout@v5 with: - # Don’t auto-init submodules + # Don't auto-init submodules submodules: false - name: Checkout submodules run: git submodule update --init -- upstream - + - name: Checkout commit of Bazel Build submodule if: ${{ inputs.bazelCommitHash != '' }} working-directory: upstream run: git checkout '${{ inputs.bazelCommitHash }}' + - name: Setup Bazel + uses: bazel-contrib/setup-bazel@0.15.0 + with: + bazelisk-cache: true + disk-cache: ${{ github.workflow }} + repository-cache: true + + - name: Build reference documentation + working-directory: upstream + run: bazel build //src/main/java/com/google/devtools/build/lib:gen_reference_docs --config=docs + - name: Clean up mdx files run: ./cleanup-mdx.sh diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a6c97c3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,50 @@ +# Mintlify documentation + +## Working relationship +- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so +- ALWAYS ask for clarification rather than making assumptions +- NEVER lie, guess, or make up anything + +## Project context +- Format: MDX files with YAML frontmatter +- Config: docs.json for navigation, theme, settings +- Components: Mintlify components + +## Content strategy +- Document just enough for user success - not too much, not too little +- Prioritize accuracy and usability +- Make content evergreen when possible +- Search for existing content before adding anything new. Avoid duplication unless it is done for a strategic reason +- Check existing patterns for consistency +- Start by making the smallest reasonable changes + +## docs.json + +- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation + +## Frontmatter requirements for pages +- title: Clear, descriptive page title +- description: Concise summary for SEO/navigation + +## Writing standards +- Second-person voice ("you") +- Prerequisites at start of procedural content +- Test all code examples before publishing +- Match style and formatting of existing pages +- Include both basic and advanced use cases +- Language tags on all code blocks +- Alt text on all images +- Relative paths for internal links + +## Git workflow +- NEVER use --no-verify when committing +- Ask how to handle uncommitted changes before starting +- Create a new branch when no clear branch exists for changes +- Commit frequently throughout development +- NEVER skip or disable pre-commit hooks + +## Do not +- Skip frontmatter on any MDX file +- Use absolute URLs for internal links +- Include untested code examples +- Make assumptions - always ask for clarification \ No newline at end of file diff --git a/templates/hugo_config.yaml.jinja2 b/legacy_devsite_to_hugo_converter/templates/hugo_config.yaml.jinja2 similarity index 100% rename from templates/hugo_config.yaml.jinja2 rename to legacy_devsite_to_hugo_converter/templates/hugo_config.yaml.jinja2 diff --git a/templates/section_index.jinja2 b/legacy_devsite_to_hugo_converter/templates/section_index.jinja2 similarity index 100% rename from templates/section_index.jinja2 rename to legacy_devsite_to_hugo_converter/templates/section_index.jinja2 diff --git a/process-reference-docs.sh b/process-reference-docs.sh new file mode 100755 index 0000000..d3a12d7 --- /dev/null +++ b/process-reference-docs.sh @@ -0,0 +1,124 @@ +#!/bin/bash + +# Script to process Bazel reference documentation from reference-docs.zip +# Usage: ./process-reference-docs.sh + +set -o errexit -o nounset -o pipefail + +if [ $# -ne 1 ]; then + echo "Usage: $0 " + exit 1 +fi + +ZIP_FILE="$1" + +if [ ! -f "$ZIP_FILE" ]; then + echo "Error: File '$ZIP_FILE' not found" + exit 1 +fi + +echo "Processing reference documentation from $ZIP_FILE..." + +# Create temporary directory for extraction +TEMP_DIR=$(mktemp -d) +trap "rm -rf $TEMP_DIR" EXIT + +# Extract the zip file +echo "Extracting reference-docs.zip..." +unzip -q "$ZIP_FILE" -d "$TEMP_DIR" + +# Process reference/be/ HTML files and convert to MDX +echo "Processing Build Encyclopedia (reference/be/) files..." +if [ -d "$TEMP_DIR/reference/be" ]; then + mkdir -p reference/be + + # Convert HTML files to MDX + for html_file in "$TEMP_DIR/reference/be"/*.html; do + if [ -f "$html_file" ]; then + basename_file=$(basename "$html_file") + mdx_file="reference/be/${basename_file%.html}.mdx" + + echo " Converting $(basename "$html_file") to MDX..." + + # Extract title from HTML and create basic MDX structure + # This is a simple conversion - may need refinement + title=$(grep -oP '\K[^<]+' "$html_file" 2>/dev/null || echo "$(basename "${html_file%.html}")") + + # Create MDX file with frontmatter + # Clean up the title to avoid issues with quotes + title=$(echo "$title" | sed "s/'/'\\\''/g") + + { + echo "---" + echo "title: '$title'" + echo "---" + echo "" + # For now, we'll keep the HTML content as-is + # The transform-docs.awk can be enhanced later for HTML->MDX conversion + cat "$html_file" + } > "$mdx_file" + + echo " Created $mdx_file" + fi + done +else + echo "Warning: No reference/be/ directory found in zip" +fi + +# Process command-line reference +echo "Processing command-line reference..." +if [ -f "$TEMP_DIR/reference/command-line-reference.html" ]; then + mkdir -p reference + + title=$(grep -oP '<title>\K[^<]+' "$TEMP_DIR/reference/command-line-reference.html" 2>/dev/null || echo "Command-Line Reference") + title=$(echo "$title" | sed "s/'/'\\\''/g") + + { + echo "---" + echo "title: '$title'" + echo "---" + echo "" + cat "$TEMP_DIR/reference/command-line-reference.html" + } > "reference/command-line-reference.mdx" + + echo " Created reference/command-line-reference.mdx" +else + echo "Warning: command-line-reference.html not found in zip" +fi + +# Process Starlark library docs +echo "Processing Starlark library documentation..." +if [ -d "$TEMP_DIR/rules/lib" ]; then + mkdir -p rules/lib + + # Copy HTML files and convert to MDX + find "$TEMP_DIR/rules/lib" -name "*.html" -type f | while read -r html_file; do + relative_path="${html_file#$TEMP_DIR/rules/lib/}" + mdx_file="rules/lib/${relative_path%.html}.mdx" + + # Create directory structure + mkdir -p "$(dirname "$mdx_file")" + + title=$(grep -oP '<title>\K[^<]+' "$html_file" 2>/dev/null || echo "$(basename "${html_file%.html}")") + title=$(echo "$title" | sed "s/'/'\\\''/g") + + { + echo "---" + echo "title: '$title'" + echo "---" + echo "" + cat "$html_file" + } > "$mdx_file" + + echo " Created $mdx_file" + done +else + echo "Warning: No rules/lib/ directory found in zip" +fi + +echo "Reference documentation processing complete!" +echo "" +echo "Summary:" +echo " - Build Encyclopedia: reference/be/*.mdx" +echo " - Command-Line Reference: reference/command-line-reference.mdx" +echo " - Starlark Library: rules/lib/**/*.mdx" From 241cd444a5855fffdb264e6153dca68d1d66c423 Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sat, 4 Oct 2025 11:59:30 -0700 Subject: [PATCH 02/14] attempt to build with remote cache --- .github/workflows/pull-from-bazel-build.yml | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pull-from-bazel-build.yml b/.github/workflows/pull-from-bazel-build.yml index 7800919..52c603f 100644 --- a/.github/workflows/pull-from-bazel-build.yml +++ b/.github/workflows/pull-from-bazel-build.yml @@ -46,12 +46,29 @@ jobs: uses: bazel-contrib/setup-bazel@0.15.0 with: bazelisk-cache: true - disk-cache: ${{ github.workflow }} repository-cache: true - name: Build reference documentation working-directory: upstream - run: bazel build //src/main/java/com/google/devtools/build/lib:gen_reference_docs --config=docs + run: > + bazel build + --config=docs + --build_metadata=ROLE=DOCS + --remote_header=x-buildbuddy-api-key=${{ secrets.BUILDBUDDY_ORG_API_KEY }} + --bes_results_url=https://app.buildbuddy.io/invocation/ + --bes_backend=grpcs://remote.buildbuddy.io + --remote_cache=grpcs://remote.buildbuddy.io + --remote_timeout=10m + //src/main/java/com/google/devtools/build/lib:gen_reference_docs + + # Upload reference-docs.zip as an artifact for debugging purposes + - name: Upload reference docs artifact + if: ${{ github.ref == 'refs/heads/main' }} + uses: actions/upload-artifact@v4.6.2 + with: + name: reference-docs + path: upstream/bazel-bin/src/main/java/com/google/devtools/build/lib/reference-docs.zip + retention-days: 7 - name: Clean up mdx files run: ./cleanup-mdx.sh From 6bd6b6400c249377465e5fb295d0e7ee1ba8c82d Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sat, 4 Oct 2025 12:10:48 -0700 Subject: [PATCH 03/14] typo --- .github/workflows/pull-from-bazel-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pull-from-bazel-build.yml b/.github/workflows/pull-from-bazel-build.yml index 52c603f..185838c 100644 --- a/.github/workflows/pull-from-bazel-build.yml +++ b/.github/workflows/pull-from-bazel-build.yml @@ -63,7 +63,7 @@ jobs: # Upload reference-docs.zip as an artifact for debugging purposes - name: Upload reference docs artifact - if: ${{ github.ref == 'refs/heads/main' }} + if: ${{ github.ref != 'refs/heads/main' }} uses: actions/upload-artifact@v4.6.2 with: name: reference-docs From 7ebbdf1ec2773aee3c46ae233576ef582454ce23 Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sat, 4 Oct 2025 14:17:55 -0700 Subject: [PATCH 04/14] add reference mdx files --- process-reference-docs.sh | 17 +- reference/be/be-nav.mdx | 57 + reference/be/c-cpp.mdx | 3172 ++++ reference/be/common-definitions.mdx | 1143 ++ reference/be/extra-actions.mdx | 324 + reference/be/functions.mdx | 810 + reference/be/general.mdx | 1529 ++ reference/be/java.mdx | 2740 ++++ reference/be/make-variables.mdx | 526 + reference/be/objective-c.mdx | 558 + reference/be/overview.mdx | 279 + reference/be/platforms-and-toolchains.mdx | 755 + reference/be/protocol-buffer.mdx | 770 + reference/be/python.mdx | 1344 ++ reference/be/shell.mdx | 341 + reference/command-line-reference.mdx | 12297 ++++++++++++++++ rules/lib/builtins.mdx | 140 + rules/lib/builtins/Action.mdx | 96 + rules/lib/builtins/Args.mdx | 423 + rules/lib/builtins/Aspect.mdx | 27 + rules/lib/builtins/Attribute.mdx | 25 + rules/lib/builtins/BuildSetting.mdx | 25 + rules/lib/builtins/CcCompilationOutputs.mdx | 44 + rules/lib/builtins/CcLinkingOutputs.mdx | 46 + rules/lib/builtins/CompilationContext.mdx | 132 + rules/lib/builtins/DirectoryExpander.mdx | 63 + rules/lib/builtins/DottedVersion.mdx | 63 + rules/lib/builtins/ExecGroupCollection.mdx | 25 + rules/lib/builtins/ExecGroupContext.mdx | 36 + rules/lib/builtins/ExecTransitionFactory.mdx | 25 + rules/lib/builtins/ExpandedDirectory.mdx | 44 + rules/lib/builtins/FeatureConfiguration.mdx | 25 + rules/lib/builtins/File.mdx | 117 + rules/lib/builtins/Label.mdx | 181 + rules/lib/builtins/LateBoundDefault.mdx | 25 + rules/lib/builtins/LibraryToLink.mdx | 126 + rules/lib/builtins/License.mdx | 25 + rules/lib/builtins/LinkerInput.mdx | 60 + rules/lib/builtins/LinkingContext.mdx | 36 + rules/lib/builtins/Provider.mdx | 29 + rules/lib/builtins/Subrule.mdx | 25 + rules/lib/builtins/SymlinkEntry.mdx | 44 + rules/lib/builtins/Target.mdx | 33 + rules/lib/builtins/TemplateDict.mdx | 168 + rules/lib/builtins/ToolchainContext.mdx | 25 + rules/lib/builtins/actions.mdx | 988 ++ rules/lib/builtins/apple_platform.mdx | 63 + rules/lib/builtins/bazel_module.mdx | 60 + rules/lib/builtins/bazel_module_tags.mdx | 27 + rules/lib/builtins/configuration.mdx | 70 + rules/lib/builtins/ctx.mdx | 625 + rules/lib/builtins/depset.mdx | 86 + rules/lib/builtins/exec_result.mdx | 54 + rules/lib/builtins/extension_metadata.mdx | 25 + rules/lib/builtins/fragments.mdx | 25 + .../builtins/java_annotation_processing.mdx | 86 + rules/lib/builtins/macro.mdx | 31 + rules/lib/builtins/mapped_root.mdx | 36 + rules/lib/builtins/module_ctx.mdx | 889 ++ rules/lib/builtins/path.mdx | 144 + rules/lib/builtins/propagation_ctx.mdx | 44 + rules/lib/builtins/repo_metadata.mdx | 26 + rules/lib/builtins/repository_ctx.mdx | 1169 ++ rules/lib/builtins/repository_os.mdx | 55 + rules/lib/builtins/repository_rule.mdx | 26 + rules/lib/builtins/root.mdx | 36 + rules/lib/builtins/rule.mdx | 30 + rules/lib/builtins/rule_attributes.mdx | 92 + rules/lib/builtins/runfiles.mdx | 136 + rules/lib/builtins/struct.mdx | 63 + rules/lib/builtins/subrule_ctx.mdx | 60 + rules/lib/builtins/tag_class.mdx | 26 + rules/lib/builtins/template_ctx.mdx | 175 + rules/lib/builtins/toolchain_type.mdx | 44 + rules/lib/builtins/transition.mdx | 94 + rules/lib/builtins/wasm_exec_result.mdx | 60 + rules/lib/builtins/wasm_module.mdx | 36 + rules/lib/core.mdx | 44 + rules/lib/core/bool.mdx | 25 + rules/lib/core/builtin_function_or_method.mdx | 25 + rules/lib/core/dict.mdx | 267 + rules/lib/core/float.mdx | 25 + rules/lib/core/function.mdx | 25 + rules/lib/core/int.mdx | 32 + rules/lib/core/json.mdx | 241 + rules/lib/core/list.mdx | 276 + rules/lib/core/range.mdx | 27 + rules/lib/core/set.mdx | 809 + rules/lib/core/string.mdx | 1031 ++ rules/lib/core/tuple.mdx | 29 + rules/lib/fragments.mdx | 42 + rules/lib/fragments/apple.mdx | 79 + rules/lib/fragments/bazel_android.mdx | 36 + rules/lib/fragments/bazel_py.mdx | 44 + rules/lib/fragments/coverage.mdx | 37 + rules/lib/fragments/cpp.mdx | 101 + rules/lib/fragments/j2objc.mdx | 36 + rules/lib/fragments/java.mdx | 140 + rules/lib/fragments/objc.mdx | 111 + rules/lib/fragments/platform.mdx | 44 + rules/lib/fragments/proto.mdx | 25 + rules/lib/fragments/py.mdx | 84 + rules/lib/globals.mdx | 32 + rules/lib/globals/all.mdx | 1169 ++ rules/lib/globals/build.mdx | 526 + rules/lib/globals/bzl.mdx | 1446 ++ rules/lib/globals/module.mdx | 947 ++ rules/lib/globals/repo.mdx | 97 + rules/lib/globals/vendor.mdx | 96 + rules/lib/overview.mdx | 1094 ++ rules/lib/providers.mdx | 76 + .../lib/providers/AnalysisTestResultInfo.mdx | 89 + rules/lib/providers/CcInfo.mdx | 99 + rules/lib/providers/CcToolchainConfigInfo.mdx | 25 + rules/lib/providers/CcToolchainInfo.mdx | 258 + rules/lib/providers/ConstraintCollection.mdx | 25 + rules/lib/providers/ConstraintSettingInfo.mdx | 36 + rules/lib/providers/ConstraintValueInfo.mdx | 25 + rules/lib/providers/DebugPackageInfo.mdx | 127 + rules/lib/providers/DefaultInfo.mdx | 144 + rules/lib/providers/ExecutionInfo.mdx | 89 + rules/lib/providers/FeatureFlagInfo.mdx | 81 + rules/lib/providers/FilesToRunProvider.mdx | 56 + .../IncompatiblePlatformProvider.mdx | 25 + rules/lib/providers/InstrumentedFilesInfo.mdx | 44 + rules/lib/providers/JavaRuntimeInfo.mdx | 119 + rules/lib/providers/JavaToolchainInfo.mdx | 118 + rules/lib/providers/MaterializedDepsInfo.mdx | 36 + rules/lib/providers/ObjcProvider.mdx | 84 + rules/lib/providers/OutputGroupInfo.mdx | 62 + .../providers/PackageSpecificationInfo.mdx | 63 + rules/lib/providers/PlatformInfo.mdx | 25 + rules/lib/providers/RunEnvironmentInfo.mdx | 44 + rules/lib/providers/TemplateVariableInfo.mdx | 36 + rules/lib/providers/ToolchainInfo.mdx | 25 + rules/lib/providers/ToolchainTypeInfo.mdx | 36 + rules/lib/providers/file_provider.mdx | 25 + rules/lib/providers/java_compilation_info.mdx | 60 + rules/lib/providers/java_output_jars.mdx | 54 + rules/lib/toplevel.mdx | 42 + rules/lib/toplevel/apple_common.mdx | 185 + rules/lib/toplevel/attr.mdx | 1276 ++ rules/lib/toplevel/cc_common.mdx | 2022 +++ rules/lib/toplevel/config.mdx | 288 + rules/lib/toplevel/config_common.mdx | 81 + rules/lib/toplevel/coverage_common.mdx | 113 + rules/lib/toplevel/java_common.mdx | 576 + rules/lib/toplevel/native.mdx | 388 + rules/lib/toplevel/platform_common.mdx | 68 + rules/lib/toplevel/proto.mdx | 115 + rules/lib/toplevel/testing.mdx | 166 + 151 files changed, 50523 insertions(+), 1 deletion(-) create mode 100644 reference/be/be-nav.mdx create mode 100644 reference/be/c-cpp.mdx create mode 100644 reference/be/common-definitions.mdx create mode 100644 reference/be/extra-actions.mdx create mode 100644 reference/be/functions.mdx create mode 100644 reference/be/general.mdx create mode 100644 reference/be/java.mdx create mode 100644 reference/be/make-variables.mdx create mode 100644 reference/be/objective-c.mdx create mode 100644 reference/be/overview.mdx create mode 100644 reference/be/platforms-and-toolchains.mdx create mode 100644 reference/be/protocol-buffer.mdx create mode 100644 reference/be/python.mdx create mode 100644 reference/be/shell.mdx create mode 100644 reference/command-line-reference.mdx create mode 100644 rules/lib/builtins.mdx create mode 100644 rules/lib/builtins/Action.mdx create mode 100644 rules/lib/builtins/Args.mdx create mode 100644 rules/lib/builtins/Aspect.mdx create mode 100644 rules/lib/builtins/Attribute.mdx create mode 100644 rules/lib/builtins/BuildSetting.mdx create mode 100644 rules/lib/builtins/CcCompilationOutputs.mdx create mode 100644 rules/lib/builtins/CcLinkingOutputs.mdx create mode 100644 rules/lib/builtins/CompilationContext.mdx create mode 100644 rules/lib/builtins/DirectoryExpander.mdx create mode 100644 rules/lib/builtins/DottedVersion.mdx create mode 100644 rules/lib/builtins/ExecGroupCollection.mdx create mode 100644 rules/lib/builtins/ExecGroupContext.mdx create mode 100644 rules/lib/builtins/ExecTransitionFactory.mdx create mode 100644 rules/lib/builtins/ExpandedDirectory.mdx create mode 100644 rules/lib/builtins/FeatureConfiguration.mdx create mode 100644 rules/lib/builtins/File.mdx create mode 100644 rules/lib/builtins/Label.mdx create mode 100644 rules/lib/builtins/LateBoundDefault.mdx create mode 100644 rules/lib/builtins/LibraryToLink.mdx create mode 100644 rules/lib/builtins/License.mdx create mode 100644 rules/lib/builtins/LinkerInput.mdx create mode 100644 rules/lib/builtins/LinkingContext.mdx create mode 100644 rules/lib/builtins/Provider.mdx create mode 100644 rules/lib/builtins/Subrule.mdx create mode 100644 rules/lib/builtins/SymlinkEntry.mdx create mode 100644 rules/lib/builtins/Target.mdx create mode 100644 rules/lib/builtins/TemplateDict.mdx create mode 100644 rules/lib/builtins/ToolchainContext.mdx create mode 100644 rules/lib/builtins/actions.mdx create mode 100644 rules/lib/builtins/apple_platform.mdx create mode 100644 rules/lib/builtins/bazel_module.mdx create mode 100644 rules/lib/builtins/bazel_module_tags.mdx create mode 100644 rules/lib/builtins/configuration.mdx create mode 100644 rules/lib/builtins/ctx.mdx create mode 100644 rules/lib/builtins/depset.mdx create mode 100644 rules/lib/builtins/exec_result.mdx create mode 100644 rules/lib/builtins/extension_metadata.mdx create mode 100644 rules/lib/builtins/fragments.mdx create mode 100644 rules/lib/builtins/java_annotation_processing.mdx create mode 100644 rules/lib/builtins/macro.mdx create mode 100644 rules/lib/builtins/mapped_root.mdx create mode 100644 rules/lib/builtins/module_ctx.mdx create mode 100644 rules/lib/builtins/path.mdx create mode 100644 rules/lib/builtins/propagation_ctx.mdx create mode 100644 rules/lib/builtins/repo_metadata.mdx create mode 100644 rules/lib/builtins/repository_ctx.mdx create mode 100644 rules/lib/builtins/repository_os.mdx create mode 100644 rules/lib/builtins/repository_rule.mdx create mode 100644 rules/lib/builtins/root.mdx create mode 100644 rules/lib/builtins/rule.mdx create mode 100644 rules/lib/builtins/rule_attributes.mdx create mode 100644 rules/lib/builtins/runfiles.mdx create mode 100644 rules/lib/builtins/struct.mdx create mode 100644 rules/lib/builtins/subrule_ctx.mdx create mode 100644 rules/lib/builtins/tag_class.mdx create mode 100644 rules/lib/builtins/template_ctx.mdx create mode 100644 rules/lib/builtins/toolchain_type.mdx create mode 100644 rules/lib/builtins/transition.mdx create mode 100644 rules/lib/builtins/wasm_exec_result.mdx create mode 100644 rules/lib/builtins/wasm_module.mdx create mode 100644 rules/lib/core.mdx create mode 100644 rules/lib/core/bool.mdx create mode 100644 rules/lib/core/builtin_function_or_method.mdx create mode 100644 rules/lib/core/dict.mdx create mode 100644 rules/lib/core/float.mdx create mode 100644 rules/lib/core/function.mdx create mode 100644 rules/lib/core/int.mdx create mode 100644 rules/lib/core/json.mdx create mode 100644 rules/lib/core/list.mdx create mode 100644 rules/lib/core/range.mdx create mode 100644 rules/lib/core/set.mdx create mode 100644 rules/lib/core/string.mdx create mode 100644 rules/lib/core/tuple.mdx create mode 100644 rules/lib/fragments.mdx create mode 100644 rules/lib/fragments/apple.mdx create mode 100644 rules/lib/fragments/bazel_android.mdx create mode 100644 rules/lib/fragments/bazel_py.mdx create mode 100644 rules/lib/fragments/coverage.mdx create mode 100644 rules/lib/fragments/cpp.mdx create mode 100644 rules/lib/fragments/j2objc.mdx create mode 100644 rules/lib/fragments/java.mdx create mode 100644 rules/lib/fragments/objc.mdx create mode 100644 rules/lib/fragments/platform.mdx create mode 100644 rules/lib/fragments/proto.mdx create mode 100644 rules/lib/fragments/py.mdx create mode 100644 rules/lib/globals.mdx create mode 100644 rules/lib/globals/all.mdx create mode 100644 rules/lib/globals/build.mdx create mode 100644 rules/lib/globals/bzl.mdx create mode 100644 rules/lib/globals/module.mdx create mode 100644 rules/lib/globals/repo.mdx create mode 100644 rules/lib/globals/vendor.mdx create mode 100644 rules/lib/overview.mdx create mode 100644 rules/lib/providers.mdx create mode 100644 rules/lib/providers/AnalysisTestResultInfo.mdx create mode 100644 rules/lib/providers/CcInfo.mdx create mode 100644 rules/lib/providers/CcToolchainConfigInfo.mdx create mode 100644 rules/lib/providers/CcToolchainInfo.mdx create mode 100644 rules/lib/providers/ConstraintCollection.mdx create mode 100644 rules/lib/providers/ConstraintSettingInfo.mdx create mode 100644 rules/lib/providers/ConstraintValueInfo.mdx create mode 100644 rules/lib/providers/DebugPackageInfo.mdx create mode 100644 rules/lib/providers/DefaultInfo.mdx create mode 100644 rules/lib/providers/ExecutionInfo.mdx create mode 100644 rules/lib/providers/FeatureFlagInfo.mdx create mode 100644 rules/lib/providers/FilesToRunProvider.mdx create mode 100644 rules/lib/providers/IncompatiblePlatformProvider.mdx create mode 100644 rules/lib/providers/InstrumentedFilesInfo.mdx create mode 100644 rules/lib/providers/JavaRuntimeInfo.mdx create mode 100644 rules/lib/providers/JavaToolchainInfo.mdx create mode 100644 rules/lib/providers/MaterializedDepsInfo.mdx create mode 100644 rules/lib/providers/ObjcProvider.mdx create mode 100644 rules/lib/providers/OutputGroupInfo.mdx create mode 100644 rules/lib/providers/PackageSpecificationInfo.mdx create mode 100644 rules/lib/providers/PlatformInfo.mdx create mode 100644 rules/lib/providers/RunEnvironmentInfo.mdx create mode 100644 rules/lib/providers/TemplateVariableInfo.mdx create mode 100644 rules/lib/providers/ToolchainInfo.mdx create mode 100644 rules/lib/providers/ToolchainTypeInfo.mdx create mode 100644 rules/lib/providers/file_provider.mdx create mode 100644 rules/lib/providers/java_compilation_info.mdx create mode 100644 rules/lib/providers/java_output_jars.mdx create mode 100644 rules/lib/toplevel.mdx create mode 100644 rules/lib/toplevel/apple_common.mdx create mode 100644 rules/lib/toplevel/attr.mdx create mode 100644 rules/lib/toplevel/cc_common.mdx create mode 100644 rules/lib/toplevel/config.mdx create mode 100644 rules/lib/toplevel/config_common.mdx create mode 100644 rules/lib/toplevel/coverage_common.mdx create mode 100644 rules/lib/toplevel/java_common.mdx create mode 100644 rules/lib/toplevel/native.mdx create mode 100644 rules/lib/toplevel/platform_common.mdx create mode 100644 rules/lib/toplevel/proto.mdx create mode 100644 rules/lib/toplevel/testing.mdx diff --git a/process-reference-docs.sh b/process-reference-docs.sh index d3a12d7..9544e2f 100755 --- a/process-reference-docs.sh +++ b/process-reference-docs.sh @@ -27,6 +27,21 @@ trap "rm -rf $TEMP_DIR" EXIT echo "Extracting reference-docs.zip..." unzip -q "$ZIP_FILE" -d "$TEMP_DIR" +# Check for nested zip files +nested_zips=$(find "$TEMP_DIR" -maxdepth 1 -name "*.zip" -type f) + +if [ -n "$nested_zips" ]; then + echo "" + echo "Error: The zip file contains another zip file inside it:" + for nested_zip in $nested_zips; do + echo " - $(basename "$nested_zip")" + done + echo "" + echo "Please extract the contents properly before running this script." + echo "The zip should contain the documentation files directly, not another zip." + exit 1 +fi + # Process reference/be/ HTML files and convert to MDX echo "Processing Build Encyclopedia (reference/be/) files..." if [ -d "$TEMP_DIR/reference/be" ]; then @@ -121,4 +136,4 @@ echo "" echo "Summary:" echo " - Build Encyclopedia: reference/be/*.mdx" echo " - Command-Line Reference: reference/command-line-reference.mdx" -echo " - Starlark Library: rules/lib/**/*.mdx" +echo " - Starlark Library: rules/lib/**/*.mdx" \ No newline at end of file diff --git a/reference/be/be-nav.mdx b/reference/be/be-nav.mdx new file mode 100644 index 0000000..beb817b --- /dev/null +++ b/reference/be/be-nav.mdx @@ -0,0 +1,57 @@ +--- +title: 'be-nav' +--- + + +**Build Encyclopedia** + +<ul class="sidebar-nav"> + <li><a href="/reference/be/overview.html">Overview</a></li> + + <li> + + <a data-toggle="collapse" href="#be-menu" aria-expanded="false" + aria-controls="be-menu"> + Concepts <span class="caret"></span> + </a> + <ul class="collapse sidebar-nav sidebar-submenu" id="be-menu"> + <li><a href="/reference/be/common-definitions.html">Common Definitions</a></li> + <li><a href="/reference/be/make-variables.html">"Make" variables</a></li> + </ul> + </li> + + <li> + + <a data-toggle="collapse" href="#be-rules" aria-expanded="false" + aria-controls="be-rules"> + Rules <span class="caret"></span> + </a> + <ul class="collapse sidebar-nav sidebar-submenu" id="be-rules"> + <li><a href="/reference/be/functions.html">Functions</a></li> + <li><a href="/reference/be/c-cpp.html">C / C++</a></li> + <li><a href="/reference/be/java.html">Java</a></li> + <li><a href="/reference/be/objective-c.html">Objective-C</a></li> + <li><a href="/reference/be/protocol-buffer.html">Protocol Buffer</a></li> + <li><a href="/reference/be/python.html">Python</a></li> + <li><a href="/reference/be/shell.html">Shell</a></li> + <li><a href="/reference/be/extra-actions.html">Extra Actions</a></li> + <li><a href="/reference/be/general.html">General</a></li> + <li><a href="/reference/be/platforms-and-toolchains.html">Platforms and Toolchains</a></li> + + <li><a href="https://github.com/bazelbuild/rules_appengine" target="_blank" rel="noopener">AppEngine</a></li> + <li><a href="https://github.com/bazelbuild/rules_apple" target="_blank" rel="noopener">Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)</a></li> + <li><a href="https://github.com/bazelbuild/rules_dotnet" target="_blank" rel="noopener">C#</a></li> + <li><a href="https://github.com/bazelbuild/rules_d" target="_blank" rel="noopener">D</a></li> + <li><a href="https://github.com/bazelbuild/rules_docker" target="_blank" rel="noopener">Docker</a></li> + <li><a href="https://github.com/bazelbuild/rules_groovy" target="_blank" rel="noopener">Groovy</a></li> + <li><a href="https://github.com/bazelbuild/rules_go" target="_blank" rel="noopener">Go</a></li> + <li><a href="https://github.com/bazelbuild/rules_closure" target="_blank" rel="noopener">JavaScript (Closure)</a></li> + <li><a href="https://github.com/bazelbuild/rules_jsonnet" target="_blank" rel="noopener">Jsonnet</a></li> + <li><a href="/reference/be/pkg.html">Packaging</a></li> + <li><a href="https://github.com/bazelbuild/rules_rust" target="_blank" rel="noopener">Rust</a></li> + <li><a href="https://github.com/bazelbuild/rules_sass" target="_blank" rel="noopener">Sass</a></li> + <li><a href="https://github.com/bazelbuild/rules_scala" target="_blank" rel="noopener">Scala</a></li> + </ul> + </li> + +</ul> diff --git a/reference/be/c-cpp.mdx b/reference/be/c-cpp.mdx new file mode 100644 index 0000000..1b436d4 --- /dev/null +++ b/reference/be/c-cpp.mdx @@ -0,0 +1,3172 @@ +--- +title: 'c-cpp' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">C / C++ Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% include "_buttons.html" %} + + + + +<h2>Rules</h2> +<ul> + <li> + <a href="#cc_binary"> + cc_binary </a> + </li> + <li> + <a href="#cc_import"> + cc_import </a> + </li> + <li> + <a href="#cc_library"> + cc_library </a> + </li> + <li> + <a href="#cc_shared_library"> + cc_shared_library </a> + </li> + <li> + <a href="#cc_static_library"> + cc_static_library </a> + </li> + <li> + <a href="#cc_test"> + cc_test </a> + </li> + <li> + <a href="#cc_toolchain"> + cc_toolchain </a> + </li> + <li> + <a href="#fdo_prefetch_hints"> + fdo_prefetch_hints </a> + </li> + <li> + <a href="#fdo_profile"> + fdo_profile </a> + </li> + <li> + <a href="#memprof_profile"> + memprof_profile </a> + </li> + <li> + <a href="#propeller_optimize"> + propeller_optimize </a> + </li> +</ul> + + <h2 id="cc_binary"> + cc_binary + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_binary.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">cc_binary(<a href="#cc_binary.name">name</a>, <a href="#cc_binary.deps">deps</a>, <a href="#cc_binary.srcs">srcs</a>, <a href="#cc_binary.data">data</a>, <a href="#cc_binary.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_binary.conlyopts">conlyopts</a>, <a href="#cc_binary.copts">copts</a>, <a href="#cc_binary.cxxopts">cxxopts</a>, <a href="#cc_binary.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#cc_binary.distribs">distribs</a>, <a href="#cc_binary.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#cc_binary.hdrs_check">hdrs_check</a>, <a href="#cc_binary.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_binary.link_extra_lib">link_extra_lib</a>, <a href="#cc_binary.linkopts">linkopts</a>, <a href="#cc_binary.linkshared">linkshared</a>, <a href="#cc_binary.linkstatic">linkstatic</a>, <a href="#cc_binary.local_defines">local_defines</a>, <a href="#cc_binary.malloc">malloc</a>, <a href="#cc_binary.module_interfaces">module_interfaces</a>, <a href="#cc_binary.nocopts">nocopts</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#cc_binary.reexport_deps">reexport_deps</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_binary.stamp">stamp</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_binary.win_def_file">win_def_file</a>)</pre> + + <p>It produces an executable binary.</p> + +<br/>The <code>name</code> of the target should be the same as the name of the +source file that is the main entry point of the application (minus the extension). +For example, if your entry point is in <code>main.cc</code>, then your name should +be <code>main</code>. + +<h4>Implicit output targets</h4> +<ul> +<li><code><var>name</var>.stripped</code> (only built if explicitly requested): A stripped + version of the binary. <code>strip -g</code> is run on the binary to remove debug + symbols. Additional strip options can be provided on the command line using + <code>--stripopt=-foo</code>.</li> +<li><code><var>name</var>.dwp</code> (only built if explicitly requested): If + <a href="https://gcc.gnu.org/wiki/DebugFission">Fission</a> is enabled: a debug + information package file suitable for debugging remotely deployed binaries. Else: an + empty file.</li> +</ul> + + <h3 id="cc_binary_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="cc_binary.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="cc_binary.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries to be linked in to the binary target. +<p>These can be <code>cc_library</code> or <code>objc_library</code> +targets.</p> + +It is also allowed to +put linker scripts (.lds) into deps, and reference them in +<a href="#cc_binary.linkopts">linkopts</a>. + </td> + </tr> + <tr> + <td id="cc_binary.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of C and C++ files that are processed to create the library target. +These are C/C++ source and header files, either non-generated (normal source +code) or generated. +<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will + be compiled. These might be generated files: if a named file is in + the <code>outs</code> of some other rule, this <code>cc_library</code> + will automatically depend on that other rule. +</p> +<p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using +the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built +using the C/C++ compiler. +</p> +<p>A <code>.h</code> file will not be compiled, but will be available for + inclusion by sources in this rule. Both <code>.cc</code> and + <code>.h</code> files can directly include headers listed in + these <code>srcs</code> or in the <code>hdrs</code> of this rule or any + rule listed in the <code>deps</code> argument. +</p> +<p>All <code>#include</code>d files must be mentioned in the + <code>hdrs</code> attribute of this or referenced <code>cc_library</code> + rules, or they should be listed in <code>srcs</code> if they are private + to this library. See <a href="#hdrs">"Header inclusion checking"</a> for + a more detailed description. +</p> +<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are + pre-compiled files. Your library might have these as + <code>srcs</code> if it uses third-party code for which we don't + have source code. +</p> +<p>If the <code>srcs</code> attribute includes the label of another rule, + <code>cc_library</code> will use the output files of that rule as source files to + compile. This is useful for one-off generation of source code (for more than occasional + use, it's better to implement a Starlark rule class and use the <code>cc_common</code> + API) +</p> +<p> + Permitted <code>srcs</code> file types: +</p> +<ul> +<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, + <code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> +<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, + <code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> +<li>Assembler with C preprocessor: <code>.S</code></li> +<li>Archive: <code>.a</code>, <code>.pic.a</code></li> +<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> +<li>Shared library, versioned or unversioned: <code>.so</code>, + <code>.so.<i>version</i></code></li> +<li>Object file: <code>.o</code>, <code>.pic.o</code></li> +</ul> + +<p> + ... and any rules that produce those files (e.g. <code>cc_embed_data</code>). + Different extensions denote different programming languages in + accordance with gcc convention. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this library at runtime. + +See general comments about <code>data</code> +at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. +<p>If a <code>data</code> is the name of a generated file, then this + <code>cc_library</code> rule automatically depends on the generating + rule. +</p> +<p>If a <code>data</code> is a rule name, then this + <code>cc_library</code> rule automatically depends on that rule, + and that rule's <code>outs</code> are automatically added to + this <code>cc_library</code>'s data files. +</p> +<p>Your C++ code can access these data files like so:</p> +<pre><code class="lang-starlark"> + const std::string path = devtools_build::GetDataDependencyFilepath( + "my/test/data/file"); +</code></pre> + </td> + </tr> + <tr> + <td id="cc_binary.additional_linker_inputs"> + <code>additional_linker_inputs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Pass these files to the C++ linker command. +<p> + For example, compiled Windows .res files can be provided here to be embedded in + the binary target. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.conlyopts"> + <code>conlyopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. + </td> + </tr> + <tr> + <td id="cc_binary.copts"> + <code>copts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C/C++ compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +<p> + Each string in this attribute is added in the given order to <code>COPTS</code> before + compiling the binary target. The flags take effect only for compiling this target, not + its dependencies, so be careful about header files included elsewhere. + All paths should be relative to the workspace, not to the current package. + This attribute should not be needed outside of <code>third_party</code>. +</p> +<p> + If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> + <code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings + that consist of a single "Make" variable. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.cxxopts"> + <code>cxxopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C++ compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. + </td> + </tr> + <tr> + <td id="cc_binary.defines"> + <code>defines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of defines to add to the compile line. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +Each string, which must consist of a single Bourne shell token, +is prepended with <code>-D</code> and added to the compile command line to this target, +as well as to every rule that depends on it. Be very careful, since this may have +far-reaching effects. When in doubt, add define values to +<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead. + </td> + </tr> + <tr> + <td id="cc_binary.distribs"> + <code>distribs</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_binary.dynamic_deps"> + <code>dynamic_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + These are other <code>cc_shared_library</code> dependencies the current target depends on. + +<p> +The <code>cc_shared_library</code> implementation will use the list of +<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the +current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in +the transitive <code>deps</code> should not be linked in because they are already provided +by a different <code>cc_shared_library</code>. + </td> + </tr> + <tr> + <td id="cc_binary.hdrs_check"> + <code>hdrs_check</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Deprecated, no-op. + </td> + </tr> + <tr> + <td id="cc_binary.includes"> + <code>includes</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of include dirs to be added to the compile line. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. +Each string is prepended with the package path and passed to the C++ toolchain for +expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system +with typical feature definitions will produce +<code>-isystem path_to_package/include_entry</code>. +This should only be used for third-party libraries that +do not conform to the Google style of writing #include statements. +Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. +<p> +The added <code>include</code> paths will include generated files as well as +files in the source tree. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.link_extra_lib"> + <code>link_extra_lib</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p> + Control linking of extra libraries. +<p> + By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>, + which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>. + Without setting the flag, this library is empty by default. Setting the label flag + allows linking optional dependencies, such as overrides for weak symbols, interceptors + for shared library functions, or special runtime libraries (for malloc replacements, + prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to + <code>None</code> disables this behaviour. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.linkopts"> + <code>linkopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these flags to the C++ linker command. +Subject to <a href="make-variables.html">"Make" variable</a> substitution, +<a href="common-definitions.html#sh-tokenization"> +Bourne shell tokenization</a> and +<a href="common-definitions.html#label-expansion">label expansion</a>. +Each string in this attribute is added to <code>LINKOPTS</code> before +linking the binary target. +<p> + Each element of this list that does not start with <code>$</code> or <code>-</code> is + assumed to be the label of a target in <code>deps</code>. The + list of files generated by that target is appended to the linker + options. An error is reported if the label is invalid, or is + not declared in <code>deps</code>. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.linkshared"> + <code>linkshared</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Create a shared library. +To enable this attribute, include <code>linkshared=True</code> in your rule. By default +this option is off. +<p> + The presence of this flag means that linking occurs with the <code>-shared</code> flag + to <code>gcc</code>, and the resulting shared library is suitable for loading into for + example a Java program. However, for build purposes it will never be linked into the + dependent binary, as it is assumed that shared libraries built with a + <a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so + it should not be considered a substitute for the <a href="#cc_library">cc_library</a> + rule. For sake of scalability we recommend avoiding this approach altogether and + simply letting <code>java_library</code> depend on <code>cc_library</code> rules + instead. +</p> +<p> + If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>, + you get a single completely self-contained unit. If you specify both + <code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly + self-contained unit. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.linkstatic"> + <code>linkstatic</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and +<a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static +mode. For <code>cc_library.link_static</code>: see below. +<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> +<p> + If enabled and this is a binary or test, this option tells the build tool to link in + <code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. + System libraries such as libc (but <i>not</i> the C/C++ runtime libraries, + see below) are still linked dynamically, as are libraries for which + there is no static library. So the resulting executable will still be dynamically + linked, hence only <i>mostly</i> static. +</p> +<p> +There are really three different ways to link an executable: +</p> +<ul> +<li> STATIC with fully_static_link feature, in which everything is linked statically; + e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/> + This mode is enabled by specifying <code>fully_static_link</code> in the + <a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> +<li> STATIC, in which all user libraries are linked statically (if a static + version is available), but where system libraries (excluding C/C++ runtime libraries) + are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/> + This mode is enabled by specifying <code>linkstatic=True</code>.</li> +<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is + available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/> + This mode is enabled by specifying <code>linkstatic=False</code>.</li> +</ul> +<p> +If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in +<code>features</code> is used outside of <code>//third_party</code> +please include a comment near the rule to explain why. +</p> +<p> +The <code>linkstatic</code> attribute has a different meaning if used on a +<a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. +For a C++ library, <code>linkstatic=True</code> indicates that only +static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does +not prevent static libraries from being created. The attribute is meant to control the +creation of dynamic libraries. +</p> +<p> +There should be very little code built with <code>linkstatic=False</code> in production. +If <code>linkstatic=False</code>, then the build tool will create symlinks to +depended-upon shared libraries in the <code>*.runfiles</code> area. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.local_defines"> + <code>local_defines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of defines to add to the compile line. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +Each string, which must consist of a single Bourne shell token, +is prepended with <code>-D</code> and added to the compile command line for this target, +but not to its dependents. + </td> + </tr> + <tr> + <td id="cc_binary.malloc"> + <code>malloc</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p> + Override the default dependency on malloc. +<p> + By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>, + which is an empty library so the binary ends up using libc malloc. + This label must refer to a <code>cc_library</code>. If compilation is for a non-C++ + rule, this option has no effect. The value of this attribute is ignored if + <code>linkshared=True</code> is specified. +</p> + </td> + </tr> + <tr> + <td id="cc_binary.module_interfaces"> + <code>module_interfaces</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files are regarded as C++20 Modules Interface. + +<p> +C++ Standard has no restriction about module interface file extension +<ul> +<li>Clang use cppm </li> +<li>GCC can use any source file extension </li> +<li>MSVC use ixx </li> +</ul> +</p> +<p>The use is guarded by the flag +<code>--experimental_cpp_modules</code>.</p> + </td> + </tr> + <tr> + <td id="cc_binary.nocopts"> + <code>nocopts</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Remove matching options from the C++ compilation command. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. +The value of this attribute is interpreted as a regular expression. +Any preexisting <code>COPTS</code> that match this regular expression +(including values explicitly specified in the rule's <a +href="#cc_binary.copts">copts</a> attribute) +will be removed from <code>COPTS</code> for purposes of compiling this rule. +This attribute should not be needed or used +outside of <code>third_party</code>. The values are not preprocessed +in any way other than the "Make" variable substitution. + </td> + </tr> + <tr> + <td id="cc_binary.reexport_deps"> + <code>reexport_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_binary.stamp"> + <code>stamp</code> + </td> + <td> + <p>Integer; default is <code>-1</code></p> + Whether to encode build information into the binary. Possible values: +<ul> +<li> + <code>stamp = 1</code>: Always stamp the build information into the binary, even in + <a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This + setting should be avoided</b>, since it potentially kills remote caching for the + binary and any downstream actions that depend on it. +</li> +<li> + <code>stamp = 0</code>: Always replace build information by constant values. This + gives good build result caching. +</li> +<li> + <code>stamp = -1</code>: Embedding of build information is controlled by the + <a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag. +</li> +</ul> +<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> + </td> + </tr> + <tr> + <td id="cc_binary.win_def_file"> + <code>win_def_file</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + The Windows DEF file to be passed to linker. +<p>This attribute should only be used when Windows is the target platform. +It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx"> +export symbols</a> during linking a shared library.</p> + </td> + </tr> + </tbody> + </table> + <h2 id="cc_import"> + cc_import + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_import.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">cc_import(<a href="#cc_import.name">name</a>, <a href="#cc_import.deps">deps</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#cc_import.hdrs">hdrs</a>, <a href="#cc_import.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#cc_import.includes">includes</a>, <a href="#cc_import.interface_library">interface_library</a>, <a href="#cc_import.linkopts">linkopts</a>, <a href="#cc_import.objects">objects</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#cc_import.pic_objects">pic_objects</a>, <a href="#cc_import.pic_static_library">pic_static_library</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_import.shared_library">shared_library</a>, <a href="#cc_import.static_library">static_library</a>, <a href="#cc_import.strip_include_prefix">strip_include_prefix</a>, <a href="#cc_import.system_provided">system_provided</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> +<code>cc_import</code> rules allows users to import precompiled C/C++ libraries. +</p> + +<p> +The following are the typical use cases: <br/> + +1. Linking a static library +<pre><code class="lang-starlark"> +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + static_library = "libmylib.a", + # If alwayslink is turned on, + # libmylib.a will be forcely linked into any binary that depends on it. + # alwayslink = 1, +) +</code></pre> + +2. Linking a shared library (Unix) +<pre><code class="lang-starlark"> +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + shared_library = "libmylib.so", +) +</code></pre> + +3. Linking a shared library with interface library + +<p>On Unix: +<pre><code class="lang-starlark"> +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + # libmylib.ifso is an interface library for libmylib.so which will be passed to linker + interface_library = "libmylib.ifso", + # libmylib.so will be available for runtime + shared_library = "libmylib.so", +) +</code></pre> + +<p>On Windows: +<pre><code class="lang-starlark"> +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + # mylib.lib is an import library for mylib.dll which will be passed to linker + interface_library = "mylib.lib", + # mylib.dll will be available for runtime + shared_library = "mylib.dll", +) +</code></pre> + +4. Linking a shared library with <code>system_provided=True</code> + +<p>On Unix: +<pre><code class="lang-starlark"> +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + interface_library = "libmylib.ifso", # Or we can also use libmylib.so as its own interface library + # libmylib.so is provided by system environment, for example it can be found in LD_LIBRARY_PATH. + # This indicates that Bazel is not responsible for making libmylib.so available. + system_provided = 1, +) +</code></pre> + +<p>On Windows: +<pre><code class="lang-starlark"> +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + # mylib.lib is an import library for mylib.dll which will be passed to linker + interface_library = "mylib.lib", + # mylib.dll is provided by system environment, for example it can be found in PATH. + # This indicates that Bazel is not responsible for making mylib.dll available. + system_provided = 1, +) +</code></pre> + +5. Linking to static or shared library + +<p>On Unix: +<pre><code class="lang-starlark"> +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + static_library = "libmylib.a", + shared_library = "libmylib.so", +) +</code></pre> + +<p>On Windows: +<pre><code class="lang-starlark"> +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + static_library = "libmylib.lib", # A normal static library + interface_library = "mylib.lib", # An import library for mylib.dll + shared_library = "mylib.dll", +) +</code></pre> + +<p>The remaining is the same on Unix and Windows: +<pre><code class="lang-starlark"> +# first will link to libmylib.a (or libmylib.lib) +cc_binary( + name = "first", + srcs = ["first.cc"], + deps = [":mylib"], + linkstatic = 1, # default value +) + +# second will link to libmylib.so (or libmylib.lib) +cc_binary( + name = "second", + srcs = ["second.cc"], + deps = [":mylib"], + linkstatic = 0, +) +</code></pre> + +<p> +<code>cc_import</code> supports an include attribute. For example: +<pre><code class="lang-starlark"> +cc_import( + name = "curl_lib", + hdrs = glob(["vendor/curl/include/curl/*.h"]), + includes = ["vendor/curl/include"], + shared_library = "vendor/curl/lib/.libs/libcurl.dylib", +) +</code></pre> +</p> + + <h3 id="cc_import_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="cc_import.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="cc_import.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries that the target depends upon. +See general comments about <code>deps</code> +at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. + </td> + </tr> + <tr> + <td id="cc_import.hdrs"> + <code>hdrs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of header files published by +this precompiled library to be directly included by sources in dependent rules. + </td> + </tr> + <tr> + <td id="cc_import.alwayslink"> + <code>alwayslink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + If 1, any binary that depends (directly or indirectly) on this C++ +precompiled library will link in all the object files archived in the static library, +even if some contain no symbols referenced by the binary. +This is useful if your code isn't explicitly called by code in +the binary, e.g., if your code registers to receive some callback +provided by some service. + +<p>If alwayslink doesn't work with VS 2017 on Windows, that is due to a +<a href="https://github.com/bazelbuild/bazel/issues/3949">known issue</a>, +please upgrade your VS 2017 to the latest version.</p> + </td> + </tr> + <tr> + <td id="cc_import.includes"> + <code>includes</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of include dirs to be added to the compile line. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. +Each string is prepended with the package path and passed to the C++ toolchain for +expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system +with typical feature definitions will produce +<code>-isystem path_to_package/include_entry</code>. +This should only be used for third-party libraries that +do not conform to the Google style of writing #include statements. +Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. +<p> +The default <code>include</code> path doesn't include generated +files. If you need to <code>#include</code> a generated header +file, list it in the <code>srcs</code>. +</p> + </td> + </tr> + <tr> + <td id="cc_import.interface_library"> + <code>interface_library</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + A single interface library for linking the shared library. +<p> Permitted file types: + <code>.ifso</code>, + <code>.tbd</code>, + <code>.lib</code>, + <code>.so</code> + or <code>.dylib</code> +</p> + </td> + </tr> + <tr> + <td id="cc_import.linkopts"> + <code>linkopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these flags to the C++ linker command. +Subject to <a href="make-variables.html">"Make" variable</a> substitution, +<a href="common-definitions.html#sh-tokenization"> +Bourne shell tokenization</a> and +<a href="common-definitions.html#label-expansion">label expansion</a>. +Each string in this attribute is added to <code>LINKOPTS</code> before +linking the binary target. +<p> + Each element of this list that does not start with <code>$</code> or <code>-</code> is + assumed to be the label of a target in <code>deps</code>. The + list of files generated by that target is appended to the linker + options. An error is reported if the label is invalid, or is + not declared in <code>deps</code>. +</p> + </td> + </tr> + <tr> + <td id="cc_import.objects"> + <code>objects</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_import.pic_objects"> + <code>pic_objects</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_import.pic_static_library"> + <code>pic_static_library</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + + </td> + </tr> + <tr> + <td id="cc_import.shared_library"> + <code>shared_library</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + A single precompiled shared library. Bazel ensures it is available to the +binary that depends on it during runtime. +<p> Permitted file types: + <code>.so</code>, + <code>.dll</code> + or <code>.dylib</code> +</p> + </td> + </tr> + <tr> + <td id="cc_import.static_library"> + <code>static_library</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + A single precompiled static library. +<p> Permitted file types: + <code>.a</code>, + <code>.pic.a</code> + or <code>.lib</code> +</p> + </td> + </tr> + <tr> + <td id="cc_import.strip_include_prefix"> + <code>strip_include_prefix</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The prefix to strip from the paths of the headers of this rule. + +<p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible +at their path with this prefix cut off. + +<p>If it's a relative path, it's taken as a package-relative one. If it's an absolute one, +it's understood as a repository-relative path. + +<p>The prefix in the <code>include_prefix</code> attribute is added after this prefix is +stripped. + +<p>This attribute is only legal under <code>third_party</code>. + </td> + </tr> + <tr> + <td id="cc_import.system_provided"> + <code>system_provided</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + If 1, it indicates the shared library required at runtime is provided by the system. In +this case, <code>interface_library</code> should be specified and +<code>shared_library</code> should be empty. + </td> + </tr> + </tbody> + </table> + <h2 id="cc_library"> + cc_library + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">cc_library(<a href="#cc_library.name">name</a>, <a href="#cc_library.deps">deps</a>, <a href="#cc_library.srcs">srcs</a>, <a href="#cc_library.data">data</a>, <a href="#cc_library.hdrs">hdrs</a>, <a href="#cc_library.additional_compiler_inputs">additional_compiler_inputs</a>, <a href="#cc_library.additional_linker_inputs">additional_linker_inputs</a>, <a href="#cc_library.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_library.conlyopts">conlyopts</a>, <a href="#cc_library.copts">copts</a>, <a href="#cc_library.cxxopts">cxxopts</a>, <a href="#cc_library.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#cc_library.hdrs_check">hdrs_check</a>, <a href="#cc_library.implementation_deps">implementation_deps</a>, <a href="#cc_library.include_prefix">include_prefix</a>, <a href="#cc_library.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_library.linkopts">linkopts</a>, <a href="#cc_library.linkstamp">linkstamp</a>, <a href="#cc_library.linkstatic">linkstatic</a>, <a href="#cc_library.local_defines">local_defines</a>, <a href="#cc_library.module_interfaces">module_interfaces</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_library.strip_include_prefix">strip_include_prefix</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="#cc_library.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_library.win_def_file">win_def_file</a>)</pre> + + <p>Use <code>cc_library()</code> for C++-compiled libraries. + The result is either a <code>.so</code>, <code>.lo</code>, + or <code>.a</code>, depending on what is needed. +</p> + +<p> + If you build something with static linking that depends on + a <code>cc_library</code>, the output of a depended-on library rule + is the <code>.a</code> file. If you specify + <code>alwayslink=True</code>, you get the <code>.lo</code> file. +</p> + +<p> + The actual output file name is <code>lib<i>foo</i>.so</code> for + the shared library, where <i>foo</i> is the name of the rule. The + other kinds of libraries end with <code>.lo</code> and <code>.a</code>, + respectively. If you need a specific shared library name, for + example, to define a Python module, use a genrule to copy the library + to the desired name. +</p> + +<h4 id="hdrs">Header inclusion checking</h4> + +<p> + All header files that are used in the build must be declared in + the <code>hdrs</code> or <code>srcs</code> of <code>cc_*</code> rules. + This is enforced. +</p> + +<p> + For <code>cc_library</code> rules, headers in <code>hdrs</code> comprise the + public interface of the library and can be directly included both + from the files in <code>hdrs</code> and <code>srcs</code> of the library + itself as well as from files in <code>hdrs</code> and <code>srcs</code> + of <code>cc_*</code> rules that list the library in their <code>deps</code>. + Headers in <code>srcs</code> must only be directly included from the files + in <code>hdrs</code> and <code>srcs</code> of the library itself. When + deciding whether to put a header into <code>hdrs</code> or <code>srcs</code>, + you should ask whether you want consumers of this library to be able to + directly include it. This is roughly the same decision as + between <code>public</code> and <code>private</code> visibility in programming languages. +</p> + +<p> + <code>cc_binary</code> and <code>cc_test</code> rules do not have an exported + interface, so they also do not have a <code>hdrs</code> attribute. All headers + that belong to the binary or test directly should be listed in + the <code>srcs</code>. +</p> + +<p> + To illustrate these rules, look at the following example. +</p> + +<pre><code class="lang-starlark"> +cc_binary( + name = "foo", + srcs = [ + "foo.cc", + "foo.h", + ], + deps = [":bar"], +) + +cc_library( + name = "bar", + srcs = [ + "bar.cc", + "bar-impl.h", + ], + hdrs = ["bar.h"], + deps = [":baz"], +) + +cc_library( + name = "baz", + srcs = [ + "baz.cc", + "baz-impl.h", + ], + hdrs = ["baz.h"], +) +</code></pre> + +<p> + The allowed direct inclusions in this example are listed in the table below. + For example <code>foo.cc</code> is allowed to directly + include <code>foo.h</code> and <code>bar.h</code>, but not <code>baz.h</code>. +</p> + +<table class="table table-striped table-bordered table-condensed"> + <thead> + <tr><th>Including file</th><th>Allowed inclusions</th></tr> + </thead> + <tbody> + <tr><td>foo.h</td><td>bar.h</td></tr> + <tr><td>foo.cc</td><td>foo.h bar.h</td></tr> + <tr><td>bar.h</td><td>bar-impl.h baz.h</td></tr> + <tr><td>bar-impl.h</td><td>bar.h baz.h</td></tr> + <tr><td>bar.cc</td><td>bar.h bar-impl.h baz.h</td></tr> + <tr><td>baz.h</td><td>baz-impl.h</td></tr> + <tr><td>baz-impl.h</td><td>baz.h</td></tr> + <tr><td>baz.cc</td><td>baz.h baz-impl.h</td></tr> + </tbody> +</table> + +<p> + The inclusion checking rules only apply to <em>direct</em> + inclusions. In the example above <code>foo.cc</code> is allowed to + include <code>bar.h</code>, which may include <code>baz.h</code>, which in + turn is allowed to include <code>baz-impl.h</code>. Technically, the + compilation of a <code>.cc</code> file may transitively include any header + file in the <code>hdrs</code> or <code>srcs</code> in + any <code>cc_library</code> in the transitive <code>deps</code> closure. In + this case the compiler may read <code>baz.h</code> and <code>baz-impl.h</code> + when compiling <code>foo.cc</code>, but <code>foo.cc</code> must not + contain <code>#include "baz.h"</code>. For that to be + allowed, <code>baz</code> must be added to the <code>deps</code> + of <code>foo</code>. +</p> + +<p> + Bazel depends on toolchain support to enforce the inclusion checking rules. + The <code>layering_check</code> feature has to be supported by the toolchain + and requested explicitly, for example via the + <code>--features=layering_check</code> command-line flag or the + <code>features</code> parameter of the + <a href="/reference/be/functions.html#package"><code>package</code></a> function. The toolchains + provided by Bazel only support this feature with clang on Unix and macOS. +</p> + +<h4 id="cc_library_examples">Examples</h4> + +<p id="alwayslink_lib_example"> + We use the <code>alwayslink</code> flag to force the linker to link in + this code although the main binary code doesn't reference it. +</p> + +<pre><code class="lang-starlark"> +cc_library( + name = "ast_inspector_lib", + srcs = ["ast_inspector_lib.cc"], + hdrs = ["ast_inspector_lib.h"], + visibility = ["//visibility:public"], + deps = ["//third_party/llvm/llvm/tools/clang:frontend"], + # alwayslink as we want to be able to call things in this library at + # debug time, even if they aren't used anywhere in the code. + alwayslink = 1, +) +</code></pre> + + +<p>The following example comes from + <code>third_party/python2_4_3/BUILD</code>. + Some of the code uses the <code>dl</code> library (to load + another, dynamic library), so this + rule specifies the <code>-ldl</code> link option to link the + <code>dl</code> library. +</p> + +<pre><code class="lang-starlark"> +cc_library( + name = "python2_4_3", + linkopts = [ + "-ldl", + "-lutil", + ], + deps = ["//third_party/expat"], +) +</code></pre> + +<p>The following example comes from <code>third_party/kde/BUILD</code>. + We keep pre-built <code>.so</code> files in the depot. + The header files live in a subdirectory named <code>include</code>. +</p> + +<pre><code class="lang-starlark"> +cc_library( + name = "kde", + srcs = [ + "lib/libDCOP.so", + "lib/libkdesu.so", + "lib/libkhtml.so", + "lib/libkparts.so", + <var>...more .so files...</var>, + ], + includes = ["include"], + deps = ["//third_party/X11"], +) +</code></pre> + +<p>The following example comes from <code>third_party/gles/BUILD</code>. + Third-party code often needs some <code>defines</code> and + <code>linkopts</code>. +</p> + +<pre><code class="lang-starlark"> +cc_library( + name = "gles", + srcs = [ + "GLES/egl.h", + "GLES/gl.h", + "ddx.c", + "egl.c", + ], + defines = [ + "USE_FLOAT", + "__GL_FLOAT", + "__GL_COMMON", + ], + linkopts = ["-ldl"], # uses dlopen(), dl library + deps = [ + "es", + "//third_party/X11", + ], +) +</code></pre> + + <h3 id="cc_library_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="cc_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="cc_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries that the library target depends upon. + +<p>These can be <code>cc_library</code> or <code>objc_library</code> targets.</p> + +<p>See general comments about <code>deps</code> + at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by + most build rules</a>. +</p> +<p>These should be names of C++ library rules. + When you build a binary that links this rule's library, + you will also link the libraries in <code>deps</code>. +</p> +<p>Despite the "deps" name, not all of this library's clients + belong here. Run-time data dependencies belong in <code>data</code>. + Source files generated by other rules belong in <code>srcs</code>. +</p> +<p>To link in a pre-compiled third-party library, add its name to + the <code>srcs</code> instead. +</p> +<p>To depend on something without linking it to this library, add its + name to the <code>data</code> instead. +</p> + </td> + </tr> + <tr> + <td id="cc_library.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of C and C++ files that are processed to create the library target. +These are C/C++ source and header files, either non-generated (normal source +code) or generated. +<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will + be compiled. These might be generated files: if a named file is in + the <code>outs</code> of some other rule, this <code>cc_library</code> + will automatically depend on that other rule. +</p> +<p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using +the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built +using the C/C++ compiler. +</p> +<p>A <code>.h</code> file will not be compiled, but will be available for + inclusion by sources in this rule. Both <code>.cc</code> and + <code>.h</code> files can directly include headers listed in + these <code>srcs</code> or in the <code>hdrs</code> of this rule or any + rule listed in the <code>deps</code> argument. +</p> +<p>All <code>#include</code>d files must be mentioned in the + <code>hdrs</code> attribute of this or referenced <code>cc_library</code> + rules, or they should be listed in <code>srcs</code> if they are private + to this library. See <a href="#hdrs">"Header inclusion checking"</a> for + a more detailed description. +</p> +<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are + pre-compiled files. Your library might have these as + <code>srcs</code> if it uses third-party code for which we don't + have source code. +</p> +<p>If the <code>srcs</code> attribute includes the label of another rule, + <code>cc_library</code> will use the output files of that rule as source files to + compile. This is useful for one-off generation of source code (for more than occasional + use, it's better to implement a Starlark rule class and use the <code>cc_common</code> + API) +</p> +<p> + Permitted <code>srcs</code> file types: +</p> +<ul> +<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, + <code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> +<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, + <code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> +<li>Assembler with C preprocessor: <code>.S</code></li> +<li>Archive: <code>.a</code>, <code>.pic.a</code></li> +<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> +<li>Shared library, versioned or unversioned: <code>.so</code>, + <code>.so.<i>version</i></code></li> +<li>Object file: <code>.o</code>, <code>.pic.o</code></li> +</ul> + +<p> + ... and any rules that produce those files (e.g. <code>cc_embed_data</code>). + Different extensions denote different programming languages in + accordance with gcc convention. +</p> + </td> + </tr> + <tr> + <td id="cc_library.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this library at runtime. + +See general comments about <code>data</code> +at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. +<p>If a <code>data</code> is the name of a generated file, then this + <code>cc_library</code> rule automatically depends on the generating + rule. +</p> +<p>If a <code>data</code> is a rule name, then this + <code>cc_library</code> rule automatically depends on that rule, + and that rule's <code>outs</code> are automatically added to + this <code>cc_library</code>'s data files. +</p> +<p>Your C++ code can access these data files like so:</p> +<pre><code class="lang-starlark"> + const std::string path = devtools_build::GetDataDependencyFilepath( + "my/test/data/file"); +</code></pre> + </td> + </tr> + <tr> + <td id="cc_library.hdrs"> + <code>hdrs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of header files published by +this library to be directly included by sources in dependent rules. +<p>This is the strongly preferred location for declaring header files that + describe the interface for the library. These headers will be made + available for inclusion by sources in this rule or in dependent rules. + Headers not meant to be included by a client of this library should be + listed in the <code>srcs</code> attribute instead, even if they are + included by a published header. See <a href="#hdrs">"Header inclusion + checking"</a> for a more detailed description. </p> +<p>Permitted <code>headers</code> file types: + <code>.h</code>, + <code>.hh</code>, + <code>.hpp</code>, + <code>.hxx</code>. +</p> + </td> + </tr> + <tr> + <td id="cc_library.additional_compiler_inputs"> + <code>additional_compiler_inputs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Any additional files you might want to pass to the compiler command line, such as sanitizer +ignorelists, for example. Files specified here can then be used in copts with the +$(location) function. + </td> + </tr> + <tr> + <td id="cc_library.additional_linker_inputs"> + <code>additional_linker_inputs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Pass these files to the C++ linker command. +<p> + For example, compiled Windows .res files can be provided here to be embedded in + the binary target. +</p> + </td> + </tr> + <tr> + <td id="cc_library.alwayslink"> + <code>alwayslink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + If 1, any binary that depends (directly or indirectly) on this C++ +library will link in all the object files for the files listed in +<code>srcs</code>, even if some contain no symbols referenced by the binary. +This is useful if your code isn't explicitly called by code in +the binary, e.g., if your code registers to receive some callback +provided by some service. + +<p>If alwayslink doesn't work with VS 2017 on Windows, that is due to a +<a href="https://github.com/bazelbuild/bazel/issues/3949">known issue</a>, +please upgrade your VS 2017 to the latest version.</p> + </td> + </tr> + <tr> + <td id="cc_library.conlyopts"> + <code>conlyopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. + </td> + </tr> + <tr> + <td id="cc_library.copts"> + <code>copts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C/C++ compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +<p> + Each string in this attribute is added in the given order to <code>COPTS</code> before + compiling the binary target. The flags take effect only for compiling this target, not + its dependencies, so be careful about header files included elsewhere. + All paths should be relative to the workspace, not to the current package. + This attribute should not be needed outside of <code>third_party</code>. +</p> +<p> + If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> + <code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings + that consist of a single "Make" variable. +</p> + </td> + </tr> + <tr> + <td id="cc_library.cxxopts"> + <code>cxxopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C++ compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. + </td> + </tr> + <tr> + <td id="cc_library.defines"> + <code>defines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of defines to add to the compile line. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +Each string, which must consist of a single Bourne shell token, +is prepended with <code>-D</code> and added to the compile command line to this target, +as well as to every rule that depends on it. Be very careful, since this may have +far-reaching effects. When in doubt, add define values to +<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead. + </td> + </tr> + <tr> + <td id="cc_library.hdrs_check"> + <code>hdrs_check</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Deprecated, no-op. + </td> + </tr> + <tr> + <td id="cc_library.implementation_deps"> + <code>implementation_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries that the library target depends on. Unlike with +<code>deps</code>, the headers and include paths of these libraries (and all their +transitive deps) are only used for compilation of this library, and not libraries that +depend on it. Libraries specified with <code>implementation_deps</code> are still linked in +binary targets that depend on this library. + </td> + </tr> + <tr> + <td id="cc_library.include_prefix"> + <code>include_prefix</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The prefix to add to the paths of the headers of this rule. + +<p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible +at is the value of this attribute prepended to their repository-relative path. + +<p>The prefix in the <code>strip_include_prefix</code> attribute is removed before this +prefix is added. + +<p>This attribute is only legal under <code>third_party</code>. + </td> + </tr> + <tr> + <td id="cc_library.includes"> + <code>includes</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of include dirs to be added to the compile line. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. +Each string is prepended with the package path and passed to the C++ toolchain for +expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system +with typical feature definitions will produce +<code>-isystem path_to_package/include_entry</code>. +This should only be used for third-party libraries that +do not conform to the Google style of writing #include statements. +Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. +<p> +The added <code>include</code> paths will include generated files as well as +files in the source tree. +</p> + </td> + </tr> + <tr> + <td id="cc_library.linkopts"> + <code>linkopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + See <a href="/reference/be/c-cpp.html#cc_binary.linkopts"><code>cc_binary.linkopts</code></a>. +The <code>linkopts</code> attribute is also applied to any target that +depends, directly or indirectly, on this library via <code>deps</code> +attributes (or via other attributes that are treated similarly: +the <a href="/reference/be/c-cpp.html#cc_binary.malloc"><code>malloc</code></a> +attribute of <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a>). Dependency +linkopts take precedence over dependent linkopts (i.e. dependency linkopts +appear later in the command line). Linkopts specified in +<a href='../user-manual.html#flag--linkopt'><code>--linkopt</code></a> +take precedence over rule linkopts. +</p> +<p> +Note that the <code>linkopts</code> attribute only applies +when creating <code>.so</code> files or executables, not +when creating <code>.a</code> or <code>.lo</code> files. +So if the <code>linkstatic=True</code> attribute is set, the +<code>linkopts</code> attribute has no effect on the creation of +this library, only on other targets which depend on this library. +</p> +<p> +Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" +options are not supported and should never be specified in this attribute. +</p> +<p> The <code>.so</code> files produced by <code>cc_library</code> +rules are not linked against the libraries that they depend +on. If you're trying to create a shared library for use +outside of the main repository, e.g. for manual use +with <code>dlopen()</code> or <code>LD_PRELOAD</code>, +it may be better to use a <code>cc_binary</code> rule +with the <code>linkshared=True</code> attribute. +See <a href="/reference/be/c-cpp.html#cc_binary.linkshared"><code>cc_binary.linkshared</code></a>. +</p> + </td> + </tr> + <tr> + <td id="cc_library.linkstamp"> + <code>linkstamp</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Simultaneously compiles and links the specified C++ source file into the final +binary. This trickery is required to introduce timestamp +information into binaries; if we compiled the source file to an +object file in the usual way, the timestamp would be incorrect. +A linkstamp compilation may not include any particular set of +compiler flags and so should not depend on any particular +header, compiler option, or other build variable. +<em class='harmful'>This option should only be needed in the +<code>base</code> package.</em> + </td> + </tr> + <tr> + <td id="cc_library.linkstatic"> + <code>linkstatic</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and +<a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static +mode. For <code>cc_library.link_static</code>: see below. +<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> +<p> + If enabled and this is a binary or test, this option tells the build tool to link in + <code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. + System libraries such as libc (but <i>not</i> the C/C++ runtime libraries, + see below) are still linked dynamically, as are libraries for which + there is no static library. So the resulting executable will still be dynamically + linked, hence only <i>mostly</i> static. +</p> +<p> +There are really three different ways to link an executable: +</p> +<ul> +<li> STATIC with fully_static_link feature, in which everything is linked statically; + e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/> + This mode is enabled by specifying <code>fully_static_link</code> in the + <a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> +<li> STATIC, in which all user libraries are linked statically (if a static + version is available), but where system libraries (excluding C/C++ runtime libraries) + are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/> + This mode is enabled by specifying <code>linkstatic=True</code>.</li> +<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is + available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/> + This mode is enabled by specifying <code>linkstatic=False</code>.</li> +</ul> +<p> +If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in +<code>features</code> is used outside of <code>//third_party</code> +please include a comment near the rule to explain why. +</p> +<p> +The <code>linkstatic</code> attribute has a different meaning if used on a +<a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. +For a C++ library, <code>linkstatic=True</code> indicates that only +static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does +not prevent static libraries from being created. The attribute is meant to control the +creation of dynamic libraries. +</p> +<p> +There should be very little code built with <code>linkstatic=False</code> in production. +If <code>linkstatic=False</code>, then the build tool will create symlinks to +depended-upon shared libraries in the <code>*.runfiles</code> area. +</p> + </td> + </tr> + <tr> + <td id="cc_library.local_defines"> + <code>local_defines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of defines to add to the compile line. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +Each string, which must consist of a single Bourne shell token, +is prepended with <code>-D</code> and added to the compile command line for this target, +but not to its dependents. + </td> + </tr> + <tr> + <td id="cc_library.module_interfaces"> + <code>module_interfaces</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files are regarded as C++20 Modules Interface. + +<p> +C++ Standard has no restriction about module interface file extension +<ul> +<li>Clang use cppm </li> +<li>GCC can use any source file extension </li> +<li>MSVC use ixx </li> +</ul> +</p> +<p>The use is guarded by the flag +<code>--experimental_cpp_modules</code>.</p> + </td> + </tr> + <tr> + <td id="cc_library.strip_include_prefix"> + <code>strip_include_prefix</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The prefix to strip from the paths of the headers of this rule. + +<p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible +at their path with this prefix cut off. + +<p>If it's a relative path, it's taken as a package-relative one. If it's an absolute one, +it's understood as a repository-relative path. + +<p>The prefix in the <code>include_prefix</code> attribute is added after this prefix is +stripped. + +<p>This attribute is only legal under <code>third_party</code>. + </td> + </tr> + <tr> + <td id="cc_library.textual_hdrs"> + <code>textual_hdrs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of header files published by +this library to be textually included by sources in dependent rules. +<p>This is the location for declaring header files that cannot be compiled on their own; + that is, they always need to be textually included by other source files to build valid + code.</p> + </td> + </tr> + <tr> + <td id="cc_library.win_def_file"> + <code>win_def_file</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + The Windows DEF file to be passed to linker. +<p>This attribute should only be used when Windows is the target platform. +It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx"> +export symbols</a> during linking a shared library.</p> + </td> + </tr> + </tbody> + </table> + <h2 id="cc_shared_library"> + cc_shared_library + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_shared_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">cc_shared_library(<a href="#cc_shared_library.name">name</a>, <a href="#cc_shared_library.deps">deps</a>, <a href="#cc_shared_library.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#cc_shared_library.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#cc_shared_library.experimental_disable_topo_sort_do_not_use_remove_before_7_0">experimental_disable_topo_sort_do_not_use_remove_before_7_0</a>, <a href="#cc_shared_library.exports_filter">exports_filter</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_shared_library.roots">roots</a>, <a href="#cc_shared_library.shared_lib_name">shared_lib_name</a>, <a href="#cc_shared_library.static_deps">static_deps</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.toolchains">toolchains</a>, <a href="#cc_shared_library.user_link_flags">user_link_flags</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_shared_library.win_def_file">win_def_file</a>)</pre> + + <p>It produces a shared library.</p> + +<h4 id="cc_shard_library_examples">Example</h4> + +<pre class="code"> +cc_shared_library( + name = "foo_shared", + deps = [ + ":foo", + ], + dynamic_deps = [ + ":bar_shared", + ], + additional_linker_inputs = [ + ":foo.lds", + ], + user_link_flags = [ + "-Wl,--version-script=$(location :foo.lds)", + ], +) +cc_library( + name = "foo", + srcs = ["foo.cc"], + hdrs = ["foo.h"], + deps = [ + ":bar", + ":baz", + ], +) +cc_shared_library( + name = "bar_shared", + shared_lib_name = "bar.so", + deps = [":bar"], +) +cc_library( + name = "bar", + srcs = ["bar.cc"], + hdrs = ["bar.h"], +) +cc_library( + name = "baz", + srcs = ["baz.cc"], + hdrs = ["baz.h"], +) +</pre> + +<p>In the example <code>foo_shared</code> statically links <code>foo</code> +and <code>baz</code>, the latter being a transitive dependency. It doesn't +link <code>bar</code> because it is already provided dynamically by the +<code>dynamic_dep</code> <code>bar_shared</code>.</p> + +<p><code>foo_shared</code> uses a linker script *.lds file to control which +symbols should be exported. The <code>cc_shared_library</code> rule logic does +not control which symbols get exported, it only uses what is assumed to be +exported to give errors during analysis phase if two shared libraries export the +same targets.</p> + +<p>Every direct dependency of <code>cc_shared_library</code> is assumed to be +exported. Therefore, Bazel assumes during analysis that <code>foo</code> is being +exported by <code>foo_shared</code>. <code>baz</code> is not assumed to be exported +by <code>foo_shared</code>. Every target matched by the <code>exports_filter</code> +is also assumed to be exported.</p> + +<p>Every single <code>cc_library</code> in the example should appear at most in one +<code>cc_shared_library</code>. If we wanted to link <code>baz</code> also into +<code>bar_shared</code> we would need to add +<code>tags = ["LINKABLE_MORE_THAN_ONCE"]</code> to <code>baz</code>.</p> + +<p>Due to the <code>shared_lib_name</code> attribute, the file produced by +<code>bar_shared</code> will have the name <code>bar.so</code> as opposed +to the name <code>libbar.so</code> that it would have by default on Linux.</p> + +<h4 id="cc_shard_library_examples">Errors</h4> +<h5><code>Two shared libraries in dependencies export the same symbols.</code></h5> + +<p>This will happen whenever you are creating a target with two different +<code>cc_shared_library</code> dependencies that export the same target. To fix this +you need to stop the libraries from being exported in one of the +<code>cc_shared_library</code> dependencies.</p> + +<h5><code>Two shared libraries in dependencies link the same library statically</code></h5> + +<p>This will happen whenever you are creating a new <code>cc_shared_library</code> with two +different <code>cc_shared_library</code> dependencies that link the same target statically. +Similar to the error with exports.</p> + +<p>One way to fix this is to stop linking the library into one of the +<code>cc_shared_library</code> dependencies. At the same time, the one that still links it +needs to export the library so that the one not linking it keeps visibility to +the symbols. Another way is to pull out a third library that exports the target. +A third way is to tag the culprit <code>cc_library</code> with <code>LINKABLE_MORE_THAN_ONCE</code> +but this fix should be rare and you should absolutely make sure that the +<code>cc_library</code> is indeed safe to link more than once.</p> + +<h5><code>'//foo:foo' is already linked statically in '//bar:bar' but not exported`</code></h5> + +<p>This means that a library in the transitive closure of your <code>deps</code> is reachable +without going through one of the <code>cc_shared_library</code> dependencies but is already +linked into a different <code>cc_shared_library</code> in <code>dynamic_deps</code> and is not +exported.</p> + +<p>The solution is to export it from the <code>cc_shared_library</code> dependency or pull out +a third <code>cc_shared_library</code> that exports it.</p> + +<h5><code>Do not place libraries which only contain a precompiled dynamic library in deps. +</code></h5> + +<p>If you have a precompiled dynamic library, this doesn't need to and cannot be +linked statically into the current <code>cc_shared_library</code> target that you are +currently creating. Therefore, it doesn't belong in <code>deps</code> of the +<code>cc_shared_library</code>. If this precompiled dynamic library is a dependency of one +of your <code>cc_libraries</code>, then the <code>cc_library</code> needs to depend on it +directly.</p> + +<h5><code>Trying to export a library already exported by a different shared library</code></h5> + +<p>You will see this error if on the current rule you are claiming to export a +target that is already being exported by one of your dynamic dependencies.</p> + +<p>To fix this, remove the target from <code>deps</code> and just rely on it from the dynamic +dependency or make sure that the <code>exports_filter</code> doesn't catch this target.</p> + + <h3 id="cc_shared_library_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="cc_shared_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="cc_shared_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Top level libraries that will unconditionally be statically linked into the shared library +after being whole-archived. + +<p> +Any transitive library dependency of these direct deps will be linked into this shared +library as long as they have not already been linked by a <code>cc_shared_library</code> +in <code>dynamic_deps</code>.</p> + +<p> +During analysis, the rule implementation will consider any target listed in +<code>deps</code> as being exported by the shared library in order to give errors when +multiple <code>cc_shared_libraries</code> export the same targets. The rule implementation +does not take care of informing the linker about which symbols should be exported by the +shared object. The user should take care of this via linker scripts or visibility +declarations in the source code.</p> + +<p> +The implementation will also trigger errors whenever the same library is linked statically +into more than one <code>cc_shared_library</code>. This can be avoided by adding +<code>"LINKABLE_MORE_THAN_ONCE"</code> to the <code>cc_library.tags</code> or by listing +the `cc_library` as an export of one of the shared libraries so that one can be made a +<code>dynamic_dep</code> of the other. +</p> + </td> + </tr> + <tr> + <td id="cc_shared_library.additional_linker_inputs"> + <code>additional_linker_inputs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Any additional files that you may want to pass to the linker, for example, linker scripts. +You have to separately pass any linker flags that the linker needs in order to be aware +of this file. You can do so via the <code>user_link_flags</code> attribute. + </td> + </tr> + <tr> + <td id="cc_shared_library.dynamic_deps"> + <code>dynamic_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + These are other <code>cc_shared_library</code> dependencies the current target depends on. + +<p> +The <code>cc_shared_library</code> implementation will use the list of +<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the +current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in +the transitive <code>deps</code> should not be linked in because they are already provided +by a different <code>cc_shared_library</code>. +</p> + </td> + </tr> + <tr> + <td id="cc_shared_library.experimental_disable_topo_sort_do_not_use_remove_before_7_0"> + <code>experimental_disable_topo_sort_do_not_use_remove_before_7_0</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + + </td> + </tr> + <tr> + <td id="cc_shared_library.exports_filter"> + <code>exports_filter</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + This attribute contains a list of targets that are claimed to be exported by the current +shared library. + +<p> +Any target <code>deps</code> is already understood to be exported by the shared library. +This attribute should be used to list any targets that are exported by the shared library +but are transitive dependencies of <code>deps</code>. +</p> + +<p> +Note that this attribute is not actually adding a dependency edge to those targets, the +dependency edge should instead be created by <code>deps</code>.The entries in this +attribute are just strings. Keep in mind that when placing a target in this attribute, +this is considered a claim that the shared library exports the symbols from that target. +The <code>cc_shared_library</code> logic doesn't actually handle telling the linker which +symbols should be exported. +</p> + +<p>The following syntax is allowed:</p> +<p><code>//foo:__pkg__</code> to account for any target in foo/BUILD</p> +<p><code>//foo:__subpackages__</code> to account for any target in foo/BUILD or any other +package below foo/ like foo/bar/BUILD</p> + </td> + </tr> + <tr> + <td id="cc_shared_library.roots"> + <code>roots</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_shared_library.shared_lib_name"> + <code>shared_lib_name</code> + </td> + <td> + <p>String; default is <code>""</code></p> + By default cc_shared_library will use a name for the shared library output file based on +the target's name and the platform. This includes an extension and sometimes a prefix. +Sometimes you may not want the default name, for example, when loading C++ shared libraries +for Python the default lib* prefix is often not desired, in which case you can use this +attribute to choose a custom name. + </td> + </tr> + <tr> + <td id="cc_shared_library.static_deps"> + <code>static_deps</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_shared_library.user_link_flags"> + <code>user_link_flags</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Any additional flags that you may want to pass to the linker. For example, to make the +linker aware of a linker script passed via additional_linker_inputs you can use the +following: + +<pre><code class="lang-starlark"> + cc_shared_library( + name = "foo_shared", + additional_linker_inputs = select({ + "//src/conditions:linux": [ + ":foo.lds", + ":additional_script.txt", + ], + "//conditions:default": []}), + user_link_flags = select({ + "//src/conditions:linux": [ + "-Wl,-rpath,kittens", + "-Wl,--version-script=$(location :foo.lds)", + "-Wl,--script=$(location :additional_script.txt)", + ], + "//conditions:default": []}), + ... + ) +</code></pre> + </td> + </tr> + <tr> + <td id="cc_shared_library.win_def_file"> + <code>win_def_file</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + The Windows DEF file to be passed to linker. +<p>This attribute should only be used when Windows is the target platform. +It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx"> +export symbols</a> during linking a shared library.</p> + </td> + </tr> + </tbody> + </table> + <h2 id="cc_static_library"> + cc_static_library + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_static_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">cc_static_library(<a href="#cc_static_library.name">name</a>, <a href="#cc_static_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + Produces a static library from a list of targets and their transitive dependencies. + +<p>The resulting static library contains the object files of the targets listed in +<code>deps</code> as well as their transitive dependencies, with preference given to +<code>PIC</code> objects.</p> + +<h4 id="cc_static_library_output_groups">Output groups</h4> + +<h5><code>linkdeps</code></h5> +<p>A text file containing the labels of those transitive dependencies of targets listed in +<code>deps</code> that did not contribute any object files to the static library, but do +provide at least one static, dynamic or interface library. The resulting static library +may require these libraries to be available at link time.</p> + +<h5><code>linkopts</code></h5> +<p>A text file containing the user-provided <code>linkopts</code> of all transitive +dependencies of targets listed in <code>deps</code>. + +<h4 id="cc_static_library_symbol_check">Duplicate symbols</h4> +<p>By default, the <code>cc_static_library</code> rule checks that the resulting static +library does not contain any duplicate symbols. If it does, the build fails with an error +message that lists the duplicate symbols and the object files containing them.</p> + +<p>This check can be disabled per target or per package by setting +<code>features = ["-symbol_check"]</code> or globally via +<code>--features=-symbol_check</code>.</p> + +<h5 id="cc_static_library_symbol_check_toolchain">Toolchain support for <code>symbol_check</code></h5> +<p>The auto-configured C++ toolchains shipped with Bazel support the +<code>symbol_check</code> feature on all platforms. Custom toolchains can add support for +it in one of two ways:</p> +<ul> + <li>Implementing the <code>ACTION_NAMES.validate_static_library</code> action and + enabling it with the <code>symbol_check</code> feature. The tool set in the action is + invoked with two arguments, the static library to check for duplicate symbols and the + path of a file that must be created if the check passes.</li> + <li>Having the <code>symbol_check</code> feature add archiver flags that cause the + action creating the static library to fail on duplicate symbols.</li> +</ul> + + <h3 id="cc_static_library_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="cc_static_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="cc_static_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of targets to combine into a static library, including all their transitive +dependencies. + +<p>Dependencies that do not provide any object files are not included in the static +library, but their labels are collected in the file provided by the +<code>linkdeps</code> output group.</p> + </td> + </tr> + </tbody> + </table> + <h2 id="cc_test"> + cc_test + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_test.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">cc_test(<a href="#cc_test.name">name</a>, <a href="#cc_test.deps">deps</a>, <a href="#cc_test.srcs">srcs</a>, <a href="#cc_test.data">data</a>, <a href="#cc_test.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_test.conlyopts">conlyopts</a>, <a href="#cc_test.copts">copts</a>, <a href="#cc_test.cxxopts">cxxopts</a>, <a href="#cc_test.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#cc_test.distribs">distribs</a>, <a href="#cc_test.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#test.flaky">flaky</a>, <a href="#cc_test.hdrs_check">hdrs_check</a>, <a href="#cc_test.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_test.link_extra_lib">link_extra_lib</a>, <a href="#cc_test.linkopts">linkopts</a>, <a href="#cc_test.linkshared">linkshared</a>, <a href="#cc_test.linkstatic">linkstatic</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#cc_test.local_defines">local_defines</a>, <a href="#cc_test.malloc">malloc</a>, <a href="#cc_test.module_interfaces">module_interfaces</a>, <a href="#cc_test.nocopts">nocopts</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#cc_test.reexport_deps">reexport_deps</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#cc_test.stamp">stamp</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#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_test.win_def_file">win_def_file</a>)</pre> + + <p> +A <code>cc_test()</code> rule compiles a test. Here, a test +is a binary wrapper around some testing code. +</p> + +<p><i>By default, C++ tests are dynamically linked.</i><br/> + To statically link a unit test, specify + <a href="/reference/be/c-cpp.html#cc_binary.linkstatic"><code>linkstatic=True</code></a>. + It would probably be good to comment why your test needs + <code>linkstatic</code>; this is probably not obvious.</p> + +<h4>Implicit output targets</h4> +<ul> +<li><code><var>name</var>.stripped</code> (only built if explicitly requested): A stripped + version of the binary. <code>strip -g</code> is run on the binary to remove debug + symbols. Additional strip options can be provided on the command line using + <code>--stripopt=-foo</code>.</li> +<li><code><var>name</var>.dwp</code> (only built if explicitly requested): If + <a href="https://gcc.gnu.org/wiki/DebugFission">Fission</a> is enabled: a debug + information package file suitable for debugging remotely deployed binaries. Else: an + empty file.</li> +</ul> + +<p> +See the <a href="/reference/be/c-cpp.html#cc_binary_args">cc_binary()</a> arguments, except that +the <code>stamp</code> argument is set to 0 by default for tests and +that <code>cc_test</code> has extra <a href="/reference/be/common-definitions#common-attributes-tests"> +attributes common to all test rules (*_test)</a>.</p> + + <h3 id="cc_test_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="cc_test.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="cc_test.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries to be linked in to the binary target. +<p>These can be <code>cc_library</code> or <code>objc_library</code> +targets.</p> + +It is also allowed to +put linker scripts (.lds) into deps, and reference them in +<a href="#cc_binary.linkopts">linkopts</a>. + </td> + </tr> + <tr> + <td id="cc_test.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of C and C++ files that are processed to create the library target. +These are C/C++ source and header files, either non-generated (normal source +code) or generated. +<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will + be compiled. These might be generated files: if a named file is in + the <code>outs</code> of some other rule, this <code>cc_library</code> + will automatically depend on that other rule. +</p> +<p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using +the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built +using the C/C++ compiler. +</p> +<p>A <code>.h</code> file will not be compiled, but will be available for + inclusion by sources in this rule. Both <code>.cc</code> and + <code>.h</code> files can directly include headers listed in + these <code>srcs</code> or in the <code>hdrs</code> of this rule or any + rule listed in the <code>deps</code> argument. +</p> +<p>All <code>#include</code>d files must be mentioned in the + <code>hdrs</code> attribute of this or referenced <code>cc_library</code> + rules, or they should be listed in <code>srcs</code> if they are private + to this library. See <a href="#hdrs">"Header inclusion checking"</a> for + a more detailed description. +</p> +<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are + pre-compiled files. Your library might have these as + <code>srcs</code> if it uses third-party code for which we don't + have source code. +</p> +<p>If the <code>srcs</code> attribute includes the label of another rule, + <code>cc_library</code> will use the output files of that rule as source files to + compile. This is useful for one-off generation of source code (for more than occasional + use, it's better to implement a Starlark rule class and use the <code>cc_common</code> + API) +</p> +<p> + Permitted <code>srcs</code> file types: +</p> +<ul> +<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, + <code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> +<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, + <code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> +<li>Assembler with C preprocessor: <code>.S</code></li> +<li>Archive: <code>.a</code>, <code>.pic.a</code></li> +<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> +<li>Shared library, versioned or unversioned: <code>.so</code>, + <code>.so.<i>version</i></code></li> +<li>Object file: <code>.o</code>, <code>.pic.o</code></li> +</ul> + +<p> + ... and any rules that produce those files (e.g. <code>cc_embed_data</code>). + Different extensions denote different programming languages in + accordance with gcc convention. +</p> + </td> + </tr> + <tr> + <td id="cc_test.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this library at runtime. + +See general comments about <code>data</code> +at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. +<p>If a <code>data</code> is the name of a generated file, then this + <code>cc_library</code> rule automatically depends on the generating + rule. +</p> +<p>If a <code>data</code> is a rule name, then this + <code>cc_library</code> rule automatically depends on that rule, + and that rule's <code>outs</code> are automatically added to + this <code>cc_library</code>'s data files. +</p> +<p>Your C++ code can access these data files like so:</p> +<pre><code class="lang-starlark"> + const std::string path = devtools_build::GetDataDependencyFilepath( + "my/test/data/file"); +</code></pre> + </td> + </tr> + <tr> + <td id="cc_test.additional_linker_inputs"> + <code>additional_linker_inputs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Pass these files to the C++ linker command. +<p> + For example, compiled Windows .res files can be provided here to be embedded in + the binary target. +</p> + </td> + </tr> + <tr> + <td id="cc_test.conlyopts"> + <code>conlyopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. + </td> + </tr> + <tr> + <td id="cc_test.copts"> + <code>copts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C/C++ compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +<p> + Each string in this attribute is added in the given order to <code>COPTS</code> before + compiling the binary target. The flags take effect only for compiling this target, not + its dependencies, so be careful about header files included elsewhere. + All paths should be relative to the workspace, not to the current package. + This attribute should not be needed outside of <code>third_party</code>. +</p> +<p> + If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> + <code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings + that consist of a single "Make" variable. +</p> + </td> + </tr> + <tr> + <td id="cc_test.cxxopts"> + <code>cxxopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these options to the C++ compilation command. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. + </td> + </tr> + <tr> + <td id="cc_test.defines"> + <code>defines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of defines to add to the compile line. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +Each string, which must consist of a single Bourne shell token, +is prepended with <code>-D</code> and added to the compile command line to this target, +as well as to every rule that depends on it. Be very careful, since this may have +far-reaching effects. When in doubt, add define values to +<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead. + </td> + </tr> + <tr> + <td id="cc_test.distribs"> + <code>distribs</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_test.dynamic_deps"> + <code>dynamic_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + These are other <code>cc_shared_library</code> dependencies the current target depends on. + +<p> +The <code>cc_shared_library</code> implementation will use the list of +<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the +current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in +the transitive <code>deps</code> should not be linked in because they are already provided +by a different <code>cc_shared_library</code>. + </td> + </tr> + <tr> + <td id="cc_test.hdrs_check"> + <code>hdrs_check</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Deprecated, no-op. + </td> + </tr> + <tr> + <td id="cc_test.includes"> + <code>includes</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of include dirs to be added to the compile line. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. +Each string is prepended with the package path and passed to the C++ toolchain for +expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system +with typical feature definitions will produce +<code>-isystem path_to_package/include_entry</code>. +This should only be used for third-party libraries that +do not conform to the Google style of writing #include statements. +Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. +<p> +The added <code>include</code> paths will include generated files as well as +files in the source tree. +</p> + </td> + </tr> + <tr> + <td id="cc_test.link_extra_lib"> + <code>link_extra_lib</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p> + Control linking of extra libraries. +<p> + By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>, + which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>. + Without setting the flag, this library is empty by default. Setting the label flag + allows linking optional dependencies, such as overrides for weak symbols, interceptors + for shared library functions, or special runtime libraries (for malloc replacements, + prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to + <code>None</code> disables this behaviour. +</p> + </td> + </tr> + <tr> + <td id="cc_test.linkopts"> + <code>linkopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Add these flags to the C++ linker command. +Subject to <a href="make-variables.html">"Make" variable</a> substitution, +<a href="common-definitions.html#sh-tokenization"> +Bourne shell tokenization</a> and +<a href="common-definitions.html#label-expansion">label expansion</a>. +Each string in this attribute is added to <code>LINKOPTS</code> before +linking the binary target. +<p> + Each element of this list that does not start with <code>$</code> or <code>-</code> is + assumed to be the label of a target in <code>deps</code>. The + list of files generated by that target is appended to the linker + options. An error is reported if the label is invalid, or is + not declared in <code>deps</code>. +</p> + </td> + </tr> + <tr> + <td id="cc_test.linkshared"> + <code>linkshared</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Create a shared library. +To enable this attribute, include <code>linkshared=True</code> in your rule. By default +this option is off. +<p> + The presence of this flag means that linking occurs with the <code>-shared</code> flag + to <code>gcc</code>, and the resulting shared library is suitable for loading into for + example a Java program. However, for build purposes it will never be linked into the + dependent binary, as it is assumed that shared libraries built with a + <a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so + it should not be considered a substitute for the <a href="#cc_library">cc_library</a> + rule. For sake of scalability we recommend avoiding this approach altogether and + simply letting <code>java_library</code> depend on <code>cc_library</code> rules + instead. +</p> +<p> + If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>, + you get a single completely self-contained unit. If you specify both + <code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly + self-contained unit. +</p> + </td> + </tr> + <tr> + <td id="cc_test.linkstatic"> + <code>linkstatic</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and +<a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static +mode. For <code>cc_library.link_static</code>: see below. +<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> +<p> + If enabled and this is a binary or test, this option tells the build tool to link in + <code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. + System libraries such as libc (but <i>not</i> the C/C++ runtime libraries, + see below) are still linked dynamically, as are libraries for which + there is no static library. So the resulting executable will still be dynamically + linked, hence only <i>mostly</i> static. +</p> +<p> +There are really three different ways to link an executable: +</p> +<ul> +<li> STATIC with fully_static_link feature, in which everything is linked statically; + e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/> + This mode is enabled by specifying <code>fully_static_link</code> in the + <a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> +<li> STATIC, in which all user libraries are linked statically (if a static + version is available), but where system libraries (excluding C/C++ runtime libraries) + are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/> + This mode is enabled by specifying <code>linkstatic=True</code>.</li> +<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is + available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/> + This mode is enabled by specifying <code>linkstatic=False</code>.</li> +</ul> +<p> +If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in +<code>features</code> is used outside of <code>//third_party</code> +please include a comment near the rule to explain why. +</p> +<p> +The <code>linkstatic</code> attribute has a different meaning if used on a +<a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. +For a C++ library, <code>linkstatic=True</code> indicates that only +static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does +not prevent static libraries from being created. The attribute is meant to control the +creation of dynamic libraries. +</p> +<p> +There should be very little code built with <code>linkstatic=False</code> in production. +If <code>linkstatic=False</code>, then the build tool will create symlinks to +depended-upon shared libraries in the <code>*.runfiles</code> area. +</p> + </td> + </tr> + <tr> + <td id="cc_test.local_defines"> + <code>local_defines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of defines to add to the compile line. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +Each string, which must consist of a single Bourne shell token, +is prepended with <code>-D</code> and added to the compile command line for this target, +but not to its dependents. + </td> + </tr> + <tr> + <td id="cc_test.malloc"> + <code>malloc</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p> + Override the default dependency on malloc. +<p> + By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>, + which is an empty library so the binary ends up using libc malloc. + This label must refer to a <code>cc_library</code>. If compilation is for a non-C++ + rule, this option has no effect. The value of this attribute is ignored if + <code>linkshared=True</code> is specified. +</p> + </td> + </tr> + <tr> + <td id="cc_test.module_interfaces"> + <code>module_interfaces</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files are regarded as C++20 Modules Interface. + +<p> +C++ Standard has no restriction about module interface file extension +<ul> +<li>Clang use cppm </li> +<li>GCC can use any source file extension </li> +<li>MSVC use ixx </li> +</ul> +</p> +<p>The use is guarded by the flag +<code>--experimental_cpp_modules</code>.</p> + </td> + </tr> + <tr> + <td id="cc_test.nocopts"> + <code>nocopts</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Remove matching options from the C++ compilation command. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. +The value of this attribute is interpreted as a regular expression. +Any preexisting <code>COPTS</code> that match this regular expression +(including values explicitly specified in the rule's <a +href="#cc_binary.copts">copts</a> attribute) +will be removed from <code>COPTS</code> for purposes of compiling this rule. +This attribute should not be needed or used +outside of <code>third_party</code>. The values are not preprocessed +in any way other than the "Make" variable substitution. + </td> + </tr> + <tr> + <td id="cc_test.reexport_deps"> + <code>reexport_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_test.stamp"> + <code>stamp</code> + </td> + <td> + <p>Integer; default is <code>0</code></p> + Whether to encode build information into the binary. Possible values: +<ul> +<li> + <code>stamp = 1</code>: Always stamp the build information into the binary, even in + <a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This + setting should be avoided</b>, since it potentially kills remote caching for the + binary and any downstream actions that depend on it. +</li> +<li> + <code>stamp = 0</code>: Always replace build information by constant values. This + gives good build result caching. +</li> +<li> + <code>stamp = -1</code>: Embedding of build information is controlled by the + <a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag. +</li> +</ul> +<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> + </td> + </tr> + <tr> + <td id="cc_test.win_def_file"> + <code>win_def_file</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + The Windows DEF file to be passed to linker. +<p>This attribute should only be used when Windows is the target platform. +It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx"> +export symbols</a> during linking a shared library.</p> + </td> + </tr> + </tbody> + </table> + <h2 id="cc_toolchain"> + cc_toolchain + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_toolchain.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">cc_toolchain(<a href="#cc_toolchain.name">name</a>, <a href="#cc_toolchain.all_files">all_files</a>, <a href="#cc_toolchain.ar_files">ar_files</a>, <a href="#cc_toolchain.as_files">as_files</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_toolchain.compiler_files">compiler_files</a>, <a href="#cc_toolchain.compiler_files_without_includes">compiler_files_without_includes</a>, <a href="#cc_toolchain.coverage_files">coverage_files</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#cc_toolchain.dwp_files">dwp_files</a>, <a href="#cc_toolchain.dynamic_runtime_lib">dynamic_runtime_lib</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#cc_toolchain.exec_transition_for_inputs">exec_transition_for_inputs</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#cc_toolchain.libc_top">libc_top</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_toolchain.linker_files">linker_files</a>, <a href="#cc_toolchain.module_map">module_map</a>, <a href="#cc_toolchain.objcopy_files">objcopy_files</a>, <a href="#cc_toolchain.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_toolchain.static_runtime_lib">static_runtime_lib</a>, <a href="#cc_toolchain.strip_files">strip_files</a>, <a href="#cc_toolchain.supports_header_parsing">supports_header_parsing</a>, <a href="#cc_toolchain.supports_param_files">supports_param_files</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="#cc_toolchain.toolchain_config">toolchain_config</a>, <a href="#cc_toolchain.toolchain_identifier">toolchain_identifier</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>Represents a C++ toolchain.</p> + +<p> + This rule is responsible for: + + <ul> + <li> + Collecting all artifacts needed for C++ actions to run. This is done by + attributes such as <code>all_files</code>, <code>compiler_files</code>, + <code>linker_files</code>, or other attributes ending with <code>_files</code>). These are + most commonly filegroups globbing all required files. + </li> + <li> + Generating correct command lines for C++ actions. This is done using + <code>CcToolchainConfigInfo</code> provider (details below). + </li> + </ul> +</p> +<p> + Use <code>toolchain_config</code> attribute to configure the C++ toolchain. + See also this + <a href="https://bazel.build/docs/cc-toolchain-config-reference"> + page + </a> for elaborate C++ toolchain configuration and toolchain selection documentation. +</p> +<p> + Use <code>tags = ["manual"]</code> in order to prevent toolchains from being built and configured + unnecessarily when invoking <code>bazel build //...</code> +</p> + + <h3 id="cc_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="cc_toolchain.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="cc_toolchain.all_files"> + <code>all_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Collection of all cc_toolchain artifacts. These artifacts will be added as inputs to all +rules_cc related actions (with the exception of actions that are using more precise sets of +artifacts from attributes below). Bazel assumes that <code>all_files</code> is a superset +of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile +and link files, so it takes <code>all_files</code>). + +<p> +This is what <code>cc_toolchain.files</code> contains, and this is used by all Starlark +rules using C++ toolchain.</p> + </td> + </tr> + <tr> + <td id="cc_toolchain.ar_files"> + <code>ar_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Collection of all cc_toolchain artifacts required for archiving actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.as_files"> + <code>as_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Collection of all cc_toolchain artifacts required for assembly actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.compiler_files"> + <code>compiler_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Collection of all cc_toolchain artifacts required for compile actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.compiler_files_without_includes"> + <code>compiler_files_without_includes</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Collection of all cc_toolchain artifacts required for compile actions in case when +input discovery is supported (currently Google-only). + </td> + </tr> + <tr> + <td id="cc_toolchain.coverage_files"> + <code>coverage_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Collection of all cc_toolchain artifacts required for coverage actions. If not specified, +all_files are used. + </td> + </tr> + <tr> + <td id="cc_toolchain.dwp_files"> + <code>dwp_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Collection of all cc_toolchain artifacts required for dwp actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.dynamic_runtime_lib"> + <code>dynamic_runtime_lib</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). + +<p>This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking +dependencies dynamically.</p> + </td> + </tr> + <tr> + <td id="cc_toolchain.exec_transition_for_inputs"> + <code>exec_transition_for_inputs</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Deprecated. No-op. + </td> + </tr> + <tr> + <td id="cc_toolchain.libc_top"> + <code>libc_top</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + A collection of artifacts for libc passed as inputs to compile/linking actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.linker_files"> + <code>linker_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Collection of all cc_toolchain artifacts required for linking actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.module_map"> + <code>module_map</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Module map artifact to be used for modular builds. + </td> + </tr> + <tr> + <td id="cc_toolchain.objcopy_files"> + <code>objcopy_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Collection of all cc_toolchain artifacts required for objcopy actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.output_licenses"> + <code>output_licenses</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="cc_toolchain.static_runtime_lib"> + <code>static_runtime_lib</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Static library artifact for the C++ runtime library (e.g. libstdc++.a). + +<p>This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking +dependencies statically.</p> + </td> + </tr> + <tr> + <td id="cc_toolchain.strip_files"> + <code>strip_files</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Collection of all cc_toolchain artifacts required for strip actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.supports_header_parsing"> + <code>supports_header_parsing</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Set to True when cc_toolchain supports header parsing actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.supports_param_files"> + <code>supports_param_files</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + Set to True when cc_toolchain supports using param files for linking actions. + </td> + </tr> + <tr> + <td id="cc_toolchain.toolchain_config"> + <code>toolchain_config</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + The label of the rule providing <code>cc_toolchain_config_info</code>. + </td> + </tr> + <tr> + <td id="cc_toolchain.toolchain_identifier"> + <code>toolchain_identifier</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The identifier used to match this cc_toolchain with the corresponding +crosstool_config.toolchain. + +<p> + Until issue <a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a> is fixed + this is the recommended way of associating <code>cc_toolchain</code> with + <code>CROSSTOOL.toolchain</code>. It will be replaced by the <code>toolchain_config</code> + attribute (<a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a>).</p> + </td> + </tr> + </tbody> + </table> + <h2 id="fdo_prefetch_hints"> + fdo_prefetch_hints + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_prefetch_hints.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">fdo_prefetch_hints(<a href="#fdo_prefetch_hints.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</a>, <a href="#fdo_prefetch_hints.profile">profile</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>Represents an FDO prefetch hints profile that is either in the workspace. +Examples:</p> + +<pre><code class="lang-starlark"> +fdo_prefetch_hints( + name = "hints", + profile = "//path/to/hints:profile.afdo", +) +</code></pre> + + <h3 id="fdo_prefetch_hints_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="fdo_prefetch_hints.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="fdo_prefetch_hints.profile"> + <code>profile</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Label of the hints profile. The hints file has the .afdo extension +The label can also point to an fdo_absolute_path_profile rule. + </td> + </tr> + </tbody> + </table> + <h2 id="fdo_profile"> + fdo_profile + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_profile.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">fdo_profile(<a href="#fdo_profile.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#fdo_profile.memprof_profile">memprof_profile</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#fdo_profile.profile">profile</a>, <a href="#fdo_profile.proto_profile">proto_profile</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>Represents an FDO profile that is in the workspace. +Example:</p> + +<pre><code class="lang-starlark"> +fdo_profile( + name = "fdo", + profile = "//path/to/fdo:profile.zip", +) +</code></pre> + + <h3 id="fdo_profile_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="fdo_profile.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="fdo_profile.memprof_profile"> + <code>memprof_profile</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the MemProf profile. The profile is expected to have +either a .profdata extension (for an indexed/symbolized memprof +profile), or a .zip extension for a zipfile containing a memprof.profdata +file. + </td> + </tr> + <tr> + <td id="fdo_profile.profile"> + <code>profile</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Label of the FDO profile or a rule which generates it. The FDO file can have one of the +following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM +profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for +XBinary profile. The label can also point to an fdo_absolute_path_profile rule. + </td> + </tr> + <tr> + <td id="fdo_profile.proto_profile"> + <code>proto_profile</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the protobuf profile. + </td> + </tr> + </tbody> + </table> + <h2 id="memprof_profile"> + memprof_profile + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/memprof_profile.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">memprof_profile(<a href="#memprof_profile.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</a>, <a href="#memprof_profile.profile">profile</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>Represents a MEMPROF profile that is in the workspace. +Example:</p> + +<pre><code class="lang-starlark"> +memprof_profile( + name = "memprof", + profile = "//path/to/memprof:profile.afdo", +) + +</code></pre> + + <h3 id="memprof_profile_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="memprof_profile.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="memprof_profile.profile"> + <code>profile</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Label of the MEMPROF profile. The profile is expected to have +either a .profdata extension (for an indexed/symbolized memprof +profile), or a .zip extension for a zipfile containing a memprof.profdata +file. +The label can also point to an fdo_absolute_path_profile rule. + </td> + </tr> + </tbody> + </table> + <h2 id="propeller_optimize"> + propeller_optimize + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/propeller_optimize.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">propeller_optimize(<a href="#propeller_optimize.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#propeller_optimize.cc_profile">cc_profile</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#propeller_optimize.ld_profile">ld_profile</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>Represents a Propeller optimization profile in the workspace. +Example:</p> + +<pre><code class="lang-starlark"> +propeller_optimize( + name = "layout", + cc_profile = "//path:cc_profile.txt", + ld_profile = "//path:ld_profile.txt" +) +</code></pre> + + <h3 id="propeller_optimize_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="propeller_optimize.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="propeller_optimize.cc_profile"> + <code>cc_profile</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Label of the profile passed to the various compile actions. This file has +the .txt extension. + </td> + </tr> + <tr> + <td id="propeller_optimize.ld_profile"> + <code>ld_profile</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + Label of the profile passed to the link action. This file has +the .txt extension. + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/common-definitions.mdx b/reference/be/common-definitions.mdx new file mode 100644 index 0000000..7c437c3 --- /dev/null +++ b/reference/be/common-definitions.mdx @@ -0,0 +1,1143 @@ +--- +title: 'common-definitions' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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 --> + +<h1 class="page-title" id="common-definitions">Common definitions</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm" %} +{% include "_buttons.html" %} +<p>This section defines various terms and concepts that are common to +many functions or build rules. +</p> + +<h2>Contents</h2> +<ul> + <li><a href="#sh-tokenization">Bourne shell tokenization</a></li> + <li><a href="#label-expansion">Label Expansion</a></li> + <li><a href="#typical-attributes">Typical attributes defined by most build rules</a></li> + <li><a href="#common-attributes">Attributes common to all build rules</a></li> + <li><a href="#common-attributes-tests">Attributes common to all test rules (*_test)</a></li> + <li><a href="#common-attributes-binaries">Attributes common to all binary rules (*_binary)</a></li> + <li><a href="#configurable-attributes">Configurable attributes</a></li> + <li><a href="#implicit-outputs">Implicit output targets</a></li> +</ul> +<h2 id='sh-tokenization'>Bourne shell tokenization</h2> +<p> + Certain string attributes of some rules are split into multiple + words according to the tokenization rules of the Bourne shell: + unquoted spaces delimit separate words, and single- and + double-quotes characters and backslashes are used to prevent + tokenization. +</p> +<p> + Those attributes that are subject to this tokenization are + explicitly indicated as such in their definitions in this document. +</p> +<p> + Attributes subject to "Make" variable expansion and Bourne shell + tokenization are typically used for passing arbitrary options to + compilers and other tools. Examples of such attributes are + <code>cc_library.copts</code> and <code>java_library.javacopts</code>. + Together these substitutions allow a + single string variable to expand into a configuration-specific list + of option words. +</p> + +<h2 id='label-expansion'>Label expansion</h2> +<p> + Some string attributes of a very few rules are subject to label + expansion: if those strings contain a valid label as a + substring, such as <code>//mypkg:target</code>, and that label is a + declared prerequisite of the current rule, it is expanded into the + pathname of the file represented by the + <a href="https://bazel.build/reference/glossary#target">target</a> + <code>//mypkg:target</code>. +</p> + +<p> + Example attributes include <code>genrule.cmd</code> and + <code>cc_binary.linkopts</code>. The details may vary significantly in + each case, over such issues as: whether relative labels are + expanded; how labels that expand to multiple files are + treated, etc. Consult the rule attribute documentation for + specifics. +</p> + + +<h2 id="typical-attributes">Typical attributes defined by most build rules</h2> + +<p>This section describes attributes that are defined by many build rules, +but not all. +</p> + + <table class="table table-condensed table-bordered table-params"> + <colgroup> + <col class="col-param" /> + <col class="param-description" /> + </colgroup> + <thead> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="typical.data"><code>data</code></td> + <td><a name="common.data"></a> +<p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + +<p> +Files needed by this rule at runtime. May list file or rule targets. Generally +allows any target. +</p> + +<p> +The default outputs and runfiles of targets in the <code>data</code> attribute +should appear in the <code>*.runfiles</code> area of any executable which is +output by or has a runtime dependency on this target. This may include data +files or binaries used when this target's +<a href="#typical.srcs"><code>srcs</code></a> are executed. See the +<a href="/concepts/dependencies#data-dependencies">data dependencies</a> +section for more information about how to depend on and use data files. +</p> + +<p> +New rules should define a <code>data</code> attribute if they process +inputs which might use other inputs at runtime. Rules' implementation functions +must also <a href="https://bazel.build/rules/rules#runfiles">populate the target's +runfiles</a> from the outputs and runfiles of any <code>data</code> attribute, +as well as runfiles from any dependency attribute which provides either +source code or runtime dependencies. +</p> +</td> + </tr> + <tr> + <td id="typical.deps"><code>deps</code></td> + <td><a name="common.deps"></a> +<p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + +<p> +Dependencies for this target. Generally should only list rule targets. (Though +some rules permit files to be listed directly in <code>deps</code>, this +should be avoided when possible.) +</p> + +<p> +Language-specific rules generally limit the listed targets to those with +specific <a href="https://bazel.build/extending/rules#providers">providers</a>.</p> + +<p> +The precise semantics of what it means for a target to depend on another using +<code>deps</code> are specific to the kind of rule, and the rule-specific +documentation goes into more detail. For rules which process source code, +<code>deps</code> generally specifies code dependencies used by the code in +<a href="#typical.srcs"><code>srcs</code></a>. +</p> + +<p> +Most often, a <code>deps</code> dependency is used to allow one module to use +symbols defined in another module written in the same programming language and +separately compiled. Cross-language dependencies are also permitted in many +cases: For example, a <code>java_library</code> target may depend on C++ code +in a <code>cc_library</code> target, by listing the latter in the +<code>deps</code> attribute. See the definition of +<a href="/concepts/build-ref#deps">dependencies</a> +for more information. +</p> +</td> + </tr> + <tr> + <td id="typical.licenses"><code>licenses</code></td> + <td><a name="common.licenses"></a> +<p>List of strings; <a href="#configurable-attributes">nonconfigurable</a>; + default is <code>["none"]</code></p> + +<p> + A list of license-type strings to be used for this particular target. + +This is part of a deprecated licensing API that Bazel no longer uses. Don't +use this. +</p> +</td> + </tr> + <tr> + <td id="typical.srcs"><code>srcs</code></td> + <td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + +<p> +Files processed or included by this rule. Generally lists files directly, but +may list rule targets (like <code>filegroup</code> or <code>genrule</code>) to +include their default outputs. +</p> + +<p> +Language-specific rules often require that the listed files have particular +file extensions. +</p> +</td> + </tr> + </tbody> + </table> + +<h2 id="common-attributes">Attributes common to all build rules</h2> + +<p>This section describes attributes that are implicitly added to all build +rules. +</p> + + <table class="table table-condensed table-bordered table-params"> + <colgroup> + <col class="col-param" /> + <col class="param-description" /> + </colgroup> + <thead> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="common.aspect_hints"><code>aspect_hints</code></td> + <td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + +<p>A list of arbitrary labels which is exposed to <a href="/extending/aspects">aspects</a> (in +particular - aspects invoked by this rule's reverse dependencies), but isn't exposed to this rule's +own implementation. Consult documentation for language-specific rule sets for details about what +effect a particular aspect hint would have.</p> + +<p>You could think of an aspect hint as a richer alternative to a <a href="#common.tags">tag</a>: +while a tag conveys only a boolean state (the tag is either present or absent in the +<code>tags</code> list), an aspect hint can convey arbitrary structured information in its +<a href="/extending/rules#providers">providers</a>.</p> + +<p>In practice, aspect hints are used for interoperability between different language-specific +rule sets. For example, imagine you have a <code>mylang_binary</code> target which needs to depend +on an <code>otherlang_library</code> target. The MyLang-specific logic needs some additional +information about the OtherLang target in order to use it, but <code>otherlang_library</code> +doesn't provide this information because it knows nothing about MyLang. One solution might be for +the MyLang rule set to define a <code>mylang_hint</code> rule which can be used to encode that +additional information; the user can add the hint to their <code>otherlang_library</code>'s +<code>aspect_hints</code>, and <code>mylang_binary</code> can use an aspect to collect the +additional information from a MyLang-specific provider in the <code>mylang_hint</code>.</p> + +<p>For a concrete example, see +<a href="https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_interop_hint"><code>swift_interop_hint</code></a> +and <a href="https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_overlay"><code>swift_overlay</code></a> +in <code>rules_swift</code>.</p> + +<p>Best practices:</p> +<ul> + <li>Targets listed in <code>aspect_hints</code> should be lightweight and minimal.</li> + <li>Language-specific logic should consider only aspect hints having providers relevant to that + language, and should ignore any other aspect hints.</li> +</ul></td> + </tr> + <tr> + <td id="common.compatible_with"><code>compatible_with</code></td> + <td><p>List of <a href="/concepts/labels">labels</a>; + <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> + +<p> +The list of environments this target can be built for, in addition to +default-supported environments. +</p> + +<p> +This is part of Bazel's constraint system, which lets users declare which +targets can and cannot depend on each other. For example, externally deployable +binaries shouldn't depend on libraries with company-secret code. See +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46"> +ConstraintSemantics</a> for details. +</p> +</td> + </tr> + <tr> + <td id="common.deprecation"><code>deprecation</code></td> + <td><p>String; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>None</code></p> + +<p> +An explanatory warning message associated with this target. +Typically this is used to notify users that a target has become obsolete, +or has become superseded by another rule, is private to a package, or is +perhaps considered harmful for some reason. It is a good idea to include +some reference (like a webpage, a bug number or example migration CLs) so +that one can easily find out what changes are required to avoid the message. +If there is a new target that can be used as a drop in replacement, it is a +good idea to just migrate all users of the old target. +</p> + +<p> +This attribute has no effect on the way things are built, but it +may affect a build tool's diagnostic output. The build tool issues a +warning when a rule with a <code>deprecation</code> attribute is +depended upon by a target in another package. +</p> + +<p> +Intra-package dependencies are exempt from this warning, so that, +for example, building the tests of a deprecated rule does not +encounter a warning. +</p> + +<p> +If a deprecated target depends on another deprecated target, no warning +message is issued. +</p> + +<p> +Once people have stopped using it, the target can be removed. +</p> +</td> + </tr> + <tr> + <td id="common.exec_compatible_with"><code>exec_compatible_with</code></td> + <td><p>List of <a href="/concepts/labels">labels</a>; + <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code> +</p> + +<p> +A list of +<code><a href="platforms-and-toolchains.html#constraint_value">constraint_values</a></code> +that must be present in the execution platform of this target's default exec +group. This is in addition to any constraints already set by the rule type. +Constraints are used to restrict the list of available execution platforms. + +For more details, see +the description of + <a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>. + and + <a href="/extending/exec-groups">exec groups</a> + +</p> +</td> + </tr> + <tr> + <td id="common.exec_group_compatible_with"><code>exec_group_compatible_with</code></td> + <td><p>Dictionary of strings to lists of <a href="/concepts/labels">labels</a>; + <a href="#configurable-attributes">nonconfigurable</a>; default is <code>{}</code> +</p> + +<p> +A dictionary of exec group names to lists of +<code><a href="platforms-and-toolchains.html#constraint_value">constraint_values</a></code> +that must be present in the execution platform for the given exec group. This +is in addition to any constraints already set on the exec group's definition. +Constraints are used to restrict the list of available execution platforms. + +For more details, see +the description of + <a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>. + and + <a href="/extending/exec-groups">exec groups</a> + +</p> +</td> + </tr> + <tr> + <td id="common.exec_properties"><code>exec_properties</code></td> + <td><p>Dictionary of strings; default is <code>{}</code></p> + +<p> A dictionary of strings that will be added to the <code>exec_properties</code> of a platform selected for this target. See <code>exec_properties</code> of the <a href="platforms-and-toolchains.html#platform">platform</a> rule.</p> + +<p>If a key is present in both the platform and target-level properties, the value will be taken from the target.</p> + +<p>Keys can be prefixed with the name of an execution group followed by a <code>.</code> to apply them only to that particular exec group.</p> +</td> + </tr> + <tr> + <td id="common.features"><code>features</code></td> + <td><p>List of <i>feature</i> strings; default is <code>[]</code></p> + +<p>A feature is string tag that can be enabled or disabled on a target. The + meaning of a feature depends on the rule itself.</p> + +<p>This <code>features</code> attribute is combined with the <a href="/reference/be/functions.html#package"> +package</a> level <code>features</code> attribute. For example, if +the features ["a", "b"] are enabled on the package level, and a target's +<code>features</code> attribute contains ["-a", "c"], the features enabled for the +rule will be "b" and "c". + <a href="https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD"> + See example</a>. +</p> + +</td> + </tr> + <tr> + <td id="common.package_metadata"><code>package_metadata</code></td> + <td><p>List of <a href="/concepts/labels">labels</a>; + <a href="#configurable-attributes">nonconfigurable</a>; default is the package's + <code><a href="/reference/be/functions.html#package.default_package_metadata">default_package_metadata</a></code> +</p> + +<p> +A list of labels that are associated metadata about this target. +Typically, the labels are simple rules that return a provider of +constant values. Rules and aspects may use these labels to perform some +additional analysis on the build graph. +</p> + +<p> +The canonical use case is that of +<a href="https://github.com/bazelbuild/rules_license">rules_license</a>. +For that use case, <code>package_metadata</code> and +<code>default_package_metadata</code> is used to attach information +about a package's licence or version to targets. An aspect applied +to a top-level binary can be used to gather those and produce +compliance reports. +</p> +</td> + </tr> + <tr> + <td id="common.restricted_to"><code>restricted_to</code></td> + <td><p>List of <a href="/concepts/labels">labels</a>; + <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> + +<p> +The list of environments this target can be built for, <i>instead</i> of +default-supported environments. +</p> + +<p> +This is part of Bazel's constraint system. See +<code><a href="#common.compatible_with">compatible_with</a></code> +for details. +</p> +</td> + </tr> + <tr> + <td id="common.tags"><code>tags</code></td> + <td><p> + List of strings; <a href="#configurable-attributes">nonconfigurable</a>; + default is <code>[]</code> +</p> + +<p> + <i>Tags</i> can be used on any rule. <i>Tags</i> on test and + <code>test_suite</code> rules are useful for categorizing the tests. + <i>Tags</i> on non-test targets are used to control sandboxed execution of + <code>genrule</code>s and + +<a href="/rules/concepts">Starlark</a> + actions, and for parsing by humans and/or external tools. +</p> + +<p> + Bazel modifies the behavior of its sandboxing code if it finds the following + keywords in the <code>tags</code> attribute of any test or <code>genrule</code> + target, or the keys of <code>execution_requirements</code> for any Starlark + action. +</p> + +<ul> + <li><code>no-sandbox</code> keyword results in the action or test never being + sandboxed; it can still be cached or run remotely - use <code>no-cache</code> + or <code>no-remote</code> to prevent either or both of those. + </li> + <li><code>no-cache</code> keyword results in the action or test never being + cached (locally or remotely). Note: for the purposes of this tag, the disk cache + is considered a local cache, whereas the HTTP and gRPC caches are considered + remote. Other caches, such as Skyframe or the persistent action cache, are not + affected. + </li> + <li><code>no-remote-cache</code> keyword results in the action or test never being + cached remotely (but it may be cached locally; it may also be executed remotely). + Note: for the purposes of this tag, the disk cache is considered a local cache, + whereas the HTTP and gRPC caches are considered remote. Other caches, such as + Skyframe or the persistent action cache, are not affected. + If a combination of local disk cache and remote cache are used (combined cache), + it's treated as a remote cache and disabled entirely unless <code>--incompatible_remote_results_ignore_disk</code> + is set in which case the local components will be used. + </li> + <li><code>no-remote-exec</code> keyword results in the action or test never being + executed remotely (but it may be cached remotely). + </li> + + <li><code>no-remote</code> keyword prevents the action or test from being executed remotely or + cached remotely. This is equivalent to using both + <code>no-remote-cache</code> and <code>no-remote-exec</code>. + </li> + <li><code>no-remote-cache-upload</code> keyword disables upload part of remote caching of a spawn. + it does not disable remote execution. + </li> + <li><code>local</code> keyword precludes the action or test from being remotely cached, + remotely executed, or run inside the sandbox. + For genrules and tests, marking the rule with the <code>local = True</code> + attribute has the same effect. + </li> + + <li><code>requires-network</code> keyword allows access to the external + network from inside the sandbox. This tag only has an effect if sandboxing + is enabled. + </li> + + <li><code>block-network</code> keyword blocks access to the external + network from inside the sandbox. In this case, only communication + with localhost is allowed. This tag only has an effect if sandboxing is + enabled. + </li> + + <li><code>requires-fakeroot</code> runs the test or action as uid and gid 0 (i.e., the root + user). This is only supported on Linux. This tag takes precedence over the + <code class='flag'>--sandbox_fake_username</code> command-line option. + </li> +</ul> + +<p> + <i>Tags</i> on tests are generally used to annotate a test's role in your + debug and release process. Typically, tags are most useful for C++ and Python + tests, which lack any runtime annotation ability. The use of tags and size + elements gives flexibility in assembling suites of tests based around codebase + check-in policy. +</p> + +<p> + Bazel modifies test running behavior if it finds the following keywords in the + <code>tags</code> attribute of the test rule: +</p> + +<ul> + <li><code>exclusive</code> will force the test to be run in the + "exclusive" mode, ensuring that no other tests are running at the + same time. Such tests will be executed in serial fashion after all build + activity and non-exclusive tests have been completed. Remote execution is + disabled for such tests because Bazel doesn't have control over what's + running on a remote machine. + </li> + + <li><code>exclusive-if-local</code> will force the test to be run in the + "exclusive" mode if it is executed locally, but will run the test in parallel if it's + executed remotely. + </li> + + <li><code>manual</code> keyword will exclude the target from expansion of target pattern wildcards + (<code>...</code>, <code>:*</code>, <code>:all</code>, etc.) and <code>test_suite</code> rules + which do not list the test explicitly when computing the set of top-level targets to build/run + for the <code>build</code>, <code>test</code>, and <code>coverage</code> commands. It does not + affect target wildcard or test suite expansion in other contexts, including the + <code>query</code> command. Note that <code>manual</code> does not imply that a target should + not be built/run automatically by continuous build/test systems. For example, it may be + desirable to exclude a target from <code>bazel test ...</code> because it requires specific + Bazel flags, but still have it included in properly-configured presubmit or continuous test + runs. + + </li> + + <li><code>external</code> keyword will force test to be unconditionally + executed (regardless of <code class='flag'>--cache_test_results</code> + value). + </li> + + </ul> + +See +<a href="/reference/test-encyclopedia#tag-conventions">Tag Conventions</a> + in the Test Encyclopedia for more conventions on tags attached to test targets. +</td> + </tr> + <tr> + <td id="common.target_compatible_with"><code>target_compatible_with</code></td> + <td><p> +List of <a href="/concepts/labels">labels</a>; default is <code>[]</code> +</p> + +<p> +A list of +<code><a href="platforms-and-toolchains.html#constraint_value">constraint_value</a></code>s +that must be present in the target platform for this target to be considered +<em>compatible</em>. This is in addition to any constraints already set by the +rule type. If the target platform does not satisfy all listed constraints then +the target is considered <em>incompatible</em>. Incompatible targets are +skipped for building and testing when the target pattern is expanded +(e.g. <code>//...</code>, <code>:all</code>). When explicitly specified on the +command line, incompatible targets cause Bazel to print an error and cause a +build or test failure. +</p> + +<p> +Targets that transitively depend on incompatible targets are themselves +considered incompatible. They are also skipped for building and testing. +</p> + +<p> +An empty list (which is the default) signifies that the target is compatible +with all platforms. +<p> + +<p> +All rules other than <a href="workspace.html">Workspace Rules</a> support this +attribute. +For some rules this attribute has no effect. For example, specifying +<code>target_compatible_with</code> for a +<code><a href="c-cpp.html#cc_toolchain">cc_toolchain</a></code> is not useful. +<p> + +<p> +See the +<a href="/docs/platforms#skipping-incompatible-targets">Platforms</a> +page for more information about incompatible target skipping. +</p> +</td> + </tr> + <tr> + <td id="common.testonly"><code>testonly</code></td> + <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>False</code> + except for test and test suite targets</p> + +<p> +If <code>True</code>, only testonly targets (such as tests) can depend on this target. +</p> + +<p> +Equivalently, a rule that is not <code>testonly</code> is not allowed to +depend on any rule that is <code>testonly</code>. +</p> + +<p> +Tests (<code>*_test</code> rules) +and test suites (<a href="/reference/be/general.html#test_suite">test_suite</a> rules) +are <code>testonly</code> by default. +</p> + +<p> +This attribute is intended to mean that the target should not be +contained in binaries that are released to production. +</p> + +<p> +Because testonly is enforced at build time, not run time, and propagates +virally through the dependency tree, it should be applied judiciously. For +example, stubs and fakes that +are useful for unit tests may also be useful for integration tests +involving the same binaries that will be released to production, and +therefore should probably not be marked testonly. Conversely, rules that +are dangerous to even link in, perhaps because they unconditionally +override normal behavior, should definitely be marked testonly. +</p> +</td> + </tr> + <tr> + <td id="common.toolchains"><code>toolchains</code></td> + <td><p>List of <a href="/concepts/labels">labels</a>; + <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> + +<p> + The set of targets whose <a href="/reference/be/make-variables">Make variables</a> this target is + allowed to access. These targets are either instances of rules that provide + <code>TemplateVariableInfo</code> or special targets for toolchain types built into Bazel. These + include: + +<ul> + <li><code>@bazel_tools//tools/cpp:toolchain_type</code> + <li><code>@rules_java//toolchains:current_java_runtime</code> + </ul> + +<p> + Note that this is distinct from the concept of + <a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a> + that is used by rule implementations for platform-dependent configuration. You cannot use this + attribute to determine which specific <code>cc_toolchain</code> or <code>java_toolchain</code> a + target will use. +</p> +</td> + </tr> + <tr> + <td id="common.visibility"><code>visibility</code></td> + <td><p>List of <a href="/concepts/labels">labels</a>; + <a href="#configurable-attributes">nonconfigurable</a>; + default varies +</p> + +<p> + The <code>visibility</code> attribute controls whether the target can be + depended on by targets in other locations. See the documentation for + <a href="/concepts/visibility">visibility</a>. +</p> + +<p> + For targets declared directly in a BUILD file or in legacy macros called from + a BUILD file, the default value is the package's + <code><a href="/reference/be/functions.html#package.default_visibility">default_visibility</a></code> + if specified, or else <code>["//visibility:private"]</code>. For targets + declared in one or more symbolic macros, the default value is always just + <code>["//visibility:private"]</code> (which makes it useable only within the + package containing the macro's code). +</p> +</td> + </tr> + </tbody> + </table> + +<h2 id="common-attributes-tests">Attributes common to all test rules (*_test)</h2> + +<p>This section describes attributes that are common to all test rules.</p> + + <table class="table table-condensed table-bordered table-params"> + <colgroup> + <col class="col-param" /> + <col class="param-description" /> + </colgroup> + <thead> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="test.args"><code>args</code></td> + <td><p>List of strings; subject to +<a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and +<a href="/reference/be/make-variables">"Make variable"</a> substitution, and +<a href="#sh-tokenization">Bourne shell tokenization</a>; default is <code>[]</code></p> + +<p>Command line arguments that Bazel passes to the target when it is +executed with <code>bazel test</code>. + +<p> +These arguments are passed before any <code>--test_arg</code> values +specified on the <code>bazel test</code> command line. +</p> +</td> + </tr> + <tr> + <td id="test.env"><code>env</code></td> + <td><p> + Dictionary of strings; values are subject to + <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and + <a href="/reference/be/make-variables">"Make variable"</a> substitution; default is <code>{}</code> +</p> + +<p> + Specifies additional environment variables to set when the test is executed by + <code>bazel test</code>. +</p> + +<p> + This attribute only applies to native rules, like <code>cc_test</code>, + <code>py_test</code>, and <code>sh_test</code>. It does not apply to + Starlark-defined test rules. For your own Starlark rules, you can add an "env" + attribute and use it to populate a + + <a href="/rules/lib/providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> + Provider. +</p> + <a href="/rules/lib/toplevel/testing#TestEnvironment">TestEnvironment</a> + + Provider. +</p> +</td> + </tr> + <tr> + <td id="test.env_inherit"><code>env_inherit</code></td> + <td><p>List of strings; default is <code>[]</code></p> + +<p>Specifies additional environment variables to inherit from the + external environment when the test is executed by <code>bazel test</code>. +</p> + +<p> + This attribute only applies to native rules, like <code>cc_test</code>, <code>py_test</code>, + and <code>sh_test</code>. It does not apply to Starlark-defined test rules. +</p> +</td> + </tr> + <tr> + <td id="test.size"><code>size</code></td> + <td><p>String <code>"enormous"</code>, <code>"large"</code>, <code>"medium"</code>, or + <code>"small"</code>; <a href="#configurable-attributes">nonconfigurable</a>; + default is <code>"medium"</code></p> + +<p>Specifies a test target's "heaviness": how much time/resources it needs to run.</p> + +<p>Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or +"enormous". Bazel uses the size to determine a default timeout, which can be overridden using the +<code>timeout</code> attribute. The timeout is for all tests in the BUILD target, not for each +individual test. When the test is run locally, the <code>size</code> is additionally used for +scheduling purposes: Bazel tries to respect <code>--local_{ram,cpu}_resources</code> and not +overwhelm the local machine by running lots of heavy tests at the same time.</p> + +<p>Test sizes correspond to the following default timeouts and assumed peak local resource +usages:</p> + +<table style="width: 100%"> + <tr> + <th>Size</th> + <th>RAM (in MB)</th> + <th>CPU (in CPU cores)</th> + <th>Default timeout</th> + </tr> + <tr> + <td>small</td> + <td>20</td> + <td>1</td> + <td>short (1 minute)</td> + </tr> + <tr> + <td>medium</td> + <td>100</td> + <td>1</td> + <td>moderate (5 minutes)</td> + </tr> + <tr> + <td>large</td> + <td>300</td> + <td>1</td> + <td>long (15 minutes)</td> + </tr> + <tr> + <td>enormous</td> + <td>800</td> + <td>1</td> + <td>eternal (60 minutes)</td> + </tr> +</table> + +<p> + The environment variable + <code><a href="/reference/test-encyclopedia#initial-conditions">TEST_SIZE</a></code> will be set to + the value of this attribute when spawning the test. +</p> + +</td> + </tr> + <tr> + <td id="test.timeout"><code>timeout</code></td> + <td><p>String <code>"short"</code>, <code>"moderate"</code>, <code>"long"</code>, or + <code>"eternal"</code>; <a href="#configurable-attributes">nonconfigurable</a>; default is derived + from the test's <code>size</code> attribute</code></p> + +<p> +How long the test is expected to run before returning. +</p> + +<p> +While a test's size attribute controls resource estimation, a test's +timeout may be set independently. If not explicitly specified, the +timeout is based on the <a href="#test.size">test's size</a>. The test +timeout can be overridden with the <code>--test_timeout</code> flag, e.g. for +running under certain conditions which are known to be slow. Test timeout values +correspond to the following time periods: +</p> + +<table style="width: 100%"> + <tr> + <th>Timeout Value</th> + <th>Time Period</th> + </tr> + <tr> + <td>short</td> + <td>1 minute</td> + </tr> + <tr> + <td>moderate</td> + <td>5 minutes</td> + </tr> + <tr> + <td>long</td> + <td>15 minutes</td> + </tr> + <tr> + <td>eternal</td> + <td>60 minutes</td> + </tr> +</table> + +<p> +For times other than the above, the test timeout can be overridden with the +<code>--test_timeout</code> bazel flag, e.g. for manually running under +conditions which are known to be slow. The <code>--test_timeout</code> values +are in seconds. For example <code>--test_timeout=120</code> will set the test +timeout to two minutes. +</p> + +<p> + The environment variable + <code><a href="/reference/test-encyclopedia#initial-conditions">TEST_TIMEOUT</a></code> will be set + to the test timeout (in seconds) when spawning the test. +</p> + +</td> + </tr> + <tr> + <td id="test.flaky"><code>flaky</code></td> + <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; + default is <code>False</code></p> + +<p> +Marks test as flaky. +</p> + +<p> +If set, executes the test up to three times, marking it as failed only if it +fails each time. By default, this attribute is set to False and the test is +executed only once. Note, that use of this attribute is generally discouraged - +tests should pass reliably when their assertions are upheld. +</p> +</td> + </tr> + <tr> + <td id="test.shard_count"><code>shard_count</code></td> + <td><p>Non-negative integer less than or equal to 50; default is <code>-1</code></p> + +<p>Specifies the number of parallel shards +to use to run the test.</p> + +<p>If set, this value will override any heuristics used to determine the number of +parallel shards with which to run the test. Note that for some test +rules, this parameter may be required to enable sharding +in the first place. Also see <code>--test_sharding_strategy</code>.</p> + +<p>If test sharding is enabled, the environment variable <code> +<a href="/reference/test-encyclopedia#initial-conditions">TEST_TOTAL_SHARDS</a> +</code> will be set to this value when spawning the test.</p> + +<p>Sharding requires the test runner to support the test sharding protocol. +If it does not, then it will most likely run every test in every shard, which +is not what you want.</p> + +<p>See +<a href="/reference/test-encyclopedia#test-sharding">Test Sharding</a> +in the Test Encyclopedia for details on sharding.</p> +</td> + </tr> + <tr> + <td id="test.local"><code>local</code></td> + <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; + default is <code>False</code></p> + +<p>Forces the test to be run locally, without sandboxing.</p> + +<p>Setting this to True is equivalent to providing "local" as a tag +(<code>tags=["local"]</code>).</p> +</td> + </tr> + </tbody> + </table> + +<h2 id="common-attributes-binaries">Attributes common to all binary rules (*_binary)</h2> + +<p>This section describes attributes that are common to all binary rules.</p> + + <table class="table table-condensed table-bordered table-params"> + <colgroup> + <col class="col-param" /> + <col class="param-description" /> + </colgroup> + <thead> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="binary.args"><code>args</code></td> + <td><p> + List of strings; subject to + <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and + <a href="/reference/be/make-variables">"Make variable"</a> substitution, and + <a href="#sh-tokenization">Bourne shell tokenization</a>; + <a href="#configurable-attributes">nonconfigurable</a>; + default is <code>[]</code> +</p> + +<p> +Command line arguments that Bazel will pass to the target when it is executed +either by the <code>run</code> command or as a test. These arguments are +passed before the ones that are specified on the <code>bazel run</code> or +<code>bazel test</code> command line. +</p> + +<p> +<em class="harmful">NOTE: The arguments are not passed when you run the target +outside of Bazel (for example, by manually executing the binary in +<code>bazel-bin/</code>).</em> +</p> +</td> + </tr> + <tr> + <td id="binary.env"><code>env</code></td> + <td><p>Dictionary of strings; values are subject to +<a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and +<a href="/reference/be/make-variables">"Make variable"</a> substitution; default is <code>{}</code></p> + +<p>Specifies additional environment variables to set when the target is + executed by <code>bazel run</code>. +</p> + +<p> + This attribute only applies to native rules, like <code>cc_binary</code>, <code>py_binary</code>, + and <code>sh_binary</code>. It does not apply to Starlark-defined executable rules. For your own + Starlark rules, you can add an "env" attribute and use it to populate a + + <a href="/rules/lib/providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> + + Provider. +</p> + +<p> +<em class="harmful">NOTE: The environment variables are not set when you run the target +outside of Bazel (for example, by manually executing the binary in +<code>bazel-bin/</code>).</em> +</p> +</td> + </tr> + <tr> + <td id="binary.output_licenses"><code>output_licenses</code></td> + <td><p>List of strings; default is <code>[]</code></p> + +<p> +The licenses of the output files that this binary generates. + +This is part of a deprecated licensing API that Bazel no longer uses. Don't +use this. +</p> + +</td> + </tr> + </tbody> + </table> + +<h2 id="configurable-attributes">Configurable attributes</h2> + +<p> + Most attributes are "configurable", meaning that their values may change when + the target is built in different ways. Specifically, configurable attributes + may vary based on the flags passed to the Bazel command line, or what + downstream dependency is requesting the target. This can be used, for + instance, to customize the target for multiple platforms or compilation modes. +</p> + +<p> + The following example declares different sources for different target + architectures. Running <code>bazel build :multiplatform_lib --cpu x86</code> + will build the target using <code>x86_impl.cc</code>, while substituting + <code>--cpu arm</code> will instead cause it to use <code>arm_impl.cc</code>. +</p> + +<pre class="code"> +cc_library( + name = "multiplatform_lib", + srcs = select({ + ":x86_mode": ["x86_impl.cc"], + ":arm_mode": ["arm_impl.cc"] + }) +) +config_setting( + name = "x86_mode", + values = { "cpu": "x86" } +) +config_setting( + name = "arm_mode", + values = { "cpu": "arm" } +) +</pre> + +<p> + The <a href="/reference/be/functions.html#select"><code>select()</code></a> function + chooses among different alternative values for a configurable attribute based + on which <a href="/reference/be/general.html#config_setting"><code>config_setting</code></a> + or <a href="/reference/be/platforms-and-toolchains.html#constraint_value"><code>constraint_value</code></a> + criteria the target's configuration satisfies. +</p> + +<p> + Bazel evaluates configurable attributes after processing macros and before + processing rules (technically, between the + <a href="https://bazel.build/rules/concepts#evaluation-model"> + loading and analysis phases</a>). + Any processing before <code>select()</code> evaluation doesn't know which + branch the <code>select()</code> chooses. Macros, for example, can't change + their behavior based on the chosen branch, and <code>bazel query</code> can + only make conservative guesses about a target's configurable dependencies. See + <a href="https://bazel.build/docs/configurable-attributes#faq"> + this FAQ</a> + for more on using <code>select()</code> with rules and macros. +</p> + +<p> + Attributes marked <code>nonconfigurable</code> in their documentation cannot + use this feature. Usually an attribute is nonconfigurable because Bazel + internally needs to know its value before it can determine how to resolve a + <code>select()</code>. +</p> + +<p> + See <a href="https://bazel.build/docs/configurable-attributes"> + Configurable Build Attributes</a> for a detailed overview. +</p> + +<h2 id="implicit-outputs">Implicit output targets</h2> + +<p> + <i>Implicit outputs in C++ are deprecated. Please refrain from using it + in other languages where possible. We don't have a deprecation path yet + but they will eventually be deprecated too.</i> +</p> + +<p>When you define a build rule in a BUILD file, you are explicitly + declaring a new, named rule target in a package. Many build rule + functions also <i>implicitly</i> entail one or more output file + targets, whose contents and meaning are rule-specific. + + For example, when you explicitly declare a + <code>java_binary(name='foo', ...)</code> rule, you are also + <i>implicitly</i> declaring an output file + target <code>foo_deploy.jar</code> as a member of the same package. + (This particular target is a self-contained Java archive suitable + for deployment.) +</p> + +<p> + Implicit output targets are first-class members of the global + target graph. Just like other targets, they are built on demand, + either when specified in the top-level built command, or when they + are necessary prerequisites for other build targets. They can be + referenced as dependencies in BUILD files, and can be observed in + the output of analysis tools such as <code>bazel query</code>. +</p> + +<p> + For each kind of build rule, the rule's documentation contains a + special section detailing the names and contents of any implicit + outputs entailed by a declaration of that kind of rule. +</p> + +<p> + An important but somewhat subtle distinction between the + two namespaces used by the build system: + <a href="/concepts/labels">labels</a> identify <em>targets</em>, + which may be rules or files, and file targets may be divided into + either source (or input) file targets and derived (or output) file + targets. These are the things you can mention in BUILD files, + build from the command-line, or examine using <code>bazel query</code>; + this is the <em>target namespace</em>. Each file target corresponds + to one actual file on disk (the "file system namespace"); each rule + target may correspond to zero, one or more actual files on disk. + There may be files on disk that have no corresponding target; for + example, <code>.o</code> object files produced during C++ compilation + cannot be referenced from within BUILD files or from the command line. + In this way, the build tool may hide certain implementation details of + how it does its job. This is explained more fully in + the <a href="/concepts/build-ref">BUILD Concept Reference</a>. +</p> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/extra-actions.mdx b/reference/be/extra-actions.mdx new file mode 100644 index 0000000..099a7eb --- /dev/null +++ b/reference/be/extra-actions.mdx @@ -0,0 +1,324 @@ +--- +title: 'extra-actions' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">Extra Actions Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% include "_buttons.html" %} + + + + +<h2>Rules</h2> +<ul> + <li> + <a href="#action_listener"> + action_listener </a> + </li> + <li> + <a href="#extra_action"> + extra_action </a> + </li> +</ul> + + <h2 id="action_listener"> + action_listener + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">action_listener(<a href="#action_listener.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#action_listener.extra_actions">extra_actions</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#action_listener.mnemonics">mnemonics</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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> + <b>WARNING:</b> Extra actions are deprecated. Use + <a href="https://bazel.build/rules/aspects">aspects</a> + instead. +</p> + +<p> + An <code>action_listener</code> rule doesn't produce any output itself. + Instead, it allows tool developers to insert + <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a>s into the build system, + by providing a mapping from action to <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code> + </a>. +</p> + +<p> + This rule's arguments map action mnemonics to + <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a> rules. +</p> + +<p> + By specifying the option <a href="/docs/user-manual#flag--experimental_action_listener"> + <code>--experimental_action_listener=<label></code></a>, + the build will use the specified <code>action_listener</code> to insert + <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a>s into the build graph. +</p> + +<h4 id="action_listener_example">Example</h4> +<pre> +action_listener( + name = "index_all_languages", + mnemonics = [ + "Javac", + "CppCompile", + "Python", + ], + extra_actions = [":indexer"], +) + +action_listener( + name = "index_java", + mnemonics = ["Javac"], + extra_actions = [":indexer"], +) + +extra_action( + name = "indexer", + tools = ["//my/tools:indexer"], + cmd = "$(location //my/tools:indexer)" + + "--extra_action_file=$(EXTRA_ACTION_FILE)", +) +</pre> + + + + <h3 id="action_listener_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="action_listener.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="action_listener.extra_actions"> + <code>extra_actions</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; required</p> + A list of <code><a href="/reference/be/extra-actions.html#extra_action">extra_action</a></code> targets + this <code>action_listener</code> should add to the build graph. + E.g. <code>[ "//my/tools:analyzer" ]</code>. + + </td> + </tr> + <tr> + <td id="action_listener.mnemonics"> + <code>mnemonics</code> + </td> + <td> + <p>List of strings; required</p> + A list of action mnemonics this <code>action_listener</code> should listen + for, e.g. <code>[ "Javac" ]</code>. + <p> + Mnemonics are not a public interface. + There's no guarantee that the mnemonics and their actions don't change. + </p> + + </td> + </tr> + </tbody> + </table> + <h2 id="extra_action"> + extra_action + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ExtraActionRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">extra_action(<a href="#extra_action.name">name</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#extra_action.cmd">cmd</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#extra_action.out_templates">out_templates</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#extra_action.requires_action_output">requires_action_output</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.toolchains">toolchains</a>, <a href="#extra_action.tools">tools</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + +<p> + <b>WARNING:</b> Extra actions are deprecated. Use + <a href="https://bazel.build/rules/aspects">aspects</a> + instead. +</p> + +<p> + An <code>extra_action</code> rule doesn't produce any meaningful output + when specified as a regular build target. Instead, it allows tool developers + to insert additional actions into the build graph that shadow existing actions. +</p> + +<p> + See <a href="/reference/be/extra-actions.html#action_listener"><code>action_listener</code></a> for details + on how to enable <code>extra_action</code>s. +</p> + +<p> + The <code>extra_action</code>s run as a command-line. The command-line tool gets + access to a file containing a protocol buffer as $(EXTRA_ACTION_FILE) + with detailed information on the original action it is shadowing. + It also has access to all the input files the original action has access to. + See <tt>extra_actions_base.proto</tt> + for details on the data stored inside the protocol buffer. Each proto file + contains an ExtraActionInfo message. +</p> + +<p> + Just like all other actions, extra actions are sandboxed, and should be designed to handle that. +</p> + + + + <h3 id="extra_action_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="extra_action.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + You may refer to this rule by <code>label</code> in the <code>extra_actions</code> argument + of <a href="/reference/be/extra-actions.html#action_listener"><code> action_listener</code></a> rules. + + </td> + </tr> + <tr> + <td id="extra_action.cmd"> + <code>cmd</code> + </td> + <td> + <p>String; required</p> + The command to run. + <p> + Like <a href="/reference/be/general.html#genrule.cmd">genrule cmd attribute</a> with the following + differences: + </p> + <ol> + <li> + <p> + No heuristic label expansion. Only labels using $(location ...) are expanded. + </p> + </li> + <li> + <p> + An additional pass is applied to the string to replace all + occurrences of the outputs created from the <code>out_templates</code> + attribute. All occurrences of <code>$(output <i>out_template</i>)</code> + are replaced with the path to the file denoted by <code>label</code>. + </p> + <p> + E.g. out_template <code>$(ACTION_ID).analysis</code> + can be matched with <code>$(output $(ACTION_ID).analysis)</code>. + </p> + <p> + In effect, this is the same substitution as <code>$(location)</code> + but with a different scope. + </p> + </li> + </ol> + + </td> + </tr> + <tr> + <td id="extra_action.out_templates"> + <code>out_templates</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + A list of templates for files generated by the <code>extra_action</code> command. + <p> + The template can use the following variables: + <ul> + <li> + $(ACTION_ID), an id uniquely identifying this <code>extra_action</code>. + Used to generate a unique output file. + </li> + </ul> + </p> + + </td> + </tr> + <tr> + <td id="extra_action.requires_action_output"> + <code>requires_action_output</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Indicates this <code>extra_action</code> requires the output of the + original action to be present as input to this <code>extra_action</code>. + <p> + When true (default false), the extra_action can assume that the + original action outputs are available as part of its inputs. + </p> + + </td> + </tr> + <tr> + <td id="extra_action.tools"> + <code>tools</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of <code>tool</code> dependencies for this rule. + <p> + See the definition of <a href="/concepts/build-ref#deps">dependencies</a> for more + information. + </p> + <p> + The build system ensures these prerequisites are built before running the + <code>extra_action</code> command; they are built using the + <a href='/docs/user-manual#configurations'><code>exec</code>configuration</a>, + since they must run as a tool during the build itself. The path of an individual + <code>tools</code> target <code>//x:y</code> can be obtained using + <code>$(location //x:y)</code>. + </p> + <p> + All tools and their data dependencies are consolidated into a single tree + within which the command can use relative paths. The working directory will + be the root of that unified tree. + </p> + + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/functions.mdx b/reference/be/functions.mdx new file mode 100644 index 0000000..a982ea8 --- /dev/null +++ b/reference/be/functions.mdx @@ -0,0 +1,810 @@ +--- +title: 'functions' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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 --> + +<h1 class="page-title">Functions</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm" %} +{% include "_buttons.html" %} + +<h2>Contents</h2> +<ul> + <li><a href="#package">package</a></li> + <li><a href="#package_group">package_group</a></li> + <li><a href="#exports_files">exports_files</a></li> + <li><a href="#glob">glob</a></li> + <li><a href="#select">select</a></li> + <li><a href="#subpackages">subpackages</a></li> +</ul> +<!-- ================================================================= + package() + ================================================================= +--> + +<h2 id="package">package</h2> + +<pre> +package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features) +</pre> +<p>This function declares metadata that applies to every rule in the +package. It is used at most once within a package (BUILD file).</p> + +<p>For the counterpart that declares metadata applying to every rule in the whole +<em>repository</em>, use the <code>repo()</code> function in the +<a href="/external/overview#repo.bazel"><code>REPO.bazel</code> file</a> at the root of your repo. +The <code>repo()</code> function takes exactly the same arguments as <code>package()</code>.</p> +<p>The package() function should be called right after all the load() statements at the top of the +file, before any rule.</p> + +<h3 id="package_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>Attribute</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="package.default_applicable_licenses"><code>default_applicable_licenses</code></td> + <td> + <p>Alias for <a href="#package.default_package_metadata"><code>default_package_metadata</code></a>. + </td> + </tr> + <tr> + <td id="package.default_visibility"><code>default_visibility</code></td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + <p>The default visibility of the top-level rule targets and symbolic + macros in this package — that is, the targets and symbolic macros + that are not themselves declared inside a symbolic macro. This attribute + is ignored if the target or macro specifies a <code>visibility</code> + value.</p> + <p>For detailed information about the syntax of this attribute, see the + documentation of <a href="/concepts/visibility"> + visibility</a>. The package default visibility does not apply to + <a href="#exports_files">exports_files</a>, which is public by default. + </p> + </td> + </tr> + <tr> + <td id="package.default_deprecation"><code>default_deprecation</code></td> + <td> + <p>String; default is <code>""</code></p> + <p>Sets the default <a href="common-definitions.html#common.deprecation"> + <code>deprecation</code></a> message for all rules in this package.</p> + </td> + </tr> + <tr> + <td id="package.default_package_metadata"><code>default_package_metadata</code></td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + <p>Sets a default list of metadata targets which apply to all other targets in the package. + These are typically targets related to OSS package and license declarations. + See <a href="https://github.com/bazelbuild/rules_license">rules_license</a> for examples.</p> + </td> + </tr> + <tr> + <td id="package.default_testonly"><code>default_testonly</code></td> + <td> + <p>Boolean; default is <code>False</code> except as noted</p> + <p>Sets the default <a href="common-definitions.html#common.testonly"> + <code>testonly</code></a> property for all rules in this package.</p> + <p>In packages under <code>javatests</code> the default value is <code>True</code>.</p> + </td> + </tr> + <tr> + <td id="package.features"><code>features</code></td> + <td> + <p>List strings; default is <code>[]</code></p> + <p>Sets various flags that affect the semantics of this BUILD file.</p> + <p>This feature is mainly used by the people working on the build system to + tag packages that need some kind of special handling. Do not use this unless + explicitly requested by someone working on the build system.</p> + + </td> + </tr> + + </tbody> +</table> + +<h3 id="package_example">Examples</h3> + +The declaration below declares that the rules in this package are +visible only to members of package +group <code>//foo:target</code>. Individual visibility declarations +on a rule, if present, override this specification. + +<pre class="code"> +package(default_visibility = ["//foo:target"]) +</pre> + +<!-- ================================================================= + package_group() + ================================================================= +--> + +<h2 id="package_group">package_group</h2> + +<pre>package_group(name, packages, includes)</pre> + +<p>This function defines a set of <a href="/concepts/build-ref#packages">packages</a> +and associates a label with the set. The label can be referenced in +<code>visibility</code> attributes.</p> + +<p>Package groups are primarily used for visibility control. A publicly visible +target can be referenced from every package in the source tree. A privately +visible target can only be referenced within its own package (not subpackages). +In between these extremes, a target may allow access to its own package plus any +of the packages described by one or more package groups. For a more detailed +explanation of the visibility system, see the +<a href="common-definitions.html#common.visibility">visibility</a> +attribute.</p> + +<p>A given package is considered to be in the group if it either matches the +<code>packages</code> attribute, or is already contained in one of the other +package groups mentioned in the <code>includes</code> attribute.</p> + +<p>Package groups are technically targets, but are not created by rules, and do +not themselves have any visibility protection.</p> + +<h3 id="package_group_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>Attribute</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="package_group.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + </td> + </tr> + <tr> + <td id="package_group.packages"><code>packages</code></td> + <td> + <p>List of strings; default is <code>[]</code></p> + <p>A list of zero or more package specifications.</p> + + <p>Each package specification string can have one of the following + forms:</p> + + <ol> + + <li>The full name of a package, without its repository, starting with a + double slash. For example, <code>//foo/bar</code> specifies the package + having that name and which lives in the same repository as the package + group. + + <li>As above, but with a trailing <code>/...</code>. For example, <code> + //foo/...</code> specifies the set of <code>//foo</code> and all its + subpackages. <code>//...</code> specifies all packages in the current + repository. + + <li>The strings <code>public</code> or <code>private</code>, which + respectively specify every package or no package. (This form requires + the flag <code>--incompatible_package_group_has_public_syntax</code> to + be set.) + + </ol> + + <p>In addition, the first two kinds of package specifications may also + be prefixed with <code>-</code> to indicate that they are negated.</p> + + <p>The package group contains any package that matches at least one of + its positive specifications and none of its negative specifications + For instance, the value <code>[//foo/..., -//foo/tests/...]</code> + includes all subpackages of <code>//foo</code> that are not also + subpackages of <code>//foo/tests</code>. (<code>//foo</code> itself is + included while </code>//foo/tests</code> itself is not.)</p> + + <p>Aside from public visibility, there is no way to directly specify + packages outside the current repository.</p> + + <p>If this attribute is missing, it is the same as setting it to an + empty list, which is also the same as setting it to a list containing + only <code>private</code>. + + <p><i>Note:</i> Prior to Bazel 6.0, the specification <code>//...</code> + had a legacy behavior of being the same as <code>public</code>. This + behavior is fixed when + <code>--incompatible_fix_package_group_reporoot_syntax</code> is + enabled, which is the default after Bazel 6.0.</p> + + <p><i>Note:</i> Prior to Bazel 6.0, when this attribute is serialized as + part of <code>bazel query --output=proto</code> (or + <code>--output=xml</code>), the leading slashes are omitted. For + instance, <code>//pkg/foo/...</code> will output as + <code>\"pkg/foo/...\"</code>. This behavior is fixed when + <code>--incompatible_package_group_includes_double_slash</code> is + enabled, which is the default after Bazel 6.0.</p> + </td> + </tr> + <tr> + <td id="package_group.includes"><code>includes</code></td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + <p>Other package groups that are included in this one.</p> + + <p>The labels in this attribute must refer to other package groups. + Packages in referenced package groups are taken to be part of this + package group. This is transitive — if package group + <code>a</code> includes package group <code>b</code>, and <code>b</code> + includes package group <code>c</code>, then every package in + <code>c</code> will also be a member of <code>a</code>.</p> + + <p>When used together with negated package specifications, note that the + set of packages for each group is first computed independently and the + results are then unioned together. This means that negated + specifications in one group have no effect on the specifications in + another group.</p> + </td> + </tr> + </tbody> +</table> + +<h3 id="package_group_example">Examples</h3> + +<p>The following <code>package_group</code> declaration specifies a +package group called "tropical" that contains tropical fruits.</p> + +<pre class="code"> +package_group( + name = "tropical", + packages = [ + "//fruits/mango", + "//fruits/orange", + "//fruits/papaya/...", + ], +) +</pre> + +<p>The following declarations specify the package groups of a fictional +application:</p> + +<pre class="code"> +package_group( + name = "fooapp", + includes = [ + ":controller", + ":model", + ":view", + ], +) + +package_group( + name = "model", + packages = ["//fooapp/database"], +) + +package_group( + name = "view", + packages = [ + "//fooapp/swingui", + "//fooapp/webui", + ], +) + +package_group( + name = "controller", + packages = ["//fooapp/algorithm"], +) +</pre> + +<!-- ================================================================= + exports_files([label, ...]) + ================================================================= + --> + +<h2 id="exports_files">exports_files</h2> + +<pre>exports_files([<i>label</i>, ...], visibility, licenses)</pre> + +<p> + <code>exports_files()</code> specifies a list of files belonging to + this package that are exported to other packages. +</p> + +<p> + The BUILD file for a package may only refer directly to source files belonging + to another package if they are explicitly exported with an + <code>exports_files()</code> statement. Read more about + <a href="/concepts/visibility#source-file-target-visibility">visibility of files</a>. +</p> + <p> + As a legacy behaviour, also files mentioned as input to a rule are exported + with the default visibility until the flag + <a href="https://github.com/bazelbuild/bazel/issues/10225"><code>--incompatible_no_implicit_file_export</code></a> + is flipped. However, this behavior should not be relied upon and actively + migrated away from. +</p> + +<h3 id="exports_files_args">Arguments</h3> + +<p> + The argument is a list of names of files within the current package. A + visibility declaration can also be specified; in this case, the files will be + visible to the targets specified. If no visibility is specified, the files + will be visible to every package, even if a package default visibility was + specified in the <code><a href="functions.html#package">package</a></code> + function. The <a href="common-definitions.html#common.licenses">licenses</a> + can also be specified. +</p> + +<h3 id="exports_files_example">Example</h3> + +<p> + The following example exports <code>golden.txt</code>, a + text file from the <code>test_data</code> package, so that other + packages may use it, for example, in the <code>data</code> attribute + of tests. +</p> + +<pre class="code"> +# from //test_data/BUILD + +exports_files(["golden.txt"]) +</pre> + +<!-- ================================================================= + glob() + ================================================================= + --> + +<h2 id="glob">glob</h2> + +<pre>glob(include, exclude=[], exclude_directories=1, allow_empty=True)</pre> + +<p> +Glob is a helper function that finds all files that match certain path patterns, +and returns a new, mutable, sorted list of their paths. Glob only searches files +in its own package, and looks only for source files (not generated files nor +other targets). +</p> + +<p> +A source file's Label is included in the result if the file's package-relative +path matches any of the <code>include</code> patterns and none of the +<code>exclude</code> patterns. +</p> + +<p> +The <code>include</code> and <code>exclude</code> lists contain path patterns +that are relative to the current package. Every pattern may consist of one or +more path segments. As usual with Unix paths, these segments are separated by +<code>/</code>. The segments in the pattern are matched against the segments of +the path. Segments may contain the <code>*</code> wildcard: this matches +any substring in the path segment (even the empty substring), excluding the +directory separator <code>/</code>. This wildcard can be used multiple times +within one path segment. Additionally, the <code>**</code> wildcard can match +zero or more complete path segments, but it must be declared as a standalone +path segment. +</p> + +Examples: +<ul> +<li><code>foo/bar.txt</code> matches exactly the <code>foo/bar.txt</code> file +in this package (unless <code>foo/</code> is a subpackage)</li> +<li><code>foo/*.txt</code> matches every file in the <code>foo/</code> directory +if the file ends with <code>.txt</code> (unless <code>foo/</code> is a +subpackage)</li> +<li><code>foo/a*.htm*</code> matches every file in the <code>foo/</code> +directory that starts with <code>a</code>, then has an arbitrary string (could +be empty), then has <code>.htm</code>, and ends with another arbitrary string +(unless <code>foo/</code> is a subpackage); such as <code>foo/axx.htm</code> +and <code>foo/a.html</code> or <code>foo/axxx.html</code></li> +<li><code>foo/*</code> matches every file in the <code>foo/</code> directory, +(unless <code>foo/</code> is a subpackage); it does not match <code>foo</code> +directory itself even if <code>exclude_directories</code> is set to +</code>0</code></li> +<li><code>foo/**</code> matches every file in every non-subpackage subdirectory +under package's first level subdirectory <code>foo/</code>; if +<code>exclude_directories</code> is set to </code>0</code>, <code>foo</code> +directory itself also matches the pattern; in this case, <code>**</code> is +considered to match zero path segments</li> +<li><code>**/a.txt</code> matches <code>a.txt</code> files in this package's +directory plus non-subpackage subdirectories.</li> +<li><code>**/bar/**/*.txt</code> matches every <code>.txt</code> file in every +non-subpackage subdirectory of this package, if at least one directory on the +resulting path is called <code>bar</code>, such as +<code>xxx/bar/yyy/zzz/a.txt</code> or <code>bar/a.txt</code> (remember that +<code>**</code> also matches zero segments) or <code>bar/zzz/a.txt</code></li> +<li><code>**</code> matches every file in every non-subpackage subdirectory of +this package</li> +<li><code>foo**/a.txt</code> is an invalid pattern, because <code>**</code> must +stand on its own as a segment</li> +<li><code>foo/</code> is an invalid pattern, because the second segment defined +after <code>/</code> is an empty string</li> +</ul> + +<p> +If the <code>exclude_directories</code> argument is enabled (set to 1), files of +type directory will be omitted from the results (default 1). +</p> +<p> +If the <code>allow_empty</code> argument is set to <code>False</code>, the +<code>glob</code> function will error-out if the result would otherwise be the +empty list. +</p> +<p> +There are several important limitations and caveats: +</p> + +<ol> + <li> + <p> + Since <code>glob()</code> runs during BUILD file evaluation, + <code>glob()</code> matches files only in your source tree, never + generated files. If you are building a target that requires both + source and generated files, you must append an explicit list of generated + files to the glob. See the <a href="#glob_example">example</a> + below with <code>:mylib</code> and <code>:gen_java_srcs</code>. + </p> + </li> + + <li> + <p> + If a rule has the same name as a matched source file, the rule will + "shadow" the file. + </p> + <p> + To understand this, remember that <code>glob()</code> returns a list of + paths, so using <code>glob()</code> in other rules' attribute (e.g. + <code>srcs = glob(["*.cc"])</code>) has the same effect as listing the + matched paths explicitly. If for example <code>glob()</code> yields + <code>["Foo.java", "bar/Baz.java"]</code> but there's also a rule in the + package called "Foo.java" (which is allowed, though Bazel warns about it), + then the consumer of the <code>glob()</code> will use the "Foo.java" rule + (its outputs) instead of the "Foo.java" file. See + <a href="https://github.com/bazelbuild/bazel/issues/10395#issuecomment-583714657">GitHub + issue #10395</a> for more details. + </p> + </li> + + <li> + Globs may match files in subdirectories. And subdirectory names + may be wildcarded. However... + </li> + + <li> + <p> + Labels are not allowed to cross the package boundary and glob does + not match files in subpackages. + </p> + + <p> + For example, the glob expression <code>**/*.cc</code> in package + <code>x</code> does not include <code>x/y/z.cc</code> if + <code>x/y</code> exists as a package (either as + <code>x/y/BUILD</code>, or somewhere else on the package-path). This + means that the result of the glob expression actually depends on the + existence of BUILD files — that is, the same glob expression would + include <code>x/y/z.cc</code> if there was no package called + <code>x/y</code> or it was marked as deleted using the + <a href="/docs/user-manual#flag--deleted_packages">--deleted_packages</a> + flag. + </p> + + </li> + + <li> + The restriction above applies to all glob expressions, + no matter which wildcards they use. + </li> + <li> + A hidden file with filename starting with <code>.</code> is completely matched by + both the <code>**</code> and the <code>*</code> wildcards. If you want to match a hidden file + with a compound pattern, your pattern needs to begin with a <code>.</code>. For example, + <code>*</code> and <code>.*.txt</code> will match <code>.foo.txt</code>, but <code>*.txt</code> + will not. + + Hidden directories are also matched in the same manner. Hidden directories + may include files that are not required as inputs, and can increase the + number of unnecessarily globbed files and memory consumption. To exclude + hidden directories, add them to the "exclude" list argument. + </li> + + <li> + The "**" wildcard has one corner case: the pattern + <code>"**"</code> doesn't match the package's directory path. That is to + say, <code>glob(["**"], exclude_directories = False)</code> matches all files + and directories transitively strictly under the current package's directory + (but of course not going into directories of subpackages - see the previous + note about that). + </li> +</ol> + +<p> +In general, you should <b>try to provide an appropriate extension (e.g. *.html) +instead of using a bare '*'</b> for a glob pattern. The more explicit name +is both self documenting and ensures that you don't accidentally match backup +files, or emacs/vi/... auto-save files. +</p> + +<p> +When writing build rules you can enumerate the elements of the glob. This +enables generating individual rules for every input, for example. See the +<a href="#expanded_glob_example">expanded glob example</a> section below. +</p> + +<h3 id="glob_example">Glob Examples</h3> + +<p> Create a Java library built from all java files in this directory, +and all files generated by the <code>:gen_java_srcs</code> rule.</p> +<pre class="code"> +java_library( + name = "mylib", + srcs = glob(["*.java"]) + [":gen_java_srcs"], + deps = "...", +) + +genrule( + name = "gen_java_srcs", + outs = [ + "Foo.java", + "Bar.java", + ], + ... +) +</pre> + +<p>Include all txt files in directory testdata except experimental.txt. +Note that files in subdirectories of testdata will not be included. If +you want those files to be included, use a recursive glob (**).</p> +<pre class="code"> +sh_test( + name = "mytest", + srcs = ["mytest.sh"], + data = glob( + ["testdata/*.txt"], + exclude = ["testdata/experimental.txt"], + ), +) +</pre> + +<h3 id="recursive_glob_example">Recursive Glob Examples</h3> + + +<p>Make the test depend on all txt files in the testdata directory and any + of its subdirectories (and their subdirectories, and so on). + Subdirectories containing a BUILD file are ignored. (See limitations + and caveats above.)</p> +<pre class="code"> +sh_test( + name = "mytest", + srcs = ["mytest.sh"], + data = glob(["testdata/**/*.txt"]), +) +</pre> + +<p>Create a library built from all java files in this directory and all +subdirectories except those whose path includes a directory named testing. +<b>This pattern should be avoided if possible, as it can reduce build +incrementality and therefore increase build times.</b> +</p> +<pre class="code"> +java_library( + name = "mylib", + srcs = glob( + ["**/*.java"], + exclude = ["**/testing/**"], + ), +) +</pre> + +<h3 id="expanded_glob_example">Expanded Glob Examples</h3> + +<p> +Create an individual genrule for *_test.cc in the current directory +that counts the number of lines in the file. +</p> + +<pre class="code"> +# Conveniently, the build language supports list comprehensions. +[genrule( + name = "count_lines_" + f[:-3], # strip ".cc" + srcs = [f], + outs = ["%s-linecount.txt" % f[:-3]], + cmd = "wc -l $< >$@", + ) for f in glob(["*_test.cc"])] +</pre> + +<p> +If the BUILD file above is in package //foo and the package contains three +matching files, a_test.cc, b_test.cc and c_test.cc then running +<code>bazel query '//foo:all'</code> will list all rules that were generated: + +<pre> +$ bazel query '//foo:all' | sort +//foo:count_lines_a_test +//foo:count_lines_b_test +//foo:count_lines_c_test +</pre> + +<!-- ================================================================= + select() + ================================================================= +--> + +<h2 id="select">select</h2> + +<pre> +select( + {conditionA: valuesA, conditionB: valuesB, ...}, + no_match_error = "custom message" +) +</pre> + +<p><code>select()</code> is the helper function that makes a rule attribute + <a href="common-definitions.html#configurable-attributes">configurable</a>. + It can replace the right-hand side of + + <i>almost</i> + any attribute assignment so its value depends on command-line Bazel flags. + You can use this, for example, to define platform-specific dependencies or to + embed different resources depending on whether a rule is built in "developer" + vs. "release" mode. +</p> + +<p>Basic use is as follows:</p> + +<pre class="code"> +sh_binary( + name = "mytarget", + srcs = select({ + ":conditionA": ["mytarget_a.sh"], + ":conditionB": ["mytarget_b.sh"], + "//conditions:default": ["mytarget_default.sh"] + }) +) +</pre> + +<p>This makes the <code>srcs</code> attribute of + a <code>sh_binary</code> configurable by replacing its normal label + list assignment with a <code>select</code> call that maps + configuration conditions to matching values. Each condition is a label + reference to + a <code><a href="general.html#config_setting">config_setting</a></code> or + <code><a href="platforms-and-toolchains.html#constraint_value">constraint_value</a></code>, + which "matches" if the target's configuration matches an expected set of + values. The value of <code>mytarget#srcs</code> then becomes whichever + label list matches the current invocation. +</p> + +<p>Notes:</p> + +<ul> + <li>Exactly one condition is selected on any invocation. + </li> + <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 and constraint + values as A plus some additional flags or constraint values. This also + means that specialization resolution is not designed to create an ordering as + demonstrated in Example 2 below. + </li> + <li>If multiple conditions match and one is not a specialization of all the + others, Bazel fails with an error, unless all conditions resolve to the same value. + </li> + <li>The special pseudo-label <code>//conditions:default</code> is + considered to match if no other condition matches. If this condition + is left out, some other rule must match to avoid an error. + </li> + <li><code>select</code> can be embedded <i>inside</i> a larger + attribute assignment. So <code>srcs = ["common.sh"] + + select({ ":conditionA": ["myrule_a.sh"], ...})</code> and <code> + srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": + ["b.sh"]})</code> are valid expressions. + </li> + <li><code>select</code> works with most, but not all, attributes. Incompatible + attributes are marked <code>nonconfigurable</code> in their documentation. + +<!-- ================================================================= + subpackages() + ================================================================= + --> + +<h2 id="subpackages">subpackages</h2> + +<pre>subpackages(include, exclude=[], allow_empty=True)</pre> + +<p> + <code>subpackages()</code> is a helper function, similar to <code>glob()</code> + that lists subpackages instead of files and directories. It uses the same + path patterns as <code>glob()</code> and can match any subpackage that is a + direct descendant of the currently loading BUILD file. See <a + href="#glob">glob</a> for a detailed explanation and examples of include and + exclude patterns. +</p> + +<p> + The resulting list of subpackages returned is in sorted order and contains + paths relative to the current loading package that match the given patterns in + <code>include</code> and not those in <code>exclude</code>. + +<h3 id=subpackages_example">Example</h3> + +<p> + The following example lists all the direct subpackages for the package <code>foo/BUILD</code> + +<pre class="code"> +# The following BUILD files exist: +# foo/BUILD +# foo/bar/baz/BUILD +# foo/bar/but/bad/BUILD +# foo/sub/BUILD +# foo/sub/deeper/BUILD +# +# In foo/BUILD a call to +subs1 = subpackages(include = ["**"]) + +# results in subs1 == ["sub", "bar/baz", "bar/but/bad"] +# +# 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of +# 'foo' + +subs2 = subpackages(include = ["bar/*"]) +# results in subs2 = ["bar/baz"] +# +# Since 'bar' is not a subpackage itself, this looks for any subpackages under +# all first level subdirectories of 'bar'. + +subs3 = subpackages(include = ["bar/**"]) +# results in subs3 = ["bar/baz", "bar/but/bad"] +# +# Since bar is not a subpackage itself, this looks for any subpackages which are +# (1) under all subdirectories of 'bar' which can be at any level, (2) not a +# subpackage of another subpackages. + +subs4 = subpackages(include = ["sub"]) +subs5 = subpackages(include = ["sub/*"]) +subs6 = subpackages(include = ["sub/**"]) +# results in subs4 and subs6 being ["sub"] +# results in subs5 = []. +# +# In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a +# subpackage of 'foo'). +# In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since +# 'foo/sub' is already a subpackage itself, the subdirectories will not be +# traversed anymore. +# In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it +# is returned. But the subdirectories of 'foo/sub' will not be traversed +# anymore. +</pre> + + <p> + In general it is preferred that instead of calling this function directly + that users use the 'subpackages' module of + <a href="https://github.com/bazelbuild/bazel-skylib">skylib</a>. + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/general.mdx b/reference/be/general.mdx new file mode 100644 index 0000000..946c9b9 --- /dev/null +++ b/reference/be/general.mdx @@ -0,0 +1,1529 @@ +--- +title: 'general' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">General Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% include "_buttons.html" %} + + + + +<h2>Rules</h2> +<ul> + <li> + <a href="#alias"> + alias </a> + </li> + <li> + <a href="#config_setting"> + config_setting </a> + </li> + <li> + <a href="#filegroup"> + filegroup </a> + </li> + <li> + <a href="#genquery"> + genquery </a> + </li> + <li> + <a href="#genrule"> + genrule </a> + </li> + <li> + <a href="#starlark_doc_extract"> + starlark_doc_extract </a> + </li> + <li> + <a href="#test_suite"> + test_suite </a> + </li> +</ul> + + <h2 id="alias"> + alias + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/Alias.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">alias(<a href="#alias.name">name</a>, <a href="#alias.actual">actual</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.package_metadata">package_metadata</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> + The <code>alias</code> rule creates another name a rule can be referred to as. +</p> + +<p> + Aliasing only works for "regular" targets. In particular, <code>package_group</code> + and <code>test_suite</code> cannot be aliased. +</p> + +<p> + Aliasing may be of help in large repositories where renaming a target would require making + changes to lots of files. You can also use alias rule to store a + <a href="/reference/be/functions.html#select">select</a> function call if you want to reuse that logic for + multiple targets. +</p> + +<p> + The alias rule has its own visibility declaration. In all other respects, it behaves + like the rule it references (e.g. testonly <em>on the alias</em> is ignored; the testonly-ness + of the referenced rule is used instead) with some minor exceptions: + + <ul> + <li> + Tests are not run if their alias is mentioned on the command line. To define an alias + that runs the referenced test, use a <a href="#test_suite"><code>test_suite</code></a> + rule with a single target in its <a href="#test_suite.tests"><code>tests</code></a> + attribute. + </li> + <li> + When defining environment groups, the aliases to <code>environment</code> rules are not + supported. They are not supported in the <code>--target_environment</code> command line + option, either. + </li> + </ul> +</p> + +<h4 id="alias_example">Examples</h4> + +<pre class="code"> +filegroup( + name = "data", + srcs = ["data.txt"], +) + +alias( + name = "other", + actual = ":data", +) +</pre> + + + + <h3 id="alias_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="alias.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="alias.actual"> + <code>actual</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + The target this alias refers to. It does not need to be a rule, it can also be an input + file. + + </td> + </tr> + </tbody> + </table> + <h2 id="config_setting"> + config_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/config/ConfigRuleClasses.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">config_setting(<a href="#config_setting.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#config_setting.constraint_values">constraint_values</a>, <a href="#config_setting.define_values">define_values</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#config_setting.flag_values">flag_values</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#config_setting.values">values</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + + <p> + Matches an expected configuration state (expressed as build flags or platform constraints) for + the purpose of triggering configurable attributes. See <a href="/reference/be/functions.html#select">select</a> for + how to consume this rule and <a href="/reference/be/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 build that sets <code>--compilation_mode=opt</code> or + <code>-c opt</code> (either explicitly at the command line or implicitly from .bazelrc files): + </p> + + <pre class="code"> + config_setting( + name = "simple", + values = {"compilation_mode": "opt"} + ) + </pre> + + <p>The following matches any build that targets ARM and 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": "arm", + "define": "FOO=bar" + } + ) + </pre> + + <p>The following matches any build that sets + <a href="https://bazel.build/rules/config#user-defined-build-settings">user-defined flag</a> + <code>--//custom_flags:foo=1</code> (either explicitly at the command line or implicitly from + .bazelrc files): + </p> + + <pre class="code"> + config_setting( + name = "my_custom_flag_is_set", + flag_values = { "//custom_flags:foo": "1" }, + ) + </pre> + + <p>The following matches any build that targets a platform with 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 = "64bit_glibc_2_25", + constraint_values = [ + "@platforms//cpu:x86_64", + "//example:glibc_2_25", + ] + ) + </pre> + + In all these cases, it's possible for the configuration to change within the build, for example if + a target needs to be built for a different platform than its dep. This means that even when a + <code>config_setting</code> doesn't match the top-level command-line flags, it may still match + some build targets. + + <h4 id="config_setting_notes">Notes</h4> + <ul> + <li>See <a href="/reference/be/functions.html#select">select</a> for what happens when multiple + <code>config_setting</code>s match the current configuration state. + </li> + + <li>For flags that support shorthand forms (e.g. <code>--compilation_mode</code> vs. + <code>-c</code>), <code>values</code> definitions must use the full form. These automatically + match invocations using either form. + </li> + + <li> + If a flag takes multiple values (like <code>--copt=-Da --copt=-Db</code> or a list-typed + <a href="https://bazel.build/rules/config#user-defined-build-settings"> + Starlark flag</a>), <code>values = { "flag": "a" }</code> matches if <code>"a"</code> is + present <i>anywhere</i> in the actual list. + + <p> + <code>values = { "myflag": "a,b" }</code> works the same way: this matches + <code>--myflag=a --myflag=b</code>, <code>--myflag=a --myflag=b --myflag=c</code>, + <code>--myflag=a,b</code>, and <code>--myflag=c,b,a</code>. Exact semantics vary between + flags. For example, <code>--copt</code> doesn't support multiple values <i>in the same + instance</i>: <code>--copt=a,b</code> produces <code>["a,b"]</code> while <code>--copt=a + --copt=b</code> produces <code>["a", "b"]</code> (so <code>values = { "copt": "a,b" }</code> + matches the former but not the latter). But <code>--ios_multi_cpus</code> (for Apple rules) + <i>does</i>: <code>-ios_multi_cpus=a,b</code> and <code>ios_multi_cpus=a --ios_multi_cpus=b + </code> both produce <code>["a", "b"]</code>. Check flag definitions and test your + conditions carefully to verify exact expectations. + </p> + </li> + + <li>If you need to define conditions that aren't modeled by built-in build flags, use + <a href="https://bazel.build/rules/config#user-defined-build-settings"> + Starlark-defined flags</a>. You can also use <code>--define</code>, but this offers weaker + support and is not recommended. See + <a href="/reference/be/common-definitions#configurable-attributes">here</a> for more discussion. + </li> + + <li>Avoid repeating identical <code>config_setting</code> definitions in different packages. + Instead, reference a common <code>config_setting</code> that defined in a canonical package. + </li> + + <li><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 <code>config_setting</code> but at least one must + be set for any given <code>config_setting</code>. + </li> + </ul> + + + <h3 id="config_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="config_setting.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="config_setting.constraint_values"> + <code>constraint_values</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> + 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://bazel.build/docs/configurable-attributes#platforms"> + Configurable Build Attributes</a> for details. + + <p>If two <code>config_setting</code>s match in the same <code>select</code> and one has + all the same flags and <code>constraint_setting</code>s as the other plus additional ones, + the one with more settings is chosen. This is known as "specialization". For example, + a <code>config_setting</code> matching <code>x86</code> and <code>Linux</code> specializes + a <code>config_setting</code> matching <code>x86</code>. + + <p>If two <code>config_setting</code>s match and both have <code>constraint_value</code>s + not present in the other, this is an error. + + </td> + </tr> + <tr> + <td id="config_setting.define_values"> + <code>define_values</code> + </td> + <td> + <p>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> + The same as <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> but + specifically for the <code>--define</code> flag. + + <p><code>--define</code> is special because its syntax (<code>--define KEY=VAL</code>) + means <code>KEY=VAL</code> is a <i>value</i> from a Bazel flag perspective. + </p> + + <p>That means: + + <pre class="code"> + config_setting( + name = "a_and_b", + values = { + "define": "a=1", + "define": "b=2", + }) + </pre> + + <p>doesn't work because the same key (<code>define</code>) appears twice in the + dictionary. This attribute solves that problem: + + <pre class="code"> + config_setting( + name = "a_and_b", + define_values = { + "a": "1", + "b": "2", + }) + </pre> + + <p>correctly matches <code>bazel build //foo --define a=1 --define b=2</code>. + + <p><code>--define</code> can still appear in + <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> with normal flag syntax, + and can be mixed freely with this attribute as long as dictionary keys remain distinct. + + </td> + </tr> + <tr> + <td id="config_setting.flag_values"> + <code>flag_values</code> + </td> + <td> + <p>Dictionary: <a href="/concepts/labels">label</a> -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> + The same as <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> but + for <a href="https://bazel.build/rules/config#user-defined-build-settings"> + user-defined build flags</a>. + + <p>This is a distinct attribute because user-defined flags are referenced as labels while + built-in flags are referenced as arbitrary strings. + + + </td> + </tr> + <tr> + <td id="config_setting.values"> + <code>values</code> + </td> + <td> + <p>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> + The set of configuration values that match this rule (expressed as build flags) + + <p>This rule inherits the configuration of the configured target that + references it in a <code>select</code> statement. It is considered to + "match" a Bazel invocation if, for every entry in the dictionary, its + configuration matches the entry's expected value. For example + <code>values = {"compilation_mode": "opt"}</code> matches the invocations + <code>bazel build --compilation_mode=opt ...</code> and + <code>bazel build -c opt ...</code> on target-configured rules. + </p> + + <p>For convenience's sake, configuration values are specified as build flags (without + the preceding <code>"--"</code>). But keep in mind that the two are not the same. This + is because targets can be built in multiple configurations within the same + build. For example, an exec configuration's "cpu" matches the value of + <code>--host_cpu</code>, not <code>--cpu</code>. So different instances of the + same <code>config_setting</code> may match the same invocation differently + depending on the configuration of the rule using them. + </p> + + <p>If a flag is not explicitly set at the command line, its default value is used. + If a key appears multiple times in the dictionary, only the last instance is used. + If a key references a flag that can be set multiple times on the command line (e.g. + <code>bazel build --copt=foo --copt=bar --copt=baz ...</code>), a match occurs if + <i>any</i> of those settings match. + <p> + + </td> + </tr> + </tbody> + </table> + <h2 id="filegroup"> + filegroup + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/filegroup/FilegroupRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">filegroup(<a href="#filegroup.name">name</a>, <a href="#filegroup.srcs">srcs</a>, <a href="#filegroup.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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#typical.licenses">licenses</a>, <a href="#filegroup.output_group">output_group</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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> + Use <code>filegroup</code> to gather the outputs of a set of targets under a single + label. +</p> + +<p> + <code>filegroup</code> is not a substitute for listing targets on the command line or + in an attribute of another rule, because targets have many properties other than their + outputs, which are not collected in the same way. However, it's still useful in quite + a few cases, for example, in the <code>srcs</code> attribute of a genrule, or + the <code>data</code> attribute of a *_binary rule. +</p> + +<p> + Using <code>filegroup</code> is encouraged instead of referencing directories directly. + Directly referencing directories is discouraged because the build system does not have + full knowledge of all files below the directory, so it may not rebuild when these files change. + When combined with <a href="/reference/be/functions.html#glob">glob</a>, <code>filegroup</code> can ensure that all + files are explicitly known to the build system. +</p> + +<h4 id="filegroup_example">Examples</h4> + +<p> + To create a <code>filegroup</code> consisting of two source files, do +</p> +<pre class="code"> +filegroup( + name = "mygroup", + srcs = [ + "a_file.txt", + "//a/library:target", + "//a/binary:target", + ], +) +</pre> +<p> + Or, use a <code>glob</code> to fully crawl a testdata directory: +</p> +<pre class="code"> +filegroup( + name = "exported_testdata", + srcs = glob([ + "testdata/*.dat", + "testdata/logs/**/*.log", + ]), +) +</pre> +<p> + To make use of these definitions, reference the <code>filegroup</code> with a label from any rule: +</p> +<pre class="code"> +cc_library( + name = "my_library", + srcs = ["foo.cc"], + data = [ + "//my_package:exported_testdata", + "//my_package:mygroup", + ], +) +</pre> + + + + <h3 id="filegroup_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="filegroup.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="filegroup.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of targets that are members of the file group. + <p> + It is common to use the result of a <a href="/reference/be/functions.html#glob">glob</a> expression for + the value of the <code>srcs</code> attribute. + </p> + + </td> + </tr> + <tr> + <td id="filegroup.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this rule at runtime. + <p> + Targets named in the <code>data</code> attribute will be added to the + <code>runfiles</code> of this <code>filegroup</code> rule. When the + <code>filegroup</code> is referenced in the <code>data</code> attribute of + another rule its <code>runfiles</code> will be added to the <code>runfiles</code> + of the depending rule. See the <a href="/concepts/dependencies#data-dependencies">data dependencies</a> + section and <a href="/reference/be/common-definitions#common.data">general documentation of + <code>data</code></a> for more information about how to depend on and use data files. + </p> + + </td> + </tr> + <tr> + <td id="filegroup.output_group"> + <code>output_group</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The output group from which to gather artifacts from sources. If this attribute is + specified, artifacts from the specified output group of the dependencies will be exported + instead of the default output group. + <p>An "output group" is a category of output artifacts of a target, specified in that + rule's implementation. + </p> + + </td> + </tr> + </tbody> + </table> + <h2 id="genquery"> + genquery + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">genquery(<a href="#genquery.name">name</a>, <a href="common-definitions.html#typical.deps">deps</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#genquery.compressed_output">compressed_output</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#genquery.expression">expression</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#genquery.opts">opts</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#genquery.scope">scope</a>, <a href="#genquery.strict">strict</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> + <code>genquery()</code> runs a query specified in the + <a href="/reference/query">Bazel query language</a> and dumps the result + into a file. + </p> + <p> + In order to keep the build consistent, the query is allowed only to visit + the transitive closure of the targets specified in the <code>scope</code> + attribute. Queries violating this rule will fail during execution if + <code>strict</code> is unspecified or true (if <code>strict</code> is false, + the out of scope targets will simply be skipped with a warning). The + easiest way to make sure this does not happen is to mention the same labels + in the scope as in the query expression. + </p> + <p> + The only difference between the queries allowed here and on the command + line is that queries containing wildcard target specifications (e.g. + <code>//pkg:*</code> or <code>//pkg:all</code>) are not allowed here. + The reasons for this are two-fold: first, because <code>genquery</code> has + to specify a scope to prevent targets outside the transitive closure of the + query to influence its output; and, second, because <code>BUILD</code> files + do not support wildcard dependencies (e.g. <code>deps=["//a/..."]</code> + is not allowed). + </p> + <p> + The genquery's output is ordered lexicographically in order to enforce deterministic output, + with the exception of <code>--output=graph|minrank|maxrank</code> or when <code>somepath</code> + is used as the top-level function. + <p> + The name of the output file is the name of the rule. + </p> + +<h4 id="genquery_examples">Examples</h4> + <p> + This example writes the list of the labels in the transitive closure of the + specified target to a file. + </p> + +<pre class="code"> +genquery( + name = "kiwi-deps", + expression = "deps(//kiwi:kiwi_lib)", + scope = ["//kiwi:kiwi_lib"], +) +</pre> + + + + <h3 id="genquery_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="genquery.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="genquery.compressed_output"> + <code>compressed_output</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + If <code>True</code>, query output is written in GZIP file format. This setting can be used + to avoid spikes in Bazel's memory use when the query output is expected to be large. Bazel + already internally compresses query outputs greater than 2<sup>20</sup> bytes regardless of + the value of this setting, so setting this to <code>True</code> may not reduce retained + heap. However, it allows Bazel to skip <em>decompression</em> when writing the output file, + which can be memory-intensive. + + </td> + </tr> + <tr> + <td id="genquery.expression"> + <code>expression</code> + </td> + <td> + <p>String; required</p> + The query to be executed. In contrast to the command line and other places in BUILD files, + labels here are resolved relative to the root directory of the workspace. For example, the + label <code>:b</code> in this attribute in the file <code>a/BUILD</code> will refer to the + target <code>//:b</code>. + + </td> + </tr> + <tr> + <td id="genquery.opts"> + <code>opts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + The options that are passed to the query engine. These correspond to the command line + options that can be passed to <code>bazel query</code>. Some query options are not allowed + here: <code>--keep_going</code>, <code>--query_file</code>, <code>--universe_scope</code>, + <code>--order_results</code> and <code>--order_output</code>. Options not specified here + will have their default values just like on the command line of <code>bazel query</code>. + + </td> + </tr> + <tr> + <td id="genquery.scope"> + <code>scope</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; required</p> + The scope of the query. The query is not allowed to touch targets outside the transitive + closure of these targets. + + </td> + </tr> + <tr> + <td id="genquery.strict"> + <code>strict</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + If true, targets whose queries escape the transitive closure of their scopes will fail to + build. If false, Bazel will print a warning and skip whatever query path led it outside of + the scope, while completing the rest of the query. + + </td> + </tr> + </tbody> + </table> + <h2 id="genrule"> + genrule + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">genrule(<a href="#genrule.name">name</a>, <a href="#genrule.srcs">srcs</a>, <a href="#genrule.outs">outs</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#genrule.cmd">cmd</a>, <a href="#genrule.cmd_bash">cmd_bash</a>, <a href="#genrule.cmd_bat">cmd_bat</a>, <a href="#genrule.cmd_ps">cmd_ps</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#genrule.executable">executable</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#genrule.local">local</a>, <a href="#genrule.message">message</a>, <a href="#genrule.output_licenses">output_licenses</a>, <a href="#genrule.output_to_bindir">output_to_bindir</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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="#genrule.toolchains">toolchains</a>, <a href="#genrule.tools">tools</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + +<p>A <code>genrule</code> generates one or more files using a user-defined Bash command.</p> + +<p> + Genrules are generic build rules that you can use if there's no specific rule for the task. + For example, you could run a Bash one-liner. If however you need to compile C++ files, stick + to the existing <code>cc_*</code> rules, because all the heavy lifting has already been done + for you. +</p> +<p> + Note that genrule requires a shell to interpret the command argument. + It is also easy to reference arbitrary programs available on the PATH, however this makes the + command non-hermetic and may not be reproducible. + If you only need to run a single tool, consider using + <a href="https://github.com/bazelbuild/bazel-skylib/blob/main/docs/run_binary_doc.md">run_binary</a> + instead. +</p> +<p> + Like every other action, the action created by genrules should not assume anything about their + working directory; all Bazel guarantees is that their declared inputs will be available at the + path that <code>$(location)</code> returns for their label. For example, if the action is run in a + sandbox or remotely, the implementation of the sandbox or the remote execution will determine the + working directory. If run directly (using the <code>standalone</code> strategy), the working + directory will be the execution root, i.e. the result of <code>bazel info execution_root</code>. +</p> +<p> + Do not use a genrule for running tests. There are special dispensations for tests and test + results, including caching policies and environment variables. Tests generally need to be run + after the build is complete and on the target architecture, whereas genrules are executed during + the build and on the exec architecture (the two may be different). If you need a general purpose + testing rule, use <a href="/reference/be/shell.html#sh_test"><code>sh_test</code></a>. +</p> + +<h4>Cross-compilation Considerations</h4> + +<p> + <em>See <a href="/docs/user-manual#configurations">the user manual</a> for more info about + cross-compilation.</em> +</p> +<p> + While genrules run during a build, their outputs are often used after the build, for deployment or + testing. Consider the example of compiling C code for a microcontroller: the compiler accepts C + source files and generates code that runs on a microcontroller. The generated code obviously + cannot run on the CPU that was used for building it, but the C compiler (if compiled from source) + itself has to. +</p> +<p> + The build system uses the exec configuration to describe the machine(s) on which the build runs + and the target configuration to describe the machine(s) on which the output of the build is + supposed to run. It provides options to configure each of these and it segregates the + corresponding files into separate directories to avoid conflicts. +</p> +<p> + For genrules, the build system ensures that dependencies are built appropriately: + <code>srcs</code> are built (if necessary) for the <em>target</em> configuration, + <code>tools</code> are built for the <em>exec</em> configuration, and the output is considered to + be for the <em>target</em> configuration. It also provides <a href="/reference/be/make-variables"> + "Make" variables</a> that genrule commands can pass to the corresponding tools. +</p> +<p> + It is intentional that genrule defines no <code>deps</code> attribute: other built-in rules use + language-dependent meta information passed between the rules to automatically determine how to + handle dependent rules, but this level of automation is not possible for genrules. Genrules work + purely at the file and runfiles level. +</p> + +<h4>Special Cases</h4> + +<p> + <i>Exec-exec compilation</i>: in some cases, the build system needs to run genrules such that the + output can also be executed during the build. If for example a genrule builds some custom compiler + which is subsequently used by another genrule, the first one has to produce its output for the + exec configuration, because that's where the compiler will run in the other genrule. In this case, + the build system does the right thing automatically: it builds the <code>srcs</code> and + <code>outs</code> of the first genrule for the exec configuration instead of the target + configuration. See <a href="/docs/user-manual#configurations">the user manual</a> for more + info. +</p> +<p> + <i>JDK & C++ Tooling</i>: to use a tool from the JDK or the C++ compiler suite, the build system + provides a set of variables to use. See <a href="/reference/be/make-variables">"Make" variable</a> for + details. +</p> + +<h4>Genrule Environment</h4> + +<p> + The genrule command is executed by a Bash shell that is configured to fail when a command + or a pipeline fails, using <code>set -e -o pipefail</code>. +</p> +<p> + The build tool executes the Bash command in a sanitized process environment that + defines only core variables such as <code>PATH</code>, <code>PWD</code>, + <code>TMPDIR</code>, and a few others. + + To ensure that builds are reproducible, most variables defined in the user's shell + environment are not passed though to the genrule's command. However, Bazel (but not + Blaze) passes through the value of the user's <code>PATH</code> environment variable. + + Any change to the value of <code>PATH</code> will cause Bazel to re-execute the command + on the next build. + <!-- See https://github.com/bazelbuild/bazel/issues/1142 --> +</p> +<p> + A genrule command should not access the network except to connect processes that are + children of the command itself, though this is not currently enforced. +</p> +<p> + The build system automatically deletes any existing output files, but creates any necessary parent + directories before it runs a genrule. It also removes any output files in case of a failure. +</p> + +<h4>General Advice</h4> + +<ul> + <li>Do ensure that tools run by a genrule are deterministic and hermetic. They should not write + timestamps to their output, and they should use stable ordering for sets and maps, as well as + write only relative file paths to the output, no absolute paths. Not following this rule will + lead to unexpected build behavior (Bazel not rebuilding a genrule you thought it would) and + degrade cache performance.</li> + <li>Do use <code>$(location)</code> extensively, for outputs, tools and sources. Due to the + segregation of output files for different configurations, genrules cannot rely on hard-coded + and/or absolute paths.</li> + <li>Do write a common Starlark macro in case the same or very similar genrules are used in + multiple places. If the genrule is complex, consider implementing it in a script or as a + Starlark rule. This improves readability as well as testability.</li> + <li>Do make sure that the exit code correctly indicates success or failure of the genrule.</li> + <li>Do not write informational messages to stdout or stderr. While useful for debugging, this can + easily become noise; a successful genrule should be silent. On the other hand, a failing genrule + should emit good error messages.</li> + <li><code>$$</code> evaluates to a <code>$</code>, a literal dollar-sign, so in order to invoke a + shell command containing dollar-signs such as <code>ls $(dirname $x)</code>, one must escape it + thus: <code>ls $$(dirname $$x)</code>.</li> + <li>Avoid creating symlinks and directories. Bazel doesn't copy over the directory/symlink + structure created by genrules and its dependency checking of directories is unsound.</li> + <li>When referencing the genrule in other rules, you can use either the genrule's label or the + labels of individual output files. Sometimes the one approach is more readable, sometimes the + other: referencing outputs by name in a consuming rule's <code>srcs</code> will avoid + unintentionally picking up other outputs of the genrule, but can be tedious if the genrule + produces many outputs.</li> +</ul> + +<h4 id="genrule_examples">Examples</h4> + +<p> + This example generates <code>foo.h</code>. There are no sources, because the command doesn't take + any input. The "binary" run by the command is a perl script in the same package as the genrule. +</p> +<pre class="code"> +genrule( + name = "foo", + srcs = [], + outs = ["foo.h"], + cmd = "./$(location create_foo.pl) > \"$@\"", + tools = ["create_foo.pl"], +) +</pre> + +<p> + The following example shows how to use a <a href="/reference/be/general.html#filegroup"><code>filegroup</code> + </a> and the outputs of another <code>genrule</code>. Note that using <code>$(SRCS)</code> instead + of explicit <code>$(location)</code> directives would also work; this example uses the latter for + sake of demonstration. +</p> +<pre class="code"> +genrule( + name = "concat_all_files", + srcs = [ + "//some:files", # a filegroup with multiple files in it ==> $(location<b>s</b>) + "//other:gen", # a genrule with a single output ==> $(location) + ], + outs = ["concatenated.txt"], + cmd = "cat $(locations //some:files) $(location //other:gen) > $@", +) +</pre> + + + + <h3 id="genrule_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="genrule.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + <br/>You may refer to this rule by name in the + <code>srcs</code> or <code>deps</code> section of other <code>BUILD</code> + rules. If the rule generates source files, you should use the + <code>srcs</code> attribute. + + </td> + </tr> + <tr> + <td id="genrule.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of inputs for this rule, such as source files to process. + <p> + <em>This attributes is not suitable to list tools executed by the <code>cmd</code>; use + the <a href="/reference/be/general.html#genrule.tools"><code>tools</code></a> attribute for them instead. + </em> + </p> + <p> + The build system ensures these prerequisites are built before running the genrule + command; they are built using the same configuration as the original build request. The + names of the files of these prerequisites are available to the command as a + space-separated list in <code>$(SRCS)</code>; alternatively the path of an individual + <code>srcs</code> target <code>//x:y</code> can be obtained using <code>$(location + //x:y)</code>, or using <code>$<</code> provided it's the only entry in + <code>srcs</code>. + </p> + + </td> + </tr> + <tr> + <td id="genrule.outs"> + <code>outs</code> + </td> + <td> + <p>List of <a href="/concepts/build-ref#filename">filenames</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; required</p> + A list of files generated by this rule. + <p> + Output files must not cross package boundaries. + Output filenames are interpreted as relative to the package. + </p> + <p> + If the <code>executable</code> flag is set, <code>outs</code> must contain exactly one + label. + </p> + <p> + The genrule command is expected to create each output file at a predetermined location. + The location is available in <code>cmd</code> using <a + href="/reference/be/make-variables#predefined_genrule_variables">genrule-specific "Make" + variables</a> (<code>$@</code>, <code>$(OUTS)</code>, <code>$(@D)</code> or <code> + $(RULEDIR)</code>) or using <a href="/reference/be/make-variables#predefined_label_variables"> + <code>$(location)</code></a> substitution. + </p> + + </td> + </tr> + <tr> + <td id="genrule.cmd"> + <code>cmd</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The command to run. + Subject to <a href="/reference/be/make-variables#predefined_label_variables"><code>$(location) + </code></a> and <a href="/reference/be/make-variables">"Make" variable</a> substitution. + <ol> + <li> + First <a href="/reference/be/make-variables#predefined_label_variables"><code>$(location) + </code></a> substitution is applied, replacing all occurrences of <code>$(location <i> + label</i>)</code> and of <code>$(locations <i>label</i>)</code> (and similar + constructions using related variables <code>execpath</code>, <code>execpaths</code>, + <code>rootpath</code> and <code>rootpaths</code>). + </li> + <li> + Next, <a href="/reference/be/make-variables">"Make" variables</a> are expanded. Note that + predefined variables <code>$(JAVA)</code>, <code>$(JAVAC)</code> and + <code>$(JAVABASE)</code> expand under the <i>exec</i> configuration, so Java invocations + that run as part of a build step can correctly load shared libraries and other + dependencies. + </li> + <li> + Finally, the resulting command is executed using the Bash shell. If its exit code is + non-zero the command is considered to have failed. + </li> + </ol> + This is the fallback of <code>cmd_bash</code>, <code>cmd_ps</code> and <code>cmd_bat</code>, + if none of them are applicable. + </p> + <p> + If the command line length exceeds the platform limit (64K on Linux/macOS, 8K on Windows), + then genrule will write the command to a script and execute that script to work around. This + applies to all cmd attributes (<code>cmd</code>, <code>cmd_bash</code>, <code>cmd_ps</code>, + <code>cmd_bat</code>). + </p> + + </td> + </tr> + <tr> + <td id="genrule.cmd_bash"> + <code>cmd_bash</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The Bash command to run. + <p> This attribute has higher priority than <code>cmd</code>. The command is expanded and + runs in the exact same way as the <code>cmd</code> attribute. + </p> + + </td> + </tr> + <tr> + <td id="genrule.cmd_bat"> + <code>cmd_bat</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The Batch command to run on Windows. + <p> This attribute has higher priority than <code>cmd</code> and <code>cmd_bash</code>. + The command runs in the similar way as the <code>cmd</code> attribute, with the + following differences: + </p> + <ul> + <li> + This attribute only applies on Windows. + </li> + <li> + The command runs with <code>cmd.exe /c</code> with the following default arguments: + <ul> + <li> + <code>/S</code> - strip first and last quotes and execute everything else as is. + </li> + <li> + <code>/E:ON</code> - enable extended command set. + </li> + <li> + <code>/V:ON</code> - enable delayed variable expansion + </li> + <li> + <code>/D</code> - ignore AutoRun registry entries. + </li> + </ul> + </li> + <li> + After <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and + <a href="/reference/be/make-variables">"Make" variable</a> substitution, the paths will be + expanded to Windows style paths (with backslash). + </li> + </ul> + + </td> + </tr> + <tr> + <td id="genrule.cmd_ps"> + <code>cmd_ps</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The Powershell command to run on Windows. + <p> This attribute has higher priority than <code>cmd</code>, <code>cmd_bash</code> and + <code>cmd_bat</code>. The command runs in the similar way as the <code>cmd</code> + attribute, with the following differences: + </p> + <ul> + <li> + This attribute only applies on Windows. + </li> + <li> + The command runs with <code>powershell.exe /c</code>. + </li> + </ul> + <p> To make Powershell easier to use and less error-prone, we run the following + commands to set up the environment before executing Powershell command in genrule. + </p> + <ul> + <li> + <code>Set-ExecutionPolicy -Scope CurrentUser RemoteSigned</code> - allow running + unsigned scripts. + </li> + <li> + <code>$errorActionPreference='Stop'</code> - In case there are multiple commands + separated by <code>;</code>, the action exits immediately if a Powershell CmdLet fails, + but this does <strong>NOT</strong> work for external command. + </li> + <li> + <code>$PSDefaultParameterValues['*:Encoding'] = 'utf8'</code> - change the default + encoding from utf-16 to utf-8. + </li> + </ul> + + </td> + </tr> + <tr> + <td id="genrule.executable"> + <code>executable</code> + </td> + <td> + <p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> + Declare output to be executable. + <p> + Setting this flag to True means the output is an executable file and can be run using the + <code>run</code> command. The genrule must produce exactly one output in this case. + If this attribute is set, <code>run</code> will try executing the file regardless of + its content. + </p> + <p>Declaring data dependencies for the generated executable is not supported.</p> + + </td> + </tr> + <tr> + <td id="genrule.local"> + <code>local</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + <p> + If set to True, this option forces this <code>genrule</code> to run using the "local" + strategy, which means no remote execution, no sandboxing, no persistent workers. + </p> + <p> + This is equivalent to providing 'local' as a tag (<code>tags=["local"]</code>). + </p> + + </td> + </tr> + <tr> + <td id="genrule.message"> + <code>message</code> + </td> + <td> + <p>String; default is <code>""</code></p> + A progress message. + <p> + A progress message that will be printed as this build step is executed. By default, the + message is "Generating <i>output</i>" (or something equally bland) but you may provide a + more specific one. Use this attribute instead of <code>echo</code> or other print + statements in your <code>cmd</code> command, as this allows the build tool to control + whether such progress messages are printed or not. + </p> + + </td> + </tr> + <tr> + <td id="genrule.output_licenses"> + <code>output_licenses</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + See <a href="/reference/be/common-definitions#binary.output_licenses"><code>common attributes + </code></a> + + </td> + </tr> + <tr> + <td id="genrule.output_to_bindir"> + <code>output_to_bindir</code> + </td> + <td> + <p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> + <p> + If set to True, this option causes output files to be written into the <code>bin</code> + directory instead of the <code>genfiles</code> directory. + </p> + + </td> + </tr> + <tr> + <td id="genrule.toolchains"> + <code>toolchains</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> + <p> + The set of targets whose <a href="/reference/be/make-variables">Make variables</a> this genrule + is allowed to access, or the <a href="/docs/toolchains"><code>toolchain_type</code></a> + targets that this genrule will access. + </p> + + <p> + Toolchains accessed via <code>toolchain_type</code> must also provide a + <code>TemplateVariableInfo</code> provider, which the target can use to access toolchain + details. + </p> + + </td> + </tr> + <tr> + <td id="genrule.tools"> + <code>tools</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of <i>tool</i> dependencies for this rule. See the definition of + <a href="/concepts/build-ref#deps">dependencies</a> for more information. <br/> + <p> + The build system ensures these prerequisites are built before running the genrule command; + they are built using the <a href='/contribute/guide#configurations'><i>exec</i> + configuration</a>, since these tools are executed as part of the build. The path of an + individual <code>tools</code> target <code>//x:y</code> can be obtained using + <code>$(location //x:y)</code>. + </p> + <p> + Any <code>*_binary</code> or tool to be executed by <code>cmd</code> must appear in this + list, not in <code>srcs</code>, to ensure they are built in the correct configuration. + </p> + + </td> + </tr> + </tbody> + </table> + <h2 id="starlark_doc_extract"> + starlark_doc_extract + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/starlarkdocextract/StarlarkDocExtractRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">starlark_doc_extract(<a href="#starlark_doc_extract.name">name</a>, <a href="#starlark_doc_extract.deps">deps</a>, <a href="#starlark_doc_extract.src">src</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#starlark_doc_extract.allow_unused_doc_comments">allow_unused_doc_comments</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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.package_metadata">package_metadata</a>, <a href="#starlark_doc_extract.render_main_repo_name">render_main_repo_name</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#starlark_doc_extract.symbol_names">symbol_names</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><code>starlark_doc_extract()</code> extracts documentation for rules, functions (including +macros), aspects, and providers defined or re-exported in a given <code>.bzl</code> or +<code>.scl</code> file. The output of this rule is a <code>ModuleInfo</code> binary proto as defined +in +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto">stardoc_output.proto</a> +in the Bazel source tree. + +<h4 id="starlark_doc_extract_implicit_outputs">Implicit output targets</h4> + <ul> + <li><code><var>name</var>.binaryproto</code> (the default output): A + <code>ModuleInfo</code> binary proto.</li> + <li><code><var>name</var>.textproto</code> (only built if explicitly requested): the text + proto version of <code><var>name</var>.binaryproto</code>.</li> + </ul> + + +<p>Warning: the output format of this rule is not guaranteed to be stable. It is intended mainly for +internal use by <a href="https://github.com/bazelbuild/stardoc">Stardoc</a>. + + + + <h3 id="starlark_doc_extract_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="starlark_doc_extract.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="starlark_doc_extract.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of targets wrapping the Starlark files which are <code>load()</code>-ed by + <code>src</code>. These targets <em>should</em> under normal usage be + <a href="https://github.com/bazelbuild/bazel-skylib/blob/main/bzl_library.bzl"><code>bzl_library</code></a> + targets, but the <code>starlark_doc_extract</code> rule does not enforce that, and accepts + any target which provides Starlark files in its <code>DefaultInfo</code>. + + <p>Note that the wrapped Starlark files must be files in the source tree; Bazel cannot + <code>load()</code> generated files. + + </td> + </tr> + <tr> + <td id="starlark_doc_extract.src"> + <code>src</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; required</p> + A Starlark file from which to extract documentation. + + <p>Note that this must be a file in the source tree; Bazel cannot <code>load()</code> + generated files. + + </td> + </tr> + <tr> + <td id="starlark_doc_extract.allow_unused_doc_comments"> + <code>allow_unused_doc_comments</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + If true, allow and silently ignore doc comments (comments starting with <code>#:</code>) + which are not attached to any global variable, or which are attached to a variable whose + value's documentation should be provided in a different way (for example, in a docstring for + a function, or via <code>rule(doc = ...)</code> for a rule). + + </td> + </tr> + <tr> + <td id="starlark_doc_extract.render_main_repo_name"> + <code>render_main_repo_name</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + If true, render labels in the main repository in emitted documentation with a repo component + (in other words, <code>//foo:bar.bzl</code> will be emitted as + <code>@main_repo_name//foo:bar.bzl</code>). + <p>The name to use for the main repository is obtained from <code>module(name = ...)</code> + in the main repository's <code>MODULE.bazel</code> file (if Bzlmod is enabled), or from + <code>workspace(name = ...)</code> in the main repository's <code>WORKSPACE</code> file. + <p>This attribute should be set to <code>False</code> when generating documentation for + Starlark files which are intended to be used only within the same repository, and to + <code>True</code> when generating documentation for Starlark files which are intended to be + used from other repositories. + + </td> + </tr> + <tr> + <td id="starlark_doc_extract.symbol_names"> + <code>symbol_names</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + An optional list of qualified names of exported functions, rules, providers, or aspects (or + structs in which they are nested) for which to extract documentation. Here, a <em>qualified + name</em> means the name under which an entity is made available to a user of the module, + including any structs in which the entity is nested for namespacing. + + <p><code>starlark_doc_extract</code> emits documentation for an entity if and only if + <ol> + <li> + each component of the entity's qualified name is public (in other words, the first + character of each component of the qualified name is alphabetic, not <code>"_"</code>); + <em>and</em> + </li> + <li> + <ol> + <li> + <em>either</em> the <code>symbol_names</code> list is empty (which is the default + case), <em>or</em> + </li> + <li> + the entity's qualified name, or the qualified name of a struct in which the entity + is nested, is in the <code>symbol_names</code> list. + </li> + </ol> + </li> + </ol> + + </td> + </tr> + </tbody> + </table> + <h2 id="test_suite"> + test_suite + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">test_suite(<a href="#test_suite.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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#typical.licenses">licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#test_suite.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="#test_suite.tests">tests</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + +<p> +A <code>test_suite</code> defines a set of tests that are considered "useful" to humans. This +allows projects to define sets of tests, such as "tests you must run before checkin", "our +project's stress tests" or "all small tests." The <code>bazel test</code> command respects this sort +of organization: For an invocation like <code>bazel test //some/test:suite</code>, Bazel first +enumerates all test targets transitively included by the <code>//some/test:suite</code> target (we +call this "test_suite expansion"), then Bazel builds and tests those targets. +</p> + +<h4 id="test_suite_examples">Examples</h4> + +<p>A test suite to run all of the small tests in the current package.</p> +<pre class="code"> +test_suite( + name = "small_tests", + tags = ["small"], +) +</pre> + +<p>A test suite that runs a specified set of tests:</p> + +<pre class="code"> +test_suite( + name = "smoke_tests", + tests = [ + "system_unittest", + "public_api_unittest", + ], +) +</pre> + +<p>A test suite to run all tests in the current package which are not flaky.</p> +<pre class="code"> +test_suite( + name = "non_flaky_test", + tags = ["-flaky"], +) +</pre> + + + + <h3 id="test_suite_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="test_suite.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="test_suite.tags"> + <code>tags</code> + </td> + <td> + <p>List of strings; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> + List of text tags such as "small" or "database" or "-flaky". Tags may be any valid string. + <p> + Tags which begin with a "-" character are considered negative tags. The + preceding "-" character is not considered part of the tag, so a suite tag + of "-small" matches a test's "small" size. All other tags are considered + positive tags. + </p> + <p> + Optionally, to make positive tags more explicit, tags may also begin with the + "+" character, which will not be evaluated as part of the text of the tag. It + merely makes the positive and negative distinction easier to read. + </p> + <p> + Only test rules that match <b>all</b> of the positive tags and <b>none</b> of the negative + tags will be included in the test suite. Note that this does not mean that error checking + for dependencies on tests that are filtered out is skipped; the dependencies on skipped + tests still need to be legal (e.g. not blocked by visibility constraints). + </p> + <p> + The <code>manual</code> tag keyword is treated differently than the above by the + "test_suite expansion" performed by the <code>bazel test</code> command on invocations + involving wildcard + <a href="https://bazel.build/docs/build#specifying-build-targets">target patterns</a>. + There, <code>test_suite</code> targets tagged "manual" are filtered out (and thus not + expanded). This behavior is consistent with how <code>bazel build</code> and + <code>bazel test</code> handle wildcard target patterns in general. Note that this is + explicitly different from how <code>bazel query 'tests(E)'</code> behaves, as suites are + always expanded by the <code>tests</code> query function, regardless of the + <code>manual</code> tag. + </p> + <p> + Note that a test's <code>size</code> is considered a tag for the purpose of filtering. + </p> + <p> + If you need a <code>test_suite</code> that contains tests with mutually exclusive tags + (e.g. all small and medium tests), you'll have to create three <code>test_suite</code> + rules: one for all small tests, one for all medium tests, and one that includes the + previous two. + </p> + + </td> + </tr> + <tr> + <td id="test_suite.tests"> + <code>tests</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> + A list of test suites and test targets of any language. + <p> + Any <code>*_test</code> is accepted here, independent of the language. No + <code>*_binary</code> targets are accepted however, even if they happen to run a test. + Filtering by the specified <code>tags</code> is only done for tests listed directly in + this attribute. If this attribute contains <code>test_suite</code>s, the tests inside + those will not be filtered by this <code>test_suite</code> (they are considered to be + filtered already). + </p> + <p> + If the <code>tests</code> attribute is unspecified or empty, the rule will default to + including all test rules in the current BUILD file that are not tagged as + <code>manual</code>. These rules are still subject to <code>tag</code> filtering. + </p> + + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/java.mdx b/reference/be/java.mdx new file mode 100644 index 0000000..2c13db2 --- /dev/null +++ b/reference/be/java.mdx @@ -0,0 +1,2740 @@ +--- +title: 'java' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">Java Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% include "_buttons.html" %} + + + + +<h2>Rules</h2> +<ul> + <li> + <a href="#java_binary"> + java_binary </a> + </li> + <li> + <a href="#java_import"> + java_import </a> + </li> + <li> + <a href="#java_library"> + java_library </a> + </li> + <li> + <a href="#java_test"> + java_test </a> + </li> + <li> + <a href="#java_package_configuration"> + java_package_configuration </a> + </li> + <li> + <a href="#java_plugin"> + java_plugin </a> + </li> + <li> + <a href="#java_runtime"> + java_runtime </a> + </li> + <li> + <a href="#java_single_jar"> + java_single_jar </a> + </li> + <li> + <a href="#java_toolchain"> + java_toolchain </a> + </li> +</ul> + + <h2 id="java_binary"> + java_binary + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_binary.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_binary(<a href="#java_binary.name">name</a>, <a href="#java_binary.deps">deps</a>, <a href="#java_binary.srcs">srcs</a>, <a href="#java_binary.data">data</a>, <a href="#java_binary.resources">resources</a>, <a href="#java_binary.add_exports">add_exports</a>, <a href="#java_binary.add_opens">add_opens</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_binary.bootclasspath">bootclasspath</a>, <a href="#java_binary.classpath_resources">classpath_resources</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_binary.create_executable">create_executable</a>, <a href="#java_binary.deploy_env">deploy_env</a>, <a href="#java_binary.deploy_manifest_lines">deploy_manifest_lines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_binary.javacopts">javacopts</a>, <a href="#java_binary.jvm_flags">jvm_flags</a>, <a href="#java_binary.launcher">launcher</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_binary.main_class">main_class</a>, <a href="#java_binary.neverlink">neverlink</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_binary.plugins">plugins</a>, <a href="#java_binary.resource_strip_prefix">resource_strip_prefix</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_binary.runtime_deps">runtime_deps</a>, <a href="#java_binary.stamp">stamp</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.toolchains">toolchains</a>, <a href="#java_binary.use_launcher">use_launcher</a>, <a href="#java_binary.use_testrunner">use_testrunner</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> + Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. + The wrapper shell script uses a classpath that includes, among other things, a jar file for each + library on which the binary depends. When running the wrapper shell script, any nonempty + <code>JAVABIN</code> environment variable will take precedence over the version specified via + Bazel's <code>--java_runtime_version</code> flag. +</p> +<p> + The wrapper script accepts several unique flags. Refer to + <code>java_stub_template.txt</code> + for a list of configurable flags and environment variables accepted by the wrapper. +</p> + +<h4 id="java_binary_implicit_outputs">Implicit output targets</h4> +<ul> + <li><code><var>name</var>.jar</code>: A Java archive, containing the class files and other + resources corresponding to the binary's direct dependencies.</li> + <li><code><var>name</var>-src.jar</code>: An archive containing the sources ("source + jar").</li> + <li><code><var>name</var>_deploy.jar</code>: A Java archive suitable for deployment (only + built if explicitly requested). + <p> + Building the <code><<var>name</var>>_deploy.jar</code> target for your rule + creates a self-contained jar file with a manifest that allows it to be run with the + <code>java -jar</code> command or with the wrapper script's <code>--singlejar</code> + option. Using the wrapper script is preferred to <code>java -jar</code> because it + also passes the <a href="#java_binary-jvm_flags">JVM flags</a> and the options + to load native libraries. + </p> + <p> + The deploy jar contains all the classes that would be found by a classloader that + searched the classpath from the binary's wrapper script from beginning to end. It also + contains the native libraries needed for dependencies. These are automatically loaded + into the JVM at runtime. + </p> + <p>If your target specifies a <a href="#java_binary.launcher">launcher</a> + attribute, then instead of being a normal JAR file, the _deploy.jar will be a + native binary. This will contain the launcher plus any native (C++) dependencies of + your rule, all linked into a static binary. The actual jar file's bytes will be + appended to that native binary, creating a single binary blob containing both the + executable and the Java code. You can execute the resulting jar file directly + like you would execute any native binary.</p> + </li> + <li><code><var>name</var>_deploy-src.jar</code>: An archive containing the sources + collected from the transitive closure of the target. These will match the classes in the + <code>deploy.jar</code> except where jars have no matching source jar.</li> +</ul> + +<p> +It is good practice to use the name of the source file that is the main entry point of the +application (minus the extension). For example, if your entry point is called +<code>Main.java</code>, then your name could be <code>Main</code>. +</p> + +<p> + A <code>deps</code> attribute is not allowed in a <code>java_binary</code> rule without + <a href="#java_binary-srcs"><code>srcs</code></a>; such a rule requires a + <a href="#java_binary-main_class"><code>main_class</code></a> provided by + <a href="#java_binary-runtime_deps"><code>runtime_deps</code></a>. +</p> + +<p>The following code snippet illustrates a common mistake:</p> + +<pre class="code"> +<code class="lang-starlark"> +java_binary( + name = "DontDoThis", + srcs = [ + <var>...</var>, + <code class="deprecated">"GeneratedJavaFile.java"</code>, # a generated .java file + ], + deps = [<code class="deprecated">":generating_rule",</code>], # rule that generates that file +) +</code> +</pre> + +<p>Do this instead:</p> + +<pre class="code"> +<code class="lang-starlark"> +java_binary( + name = "DoThisInstead", + srcs = [ + <var>...</var>, + ":generating_rule", + ], +) +</code> +</pre> + + <h3 id="java_binary_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="java_binary.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_binary.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries to be linked in to the target. +See general comments about <code>deps</code> at +<a href="common-definitions.html#typical-attributes">Typical attributes defined by +most build rules</a>. + </td> + </tr> + <tr> + <td id="java_binary.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of source files that are processed to create the target. +This attribute is almost always required; see exceptions below. +<p> +Source files of type <code>.java</code> are compiled. In case of generated +<code>.java</code> files it is generally advisable to put the generating rule's name +here instead of the name of the file itself. This not only improves readability but +makes the rule more resilient to future changes: if the generating rule generates +different files in the future, you only need to fix one place: the <code>outs</code> of +the generating rule. You should not list the generating rule in <code>deps</code> +because it is a no-op. +</p> +<p> +Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if +you need to generate a set of <code>.java</code> files with a genrule.) +</p> +<p> +Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates +any of the files listed above, they will be used the same way as described for source +files. +</p> + +<p> +This argument is almost always required, except if a +<a href="#java_binary.main_class"><code>main_class</code></a> attribute specifies a +class on the runtime classpath or you specify the <code>runtime_deps</code> argument. +</p> + </td> + </tr> + <tr> + <td id="java_binary.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this library at runtime. +See general comments about <code>data</code> +at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. + </td> + </tr> + <tr> + <td id="java_binary.resources"> + <code>resources</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of data files to include in a Java jar. + +<p> +Resources may be source files or generated files. +</p> + +<p> +If resources are specified, they will be bundled in the jar along with the usual +<code>.class</code> files produced by compilation. The location of the resources inside +of the jar file is determined by the project structure. Bazel first looks for Maven's +<a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, +(a "src" directory followed by a "resources" directory grandchild). If that is not +found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for +example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the +path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, +however, the <code>resource_strip_prefix</code> attribute can be used to specify a +specific alternative directory for resource files. + </td> + </tr> + <tr> + <td id="java_binary.add_exports"> + <code>add_exports</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to access the given <code>module</code> or <code>package</code>. +<p> +This corresponds to the javac and JVM --add-exports= flags. + </td> + </tr> + <tr> + <td id="java_binary.add_opens"> + <code>add_opens</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to reflectively access the given <code>module</code> or +<code>package</code>. +<p> +This corresponds to the javac and JVM --add-opens= flags. + </td> + </tr> + <tr> + <td id="java_binary.bootclasspath"> + <code>bootclasspath</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Restricted API, do not use! + </td> + </tr> + <tr> + <td id="java_binary.classpath_resources"> + <code>classpath_resources</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + <em class="harmful">DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)</em> +<p> +A list of resources that must be located at the root of the java tree. This attribute's +only purpose is to support third-party libraries that require that their resources be +found on the classpath as exactly <code>"myconfig.xml"</code>. It is only allowed on +binaries and not libraries, due to the danger of namespace conflicts. +</p> + </td> + </tr> + <tr> + <td id="java_binary.create_executable"> + <code>create_executable</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + Deprecated, use <code>java_single_jar</code> instead. + </td> + </tr> + <tr> + <td id="java_binary.deploy_env"> + <code>deploy_env</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of other <code>java_binary</code> targets which represent the deployment +environment for this binary. +Set this attribute when building a plugin which will be loaded by another +<code>java_binary</code>.<br/> Setting this attribute excludes all dependencies from +the runtime classpath (and the deploy jar) of this binary that are shared between this +binary and the targets specified in <code>deploy_env</code>. + </td> + </tr> + <tr> + <td id="java_binary.deploy_manifest_lines"> + <code>deploy_manifest_lines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + A list of lines to add to the <code>META-INF/manifest.mf</code> file generated for the +<code>*_deploy.jar</code> target. The contents of this attribute are <em>not</em> subject +to <a href="make-variables.html">"Make variable"</a> substitution. + </td> + </tr> + <tr> + <td id="java_binary.javacopts"> + <code>javacopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra compiler options for this binary. +Subject to <a href="make-variables.html">"Make variable"</a> substitution and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. +<p>These compiler options are passed to javac after the global compiler options.</p> + </td> + </tr> + <tr> + <td id="java_binary.jvm_flags"> + <code>jvm_flags</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + A list of flags to embed in the wrapper script generated for running this binary. +Subject to <a href="/reference/be/make-variables#location">$(location)</a> and +<a href="make-variables.html">"Make variable"</a> substitution, and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. + +<p>The wrapper script for a Java binary includes a CLASSPATH definition +(to find all the dependent jars) and invokes the right Java interpreter. +The command line generated by the wrapper script includes the name of +the main class followed by a <code>"$@"</code> so you can pass along other +arguments after the classname. However, arguments intended for parsing +by the JVM must be specified <i>before</i> the classname on the command +line. The contents of <code>jvm_flags</code> are added to the wrapper +script before the classname is listed.</p> + +<p>Note that this attribute has <em>no effect</em> on <code>*_deploy.jar</code> +outputs.</p> + </td> + </tr> + <tr> + <td id="java_binary.launcher"> + <code>launcher</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Specify a binary that will be used to run your Java program instead of the +normal <code>bin/java</code> program included with the JDK. +The target must be a <code>cc_binary</code>. Any <code>cc_binary</code> that +implements the +<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html"> +Java Invocation API</a> can be specified as a value for this attribute. + +<p>By default, Bazel will use the normal JDK launcher (bin/java or java.exe).</p> + +<p>The related <a href="/docs/user-manual#flag--java_launcher"><code> +--java_launcher</code></a> Bazel flag affects only those +<code>java_binary</code> and <code>java_test</code> targets that have +<i>not</i> specified a <code>launcher</code> attribute.</p> + +<p>Note that your native (C++, SWIG, JNI) dependencies will be built differently +depending on whether you are using the JDK launcher or another launcher:</p> + +<ul> +<li>If you are using the normal JDK launcher (the default), native dependencies are +built as a shared library named <code>{name}_nativedeps.so</code>, where +<code>{name}</code> is the <code>name</code> attribute of this java_binary rule. +Unused code is <em>not</em> removed by the linker in this configuration.</li> + +<li>If you are using any other launcher, native (C++) dependencies are statically +linked into a binary named <code>{name}_nativedeps</code>, where <code>{name}</code> +is the <code>name</code> attribute of this java_binary rule. In this case, +the linker will remove any code it thinks is unused from the resulting binary, +which means any C++ code accessed only via JNI may not be linked in unless +that <code>cc_library</code> target specifies <code>alwayslink = True</code>.</li> +</ul> + +<p>When using any launcher other than the default JDK launcher, the format +of the <code>*_deploy.jar</code> output changes. See the main +<a href="#java_binary">java_binary</a> docs for details.</p> + </td> + </tr> + <tr> + <td id="java_binary.main_class"> + <code>main_class</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Name of class with <code>main()</code> method to use as entry point. +If a rule uses this option, it does not need a <code>srcs=[...]</code> list. +Thus, with this attribute one can make an executable from a Java library that already +contains one or more <code>main()</code> methods. +<p> +The value of this attribute is a class name, not a source file. The class must be +available at runtime: it may be compiled by this rule (from <code>srcs</code>) or +provided by direct or transitive dependencies (through <code>runtime_deps</code> or +<code>deps</code>). If the class is unavailable, the binary will fail at runtime; there +is no build-time check. +</p> + </td> + </tr> + <tr> + <td id="java_binary.neverlink"> + <code>neverlink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + + </td> + </tr> + <tr> + <td id="java_binary.plugins"> + <code>plugins</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Java compiler plugins to run at compile-time. +Every <code>java_plugin</code> specified in this attribute will be run whenever this rule +is built. A library may also inherit plugins from dependencies that use +<code><a href="#java_library.exported_plugins">exported_plugins</a></code>. Resources +generated by the plugin will be included in the resulting jar of this rule. + </td> + </tr> + <tr> + <td id="java_binary.resource_strip_prefix"> + <code>resource_strip_prefix</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The path prefix to strip from Java resources. +<p> +If specified, this path prefix is stripped from every file in the <code>resources</code> +attribute. It is an error for a resource file not to be under this directory. If not +specified (the default), the path of resource file is determined according to the same +logic as the Java package of source files. For example, a source file at +<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>. +</p> + </td> + </tr> + <tr> + <td id="java_binary.runtime_deps"> + <code>runtime_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Libraries to make available to the final binary or test at runtime only. +Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike +them, not on the compile-time classpath. Dependencies needed only at runtime should be +listed here. Dependency-analysis tools should ignore targets that appear in both +<code>runtime_deps</code> and <code>deps</code>. + </td> + </tr> + <tr> + <td id="java_binary.stamp"> + <code>stamp</code> + </td> + <td> + <p>Integer; default is <code>-1</code></p> + Whether to encode build information into the binary. Possible values: +<ul> +<li> + <code>stamp = 1</code>: Always stamp the build information into the binary, even in + <a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This + setting should be avoided</b>, since it potentially kills remote caching for the + binary and any downstream actions that depend on it. +</li> +<li> + <code>stamp = 0</code>: Always replace build information by constant values. This + gives good build result caching. +</li> +<li> + <code>stamp = -1</code>: Embedding of build information is controlled by the + <a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag. +</li> +</ul> +<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> + </td> + </tr> + <tr> + <td id="java_binary.use_launcher"> + <code>use_launcher</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + Whether the binary should use a custom launcher. + +<p>If this attribute is set to false, the +<a href="/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related +<a href="/docs/user-manual#flag--java_launcher"><code>--java_launcher</code></a> flag +will be ignored for this target. + </td> + </tr> + <tr> + <td id="java_binary.use_testrunner"> + <code>use_testrunner</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Use the test runner (by default +<code>com.google.testing.junit.runner.BazelTestRunner</code>) class as the +main entry point for a Java program, and provide the test class +to the test runner as a value of <code>bazel.test_suite</code> +system property. + +<br/> +You can use this to override the default +behavior, which is to use test runner for +<code>java_test</code> rules, +and not use it for <code>java_binary</code> rules. It is unlikely +you will want to do this. One use is for <code>AllTest</code> +rules that are invoked by another rule (to set up a database +before running the tests, for example). The <code>AllTest</code> +rule must be declared as a <code>java_binary</code>, but should +still use the test runner as its main entry point. + +The name of a test runner class can be overridden with <code>main_class</code> attribute. + </td> + </tr> + </tbody> + </table> + <h2 id="java_import"> + java_import + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_import.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_import(<a href="#java_import.name">name</a>, <a href="#java_import.deps">deps</a>, <a href="#java_import.data">data</a>, <a href="#java_import.add_exports">add_exports</a>, <a href="#java_import.add_opens">add_opens</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_import.constraints">constraints</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#java_import.exports">exports</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#java_import.jars">jars</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_import.neverlink">neverlink</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_import.proguard_specs">proguard_specs</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_import.runtime_deps">runtime_deps</a>, <a href="#java_import.srcjar">srcjar</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> + This rule allows the use of precompiled <code>.jar</code> files as + libraries for <code><a href="#java_library">java_library</a></code> and + <code>java_binary</code> rules. +</p> + +<h4 id="java_import_examples">Examples</h4> + +<pre class="code"> +<code class="lang-starlark"> + java_import( + name = "maven_model", + jars = [ + "maven_model/maven-aether-provider-3.2.3.jar", + "maven_model/maven-model-3.2.3.jar", + "maven_model/maven-model-builder-3.2.3.jar", + ], + ) +</code> +</pre> + + <h3 id="java_import_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="java_import.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_import.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries to be linked in to the target. +See <a href="/reference/be/java.html#java_library.deps">java_library.deps</a>. + </td> + </tr> + <tr> + <td id="java_import.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this rule at runtime. + </td> + </tr> + <tr> + <td id="java_import.add_exports"> + <code>add_exports</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to access the given <code>module</code> or <code>package</code>. +<p> +This corresponds to the javac and JVM --add-exports= flags. + </td> + </tr> + <tr> + <td id="java_import.add_opens"> + <code>add_opens</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to reflectively access the given <code>module</code> or +<code>package</code>. +<p> +This corresponds to the javac and JVM --add-opens= flags. + </td> + </tr> + <tr> + <td id="java_import.constraints"> + <code>constraints</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra constraints imposed on this rule as a Java library. + </td> + </tr> + <tr> + <td id="java_import.exports"> + <code>exports</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Targets to make available to users of this rule. +See <a href="/reference/be/java.html#java_library.exports">java_library.exports</a>. + </td> + </tr> + <tr> + <td id="java_import.jars"> + <code>jars</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; required</p> + The list of JAR files provided to Java targets that depend on this target. + </td> + </tr> + <tr> + <td id="java_import.neverlink"> + <code>neverlink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Only use this library for compilation and not at runtime. +Useful if the library will be provided by the runtime environment +during execution. Examples of libraries like this are IDE APIs +for IDE plug-ins or <code>tools.jar</code> for anything running on +a standard JDK. + </td> + </tr> + <tr> + <td id="java_import.proguard_specs"> + <code>proguard_specs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Files to be used as Proguard specification. +These will describe the set of specifications to be used by Proguard. If specified, +they will be added to any <code>android_binary</code> target depending on this library. + +The files included here must only have idempotent rules, namely -dontnote, -dontwarn, +assumenosideeffects, and rules that start with -keep. Other options can only appear in +<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges. + </td> + </tr> + <tr> + <td id="java_import.runtime_deps"> + <code>runtime_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Libraries to make available to the final binary or test at runtime only. +See <a href="/reference/be/java.html#java_library.runtime_deps">java_library.runtime_deps</a>. + </td> + </tr> + <tr> + <td id="java_import.srcjar"> + <code>srcjar</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + A JAR file that contains source code for the compiled JAR files. + </td> + </tr> + </tbody> + </table> + <h2 id="java_library"> + java_library + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_library(<a href="#java_library.name">name</a>, <a href="#java_library.deps">deps</a>, <a href="#java_library.srcs">srcs</a>, <a href="#java_library.data">data</a>, <a href="#java_library.resources">resources</a>, <a href="#java_library.add_exports">add_exports</a>, <a href="#java_library.add_opens">add_opens</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_library.bootclasspath">bootclasspath</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#java_library.exported_plugins">exported_plugins</a>, <a href="#java_library.exports">exports</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#java_library.javabuilder_jvm_flags">javabuilder_jvm_flags</a>, <a href="#java_library.javacopts">javacopts</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_library.neverlink">neverlink</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_library.plugins">plugins</a>, <a href="#java_library.proguard_specs">proguard_specs</a>, <a href="#java_library.resource_strip_prefix">resource_strip_prefix</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_library.runtime_deps">runtime_deps</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>This rule compiles and links sources into a <code>.jar</code> file.</p> + +<h4>Implicit outputs</h4> +<ul> + <li><code>lib<var>name</var>.jar</code>: A Java archive containing the class files.</li> + <li><code>lib<var>name</var>-src.jar</code>: An archive containing the sources ("source + jar").</li> +</ul> + + <h3 id="java_library_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="java_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of libraries to link into this library. +See general comments about <code>deps</code> at +<a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. +<p> + The jars built by <code>java_library</code> rules listed in <code>deps</code> will be on + the compile-time classpath of this rule. Furthermore the transitive closure of their + <code>deps</code>, <code>runtime_deps</code> and <code>exports</code> will be on the + runtime classpath. +</p> +<p> + By contrast, targets in the <code>data</code> attribute are included in the runfiles but + on neither the compile-time nor runtime classpath. +</p> + </td> + </tr> + <tr> + <td id="java_library.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of source files that are processed to create the target. +This attribute is almost always required; see exceptions below. +<p> +Source files of type <code>.java</code> are compiled. In case of generated +<code>.java</code> files it is generally advisable to put the generating rule's name +here instead of the name of the file itself. This not only improves readability but +makes the rule more resilient to future changes: if the generating rule generates +different files in the future, you only need to fix one place: the <code>outs</code> of +the generating rule. You should not list the generating rule in <code>deps</code> +because it is a no-op. +</p> +<p> +Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if +you need to generate a set of <code>.java</code> files with a genrule.) +</p> +<p> +Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates +any of the files listed above, they will be used the same way as described for source +files. +</p> +<p> +Source files of type <code>.properties</code> are treated as resources. +</p> + +<p>All other files are ignored, as long as there is at least one file of a +file type described above. Otherwise an error is raised.</p> + +<p> +This argument is almost always required, except if you specify the <code>runtime_deps</code> argument. +</p> + </td> + </tr> + <tr> + <td id="java_library.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this library at runtime. +See general comments about <code>data</code> at +<a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. +<p> + When building a <code>java_library</code>, Bazel doesn't put these files anywhere; if the + <code>data</code> files are generated files then Bazel generates them. When building a + test that depends on this <code>java_library</code> Bazel copies or links the + <code>data</code> files into the runfiles area. +</p> + </td> + </tr> + <tr> + <td id="java_library.resources"> + <code>resources</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of data files to include in a Java jar. +<p> +Resources may be source files or generated files. +</p> + +<p> +If resources are specified, they will be bundled in the jar along with the usual +<code>.class</code> files produced by compilation. The location of the resources inside +of the jar file is determined by the project structure. Bazel first looks for Maven's +<a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, +(a "src" directory followed by a "resources" directory grandchild). If that is not +found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for +example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the +path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, +however, the <code>resource_strip_prefix</code> attribute can be used to specify a +specific alternative directory for resource files. + </td> + </tr> + <tr> + <td id="java_library.add_exports"> + <code>add_exports</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to access the given <code>module</code> or <code>package</code>. +<p> +This corresponds to the javac and JVM --add-exports= flags. + </td> + </tr> + <tr> + <td id="java_library.add_opens"> + <code>add_opens</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to reflectively access the given <code>module</code> or +<code>package</code>. +<p> +This corresponds to the javac and JVM --add-opens= flags. + </td> + </tr> + <tr> + <td id="java_library.bootclasspath"> + <code>bootclasspath</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Restricted API, do not use! + </td> + </tr> + <tr> + <td id="java_library.exported_plugins"> + <code>exported_plugins</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of <code><a href="#/reference/be/java.html#java_plugin">java_plugin</a></code>s (e.g. annotation +processors) to export to libraries that directly depend on this library. +<p> + The specified list of <code>java_plugin</code>s will be applied to any library which + directly depends on this library, just as if that library had explicitly declared these + labels in <code><a href="/reference/be/java.html#java_library.plugins">plugins</a></code>. +</p> + </td> + </tr> + <tr> + <td id="java_library.exports"> + <code>exports</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Exported libraries. +<p> + Listing rules here will make them available to parent rules, as if the parents explicitly + depended on these rules. This is not true for regular (non-exported) <code>deps</code>. +</p> +<p> + Summary: a rule <i>X</i> can access the code in <i>Y</i> if there exists a dependency + path between them that begins with a <code>deps</code> edge followed by zero or more + <code>exports</code> edges. Let's see some examples to illustrate this. +</p> +<p> + Assume <i>A</i> depends on <i>B</i> and <i>B</i> depends on <i>C</i>. In this case + C is a <em>transitive</em> dependency of A, so changing C's sources and rebuilding A will + correctly rebuild everything. However A will not be able to use classes in C. To allow + that, either A has to declare C in its <code>deps</code>, or B can make it easier for A + (and anything that may depend on A) by declaring C in its (B's) <code>exports</code> + attribute. +</p> +<p> + The closure of exported libraries is available to all direct parent rules. Take a slightly + different example: A depends on B, B depends on C and D, and also exports C but not D. + Now A has access to C but not to D. Now, if C and D exported some libraries, C' and D' + respectively, A could only access C' but not D'. +</p> +<p> + Important: an exported rule is not a regular dependency. Sticking to the previous example, + if B exports C and wants to also use C, it has to also list it in its own + <code>deps</code>. +</p> + </td> + </tr> + <tr> + <td id="java_library.javabuilder_jvm_flags"> + <code>javabuilder_jvm_flags</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Restricted API, do not use! + </td> + </tr> + <tr> + <td id="java_library.javacopts"> + <code>javacopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra compiler options for this library. +Subject to <a href="make-variables.html">"Make variable"</a> substitution and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. +<p>These compiler options are passed to javac after the global compiler options.</p> + </td> + </tr> + <tr> + <td id="java_library.neverlink"> + <code>neverlink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Whether this library should only be used for compilation and not at runtime. +Useful if the library will be provided by the runtime environment during execution. Examples +of such libraries are the IDE APIs for IDE plug-ins or <code>tools.jar</code> for anything +running on a standard JDK. +<p> + Note that <code>neverlink = True</code> does not prevent the compiler from inlining material + from this library into compilation targets that depend on it, as permitted by the Java + Language Specification (e.g., <code>static final</code> constants of <code>String</code> + or of primitive types). The preferred use case is therefore when the runtime library is + identical to the compilation library. +</p> +<p> + If the runtime library differs from the compilation library then you must ensure that it + differs only in places that the JLS forbids compilers to inline (and that must hold for + all future versions of the JLS). +</p> + </td> + </tr> + <tr> + <td id="java_library.plugins"> + <code>plugins</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Java compiler plugins to run at compile-time. +Every <code>java_plugin</code> specified in this attribute will be run whenever this rule +is built. A library may also inherit plugins from dependencies that use +<code><a href="#java_library.exported_plugins">exported_plugins</a></code>. Resources +generated by the plugin will be included in the resulting jar of this rule. + </td> + </tr> + <tr> + <td id="java_library.proguard_specs"> + <code>proguard_specs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Files to be used as Proguard specification. +These will describe the set of specifications to be used by Proguard. If specified, +they will be added to any <code>android_binary</code> target depending on this library. + +The files included here must only have idempotent rules, namely -dontnote, -dontwarn, +assumenosideeffects, and rules that start with -keep. Other options can only appear in +<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges. + </td> + </tr> + <tr> + <td id="java_library.resource_strip_prefix"> + <code>resource_strip_prefix</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The path prefix to strip from Java resources. +<p> +If specified, this path prefix is stripped from every file in the <code>resources</code> +attribute. It is an error for a resource file not to be under this directory. If not +specified (the default), the path of resource file is determined according to the same +logic as the Java package of source files. For example, a source file at +<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>. +</p> + </td> + </tr> + <tr> + <td id="java_library.runtime_deps"> + <code>runtime_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Libraries to make available to the final binary or test at runtime only. +Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike +them, not on the compile-time classpath. Dependencies needed only at runtime should be +listed here. Dependency-analysis tools should ignore targets that appear in both +<code>runtime_deps</code> and <code>deps</code>. + </td> + </tr> + </tbody> + </table> + <h2 id="java_test"> + java_test + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_test.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_test(<a href="#java_test.name">name</a>, <a href="#java_test.deps">deps</a>, <a href="#java_test.srcs">srcs</a>, <a href="#java_test.data">data</a>, <a href="#java_test.resources">resources</a>, <a href="#java_test.add_exports">add_exports</a>, <a href="#java_test.add_opens">add_opens</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_test.bootclasspath">bootclasspath</a>, <a href="#java_test.classpath_resources">classpath_resources</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_test.create_executable">create_executable</a>, <a href="#java_test.deploy_manifest_lines">deploy_manifest_lines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#test.flaky">flaky</a>, <a href="#java_test.javacopts">javacopts</a>, <a href="#java_test.jvm_flags">jvm_flags</a>, <a href="#java_test.launcher">launcher</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#java_test.main_class">main_class</a>, <a href="#java_test.neverlink">neverlink</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_test.plugins">plugins</a>, <a href="#java_test.resource_strip_prefix">resource_strip_prefix</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_test.runtime_deps">runtime_deps</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#java_test.stamp">stamp</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="#java_test.test_class">test_class</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="#java_test.use_launcher">use_launcher</a>, <a href="#java_test.use_testrunner">use_testrunner</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> +A <code>java_test()</code> rule compiles a Java test. A test is a binary wrapper around your +test code. The test runner's main method is invoked instead of the main class being compiled. +</p> + +<h4 id="java_test_implicit_outputs">Implicit output targets</h4> +<ul> + <li><code><var>name</var>.jar</code>: A Java archive.</li> + <li><code><var>name</var>_deploy.jar</code>: A Java archive suitable + for deployment. (Only built if explicitly requested.) See the description of the + <code><var>name</var>_deploy.jar</code> output from + <a href="#java_binary">java_binary</a> for more details.</li> +</ul> + +<p> +See the section on <code>java_binary()</code> arguments. This rule also +supports all <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">attributes common +to all test rules (*_test)</a>. +</p> + +<h4 id="java_test_examples">Examples</h4> + +<pre class="code"> +<code class="lang-starlark"> + +java_library( + name = "tests", + srcs = glob(["*.java"]), + deps = [ + "//java/com/foo/base:testResources", + "//java/com/foo/testing/util", + ], +) + +java_test( + name = "AllTests", + size = "small", + runtime_deps = [ + ":tests", + "//util/mysql", + ], +) +</code> +</pre> + + <h3 id="java_test_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="java_test.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_test.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries to be linked in to the target. +See general comments about <code>deps</code> at +<a href="common-definitions.html#typical-attributes">Typical attributes defined by +most build rules</a>. + </td> + </tr> + <tr> + <td id="java_test.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of source files that are processed to create the target. +This attribute is almost always required; see exceptions below. +<p> +Source files of type <code>.java</code> are compiled. In case of generated +<code>.java</code> files it is generally advisable to put the generating rule's name +here instead of the name of the file itself. This not only improves readability but +makes the rule more resilient to future changes: if the generating rule generates +different files in the future, you only need to fix one place: the <code>outs</code> of +the generating rule. You should not list the generating rule in <code>deps</code> +because it is a no-op. +</p> +<p> +Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if +you need to generate a set of <code>.java</code> files with a genrule.) +</p> +<p> +Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates +any of the files listed above, they will be used the same way as described for source +files. +</p> + +<p> +This argument is almost always required, except if a +<a href="#java_binary.main_class"><code>main_class</code></a> attribute specifies a +class on the runtime classpath or you specify the <code>runtime_deps</code> argument. +</p> + </td> + </tr> + <tr> + <td id="java_test.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this library at runtime. +See general comments about <code>data</code> +at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. + </td> + </tr> + <tr> + <td id="java_test.resources"> + <code>resources</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of data files to include in a Java jar. + +<p> +Resources may be source files or generated files. +</p> + +<p> +If resources are specified, they will be bundled in the jar along with the usual +<code>.class</code> files produced by compilation. The location of the resources inside +of the jar file is determined by the project structure. Bazel first looks for Maven's +<a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, +(a "src" directory followed by a "resources" directory grandchild). If that is not +found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for +example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the +path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, +however, the <code>resource_strip_prefix</code> attribute can be used to specify a +specific alternative directory for resource files. + </td> + </tr> + <tr> + <td id="java_test.add_exports"> + <code>add_exports</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to access the given <code>module</code> or <code>package</code>. +<p> +This corresponds to the javac and JVM --add-exports= flags. + </td> + </tr> + <tr> + <td id="java_test.add_opens"> + <code>add_opens</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to reflectively access the given <code>module</code> or +<code>package</code>. +<p> +This corresponds to the javac and JVM --add-opens= flags. + </td> + </tr> + <tr> + <td id="java_test.bootclasspath"> + <code>bootclasspath</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Restricted API, do not use! + </td> + </tr> + <tr> + <td id="java_test.classpath_resources"> + <code>classpath_resources</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + <em class="harmful">DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)</em> +<p> +A list of resources that must be located at the root of the java tree. This attribute's +only purpose is to support third-party libraries that require that their resources be +found on the classpath as exactly <code>"myconfig.xml"</code>. It is only allowed on +binaries and not libraries, due to the danger of namespace conflicts. +</p> + </td> + </tr> + <tr> + <td id="java_test.create_executable"> + <code>create_executable</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + Deprecated, use <code>java_single_jar</code> instead. + </td> + </tr> + <tr> + <td id="java_test.deploy_manifest_lines"> + <code>deploy_manifest_lines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + A list of lines to add to the <code>META-INF/manifest.mf</code> file generated for the +<code>*_deploy.jar</code> target. The contents of this attribute are <em>not</em> subject +to <a href="make-variables.html">"Make variable"</a> substitution. + </td> + </tr> + <tr> + <td id="java_test.javacopts"> + <code>javacopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra compiler options for this binary. +Subject to <a href="make-variables.html">"Make variable"</a> substitution and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. +<p>These compiler options are passed to javac after the global compiler options.</p> + </td> + </tr> + <tr> + <td id="java_test.jvm_flags"> + <code>jvm_flags</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + A list of flags to embed in the wrapper script generated for running this binary. +Subject to <a href="/reference/be/make-variables#location">$(location)</a> and +<a href="make-variables.html">"Make variable"</a> substitution, and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. + +<p>The wrapper script for a Java binary includes a CLASSPATH definition +(to find all the dependent jars) and invokes the right Java interpreter. +The command line generated by the wrapper script includes the name of +the main class followed by a <code>"$@"</code> so you can pass along other +arguments after the classname. However, arguments intended for parsing +by the JVM must be specified <i>before</i> the classname on the command +line. The contents of <code>jvm_flags</code> are added to the wrapper +script before the classname is listed.</p> + +<p>Note that this attribute has <em>no effect</em> on <code>*_deploy.jar</code> +outputs.</p> + </td> + </tr> + <tr> + <td id="java_test.launcher"> + <code>launcher</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Specify a binary that will be used to run your Java program instead of the +normal <code>bin/java</code> program included with the JDK. +The target must be a <code>cc_binary</code>. Any <code>cc_binary</code> that +implements the +<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html"> +Java Invocation API</a> can be specified as a value for this attribute. + +<p>By default, Bazel will use the normal JDK launcher (bin/java or java.exe).</p> + +<p>The related <a href="/docs/user-manual#flag--java_launcher"><code> +--java_launcher</code></a> Bazel flag affects only those +<code>java_binary</code> and <code>java_test</code> targets that have +<i>not</i> specified a <code>launcher</code> attribute.</p> + +<p>Note that your native (C++, SWIG, JNI) dependencies will be built differently +depending on whether you are using the JDK launcher or another launcher:</p> + +<ul> +<li>If you are using the normal JDK launcher (the default), native dependencies are +built as a shared library named <code>{name}_nativedeps.so</code>, where +<code>{name}</code> is the <code>name</code> attribute of this java_binary rule. +Unused code is <em>not</em> removed by the linker in this configuration.</li> + +<li>If you are using any other launcher, native (C++) dependencies are statically +linked into a binary named <code>{name}_nativedeps</code>, where <code>{name}</code> +is the <code>name</code> attribute of this java_binary rule. In this case, +the linker will remove any code it thinks is unused from the resulting binary, +which means any C++ code accessed only via JNI may not be linked in unless +that <code>cc_library</code> target specifies <code>alwayslink = True</code>.</li> +</ul> + +<p>When using any launcher other than the default JDK launcher, the format +of the <code>*_deploy.jar</code> output changes. See the main +<a href="#java_binary">java_binary</a> docs for details.</p> + </td> + </tr> + <tr> + <td id="java_test.main_class"> + <code>main_class</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Name of class with <code>main()</code> method to use as entry point. +If a rule uses this option, it does not need a <code>srcs=[...]</code> list. +Thus, with this attribute one can make an executable from a Java library that already +contains one or more <code>main()</code> methods. +<p> +The value of this attribute is a class name, not a source file. The class must be +available at runtime: it may be compiled by this rule (from <code>srcs</code>) or +provided by direct or transitive dependencies (through <code>runtime_deps</code> or +<code>deps</code>). If the class is unavailable, the binary will fail at runtime; there +is no build-time check. +</p> + </td> + </tr> + <tr> + <td id="java_test.neverlink"> + <code>neverlink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + + </td> + </tr> + <tr> + <td id="java_test.plugins"> + <code>plugins</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Java compiler plugins to run at compile-time. +Every <code>java_plugin</code> specified in this attribute will be run whenever this rule +is built. A library may also inherit plugins from dependencies that use +<code><a href="#java_library.exported_plugins">exported_plugins</a></code>. Resources +generated by the plugin will be included in the resulting jar of this rule. + </td> + </tr> + <tr> + <td id="java_test.resource_strip_prefix"> + <code>resource_strip_prefix</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The path prefix to strip from Java resources. +<p> +If specified, this path prefix is stripped from every file in the <code>resources</code> +attribute. It is an error for a resource file not to be under this directory. If not +specified (the default), the path of resource file is determined according to the same +logic as the Java package of source files. For example, a source file at +<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>. +</p> + </td> + </tr> + <tr> + <td id="java_test.runtime_deps"> + <code>runtime_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Libraries to make available to the final binary or test at runtime only. +Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike +them, not on the compile-time classpath. Dependencies needed only at runtime should be +listed here. Dependency-analysis tools should ignore targets that appear in both +<code>runtime_deps</code> and <code>deps</code>. + </td> + </tr> + <tr> + <td id="java_test.stamp"> + <code>stamp</code> + </td> + <td> + <p>Integer; default is <code>0</code></p> + Whether to encode build information into the binary. Possible values: +<ul> +<li> + <code>stamp = 1</code>: Always stamp the build information into the binary, even in + <a href="https://bazel.build/docs/user-manual#stamp"><code>--nostamp</code></a> builds. <b>This + setting should be avoided</b>, since it potentially kills remote caching for the + binary and any downstream actions that depend on it. +</li> +<li> + <code>stamp = 0</code>: Always replace build information by constant values. This + gives good build result caching. +</li> +<li> + <code>stamp = -1</code>: Embedding of build information is controlled by the + <a href="https://bazel.build/docs/user-manual#stamp"><code>--[no]stamp</code></a> flag. +</li> +</ul> +<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> + </td> + </tr> + <tr> + <td id="java_test.test_class"> + <code>test_class</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The Java class to be loaded by the test runner.<br/> +<p> + By default, if this argument is not defined then the legacy mode is used and the + test arguments are used instead. Set the <code>--nolegacy_bazel_java_test</code> flag + to not fallback on the first argument. +</p> +<p> + This attribute specifies the name of a Java class to be run by + this test. It is rare to need to set this. If this argument is omitted, + it will be inferred using the target's <code>name</code> and its + source-root-relative path. If the test is located outside a known + source root, Bazel will report an error if <code>test_class</code> + is unset. +</p> +<p> + For JUnit3, the test class needs to either be a subclass of + <code>junit.framework.TestCase</code> or it needs to have a public + static <code>suite()</code> method that returns a + <code>junit.framework.Test</code> (or a subclass of <code>Test</code>). +</p> +<p> + This attribute allows several <code>java_test</code> rules to + share the same <code>Test</code> + (<code>TestCase</code>, <code>TestSuite</code>, ...). Typically + additional information is passed to it + (e.g. via <code>jvm_flags=['-Dkey=value']</code>) so that its + behavior differs in each case, such as running a different + subset of the tests. This attribute also enables the use of + Java tests outside the <code>javatests</code> tree. +</p> + </td> + </tr> + <tr> + <td id="java_test.use_launcher"> + <code>use_launcher</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + Whether the binary should use a custom launcher. + +<p>If this attribute is set to false, the +<a href="/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related +<a href="/docs/user-manual#flag--java_launcher"><code>--java_launcher</code></a> flag +will be ignored for this target. + </td> + </tr> + <tr> + <td id="java_test.use_testrunner"> + <code>use_testrunner</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + Use the test runner (by default +<code>com.google.testing.junit.runner.BazelTestRunner</code>) class as the +main entry point for a Java program, and provide the test class +to the test runner as a value of <code>bazel.test_suite</code> +system property. + +<br/> +You can use this to override the default +behavior, which is to use test runner for +<code>java_test</code> rules, +and not use it for <code>java_binary</code> rules. It is unlikely +you will want to do this. One use is for <code>AllTest</code> +rules that are invoked by another rule (to set up a database +before running the tests, for example). The <code>AllTest</code> +rule must be declared as a <code>java_binary</code>, but should +still use the test runner as its main entry point. + +The name of a test runner class can be overridden with <code>main_class</code> attribute. + </td> + </tr> + </tbody> + </table> + <h2 id="java_package_configuration"> + java_package_configuration + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_package_configuration.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_package_configuration(<a href="#java_package_configuration.name">name</a>, <a href="#java_package_configuration.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_package_configuration.javacopts">javacopts</a>, <a href="#java_package_configuration.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_package_configuration.packages">packages</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_package_configuration.system">system</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> +Configuration to apply to a set of packages. +Configurations can be added to +<code><a href="/reference/be/java.html#java_toolchain.javacopts">java_toolchain.javacopts</a></code>s. +</p> + +<h4 id="java_package_configuration_example">Example:</h4> + +<pre class="code"> +<code class="lang-starlark"> + +java_package_configuration( + name = "my_configuration", + packages = [":my_packages"], + javacopts = ["-Werror"], +) + +package_group( + name = "my_packages", + packages = [ + "//com/my/project/...", + "-//com/my/project/testing/...", + ], +) + +java_toolchain( + ..., + package_configuration = [ + ":my_configuration", + ] +) + +</code> +</pre> + + <h3 id="java_package_configuration_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="java_package_configuration.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_package_configuration.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this configuration at runtime. + </td> + </tr> + <tr> + <td id="java_package_configuration.javacopts"> + <code>javacopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Java compiler flags. + </td> + </tr> + <tr> + <td id="java_package_configuration.output_licenses"> + <code>output_licenses</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="java_package_configuration.packages"> + <code>packages</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The set of <code><a href="/reference/be/functions.html#package_group">package_group</a></code>s +the configuration should be applied to. + </td> + </tr> + <tr> + <td id="java_package_configuration.system"> + <code>system</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Corresponds to javac's --system flag. + </td> + </tr> + </tbody> + </table> + <h2 id="java_plugin"> + java_plugin + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_plugin.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_plugin(<a href="#java_plugin.name">name</a>, <a href="#java_plugin.deps">deps</a>, <a href="#java_plugin.srcs">srcs</a>, <a href="#java_plugin.data">data</a>, <a href="#java_plugin.resources">resources</a>, <a href="#java_plugin.add_exports">add_exports</a>, <a href="#java_plugin.add_opens">add_opens</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_plugin.bootclasspath">bootclasspath</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_plugin.generates_api">generates_api</a>, <a href="#java_plugin.javabuilder_jvm_flags">javabuilder_jvm_flags</a>, <a href="#java_plugin.javacopts">javacopts</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_plugin.neverlink">neverlink</a>, <a href="#java_plugin.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_plugin.plugins">plugins</a>, <a href="#java_plugin.processor_class">processor_class</a>, <a href="#java_plugin.proguard_specs">proguard_specs</a>, <a href="#java_plugin.resource_strip_prefix">resource_strip_prefix</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> + <code>java_plugin</code> defines plugins for the Java compiler run by Bazel. The + only supported kind of plugins are annotation processors. A <code>java_library</code> or + <code>java_binary</code> rule can run plugins by depending on them via the <code>plugins</code> + attribute. A <code>java_library</code> can also automatically export plugins to libraries that + directly depend on it using + <code><a href="#java_library-exported_plugins">exported_plugins</a></code>. +</p> + +<h4 id="java_plugin_implicit_outputs">Implicit output targets</h4> + <ul> + <li><code><var>libname</var>.jar</code>: A Java archive.</li> + </ul> + +<p>Arguments are a subset of (and with identical semantics to) those of +<a href="/reference/be/java.html#java_library">java_library()</a>, +except for the addition of the <code>processor_class</code> and +<code>generates_api</code> arguments.</p> + + <h3 id="java_plugin_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="java_plugin.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_plugin.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of libraries to link into this library. +See general comments about <code>deps</code> at +<a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. +<p> + The jars built by <code>java_library</code> rules listed in <code>deps</code> will be on + the compile-time classpath of this rule. Furthermore the transitive closure of their + <code>deps</code>, <code>runtime_deps</code> and <code>exports</code> will be on the + runtime classpath. +</p> +<p> + By contrast, targets in the <code>data</code> attribute are included in the runfiles but + on neither the compile-time nor runtime classpath. +</p> + </td> + </tr> + <tr> + <td id="java_plugin.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of source files that are processed to create the target. +This attribute is almost always required; see exceptions below. +<p> +Source files of type <code>.java</code> are compiled. In case of generated +<code>.java</code> files it is generally advisable to put the generating rule's name +here instead of the name of the file itself. This not only improves readability but +makes the rule more resilient to future changes: if the generating rule generates +different files in the future, you only need to fix one place: the <code>outs</code> of +the generating rule. You should not list the generating rule in <code>deps</code> +because it is a no-op. +</p> +<p> +Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if +you need to generate a set of <code>.java</code> files with a genrule.) +</p> +<p> +Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates +any of the files listed above, they will be used the same way as described for source +files. +</p> +<p> +Source files of type <code>.properties</code> are treated as resources. +</p> + +<p>All other files are ignored, as long as there is at least one file of a +file type described above. Otherwise an error is raised.</p> + +<p> +This argument is almost always required, except if you specify the <code>runtime_deps</code> argument. +</p> + </td> + </tr> + <tr> + <td id="java_plugin.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files needed by this library at runtime. +See general comments about <code>data</code> at +<a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>. +<p> + When building a <code>java_library</code>, Bazel doesn't put these files anywhere; if the + <code>data</code> files are generated files then Bazel generates them. When building a + test that depends on this <code>java_library</code> Bazel copies or links the + <code>data</code> files into the runfiles area. +</p> + </td> + </tr> + <tr> + <td id="java_plugin.resources"> + <code>resources</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of data files to include in a Java jar. +<p> +Resources may be source files or generated files. +</p> + +<p> +If resources are specified, they will be bundled in the jar along with the usual +<code>.class</code> files produced by compilation. The location of the resources inside +of the jar file is determined by the project structure. Bazel first looks for Maven's +<a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, +(a "src" directory followed by a "resources" directory grandchild). If that is not +found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for +example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the +path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, +however, the <code>resource_strip_prefix</code> attribute can be used to specify a +specific alternative directory for resource files. + </td> + </tr> + <tr> + <td id="java_plugin.add_exports"> + <code>add_exports</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to access the given <code>module</code> or <code>package</code>. +<p> +This corresponds to the javac and JVM --add-exports= flags. + </td> + </tr> + <tr> + <td id="java_plugin.add_opens"> + <code>add_opens</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Allow this library to reflectively access the given <code>module</code> or +<code>package</code>. +<p> +This corresponds to the javac and JVM --add-opens= flags. + </td> + </tr> + <tr> + <td id="java_plugin.bootclasspath"> + <code>bootclasspath</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Restricted API, do not use! + </td> + </tr> + <tr> + <td id="java_plugin.generates_api"> + <code>generates_api</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + This attribute marks annotation processors that generate API code. +<p>If a rule uses an API-generating annotation processor, other rules +depending on it can refer to the generated code only if their +compilation actions are scheduled after the generating rule. This +attribute instructs Bazel to introduce scheduling constraints when +--java_header_compilation is enabled. +<p><em class="harmful">WARNING: This attribute affects build +performance, use it only if necessary.</em></p> + </td> + </tr> + <tr> + <td id="java_plugin.javabuilder_jvm_flags"> + <code>javabuilder_jvm_flags</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Restricted API, do not use! + </td> + </tr> + <tr> + <td id="java_plugin.javacopts"> + <code>javacopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra compiler options for this library. +Subject to <a href="make-variables.html">"Make variable"</a> substitution and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. +<p>These compiler options are passed to javac after the global compiler options.</p> + </td> + </tr> + <tr> + <td id="java_plugin.neverlink"> + <code>neverlink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Whether this library should only be used for compilation and not at runtime. +Useful if the library will be provided by the runtime environment during execution. Examples +of such libraries are the IDE APIs for IDE plug-ins or <code>tools.jar</code> for anything +running on a standard JDK. +<p> + Note that <code>neverlink = True</code> does not prevent the compiler from inlining material + from this library into compilation targets that depend on it, as permitted by the Java + Language Specification (e.g., <code>static final</code> constants of <code>String</code> + or of primitive types). The preferred use case is therefore when the runtime library is + identical to the compilation library. +</p> +<p> + If the runtime library differs from the compilation library then you must ensure that it + differs only in places that the JLS forbids compilers to inline (and that must hold for + all future versions of the JLS). +</p> + </td> + </tr> + <tr> + <td id="java_plugin.output_licenses"> + <code>output_licenses</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="java_plugin.plugins"> + <code>plugins</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Java compiler plugins to run at compile-time. +Every <code>java_plugin</code> specified in this attribute will be run whenever this rule +is built. A library may also inherit plugins from dependencies that use +<code><a href="#java_library.exported_plugins">exported_plugins</a></code>. Resources +generated by the plugin will be included in the resulting jar of this rule. + </td> + </tr> + <tr> + <td id="java_plugin.processor_class"> + <code>processor_class</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The processor class is the fully qualified type of the class that the Java compiler should +use as entry point to the annotation processor. If not specified, this rule will not +contribute an annotation processor to the Java compiler's annotation processing, but its +runtime classpath will still be included on the compiler's annotation processor path. (This +is primarily intended for use by +<a href="https://errorprone.info/docs/plugins">Error Prone plugins</a>, which are loaded +from the annotation processor path using +<a href="https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html"> +java.util.ServiceLoader</a>.) + </td> + </tr> + <tr> + <td id="java_plugin.proguard_specs"> + <code>proguard_specs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Files to be used as Proguard specification. +These will describe the set of specifications to be used by Proguard. If specified, +they will be added to any <code>android_binary</code> target depending on this library. + +The files included here must only have idempotent rules, namely -dontnote, -dontwarn, +assumenosideeffects, and rules that start with -keep. Other options can only appear in +<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges. + </td> + </tr> + <tr> + <td id="java_plugin.resource_strip_prefix"> + <code>resource_strip_prefix</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The path prefix to strip from Java resources. +<p> +If specified, this path prefix is stripped from every file in the <code>resources</code> +attribute. It is an error for a resource file not to be under this directory. If not +specified (the default), the path of resource file is determined according to the same +logic as the Java package of source files. For example, a source file at +<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>. +</p> + </td> + </tr> + </tbody> + </table> + <h2 id="java_runtime"> + java_runtime + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_runtime.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_runtime(<a href="#java_runtime.name">name</a>, <a href="#java_runtime.srcs">srcs</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_runtime.default_cds">default_cds</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_runtime.hermetic_srcs">hermetic_srcs</a>, <a href="#java_runtime.hermetic_static_libs">hermetic_static_libs</a>, <a href="#java_runtime.java">java</a>, <a href="#java_runtime.java_home">java_home</a>, <a href="#java_runtime.lib_ct_sym">lib_ct_sym</a>, <a href="#java_runtime.lib_modules">lib_modules</a>, <a href="#java_runtime.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="#java_runtime.version">version</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> +Specifies the configuration for a Java runtime. +</p> + +<h4 id="java_runtime_example">Example:</h4> + +<pre class="code"> +<code class="lang-starlark"> + +java_runtime( + name = "jdk-9-ea+153", + srcs = glob(["jdk9-ea+153/**"]), + java_home = "jdk9-ea+153", +) + +</code> +</pre> + + <h3 id="java_runtime_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="java_runtime.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_runtime.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + All files in the runtime. + </td> + </tr> + <tr> + <td id="java_runtime.default_cds"> + <code>default_cds</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Default CDS archive for hermetic <code>java_runtime</code>. When hermetic +is enabled for a <code>java_binary</code> target the <code>java_runtime</code> +default CDS is packaged in the hermetic deploy JAR. + </td> + </tr> + <tr> + <td id="java_runtime.hermetic_srcs"> + <code>hermetic_srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Files in the runtime needed for hermetic deployments. + </td> + </tr> + <tr> + <td id="java_runtime.hermetic_static_libs"> + <code>hermetic_static_libs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The libraries that are statically linked with the launcher for hermetic deployments + </td> + </tr> + <tr> + <td id="java_runtime.java"> + <code>java</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + The path to the java executable. + </td> + </tr> + <tr> + <td id="java_runtime.java_home"> + <code>java_home</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The path to the root of the runtime. +Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. +If this path is absolute, the rule denotes a non-hermetic Java runtime with a well-known +path. In that case, the <code>srcs</code> and <code>java</code> attributes must be empty. + </td> + </tr> + <tr> + <td id="java_runtime.lib_ct_sym"> + <code>lib_ct_sym</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + The lib/ct.sym file needed for compilation with <code>--release</code>. If not specified and +there is exactly one file in <code>srcs</code> whose path ends with +<code>/lib/ct.sym</code>, that file is used. + </td> + </tr> + <tr> + <td id="java_runtime.lib_modules"> + <code>lib_modules</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + The lib/modules file needed for hermetic deployments. + </td> + </tr> + <tr> + <td id="java_runtime.output_licenses"> + <code>output_licenses</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="java_runtime.version"> + <code>version</code> + </td> + <td> + <p>Integer; default is <code>0</code></p> + The feature version of the Java runtime. I.e., the integer returned by +<code>Runtime.version().feature()</code>. + </td> + </tr> + </tbody> + </table> + <h2 id="java_single_jar"> + java_single_jar + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/java_single_jar.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_single_jar(<a href="#java_single_jar.name">name</a>, <a href="#java_single_jar.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_single_jar.compress">compress</a>, <a href="#java_single_jar.deploy_env">deploy_env</a>, <a href="#java_single_jar.deploy_manifest_lines">deploy_manifest_lines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#java_single_jar.exclude_build_data">exclude_build_data</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_single_jar.multi_release">multi_release</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + Collects Java dependencies and jar files into a single jar + +`java_single_jar` collects Java dependencies and jar files into a single jar. +This is similar to java_binary with everything related to executables disabled, +and provides an alternative to the java_binary "deploy jar hack". + +## Example + +```skylark +load("//tools/build_defs/java_single_jar:java_single_jar.bzl", "java_single_jar") + +java_single_jar( + name = "my_single_jar", + deps = [ + "//java/com/google/foo", + "//java/com/google/bar", + ], +) +``` + +Outputs: + {name}.jar: A single jar containing all of the inputs. + + <h3 id="java_single_jar_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="java_single_jar.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_single_jar.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The Java targets (including java_import and java_library) to collect +transitive dependencies from. Runtime dependencies are collected via +deps, exports, and runtime_deps. Resources are also collected. +Native cc_library or java_wrap_cc dependencies are not. + </td> + </tr> + <tr> + <td id="java_single_jar.compress"> + <code>compress</code> + </td> + <td> + <p>String; default is <code>"preserve"</code></p> + Whether to always deflate ("yes"), always store ("no"), or pass +through unmodified ("preserve"). The default is "preserve", and is the +most efficient option -- no extra work is done to inflate or deflate. + </td> + </tr> + <tr> + <td id="java_single_jar.deploy_env"> + <code>deploy_env</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + A list of `java_binary` or `java_single_jar` targets which represent +the deployment environment for this binary. + +Set this attribute when building a plugin which will be loaded by another +`java_binary`. + +`deploy_env` dependencies are excluded from the jar built by this rule. + </td> + </tr> + <tr> + <td id="java_single_jar.deploy_manifest_lines"> + <code>deploy_manifest_lines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + A list of lines to add to the <code>META-INF/manifest.mf</code> file. + </td> + </tr> + <tr> + <td id="java_single_jar.exclude_build_data"> + <code>exclude_build_data</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + Whether to omit the build-data.properties file generated +by default. + </td> + </tr> + <tr> + <td id="java_single_jar.multi_release"> + <code>multi_release</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + Whether to enable Multi-Release output jars. + </td> + </tr> + </tbody> + </table> + <h2 id="java_toolchain"> + java_toolchain + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_toolchain.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_toolchain(<a href="#java_toolchain.name">name</a>, <a href="#java_toolchain.android_lint_data">android_lint_data</a>, <a href="#java_toolchain.android_lint_jvm_opts">android_lint_jvm_opts</a>, <a href="#java_toolchain.android_lint_opts">android_lint_opts</a>, <a href="#java_toolchain.android_lint_package_configuration">android_lint_package_configuration</a>, <a href="#java_toolchain.android_lint_runner">android_lint_runner</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_toolchain.bootclasspath">bootclasspath</a>, <a href="#java_toolchain.compatible_javacopts">compatible_javacopts</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#java_toolchain.deps_checker">deps_checker</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_toolchain.forcibly_disable_header_compilation">forcibly_disable_header_compilation</a>, <a href="#java_toolchain.genclass">genclass</a>, <a href="#java_toolchain.header_compiler">header_compiler</a>, <a href="#java_toolchain.header_compiler_builtin_processors">header_compiler_builtin_processors</a>, <a href="#java_toolchain.header_compiler_direct">header_compiler_direct</a>, <a href="#java_toolchain.ijar">ijar</a>, <a href="#java_toolchain.jacocorunner">jacocorunner</a>, <a href="#java_toolchain.java_runtime">java_runtime</a>, <a href="#java_toolchain.javabuilder">javabuilder</a>, <a href="#java_toolchain.javabuilder_data">javabuilder_data</a>, <a href="#java_toolchain.javabuilder_jvm_opts">javabuilder_jvm_opts</a>, <a href="#java_toolchain.javac_supports_multiplex_workers">javac_supports_multiplex_workers</a>, <a href="#java_toolchain.javac_supports_worker_cancellation">javac_supports_worker_cancellation</a>, <a href="#java_toolchain.javac_supports_worker_multiplex_sandboxing">javac_supports_worker_multiplex_sandboxing</a>, <a href="#java_toolchain.javac_supports_workers">javac_supports_workers</a>, <a href="#java_toolchain.javacopts">javacopts</a>, <a href="#java_toolchain.jspecify_implicit_deps">jspecify_implicit_deps</a>, <a href="#java_toolchain.jspecify_javacopts">jspecify_javacopts</a>, <a href="#java_toolchain.jspecify_packages">jspecify_packages</a>, <a href="#java_toolchain.jspecify_processor">jspecify_processor</a>, <a href="#java_toolchain.jspecify_processor_class">jspecify_processor_class</a>, <a href="#java_toolchain.jspecify_stubs">jspecify_stubs</a>, <a href="#java_toolchain.jvm_opts">jvm_opts</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_toolchain.misc">misc</a>, <a href="#java_toolchain.oneversion">oneversion</a>, <a href="#java_toolchain.oneversion_allowlist">oneversion_allowlist</a>, <a href="#java_toolchain.oneversion_allowlist_for_tests">oneversion_allowlist_for_tests</a>, <a href="#java_toolchain.oneversion_whitelist">oneversion_whitelist</a>, <a href="#java_toolchain.package_configuration">package_configuration</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_toolchain.proguard_allowlister">proguard_allowlister</a>, <a href="#java_toolchain.reduced_classpath_incompatible_processors">reduced_classpath_incompatible_processors</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_toolchain.singlejar">singlejar</a>, <a href="#java_toolchain.source_version">source_version</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="#java_toolchain.target_version">target_version</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#java_toolchain.timezone_data">timezone_data</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="#java_toolchain.tools">tools</a>, <a href="#java_toolchain.turbine_data">turbine_data</a>, <a href="#java_toolchain.turbine_jvm_opts">turbine_jvm_opts</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#java_toolchain.xlint">xlint</a>)</pre> + + <p> +Specifies the configuration for the Java compiler. Which toolchain to be used can be changed through +the --java_toolchain argument. Normally you should not write those kind of rules unless you want to +tune your Java compiler. +</p> + +<h4>Examples</h4> + +<p>A simple example would be: +</p> + +<pre class="code"> +<code class="lang-starlark"> + +java_toolchain( + name = "toolchain", + source_version = "7", + target_version = "7", + bootclasspath = ["//tools/jdk:bootclasspath"], + xlint = [ "classfile", "divzero", "empty", "options", "path" ], + javacopts = [ "-g" ], + javabuilder = ":JavaBuilder_deploy.jar", +) +</code> +</pre> + + <h3 id="java_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="java_toolchain.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_toolchain.android_lint_data"> + <code>android_lint_data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Labels of tools available for label-expansion in android_lint_jvm_opts. + </td> + </tr> + <tr> + <td id="java_toolchain.android_lint_jvm_opts"> + <code>android_lint_jvm_opts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + The list of arguments for the JVM when invoking Android Lint. + </td> + </tr> + <tr> + <td id="java_toolchain.android_lint_opts"> + <code>android_lint_opts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + The list of Android Lint arguments. + </td> + </tr> + <tr> + <td id="java_toolchain.android_lint_package_configuration"> + <code>android_lint_package_configuration</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Android Lint Configuration that should be applied to the specified package groups. + </td> + </tr> + <tr> + <td id="java_toolchain.android_lint_runner"> + <code>android_lint_runner</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the Android Lint runner, if any. + </td> + </tr> + <tr> + <td id="java_toolchain.bootclasspath"> + <code>bootclasspath</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. + </td> + </tr> + <tr> + <td id="java_toolchain.compatible_javacopts"> + <code>compatible_javacopts</code> + </td> + <td> + <p>null; default is <code>{}</code></p> + Internal API, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.deps_checker"> + <code>deps_checker</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the ImportDepsChecker deploy jar. + </td> + </tr> + <tr> + <td id="java_toolchain.forcibly_disable_header_compilation"> + <code>forcibly_disable_header_compilation</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Overrides --java_header_compilation to disable header compilation on platforms that do not +support it, e.g. JDK 7 Bazel. + </td> + </tr> + <tr> + <td id="java_toolchain.genclass"> + <code>genclass</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the GenClass deploy jar. + </td> + </tr> + <tr> + <td id="java_toolchain.header_compiler"> + <code>header_compiler</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the header compiler. Required if --java_header_compilation is enabled. + </td> + </tr> + <tr> + <td id="java_toolchain.header_compiler_builtin_processors"> + <code>header_compiler_builtin_processors</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Internal API, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.header_compiler_direct"> + <code>header_compiler_direct</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Optional label of the header compiler to use for direct classpath actions that do not +include any API-generating annotation processors. + +<p>This tool does not support annotation processing. + </td> + </tr> + <tr> + <td id="java_toolchain.ijar"> + <code>ijar</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the ijar executable. + </td> + </tr> + <tr> + <td id="java_toolchain.jacocorunner"> + <code>jacocorunner</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the JacocoCoverageRunner deploy jar. + </td> + </tr> + <tr> + <td id="java_toolchain.java_runtime"> + <code>java_runtime</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + The java_runtime to use with this toolchain. It defaults to java_runtime +in execution configuration. + </td> + </tr> + <tr> + <td id="java_toolchain.javabuilder"> + <code>javabuilder</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the JavaBuilder deploy jar. + </td> + </tr> + <tr> + <td id="java_toolchain.javabuilder_data"> + <code>javabuilder_data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Labels of data available for label-expansion in javabuilder_jvm_opts. + </td> + </tr> + <tr> + <td id="java_toolchain.javabuilder_jvm_opts"> + <code>javabuilder_jvm_opts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + The list of arguments for the JVM when invoking JavaBuilder. + </td> + </tr> + <tr> + <td id="java_toolchain.javac_supports_multiplex_workers"> + <code>javac_supports_multiplex_workers</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + True if JavaBuilder supports running as a multiplex persistent worker, false if it doesn't. + </td> + </tr> + <tr> + <td id="java_toolchain.javac_supports_worker_cancellation"> + <code>javac_supports_worker_cancellation</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + True if JavaBuilder supports cancellation of persistent workers, false if it doesn't. + </td> + </tr> + <tr> + <td id="java_toolchain.javac_supports_worker_multiplex_sandboxing"> + <code>javac_supports_worker_multiplex_sandboxing</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + True if JavaBuilder supports running as a multiplex persistent worker with sandboxing, false if it doesn't. + </td> + </tr> + <tr> + <td id="java_toolchain.javac_supports_workers"> + <code>javac_supports_workers</code> + </td> + <td> + <p>Boolean; default is <code>True</code></p> + True if JavaBuilder supports running as a persistent worker, false if it doesn't. + </td> + </tr> + <tr> + <td id="java_toolchain.javacopts"> + <code>javacopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + The list of extra arguments for the Java compiler. Please refer to the Java compiler +documentation for the extensive list of possible Java compiler flags. + </td> + </tr> + <tr> + <td id="java_toolchain.jspecify_implicit_deps"> + <code>jspecify_implicit_deps</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Experimental, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.jspecify_javacopts"> + <code>jspecify_javacopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Experimental, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.jspecify_packages"> + <code>jspecify_packages</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Experimental, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.jspecify_processor"> + <code>jspecify_processor</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Experimental, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.jspecify_processor_class"> + <code>jspecify_processor_class</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Experimental, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.jspecify_stubs"> + <code>jspecify_stubs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Experimental, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.jvm_opts"> + <code>jvm_opts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + The list of arguments for the JVM when invoking the Java compiler. Please refer to the Java +virtual machine documentation for the extensive list of possible flags for this option. + </td> + </tr> + <tr> + <td id="java_toolchain.misc" class="deprecated"> + <code>misc</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Deprecated: use javacopts instead + </td> + </tr> + <tr> + <td id="java_toolchain.oneversion"> + <code>oneversion</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the one-version enforcement binary. + </td> + </tr> + <tr> + <td id="java_toolchain.oneversion_allowlist"> + <code>oneversion_allowlist</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the one-version allowlist. + </td> + </tr> + <tr> + <td id="java_toolchain.oneversion_allowlist_for_tests"> + <code>oneversion_allowlist_for_tests</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the one-version allowlist for tests. + </td> + </tr> + <tr> + <td id="java_toolchain.oneversion_whitelist" class="deprecated"> + <code>oneversion_whitelist</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Deprecated: use oneversion_allowlist instead + </td> + </tr> + <tr> + <td id="java_toolchain.package_configuration"> + <code>package_configuration</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Configuration that should be applied to the specified package groups. + </td> + </tr> + <tr> + <td id="java_toolchain.proguard_allowlister"> + <code>proguard_allowlister</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/jdk:proguard_whitelister"</code></p> + Label of the Proguard allowlister. + </td> + </tr> + <tr> + <td id="java_toolchain.reduced_classpath_incompatible_processors"> + <code>reduced_classpath_incompatible_processors</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Internal API, do not use! + </td> + </tr> + <tr> + <td id="java_toolchain.singlejar"> + <code>singlejar</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of the SingleJar deploy jar. + </td> + </tr> + <tr> + <td id="java_toolchain.source_version"> + <code>source_version</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The Java source version (e.g., '6' or '7'). It specifies which set of code structures +are allowed in the Java source code. + </td> + </tr> + <tr> + <td id="java_toolchain.target_version"> + <code>target_version</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The Java target version (e.g., '6' or '7'). It specifies for which Java runtime the class +should be build. + </td> + </tr> + <tr> + <td id="java_toolchain.timezone_data"> + <code>timezone_data</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Label of a resource jar containing timezone data. If set, the timezone data is added as an +implicitly runtime dependency of all java_binary rules. + </td> + </tr> + <tr> + <td id="java_toolchain.tools"> + <code>tools</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Labels of tools available for label-expansion in jvm_opts. + </td> + </tr> + <tr> + <td id="java_toolchain.turbine_data"> + <code>turbine_data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Labels of data available for label-expansion in turbine_jvm_opts. + </td> + </tr> + <tr> + <td id="java_toolchain.turbine_jvm_opts"> + <code>turbine_jvm_opts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + The list of arguments for the JVM when invoking turbine. + </td> + </tr> + <tr> + <td id="java_toolchain.xlint"> + <code>xlint</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + The list of warning to add or removes from default list. Precedes it with a dash to +removes it. Please see the Javac documentation on the -Xlint options for more information. + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/make-variables.mdx b/reference/be/make-variables.mdx new file mode 100644 index 0000000..51579c9 --- /dev/null +++ b/reference/be/make-variables.mdx @@ -0,0 +1,526 @@ +--- +title: 'make-variables' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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 --> + +<!-- ============================================ + variables + ============================================ +--> +<h1 class="page-title" id="make-variables">Make Variables</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm" %} +{% include "_buttons.html" %} + +<ul> + <li><a href="#use">Use</a></li> + <li><a href="#predefined_variables">Predefined variables</a></li> + <li><a href="#predefined_genrule_variables">Predefined genrule variables</a></li> + <li><a href="#predefined_label_variables">Predefined source/output path variables</a></li> + <li><a href="#custom_variables">Custom variables</a></li> +</ul> +<p> + "Make" variables are a special class of expandable string variables available + to attributes marked as <i>"Subject to 'Make variable' substitution"</i>. +</p> + +<p> + These can be used, for example, to inject specific toolchain paths into + user-constructed build actions. +</p> + +<p> + Bazel provides both <i>predefined</i> variables, which are available to all + targets, and <i>custom</i> variables, which are defined in dependency targets + and only available to targets that depend on them. +</p> + +<p> + The reason for the term "Make" is historical: the syntax and semantics of + these variables were originally intended to match <a + href="https://www.gnu.org/software/make/manual/html_node/Using-Variables.html">GNU + Make</a>. +</p> + +<h2 id="use">Use</h2> + +<p> + Attributes marked as <i>"Subject to 'Make variable' substitution"</i> can + reference the "Make" variable <code>FOO</code> as follows: +</p> + +<p> +<code>my_attr = "prefix $(FOO) suffix"</code> +</p> + +<p> + In other words, any substring matching <code>$(FOO)</code> gets expanded + to <code>FOO</code>'s value. If that value is <code>"bar"</code>, the final + string becomes: +</p> + +<p> +<code>my_attr = "prefix bar suffix"</code> +</p> + +<p> + If <code>FOO</code> doesn't correspond to a variable known to the consuming + target, Bazel fails with an error. +</p> + + +<p> + "Make" variables whose names are non-letter symbols, such as + <code>@</code>, can also be referenced using only a dollar sign, without + the parentheses. For example: +</p> + +<p> +<code>my_attr = "prefix $@ suffix"</code> +</p> + +<p> + To write <code>$</code> as a string literal (i.e. to prevent variable + expansion), write <code>$$</code>. +</p> + +<h2 id="predefined_variables">Predefined variables</h2> + +<p> + Predefined "Make" variables can be referenced by any attribute marked as + <i>"Subject to 'Make variable' substitution"</i> on any target. +</p> + +<p> + To see the list of these variables and their values for a given set of build + options, run +</p> + +<p><code>bazel info --show_make_env [build options]</code></p> + +<p> + and look at the top output lines with capital letters. +</p> + +<p><a href="https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-variables"> + See an example of predefined variables</a>.</p> + +<p><strong>Toolchain option variables</strong></p> + +<ul><!-- keep alphabetically sorted --> + <li><code>COMPILATION_MODE</code>: + <code>fastbuild</code>, <code>dbg</code>, or <code>opt</code>. (<a + href="https://bazel.build/docs/user-manual#flag--compilation_mode">more + details</a>) + </li> +</ul> + +<p><strong>Path variables</strong></p> + +<ul><!-- keep alphabetically sorted --> + <li> + <p> + <code>BINDIR</code>: The base of the generated binary tree for the target + architecture. + </p> + + <p> + Note that a different tree may be used for programs that run during the + build on the host architecture, to support cross-compiling. + </p> + + <p> + If you want to run a tool from within a <code>genrule</code>, the + recommended way to get its path is <code>$(<a + href="#predefined_label_variables">execpath</a> toolname)</code>, + where <i>toolname</i> must be listed in the <code>genrule</code>'s + <code><a + href="/reference/be/general.html#genrule.tools">tools</a></code> attribute. + </p> + </li> + + <li><code>GENDIR</code>: + The base of the generated code tree for the target architecture. + </li> +</ul> + +<p><strong>Machine architecture variables</strong></p> + +<ul><!-- keep alphabetically sorted --> + <li> <code>TARGET_CPU</code>: + The target architecture's CPU, e.g. <code>k8</code>. </li> +</ul> + +<h2 id="predefined_genrule_variables">Predefined genrule variables</h2> + +<p> + The following are specially available to <code>genrule</code>'s + <code><a href="/reference/be/general.html#genrule.cmd">cmd</a></code> attribute and are + generally important for making that attribute work. +</p> + +<p><a href="https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-genrule-variables"> + See an example of predefined genrule variables</a>.</p> + +<ul><!-- keep alphabetically sorted --> + <li><code>OUTS</code>: The <code>genrule</code>'s <code><a + href="/reference/be/general.html#genrule.outs">outs</a></code> list. If you have + only one output file, you can also use <code>$@</code>.</li> + <li> + <code>SRCS</code>: The <code>genrule</code>'s <code><a + href="/reference/be/general.html#genrule.srcs">srcs</a></code> list (or more + precisely: the path names of the files corresponding to labels in the + <code><a href="/reference/be/general.html#genrule.srcs">srcs</a></code> list). + If you have only one source file, you can also use <code>$<</code>. + </li> + + <li> + <code><</code>: <code>SRCS</code>, if it is a single file. Else triggers + a build error. + </li> + <li> + <code>@</code>: <code>OUTS</code>, if it is a single file. Else triggers a + build error. + </li> + <li> + <p> + <code>RULEDIR</code>: The output directory of the target, that is, the + directory corresponding to the name of the package containing the target + under the <code>genfiles</code> or <code>bin</code> tree. For + <code>//my/pkg:my_genrule</code> this always ends in <code>my/pkg</code>, + even if <code>//my/pkg:my_genrule</code>'s outputs are in subdirectories. + </p> + </li> + <li> + <p> + <code>@D</code>: The output directory. If + <a + href="/reference/be/general.html#genrule.outs">outs</a></code> has one entry, + this expands to the directory containing that file. If it has multiple + entries, this expands to the package's root directory in the + <code>genfiles</code> tree, <i>even if all output files are in the same + subdirectory</i>! + </p> + <p> + <b>Note:</b> Use <code>RULEDIR</code> over <code>@D</code> because + <code>RULEDIR</code> has simpler semantics and behaves the same way + regardless of the number of output files. + </p> + <p> + If the genrule needs to generate temporary intermediate files (perhaps as + a result of using some other tool like a compiler), it should attempt to + write them to <code>@D</code> (although <code>/tmp</code> will also + be writable) and remove them before finishing. + </p> + <p> + Especially avoid writing to directories containing inputs. They may be on + read-only filesystems. Even if not, doing so would trash the source tree. + </p> + </li> +</ul> + +<p> + <b>Note:</b> If the filenames corresponding to the input labels or the output + filenames contain spaces, <code>'</code>, or other special characters (or your + genrule is part of a Starlark macro which downstream users may invoke on such + files), then <code>$(SRCS)</code> and <code>$(OUTS)</code> are not suitable + for interpolation into a command line, as they do not have the semantics that + <code>"${@}"</code> would in Bash. +</p> +<p>One workaround is to convert to a Bash array, with + <pre><code>mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion' +$(SRC) +genrule_srcs_expansion +)</code></pre> +and then use <code>"$$\{SRCS[@]}"</code> in subsequent command lines in place +of <code>$(SRCS)</code>. A more robust option is to write a Starlark rule +instead. +</p> + + +<h2 id="predefined_label_variables">Predefined source/output path variables</h2> +<p> + The predefined variables <code>execpath</code>, <code>execpaths</code>, + <code>rootpath</code>, <code>rootpaths</code>, <code>location</code>, and + <code>locations</code> take label parameters (e.g. <code>$(execpath + //foo:bar)</code>) and substitute the file paths denoted by that label. +</p> +<p> + + For source files, this is the path relative to your workspace root. + For files that are outputs of rules, this is the file's <i>output path</i> + (see the explanation of <i>output files</i> below). +</p> + +<p><a href="https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-path-variables"> + See an example of predefined path variables</a>.</p> + +<ul> + <li> + <p> + <code>execpath</code>: Denotes the path beneath the + + <a href="/docs/output_directories">execroot</a> + where Bazel runs build actions. + </p> + <p> + In the above example, Bazel runs all build actions in the directory linked + by the <code>bazel-myproject</code> symlink in your workspace root. The + source file <code>empty.source</code> is linked at the path + <code>bazel-myproject/testapp/empty.source</code>. So its exec path (which + is the subpath below the root) is <code>testapp/empty.source</code>. This + is the path build actions can use to find the file. + </p> + <p> + Output files are staged similarly, but are also prefixed with the subpath + <code>bazel-out/cpu-compilation_mode/bin</code> (or for the outputs of + tools: <code>bazel-out/cpu-opt-exec-hash/bin</code>). In the above example, + <code>//testapp:app</code> is a tool because it appears in + <code>show_app_output</code>'s <code><a + href="/reference/be/general.html#genrule.tools">tools</a></code> attribute. + So its output file <code>app</code> is written to + <code>bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app</code>. + The exec path is thus <code> + bazel-out/cpu-opt-exec-hash/bin/testapp/app</code>. This extra prefix + makes it possible to build the same target for, say, two different CPUs in + the same build without the results clobbering each other. + </p> + <p> + The label passed to this variable must represent exactly one file. For + labels representing source files, this is automatically true. For labels + representing rules, the rule must generate exactly one output. If this is + false or the label is malformed, the build fails with an error. + </p> + </li> + + <li> + <p> + <code>rootpath</code>: Denotes the path that a built binary can use to + find a dependency at runtime relative to the subdirectory of its runfiles + directory corresponding to the main repository. + <strong>Note:</strong> This only works if <a + href="/reference/command-line-reference#flag--enable_runfiles"> + <code>--enable_runfiles</code></a> is enabled, which is not the case on + Windows by default. Use <code>rlocationpath</code> instead for + cross-platform support. + <p> + This is similar to <code>execpath</code> but strips the configuration + prefixes described above. In the example from above this means both + <code>empty.source</code> and <code>app</code> use pure workspace-relative + paths: <code>testapp/empty.source</code> and <code>testapp/app</code>. + </p> + <p> + The <code>rootpath</code> of a file in an external repository + <code>repo</code> will start with <code>../repo/</code>, followed by the + repository-relative path. + </p> + <p> + This has the same "one output only" requirements as <code>execpath</code>. + </p> + </li> + + <li> + <p> + <code>rlocationpath</code>: The path a built binary can pass to the <code> + Rlocation</code> function of a runfiles library to find a dependency at + runtime, either in the runfiles directory (if available) or using the + runfiles manifest. + </p> + <p> + This is similar to <code>rootpath</code> in that it does not contain + configuration prefixes, but differs in that it always starts with the + name of the repository. In the example from above this means that <code> + empty.source</code> and <code>app</code> result in the following + paths: <code>myproject/testapp/empty.source</code> and <code> + myproject/testapp/app</code>. + </p> + <p> + The <code>rlocationpath</code> of a file in an external repository + <code>repo</code> will start with <code>repo/</code>, followed by the + repository-relative path. + </p> + <p> + Passing this path to a binary and resolving it to a file system path using + the runfiles libraries is the preferred approach to find dependencies at + runtime. Compared to <code>rootpath</code>, it has the advantage that it + works on all platforms and even if the runfiles directory is not + available. + </p> + <p> + This has the same "one output only" requirements as <code>execpath</code>. + </p> + </li> + + <li> + <code>location</code>: A synonym for either <code>execpath</code> or + <code>rootpath</code>, depending on the attribute being expanded. This is + legacy pre-Starlark behavior and not recommended unless you really know what + it does for a particular rule. See <a + href="https://github.com/bazelbuild/bazel/issues/2475#issuecomment-339318016">#2475</a> + for details. + </li> +</ul> + +<p> + <code>execpaths</code>, <code>rootpaths</code>, <code>rlocationpaths</code>, + and <code>locations</code> are the plural variations of <code>execpath</code>, + <code>rootpath</code>, <code>rlocationpath</code>, and<code>location</code>, + respectively. They support labels producing multiple outputs, in which case + each output is listed separated by a space. Zero-output rules and malformed + labels produce build errors. +</p> + +<p> + All referenced labels must appear in the consuming target's <code>srcs</code>, + output files, or <code>deps</code>. Otherwise the build fails. C++ targets can + also reference labels in <code><a + href="/reference/be/c-cpp.html#cc_binary.data">data</a></code>. +</p> + +<p> + Labels don't have to be in canonical form: <code>foo</code>, <code>:foo</code> + and <code>//somepkg:foo</code> are all fine. +</p> + +<h2 id="custom_variables">Custom variables</h2> + +<p> + Custom "Make" variables can be referenced by any attribute marked as + <i>"Subject to 'Make variable' substitution"</i>, but only on targets that + depend on other targets that <i>define</i> these variables. +</p> + +<p> + As best practice all variables should be custom unless there's a really good + reason to bake them into core Bazel. This saves Bazel from having to load + potentially expensive dependencies to supply variables consuming tarets may + not care about. +</p> + +<p><strong>C++ toolchain variables</strong></p> +<p> + The following are defined in C++ toolchain rules and available to any rule + that sets <code>toolchains = + ["@bazel_tools//tools/cpp:toolchain_type"]</code> + Some rules, like <code><a + href="/reference/be/java.html#java_binary">java_binary</a></code>, implicitly + include the C++ toolchain in their rule definition. They inherit these variables + automatically. +</p> + +<p> + The built-in C++ rules are much more sophisticated than "run the compiler on + it". In order to support compilation modes as diverse as *SAN, ThinLTO, + with/without modules, and carefully optimized binaries at the same time as + fast running tests on multiple platforms, the built-in rules go to great + lengths to ensure the correct inputs, outputs, and command-line flags are set + on each of potentially multiple internally generated actions. +</p> + +<p> + These variables are a fallback mechanism to be used by language experts in + rare cases. If you are tempted to use them, please <a + href="https://bazel.build/help">contact the Bazel devs</a> first. +</p> + +<ul><!-- keep alphabetically sorted --> + <li><code>ABI</code>: The C++ ABI version. </li> + + <li> <code>AR</code>: The "ar" command from crosstool. </li> + <li class="harmful"> <code>C_COMPILER</code>: + The C/C++ compiler identifier, e.g. <code>llvm</code>. + </li> + <li class="harmful"> + <p><code>CC</code>: The C and C++ compiler command.</p> + <p> + We strongly recommended always using <code>CC_FLAGS</code> in + combination with <code>CC</code>. Fail to do so at your own risk. + </p> + </li> + <li class="harmful"><code>CC_FLAGS</code>: A minimal set of flags for the C/C++ + compiler to be usable by genrules. In particular, this contains flags to + select the correct architecture if <code>CC</code> supports multiple + architectures. + </li> + + + <li> <code>DUMPBIN</code>: Microsoft COFF Binary File Dumper (dumpbin.exe) from + from Microsoft Visual Studio. </li> + + <li> <code>NM</code>: The "nm" command from crosstool. </li> + <li> <code>OBJCOPY</code>: The objcopy command from the same suite as the C/C++ + compiler. </li> + + <li> <code>STRIP</code>: The strip command from the same suite as the C/C++ + compiler.</li> +</ul> + +<p><strong>Java toolchain variables</strong></p> + +<p> + The following are defined in Java toolchain rules and available to any rule + that sets <code>toolchains = +["@rules_java//toolchains:current_java_runtime"]</code> (or + <code>"@rules_java//toolchains:current_host_java_runtime"</code> + for the host toolchain equivalent). +</p> + +<p> + Most of the tools in the JDK should not be used directly. The built-in Java + rules use much more sophisticated approaches to Java compilation and packaging + than upstream tools can express, such as interface Jars, header interface + Jars, and highly optimized Jar packaging and merging implementations. +</p> + +<p> + These variables are a fallback mechanism to be used by language experts in + rare cases. If you are tempted to use them, please <a + href="https://bazel.build/help">contact the Bazel devs</a> first. +</p> + +<ul><!-- keep alphabetically sorted --> + <li class="harmful"> <code>JAVA</code>: The "java" command (a Java virtual + machine). Avoid this, and use a <code><a + href="/reference/be/java.html#java_binary">java_binary</a></code> rule + instead where possible. May be a relative path. If you must change + directories before invoking <code>java</code>, you need to capture the + working directory before changing it. + </li> + + <li class="harmful"><code>JAVABASE</code>: The base directory containing the + Java utilities. May be a relative path. It will have a "bin" + subdirectory. + </li> +</ul> + +<p><strong>Starlark-defined variables</strong></p> + +<p> + Rule and <a href="/docs/toolchains">toolchain</a> writers can define + completely custom variables by returning a + <a href="/rules/lib/TemplateVariableInfo">TemplateVariableInfo</a> + provider. Any rules depending on these through the + <code>toolchains</code> attribute can then read their values: +</p> + +<p><a href="https://github.com/bazelbuild/examples/tree/main/make-variables#custom-starlark-defined-variables"> + See an example of Starlark-defined variables</a>.</p> + +<!-- Generated footer --> + + + +</body> +</html> diff --git a/reference/be/objective-c.mdx b/reference/be/objective-c.mdx new file mode 100644 index 0000000..e1f2160 --- /dev/null +++ b/reference/be/objective-c.mdx @@ -0,0 +1,558 @@ +--- +title: 'objective-c' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">Objective-C Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% include "_buttons.html" %} + + + + +<h2>Rules</h2> +<ul> + <li> + <a href="#objc_import"> + objc_import </a> + </li> + <li> + <a href="#objc_library"> + objc_library </a> + </li> +</ul> + + <h2 id="objc_import"> + objc_import + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_import.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">objc_import(<a href="#objc_import.name">name</a>, <a href="#objc_import.deps">deps</a>, <a href="#objc_import.hdrs">hdrs</a>, <a href="#objc_import.alwayslink">alwayslink</a>, <a href="#objc_import.archives">archives</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#objc_import.includes">includes</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#objc_import.sdk_dylibs">sdk_dylibs</a>, <a href="#objc_import.sdk_frameworks">sdk_frameworks</a>, <a href="#objc_import.sdk_includes">sdk_includes</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="#objc_import.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#objc_import.weak_sdk_frameworks">weak_sdk_frameworks</a>)</pre> + + <p>This rule encapsulates an already-compiled static library in the form of an +<code>.a</code> file. It also allows exporting headers and resources using the same +attributes supported by <code>objc_library</code>.</p> + + <h3 id="objc_import_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="objc_import.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="objc_import.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of targets that this target depend on. + </td> + </tr> + <tr> + <td id="objc_import.hdrs"> + <code>hdrs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of C, C++, Objective-C, and Objective-C++ header files published +by this library to be included by sources in dependent rules. +<p> +These headers describe the public interface for the library and will be +made available for inclusion by sources in this rule or in dependent +rules. Headers not meant to be included by a client of this library +should be listed in the srcs attribute instead. +<p> +These will be compiled separately from the source if modules are enabled. + </td> + </tr> + <tr> + <td id="objc_import.alwayslink"> + <code>alwayslink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + If 1, any bundle or binary that depends (directly or indirectly) on this +library will link in all the object files for the files listed in +<code>srcs</code> and <code>non_arc_srcs</code>, even if some contain no +symbols referenced by the binary. +This is useful if your code isn't explicitly called by code in +the binary, e.g., if your code registers to receive some callback +provided by some service. + </td> + </tr> + <tr> + <td id="objc_import.archives"> + <code>archives</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; required</p> + The list of <code>.a</code> files provided to Objective-C targets that +depend on this target. + </td> + </tr> + <tr> + <td id="objc_import.includes"> + <code>includes</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of <code>#include/#import</code> search paths to add to this target +and all depending targets. + +This is to support third party and open-sourced libraries that do not +specify the entire workspace path in their +<code>#import/#include</code> statements. +<p> +The paths are interpreted relative to the package directory, and the +genfiles and bin roots (e.g. <code>blaze-genfiles/pkg/includedir</code> +and <code>blaze-out/pkg/includedir</code>) are included in addition to the +actual client root. +<p> +Unlike <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a>, these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-iquote" flags to <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead. + </td> + </tr> + <tr> + <td id="objc_import.sdk_dylibs"> + <code>sdk_dylibs</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Names of SDK .dylib libraries to link with. For instance, "libz" or +"libarchive". + +"libc++" is included automatically if the binary has any C++ or +Objective-C++ sources in its dependency tree. When linking a binary, +all libraries named in that binary's transitive dependency graph are +used. + </td> + </tr> + <tr> + <td id="objc_import.sdk_frameworks"> + <code>sdk_frameworks</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). + +<p> When linking a top level Apple binary, all SDK frameworks listed in that binary's +transitive dependency graph are linked. + </td> + </tr> + <tr> + <td id="objc_import.sdk_includes"> + <code>sdk_includes</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of <code>#include/#import</code> search paths to add to this target +and all depending targets, where each path is relative to +<code>$(SDKROOT)/usr/include</code>. + </td> + </tr> + <tr> + <td id="objc_import.textual_hdrs"> + <code>textual_hdrs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of C, C++, Objective-C, and Objective-C++ files that are +included as headers by source files in this rule or by users of this +library. Unlike hdrs, these will not be compiled separately from the +sources. + </td> + </tr> + <tr> + <td id="objc_import.weak_sdk_frameworks"> + <code>weak_sdk_frameworks</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Names of SDK frameworks to weakly link with. For instance, +"MediaAccessibility". + +In difference to regularly linked SDK frameworks, symbols +from weakly linked frameworks do not cause an error if they +are not present at runtime. + </td> + </tr> + </tbody> + </table> + <h2 id="objc_library"> + objc_library + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">objc_library(<a href="#objc_library.name">name</a>, <a href="#objc_library.deps">deps</a>, <a href="#objc_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#objc_library.hdrs">hdrs</a>, <a href="#objc_library.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#objc_library.conlyopts">conlyopts</a>, <a href="#objc_library.copts">copts</a>, <a href="#objc_library.cxxopts">cxxopts</a>, <a href="#objc_library.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#objc_library.enable_modules">enable_modules</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#objc_library.implementation_deps">implementation_deps</a>, <a href="#objc_library.includes">includes</a>, <a href="#objc_library.linkopts">linkopts</a>, <a href="#objc_library.module_map">module_map</a>, <a href="#objc_library.module_name">module_name</a>, <a href="#objc_library.non_arc_srcs">non_arc_srcs</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#objc_library.pch">pch</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#objc_library.sdk_dylibs">sdk_dylibs</a>, <a href="#objc_library.sdk_frameworks">sdk_frameworks</a>, <a href="#objc_library.sdk_includes">sdk_includes</a>, <a href="#objc_library.stamp">stamp</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="#objc_library.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#objc_library.weak_sdk_frameworks">weak_sdk_frameworks</a>)</pre> + + <p>This rule produces a static library from the given Objective-C source files.</p> + + <h3 id="objc_library_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="objc_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="objc_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of targets that this target depend on. + </td> + </tr> + <tr> + <td id="objc_library.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of C, C++, Objective-C, and Objective-C++ source and header +files, and/or (`.s`, `.S`, or `.asm`) assembly source files, that are processed to create +the library target. +These are your checked-in files, plus any generated files. +Source files are compiled into .o files with Clang. Header files +may be included/imported by any source or header in the srcs attribute +of this target, but not by headers in hdrs or any targets that depend +on this rule. +Additionally, precompiled .o files may be given as srcs. Be careful to +ensure consistency in the architecture of provided .o files and that of the +build to avoid missing symbol linker errors. + </td> + </tr> + <tr> + <td id="objc_library.hdrs"> + <code>hdrs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of C, C++, Objective-C, and Objective-C++ header files published +by this library to be included by sources in dependent rules. +<p> +These headers describe the public interface for the library and will be +made available for inclusion by sources in this rule or in dependent +rules. Headers not meant to be included by a client of this library +should be listed in the srcs attribute instead. +<p> +These will be compiled separately from the source if modules are enabled. + </td> + </tr> + <tr> + <td id="objc_library.alwayslink"> + <code>alwayslink</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + If 1, any bundle or binary that depends (directly or indirectly) on this +library will link in all the object files for the files listed in +<code>srcs</code> and <code>non_arc_srcs</code>, even if some contain no +symbols referenced by the binary. +This is useful if your code isn't explicitly called by code in +the binary, e.g., if your code registers to receive some callback +provided by some service. + </td> + </tr> + <tr> + <td id="objc_library.conlyopts"> + <code>conlyopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra flags to pass to the compiler for C files. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +These flags will only apply to this target, and not those upon which +it depends, or those which depend on it. +<p> +Note that for the generated Xcode project, directory paths specified using "-I" flags in +copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and +added to the header search paths for the associated Xcode target. + </td> + </tr> + <tr> + <td id="objc_library.copts"> + <code>copts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra flags to pass to the compiler. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +These flags will only apply to this target, and not those upon which +it depends, or those which depend on it. +<p> +Note that for the generated Xcode project, directory paths specified using "-I" flags in +copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and +added to the header search paths for the associated Xcode target. + </td> + </tr> + <tr> + <td id="objc_library.cxxopts"> + <code>cxxopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra flags to pass to the compiler for Objective-C++ and C++ files. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. +These flags will only apply to this target, and not those upon which +it depends, or those which depend on it. +<p> +Note that for the generated Xcode project, directory paths specified using "-I" flags in +copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and +added to the header search paths for the associated Xcode target. + </td> + </tr> + <tr> + <td id="objc_library.defines"> + <code>defines</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra <code>-D</code> flags to pass to the compiler. They should be in +the form <code>KEY=VALUE</code> or simply <code>KEY</code> and are +passed not only to the compiler for this target (as <code>copts</code> +are) but also to all <code>objc_</code> dependers of this target. +Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. + </td> + </tr> + <tr> + <td id="objc_library.enable_modules"> + <code>enable_modules</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Enables clang module support (via -fmodules). +Setting this to 1 will allow you to @import system headers and other targets: +@import UIKit; +@import path_to_package_target; + </td> + </tr> + <tr> + <td id="objc_library.implementation_deps"> + <code>implementation_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other libraries that the library target depends on. Unlike with +<code>deps</code>, the headers and include paths of these libraries (and all their +transitive deps) are only used for compilation of this library, and not libraries that +depend on it. Libraries specified with <code>implementation_deps</code> are still linked +in binary targets that depend on this library. + </td> + </tr> + <tr> + <td id="objc_library.includes"> + <code>includes</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of <code>#include/#import</code> search paths to add to this target +and all depending targets. + +This is to support third party and open-sourced libraries that do not +specify the entire workspace path in their +<code>#import/#include</code> statements. +<p> +The paths are interpreted relative to the package directory, and the +genfiles and bin roots (e.g. <code>blaze-genfiles/pkg/includedir</code> +and <code>blaze-out/pkg/includedir</code>) are included in addition to the +actual client root. +<p> +Unlike <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a>, these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-iquote" flags to <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead. + </td> + </tr> + <tr> + <td id="objc_library.linkopts"> + <code>linkopts</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Extra flags to pass to the linker. + </td> + </tr> + <tr> + <td id="objc_library.module_map"> + <code>module_map</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + custom Clang module map for this target. Use of a custom module map is discouraged. Most +users should use module maps generated by Bazel. +If specified, Bazel will not generate a module map for this target, but will pass the +provided module map to the compiler. + </td> + </tr> + <tr> + <td id="objc_library.module_name"> + <code>module_name</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Sets the module name for this target. By default the module name is the target path with +all special symbols replaced by _, e.g. //foo/baz:bar can be imported as foo_baz_bar. + </td> + </tr> + <tr> + <td id="objc_library.non_arc_srcs"> + <code>non_arc_srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of Objective-C files that are processed to create the +library target that DO NOT use ARC. +The files in this attribute are treated very similar to those in the +srcs attribute, but are compiled without ARC enabled. + </td> + </tr> + <tr> + <td id="objc_library.pch"> + <code>pch</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Header file to prepend to every source file being compiled (both arc +and non-arc). +Use of pch files is actively discouraged in BUILD files, and this should be +considered deprecated. Since pch files are not actually precompiled this is not +a build-speed enhancement, and instead is just a global dependency. From a build +efficiency point of view you are actually better including what you need directly +in your sources where you need it. + </td> + </tr> + <tr> + <td id="objc_library.sdk_dylibs"> + <code>sdk_dylibs</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Names of SDK .dylib libraries to link with. For instance, "libz" or +"libarchive". + +"libc++" is included automatically if the binary has any C++ or +Objective-C++ sources in its dependency tree. When linking a binary, +all libraries named in that binary's transitive dependency graph are +used. + </td> + </tr> + <tr> + <td id="objc_library.sdk_frameworks"> + <code>sdk_frameworks</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). + +<p> When linking a top level Apple binary, all SDK frameworks listed in that binary's +transitive dependency graph are linked. + </td> + </tr> + <tr> + <td id="objc_library.sdk_includes"> + <code>sdk_includes</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of <code>#include/#import</code> search paths to add to this target +and all depending targets, where each path is relative to +<code>$(SDKROOT)/usr/include</code>. + </td> + </tr> + <tr> + <td id="objc_library.stamp"> + <code>stamp</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + + </td> + </tr> + <tr> + <td id="objc_library.textual_hdrs"> + <code>textual_hdrs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of C, C++, Objective-C, and Objective-C++ files that are +included as headers by source files in this rule or by users of this +library. Unlike hdrs, these will not be compiled separately from the +sources. + </td> + </tr> + <tr> + <td id="objc_library.weak_sdk_frameworks"> + <code>weak_sdk_frameworks</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Names of SDK frameworks to weakly link with. For instance, +"MediaAccessibility". + +In difference to regularly linked SDK frameworks, symbols +from weakly linked frameworks do not cause an error if they +are not present at runtime. + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/overview.mdx b/reference/be/overview.mdx new file mode 100644 index 0000000..82d417a --- /dev/null +++ b/reference/be/overview.mdx @@ -0,0 +1,279 @@ +--- +title: 'overview' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title">Bazel BUILD Encyclopedia of Functions</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm" %} +{% include "_buttons.html" %} +<h2>Concepts and terminology</h2> + +<ul> + <li> + <a href="/reference/be/common-definitions">Common definitions</a> + <ul> + <li><a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a></li> + <li><a href="/reference/be/common-definitions#label-expansion">Label expansion</a></li> + <li><a href="/reference/be/common-definitions#typical-attributes">Typical attributes for most rules</a></li> + <li><a href="/reference/be/common-definitions#common-attributes">Common attributes for all rules</a></li> + <li><a href="/reference/be/common-definitions#common-attributes-tests">Common attributes for tests</a></li> + <li><a href="/reference/be/common-definitions#common-attributes-binaries">Common attributes for binaries</a></li> + <li><a href="/reference/be/common-definitions#configurable-attributes">Configurable attributes</a></li> + <li><a href="/reference/be/common-definitions#implicit-outputs">Implicit output targets</a></li> + </ul> + </li> + <li> + <a href="/reference/be/make-variables">"Make" variables</a> + <ul class="be-toc"> + <li><a href="/reference/be/make-variables#use">Use</a></li> + + </ul> + </li> +</ul> + +<h2>Functions</h2> + +<ul class="be-toc"> + <li><a href="/reference/be/functions.html#package">package</a></li> + <li><a href="/reference/be/functions.html#package_group">package_group</a></li> + + <li><a href="/reference/be/functions.html#exports_files">exports_files</a></li> + <li><a href="/reference/be/functions.html#glob">glob</a></li> + <li><a href="/reference/be/functions.html#select">select</a></li> + <li><a href="/rules/lib/globals/workspace#workspace">workspace</a></li> +</ul> + +<h2>Rules</h2> + +Native rules ship with the Bazel binary and do not require a <code>load</code> statement. +Native rules are available globally in BUILD files. In .bzl files, you can find them in +the <code>native</code> module. + +For non-native Starlark rules that ship separately from Bazel, see the list of +<a href="/rules/rules#recommended-rules">recommended rules</a>. + +<h3>Language-specific native rules</h3> + + +<table class="table table-condensed table-striped" summary="Table of rules sorted by language"> + <thead> + <tr> + <th>Language</th> + <th>Flags</th> + <th>Binary rules</th> + <th>Library rules</th> + <th>Test rules</th> + <th>Other rules</th> + </tr> + </thead> + <tbody> + <tr> + <td class="lang">C / C++</td> + <td></td> + + <td> + <a href="c-cpp.html#cc_binary">cc_binary</a> + <br /> + </td> + <td> + <a href="c-cpp.html#cc_import">cc_import</a> + <br /> + <a href="c-cpp.html#cc_library">cc_library</a> + <br /> + <a href="c-cpp.html#cc_shared_library">cc_shared_library</a> + <br /> + <a href="c-cpp.html#cc_static_library">cc_static_library</a> + <br /> + </td> + <td> + <a href="c-cpp.html#cc_test">cc_test</a> + <br /> + </td> + <td> + <a href="c-cpp.html#cc_toolchain">cc_toolchain</a> + <br /> + <a href="c-cpp.html#fdo_prefetch_hints">fdo_prefetch_hints</a> + <br /> + <a href="c-cpp.html#fdo_profile">fdo_profile</a> + <br /> + <a href="c-cpp.html#memprof_profile">memprof_profile</a> + <br /> + <a href="c-cpp.html#propeller_optimize">propeller_optimize</a> + <br /> + </td> + </tr> + <tr> + <td class="lang">Java</td> + <td></td> + + <td> + <a href="java.html#java_binary">java_binary</a> + <br /> + </td> + <td> + <a href="java.html#java_import">java_import</a> + <br /> + <a href="java.html#java_library">java_library</a> + <br /> + </td> + <td> + <a href="java.html#java_test">java_test</a> + <br /> + </td> + <td> + <a href="java.html#java_package_configuration">java_package_configuration</a> + <br /> + <a href="java.html#java_plugin">java_plugin</a> + <br /> + <a href="java.html#java_runtime">java_runtime</a> + <br /> + <a href="java.html#java_single_jar">java_single_jar</a> + <br /> + <a href="java.html#java_toolchain">java_toolchain</a> + <br /> + </td> + </tr> + <tr> + <td class="lang">Objective-C</td> + <td></td> + + <td> + </td> + <td> + <a href="objective-c.html#objc_import">objc_import</a> + <br /> + <a href="objective-c.html#objc_library">objc_library</a> + <br /> + </td> + <td> + </td> + <td> + </td> + </tr> + <tr> + <td class="lang">Protocol Buffer</td> + <td></td> + + <td> + </td> + <td> + <a href="protocol-buffer.html#cc_proto_library">cc_proto_library</a> + <br /> + <a href="protocol-buffer.html#java_lite_proto_library">java_lite_proto_library</a> + <br /> + <a href="protocol-buffer.html#java_proto_library">java_proto_library</a> + <br /> + <a href="protocol-buffer.html#proto_library">proto_library</a> + <br /> + <a href="protocol-buffer.html#py_proto_library">py_proto_library</a> + <br /> + </td> + <td> + </td> + <td> + <a href="protocol-buffer.html#proto_lang_toolchain">proto_lang_toolchain</a> + <br /> + <a href="protocol-buffer.html#proto_toolchain">proto_toolchain</a> + <br /> + </td> + </tr> + <tr> + <td class="lang">Python</td> + <td></td> + + <td> + <a href="python.html#py_binary">py_binary</a> + <br /> + </td> + <td> + <a href="python.html#py_library">py_library</a> + <br /> + </td> + <td> + <a href="python.html#py_test">py_test</a> + <br /> + </td> + <td> + <a href="python.html#py_runtime">py_runtime</a> + <br /> + </td> + </tr> + <tr> + <td class="lang">Shell</td> + <td></td> + + <td> + <a href="shell.html#sh_binary">sh_binary</a> + <br /> + </td> + <td> + <a href="shell.html#sh_library">sh_library</a> + <br /> + </td> + <td> + <a href="shell.html#sh_test">sh_test</a> + <br /> + </td> + <td> + </td> + </tr> + </tbody> + +</table> +<h3>Language-agnostic native rules</h3> + +<table class="table table-condensed table-striped" summary="Table of rules not specific to a programming language"> + <thead> + <tr> + <th>Family</th> + <th>Rules</th> + </tr> + </thead> + <tbody> + <tr> + <td class="lang">Extra Actions</td> + <td> + <ul class="hlist"> + <li> <a href="extra-actions.html#action_listener">action_listener</a> + <li> <a href="extra-actions.html#extra_action">extra_action</a> + </ul> + </td> + </tr> + <tr> + <td class="lang">General</td> + <td> + <ul class="hlist"> + <li> <a href="general.html#alias">alias</a> + <li> <a href="general.html#config_setting">config_setting</a> + <li> <a href="general.html#filegroup">filegroup</a> + <li> <a href="general.html#genquery">genquery</a> + <li> <a href="general.html#genrule">genrule</a> + <li> <a href="general.html#starlark_doc_extract">starlark_doc_extract</a> + <li> <a href="general.html#test_suite">test_suite</a> + </ul> + </td> + </tr> + <tr> + <td class="lang">Platforms and Toolchains</td> + <td> + <ul class="hlist"> + <li> <a href="platforms-and-toolchains.html#constraint_setting">constraint_setting</a> + <li> <a href="platforms-and-toolchains.html#constraint_value">constraint_value</a> + <li> <a href="platforms-and-toolchains.html#platform">platform</a> + <li> <a href="platforms-and-toolchains.html#toolchain">toolchain</a> + <li> <a href="platforms-and-toolchains.html#toolchain_type">toolchain_type</a> + </ul> + </td> + </tr> + </tbody> + +</table> +</body> +</html> diff --git a/reference/be/platforms-and-toolchains.mdx b/reference/be/platforms-and-toolchains.mdx new file mode 100644 index 0000000..23ecc85 --- /dev/null +++ b/reference/be/platforms-and-toolchains.mdx @@ -0,0 +1,755 @@ +--- +title: 'platforms-and-toolchains' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">Platforms and Toolchains Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% 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="/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="common-definitions.html#common.aspect_hints">aspect_hints</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.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/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="/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="/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> + </table> + <h2 id="constraint_value"> + constraint_value + </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/ConstraintValueRule.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_value(<a href="#constraint_value.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.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/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="/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="/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> + </table> + <h2 id="platform"> + platform + </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/PlatformRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">platform(<a href="#platform.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#platform.constraint_values">constraint_values</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#platform.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#platform.flags">flags</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#platform.missing_toolchain_error">missing_toolchain_error</a>, <a href="#platform.parents">parents</a>, <a href="#platform.remote_execution_properties">remote_execution_properties</a>, <a href="#platform.required_settings">required_settings</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="/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_flags">Platform Flags</h3> +<p> + Platforms may use the <code>flags</code> attribute to specify a list of flags that will be added + to the configuration whenever the platform is used as the target platform (i.e., as the value of + the <code>--platforms</code> flag). +</p> + +<p> + Flags set from the platform effectively have the highest precedence and overwrite any previous + value for that flag, from the command line, rc file, or transition. +</p> + +<h4 id="platform_flags_examples">Example</h4> + +<pre class="code"> +platform( + name = "foo", + flags = [ + "--dynamic_mode=fully", + "--//bool_flag", + "--no//package:other_bool_flag", + ], +) +</pre> + +<p> + This defines a platform named <code>foo</code>. When this is the target platform (either because + the user specified <code>--platforms//:foo</code>, because a transition set the + <code>//command_line_option:platforms</code> flag to <code>["//:foo"]</code>, or because + <code>//:foo</code> was used as an execution platform), then the given flags will be set in the + configuration. +</p> + +<h4 id=platform_flags_repeated>Platforms and Repeatable Flags</h4> + +<p> + Some flags will accumulate values when they are repeated, such as <code>--features</code>, + <code>--copt</code>, any Starlark flag created as <code>config.string(repeatable = True)</code>. + These flags are not compatible with setting the flags from the platform: instead, all previous + values will be removed and overwritten with the values from the platform. +</p> + +<p> + As an example, given the following platform, the invocation <code>build --platforms=//:repeat_demo + --features feature_a --features feature_b</code> will end up with the value of the + <code>--feature</code> flag being <code>["feature_c", "feature_d"]</code>, removing the features + set on the command line. +</p> + +<pre class="code"> +platform( + name = "repeat_demo", + flags = [ + "--features=feature_c", + "--features=feature_d", + ], +) +</pre> + +<p> + For this reason, it is discouraged to use repeatable flags in the <code>flags</code> attribute. +</p> + +<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="/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="/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.flags"> + <code>flags</code> + </td> + <td> + <p>List of strings; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> + A list of flags that will be enabled when this platform is used as the target platform in + a configuration. Only flags that are part of the configuration can be set, such as those + that can be used in transitions, or the <code>--define</code> flag. + + </td> + </tr> + <tr> + <td id="platform.missing_toolchain_error"> + <code>missing_toolchain_error</code> + </td> + <td> + <p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>"For more information on platforms or toolchains see https://bazel.build/concepts/platforms-intro."</code></p> + A custom error message that is displayed when a mandatory toolchain requirement cannot be satisfied for this target platform. Intended to point to relevant documentation users can read to understand why their toolchains are misconfigured. + + Not inherited from parent platforms. + + </td> + </tr> + <tr> + <td id="platform.parents"> + <code>parents</code> + </td> + <td> + <p>List of <a href="/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> + <tr> + <td id="platform.required_settings"> + <code>required_settings</code> + </td> + <td> + <p>List of <a href="/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 platform to be used as an execution platform during toolchain resolution. + + Required settings are not inherited from parent platforms. + + </td> + </tr> + </tbody> + </table> + <h2 id="toolchain"> + toolchain + </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/ToolchainRule.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">toolchain(<a href="#toolchain.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#toolchain.exec_compatible_with">exec_compatible_with</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.package_metadata">package_metadata</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="#toolchain.use_target_platform_constraints">use_target_platform_constraints</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/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><a href="/concepts/labels#target-names">Name</a>; required</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>List of <a href="/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="/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="/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="/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="/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> + <tr> + <td id="toolchain.use_target_platform_constraints"> + <code>use_target_platform_constraints</code> + </td> + <td> + <p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> + If <code>True</code>, this toolchain behaves as if its <code>exec_compatible_with</code> and + <code>target_compatible_with</code> constraints are set to those of the current target + platform. <code>exec_compatible_with</code> and <code>target_compatible_with</code> must not + be set in that case. + + </td> + </tr> + </tbody> + </table> + <h2 id="toolchain_type"> + toolchain_type + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/ToolchainType.java" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">toolchain_type(<a href="#toolchain_type.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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="#toolchain_type.no_match_error">no_match_error</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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="/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><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="toolchain_type.no_match_error"> + <code>no_match_error</code> + </td> + <td> + <p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>""</code></p> + A custom error message to display when no matching toolchain is found for this type. + + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/protocol-buffer.mdx b/reference/be/protocol-buffer.mdx new file mode 100644 index 0000000..7129166 --- /dev/null +++ b/reference/be/protocol-buffer.mdx @@ -0,0 +1,770 @@ +--- +title: 'protocol-buffer' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">Protocol Buffer Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% include "_buttons.html" %} + + + + +<h2>Rules</h2> +<ul> + <li> + <a href="#cc_proto_library"> + cc_proto_library </a> + </li> + <li> + <a href="#java_lite_proto_library"> + java_lite_proto_library </a> + </li> + <li> + <a href="#java_proto_library"> + java_proto_library </a> + </li> + <li> + <a href="#proto_library"> + proto_library </a> + </li> + <li> + <a href="#py_proto_library"> + py_proto_library </a> + </li> + <li> + <a href="#proto_lang_toolchain"> + proto_lang_toolchain </a> + </li> + <li> + <a href="#proto_toolchain"> + proto_toolchain </a> + </li> +</ul> + + <h2 id="cc_proto_library"> + cc_proto_library + </h2> + + <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_cc_proto_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">cc_proto_library(<a href="#cc_proto_library.name">name</a>, <a href="#cc_proto_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> +<code>cc_proto_library</code> generates C++ code from <code>.proto</code> files. +</p> + +<p> +<code>deps</code> must point to <a href="protocol-buffer.html#proto_library"><code>proto_library +</code></a> rules. +</p> + +<p> +Example: +</p> + +<pre> +<code class="lang-starlark"> +cc_library( + name = "lib", + deps = [":foo_cc_proto"], +) + +cc_proto_library( + name = "foo_cc_proto", + deps = [":foo_proto"], +) + +proto_library( + name = "foo_proto", +) +</code> +</pre> + + <h3 id="cc_proto_library_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="cc_proto_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="cc_proto_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> +rules to generate C++ code for. + </td> + </tr> + </tbody> + </table> + <h2 id="java_lite_proto_library"> + java_lite_proto_library + </h2> + + <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/java_lite_proto_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_lite_proto_library(<a href="#java_lite_proto_library.name">name</a>, <a href="#java_lite_proto_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> +<code>java_lite_proto_library</code> generates Java code from <code>.proto</code> files. +</p> + +<p> +<code>deps</code> must point to <a href="protocol-buffer.html#proto_library"><code>proto_library +</code></a> rules. +</p> + +<p> +Example: +</p> + +<pre class="code"> +<code class="lang-starlark"> +java_library( + name = "lib", + runtime_deps = [":foo"], +) + +java_lite_proto_library( + name = "foo", + deps = [":bar"], +) + +proto_library( + name = "bar", +) +</code> +</pre> + + <h3 id="java_lite_proto_library_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="java_lite_proto_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_lite_proto_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> +rules to generate Java code for. + </td> + </tr> + </tbody> + </table> + <h2 id="java_proto_library"> + java_proto_library + </h2> + + <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_java_proto_library_rule.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">java_proto_library(<a href="#java_proto_library.name">name</a>, <a href="#java_proto_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> +<code>java_proto_library</code> generates Java code from <code>.proto</code> files. +</p> + +<p> +<code>deps</code> must point to <a href="protocol-buffer.html#proto_library"><code>proto_library +</code></a> rules. +</p> + +<p> +Example: +</p> + +<pre class="code"> +<code class="lang-starlark"> +java_library( + name = "lib", + runtime_deps = [":foo_java_proto"], +) + +java_proto_library( + name = "foo_java_proto", + deps = [":foo_proto"], +) + +proto_library( + name = "foo_proto", +) +</code> +</pre> + + <h3 id="java_proto_library_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="java_proto_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="java_proto_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> +rules to generate Java code for. + </td> + </tr> + </tbody> + </table> + <h2 id="proto_library"> + proto_library + </h2> + + <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_library_rule.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">proto_library(<a href="#proto_library.name">name</a>, <a href="#proto_library.deps">deps</a>, <a href="#proto_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#proto_library.allow_exports">allow_exports</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#proto_library.exports">exports</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#proto_library.import_prefix">import_prefix</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#proto_library.option_deps">option_deps</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#proto_library.strip_import_prefix">strip_import_prefix</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>Use <code>proto_library</code> to define libraries of protocol buffers which +may be used from multiple languages. A <code>proto_library</code> may be listed +in the <code>deps</code> clause of supported rules, such as +<code>java_proto_library</code>. + +<p>When compiled on the command-line, a <code>proto_library</code> creates a file +named <code>foo-descriptor-set.proto.bin</code>, which is the descriptor set for +the messages the rule srcs. The file is a serialized +<code>FileDescriptorSet</code>, which is described in +<a href="https://developers.google.com/protocol-buffers/docs/techniques#self-description"> +https://developers.google.com/protocol-buffers/docs/techniques#self-description</a>. + +<p>It only contains information about the <code>.proto</code> files directly +mentioned by a <code>proto_library</code> rule; the collection of transitive +descriptor sets is available through the +<code>[ProtoInfo].transitive_descriptor_sets</code> Starlark provider. +See documentation in <code>proto_info.bzl</code>. + +<p>Recommended code organization: +<ul> +<li>One <code>proto_library</code> rule per <code>.proto</code> file. +<li>A file named <code>foo.proto</code> will be in a rule named <code>foo_proto</code>, + which is located in the same package. +<li>A <code>[language]_proto_library</code> that wraps a <code>proto_library</code> + named <code>foo_proto</code> should be called <code>foo_[language]_proto</code>, + and be located in the same package. +</ul> + + <h3 id="proto_library_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="proto_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="proto_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other <code>proto_library</code> rules that the target depends upon. +A <code>proto_library</code> may only depend on other <code>proto_library</code> +targets. It may not depend on language-specific libraries. + </td> + </tr> + <tr> + <td id="proto_library.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of <code>.proto</code> and <code>.protodevel</code> files that are +processed to create the target. This is usually a non empty list. One usecase +where <code>srcs</code> can be empty is an <i>alias-library</i>. This is a +proto_library rule having one or more other proto_library in <code>deps</code>. +This pattern can be used to e.g. export a public api under a persistent name. + </td> + </tr> + <tr> + <td id="proto_library.allow_exports"> + <code>allow_exports</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + An optional allowlist that prevents proto library to be reexported or used in +lang_proto_library that is not in one of the listed packages. + </td> + </tr> + <tr> + <td id="proto_library.exports"> + <code>exports</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + List of proto_library targets that can be referenced via "import public" in the +proto source. +It's an error if you use "import public" but do not list the corresponding library +in the exports attribute. +Note that you have list the library both in deps and exports since not all +lang_proto_library implementations have been changed yet. + </td> + </tr> + <tr> + <td id="proto_library.import_prefix"> + <code>import_prefix</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The prefix to add to the paths of the .proto files in this rule. + +<p>When set, the .proto source files in the <code>srcs</code> attribute of this rule are +accessible at is the value of this attribute prepended to their repository-relative path. + +<p>The prefix in the <code>strip_import_prefix</code> attribute is removed before this +prefix is added. + </td> + </tr> + <tr> + <td id="proto_library.option_deps"> + <code>option_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of other <code>proto_library</code> rules that the target depends upon for options only. +A <code>proto_library</code> may only depend on other <code>proto_library</code> +targets. It may not depend on language-specific libraries. + </td> + </tr> + <tr> + <td id="proto_library.strip_import_prefix"> + <code>strip_import_prefix</code> + </td> + <td> + <p>String; default is <code>"/"</code></p> + The prefix to strip from the paths of the .proto files in this rule. + +<p>When set, .proto source files in the <code>srcs</code> attribute of this rule are +accessible at their path with this prefix cut off. + +<p>If it's a relative path (not starting with a slash), it's taken as a package-relative +one. If it's an absolute one, it's understood as a repository-relative path. + +<p>The prefix in the <code>import_prefix</code> attribute is added after this prefix is +stripped. + </td> + </tr> + </tbody> + </table> + <h2 id="py_proto_library"> + py_proto_library + </h2> + + <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/py_proto_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">py_proto_library(<a href="#py_proto_library.name">name</a>, <a href="#py_proto_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + Use `py_proto_library` to generate Python libraries from `.proto` files. + + The convention is to name the `py_proto_library` rule `foo_py_pb2`, + when it is wrapping `proto_library` rule `foo_proto`. + + `deps` must point to a `proto_library` rule. + + Example: + +```starlark +py_library( + name = "lib", + deps = [":foo_py_pb2"], +) + +py_proto_library( + name = "foo_py_pb2", + deps = [":foo_proto"], +) + +proto_library( + name = "foo_proto", + srcs = ["foo.proto"], +) +``` + + <h3 id="py_proto_library_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="py_proto_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="py_proto_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of `proto_library` rules to generate Python libraries for. + +Usually this is just the one target: the proto library of interest. +It can be any target providing `ProtoInfo`. + </td> + </tr> + </tbody> + </table> + <h2 id="proto_lang_toolchain"> + proto_lang_toolchain + </h2> + + <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_lang_toolchain_rule.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">proto_lang_toolchain(<a href="#proto_lang_toolchain.name">name</a>, <a href="#proto_lang_toolchain.allowlist_different_package">allowlist_different_package</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#proto_lang_toolchain.blacklisted_protos">blacklisted_protos</a>, <a href="#proto_lang_toolchain.command_line">command_line</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#proto_lang_toolchain.denylisted_protos">denylisted_protos</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#proto_lang_toolchain.mnemonic">mnemonic</a>, <a href="#proto_lang_toolchain.output_files">output_files</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#proto_lang_toolchain.plugin">plugin</a>, <a href="#proto_lang_toolchain.plugin_format_flag">plugin_format_flag</a>, <a href="#proto_lang_toolchain.progress_message">progress_message</a>, <a href="#proto_lang_toolchain.protoc_minimal_do_not_use">protoc_minimal_do_not_use</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#proto_lang_toolchain.runtime">runtime</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="#proto_lang_toolchain.toolchain_type">toolchain_type</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>If using Bazel, please load the rule from <a href="https://github.com/bazelbuild/rules_proto"> +https://github.com/bazelbuild/rules_proto</a>. + +<p>Specifies how a LANG_proto_library rule (e.g., <code>java_proto_library</code>) should invoke the +proto-compiler. +Some LANG_proto_library rules allow specifying which toolchain to use using command-line flags; +consult their documentation. + +<p>Normally you should not write those kind of rules unless you want to +tune your Java compiler. + +<p>There's no compiler. The proto-compiler is taken from the proto_library rule we attach to. It is +passed as a command-line flag to Blaze. +Several features require a proto-compiler to be invoked on the proto_library rule itself. +It's beneficial to enforce the compiler that LANG_proto_library uses is the same as the one +<code>proto_library</code> does. + +<h4>Examples</h4> + +<p>A simple example would be: +<pre><code class="lang-starlark"> +proto_lang_toolchain( + name = "javalite_toolchain", + command_line = "--javalite_out=shared,immutable:$(OUT)", + plugin = ":javalite_plugin", + runtime = ":protobuf_lite", +) +</code></pre> + + <h3 id="proto_lang_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="proto_lang_toolchain.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.allowlist_different_package"> + <code>allowlist_different_package</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.blacklisted_protos"> + <code>blacklisted_protos</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Deprecated. Alias for <code>denylisted_protos</code>. Will be removed in a future release. + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.command_line"> + <code>command_line</code> + </td> + <td> + <p>String; required</p> + This value will be passed to proto-compiler to generate the code. Only include the parts +specific to this code-generator/plugin (e.g., do not include -I parameters) +<ul> + <li><code>$(OUT)</code> is LANG_proto_library-specific. The rules are expected to define + how they interpret this variable. For Java, for example, $(OUT) will be replaced with + the src-jar filename to create.</li> +</ul> + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.denylisted_protos"> + <code>denylisted_protos</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + No code will be generated for files in the <code>srcs</code> attribute of +<code>denylisted_protos</code>. +This is used for .proto files that are already linked into proto runtimes, such as +<code>any.proto</code>. + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.mnemonic"> + <code>mnemonic</code> + </td> + <td> + <p>String; default is <code>"GenProto"</code></p> + This value will be set as the mnemonic on protoc action. + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.output_files"> + <code>output_files</code> + </td> + <td> + <p>String; default is <code>"legacy"</code></p> + Controls how <code>$(OUT)</code> in <code>command_line</code> is formatted, either by +a path to a single file or output directory in case of multiple files. +Possible values are: "single", "multiple". + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.plugin"> + <code>plugin</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + If provided, will be made available to the action that calls the proto-compiler, and will be +passed to the proto-compiler: +<code>--plugin=protoc-gen-PLUGIN=<executable>.</code> + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.plugin_format_flag"> + <code>plugin_format_flag</code> + </td> + <td> + <p>String; default is <code>""</code></p> + If provided, this value will be passed to proto-compiler to use the plugin. +The value must contain a single %s which is replaced with plugin executable. +<code>--plugin=protoc-gen-PLUGIN=<executable>.</code> + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.progress_message"> + <code>progress_message</code> + </td> + <td> + <p>String; default is <code>"Generating proto_library %{label}"</code></p> + This value will be set as the progress message on protoc action. + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.protoc_minimal_do_not_use"> + <code>protoc_minimal_do_not_use</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.runtime"> + <code>runtime</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + A language-specific library that the generated code is compiled against. +The exact behavior is LANG_proto_library-specific. +Java, for example, should compile against the runtime. + </td> + </tr> + <tr> + <td id="proto_lang_toolchain.toolchain_type"> + <code>toolchain_type</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + + </td> + </tr> + </tbody> + </table> + <h2 id="proto_toolchain"> + proto_toolchain + </h2> + + <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_toolchain_rule.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">proto_toolchain(<a href="#proto_toolchain.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#proto_toolchain.command_line">command_line</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#proto_toolchain.mnemonic">mnemonic</a>, <a href="#proto_toolchain.output_files">output_files</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#proto_toolchain.progress_message">progress_message</a>, <a href="#proto_toolchain.proto_compiler">proto_compiler</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + + + <h3 id="proto_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="proto_toolchain.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="proto_toolchain.command_line"> + <code>command_line</code> + </td> + <td> + <p>String; default is <code>"--descriptor_set_out=%s"</code></p> + + </td> + </tr> + <tr> + <td id="proto_toolchain.mnemonic"> + <code>mnemonic</code> + </td> + <td> + <p>String; default is <code>"GenProtoDescriptorSet"</code></p> + + </td> + </tr> + <tr> + <td id="proto_toolchain.output_files"> + <code>output_files</code> + </td> + <td> + <p>String; default is <code>"single"</code></p> + + </td> + </tr> + <tr> + <td id="proto_toolchain.progress_message"> + <code>progress_message</code> + </td> + <td> + <p>String; default is <code>"Generating Descriptor Set proto_library %{label}"</code></p> + + </td> + </tr> + <tr> + <td id="proto_toolchain.proto_compiler"> + <code>proto_compiler</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/python.mdx b/reference/be/python.mdx new file mode 100644 index 0000000..08c4174 --- /dev/null +++ b/reference/be/python.mdx @@ -0,0 +1,1344 @@ +--- +title: 'python' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">Python Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% include "_buttons.html" %} + + + + +<h2>Rules</h2> +<ul> + <li> + <a href="#py_binary"> + py_binary </a> + </li> + <li> + <a href="#py_library"> + py_library </a> + </li> + <li> + <a href="#py_test"> + py_test </a> + </li> + <li> + <a href="#py_runtime"> + py_runtime </a> + </li> +</ul> + + <h2 id="py_binary"> + py_binary + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_binary_rule.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">py_binary(<a href="#py_binary.name">name</a>, <a href="#py_binary.deps">deps</a>, <a href="#py_binary.srcs">srcs</a>, <a href="#py_binary.data">data</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#py_binary.distribs">distribs</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#py_binary.imports">imports</a>, <a href="#py_binary.interpreter_args">interpreter_args</a>, <a href="#py_binary.legacy_create_init">legacy_create_init</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#py_binary.main">main</a>, <a href="#py_binary.main_module">main_module</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#py_binary.precompile">precompile</a>, <a href="#py_binary.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_binary.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_binary.precompile_source_retention">precompile_source_retention</a>, <a href="#py_binary.pyc_collection">pyc_collection</a>, <a href="#py_binary.pyi_deps">pyi_deps</a>, <a href="#py_binary.pyi_srcs">pyi_srcs</a>, <a href="#py_binary.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_binary.srcs_version">srcs_version</a>, <a href="#py_binary.stamp">stamp</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + + + <h3 id="py_binary_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="py_binary.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="py_binary.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + List of additional libraries to be linked in to the target. +See comments about +the [`deps` attribute typically defined by +rules](https://bazel.build/reference/be/common-definitions#typical-attributes). +These are typically `py_library` rules. + +Targets that only provide data files used at runtime belong in the `data` +attribute. + +:::{note} +The order of this list can matter because it affects the order that information +from dependencies is merged in, which can be relevant depending on the ordering +mode of depsets that are merged. + +* {obj}`PyInfo.site_packages_symlinks` uses topological ordering. + +See {obj}`PyInfo` for more information about the ordering of its depsets and +how its fields are merged. +::: + </td> + </tr> + <tr> + <td id="py_binary.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The +`.py` files belong in `srcs` and library targets belong in `deps`. Other binary +files that may be needed at run time belong in `data`. + </td> + </tr> + <tr> + <td id="py_binary.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files need by this library at runtime. See comments about +the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). + +There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. +This is because Python has a concept of runtime resources. + </td> + </tr> + <tr> + <td id="py_binary.distribs"> + <code>distribs</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="py_binary.imports"> + <code>imports</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of import directories to be added to the PYTHONPATH. + +Subject to "Make variable" substitution. These import directories will be added +for this rule and all rules that depend on it (note: not the rules this rule +depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules +that depend on this rule. The strings are repo-runfiles-root relative, + +Absolute paths (paths that start with `/`) and paths that references a path +above the execution root are not allowed and will result in an error. + </td> + </tr> + <tr> + <td id="py_binary.interpreter_args"> + <code>interpreter_args</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Arguments that are only applicable to the interpreter. + +The args an interpreter supports are specific to the interpreter. For +CPython, see https://docs.python.org/3/using/cmdline.html. + +:::{note} +Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise. +::: + +:::{seealso} +The {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable +::: + +:::{versionadded} 1.3.0 +::: + </td> + </tr> + <tr> + <td id="py_binary.legacy_create_init"> + <code>legacy_create_init</code> + </td> + <td> + <p>Integer; default is <code>-1</code></p> + Whether to implicitly create empty `__init__.py` files in the runfiles tree. +These are created in every directory containing Python source code or shared +libraries, and every parent directory of those directories, excluding the repo +root directory. The default, `-1` (auto), means true unless +`--incompatible_default_to_explicit_init_py` is used. If false, the user is +responsible for creating (possibly empty) `__init__.py` files and adding them to +the `srcs` of Python targets as required. + </td> + </tr> + <tr> + <td id="py_binary.main"> + <code>main</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Optional; the name of the source file that is the main entry point of the +application. This file must also be listed in `srcs`. If left unspecified, +`name`, with `.py` appended, is used instead. If `name` does not match any +filename in `srcs`, `main` must be specified. + +This is mutually exclusive with {obj}`main_module`. + </td> + </tr> + <tr> + <td id="py_binary.main_module"> + <code>main_module</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Module name to execute as the main program. + +When set, `srcs` is not required, and it is assumed the module is +provided by a dependency. + +See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more +information about running modules as the main program. + +This is mutually exclusive with {obj}`main`. + +:::{versionadded} 1.3.0 +::: + </td> + </tr> + <tr> + <td id="py_binary.precompile"> + <code>precompile</code> + </td> + <td> + <p>String; default is <code>"inherit"</code></p> + Whether py source files **for this target** should be precompiled. + +Values: + +* `inherit`: Allow the downstream binary decide if precompiled files are used. +* `enabled`: Compile Python source files at build time. +* `disabled`: Don't compile Python source files at build time. + +:::{seealso} + +* The {flag}`--precompile` flag, which can override this attribute in some cases + and will affect all targets when building. +* The {obj}`pyc_collection` attribute for transitively enabling precompiling on + a per-target basis. +* The [Precompiling](precompiling) docs for a guide about using precompiling. +::: + </td> + </tr> + <tr> + <td id="py_binary.precompile_invalidation_mode"> + <code>precompile_invalidation_mode</code> + </td> + <td> + <p>String; default is <code>"auto"</code></p> + How precompiled files should be verified to be up-to-date with their associated +source files. Possible values are: +* `auto`: The effective value will be automatically determined by other build + settings. +* `checked_hash`: Use the pyc file if the hash of the source file matches the hash + recorded in the pyc file. This is most useful when working with code that + you may modify. +* `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against + the source file. This is most useful when the code won't be modified. + +For more information on pyc invalidation modes, see +https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode + </td> + </tr> + <tr> + <td id="py_binary.precompile_optimize_level"> + <code>precompile_optimize_level</code> + </td> + <td> + <p>Integer; default is <code>0</code></p> + The optimization level for precompiled files. + +For more information about optimization levels, see the `compile()` function's +`optimize` arg docs at https://docs.python.org/3/library/functions.html#compile + +NOTE: The value `-1` means "current interpreter", which will be the interpreter +used _at build time when pycs are generated_, not the interpreter used at +runtime when the code actually runs. + </td> + </tr> + <tr> + <td id="py_binary.precompile_source_retention"> + <code>precompile_source_retention</code> + </td> + <td> + <p>String; default is <code>"inherit"</code></p> + Determines, when a source file is compiled, if the source file is kept +in the resulting output or not. Valid values are: + +* `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. +* `keep_source`: Include the original Python source. +* `omit_source`: Don't include the original py source. + </td> + </tr> + <tr> + <td id="py_binary.pyc_collection"> + <code>pyc_collection</code> + </td> + <td> + <p>String; default is <code>"inherit"</code></p> + Determines whether pyc files from dependencies should be manually included. + +Valid values are: +* `inherit`: Inherit the value from {flag}`--precompile`. +* `include_pyc`: Add implicitly generated pyc files from dependencies. i.e. + pyc files for targets that specify {attr}`precompile="inherit"`. +* `disabled`: Don't add implicitly generated pyc files. Note that + pyc files may still come from dependencies that enable precompiling at the + target level. + </td> + </tr> + <tr> + <td id="py_binary.pyi_deps"> + <code>pyi_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Dependencies providing type definitions the library needs. + +These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. +These are build-time only dependencies and not included as part of a runnable +program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + </td> + </tr> + <tr> + <td id="py_binary.pyi_srcs"> + <code>pyi_srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Type definition files for the library. + +These are typically `.pyi` files, but other file types for type-checker specific +formats are allowed. These files are build-time only dependencies and not included +as part of a runnable program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + </td> + </tr> + <tr> + <td id="py_binary.python_version"> + <code>python_version</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The Python version this target should use. + +The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or +unspecified, the incoming configuration's {obj}`--python_version` flag is +inherited. For backwards compatibility, the values `PY2` and `PY3` are +accepted, but treated as an empty/unspecified value. + +:::{note} +In order for the requested version to be used, there must be a +toolchain configured to match the Python version. If there isn't, then it +may be silently ignored, or an error may occur, depending on the toolchain +configuration. +::: + +:::{versionchanged} 1.1.0 + +This attribute was changed from only accepting `PY2` and `PY3` values to +accepting arbitrary Python versions. +::: + </td> + </tr> + <tr> + <td id="py_binary.srcs_version"> + <code>srcs_version</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Defunct, unused, does nothing. + </td> + </tr> + <tr> + <td id="py_binary.stamp"> + <code>stamp</code> + </td> + <td> + <p>Integer; default is <code>-1</code></p> + Whether to encode build information into the binary. Possible values: + +* `stamp = 1`: Always stamp the build information into the binary, even in + `--nostamp` builds. **This setting should be avoided**, since it potentially kills + remote caching for the binary and any downstream actions that depend on it. +* `stamp = 0`: Always replace build information by constant values. This gives + good build result caching. +* `stamp = -1`: Embedding of build information is controlled by the + `--[no]stamp` flag. + +Stamped binaries are not rebuilt unless their dependencies change. + +WARNING: Stamping can harm build performance by reducing cache hits and should +be avoided if possible. + </td> + </tr> + </tbody> + </table> + <h2 id="py_library"> + py_library + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_library_rule.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">py_library(<a href="#py_library.name">name</a>, <a href="#py_library.deps">deps</a>, <a href="#py_library.srcs">srcs</a>, <a href="#py_library.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#py_library.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#py_library.experimental_venvs_site_packages">experimental_venvs_site_packages</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#py_library.imports">imports</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#py_library.precompile">precompile</a>, <a href="#py_library.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_library.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_library.precompile_source_retention">precompile_source_retention</a>, <a href="#py_library.pyi_deps">pyi_deps</a>, <a href="#py_library.pyi_srcs">pyi_srcs</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_library.srcs_version">srcs_version</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + A library of Python code that can be depended upon. + +Default outputs: +* The input Python sources +* The precompiled artifacts from the sources. + +NOTE: Precompilation affects which of the default outputs are included in the +resulting runfiles. See the precompile-related attributes and flags for +more information. + +:::{versionchanged} 0.37.0 +Source files are no longer added to the runfiles directly. +::: + + <h3 id="py_library_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="py_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="py_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + List of additional libraries to be linked in to the target. +See comments about +the [`deps` attribute typically defined by +rules](https://bazel.build/reference/be/common-definitions#typical-attributes). +These are typically `py_library` rules. + +Targets that only provide data files used at runtime belong in the `data` +attribute. + +:::{note} +The order of this list can matter because it affects the order that information +from dependencies is merged in, which can be relevant depending on the ordering +mode of depsets that are merged. + +* {obj}`PyInfo.site_packages_symlinks` uses topological ordering. + +See {obj}`PyInfo` for more information about the ordering of its depsets and +how its fields are merged. +::: + </td> + </tr> + <tr> + <td id="py_library.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The +`.py` files belong in `srcs` and library targets belong in `deps`. Other binary +files that may be needed at run time belong in `data`. + </td> + </tr> + <tr> + <td id="py_library.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files need by this library at runtime. See comments about +the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). + +There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. +This is because Python has a concept of runtime resources. + </td> + </tr> + <tr> + <td id="py_library.distribs"> + <code>distribs</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="py_library.experimental_venvs_site_packages"> + <code>experimental_venvs_site_packages</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + **INTERNAL ATTRIBUTE. SHOULD ONLY BE SET BY rules_python-INTERNAL CODE.** + +:::{include} /_includes/experimental_api.md +::: + +A flag that decides whether the library should treat its sources as a +site-packages layout. + +When the flag is `yes`, then the `srcs` files are treated as a site-packages +layout that is relative to the `imports` attribute. The `imports` attribute +can have only a single element. It is a repo-relative runfiles path. + +For example, in the `my/pkg/BUILD.bazel` file, given +`srcs=["site-packages/foo/bar.py"]`, specifying +`imports=["my/pkg/site-packages"]` means `foo/bar.py` is the file path +under the binary's venv site-packages directory that should be made available (i.e. +`import foo.bar` will work). + +`__init__.py` files are treated specially to provide basic support for [implicit +namespace packages]( +https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages). +However, the *content* of the files cannot be taken into account, merely their +presence or absense. Stated another way: [pkgutil-style namespace packages]( +https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages) +won't be understood as namespace packages; they'll be seen as regular packages. This will +likely lead to conflicts with other targets that contribute to the namespace. + +:::{tip} +This attributes populates {obj}`PyInfo.site_packages_symlinks`, which is +a topologically ordered depset. This means dependencies closer and earlier +to a consumer have precedence. See {obj}`PyInfo.site_packages_symlinks` for +more information. +::: + +:::{versionadded} 1.4.0 +::: + </td> + </tr> + <tr> + <td id="py_library.imports"> + <code>imports</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of import directories to be added to the PYTHONPATH. + +Subject to "Make variable" substitution. These import directories will be added +for this rule and all rules that depend on it (note: not the rules this rule +depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules +that depend on this rule. The strings are repo-runfiles-root relative, + +Absolute paths (paths that start with `/`) and paths that references a path +above the execution root are not allowed and will result in an error. + </td> + </tr> + <tr> + <td id="py_library.precompile"> + <code>precompile</code> + </td> + <td> + <p>String; default is <code>"inherit"</code></p> + Whether py source files **for this target** should be precompiled. + +Values: + +* `inherit`: Allow the downstream binary decide if precompiled files are used. +* `enabled`: Compile Python source files at build time. +* `disabled`: Don't compile Python source files at build time. + +:::{seealso} + +* The {flag}`--precompile` flag, which can override this attribute in some cases + and will affect all targets when building. +* The {obj}`pyc_collection` attribute for transitively enabling precompiling on + a per-target basis. +* The [Precompiling](precompiling) docs for a guide about using precompiling. +::: + </td> + </tr> + <tr> + <td id="py_library.precompile_invalidation_mode"> + <code>precompile_invalidation_mode</code> + </td> + <td> + <p>String; default is <code>"auto"</code></p> + How precompiled files should be verified to be up-to-date with their associated +source files. Possible values are: +* `auto`: The effective value will be automatically determined by other build + settings. +* `checked_hash`: Use the pyc file if the hash of the source file matches the hash + recorded in the pyc file. This is most useful when working with code that + you may modify. +* `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against + the source file. This is most useful when the code won't be modified. + +For more information on pyc invalidation modes, see +https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode + </td> + </tr> + <tr> + <td id="py_library.precompile_optimize_level"> + <code>precompile_optimize_level</code> + </td> + <td> + <p>Integer; default is <code>0</code></p> + The optimization level for precompiled files. + +For more information about optimization levels, see the `compile()` function's +`optimize` arg docs at https://docs.python.org/3/library/functions.html#compile + +NOTE: The value `-1` means "current interpreter", which will be the interpreter +used _at build time when pycs are generated_, not the interpreter used at +runtime when the code actually runs. + </td> + </tr> + <tr> + <td id="py_library.precompile_source_retention"> + <code>precompile_source_retention</code> + </td> + <td> + <p>String; default is <code>"inherit"</code></p> + Determines, when a source file is compiled, if the source file is kept +in the resulting output or not. Valid values are: + +* `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. +* `keep_source`: Include the original Python source. +* `omit_source`: Don't include the original py source. + </td> + </tr> + <tr> + <td id="py_library.pyi_deps"> + <code>pyi_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Dependencies providing type definitions the library needs. + +These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. +These are build-time only dependencies and not included as part of a runnable +program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + </td> + </tr> + <tr> + <td id="py_library.pyi_srcs"> + <code>pyi_srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Type definition files for the library. + +These are typically `.pyi` files, but other file types for type-checker specific +formats are allowed. These files are build-time only dependencies and not included +as part of a runnable program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + </td> + </tr> + <tr> + <td id="py_library.srcs_version"> + <code>srcs_version</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Defunct, unused, does nothing. + </td> + </tr> + </tbody> + </table> + <h2 id="py_test"> + py_test + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_test_rule.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">py_test(<a href="#py_test.name">name</a>, <a href="#py_test.deps">deps</a>, <a href="#py_test.srcs">srcs</a>, <a href="#py_test.data">data</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#py_test.distribs">distribs</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#test.flaky">flaky</a>, <a href="#py_test.imports">imports</a>, <a href="#py_test.interpreter_args">interpreter_args</a>, <a href="#py_test.legacy_create_init">legacy_create_init</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#py_test.main">main</a>, <a href="#py_test.main_module">main_module</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#py_test.precompile">precompile</a>, <a href="#py_test.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_test.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_test.precompile_source_retention">precompile_source_retention</a>, <a href="#py_test.pyc_collection">pyc_collection</a>, <a href="#py_test.pyi_deps">pyi_deps</a>, <a href="#py_test.pyi_srcs">pyi_srcs</a>, <a href="#py_test.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#py_test.srcs_version">srcs_version</a>, <a href="#py_test.stamp">stamp</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#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + + + <h3 id="py_test_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="py_test.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="py_test.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + List of additional libraries to be linked in to the target. +See comments about +the [`deps` attribute typically defined by +rules](https://bazel.build/reference/be/common-definitions#typical-attributes). +These are typically `py_library` rules. + +Targets that only provide data files used at runtime belong in the `data` +attribute. + +:::{note} +The order of this list can matter because it affects the order that information +from dependencies is merged in, which can be relevant depending on the ordering +mode of depsets that are merged. + +* {obj}`PyInfo.site_packages_symlinks` uses topological ordering. + +See {obj}`PyInfo` for more information about the ordering of its depsets and +how its fields are merged. +::: + </td> + </tr> + <tr> + <td id="py_test.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The +`.py` files belong in `srcs` and library targets belong in `deps`. Other binary +files that may be needed at run time belong in `data`. + </td> + </tr> + <tr> + <td id="py_test.data"> + <code>data</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of files need by this library at runtime. See comments about +the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). + +There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. +This is because Python has a concept of runtime resources. + </td> + </tr> + <tr> + <td id="py_test.distribs"> + <code>distribs</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="py_test.imports"> + <code>imports</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + List of import directories to be added to the PYTHONPATH. + +Subject to "Make variable" substitution. These import directories will be added +for this rule and all rules that depend on it (note: not the rules this rule +depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules +that depend on this rule. The strings are repo-runfiles-root relative, + +Absolute paths (paths that start with `/`) and paths that references a path +above the execution root are not allowed and will result in an error. + </td> + </tr> + <tr> + <td id="py_test.interpreter_args"> + <code>interpreter_args</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + Arguments that are only applicable to the interpreter. + +The args an interpreter supports are specific to the interpreter. For +CPython, see https://docs.python.org/3/using/cmdline.html. + +:::{note} +Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise. +::: + +:::{seealso} +The {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable +::: + +:::{versionadded} 1.3.0 +::: + </td> + </tr> + <tr> + <td id="py_test.legacy_create_init"> + <code>legacy_create_init</code> + </td> + <td> + <p>Integer; default is <code>-1</code></p> + Whether to implicitly create empty `__init__.py` files in the runfiles tree. +These are created in every directory containing Python source code or shared +libraries, and every parent directory of those directories, excluding the repo +root directory. The default, `-1` (auto), means true unless +`--incompatible_default_to_explicit_init_py` is used. If false, the user is +responsible for creating (possibly empty) `__init__.py` files and adding them to +the `srcs` of Python targets as required. + </td> + </tr> + <tr> + <td id="py_test.main"> + <code>main</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + Optional; the name of the source file that is the main entry point of the +application. This file must also be listed in `srcs`. If left unspecified, +`name`, with `.py` appended, is used instead. If `name` does not match any +filename in `srcs`, `main` must be specified. + +This is mutually exclusive with {obj}`main_module`. + </td> + </tr> + <tr> + <td id="py_test.main_module"> + <code>main_module</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Module name to execute as the main program. + +When set, `srcs` is not required, and it is assumed the module is +provided by a dependency. + +See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more +information about running modules as the main program. + +This is mutually exclusive with {obj}`main`. + +:::{versionadded} 1.3.0 +::: + </td> + </tr> + <tr> + <td id="py_test.precompile"> + <code>precompile</code> + </td> + <td> + <p>String; default is <code>"inherit"</code></p> + Whether py source files **for this target** should be precompiled. + +Values: + +* `inherit`: Allow the downstream binary decide if precompiled files are used. +* `enabled`: Compile Python source files at build time. +* `disabled`: Don't compile Python source files at build time. + +:::{seealso} + +* The {flag}`--precompile` flag, which can override this attribute in some cases + and will affect all targets when building. +* The {obj}`pyc_collection` attribute for transitively enabling precompiling on + a per-target basis. +* The [Precompiling](precompiling) docs for a guide about using precompiling. +::: + </td> + </tr> + <tr> + <td id="py_test.precompile_invalidation_mode"> + <code>precompile_invalidation_mode</code> + </td> + <td> + <p>String; default is <code>"auto"</code></p> + How precompiled files should be verified to be up-to-date with their associated +source files. Possible values are: +* `auto`: The effective value will be automatically determined by other build + settings. +* `checked_hash`: Use the pyc file if the hash of the source file matches the hash + recorded in the pyc file. This is most useful when working with code that + you may modify. +* `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against + the source file. This is most useful when the code won't be modified. + +For more information on pyc invalidation modes, see +https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode + </td> + </tr> + <tr> + <td id="py_test.precompile_optimize_level"> + <code>precompile_optimize_level</code> + </td> + <td> + <p>Integer; default is <code>0</code></p> + The optimization level for precompiled files. + +For more information about optimization levels, see the `compile()` function's +`optimize` arg docs at https://docs.python.org/3/library/functions.html#compile + +NOTE: The value `-1` means "current interpreter", which will be the interpreter +used _at build time when pycs are generated_, not the interpreter used at +runtime when the code actually runs. + </td> + </tr> + <tr> + <td id="py_test.precompile_source_retention"> + <code>precompile_source_retention</code> + </td> + <td> + <p>String; default is <code>"inherit"</code></p> + Determines, when a source file is compiled, if the source file is kept +in the resulting output or not. Valid values are: + +* `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. +* `keep_source`: Include the original Python source. +* `omit_source`: Don't include the original py source. + </td> + </tr> + <tr> + <td id="py_test.pyc_collection"> + <code>pyc_collection</code> + </td> + <td> + <p>String; default is <code>"inherit"</code></p> + Determines whether pyc files from dependencies should be manually included. + +Valid values are: +* `inherit`: Inherit the value from {flag}`--precompile`. +* `include_pyc`: Add implicitly generated pyc files from dependencies. i.e. + pyc files for targets that specify {attr}`precompile="inherit"`. +* `disabled`: Don't add implicitly generated pyc files. Note that + pyc files may still come from dependencies that enable precompiling at the + target level. + </td> + </tr> + <tr> + <td id="py_test.pyi_deps"> + <code>pyi_deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Dependencies providing type definitions the library needs. + +These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. +These are build-time only dependencies and not included as part of a runnable +program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + </td> + </tr> + <tr> + <td id="py_test.pyi_srcs"> + <code>pyi_srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + Type definition files for the library. + +These are typically `.pyi` files, but other file types for type-checker specific +formats are allowed. These files are build-time only dependencies and not included +as part of a runnable program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + </td> + </tr> + <tr> + <td id="py_test.python_version"> + <code>python_version</code> + </td> + <td> + <p>String; default is <code>""</code></p> + The Python version this target should use. + +The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or +unspecified, the incoming configuration's {obj}`--python_version` flag is +inherited. For backwards compatibility, the values `PY2` and `PY3` are +accepted, but treated as an empty/unspecified value. + +:::{note} +In order for the requested version to be used, there must be a +toolchain configured to match the Python version. If there isn't, then it +may be silently ignored, or an error may occur, depending on the toolchain +configuration. +::: + +:::{versionchanged} 1.1.0 + +This attribute was changed from only accepting `PY2` and `PY3` values to +accepting arbitrary Python versions. +::: + </td> + </tr> + <tr> + <td id="py_test.srcs_version"> + <code>srcs_version</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Defunct, unused, does nothing. + </td> + </tr> + <tr> + <td id="py_test.stamp"> + <code>stamp</code> + </td> + <td> + <p>Integer; default is <code>0</code></p> + Whether to encode build information into the binary. Possible values: + +* `stamp = 1`: Always stamp the build information into the binary, even in + `--nostamp` builds. **This setting should be avoided**, since it potentially kills + remote caching for the binary and any downstream actions that depend on it. +* `stamp = 0`: Always replace build information by constant values. This gives + good build result caching. +* `stamp = -1`: Embedding of build information is controlled by the + `--[no]stamp` flag. + +Stamped binaries are not rebuilt unless their dependencies change. + +WARNING: Stamping can harm build performance by reducing cache hits and should +be avoided if possible. + </td> + </tr> + </tbody> + </table> + <h2 id="py_runtime"> + py_runtime + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_runtime_rule.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">py_runtime(<a href="#py_runtime.name">name</a>, <a href="#py_runtime.abi_flags">abi_flags</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#py_runtime.bootstrap_template">bootstrap_template</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#py_runtime.coverage_tool">coverage_tool</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#py_runtime.files">files</a>, <a href="#py_runtime.implementation_name">implementation_name</a>, <a href="#py_runtime.interpreter">interpreter</a>, <a href="#py_runtime.interpreter_path">interpreter_path</a>, <a href="#py_runtime.interpreter_version_info">interpreter_version_info</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#py_runtime.pyc_tag">pyc_tag</a>, <a href="#py_runtime.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_runtime.site_init_template">site_init_template</a>, <a href="#py_runtime.stage2_bootstrap_template">stage2_bootstrap_template</a>, <a href="#py_runtime.stub_shebang">stub_shebang</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#py_runtime.zip_main_template">zip_main_template</a>)</pre> + + Represents a Python runtime used to execute Python code. + +A `py_runtime` target can represent either a *platform runtime* or an *in-build +runtime*. A platform runtime accesses a system-installed interpreter at a known +path, whereas an in-build runtime points to an executable target that acts as +the interpreter. In both cases, an "interpreter" means any executable binary or +wrapper script that is capable of running a Python script passed on the command +line, following the same conventions as the standard CPython interpreter. + +A platform runtime is by its nature non-hermetic. It imposes a requirement on +the target platform to have an interpreter located at a specific path. An +in-build runtime may or may not be hermetic, depending on whether it points to +a checked-in interpreter or a wrapper script that accesses the system +interpreter. + +Example + +``` +load("@rules_python//python:py_runtime.bzl", "py_runtime") + +py_runtime( + name = "python-2.7.12", + files = glob(["python-2.7.12/**"]), + interpreter = "python-2.7.12/bin/python", +) + +py_runtime( + name = "python-3.6.0", + interpreter_path = "/opt/pyenv/versions/3.6.0/bin/python", +) +``` + + <h3 id="py_runtime_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="py_runtime.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="py_runtime.abi_flags"> + <code>abi_flags</code> + </td> + <td> + <p>String; default is <code>"<AUTO>"</code></p> + The runtime's ABI flags, i.e. `sys.abiflags`. + +If not set, then it will be set based on flags. + </td> + </tr> + <tr> + <td id="py_runtime.bootstrap_template"> + <code>bootstrap_template</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:bootstrap_template"</code></p> + The bootstrap script template file to use. Should have %python_binary%, +%workspace_name%, %main%, and %imports%. + +This template, after expansion, becomes the executable file used to start the +process, so it is responsible for initial bootstrapping actions such as finding +the Python interpreter, runfiles, and constructing an environment to run the +intended Python application. + +While this attribute is currently optional, it will become required when the +Python rules are moved out of Bazel itself. + +The exact variable names expanded is an unstable API and is subject to change. +The API will become more stable when the Python rules are moved out of Bazel +itself. + +See @bazel_tools//tools/python:python_bootstrap_template.txt for more variables. + </td> + </tr> + <tr> + <td id="py_runtime.coverage_tool"> + <code>coverage_tool</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + This is a target to use for collecting code coverage information from +{rule}`py_binary` and {rule}`py_test` targets. + +If set, the target must either produce a single file or be an executable target. +The path to the single file, or the executable if the target is executable, +determines the entry point for the python coverage tool. The target and its +runfiles will be added to the runfiles when coverage is enabled. + +The entry point for the tool must be loadable by a Python interpreter (e.g. a +`.py` or `.pyc` file). It must accept the command line arguments +of [`coverage.py`](https://coverage.readthedocs.io), at least including +the `run` and `lcov` subcommands. + </td> + </tr> + <tr> + <td id="py_runtime.files"> + <code>files</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + For an in-build runtime, this is the set of files comprising this runtime. +These files will be added to the runfiles of Python binaries that use this +runtime. For a platform runtime this attribute must not be set. + </td> + </tr> + <tr> + <td id="py_runtime.implementation_name"> + <code>implementation_name</code> + </td> + <td> + <p>String; default is <code>"cpython"</code></p> + The Python implementation name (`sys.implementation.name`) + </td> + </tr> + <tr> + <td id="py_runtime.interpreter"> + <code>interpreter</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> + For an in-build runtime, this is the target to invoke as the interpreter. It +can be either of: + +* A single file, which will be the interpreter binary. It's assumed such + interpreters are either self-contained single-file executables or any + supporting files are specified in `files`. +* An executable target. The target's executable will be the interpreter binary. + Any other default outputs (`target.files`) and plain files runfiles + (`runfiles.files`) will be automatically included as if specified in the + `files` attribute. + + NOTE: the runfiles of the target may not yet be properly respected/propagated + to consumers of the toolchain/interpreter, see + bazel-contrib/rules_python/issues/1612 + +For a platform runtime (i.e. `interpreter_path` being set) this attribute must +not be set. + </td> + </tr> + <tr> + <td id="py_runtime.interpreter_path"> + <code>interpreter_path</code> + </td> + <td> + <p>String; default is <code>""</code></p> + For a platform runtime, this is the absolute path of a Python interpreter on +the target platform. For an in-build runtime this attribute must not be set. + </td> + </tr> + <tr> + <td id="py_runtime.interpreter_version_info"> + <code>interpreter_version_info</code> + </td> + <td> + <p>Dictionary: String -> String; default is <code>{}</code></p> + Version information about the interpreter this runtime provides. + +If not specified, uses {obj}`--python_version` + +The supported keys match the names for `sys.version_info`. While the input +values are strings, most are converted to ints. The supported keys are: + * major: int, the major version number + * minor: int, the minor version number + * micro: optional int, the micro version number + * releaselevel: optional str, the release level + * serial: optional int, the serial number of the release + +:::{versionchanged} 0.36.0 +{obj}`--python_version` determines the default value. +::: + </td> + </tr> + <tr> + <td id="py_runtime.pyc_tag"> + <code>pyc_tag</code> + </td> + <td> + <p>String; default is <code>""</code></p> + Optional string; the tag portion of a pyc filename, e.g. the `cpython-39` infix +of `foo.cpython-39.pyc`. See PEP 3147. If not specified, it will be computed +from `implementation_name` and `interpreter_version_info`. If no pyc_tag is +available, then only source-less pyc generation will function correctly. + </td> + </tr> + <tr> + <td id="py_runtime.python_version"> + <code>python_version</code> + </td> + <td> + <p>String; default is <code>"PY3"</code></p> + Whether this runtime is for Python major version 2 or 3. Valid values are `"PY2"` +and `"PY3"`. + +The default value is controlled by the `--incompatible_py3_is_default` flag. +However, in the future this attribute will be mandatory and have no default +value. + </td> + </tr> + <tr> + <td id="py_runtime.site_init_template"> + <code>site_init_template</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:site_init_template"</code></p> + The template to use for the binary-specific site-init hook run by the +interpreter at startup. + +:::{versionadded} 0.41.0 +::: + </td> + </tr> + <tr> + <td id="py_runtime.stage2_bootstrap_template"> + <code>stage2_bootstrap_template</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:stage2_bootstrap_template"</code></p> + The template to use when two stage bootstrapping is enabled + +:::{seealso} +{obj}`PyRuntimeInfo.stage2_bootstrap_template` and {obj}`--bootstrap_impl` +::: + </td> + </tr> + <tr> + <td id="py_runtime.stub_shebang"> + <code>stub_shebang</code> + </td> + <td> + <p>String; default is <code>"#!/usr/bin/env python3"</code></p> + "Shebang" expression prepended to the bootstrapping Python stub script +used when executing {rule}`py_binary` targets. + +See https://github.com/bazelbuild/bazel/issues/8685 for +motivation. + +Does not apply to Windows. + </td> + </tr> + <tr> + <td id="py_runtime.zip_main_template"> + <code>zip_main_template</code> + </td> + <td> + <p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:zip_main_template"</code></p> + The template to use for a zip's top-level `__main__.py` file. + +This becomes the entry point executed when `python foo.zip` is run. + +:::{seealso} +The {obj}`PyRuntimeInfo.zip_main_template` field. +::: + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/be/shell.mdx b/reference/be/shell.mdx new file mode 100644 index 0000000..50f85c5 --- /dev/null +++ b/reference/be/shell.mdx @@ -0,0 +1,341 @@ +--- +title: 'shell' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_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">Shell Rules</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} +{% include "_buttons.html" %} + + + + +<h2>Rules</h2> +<ul> + <li> + <a href="#sh_binary"> + sh_binary </a> + </li> + <li> + <a href="#sh_library"> + sh_library </a> + </li> + <li> + <a href="#sh_test"> + sh_test </a> + </li> +</ul> + + <h2 id="sh_binary"> + sh_binary + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_binary.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">sh_binary(<a href="#sh_binary.name">name</a>, <a href="#sh_binary.deps">deps</a>, <a href="#sh_binary.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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#binary.env">env</a>, <a href="#sh_binary.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="#sh_binary.use_bash_launcher">use_bash_launcher</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> + The <code>sh_binary</code> rule is used to declare executable shell scripts. + (<code>sh_binary</code> is a misnomer: its outputs aren't necessarily binaries.) This rule ensures + that all dependencies are built, and appear in the <code>runfiles</code> area at execution time. + We recommend that you name your <code>sh_binary()</code> rules after the name of the script minus + the extension (e.g. <code>.sh</code>); the rule name and the file name must be distinct. + <code>sh_binary</code> respects shebangs, so any available interpreter may be used (eg. + <code>#!/bin/zsh</code>) +</p> +<h4 id="sh_binary_examples">Example</h4> +<p>For a simple shell script with no dependencies and some data files: +</p> +<pre class="code"> +sh_binary( + name = "foo", + srcs = ["foo.sh"], + data = glob(["datafiles/*.txt"]), +) +</pre> + + <h3 id="sh_binary_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="sh_binary.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="sh_binary.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of "library" targets to be aggregated into this target. +See general comments about <code>deps</code> +at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by +most build rules</a>. +<p> + This attribute should be used to list other <code>sh_library</code> rules that provide + interpreted program source code depended on by the code in <code>srcs</code>. The files + provided by these rules will be present among the <code>runfiles</code> of this target. +</p> + </td> + </tr> + <tr> + <td id="sh_binary.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The file containing the shell script. +<p> + This attribute must be a singleton list, whose element is the shell script. + This script must be executable, and may be a source file or a generated file. + All other files required at runtime (whether scripts or data) belong in the + <code>data</code> attribute. +</p> + </td> + </tr> + <tr> + <td id="sh_binary.env_inherit"> + <code>env_inherit</code> + </td> + <td> + <p>List of strings; default is <code>[]</code></p> + + </td> + </tr> + <tr> + <td id="sh_binary.use_bash_launcher"> + <code>use_bash_launcher</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Use a bash launcher initializing the runfiles library + </td> + </tr> + </tbody> + </table> + <h2 id="sh_library"> + sh_library + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_library.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">sh_library(<a href="#sh_library.name">name</a>, <a href="#sh_library.deps">deps</a>, <a href="#sh_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p> + The main use for this rule is to aggregate together a logical + "library" consisting of related scripts—programs in an + interpreted language that does not require compilation or linking, + such as the Bourne shell—and any data those programs need at + run-time. Such "libraries" can then be used from + the <code>data</code> attribute of one or + more <code>sh_binary</code> rules. +</p> + +<p> + You can use the <a href="/reference/be/general.html#filegroup"><code>filegroup</code></a> rule to aggregate data + files. +</p> + +<p> + In interpreted programming languages, there's not always a clear + distinction between "code" and "data": after all, the program is + just "data" from the interpreter's point of view. For this reason + this rule has three attributes which are all essentially equivalent: + <code>srcs</code>, <code>deps</code> and <code>data</code>. + The current implementation does not distinguish between the elements of these lists. + All three attributes accept rules, source files and generated files. + It is however good practice to use the attributes for their usual purpose (as with other rules). +</p> + +<h4 id="sh_library_examples">Examples</h4> + +<pre class="code"> +sh_library( + name = "foo", + data = [ + ":foo_service_script", # an sh_binary with srcs + ":deploy_foo", # another sh_binary with srcs + ], +) +</pre> + + <h3 id="sh_library_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="sh_library.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="sh_library.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of "library" targets to be aggregated into this target. +See general comments about <code>deps</code> +at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by +most build rules</a>. +<p> + This attribute should be used to list other <code>sh_library</code> rules that provide + interpreted program source code depended on by the code in <code>srcs</code>. The files + provided by these rules will be present among the <code>runfiles</code> of this target. +</p> + </td> + </tr> + <tr> + <td id="sh_library.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of input files. +<p> + This attribute should be used to list shell script source files that belong to + this library. Scripts can load other scripts using the shell's <code>source</code> + or <code>.</code> command. +</p> + </td> + </tr> + </tbody> + </table> + <h2 id="sh_test"> + sh_test + </h2> + + <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_test.bzl" target="_blank"> + View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> + </a> + + <pre class="rule-signature">sh_test(<a href="#sh_test.name">name</a>, <a href="#sh_test.deps">deps</a>, <a href="#sh_test.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#test.flaky">flaky</a>, <a href="common-definitions.html#test.local">local</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</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#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="#sh_test.use_bash_launcher">use_bash_launcher</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> + + <p>A <code>sh_test()</code> rule creates a test written as a Bourne shell script.</p> + +<p>See the <a href="/reference/be/common-definitions#common-attributes-tests"> +attributes common to all test rules (*_test)</a>.</p> + +<h4 id="sh_test_examples">Examples</h4> + +<pre class="code"> +sh_test( + name = "foo_integration_test", + size = "small", + srcs = ["foo_integration_test.sh"], + deps = [":foo_sh_lib"], + data = glob(["testdata/*.txt"]), +) +</pre> + + <h3 id="sh_test_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="sh_test.name"><code>name</code></td> + <td> + <p><a href="/concepts/labels#target-names">Name</a>; required</p> + <p>A unique name for this target.</p> + + </td> + </tr> + <tr> + <td id="sh_test.deps"> + <code>deps</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The list of "library" targets to be aggregated into this target. +See general comments about <code>deps</code> +at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by +most build rules</a>. +<p> + This attribute should be used to list other <code>sh_library</code> rules that provide + interpreted program source code depended on by the code in <code>srcs</code>. The files + provided by these rules will be present among the <code>runfiles</code> of this target. +</p> + </td> + </tr> + <tr> + <td id="sh_test.srcs"> + <code>srcs</code> + </td> + <td> + <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> + The file containing the shell script. +<p> + This attribute must be a singleton list, whose element is the shell script. + This script must be executable, and may be a source file or a generated file. + All other files required at runtime (whether scripts or data) belong in the + <code>data</code> attribute. +</p> + </td> + </tr> + <tr> + <td id="sh_test.use_bash_launcher"> + <code>use_bash_launcher</code> + </td> + <td> + <p>Boolean; default is <code>False</code></p> + Use a bash launcher initializing the runfiles library + </td> + </tr> + </tbody> + </table> + +<!-- Generated footer --> + +</body> +</html> diff --git a/reference/command-line-reference.mdx b/reference/command-line-reference.mdx new file mode 100644 index 0000000..cf6021e --- /dev/null +++ b/reference/command-line-reference.mdx @@ -0,0 +1,12297 @@ +--- +title: 'Command-Line Reference' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title">Command-Line Reference</h1> + +{% dynamic setvar source_file "site/command-line-reference-prefix.html" %} +{% include "_buttons.html" %} + +<pre> +bazel [<startup options>] <command> [<args>] +</pre> + +or + +<pre> +bazel [<startup options>] <command> [<args>] -- [<target patterns>] +</pre> + +See the <a href="/docs/build#specifying-build-targets">User's Guide</a> for the +target patterns syntax. + +<h2>Option Syntax</h2> + +<p> +Options can be passed to Bazel in different ways. Options that require a value +can be passed with either an equals sign or a space: +<pre> +--<option>=<value> +--<option> <value> +</pre> +Some options have a single character short form; in that case, the short form +has to be passed with a single dash and a space. +<pre> +-<short_form> <value> +</pre> +</p> + +<p> +Boolean options can be enabled as follows: +<pre> +--<option> +--<option>=[true|yes|1] +</pre> + +and disabled as follows: +<pre> +--no<option> +--<option>=[false|no|0] +</pre> +</p> + +<p> +Tristate options are usually set to automatic by default, and can be +force-enabled as follows: +<pre> +--<option>=[true|yes|1] +</pre> +or force-disabled as follows: +<pre> +--no<option> +--<option>=[false|no|0] +</pre> +</p> +<h2>Commands</h2> +<table> +<tr> + <td><a href="#aquery"><code>aquery</code></a></td> + <td>Analyzes the given targets and queries the action graph.</td> +</tr> +<tr> + <td><a href="#build"><code>build</code></a></td> + <td>Builds the specified targets.</td> +</tr> +<tr> + <td><a href="#canonicalize-flags"><code>canonicalize-flags</code></a></td> + <td>Canonicalizes a list of bazel options.</td> +</tr> +<tr> + <td><a href="#clean"><code>clean</code></a></td> + <td>Removes output files and optionally stops the server.</td> +</tr> +<tr> + <td><a href="#coverage"><code>coverage</code></a></td> + <td>Generates code coverage report for specified test targets.</td> +</tr> +<tr> + <td><a href="#cquery"><code>cquery</code></a></td> + <td>Loads, analyzes, and queries the specified targets w/ configurations.</td> +</tr> +<tr> + <td><a href="#dump"><code>dump</code></a></td> + <td>Dumps the internal state of the bazel server process.</td> +</tr> +<tr> + <td><a href="#fetch"><code>fetch</code></a></td> + <td>Fetches external repositories that are prerequisites to the targets.</td> +</tr> +<tr> + <td><a href="#help"><code>help</code></a></td> + <td>Prints help for commands, or the index.</td> +</tr> +<tr> + <td><a href="#info"><code>info</code></a></td> + <td>Displays runtime info about the bazel server.</td> +</tr> +<tr> + <td><a href="#license"><code>license</code></a></td> + <td>Prints the license of this software.</td> +</tr> +<tr> + <td><a href="#mobile-install"><code>mobile-install</code></a></td> + <td>Installs targets to mobile devices.</td> +</tr> +<tr> + <td><a href="#mod"><code>mod</code></a></td> + <td>Queries the Bzlmod external dependency graph</td> +</tr> +<tr> + <td><a href="#print_action"><code>print_action</code></a></td> + <td>Prints the command line args for compiling a file.</td> +</tr> +<tr> + <td><a href="#query"><code>query</code></a></td> + <td>Executes a dependency graph query.</td> +</tr> +<tr> + <td><a href="#run"><code>run</code></a></td> + <td>Runs the specified target.</td> +</tr> +<tr> + <td><a href="#shutdown"><code>shutdown</code></a></td> + <td>Stops the bazel server.</td> +</tr> +<tr> + <td><a href="#test"><code>test</code></a></td> + <td>Builds and runs the specified test targets.</td> +</tr> +<tr> + <td><a href="#vendor"><code>vendor</code></a></td> + <td>Fetches external repositories into a folder specified by the flag --vendor_dir.</td> +</tr> +<tr> + <td><a href="#version"><code>version</code></a></td> + <td>Prints version information for bazel.</td> +</tr> +</table> + +<h2>Startup Options</h2> +<dl>Options that appear before the command and are parsed by the client: +<dt id="startup_options-flag--autodetect_server_javabase"><code id="autodetect_server_javabase"><a href="#startup_options-flag--autodetect_server_javabase">--[no]autodetect_server_javabase</a></code> default: "true"</dt> +<dd> +<p>When --noautodetect_server_javabase is passed, Bazel does not fall back to the local JDK for running the bazel server and instead exits.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="startup_options-flag--batch"><code id="batch"><a href="#startup_options-flag--batch">--[no]batch</a></code> default: "false"</dt> +<dd> +<p>If set, Bazel will be run as just a client process without a server, instead of in the standard client/server mode. This is deprecated and will be removed, please prefer shutting down the server explicitly if you wish to avoid lingering servers.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> +</p></dd> +<dt id="startup_options-flag--batch_cpu_scheduling"><code id="batch_cpu_scheduling"><a href="#startup_options-flag--batch_cpu_scheduling">--[no]batch_cpu_scheduling</a></code> default: "false"</dt> +<dd> +<p>Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched_setscheduler'. If false, then Bazel does not perform a system call.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="startup_options-flag--bazelrc"><code id="bazelrc"><a href="#startup_options-flag--bazelrc">--bazelrc</a>=<path></code> multiple uses are accumulated</dt> +<dd> +<p>The location of the user .bazelrc file containing default values of Bazel options. /dev/null indicates that all further <code>--bazelrc</code>s will be ignored, which is useful to disable the search for a user rc file, e.g. in release builds. +This option can also be specified multiple times. +E.g. with <code>--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc</code>,</p> +<ol> +<li>x.rc and y.rc are read.</li> +<li>z.rc is ignored due to the prior /dev/null. +If unspecified, Bazel uses the first .bazelrc file it finds in the following two locations: the workspace directory, then the user's home directory. +Note: command line options will always supersede any option in bazelrc.</li> +</ol> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="startup_options-flag--block_for_lock"><code id="block_for_lock"><a href="#startup_options-flag--block_for_lock">--[no]block_for_lock</a></code> default: "true"</dt> +<dd> +<p>When --noblock_for_lock is passed, Bazel does not wait for a running command to complete, but instead exits immediately.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="startup_options-flag--client_debug"><code id="client_debug"><a href="#startup_options-flag--client_debug">--[no]client_debug</a></code> default: "false"</dt> +<dd> +<p>If true, log debug information from the client to stderr. Changing this option will not cause the server to restart.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="startup_options-flag--connect_timeout_secs"><code id="connect_timeout_secs"><a href="#startup_options-flag--connect_timeout_secs">--connect_timeout_secs</a>=<an integer></code> default: "30"</dt> +<dd> +<p>The amount of time the client waits for each attempt to connect to the server</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="startup_options-flag--digest_function"><code id="digest_function"><a href="#startup_options-flag--digest_function">--digest_function</a>=<hash function></code> default: see description</dt> +<dd> +<p>The hash function to use when computing file digests.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="startup_options-flag--experimental_cgroup_parent"><code id="experimental_cgroup_parent"><a href="#startup_options-flag--experimental_cgroup_parent">--experimental_cgroup_parent</a>=<path></code> default: see description</dt> +<dd> +<p>The cgroup where to start the bazel server as an absolute path. The server process will be started in the specified cgroup for each supported controller. For example, if the value of this flag is /build/bazel and the cpu and memory controllers are mounted respectively on /sys/fs/cgroup/cpu and /sys/fs/cgroup/memory, the server will be started in the cgroups /sys/fs/cgroup/cpu/build/bazel and /sys/fs/cgroup/memory/build/bazel.It is not an error if the specified cgroup is not writable for one or more of the controllers. This options does not have any effect on platforms that do not support cgroups.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="startup_options-flag--experimental_run_in_user_cgroup"><code id="experimental_run_in_user_cgroup"><a href="#startup_options-flag--experimental_run_in_user_cgroup">--[no]experimental_run_in_user_cgroup</a></code> default: "false"</dt> +<dd> +<p>If true, the Bazel server will be run with systemd-run, and the user will own the cgroup. This flag only takes effect on Linux.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="startup_options-flag--failure_detail_out"><code id="failure_detail_out"><a href="#startup_options-flag--failure_detail_out">--failure_detail_out</a>=<path></code> default: see description</dt> +<dd> +<p>If set, specifies a location to write a failure_detail protobuf message if the server experiences a failure and cannot report it via gRPC, as normal. Otherwise, the location will be ${OUTPUT_BASE}/failure_detail.rawproto.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="startup_options-flag--home_rc"><code id="home_rc"><a href="#startup_options-flag--home_rc">--[no]home_rc</a></code> default: "true"</dt> +<dd> +<p>Whether or not to look for the home bazelrc file at $HOME/.bazelrc</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="startup_options-flag--idle_server_tasks"><code id="idle_server_tasks"><a href="#startup_options-flag--idle_server_tasks">--[no]idle_server_tasks</a></code> default: "true"</dt> +<dd> +<p>Run System.gc() when the server is idle</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="startup_options-flag--ignore_all_rc_files"><code id="ignore_all_rc_files"><a href="#startup_options-flag--ignore_all_rc_files">--[no]ignore_all_rc_files</a></code> default: "false"</dt> +<dd> +<p>Disables all rc files, regardless of the values of other rc-modifying flags, even if these flags come later in the list of startup options.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="startup_options-flag--io_nice_level"><code id="io_nice_level"><a href="#startup_options-flag--io_nice_level">--io_nice_level</a>={-1,0,1,2,3,4,5,6,7}</code> default: "-1"</dt> +<dd> +<p>Only on Linux; set a level from 0-7 for best-effort IO scheduling using the sys_ioprio_set system call. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. If set to a negative value, then Bazel does not perform a system call.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="startup_options-flag--local_startup_timeout_secs"><code id="local_startup_timeout_secs"><a href="#startup_options-flag--local_startup_timeout_secs">--local_startup_timeout_secs</a>=<an integer></code> default: "120"</dt> +<dd> +<p>The maximum amount of time the client waits to connect to the server</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="startup_options-flag--macos_qos_class"><code id="macos_qos_class"><a href="#startup_options-flag--macos_qos_class">--macos_qos_class</a>=<a string></code> default: "default"</dt> +<dd> +<p>Sets the QoS service class of the bazel server when running on macOS. This flag has no effect on all other platforms but is supported to ensure rc files can be shared among them without changes. Possible values are: user-interactive, user-initiated, default, utility, and background.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="startup_options-flag--max_idle_secs"><code id="max_idle_secs"><a href="#startup_options-flag--max_idle_secs">--max_idle_secs</a>=<integer></code> default: "10800"</dt> +<dd> +<p>The number of seconds the build server will wait idling before shutting down. Zero means that the server will never shutdown. This is only read on server-startup, changing this option will not cause the server to restart.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="startup_options-flag--output_base"><code id="output_base"><a href="#startup_options-flag--output_base">--output_base</a>=<path></code> default: see description</dt> +<dd> +<p>If set, specifies the output location to which all build output will be written. Otherwise, the location will be ${OUTPUT_ROOT}/<em>blaze</em>${USER}/${MD5_OF_WORKSPACE_ROOT}. Note: If you specify a different option from one to the next Bazel invocation for this value, you'll likely start up a new, additional Bazel server. Bazel starts exactly one server per specified output base. Typically there is one output base per workspace - however, with this option you may have multiple output bases per workspace and thereby run multiple builds for the same client on the same machine concurrently. See 'bazel help shutdown' on how to shutdown a Bazel server.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="startup_options-flag--output_user_root"><code id="output_user_root"><a href="#startup_options-flag--output_user_root">--output_user_root</a>=<path></code> default: see description</dt> +<dd> +<p>The user-specific directory beneath which all build outputs are written; by default, this is a function of $USER, but by specifying a constant, build outputs can be shared between collaborating users.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="startup_options-flag--preemptible"><code id="preemptible"><a href="#startup_options-flag--preemptible">--[no]preemptible</a></code> default: "false"</dt> +<dd> +<p>If true, the command can be preempted if another command is started.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="startup_options-flag--quiet"><code id="quiet"><a href="#startup_options-flag--quiet">--[no]quiet</a></code> default: "false"</dt> +<dd> +<p>If true, no informational messages are emitted on the console, only errors. Changing this option will not cause the server to restart.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="startup_options-flag--server_jvm_out"><code id="server_jvm_out"><a href="#startup_options-flag--server_jvm_out">--server_jvm_out</a>=<path></code> default: see description</dt> +<dd> +<p>The location to write the server's JVM's output. If unset then defaults to a location in output_base.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="startup_options-flag--shutdown_on_low_sys_mem"><code id="shutdown_on_low_sys_mem"><a href="#startup_options-flag--shutdown_on_low_sys_mem">--[no]shutdown_on_low_sys_mem</a></code> default: "false"</dt> +<dd> +<p>If max_idle_secs is set and the build server has been idle for a while, shut down the server when the system is low on free RAM. Linux and MacOS only.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="startup_options-flag--system_rc"><code id="system_rc"><a href="#startup_options-flag--system_rc">--[no]system_rc</a></code> default: "true"</dt> +<dd> +<p>Whether or not to look for the system-wide bazelrc.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="startup_options-flag--unlimit_coredumps"><code id="unlimit_coredumps"><a href="#startup_options-flag--unlimit_coredumps">--[no]unlimit_coredumps</a></code> default: "false"</dt> +<dd> +<p>Raises the soft coredump limit to the hard limit to make coredumps of the server (including the JVM) and the client possible under common conditions. Stick this flag in your bazelrc once and forget about it so that you get coredumps when you actually encounter a condition that triggers them.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="startup_options-flag--windows_enable_symlinks"><code id="windows_enable_symlinks"><a href="#startup_options-flag--windows_enable_symlinks">--[no]windows_enable_symlinks</a></code> default: "false"</dt> +<dd> +<p>If true, real symbolic links will be created on Windows instead of file copying. Requires Windows developer mode to be enabled and Windows 10 version 1703 or greater.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="startup_options-flag--workspace_rc"><code id="workspace_rc"><a href="#startup_options-flag--workspace_rc">--[no]workspace_rc</a></code> default: "true"</dt> +<dd> +<p>Whether or not to look for the workspace bazelrc file at $workspace/.bazelrc</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="startup_options-flag--host_jvm_args"><code id="host_jvm_args"><a href="#startup_options-flag--host_jvm_args">--host_jvm_args</a>=<jvm_arg></code> multiple uses are accumulated</dt> +<dd> +<p>Flags to pass to the JVM executing Blaze.</p> +</dd> +<dt id="startup_options-flag--host_jvm_debug"><code id="host_jvm_debug"><a href="#startup_options-flag--host_jvm_debug">--host_jvm_debug</a></code></dt> +<dd> +<p>Convenience option to add some additional JVM startup flags, which cause the JVM to wait during startup until you connect from a JDWP-compliant debugger (like Eclipse) to port 5005.</p> +<p>Expands to: +<br/>  <code><a href="#flag--host_jvm_args">--host_jvm_args=-agentlib:jdwp=transport=dt_socket,server=y,address=5005</a></code> +</p></dd> +<dt id="startup_options-flag--server_javabase"><code id="server_javabase"><a href="#startup_options-flag--server_javabase">--server_javabase</a>=<jvm path></code> default: ""</dt> +<dd> +<p>Path to the JVM used to execute Bazel itself.</p> +</dd> +</dl> + +<h2><a name="common_options">Options Common to all Commands</a></h2> +<dl>Options that appear before the command and are parsed by the client: +<dt id="common_options-flag--distdir"><code id="distdir"><a href="#common_options-flag--distdir">--distdir</a>=<a path></code> multiple uses are accumulated</dt> +<dd> +<p>Additional places to search for archives before accessing the network to download them.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--experimental_repository_cache_hardlinks"><code id="experimental_repository_cache_hardlinks"><a href="#common_options-flag--experimental_repository_cache_hardlinks">--[no]experimental_repository_cache_hardlinks</a></code> default: "false"</dt> +<dd> +<p>If set, the repository cache will hardlink the file in case of a cache hit, rather than copying. This is intended to save disk space.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--experimental_repository_downloader_retries"><code id="experimental_repository_downloader_retries"><a href="#common_options-flag--experimental_repository_downloader_retries">--experimental_repository_downloader_retries</a>=<an integer></code> default: "5"</dt> +<dd> +<p>The maximum number of attempts to retry a download error. If set to 0, retries are disabled.</p> +<p>Tags: +<a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_scale_timeouts"><code id="experimental_scale_timeouts"><a href="#common_options-flag--experimental_scale_timeouts">--experimental_scale_timeouts</a>=<a double></code> default: "1.0"</dt> +<dd> +<p>Scale all timeouts in Starlark repository rules by this factor. In this way, external repositories can be made working on machines that are slower than the rule author expected, without changing the source code</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--http_connector_attempts"><code id="http_connector_attempts"><a href="#common_options-flag--http_connector_attempts">--http_connector_attempts</a>=<an integer></code> default: "8"</dt> +<dd> +<p>The maximum number of attempts for http downloads.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--http_connector_retry_max_timeout"><code id="http_connector_retry_max_timeout"><a href="#common_options-flag--http_connector_retry_max_timeout">--http_connector_retry_max_timeout</a>=<An immutable length of time.></code> default: "0s"</dt> +<dd> +<p>The maximum timeout for http download retries. With a value of 0, no timeout maximum is defined.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--http_max_parallel_downloads"><code id="http_max_parallel_downloads"><a href="#common_options-flag--http_max_parallel_downloads">--http_max_parallel_downloads</a>=<an integer></code> default: "8"</dt> +<dd> +<p>The maximum number parallel http downloads.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--http_timeout_scaling"><code id="http_timeout_scaling"><a href="#common_options-flag--http_timeout_scaling">--http_timeout_scaling</a>=<a double></code> default: "1.0"</dt> +<dd> +<p>Scale all timeouts related to http downloads by the given factor</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--repo_contents_cache"><code id="repo_contents_cache"><a href="#common_options-flag--repo_contents_cache">--repo_contents_cache</a>=<a path></code> default: see description</dt> +<dd> +<p>Specifies the location of the repo contents cache, which contains fetched repo directories shareable across workspaces. An empty string as argument requests the repo contents cache to be disabled, otherwise the default of '<--repository_cache>/contents' is used. Note that this means setting '--repository_cache=' would by default disable the repo contents cache as well, unless '--repo_contents_cache=<some_path>' is also set.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--repo_contents_cache_gc_idle_delay"><code id="repo_contents_cache_gc_idle_delay"><a href="#common_options-flag--repo_contents_cache_gc_idle_delay">--repo_contents_cache_gc_idle_delay</a>=<An immutable length of time.></code> default: "5m"</dt> +<dd> +<p>Specifies the amount of time the server must remain idle before garbage collection happens +to the repo contents cache.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--repo_contents_cache_gc_max_age"><code id="repo_contents_cache_gc_max_age"><a href="#common_options-flag--repo_contents_cache_gc_max_age">--repo_contents_cache_gc_max_age</a>=<An immutable length of time.></code> default: "14d"</dt> +<dd> +<p>Specifies the amount of time an entry in the repo contents cache can stay unused before it's garbage collected. If set to zero, only duplicate entries will be garbage collected.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--repository_cache"><code id="repository_cache"><a href="#common_options-flag--repository_cache">--repository_cache</a>=<a path></code> default: see description</dt> +<dd> +<p>Specifies the cache location of the downloaded values obtained during the fetching of external repositories. An empty string as argument requests the cache to be disabled, otherwise the default of '<--output_user_root>/cache/repos/v1' is used</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--repository_disable_download"><code id="repository_disable_download"><a href="#common_options-flag--repository_disable_download">--[no]repository_disable_download</a></code> default: "false"</dt> +<dd> +<p>If set, downloading using ctx.download{,_and_extract} is not allowed during repository fetching. Note that network access is not completely disabled; ctx.execute could still run an arbitrary executable that accesses the Internet.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +</dl> +<dl>Options that control build execution: +<dt id="common_options-flag--experimental_ui_max_stdouterr_bytes"><code id="experimental_ui_max_stdouterr_bytes"><a href="#common_options-flag--experimental_ui_max_stdouterr_bytes">--experimental_ui_max_stdouterr_bytes</a>=<an integer in (-1)-1073741819 range></code> default: "1048576"</dt> +<dd> +<p>The maximum size of the stdout / stderr files that will be printed to the console. -1 implies no limit.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="common_options-flag--gc_churning_threshold"><code id="gc_churning_threshold"><a href="#common_options-flag--gc_churning_threshold">--gc_churning_threshold</a>=<an integer in 0-100 range></code> default: "100"</dt> +<dd> +<p>At any point after an invocation has been running for at least one minute, if Blaze has spent at least this percentage of the invocation's wall time doing full GCs, Blaze will give up and fail with an OOM. A value of 100 effectively means to never give up for this reason.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--gc_churning_threshold_if_multiple_top_level_targets"><code id="gc_churning_threshold_if_multiple_top_level_targets"><a href="#common_options-flag--gc_churning_threshold_if_multiple_top_level_targets">--gc_churning_threshold_if_multiple_top_level_targets</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>If set to a value in [0, 100] and this is a command that takes top-level targets (e.g. build but not query) and there are multiple such top-level targets, overrides --gc_churning_threshold. Useful to configure more aggressive OOMing behavior (i.e. a lower value than --gc_churning_threshold) when they are multiple top-level targets so that the invoker of Bazel can split and retry while still having less aggressive behavior when there is a single top-level target.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--gc_thrashing_threshold"><code id="gc_thrashing_threshold"><a href="#common_options-flag--gc_thrashing_threshold">--gc_thrashing_threshold</a>=<an integer in 0-100 range></code> default: "100"</dt> +<dd> +<p>The percent of tenured space occupied (0-100) above which GcThrashingDetector considers memory pressure events against its limits (--gc_thrashing_limits). If set to 100, GcThrashingDetector is disabled.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="common_options-flag--incompatible_enable_proto_toolchain_resolution"><code id="incompatible_enable_proto_toolchain_resolution"><a href="#common_options-flag--incompatible_enable_proto_toolchain_resolution">--[no]incompatible_enable_proto_toolchain_resolution</a></code> default: "false"</dt> +<dd> +<p>If true, proto lang rules define toolchains from protobuf repository.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="common_options-flag--bep_maximum_open_remote_upload_files"><code id="bep_maximum_open_remote_upload_files"><a href="#common_options-flag--bep_maximum_open_remote_upload_files">--bep_maximum_open_remote_upload_files</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>Maximum number of open files allowed during BEP artifact upload.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--remote_download_all"><code id="remote_download_all"><a href="#common_options-flag--remote_download_all">--remote_download_all</a></code></dt> +<dd> +<p>Downloads all remote outputs to the local machine. This flag is an alias for --remote_download_outputs=all.</p> +<p>Expands to: +<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=all</a></code> +</p><p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--remote_download_minimal"><code id="remote_download_minimal"><a href="#common_options-flag--remote_download_minimal">--remote_download_minimal</a></code></dt> +<dd> +<p>Does not download any remote build outputs to the local machine. This flag is an alias for --remote_download_outputs=minimal.</p> +<p>Expands to: +<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=minimal</a></code> +</p><p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--remote_download_outputs"><code id="remote_download_outputs"><a href="#common_options-flag--remote_download_outputs">--remote_download_outputs</a>=<all, minimal or toplevel></code> default: "toplevel"</dt> +<dd> +<p>If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--remote_download_symlink_template"><code id="remote_download_symlink_template"><a href="#common_options-flag--remote_download_symlink_template">--remote_download_symlink_template</a>=<a string></code> default: ""</dt> +<dd> +<p>Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--remote_download_toplevel"><code id="remote_download_toplevel"><a href="#common_options-flag--remote_download_toplevel">--remote_download_toplevel</a></code></dt> +<dd> +<p>Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote_download_outputs=toplevel.</p> +<p>Expands to: +<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=toplevel</a></code> +</p><p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--repo_env"><code id="repo_env"><a href="#common_options-flag--repo_env">--repo_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional environment variables to be available only for repository rules. Note that repository rules see the full environment anyway, but in this way variables can be set via command-line flags and <code>.bazelrc</code> entries. The special syntax <code>=NAME</code> can be used to explicitly unset a variable.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="common_options-flag--allow_experimental_loads"><code id="allow_experimental_loads"><a href="#common_options-flag--allow_experimental_loads">--[no]allow_experimental_loads</a></code> default: "false"</dt> +<dd> +<p>If enabled, issue only a warning instead of an error for loads of experimental .bzls.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="common_options-flag--check_bzl_visibility"><code id="check_bzl_visibility"><a href="#common_options-flag--check_bzl_visibility">--[no]check_bzl_visibility</a></code> default: "true"</dt> +<dd> +<p>If disabled, .bzl load visibility errors are demoted to warnings.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_enforce_starlark_utf8"><code id="incompatible_enforce_starlark_utf8"><a href="#common_options-flag--incompatible_enforce_starlark_utf8">--[no]incompatible_enforce_starlark_utf8</a></code> default: "warning"</dt> +<dd> +<p>If enabled (or set to 'error'), fail if Starlark files are not UTF-8 encoded. If set to 'warning', emit a warning instead. If set to 'off', Bazel assumes that Starlark files are UTF-8 encoded but does not verify this assumption. Note that Starlark files which are not UTF-8 encoded can cause Bazel to behave inconsistently.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="common_options-flag--experimental_bzl_visibility"><code id="experimental_bzl_visibility"><a href="#common_options-flag--experimental_bzl_visibility">--[no]experimental_bzl_visibility</a></code> default: "true"</dt> +<dd> +<p>If enabled, adds a <code>visibility()</code> function that .bzl files may call during top-level evaluation to set their visibility for the purpose of load() statements.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_cc_shared_library"><code id="experimental_cc_shared_library"><a href="#common_options-flag--experimental_cc_shared_library">--[no]experimental_cc_shared_library</a></code> default: "false"</dt> +<dd> +<p>If set to true, rule attributes and Starlark API methods needed for the rule cc_shared_library will be available</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_disable_external_package"><code id="experimental_disable_external_package"><a href="#common_options-flag--experimental_disable_external_package">--[no]experimental_disable_external_package</a></code> default: "false"</dt> +<dd> +<p>If set to true, the auto-generated //external package will not be available anymore. Bazel will still be unable to parse the file 'external/BUILD', but globs reaching into external/ from the unnamed package will work.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_dormant_deps"><code id="experimental_dormant_deps"><a href="#common_options-flag--experimental_dormant_deps">--[no]experimental_dormant_deps</a></code> default: "false"</dt> +<dd> +<p>If set to true, attr.label(materializer=), attr(for_dependency_resolution=), attr.dormant_label(), attr.dormant_label_list() and rule(for_dependency_resolution=) are allowed.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_enable_android_migration_apis"><code id="experimental_enable_android_migration_apis"><a href="#common_options-flag--experimental_enable_android_migration_apis">--[no]experimental_enable_android_migration_apis</a></code> default: "false"</dt> +<dd> +<p>If set to true, enables the APIs required to support the Android Starlark migration.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="common_options-flag--experimental_enable_first_class_macros"><code id="experimental_enable_first_class_macros"><a href="#common_options-flag--experimental_enable_first_class_macros">--[no]experimental_enable_first_class_macros</a></code> default: "true"</dt> +<dd> +<p>If set to true, enables the <code>macro()</code> construct for defining symbolic macros.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="common_options-flag--experimental_enable_scl_dialect"><code id="experimental_enable_scl_dialect"><a href="#common_options-flag--experimental_enable_scl_dialect">--[no]experimental_enable_scl_dialect</a></code> default: "true"</dt> +<dd> +<p>If set to true, .scl files may be used in load() statements.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="common_options-flag--experimental_enable_starlark_set"><code id="experimental_enable_starlark_set"><a href="#common_options-flag--experimental_enable_starlark_set">--[no]experimental_enable_starlark_set</a></code> default: "true"</dt> +<dd> +<p>If true, enable the set data type and set() constructor in Starlark.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_google_legacy_api"><code id="experimental_google_legacy_api"><a href="#common_options-flag--experimental_google_legacy_api">--[no]experimental_google_legacy_api</a></code> default: "false"</dt> +<dd> +<p>If set to true, exposes a number of experimental pieces of Starlark build API pertaining to Google legacy code.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_isolated_extension_usages"><code id="experimental_isolated_extension_usages"><a href="#common_options-flag--experimental_isolated_extension_usages">--[no]experimental_isolated_extension_usages</a></code> default: "false"</dt> +<dd> +<p>If true, enables the <code>isolate</code> parameter in the <a href="https://bazel.build/rules/lib/globals/module#use_extension"><code>use_extension</code></a> function.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--experimental_platforms_api"><code id="experimental_platforms_api"><a href="#common_options-flag--experimental_platforms_api">--[no]experimental_platforms_api</a></code> default: "false"</dt> +<dd> +<p>If set to true, enables a number of platform-related Starlark APIs useful for debugging.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_repo_remote_exec"><code id="experimental_repo_remote_exec"><a href="#common_options-flag--experimental_repo_remote_exec">--[no]experimental_repo_remote_exec</a></code> default: "false"</dt> +<dd> +<p>If set to true, repository_rule gains some remote execution capabilities.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_repository_ctx_execute_wasm"><code id="experimental_repository_ctx_execute_wasm"><a href="#common_options-flag--experimental_repository_ctx_execute_wasm">--[no]experimental_repository_ctx_execute_wasm</a></code> default: "false"</dt> +<dd> +<p>If true enables the repository_ctx <code>load_wasm</code> and <code>execute_wasm</code> methods.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_sibling_repository_layout"><code id="experimental_sibling_repository_layout"><a href="#common_options-flag--experimental_sibling_repository_layout">--[no]experimental_sibling_repository_layout</a></code> default: "false"</dt> +<dd> +<p>If set to true, non-main repositories are planted as symlinks to the main repository in the execution root. That is, all repositories are direct children of the $output_base/execution_root directory. This has the side effect of freeing up $output_base/execution_root/<strong>main</strong>/external for the real top-level 'external' directory.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_single_package_toolchain_binding"><code id="experimental_single_package_toolchain_binding"><a href="#common_options-flag--experimental_single_package_toolchain_binding">--[no]experimental_single_package_toolchain_binding</a></code> default: "false"</dt> +<dd> +<p>If enabled, the register_toolchain function may not include target patterns which may refer to more than one package.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--experimental_starlark_types"><code id="experimental_starlark_types"><a href="#common_options-flag--experimental_starlark_types">--[no]experimental_starlark_types</a></code> default: "false"</dt> +<dd> +<p>Enables type annotations and type checking. Locations where the annotations are allowed is further controlled by <code>--experimental_starlark_types_allowed_paths</code>.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_starlark_types_allowed_paths"><code id="experimental_starlark_types_allowed_paths"><a href="#common_options-flag--experimental_starlark_types_allowed_paths">--experimental_starlark_types_allowed_paths</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>List of canonical Label prefixes under which Starlark type annotations are allowed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_allow_tags_propagation"><code id="incompatible_allow_tags_propagation"><a href="#common_options-flag--incompatible_allow_tags_propagation">--[no]incompatible_allow_tags_propagation</a></code> default: "true"</dt> +<dd> +<p>If set to true, tags will be propagated from a target to the actions' execution requirements; otherwise tags are not propagated. See https://github.com/bazelbuild/bazel/issues/8830 for details.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_always_check_depset_elements"><code id="incompatible_always_check_depset_elements"><a href="#common_options-flag--incompatible_always_check_depset_elements">--[no]incompatible_always_check_depset_elements</a></code> default: "true"</dt> +<dd> +<p>Check the validity of elements added to depsets, in all constructors. Elements must be immutable, but historically the depset(direct=...) constructor forgot to check. Use tuples instead of lists in depset elements. See https://github.com/bazelbuild/bazel/issues/10313 for details.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_autoload_externally"><code id="incompatible_autoload_externally"><a href="#common_options-flag--incompatible_autoload_externally">--incompatible_autoload_externally</a>=<comma-separated set of options></code> default: "+@rules_cc"</dt> +<dd> +<p>A comma-separated list of rules (or other symbols) that were previously part of Bazel and which are now to be retrieved from their respective external repositories. This flag is intended to be used to facilitate migration of rules out of Bazel. See also https://github.com/bazelbuild/bazel/issues/23043. +A symbol that is autoloaded within a file behaves as if its built-into-Bazel definition were replaced by its canonical new definition in an external repository. For a BUILD file, this essentially means implicitly adding a load() statement. For a .bzl file, it's either a load() statement or a change to a field of the <code>native</code> object, depending on whether the autoloaded symbol is a rule. +Bazel maintains a hardcoded list of all symbols that may be autoloaded; only those symbols may appear in this flag. For each symbol, Bazel knows the new definition location in an external repository, as well as a set of special-cased repositories that must not autoload it to avoid creating cycles. +A list item of "+foo" in this flag causes symbol foo to be autoloaded, except in foo's exempt repositories, within which the Bazel-defined version of foo is still available. +A list item of "foo" triggers autoloading as above, but the Bazel-defined version of foo is not made available to the excluded repositories. This ensures that foo's external repository does not depend on the old Bazel implementation of foo +A list item of "-foo" does not trigger any autoloading, but makes the Bazel-defined version of foo inaccessible throughout the workspace. This is used to validate that the workspace is ready for foo's definition to be deleted from Bazel. +If a symbol is not named in this flag then it continues to work as normal -- no autoloading is done, nor is the Bazel-defined version suppressed. For configuration see https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/packages/AutoloadSymbols.java As a shortcut also whole repository may be used, for example +@rules_python will autoload all Python rules.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_disable_autoloads_in_main_repo"><code id="incompatible_disable_autoloads_in_main_repo"><a href="#common_options-flag--incompatible_disable_autoloads_in_main_repo">--[no]incompatible_disable_autoloads_in_main_repo</a></code> default: "true"</dt> +<dd> +<p>Controls if the autoloads (set by --incompatible_autoload_externally) are enabled in themain repository. When enabled the rules (or other symbols) that were previously part of Bazel need to have load statements. Use buildifier to add them.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_disable_objc_library_transition"><code id="incompatible_disable_objc_library_transition"><a href="#common_options-flag--incompatible_disable_objc_library_transition">--[no]incompatible_disable_objc_library_transition</a></code> default: "true"</dt> +<dd> +<p>Disable objc_library's custom transition and inherit from the top level target instead (No-op in Bazel)</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_disable_starlark_host_transitions"><code id="incompatible_disable_starlark_host_transitions"><a href="#common_options-flag--incompatible_disable_starlark_host_transitions">--[no]incompatible_disable_starlark_host_transitions</a></code> default: "false"</dt> +<dd> +<p>If set to true, rule attributes cannot set 'cfg = "host"'. Rules should set 'cfg = "exec"' instead.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_disable_target_default_provider_fields"><code id="incompatible_disable_target_default_provider_fields"><a href="#common_options-flag--incompatible_disable_target_default_provider_fields">--[no]incompatible_disable_target_default_provider_fields</a></code> default: "false"</dt> +<dd> +<p>If set to true, disable the ability to utilize the default provider via field syntax. Use provider-key syntax instead. For example, instead of using <code>ctx.attr.dep.files</code> to access <code>files</code>, utilize `ctx.attr.dep[DefaultInfo].files See https://github.com/bazelbuild/bazel/issues/9014 for details.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_disable_transitions_on"><code id="incompatible_disable_transitions_on"><a href="#common_options-flag--incompatible_disable_transitions_on">--incompatible_disable_transitions_on</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>A comma-separated list of flags that cannot be used in transitions inputs or outputs.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_disallow_ctx_resolve_tools"><code id="incompatible_disallow_ctx_resolve_tools"><a href="#common_options-flag--incompatible_disallow_ctx_resolve_tools">--[no]incompatible_disallow_ctx_resolve_tools</a></code> default: "true"</dt> +<dd> +<p>If set to true, calling the deprecated ctx.resolve_tools API always fails. Uses of this API should be replaced by an executable or tools argument to ctx.actions.run or ctx.actions.run_shell.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_disallow_empty_glob"><code id="incompatible_disallow_empty_glob"><a href="#common_options-flag--incompatible_disallow_empty_glob">--[no]incompatible_disallow_empty_glob</a></code> default: "true"</dt> +<dd> +<p>If set to true, the default value of the <code>allow_empty</code> argument of glob() is False.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_enable_deprecated_label_apis"><code id="incompatible_enable_deprecated_label_apis"><a href="#common_options-flag--incompatible_enable_deprecated_label_apis">--[no]incompatible_enable_deprecated_label_apis</a></code> default: "true"</dt> +<dd> +<p>If enabled, certain deprecated APIs (native.repository_name, Label.workspace_name, Label.relative) can be used.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_fail_on_unknown_attributes"><code id="incompatible_fail_on_unknown_attributes"><a href="#common_options-flag--incompatible_fail_on_unknown_attributes">--[no]incompatible_fail_on_unknown_attributes</a></code> default: "true"</dt> +<dd> +<p>If enabled, targets that have unknown attributes set to None fail.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_fix_package_group_reporoot_syntax"><code id="incompatible_fix_package_group_reporoot_syntax"><a href="#common_options-flag--incompatible_fix_package_group_reporoot_syntax">--[no]incompatible_fix_package_group_reporoot_syntax</a></code> default: "true"</dt> +<dd> +<p>In package_group's <code>packages</code> attribute, changes the meaning of the value "//..." to refer to all packages in the current repository instead of all packages in any repository. You can use the special value "public" in place of "//..." to obtain the old behavior. This flag requires that --incompatible_package_group_has_public_syntax also be enabled.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_locations_prefers_executable"><code id="incompatible_locations_prefers_executable"><a href="#common_options-flag--incompatible_locations_prefers_executable">--[no]incompatible_locations_prefers_executable</a></code> default: "true"</dt> +<dd> +<p>Whether a target that provides an executable expands to the executable rather than the files in <code>DefaultInfo.files</code> under $(locations ...) expansion if the number of files is not 1.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_no_attr_license"><code id="incompatible_no_attr_license"><a href="#common_options-flag--incompatible_no_attr_license">--[no]incompatible_no_attr_license</a></code> default: "true"</dt> +<dd> +<p>If set to true, disables the function <code>attr.license</code>.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_no_implicit_file_export"><code id="incompatible_no_implicit_file_export"><a href="#common_options-flag--incompatible_no_implicit_file_export">--[no]incompatible_no_implicit_file_export</a></code> default: "false"</dt> +<dd> +<p>If set, (used) source files are package private unless exported explicitly. See https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_no_implicit_watch_label"><code id="incompatible_no_implicit_watch_label"><a href="#common_options-flag--incompatible_no_implicit_watch_label">--[no]incompatible_no_implicit_watch_label</a></code> default: "true"</dt> +<dd> +<p>If true, then methods on <code>repository_ctx</code> that are passed a Label will no longer automatically watch the file under that label for changes even if <code>watch = "no"</code>, and <code>repository_ctx.path</code> no longer causes the returned path to be watched. Use <code>repository_ctx.watch</code> instead.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_no_rule_outputs_param"><code id="incompatible_no_rule_outputs_param"><a href="#common_options-flag--incompatible_no_rule_outputs_param">--[no]incompatible_no_rule_outputs_param</a></code> default: "false"</dt> +<dd> +<p>If set to true, disables the <code>outputs</code> parameter of the <code>rule()</code> Starlark function.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_package_group_has_public_syntax"><code id="incompatible_package_group_has_public_syntax"><a href="#common_options-flag--incompatible_package_group_has_public_syntax">--[no]incompatible_package_group_has_public_syntax</a></code> default: "true"</dt> +<dd> +<p>In package_group's <code>packages</code> attribute, allows writing "public" or "private" to refer to all packages or no packages respectively.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_resolve_select_keys_eagerly"><code id="incompatible_resolve_select_keys_eagerly"><a href="#common_options-flag--incompatible_resolve_select_keys_eagerly">--[no]incompatible_resolve_select_keys_eagerly</a></code> default: "false"</dt> +<dd> +<p>If enabled, string keys in dicts passed to select() in .bzl files are immediately resolved to Labels relative to the file instead of being interpreted relative to the BUILD file they are ultimately loaded from.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_run_shell_command_string"><code id="incompatible_run_shell_command_string"><a href="#common_options-flag--incompatible_run_shell_command_string">--[no]incompatible_run_shell_command_string</a></code> default: "true"</dt> +<dd> +<p>If set to true, the command parameter of actions.run_shell will only accept string</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_simplify_unconditional_selects_in_rule_attrs"><code id="incompatible_simplify_unconditional_selects_in_rule_attrs"><a href="#common_options-flag--incompatible_simplify_unconditional_selects_in_rule_attrs">--[no]incompatible_simplify_unconditional_selects_in_rule_attrs</a></code> default: "true"</dt> +<dd> +<p>If true, simplify configurable rule attributes which contain only unconditional selects; for example, if ["a"] + select("//conditions:default", ["b"]) is assigned to a rule attribute, it is stored as ["a", "b"]. This option does not affect attributes of symbolic macros or attribute default values.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_stop_exporting_build_file_path"><code id="incompatible_stop_exporting_build_file_path"><a href="#common_options-flag--incompatible_stop_exporting_build_file_path">--[no]incompatible_stop_exporting_build_file_path</a></code> default: "false"</dt> +<dd> +<p>If set to true, deprecated ctx.build_file_path will not be available. ctx.label.package + '/BUILD' can be used instead.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_stop_exporting_language_modules"><code id="incompatible_stop_exporting_language_modules"><a href="#common_options-flag--incompatible_stop_exporting_language_modules">--[no]incompatible_stop_exporting_language_modules</a></code> default: "false"</dt> +<dd> +<p>If enabled, certain language-specific modules (such as <code>cc_common</code>) are unavailable in user .bzl files and may only be called from their respective rules repositories.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_unambiguous_label_stringification"><code id="incompatible_unambiguous_label_stringification"><a href="#common_options-flag--incompatible_unambiguous_label_stringification">--[no]incompatible_unambiguous_label_stringification</a></code> default: "true"</dt> +<dd> +<p>When true, Bazel will stringify the label @//foo:bar to @//foo:bar, instead of //foo:bar. This only affects the behavior of str(), the % operator, and so on; the behavior of repr() is unchanged. See https://github.com/bazelbuild/bazel/issues/15916 for more information.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_use_cc_configure_from_rules_cc"><code id="incompatible_use_cc_configure_from_rules_cc"><a href="#common_options-flag--incompatible_use_cc_configure_from_rules_cc">--[no]incompatible_use_cc_configure_from_rules_cc</a></code> default: "false"</dt> +<dd> +<p>When true, Bazel will no longer allow using cc_configure from @bazel_tools. Please see https://github.com/bazelbuild/bazel/issues/10134 for details and migration instructions.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--max_computation_steps"><code id="max_computation_steps"><a href="#common_options-flag--max_computation_steps">--max_computation_steps</a>=<a long integer></code> default: "0"</dt> +<dd> +<p>The maximum number of Starlark computation steps that may be executed by a BUILD file (zero means no limit).</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="common_options-flag--nested_set_depth_limit"><code id="nested_set_depth_limit"><a href="#common_options-flag--nested_set_depth_limit">--nested_set_depth_limit</a>=<an integer></code> default: "3500"</dt> +<dd> +<p>The maximum depth of the graph internal to a depset (also known as NestedSet), above which the depset() constructor will fail.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--repositories_without_autoloads"><code id="repositories_without_autoloads"><a href="#common_options-flag--repositories_without_autoloads">--repositories_without_autoloads</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>A list of additional repositories (beyond the hardcoded ones Bazel knows about) where autoloads are not to be added. This should typically contain repositories that are transitively depended on by a repository that may be loaded automatically (and which can therefore potentially create a cycle).</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options relating to Bzlmod output and semantics: +<dt id="common_options-flag--allow_yanked_versions"><code id="allow_yanked_versions"><a href="#common_options-flag--allow_yanked_versions">--allow_yanked_versions</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Specified the module versions in the form of <code>&lt;module1&gt;@&lt;version1&gt;,&lt;module2&gt;@&lt;version2&gt;</code> that will be allowed in the resolved dependency graph even if they are declared yanked in the registry where they come from (if they are not coming from a NonRegistryOverride). Otherwise, yanked versions will cause the resolution to fail. You can also define allowed yanked version with the <code>BZLMOD_ALLOW_YANKED_VERSIONS</code> environment variable. You can disable this check by using the keyword 'all' (not recommended).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--check_bazel_compatibility"><code id="check_bazel_compatibility"><a href="#common_options-flag--check_bazel_compatibility">--check_bazel_compatibility</a>=<error, warning or off></code> default: "error"</dt> +<dd> +<p>Check bazel version compatibility of Bazel modules. Valid values are <code>error</code> to escalate it to a resolution failure, <code>off</code> to disable the check, or <code>warning</code> to print a warning when mismatch detected.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--check_direct_dependencies"><code id="check_direct_dependencies"><a href="#common_options-flag--check_direct_dependencies">--check_direct_dependencies</a>=<off, warning or error></code> default: "warning"</dt> +<dd> +<p>Check if the direct <code>bazel_dep</code> dependencies declared in the root module are the same versions you get in the resolved dependency graph. Valid values are <code>off</code> to disable the check, <code>warning</code> to print a warning when mismatch detected or <code>error</code> to escalate it to a resolution failure.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--ignore_dev_dependency"><code id="ignore_dev_dependency"><a href="#common_options-flag--ignore_dev_dependency">--[no]ignore_dev_dependency</a></code> default: "false"</dt> +<dd> +<p>If true, Bazel ignores <code>bazel_dep</code> and <code>use_extension</code> declared as <code>dev_dependency</code> in the MODULE.bazel of the root module. Note that, those dev dependencies are always ignored in the MODULE.bazel if it's not the root module regardless of the value of this flag.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--lockfile_mode"><code id="lockfile_mode"><a href="#common_options-flag--lockfile_mode">--lockfile_mode</a>=<off, update, refresh or error></code> default: "update"</dt> +<dd> +<p>Specifies how and whether or not to use the lockfile. Valid values are <code>update</code> to use the lockfile and update it if there are changes, <code>refresh</code> to additionally refresh mutable information (yanked versions and previously missing modules) from remote registries from time to time, <code>error</code> to use the lockfile but throw an error if it's not up-to-date, or <code>off</code> to neither read from or write to the lockfile.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--module_mirrors"><code id="module_mirrors"><a href="#common_options-flag--module_mirrors">--module_mirrors</a>=<comma-separated list of options></code> default: see description</dt> +<dd> +<p>A comma-separated list of URLs under which the source URLs of Bazel modules can be found, +in addition to and taking precedence over any registry-provided mirror URLs. Set this to +an empty value to disable the use of any mirrors not specified by the registries. The +default set of mirrors may change over time, but all downloads from mirrors are verified +by hashes stored in the registry (and thus pinned by the lockfile).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="common_options-flag--override_module"><code id="override_module"><a href="#common_options-flag--override_module">--override_module</a>=<an equals-separated mapping of module name to path></code> multiple uses are accumulated</dt> +<dd> +<p>Override a module with a local path in the form of <module name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of <code>bazel info workspace</code>. If the given path is empty, then remove any previous overrides.</p> +</dd> +<dt id="common_options-flag--registry"><code id="registry"><a href="#common_options-flag--registry">--registry</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the registries to use to locate Bazel module dependencies. The order is important: modules will be looked up in earlier registries first, and only fall back to later registries when they're missing from the earlier ones.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="common_options-flag--vendor_dir"><code id="vendor_dir"><a href="#common_options-flag--vendor_dir">--vendor_dir</a>=<a path></code> default: see description</dt> +<dd> +<p>Specifies the directory that should hold the external repositories in vendor mode, whether for the purpose of fetching them into it or using them while building. The path can be specified as either an absolute path or a path relative to the workspace directory.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> +<dl>Options that trigger optimizations of the build time: +<dt id="common_options-flag--gc_thrashing_limits"><code id="gc_thrashing_limits"><a href="#common_options-flag--gc_thrashing_limits">--gc_thrashing_limits</a>=<comma separated pairs of <period>:<count>></code> default: "1s:2,20s:3,1m:5"</dt> +<dd> +<p>Limits which, if reached, cause GcThrashingDetector to crash Bazel with an OOM. Each limit is specified as <period>:<count> where period is a duration and count is a positive integer. If more than --gc_thrashing_threshold percent of tenured space (old gen heap) remains occupied after <count> consecutive full GCs within <period>, an OOM is triggered. Multiple limits can be specified separated by commas.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--heuristically_drop_nodes"><code id="heuristically_drop_nodes"><a href="#common_options-flag--heuristically_drop_nodes">--[no]heuristically_drop_nodes</a></code> default: "false"</dt> +<dd> +<p>If true, Blaze will remove FileState and DirectoryListingState nodes after related File and DirectoryListing node is done to save memory. We expect that it is less likely that these nodes will be needed again. If so, the program will re-evaluate them.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_do_not_split_linking_cmdline"><code id="incompatible_do_not_split_linking_cmdline"><a href="#common_options-flag--incompatible_do_not_split_linking_cmdline">--[no]incompatible_do_not_split_linking_cmdline</a></code> default: "true"</dt> +<dd> +<p>When true, Bazel no longer modifies command line flags used for linking, and also doesn't selectively decide which flags go to the param file and which don't. See https://github.com/bazelbuild/bazel/issues/7670 for details.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--keep_state_after_build"><code id="keep_state_after_build"><a href="#common_options-flag--keep_state_after_build">--[no]keep_state_after_build</a></code> default: "true"</dt> +<dd> +<p>If false, Blaze will discard the inmemory state from this build when the build finishes. Subsequent builds will not have any incrementality with respect to this one.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="common_options-flag--skyframe_high_water_mark_full_gc_drops_per_invocation"><code id="skyframe_high_water_mark_full_gc_drops_per_invocation"><a href="#common_options-flag--skyframe_high_water_mark_full_gc_drops_per_invocation">--skyframe_high_water_mark_full_gc_drops_per_invocation</a>=<an integer, >= 0></code> default: "10"</dt> +<dd> +<p>Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe_high_water_mark_threshold, when a full GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that full GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a full GC event occurs and that retained heap percentage threshold is exceeded.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--skyframe_high_water_mark_minor_gc_drops_per_invocation"><code id="skyframe_high_water_mark_minor_gc_drops_per_invocation"><a href="#common_options-flag--skyframe_high_water_mark_minor_gc_drops_per_invocation">--skyframe_high_water_mark_minor_gc_drops_per_invocation</a>=<an integer, >= 0></code> default: "10"</dt> +<dd> +<p>Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe_high_water_mark_threshold, when a minor GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that minor GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a minor GC event occurs and that retained heap percentage threshold is exceeded.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--skyframe_high_water_mark_threshold"><code id="skyframe_high_water_mark_threshold"><a href="#common_options-flag--skyframe_high_water_mark_threshold">--skyframe_high_water_mark_threshold</a>=<an integer></code> default: "85"</dt> +<dd> +<p>Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage is at least this threshold, it will drop unnecessary temporary Skyframe state. Tweaking this may let you mitigate wall time impact of GC thrashing, when the GC thrashing is (i) caused by the memory usage of this temporary state and (ii) more costly than reconstituting the state when it is needed.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--track_incremental_state"><code id="track_incremental_state"><a href="#common_options-flag--track_incremental_state">--[no]track_incremental_state</a></code> default: "true"</dt> +<dd> +<p>If false, Blaze will not persist data that allows for invalidation and re-evaluation on incremental builds in order to save memory on this build. Subsequent builds will not have any incrementality with respect to this one. Usually you will want to specify --batch when setting this to false.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="common_options-flag--announce_rc"><code id="announce_rc"><a href="#common_options-flag--announce_rc">--[no]announce_rc</a></code> default: "false"</dt> +<dd> +<p>Whether to announce rc options.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--attempt_to_print_relative_paths"><code id="attempt_to_print_relative_paths"><a href="#common_options-flag--attempt_to_print_relative_paths">--[no]attempt_to_print_relative_paths</a></code> default: "false"</dt> +<dd> +<p>When printing the location part of messages, attempt to use a path relative to the workspace directory or one of the directories specified by --package_path.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="common_options-flag--bes_backend"><code id="bes_backend"><a href="#common_options-flag--bes_backend">--bes_backend</a>=<a string></code> default: ""</dt> +<dd> +<p>Specifies the build event service (BES) backend endpoint in the form [SCHEME://]HOST[:PORT]. The default is to disable BES uploads. Supported schemes are grpc and grpcs (grpc with TLS enabled). If no scheme is provided, Bazel assumes grpcs.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_check_preceding_lifecycle_events"><code id="bes_check_preceding_lifecycle_events"><a href="#common_options-flag--bes_check_preceding_lifecycle_events">--[no]bes_check_preceding_lifecycle_events</a></code> default: "false"</dt> +<dd> +<p>Sets the field check_preceding_lifecycle_events_present on PublishBuildToolEventStreamRequest which tells BES to check whether it previously received InvocationAttemptStarted and BuildEnqueued events matching the current tool event.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_header"><code id="bes_header"><a href="#common_options-flag--bes_header">--bes_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header in NAME=VALUE form that will be included in BES requests. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_instance_name"><code id="bes_instance_name"><a href="#common_options-flag--bes_instance_name">--bes_instance_name</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies the instance name under which the BES will persist uploaded BEP. Defaults to null.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_keywords"><code id="bes_keywords"><a href="#common_options-flag--bes_keywords">--bes_keywords</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies a list of notification keywords to be added the default set of keywords published to BES ("command_name=<command_name> ", "protocol_name=BEP"). Defaults to none.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_lifecycle_events"><code id="bes_lifecycle_events"><a href="#common_options-flag--bes_lifecycle_events">--[no]bes_lifecycle_events</a></code> default: "true"</dt> +<dd> +<p>Specifies whether to publish BES lifecycle events. (defaults to 'true').</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_oom_finish_upload_timeout"><code id="bes_oom_finish_upload_timeout"><a href="#common_options-flag--bes_oom_finish_upload_timeout">--bes_oom_finish_upload_timeout</a>=<An immutable length of time.></code> default: "10m"</dt> +<dd> +<p>Specifies how long bazel should wait for the BES/BEP upload to complete while OOMing. This flag ensures termination when the JVM is severely GC thrashing and cannot make progress on any user thread.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--bes_outerr_buffer_size"><code id="bes_outerr_buffer_size"><a href="#common_options-flag--bes_outerr_buffer_size">--bes_outerr_buffer_size</a>=<an integer></code> default: "10240"</dt> +<dd> +<p>Specifies the maximal size of stdout or stderr to be buffered in BEP, before it is reported as a progress event. Individual writes are still reported in a single event, even if larger than the specified value up to --bes_outerr_chunk_size.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_outerr_chunk_size"><code id="bes_outerr_chunk_size"><a href="#common_options-flag--bes_outerr_chunk_size">--bes_outerr_chunk_size</a>=<an integer></code> default: "1048576"</dt> +<dd> +<p>Specifies the maximal size of stdout or stderr to be sent to BEP in a single message.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_proxy"><code id="bes_proxy"><a href="#common_options-flag--bes_proxy">--bes_proxy</a>=<a string></code> default: see description</dt> +<dd> +<p>Connect to the Build Event Service through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket).</p> +</dd> +<dt id="common_options-flag--bes_results_url"><code id="bes_results_url"><a href="#common_options-flag--bes_results_url">--bes_results_url</a>=<a string></code> default: ""</dt> +<dd> +<p>Specifies the base URL where a user can view the information streamed to the BES backend. Bazel will output the URL appended by the invocation id to the terminal.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="common_options-flag--bes_system_keywords"><code id="bes_system_keywords"><a href="#common_options-flag--bes_system_keywords">--bes_system_keywords</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies a list of notification keywords to be included directly, without the "user_keyword=" prefix included for keywords supplied via --bes_keywords. Intended for Build service operators that set --bes_lifecycle_events=false and include keywords when calling PublishLifecycleEvent. Build service operators using this flag should prevent users from overriding the flag value.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_timeout"><code id="bes_timeout"><a href="#common_options-flag--bes_timeout">--bes_timeout</a>=<An immutable length of time.></code> default: "0s"</dt> +<dd> +<p>Specifies how long bazel should wait for the BES/BEP upload to complete after the build and tests have finished. A valid timeout is a natural number followed by a unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The default value is '0' which means that there is no timeout.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--bes_upload_mode"><code id="bes_upload_mode"><a href="#common_options-flag--bes_upload_mode">--bes_upload_mode</a>=<wait_for_upload_complete, nowait_for_upload_complete or fully_async></code> default: "wait_for_upload_complete"</dt> +<dd> +<p>Specifies whether the Build Event Service upload should block the build completion or should end the invocation immediately and finish the upload in the background.</p> +<ul> +<li><code>wait_for_upload_complete</code>: blocks at the end of the current invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend.</li> +<li><code>nowait_for_upload_complete</code>: blocks at the beginning of the next invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend.</li> +<li><code>fully_async</code>: blocks at the beginning of the next invocation until all events are uploaded but does not wait for acknowledgements. Events may be lost in case of (transient) failures and backends may report streams as incomplete in this mode. There is no guarantee that <code>FinishInvocationAttempt</code> or <code>FinishBuild</code> lifecycle events are sent.</li> +</ul> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="common_options-flag--build_event_binary_file"><code id="build_event_binary_file"><a href="#common_options-flag--build_event_binary_file">--build_event_binary_file</a>=<a string></code> default: ""</dt> +<dd> +<p>If non-empty, write a varint delimited binary representation of representation of the build event protocol to that file. This option implies --bes_upload_mode=wait_for_upload_complete.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--build_event_binary_file_path_conversion"><code id="build_event_binary_file_path_conversion"><a href="#common_options-flag--build_event_binary_file_path_conversion">--[no]build_event_binary_file_path_conversion</a></code> default: "true"</dt> +<dd> +<p>Convert paths in the binary file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--build_event_binary_file_upload_mode"><code id="build_event_binary_file_upload_mode"><a href="#common_options-flag--build_event_binary_file_upload_mode">--build_event_binary_file_upload_mode</a>=<wait_for_upload_complete, nowait_for_upload_complete or fully_async></code> default: "wait_for_upload_complete"</dt> +<dd> +<p>Specifies whether the Build Event Service upload for --build_event_binary_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="common_options-flag--build_event_json_file"><code id="build_event_json_file"><a href="#common_options-flag--build_event_json_file">--build_event_json_file</a>=<a string></code> default: ""</dt> +<dd> +<p>If non-empty, write a JSON serialisation of the build event protocol to that file. This option implies --bes_upload_mode=wait_for_upload_complete.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--build_event_json_file_path_conversion"><code id="build_event_json_file_path_conversion"><a href="#common_options-flag--build_event_json_file_path_conversion">--[no]build_event_json_file_path_conversion</a></code> default: "true"</dt> +<dd> +<p>Convert paths in the json file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--build_event_json_file_upload_mode"><code id="build_event_json_file_upload_mode"><a href="#common_options-flag--build_event_json_file_upload_mode">--build_event_json_file_upload_mode</a>=<wait_for_upload_complete, nowait_for_upload_complete or fully_async></code> default: "wait_for_upload_complete"</dt> +<dd> +<p>Specifies whether the Build Event Service upload for --build_event_json_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="common_options-flag--build_event_max_named_set_of_file_entries"><code id="build_event_max_named_set_of_file_entries"><a href="#common_options-flag--build_event_max_named_set_of_file_entries">--build_event_max_named_set_of_file_entries</a>=<an integer></code> default: "5000"</dt> +<dd> +<p>The maximum number of entries for a single named_set_of_files event; values smaller than 2 are ignored and no event splitting is performed. This is intended for limiting the maximum event size in the build event protocol, although it does not directly control event size. The total event size is a function of the structure of the set as well as the file and uri lengths, which may in turn depend on the hash function.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--build_event_publish_all_actions"><code id="build_event_publish_all_actions"><a href="#common_options-flag--build_event_publish_all_actions">--[no]build_event_publish_all_actions</a></code> default: "false"</dt> +<dd> +<p>Whether all actions should be published.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--build_event_text_file"><code id="build_event_text_file"><a href="#common_options-flag--build_event_text_file">--build_event_text_file</a>=<a string></code> default: ""</dt> +<dd> +<p>If non-empty, write a textual representation of the build event protocol to that file</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--build_event_text_file_path_conversion"><code id="build_event_text_file_path_conversion"><a href="#common_options-flag--build_event_text_file_path_conversion">--[no]build_event_text_file_path_conversion</a></code> default: "true"</dt> +<dd> +<p>Convert paths in the text file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--build_event_text_file_upload_mode"><code id="build_event_text_file_upload_mode"><a href="#common_options-flag--build_event_text_file_upload_mode">--build_event_text_file_upload_mode</a>=<wait_for_upload_complete, nowait_for_upload_complete or fully_async></code> default: "wait_for_upload_complete"</dt> +<dd> +<p>Specifies whether the Build Event Service upload for --build_event_text_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="common_options-flag--build_event_upload_max_retries"><code id="build_event_upload_max_retries"><a href="#common_options-flag--build_event_upload_max_retries">--build_event_upload_max_retries</a>=<an integer></code> default: "4"</dt> +<dd> +<p>The maximum number of times Bazel should retry uploading a build event.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--experimental_bep_target_summary"><code id="experimental_bep_target_summary"><a href="#common_options-flag--experimental_bep_target_summary">--[no]experimental_bep_target_summary</a></code> default: "false"</dt> +<dd> +<p>Whether to publish TargetSummary events.</p> +</dd> +<dt id="common_options-flag--experimental_build_event_expand_filesets"><code id="experimental_build_event_expand_filesets"><a href="#common_options-flag--experimental_build_event_expand_filesets">--[no]experimental_build_event_expand_filesets</a></code> default: "false"</dt> +<dd> +<p>If true, expand Filesets in the BEP when presenting output files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--experimental_build_event_output_group_mode"><code id="experimental_build_event_output_group_mode"><a href="#common_options-flag--experimental_build_event_output_group_mode">--experimental_build_event_output_group_mode</a>=<an output group name followed by an OutputGroupFileMode, e.g. default=both></code> multiple uses are accumulated</dt> +<dd> +<p>Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED_SET_OF_FILES_ONLY', 'INLINE_ONLY', or 'BOTH'. The default value is 'NAMED_SET_OF_FILES_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental_build_event_output_group_mode=baseline.lcov=both</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--experimental_build_event_upload_retry_minimum_delay"><code id="experimental_build_event_upload_retry_minimum_delay"><a href="#common_options-flag--experimental_build_event_upload_retry_minimum_delay">--experimental_build_event_upload_retry_minimum_delay</a>=<An immutable length of time.></code> default: "1s"</dt> +<dd> +<p>Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6)</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--experimental_build_event_upload_strategy"><code id="experimental_build_event_upload_strategy"><a href="#common_options-flag--experimental_build_event_upload_strategy">--experimental_build_event_upload_strategy</a>=<a string></code> default: see description</dt> +<dd> +<p>Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--experimental_collect_load_average_in_profiler"><code id="experimental_collect_load_average_in_profiler"><a href="#common_options-flag--experimental_collect_load_average_in_profiler">--[no]experimental_collect_load_average_in_profiler</a></code> default: "true"</dt> +<dd> +<p>If enabled, the profiler collects the system's overall load average.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_collect_pressure_stall_indicators"><code id="experimental_collect_pressure_stall_indicators"><a href="#common_options-flag--experimental_collect_pressure_stall_indicators">--[no]experimental_collect_pressure_stall_indicators</a></code> default: "false"</dt> +<dd> +<p>If enabled, the profiler collects the Linux PSI data.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_collect_resource_estimation"><code id="experimental_collect_resource_estimation"><a href="#common_options-flag--experimental_collect_resource_estimation">--[no]experimental_collect_resource_estimation</a></code> default: "false"</dt> +<dd> +<p>If enabled, the profiler collects CPU and memory usage estimation for local actions.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_collect_skyframe_counts_in_profiler"><code id="experimental_collect_skyframe_counts_in_profiler"><a href="#common_options-flag--experimental_collect_skyframe_counts_in_profiler">--[no]experimental_collect_skyframe_counts_in_profiler</a></code> default: "false"</dt> +<dd> +<p>If enabled, the profiler collects SkyFunction counts in the Skyframe graph over time for key function types, like configured targets and action executions. May have a performance hit as this visits the ENTIRE Skyframe graph at every profiling time unit. Do not use this flag with performance-critical measurements.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_collect_system_network_usage"><code id="experimental_collect_system_network_usage"><a href="#common_options-flag--experimental_collect_system_network_usage">--[no]experimental_collect_system_network_usage</a></code> default: "true"</dt> +<dd> +<p>If enabled, the profiler collects the system's network usage.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_collect_worker_data_in_profiler"><code id="experimental_collect_worker_data_in_profiler"><a href="#common_options-flag--experimental_collect_worker_data_in_profiler">--[no]experimental_collect_worker_data_in_profiler</a></code> default: "true"</dt> +<dd> +<p>If enabled, the profiler collects worker's aggregated resource data.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_command_profile"><code id="experimental_command_profile"><a href="#common_options-flag--experimental_command_profile">--experimental_command_profile</a>=<cpu, wall, alloc or lock></code> default: see description</dt> +<dd> +<p>Records a Java Flight Recorder profile for the duration of the command. One of the supported profiling event types (cpu, wall, alloc or lock) must be given as an argument. The profile is written to a file named after the event type under the output base directory. The syntax and semantics of this flag might change in the future to support additional profile types or output formats; use at your own risk.</p> +</dd> +<dt id="common_options-flag--experimental_profile_additional_tasks"><code id="experimental_profile_additional_tasks"><a href="#common_options-flag--experimental_profile_additional_tasks">--experimental_profile_additional_tasks</a>=<phase, action, discover_inputs, action_check, action_lock, action_update, action_complete, action_rewinding, bzlmod, info, create_package, remote_execution, local_execution, scanner, local_parse, upload_time, remote_process_time, remote_queue, remote_setup, fetch, local_process_time, vfs_stat, vfs_dir, vfs_readlink, vfs_md5, vfs_xattr, vfs_delete, vfs_open, vfs_read, vfs_write, vfs_glob, vfs_vmfs_stat, vfs_vmfs_dir, vfs_vmfs_read, wait, thread_name, thread_sort_index, skyframe_eval, skyfunction, critical_path, critical_path_component, handle_gc_notification, local_action_counts, starlark_parser, starlark_user_fn, starlark_builtin_fn, starlark_user_compiled_fn, starlark_repository_fn, action_fs_staging, remote_cache_check, remote_download, remote_network, filesystem_traversal, worker_execution, worker_setup, worker_borrow, worker_working, worker_copying_outputs, credential_helper, conflict_check, dynamic_lock, repository_fetch, repository_vendor, repo_cache_gc_wait, spawn_log, rpc, skycache, wasm_load, wasm_exec or unknown></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional profile tasks to be included in the profile.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_profile_include_primary_output"><code id="experimental_profile_include_primary_output"><a href="#common_options-flag--experimental_profile_include_primary_output">--[no]experimental_profile_include_primary_output</a></code> default: "false"</dt> +<dd> +<p>Includes the extra "out" attribute in action events that contains the exec path to the action's primary output.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_profile_include_target_configuration"><code id="experimental_profile_include_target_configuration"><a href="#common_options-flag--experimental_profile_include_target_configuration">--[no]experimental_profile_include_target_configuration</a></code> default: "false"</dt> +<dd> +<p>Includes target configuration hash in action events' JSON profile data.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_profile_include_target_label"><code id="experimental_profile_include_target_label"><a href="#common_options-flag--experimental_profile_include_target_label">--[no]experimental_profile_include_target_label</a></code> default: "false"</dt> +<dd> +<p>Includes target label in action events' JSON profile data.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_record_metrics_for_all_mnemonics"><code id="experimental_record_metrics_for_all_mnemonics"><a href="#common_options-flag--experimental_record_metrics_for_all_mnemonics">--[no]experimental_record_metrics_for_all_mnemonics</a></code> default: "false"</dt> +<dd> +<p>Controls the output of BEP ActionSummary and BuildGraphMetrics, limiting the number of mnemonics in ActionData and number of entries reported in BuildGraphMetrics.AspectCount/RuleClassCount. By default the number of types is limited to the top 20, by number of executed actions for ActionData, and instances for RuleClass and Asepcts. Setting this option will write statistics for all mnemonics, rule classes and aspects.</p> +</dd> +<dt id="common_options-flag--experimental_record_skyframe_metrics"><code id="experimental_record_skyframe_metrics"><a href="#common_options-flag--experimental_record_skyframe_metrics">--[no]experimental_record_skyframe_metrics</a></code> default: "false"</dt> +<dd> +<p>Controls the output of BEP BuildGraphMetrics, including expensiveto compute skyframe metrics about Skykeys, RuleClasses and Aspects.With this flag set to false BuildGraphMetrics.rule_count and aspectfields will not be populated in the BEP.</p> +</dd> +<dt id="common_options-flag--experimental_run_bep_event_include_residue"><code id="experimental_run_bep_event_include_residue"><a href="#common_options-flag--experimental_run_bep_event_include_residue">--[no]experimental_run_bep_event_include_residue</a></code> default: "false"</dt> +<dd> +<p>Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--experimental_stream_log_file_uploads"><code id="experimental_stream_log_file_uploads"><a href="#common_options-flag--experimental_stream_log_file_uploads">--[no]experimental_stream_log_file_uploads</a></code> default: "false"</dt> +<dd> +<p>Stream log file uploads directly to the remote storage rather than writing them to disk.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--experimental_workspace_rules_log_file"><code id="experimental_workspace_rules_log_file"><a href="#common_options-flag--experimental_workspace_rules_log_file">--experimental_workspace_rules_log_file</a>=<a path></code> default: see description</dt> +<dd> +<p>Log certain Workspace Rules events into this file as delimited WorkspaceEvent protos.</p> +</dd> +<dt id="common_options-flag--generate_json_trace_profile"><code id="generate_json_trace_profile"><a href="#common_options-flag--generate_json_trace_profile">--[no]generate_json_trace_profile</a></code> default: "auto"</dt> +<dd> +<p>If enabled, Bazel profiles the build and writes a JSON-format profile into a file in the output base. View profile by loading into chrome://tracing. By default Bazel writes the profile for all build-like commands and query.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--heap_dump_on_oom"><code id="heap_dump_on_oom"><a href="#common_options-flag--heap_dump_on_oom">--[no]heap_dump_on_oom</a></code> default: "false"</dt> +<dd> +<p>Whether to manually output a heap dump if an OOM is thrown (including manual OOMs due to reaching --gc_thrashing_limits). The dump will be written to <output_base>/<invocation_id>.heapdump.hprof. This option effectively replaces -XX:+HeapDumpOnOutOfMemoryError, which has no effect for manual OOMs.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--jvm_heap_histogram_internal_object_pattern"><code id="jvm_heap_histogram_internal_object_pattern"><a href="#common_options-flag--jvm_heap_histogram_internal_object_pattern">--jvm_heap_histogram_internal_object_pattern</a>=<a valid Java regular expression></code> default: "jdk\.internal\.vm\.Filler.+"</dt> +<dd> +<p>Regex for overriding the matching logic for JDK21+ JVM heap memory collection. We are relying on volatile internal G1 GC implemenation details to get a clean memory metric, this option allows us to adapt to changes in that internal implementation without having to wait for a binary release. Passed to JDK Matcher.find()</p> +</dd> +<dt id="common_options-flag--legacy_important_outputs"><code id="legacy_important_outputs"><a href="#common_options-flag--legacy_important_outputs">--[no]legacy_important_outputs</a></code> default: "false"</dt> +<dd> +<p>Use this to suppress generation of the legacy important_outputs field in the TargetComplete event. important_outputs are required for Bazel to ResultStore/BTX integration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--logging"><code id="logging"><a href="#common_options-flag--logging">--logging</a>=<0 <= an integer <= 6></code> default: "3"</dt> +<dd> +<p>The logging level.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--memory_profile"><code id="memory_profile"><a href="#common_options-flag--memory_profile">--memory_profile</a>=<a path></code> default: see description</dt> +<dd> +<p>If set, write memory usage data to the specified file at phase ends and stable heap to master log at end of build.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--memory_profile_stable_heap_parameters"><code id="memory_profile_stable_heap_parameters"><a href="#common_options-flag--memory_profile_stable_heap_parameters">--memory_profile_stable_heap_parameters</a>=<integers, separated by a comma expected in pairs></code> default: "1,0"</dt> +<dd> +<p>Tune memory profile's computation of stable heap at end of build. Should be and even number of integers separated by commas. In each pair the first integer is the number of GCs to perform. The second integer in each pair is the number of seconds to wait between GCs. Ex: 2,4,4,0 would 2 GCs with a 4sec pause, followed by 4 GCs with zero second pause</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--profile"><code id="profile"><a href="#common_options-flag--profile">--profile</a>=<a path></code> default: see description</dt> +<dd> +<p>If set, profile Bazel and write data to the specified file. See https://bazel.build/advanced/performance/json-trace-profile for more information.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--profiles_to_retain"><code id="profiles_to_retain"><a href="#common_options-flag--profiles_to_retain">--profiles_to_retain</a>=<an integer></code> default: "5"</dt> +<dd> +<p>Number of profiles to retain in the output base. If there are more than this number of profiles in the output base, the oldest are deleted until the total is under the limit.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--record_full_profiler_data"><code id="record_full_profiler_data"><a href="#common_options-flag--record_full_profiler_data">--[no]record_full_profiler_data</a></code> default: "false"</dt> +<dd> +<p>By default, Bazel profiler will record only aggregated data for fast but numerous events (such as statting the file). If this option is enabled, profiler will record each event - resulting in more precise profiling data but LARGE performance hit. Option only has effect if --profile used as well.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--redirect_local_instrumentation_output_writes"><code id="redirect_local_instrumentation_output_writes"><a href="#common_options-flag--redirect_local_instrumentation_output_writes">--[no]redirect_local_instrumentation_output_writes</a></code> default: "false"</dt> +<dd> +<p>If true and supported, instrumentation output is redirected to be written locally on a different machine than where bazel is running on.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--remote_print_execution_messages"><code id="remote_print_execution_messages"><a href="#common_options-flag--remote_print_execution_messages">--remote_print_execution_messages</a>=<failure, success or all></code> default: "failure"</dt> +<dd> +<p>Choose when to print remote execution messages. Valid values are <code>failure</code>, to print only on failures, <code>success</code> to print only on successes and <code>all</code> to print always.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="common_options-flag--slim_profile"><code id="slim_profile"><a href="#common_options-flag--slim_profile">--[no]slim_profile</a></code> default: "true"</dt> +<dd> +<p>Slims down the size of the JSON profile by merging events if the profile gets too large.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--starlark_cpu_profile"><code id="starlark_cpu_profile"><a href="#common_options-flag--starlark_cpu_profile">--starlark_cpu_profile</a>=<a string></code> default: ""</dt> +<dd> +<p>Writes into the specified file a pprof profile of CPU usage by all Starlark threads.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--tool_tag"><code id="tool_tag"><a href="#common_options-flag--tool_tag">--tool_tag</a>=<a string></code> default: ""</dt> +<dd> +<p>A tool name to attribute this Bazel invocation to.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--ui_event_filters"><code id="ui_event_filters"><a href="#common_options-flag--ui_event_filters">--ui_event_filters</a>=<Convert list of comma separated event kind to list of filters></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies which events to show in the UI. It is possible to add or remove events to the default ones using leading +/-, or override the default set completely with direct assignment. The set of supported event kinds include INFO, DEBUG, ERROR and more.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="common_options-flag--write_command_log"><code id="write_command_log"><a href="#common_options-flag--write_command_log">--[no]write_command_log</a></code> default: "false"</dt> +<dd> +<p>Whether or not to write the command.log file</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +</dl> +<dl>Remote caching and execution options: +<dt id="common_options-flag--downloader_config"><code id="downloader_config"><a href="#common_options-flag--downloader_config">--downloader_config</a>=<a path></code> default: see description</dt> +<dd> +<p>Specify a file to configure the remote downloader with. This file consists of lines, each of which starts with a directive (<code>allow</code>, <code>block</code> or <code>rewrite</code>) followed by either a host name (for <code>allow</code> and <code>block</code>) or two patterns, one to match against, and one to use as a substitute URL, with back-references starting from <code>$1</code>. It is possible for multiple <code>rewrite</code> directives for the same URL to be given, and in this case multiple URLs will be returned.</p> +</dd> +<dt id="common_options-flag--experimental_circuit_breaker_strategy"><code id="experimental_circuit_breaker_strategy"><a href="#common_options-flag--experimental_circuit_breaker_strategy">--experimental_circuit_breaker_strategy</a>=<failure></code> default: see description</dt> +<dd> +<p>Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="common_options-flag--experimental_remote_cache_compression_threshold"><code id="experimental_remote_cache_compression_threshold"><a href="#common_options-flag--experimental_remote_cache_compression_threshold">--experimental_remote_cache_compression_threshold</a>=<an integer></code> default: "100"</dt> +<dd> +<p>The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote_cache_compression is set.</p> +</dd> +<dt id="common_options-flag--experimental_remote_cache_lease_extension"><code id="experimental_remote_cache_lease_extension"><a href="#common_options-flag--experimental_remote_cache_lease_extension">--[no]experimental_remote_cache_lease_extension</a></code> default: "false"</dt> +<dd> +<p>If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending <code>FindMissingBlobs</code> calls periodically to remote cache. The frequency is based on the value of <code>--experimental_remote_cache_ttl</code>.</p> +</dd> +<dt id="common_options-flag--experimental_remote_cache_ttl"><code id="experimental_remote_cache_ttl"><a href="#common_options-flag--experimental_remote_cache_ttl">--experimental_remote_cache_ttl</a>=<An immutable length of time.></code> default: "3h"</dt> +<dd> +<p>The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="common_options-flag--experimental_remote_capture_corrupted_outputs"><code id="experimental_remote_capture_corrupted_outputs"><a href="#common_options-flag--experimental_remote_capture_corrupted_outputs">--experimental_remote_capture_corrupted_outputs</a>=<a path></code> default: see description</dt> +<dd> +<p>A path to a directory where the corrupted outputs will be captured to.</p> +</dd> +<dt id="common_options-flag--experimental_remote_discard_merkle_trees"><code id="experimental_remote_discard_merkle_trees"><a href="#common_options-flag--experimental_remote_discard_merkle_trees">--[no]experimental_remote_discard_merkle_trees</a></code> default: "true"</dt> +<dd> +<p>If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries.</p> +</dd> +<dt id="common_options-flag--experimental_remote_downloader"><code id="experimental_remote_downloader"><a href="#common_options-flag--experimental_remote_downloader">--experimental_remote_downloader</a>=<a string></code> default: see description</dt> +<dd> +<p>A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote_asset.proto</p> +</dd> +<dt id="common_options-flag--experimental_remote_downloader_local_fallback"><code id="experimental_remote_downloader_local_fallback"><a href="#common_options-flag--experimental_remote_downloader_local_fallback">--[no]experimental_remote_downloader_local_fallback</a></code> default: "false"</dt> +<dd> +<p>Whether to fall back to the local downloader if remote downloader fails.</p> +</dd> +<dt id="common_options-flag--experimental_remote_downloader_propagate_credentials"><code id="experimental_remote_downloader_propagate_credentials"><a href="#common_options-flag--experimental_remote_downloader_propagate_credentials">--[no]experimental_remote_downloader_propagate_credentials</a></code> default: "false"</dt> +<dd> +<p>Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new <code>http_header_url:&lt;url-index&gt;:&lt;header-key&gt;</code> qualifier where the <code>&lt;url-index&gt;</code> is a 0-based position of the URL inside the FetchBlobRequest's <code>uris</code> field. The URL-specific headers should take precedence over the global headers.</p> +</dd> +<dt id="common_options-flag--experimental_remote_execution_keepalive"><code id="experimental_remote_execution_keepalive"><a href="#common_options-flag--experimental_remote_execution_keepalive">--[no]experimental_remote_execution_keepalive</a></code> default: "false"</dt> +<dd> +<p>Whether to use keepalive for remote execution calls.</p> +</dd> +<dt id="common_options-flag--experimental_remote_failure_rate_threshold"><code id="experimental_remote_failure_rate_threshold"><a href="#common_options-flag--experimental_remote_failure_rate_threshold">--experimental_remote_failure_rate_threshold</a>=<an integer in 0-100 range></code> default: "10"</dt> +<dd> +<p>Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="common_options-flag--experimental_remote_failure_window_interval"><code id="experimental_remote_failure_window_interval"><a href="#common_options-flag--experimental_remote_failure_window_interval">--experimental_remote_failure_window_interval</a>=<An immutable length of time.></code> default: "60s"</dt> +<dd> +<p>The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="common_options-flag--experimental_remote_mark_tool_inputs"><code id="experimental_remote_mark_tool_inputs"><a href="#common_options-flag--experimental_remote_mark_tool_inputs">--[no]experimental_remote_mark_tool_inputs</a></code> default: "false"</dt> +<dd> +<p>If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers.</p> +</dd> +<dt id="common_options-flag--experimental_remote_merkle_tree_cache"><code id="experimental_remote_merkle_tree_cache"><a href="#common_options-flag--experimental_remote_merkle_tree_cache">--[no]experimental_remote_merkle_tree_cache</a></code> default: "false"</dt> +<dd> +<p>If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental_remote_merkle_tree_cache_size.</p> +</dd> +<dt id="common_options-flag--experimental_remote_merkle_tree_cache_size"><code id="experimental_remote_merkle_tree_cache_size"><a href="#common_options-flag--experimental_remote_merkle_tree_cache_size">--experimental_remote_merkle_tree_cache_size</a>=<a long integer></code> default: "1000"</dt> +<dd> +<p>The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000.</p> +</dd> +<dt id="common_options-flag--experimental_remote_output_service"><code id="experimental_remote_output_service"><a href="#common_options-flag--experimental_remote_output_service">--experimental_remote_output_service</a>=<a string></code> default: see description</dt> +<dd> +<p>HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS.</p> +</dd> +<dt id="common_options-flag--experimental_remote_output_service_output_path_prefix"><code id="experimental_remote_output_service_output_path_prefix"><a href="#common_options-flag--experimental_remote_output_service_output_path_prefix">--experimental_remote_output_service_output_path_prefix</a>=<a string></code> default: ""</dt> +<dd> +<p>The path under which the contents of output directories managed by the --experimental_remote_output_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service.</p> +</dd> +<dt id="common_options-flag--experimental_remote_require_cached"><code id="experimental_remote_require_cached"><a href="#common_options-flag--experimental_remote_require_cached">--[no]experimental_remote_require_cached</a></code> default: "false"</dt> +<dd> +<p>If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache.</p> +</dd> +<dt id="common_options-flag--experimental_remote_scrubbing_config"><code id="experimental_remote_scrubbing_config"><a href="#common_options-flag--experimental_remote_scrubbing_config">--experimental_remote_scrubbing_config</a>=<Converts to a Scrubber></code> default: see description</dt> +<dd> +<p>Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote_scrubbing.proto).</p> +<p>This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds.</p> +<p>Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead.</p> +<p>Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions.</p> +<p>In order to successfully use this feature, you likely want to set a custom --host_platform together with --experimental_platform_in_output_dir (to normalize output prefixes) and --incompatible_strict_action_env (to normalize environment variables).</p> +</dd> +<dt id="common_options-flag--guard_against_concurrent_changes"><code id="guard_against_concurrent_changes"><a href="#common_options-flag--guard_against_concurrent_changes">--[no]guard_against_concurrent_changes</a></code> default: "lite"</dt> +<dd> +<p>Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="common_options-flag--remote_accept_cached"><code id="remote_accept_cached"><a href="#common_options-flag--remote_accept_cached">--[no]remote_accept_cached</a></code> default: "true"</dt> +<dd> +<p>Whether to accept remotely cached action results.</p> +</dd> +<dt id="common_options-flag--remote_build_event_upload"><code id="remote_build_event_upload"><a href="#common_options-flag--remote_build_event_upload">--remote_build_event_upload</a>=<all or minimal></code> default: "minimal"</dt> +<dd> +<p>If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. +If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. +Default to 'minimal'.</p> +</dd> +<dt id="common_options-flag--remote_bytestream_uri_prefix"><code id="remote_bytestream_uri_prefix"><a href="#common_options-flag--remote_bytestream_uri_prefix">--remote_bytestream_uri_prefix</a>=<a string></code> default: see description</dt> +<dd> +<p>The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote_executor and --remote_instance_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "${hostname}/${instance_name}".</p> +</dd> +<dt id="common_options-flag--remote_cache"><code id="remote_cache"><a href="#common_options-flag--remote_cache">--remote_cache</a>=<a string></code> default: see description</dt> +<dd> +<p>A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching</p> +</dd> +<dt id="common_options-flag--remote_cache_async"><code id="remote_cache_async"><a href="#common_options-flag--remote_cache_async">--[no]remote_cache_async</a></code> default: "true"</dt> +<dd> +<p>If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set.</p> +</dd> +<dt id="common_options-flag--remote_cache_compression"><code id="remote_cache_compression"><a href="#common_options-flag--remote_cache_compression">--[no]remote_cache_compression</a></code> default: "false"</dt> +<dd> +<p>If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental_remote_cache_compression_threshold.</p> +</dd> +<dt id="common_options-flag--remote_cache_header"><code id="remote_cache_header"><a href="#common_options-flag--remote_cache_header">--remote_cache_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header that will be included in cache requests: --remote_cache_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +</dd> +<dt id="common_options-flag--remote_default_exec_properties"><code id="remote_default_exec_properties"><a href="#common_options-flag--remote_default_exec_properties">--remote_default_exec_properties</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec_properties.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--remote_default_platform_properties"><code id="remote_default_platform_properties"><a href="#common_options-flag--remote_default_platform_properties">--remote_default_platform_properties</a>=<a string></code> default: ""</dt> +<dd> +<p>Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote_execution_properties. This value will also be used if the host platform is selected as the execution platform for remote execution.</p> +</dd> +<dt id="common_options-flag--remote_download_regex"><code id="remote_download_regex"><a href="#common_options-flag--remote_download_regex">--remote_download_regex</a>=<a valid Java regular expression></code> multiple uses are accumulated</dt> +<dd> +<p>Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote_download_outputs. Multiple patterns may be specified by repeating this flag.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="common_options-flag--remote_downloader_header"><code id="remote_downloader_header"><a href="#common_options-flag--remote_downloader_header">--remote_downloader_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header that will be included in remote downloader requests: --remote_downloader_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +</dd> +<dt id="common_options-flag--remote_exec_header"><code id="remote_exec_header"><a href="#common_options-flag--remote_exec_header">--remote_exec_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header that will be included in execution requests: --remote_exec_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +</dd> +<dt id="common_options-flag--remote_execution_priority"><code id="remote_execution_priority"><a href="#common_options-flag--remote_execution_priority">--remote_execution_priority</a>=<an integer></code> default: "0"</dt> +<dd> +<p>The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent.</p> +</dd> +<dt id="common_options-flag--remote_executor"><code id="remote_executor"><a href="#common_options-flag--remote_executor">--remote_executor</a>=<a string></code> default: see description</dt> +<dd> +<p>HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS.</p> +</dd> +<dt id="common_options-flag--remote_grpc_log"><code id="remote_grpc_log"><a href="#common_options-flag--remote_grpc_log">--remote_grpc_log</a>=<a path></code> default: see description</dt> +<dd> +<p>If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream).</p> +</dd> +<dt id="common_options-flag--remote_header"><code id="remote_header"><a href="#common_options-flag--remote_header">--remote_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header that will be included in requests: --remote_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +</dd> +<dt id="common_options-flag--remote_instance_name"><code id="remote_instance_name"><a href="#common_options-flag--remote_instance_name">--remote_instance_name</a>=<a string></code> default: ""</dt> +<dd> +<p>Value to pass as instance_name in the remote execution API.</p> +</dd> +<dt id="common_options-flag--remote_local_fallback"><code id="remote_local_fallback"><a href="#common_options-flag--remote_local_fallback">--[no]remote_local_fallback</a></code> default: "false"</dt> +<dd> +<p>Whether to fall back to standalone local execution strategy if remote execution fails.</p> +</dd> +<dt id="common_options-flag--remote_local_fallback_strategy"><code id="remote_local_fallback_strategy"><a href="#common_options-flag--remote_local_fallback_strategy">--remote_local_fallback_strategy</a>=<a string></code> default: "local"</dt> +<dd> +<p>Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details.</p> +</dd> +<dt id="common_options-flag--remote_max_connections"><code id="remote_max_connections"><a href="#common_options-flag--remote_max_connections">--remote_max_connections</a>=<an integer></code> default: "100"</dt> +<dd> +<p>Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. +For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote_max_connections concurrent requests. +For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around <code>--remote_max_connections * 100</code> concurrent requests.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--remote_proxy"><code id="remote_proxy"><a href="#common_options-flag--remote_proxy">--remote_proxy</a>=<a string></code> default: see description</dt> +<dd> +<p>Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket).</p> +</dd> +<dt id="common_options-flag--remote_result_cache_priority"><code id="remote_result_cache_priority"><a href="#common_options-flag--remote_result_cache_priority">--remote_result_cache_priority</a>=<an integer></code> default: "0"</dt> +<dd> +<p>The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent.</p> +</dd> +<dt id="common_options-flag--remote_retries"><code id="remote_retries"><a href="#common_options-flag--remote_retries">--remote_retries</a>=<an integer></code> default: "5"</dt> +<dd> +<p>The maximum number of attempts to retry a transient error. If set to 0, retries are disabled.</p> +</dd> +<dt id="common_options-flag--remote_retry_max_delay"><code id="remote_retry_max_delay"><a href="#common_options-flag--remote_retry_max_delay">--remote_retry_max_delay</a>=<An immutable length of time.></code> default: "5s"</dt> +<dd> +<p>The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> +</dd> +<dt id="common_options-flag--remote_timeout"><code id="remote_timeout"><a href="#common_options-flag--remote_timeout">--remote_timeout</a>=<An immutable length of time.></code> default: "60s"</dt> +<dd> +<p>The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> +</dd> +<dt id="common_options-flag--remote_upload_local_results"><code id="remote_upload_local_results"><a href="#common_options-flag--remote_upload_local_results">--[no]remote_upload_local_results</a></code> default: "true"</dt> +<dd> +<p>Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so.</p> +</dd> +<dt id="common_options-flag--remote_verify_downloads"><code id="remote_verify_downloads"><a href="#common_options-flag--remote_verify_downloads">--[no]remote_verify_downloads</a></code> default: "true"</dt> +<dd> +<p>If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value.</p> +</dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="common_options-flag--build_metadata"><code id="build_metadata"><a href="#common_options-flag--build_metadata">--build_metadata</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Custom key-value string pairs to supply in a build event.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="common_options-flag--color"><code id="color"><a href="#common_options-flag--color">--color</a>=<yes, no or auto></code> default: "auto"</dt> +<dd> +<p>Use terminal controls to colorize output.</p> +</dd> +<dt id="common_options-flag--config"><code id="config"><a href="#common_options-flag--config">--config</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Selects additional config sections from the rc files; for every <command>, it also pulls in the options from <command>:<config> if such a section exists; if this section doesn't exist in any .rc file, Blaze fails with an error. The config sections and flag combinations they are equivalent to are located in the tools/*.blazerc config files.</p> +</dd> +<dt id="common_options-flag--credential_helper"><code id="credential_helper"><a href="#common_options-flag--credential_helper">--credential_helper</a>=<Path to a credential helper. It may be absolute, relative to the PATH environment variable, or %workspace%-relative. The path be optionally prefixed by a scope followed by an '='. The scope is a domain name, optionally with a single leading '*' wildcard component. A helper applies to URIs matching its scope, with more specific scopes preferred. If a helper has no scope, it applies to every URI.></code> multiple uses are accumulated</dt> +<dd> +<p>Configures a credential helper conforming to the <a href="https://github.com/EngFlow/credential-helper-spec">Credential Helper Specification</a> to use for retrieving authorization credentials for repository fetching, remote caching and execution, and the build event service.</p> +<p>Credentials supplied by a helper take precedence over credentials supplied by <code>--google_default_credentials</code>, <code>--google_credentials</code>, a <code>.netrc</code> file, or the auth parameter to <code>repository_ctx.download()</code> and <code>repository_ctx.download_and_extract()</code>.</p> +<p>May be specified multiple times to set up multiple helpers.</p> +<p>See https://blog.engflow.com/2023/10/09/configuring-bazels-credential-helper/ for instructions.</p> +</dd> +<dt id="common_options-flag--credential_helper_cache_duration"><code id="credential_helper_cache_duration"><a href="#common_options-flag--credential_helper_cache_duration">--credential_helper_cache_duration</a>=<An immutable length of time.></code> default: "30m"</dt> +<dd> +<p>How long to cache credentials for if the credential helper doesn't return an expiration time. Changing the value of this flag clears the cache.</p> +</dd> +<dt id="common_options-flag--credential_helper_timeout"><code id="credential_helper_timeout"><a href="#common_options-flag--credential_helper_timeout">--credential_helper_timeout</a>=<An immutable length of time.></code> default: "10s"</dt> +<dd> +<p>Configures the timeout for a credential helper.</p> +<p>Credential helpers failing to respond within this timeout will fail the invocation.</p> +</dd> +<dt id="common_options-flag--curses"><code id="curses"><a href="#common_options-flag--curses">--curses</a>=<yes, no or auto></code> default: "auto"</dt> +<dd> +<p>Use terminal cursor controls to minimize scrolling output.</p> +</dd> +<dt id="common_options-flag--disk_cache"><code id="disk_cache"><a href="#common_options-flag--disk_cache">--disk_cache</a>=<a path></code> default: see description</dt> +<dd> +<p>A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created.</p> +</dd> +<dt id="common_options-flag--enable_platform_specific_config"><code id="enable_platform_specific_config"><a href="#common_options-flag--enable_platform_specific_config">--[no]enable_platform_specific_config</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel picks up host-OS-specific config lines from bazelrc files. For example, if the host OS is Linux and you run bazel build, Bazel picks up lines starting with build:linux. Supported OS identifiers are linux, macos, windows, freebsd, and openbsd. Enabling this flag is equivalent to using --config=linux on Linux, --config=windows on Windows, etc.</p> +</dd> +<dt id="common_options-flag--experimental_action_cache_gc_idle_delay"><code id="experimental_action_cache_gc_idle_delay"><a href="#common_options-flag--experimental_action_cache_gc_idle_delay">--experimental_action_cache_gc_idle_delay</a>=<An immutable length of time.></code> default: "5m"</dt> +<dd> +<p>How long the server must remain idle before a garbage collection of the action cache is attempted. Ineffectual unless --experimental_action_cache_gc_max_age is nonzero.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--experimental_action_cache_gc_max_age"><code id="experimental_action_cache_gc_max_age"><a href="#common_options-flag--experimental_action_cache_gc_max_age">--experimental_action_cache_gc_max_age</a>=<An immutable length of time.></code> default: "0"</dt> +<dd> +<p>If set to a nonzero value, the action cache will be periodically garbage collected to remove entries older than this age. Garbage collection occurs in the background once the server has become idle, as determined by the --experimental_action_cache_gc_idle_delay and --experimental_action_cache_gc_threshold flags.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--experimental_action_cache_gc_threshold"><code id="experimental_action_cache_gc_threshold"><a href="#common_options-flag--experimental_action_cache_gc_threshold">--experimental_action_cache_gc_threshold</a>=<an integer in 0-100 range></code> default: "10"</dt> +<dd> +<p>The percentage of stale action cache entries required for garbage collection to be triggered. Ineffectual unless --experimental_action_cache_gc_max_age is nonzero.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--experimental_disk_cache_gc_idle_delay"><code id="experimental_disk_cache_gc_idle_delay"><a href="#common_options-flag--experimental_disk_cache_gc_idle_delay">--experimental_disk_cache_gc_idle_delay</a>=<An immutable length of time.></code> default: "5m"</dt> +<dd> +<p>How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental_disk_cache_gc_max_size and/or --experimental_disk_cache_gc_max_age.</p> +</dd> +<dt id="common_options-flag--experimental_disk_cache_gc_max_age"><code id="experimental_disk_cache_gc_max_age"><a href="#common_options-flag--experimental_disk_cache_gc_max_age">--experimental_disk_cache_gc_max_age</a>=<An immutable length of time.></code> default: "0"</dt> +<dd> +<p>If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental_disk_cache_gc_max_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag.</p> +</dd> +<dt id="common_options-flag--experimental_disk_cache_gc_max_size"><code id="experimental_disk_cache_gc_max_size"><a href="#common_options-flag--experimental_disk_cache_gc_max_size">--experimental_disk_cache_gc_max_size</a>=<a size in bytes, optionally followed by a K, M, G or T multiplier></code> default: "0"</dt> +<dd> +<p>If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental_disk_cache_gc_max_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag.</p> +</dd> +<dt id="common_options-flag--experimental_enable_thread_dump"><code id="experimental_enable_thread_dump"><a href="#common_options-flag--experimental_enable_thread_dump">--[no]experimental_enable_thread_dump</a></code> default: "false"</dt> +<dd> +<p>Whether to enable thread dumps. If true, Bazel will dump the state of all threads (including virtual threads) to a file every --experimental_thread_dump_interval, or after action execution being inactive for --experimental_thread_dump_action_execution_inactivity_duration. The dumps will be written to the <output_base>/server/thread_dumps/ directory.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_install_base_gc_max_age"><code id="experimental_install_base_gc_max_age"><a href="#common_options-flag--experimental_install_base_gc_max_age">--experimental_install_base_gc_max_age</a>=<An immutable length of time.></code> default: "30d"</dt> +<dd> +<p>How long an install base must go unused before it's eligible for garbage collection. If nonzero, the server will attempt to garbage collect other install bases when idle.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="common_options-flag--experimental_rule_extension_api"><code id="experimental_rule_extension_api"><a href="#common_options-flag--experimental_rule_extension_api">--[no]experimental_rule_extension_api</a></code> default: "true"</dt> +<dd> +<p>Enable experimental rule extension API and subrule APIs</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="common_options-flag--experimental_thread_dump_action_execution_inactivity_duration"><code id="experimental_thread_dump_action_execution_inactivity_duration"><a href="#common_options-flag--experimental_thread_dump_action_execution_inactivity_duration">--experimental_thread_dump_action_execution_inactivity_duration</a>=<An immutable length of time.></code> default: "0"</dt> +<dd> +<p>Dump the threads when action execution being inactive for this duration. If zero, no thread dumps are written for action execution being inactive.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_thread_dump_interval"><code id="experimental_thread_dump_interval"><a href="#common_options-flag--experimental_thread_dump_interval">--experimental_thread_dump_interval</a>=<An immutable length of time.></code> default: "0"</dt> +<dd> +<p>How often to dump the threads periodically. If zero, no thread dumps are written periodically.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="common_options-flag--experimental_windows_watchfs"><code id="experimental_windows_watchfs"><a href="#common_options-flag--experimental_windows_watchfs">--[no]experimental_windows_watchfs</a></code> default: "false"</dt> +<dd> +<p>If true, experimental Windows support for --watchfs is enabled. Otherwise --watchfsis a non-op on Windows. Make sure to also enable --watchfs.</p> +</dd> +<dt id="common_options-flag--google_auth_scopes"><code id="google_auth_scopes"><a href="#common_options-flag--google_auth_scopes">--google_auth_scopes</a>=<comma-separated list of options></code> default: "https://www.googleapis.com/auth/cloud-platform"</dt> +<dd> +<p>A comma-separated list of Google Cloud authentication scopes.</p> +</dd> +<dt id="common_options-flag--google_credentials"><code id="google_credentials"><a href="#common_options-flag--google_credentials">--google_credentials</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies the file to get authentication credentials from. See https://cloud.google.com/docs/authentication for details.</p> +</dd> +<dt id="common_options-flag--google_default_credentials"><code id="google_default_credentials"><a href="#common_options-flag--google_default_credentials">--[no]google_default_credentials</a></code> default: "false"</dt> +<dd> +<p>Whether to use 'Google Application Default Credentials' for authentication. See https://cloud.google.com/docs/authentication for details. Disabled by default.</p> +</dd> +<dt id="common_options-flag--grpc_keepalive_time"><code id="grpc_keepalive_time"><a href="#common_options-flag--grpc_keepalive_time">--grpc_keepalive_time</a>=<An immutable length of time.></code> default: see description</dt> +<dd> +<p>Configures keep-alive pings for outgoing gRPC connections. If this is set, then Bazel sends pings after this much time of no read operations on the connection, but only if there is at least one pending gRPC call. Times are treated as second granularity; it is an error to set a value less than one second. By default, keep-alive pings are disabled. You should coordinate with the service owner before enabling this setting. For example to set a value of 30 seconds to this flag, it should be done as this --grpc_keepalive_time=30s</p> +</dd> +<dt id="common_options-flag--grpc_keepalive_timeout"><code id="grpc_keepalive_timeout"><a href="#common_options-flag--grpc_keepalive_timeout">--grpc_keepalive_timeout</a>=<An immutable length of time.></code> default: "20s"</dt> +<dd> +<p>Configures a keep-alive timeout for outgoing gRPC connections. If keep-alive pings are enabled with --grpc_keepalive_time, then Bazel times out a connection if it does not receive a ping reply after this much time. Times are treated as second granularity; it is an error to set a value less than one second. If keep-alive pings are disabled, then this setting is ignored.</p> +</dd> +<dt id="common_options-flag--incompatible_disable_non_executable_java_binary"><code id="incompatible_disable_non_executable_java_binary"><a href="#common_options-flag--incompatible_disable_non_executable_java_binary">--[no]incompatible_disable_non_executable_java_binary</a></code> default: "false"</dt> +<dd> +<p>If true, java_binary is always executable. create_executable attribute is removed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--incompatible_repo_env_ignores_action_env"><code id="incompatible_repo_env_ignores_action_env"><a href="#common_options-flag--incompatible_repo_env_ignores_action_env">--[no]incompatible_repo_env_ignores_action_env</a></code> default: "true"</dt> +<dd> +<p>If true, <code>--action_env=NAME=VALUE</code> will no longer affect repository rule and module extension environments.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="common_options-flag--inject_repository"><code id="inject_repository"><a href="#common_options-flag--inject_repository">--inject_repository</a>=<an equals-separated mapping of repository name to path></code> multiple uses are accumulated</dt> +<dd> +<p>Adds a new repository with a local path in the form of <repository name>=<path>. This only takes effect with --enable_bzlmod and is equivalent to adding a corresponding <code>local_repository</code> to the root module's MODULE.bazel file via <code>use_repo_rule</code>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%', it is relative to the workspace root, which is the output of <code>bazel info workspace</code>. If the given path is empty, then remove any previous injections.</p> +</dd> +<dt id="common_options-flag--invocation_id"><code id="invocation_id"><a href="#common_options-flag--invocation_id">--invocation_id</a>=<a UUID></code> default: ""</dt> +<dd> +<p>Unique identifier, in UUID format, for the command being run. If explicitly specified uniqueness must be ensured by the caller. The UUID is printed to stderr, the BEP and remote execution protocol.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="common_options-flag--override_repository"><code id="override_repository"><a href="#common_options-flag--override_repository">--override_repository</a>=<an equals-separated mapping of repository name to path></code> multiple uses are accumulated</dt> +<dd> +<p>Override a repository with a local path in the form of <repository name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of <code>bazel info workspace</code>. If the given path is empty, then remove any previous overrides.</p> +</dd> +<dt id="common_options-flag--progress_in_terminal_title"><code id="progress_in_terminal_title"><a href="#common_options-flag--progress_in_terminal_title">--[no]progress_in_terminal_title</a></code> default: "false"</dt> +<dd> +<p>Show the command progress in the terminal title. Useful to see what bazel is doing when having multiple terminal tabs.</p> +</dd> +<dt id="common_options-flag--show_progress"><code id="show_progress"><a href="#common_options-flag--show_progress">--[no]show_progress</a></code> default: "true"</dt> +<dd> +<p>Display progress messages during a build.</p> +</dd> +<dt id="common_options-flag--show_progress_rate_limit"><code id="show_progress_rate_limit"><a href="#common_options-flag--show_progress_rate_limit">--show_progress_rate_limit</a>=<a double></code> default: "0.2"</dt> +<dd> +<p>Minimum number of seconds between progress messages in the output.</p> +</dd> +<dt id="common_options-flag--show_timestamps"><code id="show_timestamps"><a href="#common_options-flag--show_timestamps">--[no]show_timestamps</a></code> default: "false"</dt> +<dd> +<p>Include timestamps in messages</p> +</dd> +<dt id="common_options-flag--tls_certificate"><code id="tls_certificate"><a href="#common_options-flag--tls_certificate">--tls_certificate</a>=<a string></code> default: see description</dt> +<dd> +<p>Specify a path to a TLS certificate that is trusted to sign server certificates.</p> +</dd> +<dt id="common_options-flag--tls_client_certificate"><code id="tls_client_certificate"><a href="#common_options-flag--tls_client_certificate">--tls_client_certificate</a>=<a string></code> default: see description</dt> +<dd> +<p>Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication.</p> +</dd> +<dt id="common_options-flag--tls_client_key"><code id="tls_client_key"><a href="#common_options-flag--tls_client_key">--tls_client_key</a>=<a string></code> default: see description</dt> +<dd> +<p>Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication.</p> +</dd> +<dt id="common_options-flag--ui_actions_shown"><code id="ui_actions_shown"><a href="#common_options-flag--ui_actions_shown">--ui_actions_shown</a>=<an integer></code> default: "8"</dt> +<dd> +<p>Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="common_options-flag--watchfs"><code id="watchfs"><a href="#common_options-flag--watchfs">--[no]watchfs</a></code> default: "false"</dt> +<dd> +<p>On Linux/macOS: If true, bazel tries to use the operating system's file watch service for local changes instead of scanning every file for a change. On Windows: this flag currently is a non-op but can be enabled in conjunction with --experimental_windows_watchfs. On any OS: The behavior is undefined if your workspace is on a network file system, and files are edited on a remote machine.</p> +</dd> +</dl> + +<h2><a name="aquery">Aquery Options</a></h2> +<p>Inherits all options from <a href="#build">build</a>.</p> + +<dl>Options relating to query output and semantics: +<dt id="aquery-flag--aspect_deps"><code id="aspect_deps"><a href="#aquery-flag--aspect_deps">--aspect_deps</a>=<off, conservative or precise></code> default: "conservative"</dt> +<dd> +<p>How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="aquery-flag--consistent_labels"><code id="consistent_labels"><a href="#aquery-flag--consistent_labels">--[no]consistent_labels</a></code> default: "false"</dt> +<dd> +<p>If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--experimental_explicit_aspects"><code id="experimental_explicit_aspects"><a href="#aquery-flag--experimental_explicit_aspects">--[no]experimental_explicit_aspects</a></code> default: "false"</dt> +<dd> +<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--graph:factored"><code id="graph:factored"><a href="#aquery-flag--graph:factored">--[no]graph:factored</a></code> default: "true"</dt> +<dd> +<p>If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--graph:node_limit"><code id="graph:node_limit"><a href="#aquery-flag--graph:node_limit">--graph:node_limit</a>=<an integer></code> default: "512"</dt> +<dd> +<p>The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--implicit_deps"><code id="implicit_deps"><a href="#aquery-flag--implicit_deps">--[no]implicit_deps</a></code> default: "true"</dt> +<dd> +<p>If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="aquery-flag--include_artifacts"><code id="include_artifacts"><a href="#aquery-flag--include_artifacts">--[no]include_artifacts</a></code> default: "true"</dt> +<dd> +<p>Includes names of the action inputs and outputs in the output (potentially large).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--include_aspects"><code id="include_aspects"><a href="#aquery-flag--include_aspects">--[no]include_aspects</a></code> default: "true"</dt> +<dd> +<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--include_commandline"><code id="include_commandline"><a href="#aquery-flag--include_commandline">--[no]include_commandline</a></code> default: "true"</dt> +<dd> +<p>Includes the content of the action command lines in the output (potentially large).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--include_file_write_contents"><code id="include_file_write_contents"><a href="#aquery-flag--include_file_write_contents">--[no]include_file_write_contents</a></code> default: "false"</dt> +<dd> +<p>Include the file contents for the FileWrite, SourceSymlinkManifest, and RepoMappingManifest actions (potentially large).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--include_param_files"><code id="include_param_files"><a href="#aquery-flag--include_param_files">--[no]include_param_files</a></code> default: "false"</dt> +<dd> +<p>Include the content of the param files used in the command (potentially large). Note: Enabling this flag will automatically enable the --include_commandline flag.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--include_pruned_inputs"><code id="include_pruned_inputs"><a href="#aquery-flag--include_pruned_inputs">--[no]include_pruned_inputs</a></code> default: "true"</dt> +<dd> +<p>Includes action inputs that were pruned during action execution. Only affects actions that discover inputs and have been executed in a previous invocation. Only takes effect if --include_artifacts is also set.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--incompatible_package_group_includes_double_slash"><code id="incompatible_package_group_includes_double_slash"><a href="#aquery-flag--incompatible_package_group_includes_double_slash">--[no]incompatible_package_group_includes_double_slash</a></code> default: "true"</dt> +<dd> +<p>If enabled, when outputting package_group's <code>packages</code> attribute, the leading <code>//</code> will not be omitted.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="aquery-flag--infer_universe_scope"><code id="infer_universe_scope"><a href="#aquery-flag--infer_universe_scope">--[no]infer_universe_scope</a></code> default: "false"</dt> +<dd> +<p>If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.<code>allrdeps</code>) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to <code>query</code> (i.e. not <code>cquery</code>).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="aquery-flag--line_terminator_null"><code id="line_terminator_null"><a href="#aquery-flag--line_terminator_null">--[no]line_terminator_null</a></code> default: "false"</dt> +<dd> +<p>Whether each format is terminated with \0 instead of newline.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--nodep_deps"><code id="nodep_deps"><a href="#aquery-flag--nodep_deps">--[no]nodep_deps</a></code> default: "true"</dt> +<dd> +<p>If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of <code>info build-language</code> to learn about all the "nodep" attributes in the build language.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="aquery-flag--output"><code id="output"><a href="#aquery-flag--output">--output</a>=<a string></code> default: "text"</dt> +<dd> +<p>The format in which the aquery results should be printed. Allowed values for aquery are: text, textproto, proto, streamed_proto, jsonproto.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--output_file"><code id="output_file"><a href="#aquery-flag--output_file">--output_file</a>=<a string></code> default: ""</dt> +<dd> +<p>When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query &gt; file</code>.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:default_values"><code id="proto:default_values"><a href="#aquery-flag--proto:default_values">--[no]proto:default_values</a></code> default: "true"</dt> +<dd> +<p>If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:definition_stack"><code id="proto:definition_stack"><a href="#aquery-flag--proto:definition_stack">--[no]proto:definition_stack</a></code> default: "false"</dt> +<dd> +<p>Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:flatten_selects"><code id="proto:flatten_selects"><a href="#aquery-flag--proto:flatten_selects">--[no]proto:flatten_selects</a></code> default: "true"</dt> +<dd> +<p>If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="aquery-flag--proto:include_attribute_source_aspects"><code id="proto:include_attribute_source_aspects"><a href="#aquery-flag--proto:include_attribute_source_aspects">--[no]proto:include_attribute_source_aspects</a></code> default: "false"</dt> +<dd> +<p>Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:include_starlark_rule_env"><code id="proto:include_starlark_rule_env"><a href="#aquery-flag--proto:include_starlark_rule_env">--[no]proto:include_starlark_rule_env</a></code> default: "true"</dt> +<dd> +<p>Use the starlark environment in the value of the generated $internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:include_synthetic_attribute_hash"><code id="proto:include_synthetic_attribute_hash"><a href="#aquery-flag--proto:include_synthetic_attribute_hash">--[no]proto:include_synthetic_attribute_hash</a></code> default: "false"</dt> +<dd> +<p>Whether or not to calculate and populate the $internal_attr_hash attribute.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:instantiation_stack"><code id="proto:instantiation_stack"><a href="#aquery-flag--proto:instantiation_stack">--[no]proto:instantiation_stack</a></code> default: "false"</dt> +<dd> +<p>Populate the instantiation call stack of each rule. Note that this requires the stack to be present</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:locations"><code id="proto:locations"><a href="#aquery-flag--proto:locations">--[no]proto:locations</a></code> default: "true"</dt> +<dd> +<p>Whether to output location information in proto output at all.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:output_rule_attrs"><code id="proto:output_rule_attrs"><a href="#aquery-flag--proto:output_rule_attrs">--proto:output_rule_attrs</a>=<comma-separated list of options></code> default: "all"</dt> +<dd> +<p>Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:rule_classes"><code id="proto:rule_classes"><a href="#aquery-flag--proto:rule_classes">--[no]proto:rule_classes</a></code> default: "false"</dt> +<dd> +<p>Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--proto:rule_inputs_and_outputs"><code id="proto:rule_inputs_and_outputs"><a href="#aquery-flag--proto:rule_inputs_and_outputs">--[no]proto:rule_inputs_and_outputs</a></code> default: "true"</dt> +<dd> +<p>Whether or not to populate the rule_input and rule_output fields.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--query_file"><code id="query_file"><a href="#aquery-flag--query_file">--query_file</a>=<a string></code> default: ""</dt> +<dd> +<p>If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="aquery-flag--relative_locations"><code id="relative_locations"><a href="#aquery-flag--relative_locations">--[no]relative_locations</a></code> default: "false"</dt> +<dd> +<p>If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--skyframe_state"><code id="skyframe_state"><a href="#aquery-flag--skyframe_state">--[no]skyframe_state</a></code> default: "false"</dt> +<dd> +<p>Without performing extra analysis, dump the current Action Graph from Skyframe. Note: Specifying a target with --skyframe_state is currently not supported. This flag is only available with --output=proto or --output=textproto.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="aquery-flag--tool_deps"><code id="tool_deps"><a href="#aquery-flag--tool_deps">--[no]tool_deps</a></code> default: "true"</dt> +<dd> +<p>Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="aquery-flag--universe_scope"><code id="universe_scope"><a href="#aquery-flag--universe_scope">--universe_scope</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> + +<dl>Options that control build execution: +<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> +<dd> +<p>Enable persistent aar extractor by using workers.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> +<dd> +<p>Whether to make source manifest actions remotable</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> +<dd> +<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> +<dd> +<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> +<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> +<p>Examples: +'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> +<dd> +<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> +<dd> +<p>If true, use the target platform for running tests rather than the test exec group.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The Android target compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> +<dd> +<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The C++ compiler to use for compiling the target.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> +<dd> +<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> +<dd> +<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> +<dd> +<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> +<dd> +<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> +<dd> +<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>No-op flag. Will be removed in a future release.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> +<dd> +<p>The label of a platform rule that describes the host system.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> +<dd> +<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> +<dd> +<p>Whether to emit a strip action as part of objc linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> +<dd> +<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> +<dd> +<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> +<dd> +<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> +<dd> +<p>The minimum OS version which your compilation targets.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> +<dd> +<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>The labels of the platform rules describing the target platforms for the current command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> +<dd> +<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> +<dd> +<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> +<dd> +<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> +<dd> +<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> +<dl>Options that control the output of the command: +<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> +<dd> +<p>Whether to generate debug symbol(.dSYM) file(s).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> +<dd> +<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> +<dd> +<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> +<dd> +<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> +<dd> +<p>Sets the suffixes of header files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> +<dd> +<p>Sets the suffixes of source files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> +<dd> +<p>Run extra actions for alternative Java api versions in a proto_library.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> +<dd> +<p>Save the state of enabled and requested feautres as an output of compilation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> +<dd> +<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> +<dd> +<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> +<dd> +<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>List of flags for which the use in select() is disabled.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> +<dd> +<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> +<dd> +<p>Specifies whether to generate a linkmap file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> +<dd> +<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>Allowed values for the --cpu flag.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> +<dd> +<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> +<dd> +<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> +<dd> +<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> +<dd> +<p>Build python executable zip; on on Windows, off on other platforms</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> +<dd> +<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> +<dd> +<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> +<dd> +<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for FDO will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> +<dd> +<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> +<dd> +<p>Compress Java resources in APKs</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> +<dd> +<p>use rex tool to rewrite dex files</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will also generate collect coverage information for generated files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> +<dd> +<p>Uses these strings as objc fastbuild compiler options.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> +<dd> +<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> +<dd> +<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> +<dd> +<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> +<dd> +<p>py_binary targets include their label even when stamping is disabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> +<dd> +<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> +<dd> +<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use cache prefetch hints.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The fdo_profile representing the profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> +<dd> +<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> +<dd> +<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>The host CPU.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to linker when linking tools in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> +<dd> +<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> +<dd> +<p>If true, the genfiles directory is folded into the bin directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> +<dd> +<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> +<dd> +<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> +<dd> +<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> +</p></dd> +<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use memprof profile.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> +<dd> +<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> +<dd> +<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> +<dd> +<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> +<dd> +<p>If true, native libraries that contain identical functionality will be shared among different targets</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> +<dd> +<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> +<dd> +<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> +<dd> +<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> +<dd> +<p>Whether to desugar Java 8 bytecode before dexing.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> +<dd> +<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> +<dd> +<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> +<dd> +<p>Whether to double-check correct desugaring at Android binary level.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> +<dd> +<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> +<dd> +<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> +<dd> +<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> +<dd> +<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> +<dd> +<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> +<dd> +<p>No-op. Kept here for backwards compatibility.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> +<dd> +<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> +<dd> +<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> +<dd> +<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Options that affect the signing outputs of a build: +<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> +<dd> +<p>Implementation to use to sign APKs</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> +<dd> +<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> +<dd> +<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> +<dd> +<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> +<dd> +<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> +<dd> +<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that govern the behavior of the test environment or test runner: +<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> +<dd> +<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> +<dd> +<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> +<dd> +<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> +<dd> +<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> +</dd> +<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> +<dd> +<p>Use dex2oat in parallel to possibly speed up android_test.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> +<dd> +<p>Enable checking for memory leaks in ios_test targets.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> +<dd> +<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> +</dd> +<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> +<dd> +<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> +</dd> +<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, undeclared test outputs will be archived in a zip file.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +</dl> +<dl>Options that trigger optimizations of the build time: +<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> +<dd> +<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> +<dd> +<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> +<dd> +<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> +<dd> +<p>Does most of the work for dexing separately for each Jar file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> +<dd> +<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> +<dd> +<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> +<dd> +<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> +<dd> +<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> +<dd> +<p>If enabled, visibility errors include additional diagnostic information.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> +<dd> +<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> +<dd> +<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> +<dd> +<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> +</dd> +<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> +<dd> +<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> +<dd> +<p>If true, coverage for clang will generate an LCOV report.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> +<dd> +<p>Enables reduced classpaths for Java compilations.</p> +</dd> +<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> +<dd> +<p>Whether to validate java_* sources.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> +<dd> +<p>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.</p> +</dd> +<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher used by tools that are executed during a build.</p> +</dd> +<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac when building tools that are executed during a build.</p> +</dd> +<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> +<dd> +<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> +<dd> +<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the J2ObjC tool.</p> +</dd> +<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> +<dd> +<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> +<p>Expands to: +<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> +<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> +<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> +<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> +<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> +</p></dd> +<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> +<dd> +<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> +</dd> +<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> +<dd> +<p>Compile ijars directly from source.</p> +</dd> +<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version</p> +</dd> +<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> +</dd> +<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> +<dd> +<p>The Java runtime version</p> +</dd> +<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac.</p> +</dd> +<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> +</dd> +<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to do dexing without sharding.</p> +</dd> +<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Plugins to use in the build. Currently works with java_plugin.</p> +</dd> +<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> +</dd> +<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> +<dd> +<p>The label of the proto-compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> +<dd> +<p>Whether to pass profile_path to the proto compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the protobuf compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> +<dd> +<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> +</dd> +<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> +<dd> +<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> +</dd> +<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> +</dd> +<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>This option is deprecated and has no effect.</p> +</dd> +<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> +<dd> +<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> +</dd> +<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> +<dd> +<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> +</dd> +<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version used to execute the tools that are needed during a build</p> +</dd> +<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> +<dd> +<p>The Java runtime version used to execute tools during the build</p> +</dd> +<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> +<dd> +<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> +</dd> +</dl> + +<h2><a name="build">Build Options</a></h2> +<dl>Options that control build execution: +<dt id="build-flag--allow_one_action_on_resource_unavailable"><code id="allow_one_action_on_resource_unavailable"><a href="#build-flag--allow_one_action_on_resource_unavailable">--[no]allow_one_action_on_resource_unavailable</a></code> default: "true"</dt> +<dd> +<p>If set, allow at least one action to run even if the resource is not enough or unavailable.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--check_up_to_date"><code id="check_up_to_date"><a href="#build-flag--check_up_to_date">--[no]check_up_to_date</a></code> default: "false"</dt> +<dd> +<p>Don't perform the build, just check if it is up-to-date. If all targets are up-to-date, the build completes successfully. If any step needs to be executed an error is reported and the build fails.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--dynamic_local_execution_delay"><code id="dynamic_local_execution_delay"><a href="#build-flag--dynamic_local_execution_delay">--dynamic_local_execution_delay</a>=<an integer></code> default: "1000"</dt> +<dd> +<p>How many milliseconds should local execution be delayed, if remote execution was faster during a build at least once?</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--dynamic_local_strategy"><code id="dynamic_local_strategy"><a href="#build-flag--dynamic_local_strategy">--dynamic_local_strategy</a>=<a '[name=]value1[,..,valueN]' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>The local strategies, in order, to use for the given mnemonic - the first applicable strategy is used. For example, <code>worker,sandboxed</code> runs actions that support persistent workers using the worker strategy, and all others using the sandboxed strategy. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is <code>worker,sandboxed</code>, or<code>worker,sandboxed,standalone</code> if <code>experimental_local_lockfree_output</code> is set. Takes [mnemonic=]local_strategy[,local_strategy,...]</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--dynamic_remote_strategy"><code id="dynamic_remote_strategy"><a href="#build-flag--dynamic_remote_strategy">--dynamic_remote_strategy</a>=<a '[name=]value1[,..,valueN]' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>The remote strategies, in order, to use for the given mnemonic - the first applicable strategy is used. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is <code>remote</code>, so this flag usually does not need to be set explicitly. Takes [mnemonic=]remote_strategy[,remote_strategy,...]</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_async_execution"><code id="experimental_async_execution"><a href="#build-flag--experimental_async_execution">--[no]experimental_async_execution</a></code> default: "false"</dt> +<dd> +<p>If set to true, Bazel is allowed to run action in a virtual thread. The number of actions in flight is still capped with --jobs.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="build-flag--experimental_async_execution_max_concurrent_actions"><code id="experimental_async_execution_max_concurrent_actions"><a href="#build-flag--experimental_async_execution_max_concurrent_actions">--experimental_async_execution_max_concurrent_actions</a>=<an integer></code> default: "5000"</dt> +<dd> +<p>The number of maximum concurrent actions to run with async execution. If the value is less than --jobs, it is clamped to --jobs.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_docker_image"><code id="experimental_docker_image"><a href="#build-flag--experimental_docker_image">--experimental_docker_image</a>=<a string></code> default: ""</dt> +<dd> +<p>Specify a Docker image name (e.g. "ubuntu:latest") that should be used to execute a sandboxed action when using the docker strategy and the action itself doesn't already have a container-image attribute in its remote_execution_properties in the platform description. The value of this flag is passed verbatim to 'docker run', so it supports the same syntax and mechanisms as Docker itself.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_docker_use_customized_images"><code id="experimental_docker_use_customized_images"><a href="#build-flag--experimental_docker_use_customized_images">--[no]experimental_docker_use_customized_images</a></code> default: "true"</dt> +<dd> +<p>If enabled, injects the uid and gid of the current user into the Docker image before using it. This is required if your build / tests depend on the user having a name and home directory inside the container. This is on by default, but you can disable it in case the automatic image customization feature doesn't work in your case or you know that you don't need it.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_dynamic_exclude_tools"><code id="experimental_dynamic_exclude_tools"><a href="#build-flag--experimental_dynamic_exclude_tools">--[no]experimental_dynamic_exclude_tools</a></code> default: "true"</dt> +<dd> +<p>When set, targets that are build "for tool" are not subject to dynamic execution. Such targets are extremely unlikely to be built incrementally and thus not worth spending local cycles on.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_dynamic_local_load_factor"><code id="experimental_dynamic_local_load_factor"><a href="#build-flag--experimental_dynamic_local_load_factor">--experimental_dynamic_local_load_factor</a>=<a double></code> default: "0"</dt> +<dd> +<p>Controls how much load from dynamic execution to put on the local machine. This flag adjusts how many actions in dynamic execution we will schedule concurrently. It is based on the number of CPUs Blaze thinks is available, which can be controlled with the --local_resources=cpu= flag. +If this flag is 0, all actions are scheduled locally immediately. If > 0, the amount of actions scheduled locally is limited by the number of CPUs available. If < 1, the load factor is used to reduce the number of locally scheduled actions when the number of actions waiting to schedule is high. This lessens the load on the local machine in the clean build case, where the local machine does not contribute much.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_dynamic_slow_remote_time"><code id="experimental_dynamic_slow_remote_time"><a href="#build-flag--experimental_dynamic_slow_remote_time">--experimental_dynamic_slow_remote_time</a>=<An immutable length of time.></code> default: "0"</dt> +<dd> +<p>If >0, the time a dynamically run action must run remote-only before we prioritize its local execution to avoid remote timeouts. This may hide some problems on the remote execution system. Do not turn this on without monitoring of remote execution issues.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_enable_docker_sandbox"><code id="experimental_enable_docker_sandbox"><a href="#build-flag--experimental_enable_docker_sandbox">--[no]experimental_enable_docker_sandbox</a></code> default: "false"</dt> +<dd> +<p>Enable Docker-based sandboxing. This option has no effect if Docker is not installed.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_inmemory_sandbox_stashes"><code id="experimental_inmemory_sandbox_stashes"><a href="#build-flag--experimental_inmemory_sandbox_stashes">--[no]experimental_inmemory_sandbox_stashes</a></code> default: "false"</dt> +<dd> +<p>If set to true, the contents of stashed sandboxes for reuse_sandbox_directories will be tracked in memory. This reduces the amount of I/O needed during reuse. Depending on the build this flag may improve wall time. Depending on the build as well this flag may use a significant amount of additional memory.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_sandbox_async_tree_delete_idle_threads"><code id="experimental_sandbox_async_tree_delete_idle_threads"><a href="#build-flag--experimental_sandbox_async_tree_delete_idle_threads">--experimental_sandbox_async_tree_delete_idle_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "4"</dt> +<dd> +<p>If 0, sandboxes are deleted as soon as actions finish, blocking action completion. If greater than 0, sandboxes are deleted asynchronously in the background without blocking action completion. Asynchronous deletion uses a single thread while a command is running, but ramps up to as many threads as the value of this flag once the server becomes idle. Set to <code>auto</code> to use as many threads as the number of CPUs. A server shutdown blocks on any pending asynchronous deletions.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_sandbox_enforce_resources_regexp"><code id="experimental_sandbox_enforce_resources_regexp"><a href="#build-flag--experimental_sandbox_enforce_resources_regexp">--experimental_sandbox_enforce_resources_regexp</a>=<a valid Java regular expression></code> default: ""</dt> +<dd> +<p>If true, actions whose mnemonic matches the input regex will have their resources request enforced as limits, overriding the value of --experimental_sandbox_limits, if the resource type supports it. For example a test that declares cpu:3 and resources:memory:10, will run with at most 3 cpus and 10 megabytes of memory.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_sandbox_limits"><code id="experimental_sandbox_limits"><a href="#build-flag--experimental_sandbox_limits">--experimental_sandbox_limits</a>=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> multiple uses are accumulated</dt> +<dd> +<p>If > 0, each Linux sandbox will be limited to the given amount for the specified resource. Requires --incompatible_use_new_cgroup_implementation and overrides --experimental_sandbox_memory_limit_mb. Requires cgroups v1 or v2 and permissions for the users to the cgroups dir.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_sandbox_memory_limit_mb"><code id="experimental_sandbox_memory_limit_mb"><a href="#build-flag--experimental_sandbox_memory_limit_mb">--experimental_sandbox_memory_limit_mb</a>=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.></code> default: "0"</dt> +<dd> +<p>If > 0, each Linux sandbox will be limited to the given amount of memory (in MB). Requires cgroups v1 or v2 and permissions for the users to the cgroups dir.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_shrink_worker_pool"><code id="experimental_shrink_worker_pool"><a href="#build-flag--experimental_shrink_worker_pool">--[no]experimental_shrink_worker_pool</a></code> default: "false"</dt> +<dd> +<p>If enabled, could shrink worker pool if worker memory pressure is high. This flag works only when flag experimental_total_worker_memory_limit_mb is enabled.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_total_worker_memory_limit_mb"><code id="experimental_total_worker_memory_limit_mb"><a href="#build-flag--experimental_total_worker_memory_limit_mb">--experimental_total_worker_memory_limit_mb</a>=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.></code> default: "0"</dt> +<dd> +<p>If this limit is greater than zero idle workers might be killed if the total memory usage of all workers exceed the limit.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_use_hermetic_linux_sandbox"><code id="experimental_use_hermetic_linux_sandbox"><a href="#build-flag--experimental_use_hermetic_linux_sandbox">--[no]experimental_use_hermetic_linux_sandbox</a></code> default: "false"</dt> +<dd> +<p>If set to true, do not mount root, only mount whats provided with sandbox_add_mount_pair. Input files will be hardlinked to the sandbox instead of symlinked to from the sandbox. If action input files are located on a filesystem different from the sandbox, then the input files will be copied instead.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_use_windows_sandbox"><code id="experimental_use_windows_sandbox"><a href="#build-flag--experimental_use_windows_sandbox">--[no]experimental_use_windows_sandbox</a></code> default: "false"</dt> +<dd> +<p>Use Windows sandbox to run actions. If "yes", the binary provided by --experimental_windows_sandbox_path must be valid and correspond to a supported version of sandboxfs. If "auto", the binary may be missing or not compatible.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_windows_sandbox_path"><code id="experimental_windows_sandbox_path"><a href="#build-flag--experimental_windows_sandbox_path">--experimental_windows_sandbox_path</a>=<a string></code> default: "BazelSandbox.exe"</dt> +<dd> +<p>Path to the Windows sandbox binary to use when --experimental_use_windows_sandbox is true. If a bare name, use the first binary of that name found in the PATH.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_worker_allowlist"><code id="experimental_worker_allowlist"><a href="#build-flag--experimental_worker_allowlist">--experimental_worker_allowlist</a>=<comma-separated set of options></code> default: see description</dt> +<dd> +<p>If non-empty, only allow using persistent workers with the given worker key mnemonic.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_worker_cancellation"><code id="experimental_worker_cancellation"><a href="#build-flag--experimental_worker_cancellation">--[no]experimental_worker_cancellation</a></code> default: "false"</dt> +<dd> +<p>If enabled, Bazel may send cancellation requests to workers that support them.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_worker_memory_limit_mb"><code id="experimental_worker_memory_limit_mb"><a href="#build-flag--experimental_worker_memory_limit_mb">--experimental_worker_memory_limit_mb</a>=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.></code> default: "0"</dt> +<dd> +<p>If this limit is greater than zero, workers might be killed if the memory usage of the worker exceeds the limit. If not used together with dynamic execution and <code>--experimental_dynamic_ignore_local_signals=9</code>, this may crash your build.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_worker_metrics_poll_interval"><code id="experimental_worker_metrics_poll_interval"><a href="#build-flag--experimental_worker_metrics_poll_interval">--experimental_worker_metrics_poll_interval</a>=<An immutable length of time.></code> default: "5s"</dt> +<dd> +<p>The interval between collecting worker metrics and possibly attempting evictions. Cannot effectively be less than 1s for performance reasons.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_worker_multiplex_sandboxing"><code id="experimental_worker_multiplex_sandboxing"><a href="#build-flag--experimental_worker_multiplex_sandboxing">--[no]experimental_worker_multiplex_sandboxing</a></code> default: "false"</dt> +<dd> +<p>If enabled, multiplex workers with a 'supports-multiplex-sandboxing' execution requirement will run in a sandboxed environment, using a separate sandbox directory per work request. Multiplex workers with the execution requirement are always sandboxed when running under the dynamic execution strategy, irrespective of this flag.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_worker_sandbox_hardening"><code id="experimental_worker_sandbox_hardening"><a href="#build-flag--experimental_worker_sandbox_hardening">--[no]experimental_worker_sandbox_hardening</a></code> default: "false"</dt> +<dd> +<p>If enabled, workers are run in a hardened sandbox, if the implementation allows it. If hardening is enabled then tmp directories are distinct for different workers.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_worker_sandbox_inmemory_tracking"><code id="experimental_worker_sandbox_inmemory_tracking"><a href="#build-flag--experimental_worker_sandbox_inmemory_tracking">--experimental_worker_sandbox_inmemory_tracking</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>A worker key mnemonic for which the contents of the sandbox directory are tracked in memory. This may improve build performance at the cost of additional memory usage. Only affects sandboxed workers. May be specified multiple times for different mnemonics.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_worker_strict_flagfiles"><code id="experimental_worker_strict_flagfiles"><a href="#build-flag--experimental_worker_strict_flagfiles">--[no]experimental_worker_strict_flagfiles</a></code> default: "false"</dt> +<dd> +<p>If enabled, actions arguments for workers that do not follow the worker specification will cause an error. Worker arguments must have exactly one @flagfile argument as the last of its list of arguments.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--genrule_strategy"><code id="genrule_strategy"><a href="#build-flag--genrule_strategy">--genrule_strategy</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>Specify how to execute genrules. This flag will be phased out. Instead, use --spawn_strategy=<value> to control all actions or --strategy=Genrule=<value> to control genrules only.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--incompatible_use_new_cgroup_implementation"><code id="incompatible_use_new_cgroup_implementation"><a href="#build-flag--incompatible_use_new_cgroup_implementation">--[no]incompatible_use_new_cgroup_implementation</a></code> default: "true"</dt> +<dd> +<p>If true, use the new implementation for cgroups. The old implementation only supports the memory controller and ignores the value of --experimental_sandbox_limits.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--internal_spawn_scheduler"><code id="internal_spawn_scheduler"><a href="#build-flag--internal_spawn_scheduler">--[no]internal_spawn_scheduler</a></code> default: "true"</dt> +<dd> +<p>Placeholder option so that we can tell in Blaze whether the spawn scheduler was enabled.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--jobs"><code id="jobs"><a href="#build-flag--jobs">--jobs</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> [<code>-j</code>] default: "auto"</dt> +<dd> +<p>The number of concurrent jobs to run. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". Values must be between 1 and 5000. Values above 2500 may cause memory issues. "auto" calculates a reasonable default based on host resources.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--keep_going"><code id="keep_going"><a href="#build-flag--keep_going">--[no]keep_going</a></code> [<code>-k</code>] default: "false"</dt> +<dd> +<p>Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="build-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#build-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> +<dd> +<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="build-flag--reuse_sandbox_directories"><code id="reuse_sandbox_directories"><a href="#build-flag--reuse_sandbox_directories">--[no]reuse_sandbox_directories</a></code> default: "true"</dt> +<dd> +<p>If set to true, directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_base"><code id="sandbox_base"><a href="#build-flag--sandbox_base">--sandbox_base</a>=<a string></code> default: ""</dt> +<dd> +<p>Lets the sandbox create its sandbox directories underneath this path. Specify a path on tmpfs (like /run/shm) to possibly improve performance a lot when your build / tests have many input files. Note: You need enough RAM and free space on the tmpfs to hold output and intermediate files generated by running actions.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_enable_loopback_device"><code id="sandbox_enable_loopback_device"><a href="#build-flag--sandbox_enable_loopback_device">--[no]sandbox_enable_loopback_device</a></code> default: "true"</dt> +<dd> +<p>If true, a loopback device will be set up in the linux-sandbox network namespace for local actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_explicit_pseudoterminal"><code id="sandbox_explicit_pseudoterminal"><a href="#build-flag--sandbox_explicit_pseudoterminal">--[no]sandbox_explicit_pseudoterminal</a></code> default: "false"</dt> +<dd> +<p>Explicitly enable the creation of pseudoterminals for sandboxed actions. Some linux distributions require setting the group id of the process to 'tty' inside the sandbox in order for pseudoterminals to function. If this is causing issues, this flag can be disabled to enable other groups to be used.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_tmpfs_path"><code id="sandbox_tmpfs_path"><a href="#build-flag--sandbox_tmpfs_path">--sandbox_tmpfs_path</a>=<an absolute path></code> multiple uses are accumulated</dt> +<dd> +<p>For sandboxed actions, mount an empty, writable directory at this absolute path (if supported by the sandboxing implementation, ignored otherwise).</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--skip_incompatible_explicit_targets"><code id="skip_incompatible_explicit_targets"><a href="#build-flag--skip_incompatible_explicit_targets">--[no]skip_incompatible_explicit_targets</a></code> default: "false"</dt> +<dd> +<p>Skip incompatible targets that are explicitly listed on the command line. By default, building such targets results in an error but they are silently skipped when this option is enabled. See: https://bazel.build/extending/platforms#skipping-incompatible-targets</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="build-flag--spawn_strategy"><code id="spawn_strategy"><a href="#build-flag--spawn_strategy">--spawn_strategy</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>Specify how spawn actions are executed by default. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". See https://blog.bazel.build/2019/06/19/list-strategy.html for details.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--strategy"><code id="strategy"><a href="#build-flag--strategy">--strategy</a>=<a '[name=]value1[,..,valueN]' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify how to distribute compilation of other spawn actions. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". This flag overrides the values set by --spawn_strategy (and --genrule_strategy if used with mnemonic Genrule). See https://blog.bazel.build/2019/06/19/list-strategy.html for details.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--strategy_regexp"><code id="strategy_regexp"><a href="#build-flag--strategy_regexp">--strategy_regexp</a>=<a '<RegexFilter>=value[,value]' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Override which spawn strategy should be used to execute spawn actions that have descriptions matching a certain regex_filter. See --per_file_copt for details onregex_filter matching. The last regex_filter that matches the description is used. This option overrides other flags for specifying strategy. Example: --strategy_regexp=//foo.<em>.cc,-//foo/bar=local means to run actions using local strategy if their descriptions match //foo.</em>.cc but not //foo/bar. Example: --strategy_regexp='Compiling.*/bar=local --strategy_regexp=Compiling=sandboxed will run 'Compiling //foo/bar/baz' with the 'local' strategy, but reversing the order would run it with 'sandboxed'.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--worker_extra_flag"><code id="worker_extra_flag"><a href="#build-flag--worker_extra_flag">--worker_extra_flag</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Extra command-flags that will be passed to worker processes in addition to --persistent_worker, keyed by mnemonic (e.g. --worker_extra_flag=Javac=--debug.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--worker_max_instances"><code id="worker_max_instances"><a href="#build-flag--worker_max_instances">--worker_max_instances</a>=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> multiple uses are accumulated</dt> +<dd> +<p>How many instances of each kind of persistent worker may be launched if you use the 'worker' strategy. May be specified as [name=value] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--worker_max_multiplex_instances"><code id="worker_max_multiplex_instances"><a href="#build-flag--worker_max_multiplex_instances">--worker_max_multiplex_instances</a>=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> multiple uses are accumulated</dt> +<dd> +<p>How many WorkRequests a multiplex worker process may receive in parallel if you use the 'worker' strategy with --worker_multiplex. May be specified as [name=value] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--worker_multiplex"><code id="worker_multiplex"><a href="#build-flag--worker_multiplex">--[no]worker_multiplex</a></code> default: "true"</dt> +<dd> +<p>If enabled, workers will use multiplexing if they support it.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--worker_quit_after_build"><code id="worker_quit_after_build"><a href="#build-flag--worker_quit_after_build">--[no]worker_quit_after_build</a></code> default: "false"</dt> +<dd> +<p>If enabled, all workers quit after a build is done.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--worker_sandboxing"><code id="worker_sandboxing"><a href="#build-flag--worker_sandboxing">--[no]worker_sandboxing</a></code> default: "false"</dt> +<dd> +<p>If enabled, singleplex workers will run in a sandboxed environment. Singleplex workers are always sandboxed when running under the dynamic execution strategy, irrespective of this flag.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--worker_verbose"><code id="worker_verbose"><a href="#build-flag--worker_verbose">--[no]worker_verbose</a></code> default: "false"</dt> +<dd> +<p>If enabled, prints verbose messages when workers are started, shutdown, ...</p> +</dd> +</dl> +<dl>Options that control the output of the command: +<dt id="build-flag--build"><code id="build"><a href="#build-flag--build">--[no]build</a></code> default: "true"</dt> +<dd> +<p>Execute the build; this is the usual behaviour. Specifying --nobuild causes the build to stop before executing the build actions, returning zero iff the package loading and analysis phases completed successfully; this mode is useful for testing those phases.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--experimental_use_validation_aspect"><code id="experimental_use_validation_aspect"><a href="#build-flag--experimental_use_validation_aspect">--[no]experimental_use_validation_aspect</a></code> default: "false"</dt> +<dd> +<p>Whether to run validation actions using aspect (for parallelism with tests).</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--output_groups"><code id="output_groups"><a href="#build-flag--output_groups">--output_groups</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>A list of comma-separated output group names, each of which optionally prefixed by a + or a -. A group prefixed by + is added to the default set of output groups, while a group prefixed by - is removed from the default set. If at least one group is not prefixed, the default set of output groups is omitted. For example, --output_groups=+foo,+bar builds the union of the default set, foo, and bar, while --output_groups=foo,bar overrides the default set such that only foo and bar are built.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--run_validations"><code id="run_validations"><a href="#build-flag--run_validations">--[no]run_validations</a></code> default: "true"</dt> +<dd> +<p>Whether to run validation actions as part of the build. See https://bazel.build/extending/rules#validation_actions</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--serialized_frontier_profile"><code id="serialized_frontier_profile"><a href="#build-flag--serialized_frontier_profile">--serialized_frontier_profile</a>=<a string></code> default: ""</dt> +<dd> +<p>Dump a profile of serialized frontier bytes. Specifies the output path.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="build-flag--aspects"><code id="aspects"><a href="#build-flag--aspects">--aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of aspects to be applied to top-level targets. In the list, if aspect some_aspect specifies required aspect providers via required_aspect_providers, some_aspect will run after every aspect that was mentioned before it in the aspects list whose advertised providers satisfy some_aspect required aspect providers. Moreover, some_aspect will run after all its required aspects specified by requires attribute. some_aspect will then have access to the values of those aspects' providers. <bzl-file-label>%<aspect_name>, for example '//tools:my_def.bzl%my_aspect', where 'my_aspect' is a top-level value from a file tools/my_def.bzl</p> +</dd> +<dt id="build-flag--bep_maximum_open_remote_upload_files"><code id="bep_maximum_open_remote_upload_files"><a href="#build-flag--bep_maximum_open_remote_upload_files">--bep_maximum_open_remote_upload_files</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>Maximum number of open files allowed during BEP artifact upload.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--experimental_convenience_symlinks"><code id="experimental_convenience_symlinks"><a href="#build-flag--experimental_convenience_symlinks">--[no]experimental_convenience_symlinks</a></code> default: "normal"</dt> +<dd> +<p>This flag controls how the convenience symlinks (the symlinks that appear in the workspace after the build) will be managed. Possible values: +normal (default): Each kind of convenience symlink will be created or deleted, as determined by the build. +clean: All symlinks will be unconditionally deleted. +ignore: Symlinks will not be created or cleaned up. +log_only: Generate log messages as if 'normal' were passed, but don't actually perform any filesystem operations (useful for tools). +Note that only symlinks whose names are generated by the current value of --symlink_prefix can be affected; if the prefix changes, any pre-existing symlinks will be left alone.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--experimental_convenience_symlinks_bep_event"><code id="experimental_convenience_symlinks_bep_event"><a href="#build-flag--experimental_convenience_symlinks_bep_event">--[no]experimental_convenience_symlinks_bep_event</a></code> default: "true"</dt> +<dd> +<p>This flag controls whether or not we will post the build eventConvenienceSymlinksIdentified to the BuildEventProtocol. If the value is true, the BuildEventProtocol will have an entry for convenienceSymlinksIdentified, listing all of the convenience symlinks created in your workspace. If false, then the convenienceSymlinksIdentified entry in the BuildEventProtocol will be empty.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--remote_download_all"><code id="remote_download_all"><a href="#build-flag--remote_download_all">--remote_download_all</a></code></dt> +<dd> +<p>Downloads all remote outputs to the local machine. This flag is an alias for --remote_download_outputs=all.</p> +<p>Expands to: +<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=all</a></code> +</p><p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--remote_download_minimal"><code id="remote_download_minimal"><a href="#build-flag--remote_download_minimal">--remote_download_minimal</a></code></dt> +<dd> +<p>Does not download any remote build outputs to the local machine. This flag is an alias for --remote_download_outputs=minimal.</p> +<p>Expands to: +<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=minimal</a></code> +</p><p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--remote_download_outputs"><code id="remote_download_outputs"><a href="#build-flag--remote_download_outputs">--remote_download_outputs</a>=<all, minimal or toplevel></code> default: "toplevel"</dt> +<dd> +<p>If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--remote_download_symlink_template"><code id="remote_download_symlink_template"><a href="#build-flag--remote_download_symlink_template">--remote_download_symlink_template</a>=<a string></code> default: ""</dt> +<dd> +<p>Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--remote_download_toplevel"><code id="remote_download_toplevel"><a href="#build-flag--remote_download_toplevel">--remote_download_toplevel</a></code></dt> +<dd> +<p>Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote_download_outputs=toplevel.</p> +<p>Expands to: +<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=toplevel</a></code> +</p><p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--symlink_prefix"><code id="symlink_prefix"><a href="#build-flag--symlink_prefix">--symlink_prefix</a>=<a string></code> default: see description</dt> +<dd> +<p>The prefix that is prepended to any of the convenience symlinks that are created after a build. If omitted, the default value is the name of the build tool followed by a hyphen. If '/' is passed, then no symlinks are created and no warning is emitted. Warning: the special functionality for '/' will be deprecated soon; use --experimental_convenience_symlinks=ignore instead.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="build-flag--experimental_docker_privileged"><code id="experimental_docker_privileged"><a href="#build-flag--experimental_docker_privileged">--[no]experimental_docker_privileged</a></code> default: "false"</dt> +<dd> +<p>If enabled, Bazel will pass the --privileged flag to 'docker run' when running actions. This might be required by your build, but it might also result in reduced hermeticity.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_sandboxfs_map_symlink_targets"><code id="experimental_sandboxfs_map_symlink_targets"><a href="#build-flag--experimental_sandboxfs_map_symlink_targets">--[no]experimental_sandboxfs_map_symlink_targets</a></code> default: "false"</dt> +<dd> +<p>No-op</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_add_mount_pair"><code id="sandbox_add_mount_pair"><a href="#build-flag--sandbox_add_mount_pair">--sandbox_add_mount_pair</a>=<a single path or a 'source:target' pair></code> multiple uses are accumulated</dt> +<dd> +<p>Add additional path pair to mount in sandbox.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_block_path"><code id="sandbox_block_path"><a href="#build-flag--sandbox_block_path">--sandbox_block_path</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>For sandboxed actions, disallow access to this path.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_default_allow_network"><code id="sandbox_default_allow_network"><a href="#build-flag--sandbox_default_allow_network">--[no]sandbox_default_allow_network</a></code> default: "true"</dt> +<dd> +<p>Allow network access by default for actions; this may not work with all sandboxing implementations.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_fake_hostname"><code id="sandbox_fake_hostname"><a href="#build-flag--sandbox_fake_hostname">--[no]sandbox_fake_hostname</a></code> default: "false"</dt> +<dd> +<p>Change the current hostname to 'localhost' for sandboxed actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_fake_username"><code id="sandbox_fake_username"><a href="#build-flag--sandbox_fake_username">--[no]sandbox_fake_username</a></code> default: "false"</dt> +<dd> +<p>Change the current username to 'nobody' for sandboxed actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--sandbox_writable_path"><code id="sandbox_writable_path"><a href="#build-flag--sandbox_writable_path">--sandbox_writable_path</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>For sandboxed actions, make an existing directory writable in the sandbox (if supported by the sandboxing implementation, ignored otherwise).</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="build-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#build-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> +<dd> +<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="build-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#build-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> +<dd> +<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that govern the behavior of the test environment or test runner: +<dt id="build-flag--check_tests_up_to_date"><code id="check_tests_up_to_date"><a href="#build-flag--check_tests_up_to_date">--[no]check_tests_up_to_date</a></code> default: "false"</dt> +<dd> +<p>Don't run tests, just check if they are up-to-date. If all tests results are up-to-date, the testing completes successfully. If any test needs to be built or executed, an error is reported and the testing fails. This option implies --check_up_to_date behavior.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--flaky_test_attempts"><code id="flaky_test_attempts"><a href="#build-flag--flaky_test_attempts">--flaky_test_attempts</a>=<a positive integer, the string "default", or test_regex@attempts. This flag may be passed more than once></code> multiple uses are accumulated</dt> +<dd> +<p>Each test will be retried up to the specified number of times in case of any test failure. Tests that required more than one attempt to pass are marked as 'FLAKY' in the test summary. Normally the value specified is just an integer or the string 'default'. If an integer, then all tests will be run up to N times. If 'default', then only a single test attempt will be made for regular tests and three for tests marked explicitly as flaky by their rule (flaky=1 attribute). Alternate syntax: regex_filter@flaky_test_attempts. Where flaky_test_attempts is as above and regex_filter stands for a list of include and exclude regular expression patterns (Also see --runs_per_test). Example: --flaky_test_attempts=//foo/.<em>,-//foo/bar/.</em>@3 deflakes all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, behavior is as if 'default' above.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--local_test_jobs"><code id="local_test_jobs"><a href="#build-flag--local_test_jobs">--local_test_jobs</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> +<dd> +<p>The max number of local test jobs to run concurrently. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". 0 means local resources will limit the number of local test jobs to run concurrently instead. Setting this greater than the value for --jobs is ineffectual.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--test_keep_going"><code id="test_keep_going"><a href="#build-flag--test_keep_going">--[no]test_keep_going</a></code> default: "true"</dt> +<dd> +<p>When disabled, any non-passing test will cause the entire build to stop. By default all tests are run, even if some do not pass.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--test_strategy"><code id="test_strategy"><a href="#build-flag--test_strategy">--test_strategy</a>=<a string></code> default: ""</dt> +<dd> +<p>Specifies which strategy to use when running tests.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--test_tmpdir"><code id="test_tmpdir"><a href="#build-flag--test_tmpdir">--test_tmpdir</a>=<a path></code> default: see description</dt> +<dd> +<p>Specifies the base temporary directory for 'bazel test' to use.</p> +</dd> +</dl> +<dl>Options that trigger optimizations of the build time: +<dt id="build-flag--cache_computed_file_digests"><code id="cache_computed_file_digests"><a href="#build-flag--cache_computed_file_digests">--cache_computed_file_digests</a>=<a long integer></code> default: "50000"</dt> +<dd> +<p>If greater than 0, configures Bazel to cache file digests in memory based on their metadata instead of recomputing the digests from disk every time they are needed. Setting this to 0 ensures correctness because not all file changes can be noted from file metadata. When not 0, the number indicates the size of the cache as the number of file digests to be cached.</p> +</dd> +<dt id="build-flag--experimental_active_directories"><code id="experimental_active_directories"><a href="#build-flag--experimental_active_directories">--experimental_active_directories</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>Active directories for Skyfocus and remote analysis caching. Specify as comma-separated workspace root-relative paths. This is a stateful flag. Defining one persists it for subsequent invocations, until it is redefined with a new set.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--experimental_cpu_load_scheduling"><code id="experimental_cpu_load_scheduling"><a href="#build-flag--experimental_cpu_load_scheduling">--[no]experimental_cpu_load_scheduling</a></code> default: "false"</dt> +<dd> +<p>Enables the experimental local execution scheduling based on CPU load, not estimation of actions one by one. Experimental scheduling have showed the large benefit on a large local builds on a powerful machines with the large number of cores. Reccommended to use with --local_resources=cpu=HOST_CPUS</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_dynamic_ignore_local_signals"><code id="experimental_dynamic_ignore_local_signals"><a href="#build-flag--experimental_dynamic_ignore_local_signals">--experimental_dynamic_ignore_local_signals</a>=<a comma-separated list of signal numbers></code> default: see description</dt> +<dd> +<p>Takes a list of OS signal numbers. If a local branch of dynamic execution gets killed with any of these signals, the remote branch will be allowed to finish instead. For persistent workers, this only affects signals that kill the worker process.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_enable_skyfocus"><code id="experimental_enable_skyfocus"><a href="#build-flag--experimental_enable_skyfocus">--[no]experimental_enable_skyfocus</a></code> default: "false"</dt> +<dd> +<p>If true, enable the use of --experimental_active_directories to reduce Bazel's memory footprint for incremental builds. This feature is known as Skyfocus.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--local_cpu_resources"><code id="local_cpu_resources"><a href="#build-flag--local_cpu_resources">--local_cpu_resources</a>=<an integer, or "HOST_CPUS", optionally followed by [-|*]<float>.></code> default: "HOST_CPUS"</dt> +<dd> +<p>Explicitly set the total number of local CPU cores available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST_CPUS", optionally followed by [-|<em>]<float> (eg. HOST_CPUS</em>.5 to use half the available CPU cores). By default, ("HOST_CPUS"), Bazel will query system configuration to estimate the number of CPU cores available.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--local_extra_resources"><code id="local_extra_resources"><a href="#build-flag--local_extra_resources">--local_extra_resources</a>=<a named float, 'name=value'></code> multiple uses are accumulated</dt> +<dd> +<p>Set the number of extra resources available to Bazel. Takes in a string-float pair. Can be used multiple times to specify multiple types of extra resources. Bazel will limit concurrently running actions based on the available extra resources and the extra resources required. Tests can declare the amount of extra resources they need by using a tag of the "resources:<resoucename>:<amount>" format. Available CPU, RAM and resources cannot be set with this flag.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--local_ram_resources"><code id="local_ram_resources"><a href="#build-flag--local_ram_resources">--local_ram_resources</a>=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.></code> default: "HOST_RAM*.67"</dt> +<dd> +<p>Explicitly set the total amount of local host RAM (in MB) available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST_RAM", optionally followed by [-|<em>]<float> (eg. HOST_RAM</em>.5 to use half the available RAM). By default, ("HOST_RAM*.67"), Bazel will query system configuration to estimate the amount of RAM available and will use 67% of it.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--local_resources"><code id="local_resources"><a href="#build-flag--local_resources">--local_resources</a>=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> multiple uses are accumulated</dt> +<dd> +<p>Set the number of resources available to Bazel. Takes in an assignment to a float or HOST_RAM/HOST_CPUS, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.5 to use half the available RAM). Can be used multiple times to specify multiple types of resources. Bazel will limit concurrently running actions based on the available resources and the resources required. Tests can declare the amount of resources they need by using a tag of the "resources:<resource name>:<amount>" format. Overrides resources specified by --local_{cpu|ram|extra}_resources.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="build-flag--build_event_upload_max_retries"><code id="build_event_upload_max_retries"><a href="#build-flag--build_event_upload_max_retries">--build_event_upload_max_retries</a>=<an integer></code> default: "4"</dt> +<dd> +<p>The maximum number of times Bazel should retry uploading a build event.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="build-flag--debug_spawn_scheduler"><code id="debug_spawn_scheduler"><a href="#build-flag--debug_spawn_scheduler">--[no]debug_spawn_scheduler</a></code> default: "false"</dt> +<dd> +</dd> +<dt id="build-flag--experimental_bep_target_summary"><code id="experimental_bep_target_summary"><a href="#build-flag--experimental_bep_target_summary">--[no]experimental_bep_target_summary</a></code> default: "false"</dt> +<dd> +<p>Whether to publish TargetSummary events.</p> +</dd> +<dt id="build-flag--experimental_build_event_expand_filesets"><code id="experimental_build_event_expand_filesets"><a href="#build-flag--experimental_build_event_expand_filesets">--[no]experimental_build_event_expand_filesets</a></code> default: "false"</dt> +<dd> +<p>If true, expand Filesets in the BEP when presenting output files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--experimental_build_event_output_group_mode"><code id="experimental_build_event_output_group_mode"><a href="#build-flag--experimental_build_event_output_group_mode">--experimental_build_event_output_group_mode</a>=<an output group name followed by an OutputGroupFileMode, e.g. default=both></code> multiple uses are accumulated</dt> +<dd> +<p>Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED_SET_OF_FILES_ONLY', 'INLINE_ONLY', or 'BOTH'. The default value is 'NAMED_SET_OF_FILES_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental_build_event_output_group_mode=baseline.lcov=both</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--experimental_build_event_upload_retry_minimum_delay"><code id="experimental_build_event_upload_retry_minimum_delay"><a href="#build-flag--experimental_build_event_upload_retry_minimum_delay">--experimental_build_event_upload_retry_minimum_delay</a>=<An immutable length of time.></code> default: "1s"</dt> +<dd> +<p>Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6)</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="build-flag--experimental_build_event_upload_strategy"><code id="experimental_build_event_upload_strategy"><a href="#build-flag--experimental_build_event_upload_strategy">--experimental_build_event_upload_strategy</a>=<a string></code> default: see description</dt> +<dd> +<p>Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--experimental_docker_verbose"><code id="experimental_docker_verbose"><a href="#build-flag--experimental_docker_verbose">--[no]experimental_docker_verbose</a></code> default: "false"</dt> +<dd> +<p>If enabled, Bazel will print more verbose messages about the Docker sandbox strategy.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_frontier_violation_check"><code id="experimental_frontier_violation_check"><a href="#build-flag--experimental_frontier_violation_check">--experimental_frontier_violation_check</a>=<strict, warn or disabled_for_testing></code> default: "strict"</dt> +<dd> +<p>Strategies to handle potential incorrectness from changes beyond the frontier (i.e. outside the active directories)</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="build-flag--experimental_frontier_violation_verbose"><code id="experimental_frontier_violation_verbose"><a href="#build-flag--experimental_frontier_violation_verbose">--[no]experimental_frontier_violation_verbose</a></code> default: "false"</dt> +<dd> +<p>If true, Bazel will print instructions for fixing Skycache violations</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--experimental_materialize_param_files_directly"><code id="experimental_materialize_param_files_directly"><a href="#build-flag--experimental_materialize_param_files_directly">--[no]experimental_materialize_param_files_directly</a></code> default: "false"</dt> +<dd> +<p>If materializing param files, do so with direct writes to disk.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_run_bep_event_include_residue"><code id="experimental_run_bep_event_include_residue"><a href="#build-flag--experimental_run_bep_event_include_residue">--[no]experimental_run_bep_event_include_residue</a></code> default: "false"</dt> +<dd> +<p>Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--experimental_skyfocus_dump_keys"><code id="experimental_skyfocus_dump_keys"><a href="#build-flag--experimental_skyfocus_dump_keys">--experimental_skyfocus_dump_keys</a>=<none, count or verbose></code> default: "none"</dt> +<dd> +<p>For debugging Skyfocus. Dump the focused SkyKeys (roots, leafs, focused deps, focused rdeps).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--experimental_skyfocus_dump_post_gc_stats"><code id="experimental_skyfocus_dump_post_gc_stats"><a href="#build-flag--experimental_skyfocus_dump_post_gc_stats">--[no]experimental_skyfocus_dump_post_gc_stats</a></code> default: "false"</dt> +<dd> +<p>For debugging Skyfocus. If enabled, trigger manual GC before/after focusing to report heap sizes reductions. This will increase the Skyfocus latency.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--experimental_stream_log_file_uploads"><code id="experimental_stream_log_file_uploads"><a href="#build-flag--experimental_stream_log_file_uploads">--[no]experimental_stream_log_file_uploads</a></code> default: "false"</dt> +<dd> +<p>Stream log file uploads directly to the remote storage rather than writing them to disk.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--explain"><code id="explain"><a href="#build-flag--explain">--explain</a>=<a path></code> default: see description</dt> +<dd> +<p>Causes the build system to explain each executed step of the build. The explanation is written to the specified log file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--ignore_unsupported_sandboxing"><code id="ignore_unsupported_sandboxing"><a href="#build-flag--ignore_unsupported_sandboxing">--[no]ignore_unsupported_sandboxing</a></code> default: "false"</dt> +<dd> +<p>Do not print a warning when sandboxed execution is not supported on this system.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--legacy_important_outputs"><code id="legacy_important_outputs"><a href="#build-flag--legacy_important_outputs">--[no]legacy_important_outputs</a></code> default: "false"</dt> +<dd> +<p>Use this to suppress generation of the legacy important_outputs field in the TargetComplete event. important_outputs are required for Bazel to ResultStore/BTX integration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--materialize_param_files"><code id="materialize_param_files"><a href="#build-flag--materialize_param_files">--[no]materialize_param_files</a></code> default: "false"</dt> +<dd> +<p>Writes intermediate parameter files to output tree even when using remote action execution or caching. Useful when debugging actions. This is implied by --subcommands and --verbose_failures.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--max_config_changes_to_show"><code id="max_config_changes_to_show"><a href="#build-flag--max_config_changes_to_show">--max_config_changes_to_show</a>=<an integer></code> default: "3"</dt> +<dd> +<p>When discarding the analysis cache due to a change in the build options, displays up to the given number of changed option names. If the number given is -1, all changed options will be displayed.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--max_test_output_bytes"><code id="max_test_output_bytes"><a href="#build-flag--max_test_output_bytes">--max_test_output_bytes</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>Specifies maximum per-test-log size that can be emitted when --test_output is 'errors' or 'all'. Useful for avoiding overwhelming the output with excessively noisy test output. The test header is included in the log size. Negative values imply no limit. Output is all or nothing.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--output_filter"><code id="output_filter"><a href="#build-flag--output_filter">--output_filter</a>=<a valid Java regular expression></code> default: see description</dt> +<dd> +<p>Only shows warnings and action outputs for rules with a name matching the provided regular expression.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--progress_report_interval"><code id="progress_report_interval"><a href="#build-flag--progress_report_interval">--progress_report_interval</a>=<an integer in 0-3600 range></code> default: "0"</dt> +<dd> +<p>The number of seconds to wait between reports on still running jobs. The default value 0 means the first report will be printed after 10 seconds, then 30 seconds and after that progress is reported once every minute. When --curses is enabled, progress is reported every second.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--remote_analysis_json_log"><code id="remote_analysis_json_log"><a href="#build-flag--remote_analysis_json_log">--remote_analysis_json_log</a>=<a string></code> default: see description</dt> +<dd> +<p>If set, a JSON file is written to this location that contains a detailed log of the behavior of remote analysis caching. It's interpreted as a path relative to the current working directory.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="build-flag--remote_print_execution_messages"><code id="remote_print_execution_messages"><a href="#build-flag--remote_print_execution_messages">--remote_print_execution_messages</a>=<failure, success or all></code> default: "failure"</dt> +<dd> +<p>Choose when to print remote execution messages. Valid values are <code>failure</code>, to print only on failures, <code>success</code> to print only on successes and <code>all</code> to print always.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--sandbox_debug"><code id="sandbox_debug"><a href="#build-flag--sandbox_debug">--[no]sandbox_debug</a></code> default: "false"</dt> +<dd> +<p>Enables debugging features for the sandboxing feature. This includes two things: first, the sandbox root contents are left untouched after a build; and second, prints extra debugging information on execution. This can help developers of Bazel or Starlark rules with debugging failures due to missing input files, etc.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--show_result"><code id="show_result"><a href="#build-flag--show_result">--show_result</a>=<an integer></code> default: "1"</dt> +<dd> +<p>Show the results of the build. For each target, state whether or not it was brought up-to-date, and if so, a list of output files that were built. The printed files are convenient strings for copy+pasting to the shell, to execute them. +This option requires an integer argument, which is the threshold number of targets above which result information is not printed. Thus zero causes suppression of the message and MAX_INT causes printing of the result to occur always. The default is one. +If nothing was built for a target its results may be omitted to keep the output under the threshold.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--subcommands"><code id="subcommands"><a href="#build-flag--subcommands">--[no]subcommands</a></code> [<code>-s</code>] default: "false"</dt> +<dd> +<p>Display the subcommands executed during a build. Related flags: --execution_log_json_file, --execution_log_binary_file (for logging subcommands to a file in a tool-friendly format).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--test_output"><code id="test_output"><a href="#build-flag--test_output">--test_output</a>=<summary, errors, all or streamed></code> default: "summary"</dt> +<dd> +<p>Specifies desired output mode. Valid values are 'summary' to output only test status summary, 'errors' to also print test logs for failed tests, 'all' to print logs for all tests and 'streamed' to output logs for all tests in real time (this will force tests to be executed locally one at a time regardless of --test_strategy value).</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--test_summary"><code id="test_summary"><a href="#build-flag--test_summary">--test_summary</a>=<short, terse, detailed, none or testcase></code> default: "short"</dt> +<dd> +<p>Specifies the desired format of the test summary. Valid values are 'short' to print information only about tests executed, 'terse', to print information only about unsuccessful tests that were run, 'detailed' to print detailed information about failed test cases, 'testcase' to print summary in test case resolution, do not print detailed information about failed test cases and 'none' to omit the summary.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="build-flag--verbose_failures"><code id="verbose_failures"><a href="#build-flag--verbose_failures">--[no]verbose_failures</a></code> default: "false"</dt> +<dd> +<p>If a command fails, print out the full command line.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="build-flag--aspects_parameters"><code id="aspects_parameters"><a href="#build-flag--aspects_parameters">--aspects_parameters</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the values of the command-line aspects parameters. Each parameter value is specified via <param_name>=<param_value>, for example 'my_param=my_val' where 'my_param' is a parameter of some aspect in --aspects list or required by an aspect in the list. This option can be used multiple times. However, it is not allowed to assign values to the same parameter more than once.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="build-flag--target_pattern_file"><code id="target_pattern_file"><a href="#build-flag--target_pattern_file">--target_pattern_file</a>=<a string></code> default: ""</dt> +<dd> +<p>If set, build will read patterns from the file named here, rather than on the command line. It is an error to specify a file here as well as command-line patterns.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Remote caching and execution options: +<dt id="build-flag--experimental_circuit_breaker_strategy"><code id="experimental_circuit_breaker_strategy"><a href="#build-flag--experimental_circuit_breaker_strategy">--experimental_circuit_breaker_strategy</a>=<failure></code> default: see description</dt> +<dd> +<p>Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_remote_cache_compression_threshold"><code id="experimental_remote_cache_compression_threshold"><a href="#build-flag--experimental_remote_cache_compression_threshold">--experimental_remote_cache_compression_threshold</a>=<an integer></code> default: "100"</dt> +<dd> +<p>The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote_cache_compression is set.</p> +</dd> +<dt id="build-flag--experimental_remote_cache_eviction_retries"><code id="experimental_remote_cache_eviction_retries"><a href="#build-flag--experimental_remote_cache_eviction_retries">--experimental_remote_cache_eviction_retries</a>=<an integer></code> default: "5"</dt> +<dd> +<p>The maximum number of attempts to retry if the build encountered a transient remote cache error that would otherwise fail the build. Applies for example when artifacts are evicted from the remote cache, or in certain cache failure conditions. A new invocation id will be generated for each attempt.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_remote_cache_lease_extension"><code id="experimental_remote_cache_lease_extension"><a href="#build-flag--experimental_remote_cache_lease_extension">--[no]experimental_remote_cache_lease_extension</a></code> default: "false"</dt> +<dd> +<p>If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending <code>FindMissingBlobs</code> calls periodically to remote cache. The frequency is based on the value of <code>--experimental_remote_cache_ttl</code>.</p> +</dd> +<dt id="build-flag--experimental_remote_cache_ttl"><code id="experimental_remote_cache_ttl"><a href="#build-flag--experimental_remote_cache_ttl">--experimental_remote_cache_ttl</a>=<An immutable length of time.></code> default: "3h"</dt> +<dd> +<p>The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_remote_capture_corrupted_outputs"><code id="experimental_remote_capture_corrupted_outputs"><a href="#build-flag--experimental_remote_capture_corrupted_outputs">--experimental_remote_capture_corrupted_outputs</a>=<a path></code> default: see description</dt> +<dd> +<p>A path to a directory where the corrupted outputs will be captured to.</p> +</dd> +<dt id="build-flag--experimental_remote_discard_merkle_trees"><code id="experimental_remote_discard_merkle_trees"><a href="#build-flag--experimental_remote_discard_merkle_trees">--[no]experimental_remote_discard_merkle_trees</a></code> default: "true"</dt> +<dd> +<p>If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries.</p> +</dd> +<dt id="build-flag--experimental_remote_downloader"><code id="experimental_remote_downloader"><a href="#build-flag--experimental_remote_downloader">--experimental_remote_downloader</a>=<a string></code> default: see description</dt> +<dd> +<p>A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote_asset.proto</p> +</dd> +<dt id="build-flag--experimental_remote_downloader_local_fallback"><code id="experimental_remote_downloader_local_fallback"><a href="#build-flag--experimental_remote_downloader_local_fallback">--[no]experimental_remote_downloader_local_fallback</a></code> default: "false"</dt> +<dd> +<p>Whether to fall back to the local downloader if remote downloader fails.</p> +</dd> +<dt id="build-flag--experimental_remote_downloader_propagate_credentials"><code id="experimental_remote_downloader_propagate_credentials"><a href="#build-flag--experimental_remote_downloader_propagate_credentials">--[no]experimental_remote_downloader_propagate_credentials</a></code> default: "false"</dt> +<dd> +<p>Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new <code>http_header_url:&lt;url-index&gt;:&lt;header-key&gt;</code> qualifier where the <code>&lt;url-index&gt;</code> is a 0-based position of the URL inside the FetchBlobRequest's <code>uris</code> field. The URL-specific headers should take precedence over the global headers.</p> +</dd> +<dt id="build-flag--experimental_remote_execution_keepalive"><code id="experimental_remote_execution_keepalive"><a href="#build-flag--experimental_remote_execution_keepalive">--[no]experimental_remote_execution_keepalive</a></code> default: "false"</dt> +<dd> +<p>Whether to use keepalive for remote execution calls.</p> +</dd> +<dt id="build-flag--experimental_remote_failure_rate_threshold"><code id="experimental_remote_failure_rate_threshold"><a href="#build-flag--experimental_remote_failure_rate_threshold">--experimental_remote_failure_rate_threshold</a>=<an integer in 0-100 range></code> default: "10"</dt> +<dd> +<p>Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_remote_failure_window_interval"><code id="experimental_remote_failure_window_interval"><a href="#build-flag--experimental_remote_failure_window_interval">--experimental_remote_failure_window_interval</a>=<An immutable length of time.></code> default: "60s"</dt> +<dd> +<p>The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--experimental_remote_mark_tool_inputs"><code id="experimental_remote_mark_tool_inputs"><a href="#build-flag--experimental_remote_mark_tool_inputs">--[no]experimental_remote_mark_tool_inputs</a></code> default: "false"</dt> +<dd> +<p>If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers.</p> +</dd> +<dt id="build-flag--experimental_remote_merkle_tree_cache"><code id="experimental_remote_merkle_tree_cache"><a href="#build-flag--experimental_remote_merkle_tree_cache">--[no]experimental_remote_merkle_tree_cache</a></code> default: "false"</dt> +<dd> +<p>If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental_remote_merkle_tree_cache_size.</p> +</dd> +<dt id="build-flag--experimental_remote_merkle_tree_cache_size"><code id="experimental_remote_merkle_tree_cache_size"><a href="#build-flag--experimental_remote_merkle_tree_cache_size">--experimental_remote_merkle_tree_cache_size</a>=<a long integer></code> default: "1000"</dt> +<dd> +<p>The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000.</p> +</dd> +<dt id="build-flag--experimental_remote_output_service"><code id="experimental_remote_output_service"><a href="#build-flag--experimental_remote_output_service">--experimental_remote_output_service</a>=<a string></code> default: see description</dt> +<dd> +<p>HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS.</p> +</dd> +<dt id="build-flag--experimental_remote_output_service_output_path_prefix"><code id="experimental_remote_output_service_output_path_prefix"><a href="#build-flag--experimental_remote_output_service_output_path_prefix">--experimental_remote_output_service_output_path_prefix</a>=<a string></code> default: ""</dt> +<dd> +<p>The path under which the contents of output directories managed by the --experimental_remote_output_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service.</p> +</dd> +<dt id="build-flag--experimental_remote_require_cached"><code id="experimental_remote_require_cached"><a href="#build-flag--experimental_remote_require_cached">--[no]experimental_remote_require_cached</a></code> default: "false"</dt> +<dd> +<p>If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache.</p> +</dd> +<dt id="build-flag--experimental_remote_scrubbing_config"><code id="experimental_remote_scrubbing_config"><a href="#build-flag--experimental_remote_scrubbing_config">--experimental_remote_scrubbing_config</a>=<Converts to a Scrubber></code> default: see description</dt> +<dd> +<p>Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote_scrubbing.proto).</p> +<p>This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds.</p> +<p>Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead.</p> +<p>Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions.</p> +<p>In order to successfully use this feature, you likely want to set a custom --host_platform together with --experimental_platform_in_output_dir (to normalize output prefixes) and --incompatible_strict_action_env (to normalize environment variables).</p> +</dd> +<dt id="build-flag--guard_against_concurrent_changes"><code id="guard_against_concurrent_changes"><a href="#build-flag--guard_against_concurrent_changes">--[no]guard_against_concurrent_changes</a></code> default: "lite"</dt> +<dd> +<p>Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="build-flag--remote_accept_cached"><code id="remote_accept_cached"><a href="#build-flag--remote_accept_cached">--[no]remote_accept_cached</a></code> default: "true"</dt> +<dd> +<p>Whether to accept remotely cached action results.</p> +</dd> +<dt id="build-flag--remote_build_event_upload"><code id="remote_build_event_upload"><a href="#build-flag--remote_build_event_upload">--remote_build_event_upload</a>=<all or minimal></code> default: "minimal"</dt> +<dd> +<p>If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. +If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. +Default to 'minimal'.</p> +</dd> +<dt id="build-flag--remote_bytestream_uri_prefix"><code id="remote_bytestream_uri_prefix"><a href="#build-flag--remote_bytestream_uri_prefix">--remote_bytestream_uri_prefix</a>=<a string></code> default: see description</dt> +<dd> +<p>The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote_executor and --remote_instance_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "${hostname}/${instance_name}".</p> +</dd> +<dt id="build-flag--remote_cache"><code id="remote_cache"><a href="#build-flag--remote_cache">--remote_cache</a>=<a string></code> default: see description</dt> +<dd> +<p>A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching</p> +</dd> +<dt id="build-flag--remote_cache_async"><code id="remote_cache_async"><a href="#build-flag--remote_cache_async">--[no]remote_cache_async</a></code> default: "true"</dt> +<dd> +<p>If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set.</p> +</dd> +<dt id="build-flag--remote_cache_compression"><code id="remote_cache_compression"><a href="#build-flag--remote_cache_compression">--[no]remote_cache_compression</a></code> default: "false"</dt> +<dd> +<p>If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental_remote_cache_compression_threshold.</p> +</dd> +<dt id="build-flag--remote_cache_header"><code id="remote_cache_header"><a href="#build-flag--remote_cache_header">--remote_cache_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header that will be included in cache requests: --remote_cache_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +</dd> +<dt id="build-flag--remote_default_exec_properties"><code id="remote_default_exec_properties"><a href="#build-flag--remote_default_exec_properties">--remote_default_exec_properties</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec_properties.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--remote_default_platform_properties"><code id="remote_default_platform_properties"><a href="#build-flag--remote_default_platform_properties">--remote_default_platform_properties</a>=<a string></code> default: ""</dt> +<dd> +<p>Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote_execution_properties. This value will also be used if the host platform is selected as the execution platform for remote execution.</p> +</dd> +<dt id="build-flag--remote_download_regex"><code id="remote_download_regex"><a href="#build-flag--remote_download_regex">--remote_download_regex</a>=<a valid Java regular expression></code> multiple uses are accumulated</dt> +<dd> +<p>Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote_download_outputs. Multiple patterns may be specified by repeating this flag.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="build-flag--remote_downloader_header"><code id="remote_downloader_header"><a href="#build-flag--remote_downloader_header">--remote_downloader_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header that will be included in remote downloader requests: --remote_downloader_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +</dd> +<dt id="build-flag--remote_exec_header"><code id="remote_exec_header"><a href="#build-flag--remote_exec_header">--remote_exec_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header that will be included in execution requests: --remote_exec_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +</dd> +<dt id="build-flag--remote_execution_priority"><code id="remote_execution_priority"><a href="#build-flag--remote_execution_priority">--remote_execution_priority</a>=<an integer></code> default: "0"</dt> +<dd> +<p>The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent.</p> +</dd> +<dt id="build-flag--remote_executor"><code id="remote_executor"><a href="#build-flag--remote_executor">--remote_executor</a>=<a string></code> default: see description</dt> +<dd> +<p>HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS.</p> +</dd> +<dt id="build-flag--remote_grpc_log"><code id="remote_grpc_log"><a href="#build-flag--remote_grpc_log">--remote_grpc_log</a>=<a path></code> default: see description</dt> +<dd> +<p>If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream).</p> +</dd> +<dt id="build-flag--remote_header"><code id="remote_header"><a href="#build-flag--remote_header">--remote_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Specify a header that will be included in requests: --remote_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> +</dd> +<dt id="build-flag--remote_instance_name"><code id="remote_instance_name"><a href="#build-flag--remote_instance_name">--remote_instance_name</a>=<a string></code> default: ""</dt> +<dd> +<p>Value to pass as instance_name in the remote execution API.</p> +</dd> +<dt id="build-flag--remote_local_fallback"><code id="remote_local_fallback"><a href="#build-flag--remote_local_fallback">--[no]remote_local_fallback</a></code> default: "false"</dt> +<dd> +<p>Whether to fall back to standalone local execution strategy if remote execution fails.</p> +</dd> +<dt id="build-flag--remote_local_fallback_strategy"><code id="remote_local_fallback_strategy"><a href="#build-flag--remote_local_fallback_strategy">--remote_local_fallback_strategy</a>=<a string></code> default: "local"</dt> +<dd> +<p>Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details.</p> +</dd> +<dt id="build-flag--remote_max_connections"><code id="remote_max_connections"><a href="#build-flag--remote_max_connections">--remote_max_connections</a>=<an integer></code> default: "100"</dt> +<dd> +<p>Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. +For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote_max_connections concurrent requests. +For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around <code>--remote_max_connections * 100</code> concurrent requests.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="build-flag--remote_proxy"><code id="remote_proxy"><a href="#build-flag--remote_proxy">--remote_proxy</a>=<a string></code> default: see description</dt> +<dd> +<p>Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket).</p> +</dd> +<dt id="build-flag--remote_result_cache_priority"><code id="remote_result_cache_priority"><a href="#build-flag--remote_result_cache_priority">--remote_result_cache_priority</a>=<an integer></code> default: "0"</dt> +<dd> +<p>The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent.</p> +</dd> +<dt id="build-flag--remote_retries"><code id="remote_retries"><a href="#build-flag--remote_retries">--remote_retries</a>=<an integer></code> default: "5"</dt> +<dd> +<p>The maximum number of attempts to retry a transient error. If set to 0, retries are disabled.</p> +</dd> +<dt id="build-flag--remote_retry_max_delay"><code id="remote_retry_max_delay"><a href="#build-flag--remote_retry_max_delay">--remote_retry_max_delay</a>=<An immutable length of time.></code> default: "5s"</dt> +<dd> +<p>The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> +</dd> +<dt id="build-flag--remote_timeout"><code id="remote_timeout"><a href="#build-flag--remote_timeout">--remote_timeout</a>=<An immutable length of time.></code> default: "60s"</dt> +<dd> +<p>The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> +</dd> +<dt id="build-flag--remote_upload_local_results"><code id="remote_upload_local_results"><a href="#build-flag--remote_upload_local_results">--[no]remote_upload_local_results</a></code> default: "true"</dt> +<dd> +<p>Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so.</p> +</dd> +<dt id="build-flag--remote_verify_downloads"><code id="remote_verify_downloads"><a href="#build-flag--remote_verify_downloads">--[no]remote_verify_downloads</a></code> default: "true"</dt> +<dd> +<p>If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value.</p> +</dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="build-flag--allow_analysis_cache_discard"><code id="allow_analysis_cache_discard"><a href="#build-flag--allow_analysis_cache_discard">--[no]allow_analysis_cache_discard</a></code> default: "true"</dt> +<dd> +<p>If discarding the analysis cache due to a change in the build system, setting this option to false will cause bazel to exit, rather than continuing with the build. This option has no effect when 'discard_analysis_cache' is also set.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="build-flag--auto_output_filter"><code id="auto_output_filter"><a href="#build-flag--auto_output_filter">--auto_output_filter</a>=<none, all, packages or subpackages></code> default: "none"</dt> +<dd> +<p>If --output_filter is not specified, then the value for this option is used create a filter automatically. Allowed values are 'none' (filter nothing / show everything), 'all' (filter everything / show nothing), 'packages' (include output from rules in packages mentioned on the Blaze command line), and 'subpackages' (like 'packages', but also include subpackages). For the 'packages' and 'subpackages' values //java/foo and //javatests/foo are treated as one package)'.</p> +</dd> +<dt id="build-flag--build_manual_tests"><code id="build_manual_tests"><a href="#build-flag--build_manual_tests">--[no]build_manual_tests</a></code> default: "false"</dt> +<dd> +<p>Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from processing. This option forces them to be built (but not executed).</p> +</dd> +<dt id="build-flag--build_tag_filters"><code id="build_tag_filters"><a href="#build-flag--build_tag_filters">--build_tag_filters</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>Specifies a comma-separated list of tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those targets will be built that contain at least one included tag and do not contain any excluded tags. This option does not affect the set of tests executed with the 'test' command; those are be governed by the test filtering options, for example '--test_tag_filters'</p> +</dd> +<dt id="build-flag--build_tests_only"><code id="build_tests_only"><a href="#build-flag--build_tests_only">--[no]build_tests_only</a></code> default: "false"</dt> +<dd> +<p>If specified, only *_test and test_suite rules will be built and other targets specified on the command line will be ignored. By default everything that was requested will be built.</p> +</dd> +<dt id="build-flag--combined_report"><code id="combined_report"><a href="#build-flag--combined_report">--combined_report</a>=<none or lcov></code> default: "lcov"</dt> +<dd> +<p>Specifies desired cumulative coverage report type. At this point only LCOV is supported.</p> +</dd> +<dt id="build-flag--compile_one_dependency"><code id="compile_one_dependency"><a href="#build-flag--compile_one_dependency">--[no]compile_one_dependency</a></code> default: "false"</dt> +<dd> +<p>Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single target that depends on the source file to detect errors as early as possible in the edit/build/test cycle. This argument affects the way all non-flag arguments are interpreted; instead of being targets to build they are source filenames. For each source filename an arbitrary target that depends on it will be built.</p> +</dd> +<dt id="build-flag--deleted_packages"><code id="deleted_packages"><a href="#build-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> +<dd> +<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> +</dd> +<dt id="build-flag--discard_analysis_cache"><code id="discard_analysis_cache"><a href="#build-flag--discard_analysis_cache">--[no]discard_analysis_cache</a></code> default: "false"</dt> +<dd> +<p>Discard the analysis cache immediately after the analysis phase completes. Reduces memory usage by ~10%, but makes further incremental builds slower.</p> +</dd> +<dt id="build-flag--disk_cache"><code id="disk_cache"><a href="#build-flag--disk_cache">--disk_cache</a>=<a path></code> default: see description</dt> +<dd> +<p>A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created.</p> +</dd> +<dt id="build-flag--embed_label"><code id="embed_label"><a href="#build-flag--embed_label">--embed_label</a>=<a one-line string></code> default: ""</dt> +<dd> +<p>Embed source control revision or release label in binary</p> +</dd> +<dt id="build-flag--execution_log_binary_file"><code id="execution_log_binary_file"><a href="#build-flag--execution_log_binary_file">--execution_log_binary_file</a>=<a path></code> default: see description</dt> +<dd> +<p>Log the executed spawns into this file as length-delimited SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution_log_compact_file, which is significantly smaller and cheaper to produce. Related flags: --execution_log_compact_file (compact format; mutually exclusive), --execution_log_json_file (text JSON format; mutually exclusive), --execution_log_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output).</p> +</dd> +<dt id="build-flag--execution_log_compact_file"><code id="execution_log_compact_file"><a href="#build-flag--execution_log_compact_file">--execution_log_compact_file</a>=<a path></code> default: see description</dt> +<dd> +<p>Log the executed spawns into this file as length-delimited ExecLogEntry protos, according to src/main/protobuf/spawn.proto. The entire file is zstd compressed. Related flags: --execution_log_binary_file (binary protobuf format; mutually exclusive), --execution_log_json_file (text JSON format; mutually exclusive), --subcommands (for displaying subcommands in terminal output).</p> +</dd> +<dt id="build-flag--execution_log_json_file"><code id="execution_log_json_file"><a href="#build-flag--execution_log_json_file">--execution_log_json_file</a>=<a path></code> default: see description</dt> +<dd> +<p>Log the executed spawns into this file as newline-delimited JSON representations of SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution_log_compact_file, which is significantly smaller and cheaper to produce. Related flags: --execution_log_compact_file (compact format; mutually exclusive), --execution_log_binary_file (binary protobuf format; mutually exclusive), --execution_log_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output).</p> +</dd> +<dt id="build-flag--execution_log_sort"><code id="execution_log_sort"><a href="#build-flag--execution_log_sort">--[no]execution_log_sort</a></code> default: "true"</dt> +<dd> +<p>Whether to sort the execution log, making it easier to compare logs across invocations. Set to false to avoid potentially significant CPU and memory usage at the end of the invocation, at the cost of producing the log in nondeterministic execution order. Only applies to the binary and JSON formats; the compact format is never sorted.</p> +</dd> +<dt id="build-flag--expand_test_suites"><code id="expand_test_suites"><a href="#build-flag--expand_test_suites">--[no]expand_test_suites</a></code> default: "true"</dt> +<dd> +<p>Expand test_suite targets into their constituent tests before analysis. When this flag is turned on (the default), negative target patterns will apply to the tests belonging to the test suite, otherwise they will not. Turning off this flag is useful when top-level aspects are applied at command line: then they can analyze test_suite targets.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="build-flag--experimental_disk_cache_gc_idle_delay"><code id="experimental_disk_cache_gc_idle_delay"><a href="#build-flag--experimental_disk_cache_gc_idle_delay">--experimental_disk_cache_gc_idle_delay</a>=<An immutable length of time.></code> default: "5m"</dt> +<dd> +<p>How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental_disk_cache_gc_max_size and/or --experimental_disk_cache_gc_max_age.</p> +</dd> +<dt id="build-flag--experimental_disk_cache_gc_max_age"><code id="experimental_disk_cache_gc_max_age"><a href="#build-flag--experimental_disk_cache_gc_max_age">--experimental_disk_cache_gc_max_age</a>=<An immutable length of time.></code> default: "0"</dt> +<dd> +<p>If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental_disk_cache_gc_max_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag.</p> +</dd> +<dt id="build-flag--experimental_disk_cache_gc_max_size"><code id="experimental_disk_cache_gc_max_size"><a href="#build-flag--experimental_disk_cache_gc_max_size">--experimental_disk_cache_gc_max_size</a>=<a size in bytes, optionally followed by a K, M, G or T multiplier></code> default: "0"</dt> +<dd> +<p>If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental_disk_cache_gc_max_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag.</p> +</dd> +<dt id="build-flag--experimental_extra_action_filter"><code id="experimental_extra_action_filter"><a href="#build-flag--experimental_extra_action_filter">--experimental_extra_action_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: ""</dt> +<dd> +<p>Deprecated in favor of aspects. Filters set of targets to schedule extra_actions for.</p> +</dd> +<dt id="build-flag--experimental_extra_action_top_level_only"><code id="experimental_extra_action_top_level_only"><a href="#build-flag--experimental_extra_action_top_level_only">--[no]experimental_extra_action_top_level_only</a></code> default: "false"</dt> +<dd> +<p>Deprecated in favor of aspects. Only schedules extra_actions for top level targets.</p> +</dd> +<dt id="build-flag--experimental_spawn_scheduler"><code id="experimental_spawn_scheduler"><a href="#build-flag--experimental_spawn_scheduler">--experimental_spawn_scheduler</a></code></dt> +<dd> +<p>Enable dynamic execution by running actions locally and remotely in parallel. Bazel spawns each action locally and remotely and picks the one that completes first. If an action supports workers, the local action will be run in the persistent worker mode. To enable dynamic execution for an individual action mnemonic, use the <code>--internal_spawn_scheduler</code> and <code>--strategy=&lt;mnemonic&gt;=dynamic</code> flags instead.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_spawn_scheduler">--internal_spawn_scheduler</a></code> +<br/>  <code><a href="#flag--spawn_strategy">--spawn_strategy=dynamic</a></code> +</p></dd> +<dt id="build-flag--fetch"><code id="fetch"><a href="#build-flag--fetch">--[no]fetch</a></code> default: "true"</dt> +<dd> +<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> +</dd> +<dt id="build-flag--local_termination_grace_seconds"><code id="local_termination_grace_seconds"><a href="#build-flag--local_termination_grace_seconds">--local_termination_grace_seconds</a>=<an integer></code> default: "15"</dt> +<dd> +<p>Time to wait between terminating a local process due to timeout and forcefully shutting it down.</p> +</dd> +<dt id="build-flag--package_path"><code id="package_path"><a href="#build-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> +<dd> +<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> +</dd> +<dt id="build-flag--show_loading_progress"><code id="show_loading_progress"><a href="#build-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> +<dd> +<p>If enabled, causes Bazel to print "Loading package:" messages.</p> +</dd> +<dt id="build-flag--test_lang_filters"><code id="test_lang_filters"><a href="#build-flag--test_lang_filters">--test_lang_filters</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>Specifies a comma-separated list of test languages. Each language can be optionally preceded with '-' to specify excluded languages. Only those test targets will be found that are written in the specified languages. The name used for each language should be the same as the language prefix in the *_test rule, e.g. one of 'cc', 'java', 'py', etc. This option affects --build_tests_only behavior and the test command.</p> +</dd> +<dt id="build-flag--test_size_filters"><code id="test_size_filters"><a href="#build-flag--test_size_filters">--test_size_filters</a>=<comma-separated list of values: small, medium, large, or enormous></code> default: ""</dt> +<dd> +<p>Specifies a comma-separated list of test sizes. Each size can be optionally preceded with '-' to specify excluded sizes. Only those test targets will be found that contain at least one included size and do not contain any excluded sizes. This option affects --build_tests_only behavior and the test command.</p> +</dd> +<dt id="build-flag--test_tag_filters"><code id="test_tag_filters"><a href="#build-flag--test_tag_filters">--test_tag_filters</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>Specifies a comma-separated list of test tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those test targets will be found that contain at least one included tag and do not contain any excluded tags. This option affects --build_tests_only behavior and the test command.</p> +</dd> +<dt id="build-flag--test_timeout_filters"><code id="test_timeout_filters"><a href="#build-flag--test_timeout_filters">--test_timeout_filters</a>=<comma-separated list of values: short, moderate, long, or eternal></code> default: ""</dt> +<dd> +<p>Specifies a comma-separated list of test timeouts. Each timeout can be optionally preceded with '-' to specify excluded timeouts. Only those test targets will be found that contain at least one included timeout and do not contain any excluded timeouts. This option affects --build_tests_only behavior and the test command.</p> +</dd> +<dt id="build-flag--workspace_status_command"><code id="workspace_status_command"><a href="#build-flag--workspace_status_command">--workspace_status_command</a>=<path></code> default: ""</dt> +<dd> +<p>A command invoked at the beginning of the build to provide status information about the workspace in the form of key/value pairs. See the User's Manual for the full specification. Also see tools/buildstamp/get_workspace_status for an example.</p> +</dd> +</dl> + +<dl>Options that control build execution: +<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> +<dd> +<p>Enable persistent aar extractor by using workers.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> +<dd> +<p>Whether to make source manifest actions remotable</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> +<dd> +<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> +<dd> +<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> +<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> +<p>Examples: +'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> +<dd> +<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> +<dd> +<p>If true, use the target platform for running tests rather than the test exec group.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The Android target compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> +<dd> +<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The C++ compiler to use for compiling the target.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> +<dd> +<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> +<dd> +<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> +<dd> +<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> +<dd> +<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> +<dd> +<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>No-op flag. Will be removed in a future release.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> +<dd> +<p>The label of a platform rule that describes the host system.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> +<dd> +<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> +<dd> +<p>Whether to emit a strip action as part of objc linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> +<dd> +<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> +<dd> +<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> +<dd> +<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> +<dd> +<p>The minimum OS version which your compilation targets.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> +<dd> +<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>The labels of the platform rules describing the target platforms for the current command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> +<dd> +<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> +<dd> +<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> +<dd> +<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> +<dd> +<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> +<dl>Options that control the output of the command: +<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> +<dd> +<p>Whether to generate debug symbol(.dSYM) file(s).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> +<dd> +<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> +<dd> +<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> +<dd> +<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> +<dd> +<p>Sets the suffixes of header files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> +<dd> +<p>Sets the suffixes of source files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> +<dd> +<p>Run extra actions for alternative Java api versions in a proto_library.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> +<dd> +<p>Save the state of enabled and requested feautres as an output of compilation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> +<dd> +<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> +<dd> +<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> +<dd> +<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>List of flags for which the use in select() is disabled.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> +<dd> +<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> +<dd> +<p>Specifies whether to generate a linkmap file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> +<dd> +<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>Allowed values for the --cpu flag.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> +<dd> +<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> +<dd> +<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> +<dd> +<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> +<dd> +<p>Build python executable zip; on on Windows, off on other platforms</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> +<dd> +<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> +<dd> +<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> +<dd> +<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for FDO will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> +<dd> +<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> +<dd> +<p>Compress Java resources in APKs</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> +<dd> +<p>use rex tool to rewrite dex files</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will also generate collect coverage information for generated files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> +<dd> +<p>Uses these strings as objc fastbuild compiler options.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> +<dd> +<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> +<dd> +<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> +<dd> +<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> +<dd> +<p>py_binary targets include their label even when stamping is disabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> +<dd> +<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> +<dd> +<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use cache prefetch hints.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The fdo_profile representing the profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> +<dd> +<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> +<dd> +<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>The host CPU.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to linker when linking tools in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> +<dd> +<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> +<dd> +<p>If true, the genfiles directory is folded into the bin directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> +<dd> +<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> +<dd> +<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> +<dd> +<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> +</p></dd> +<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use memprof profile.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> +<dd> +<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> +<dd> +<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> +<dd> +<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> +<dd> +<p>If true, native libraries that contain identical functionality will be shared among different targets</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> +<dd> +<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> +<dd> +<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> +<dd> +<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> +<dd> +<p>Whether to desugar Java 8 bytecode before dexing.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> +<dd> +<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> +<dd> +<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> +<dd> +<p>Whether to double-check correct desugaring at Android binary level.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> +<dd> +<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> +<dd> +<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> +<dd> +<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> +<dd> +<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> +<dd> +<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> +<dd> +<p>No-op. Kept here for backwards compatibility.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> +<dd> +<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> +<dd> +<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> +<dd> +<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Options that affect the signing outputs of a build: +<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> +<dd> +<p>Implementation to use to sign APKs</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> +<dd> +<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> +<dd> +<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> +<dd> +<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> +<dd> +<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> +<dd> +<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that govern the behavior of the test environment or test runner: +<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> +<dd> +<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> +<dd> +<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> +<dd> +<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> +<dd> +<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> +</dd> +<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> +<dd> +<p>Use dex2oat in parallel to possibly speed up android_test.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> +<dd> +<p>Enable checking for memory leaks in ios_test targets.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> +<dd> +<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> +</dd> +<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> +<dd> +<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> +</dd> +<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, undeclared test outputs will be archived in a zip file.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +</dl> +<dl>Options that trigger optimizations of the build time: +<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> +<dd> +<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> +<dd> +<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> +<dd> +<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> +<dd> +<p>Does most of the work for dexing separately for each Jar file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> +<dd> +<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> +<dd> +<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> +<dd> +<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> +<dd> +<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> +<dd> +<p>If enabled, visibility errors include additional diagnostic information.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> +<dd> +<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> +<dd> +<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> +<dd> +<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> +</dd> +<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> +<dd> +<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> +<dd> +<p>If true, coverage for clang will generate an LCOV report.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> +<dd> +<p>Enables reduced classpaths for Java compilations.</p> +</dd> +<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> +<dd> +<p>Whether to validate java_* sources.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> +<dd> +<p>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.</p> +</dd> +<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher used by tools that are executed during a build.</p> +</dd> +<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac when building tools that are executed during a build.</p> +</dd> +<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> +<dd> +<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> +<dd> +<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the J2ObjC tool.</p> +</dd> +<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> +<dd> +<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> +<p>Expands to: +<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> +<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> +<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> +<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> +<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> +</p></dd> +<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> +<dd> +<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> +</dd> +<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> +<dd> +<p>Compile ijars directly from source.</p> +</dd> +<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version</p> +</dd> +<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> +</dd> +<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> +<dd> +<p>The Java runtime version</p> +</dd> +<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac.</p> +</dd> +<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> +</dd> +<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to do dexing without sharding.</p> +</dd> +<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Plugins to use in the build. Currently works with java_plugin.</p> +</dd> +<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> +</dd> +<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> +<dd> +<p>The label of the proto-compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> +<dd> +<p>Whether to pass profile_path to the proto compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the protobuf compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> +<dd> +<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> +</dd> +<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> +<dd> +<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> +</dd> +<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> +</dd> +<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>This option is deprecated and has no effect.</p> +</dd> +<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> +<dd> +<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> +</dd> +<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> +<dd> +<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> +</dd> +<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version used to execute the tools that are needed during a build</p> +</dd> +<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> +<dd> +<p>The Java runtime version used to execute tools during the build</p> +</dd> +<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> +<dd> +<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> +</dd> +</dl> + +<h2><a name="canonicalize-flags">Canonicalize-flags Options</a></h2> +<p>Inherits all options from <a href="#build">build</a>.</p> + +<dl>Options that control the output of the command: +<dt id="canonicalize-flags-flag--canonicalize_policy"><code id="canonicalize_policy"><a href="#canonicalize-flags-flag--canonicalize_policy">--[no]canonicalize_policy</a></code> default: "false"</dt> +<dd> +<p>Output the canonical policy, after expansion and filtering. To keep the output clean, the canonicalized command arguments will NOT be shown when this option is set to true. Note that the command specified by --for_command affects the filtered policy, and if none is specified, the default command is 'build'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="canonicalize-flags-flag--experimental_include_default_values"><code id="experimental_include_default_values"><a href="#canonicalize-flags-flag--experimental_include_default_values">--[no]experimental_include_default_values</a></code> default: "true"</dt> +<dd> +<p>Whether Starlark options set to their default values are included in the output.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="canonicalize-flags-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#canonicalize-flags-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> +<dd> +<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="canonicalize-flags-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#canonicalize-flags-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> +<dd> +<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="canonicalize-flags-flag--for_command"><code id="for_command"><a href="#canonicalize-flags-flag--for_command">--for_command</a>=<a string></code> default: "build"</dt> +<dd> +<p>The command for which the options should be canonicalized.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="canonicalize-flags-flag--invocation_policy"><code id="invocation_policy"><a href="#canonicalize-flags-flag--invocation_policy">--invocation_policy</a>=<a string></code> default: ""</dt> +<dd> +<p>Applies an invocation policy to the options to be canonicalized.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="canonicalize-flags-flag--deleted_packages"><code id="deleted_packages"><a href="#canonicalize-flags-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> +<dd> +<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> +</dd> +<dt id="canonicalize-flags-flag--fetch"><code id="fetch"><a href="#canonicalize-flags-flag--fetch">--[no]fetch</a></code> default: "true"</dt> +<dd> +<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> +</dd> +<dt id="canonicalize-flags-flag--package_path"><code id="package_path"><a href="#canonicalize-flags-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> +<dd> +<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> +</dd> +<dt id="canonicalize-flags-flag--show_loading_progress"><code id="show_loading_progress"><a href="#canonicalize-flags-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> +<dd> +<p>If enabled, causes Bazel to print "Loading package:" messages.</p> +</dd> +</dl> + +<h2><a name="clean">Clean Options</a></h2> +<p>Inherits all options from <a href="#build">build</a>.</p> + +<dl>Options that control the output of the command: +<dt id="clean-flag--async"><code id="async"><a href="#clean-flag--async">--[no]async</a></code> default: "false"</dt> +<dd> +<p>If true, output cleaning is asynchronous. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="clean-flag--expunge"><code id="expunge"><a href="#clean-flag--expunge">--[no]expunge</a></code> default: "false"</dt> +<dd> +<p>If true, clean removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running.</p> +<p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +<dt id="clean-flag--expunge_async"><code id="expunge_async"><a href="#clean-flag--expunge_async">--expunge_async</a></code></dt> +<dd> +<p>If specified, clean asynchronously removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background.</p> +<p>Expands to: +<br/>  <code><a href="#flag--expunge">--expunge</a></code> +<br/>  <code><a href="#flag--async">--async</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> +</p></dd> +</dl> + +<h2><a name="config">Config Options</a></h2> +<h2><a name="coverage">Coverage Options</a></h2> +<p>Inherits all options from <a href="#test">test</a>.</p> + + +<h2><a name="cquery">Cquery Options</a></h2> +<p>Inherits all options from <a href="#test">test</a>.</p> + +<dl>Options relating to query output and semantics: +<dt id="cquery-flag--aspect_deps"><code id="aspect_deps"><a href="#cquery-flag--aspect_deps">--aspect_deps</a>=<off, conservative or precise></code> default: "conservative"</dt> +<dd> +<p>How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="cquery-flag--consistent_labels"><code id="consistent_labels"><a href="#cquery-flag--consistent_labels">--[no]consistent_labels</a></code> default: "false"</dt> +<dd> +<p>If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--experimental_explicit_aspects"><code id="experimental_explicit_aspects"><a href="#cquery-flag--experimental_explicit_aspects">--[no]experimental_explicit_aspects</a></code> default: "false"</dt> +<dd> +<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--graph:factored"><code id="graph:factored"><a href="#cquery-flag--graph:factored">--[no]graph:factored</a></code> default: "true"</dt> +<dd> +<p>If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--graph:node_limit"><code id="graph:node_limit"><a href="#cquery-flag--graph:node_limit">--graph:node_limit</a>=<an integer></code> default: "512"</dt> +<dd> +<p>The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--implicit_deps"><code id="implicit_deps"><a href="#cquery-flag--implicit_deps">--[no]implicit_deps</a></code> default: "true"</dt> +<dd> +<p>If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="cquery-flag--include_aspects"><code id="include_aspects"><a href="#cquery-flag--include_aspects">--[no]include_aspects</a></code> default: "true"</dt> +<dd> +<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--incompatible_package_group_includes_double_slash"><code id="incompatible_package_group_includes_double_slash"><a href="#cquery-flag--incompatible_package_group_includes_double_slash">--[no]incompatible_package_group_includes_double_slash</a></code> default: "true"</dt> +<dd> +<p>If enabled, when outputting package_group's <code>packages</code> attribute, the leading <code>//</code> will not be omitted.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="cquery-flag--infer_universe_scope"><code id="infer_universe_scope"><a href="#cquery-flag--infer_universe_scope">--[no]infer_universe_scope</a></code> default: "false"</dt> +<dd> +<p>If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.<code>allrdeps</code>) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to <code>query</code> (i.e. not <code>cquery</code>).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="cquery-flag--line_terminator_null"><code id="line_terminator_null"><a href="#cquery-flag--line_terminator_null">--[no]line_terminator_null</a></code> default: "false"</dt> +<dd> +<p>Whether each format is terminated with \0 instead of newline.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--nodep_deps"><code id="nodep_deps"><a href="#cquery-flag--nodep_deps">--[no]nodep_deps</a></code> default: "true"</dt> +<dd> +<p>If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of <code>info build-language</code> to learn about all the "nodep" attributes in the build language.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="cquery-flag--output"><code id="output"><a href="#cquery-flag--output">--output</a>=<a string></code> default: "label"</dt> +<dd> +<p>The format in which the cquery results should be printed. Allowed values for cquery are: label, label_kind, textproto, transitions, proto, streamed_proto, jsonproto. If you select 'transitions', you also have to specify the --transitions=(lite|full) option.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--output_file"><code id="output_file"><a href="#cquery-flag--output_file">--output_file</a>=<a string></code> default: ""</dt> +<dd> +<p>When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query &gt; file</code>.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:default_values"><code id="proto:default_values"><a href="#cquery-flag--proto:default_values">--[no]proto:default_values</a></code> default: "true"</dt> +<dd> +<p>If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:definition_stack"><code id="proto:definition_stack"><a href="#cquery-flag--proto:definition_stack">--[no]proto:definition_stack</a></code> default: "false"</dt> +<dd> +<p>Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:flatten_selects"><code id="proto:flatten_selects"><a href="#cquery-flag--proto:flatten_selects">--[no]proto:flatten_selects</a></code> default: "true"</dt> +<dd> +<p>If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="cquery-flag--proto:include_attribute_source_aspects"><code id="proto:include_attribute_source_aspects"><a href="#cquery-flag--proto:include_attribute_source_aspects">--[no]proto:include_attribute_source_aspects</a></code> default: "false"</dt> +<dd> +<p>Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:include_configurations"><code id="proto:include_configurations"><a href="#cquery-flag--proto:include_configurations">--[no]proto:include_configurations</a></code> default: "true"</dt> +<dd> +<p>if enabled, proto output will include information about configurations. When disabled,cquery proto output format resembles query output format.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="cquery-flag--proto:include_starlark_rule_env"><code id="proto:include_starlark_rule_env"><a href="#cquery-flag--proto:include_starlark_rule_env">--[no]proto:include_starlark_rule_env</a></code> default: "true"</dt> +<dd> +<p>Use the starlark environment in the value of the generated $internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:include_synthetic_attribute_hash"><code id="proto:include_synthetic_attribute_hash"><a href="#cquery-flag--proto:include_synthetic_attribute_hash">--[no]proto:include_synthetic_attribute_hash</a></code> default: "false"</dt> +<dd> +<p>Whether or not to calculate and populate the $internal_attr_hash attribute.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:instantiation_stack"><code id="proto:instantiation_stack"><a href="#cquery-flag--proto:instantiation_stack">--[no]proto:instantiation_stack</a></code> default: "false"</dt> +<dd> +<p>Populate the instantiation call stack of each rule. Note that this requires the stack to be present</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:locations"><code id="proto:locations"><a href="#cquery-flag--proto:locations">--[no]proto:locations</a></code> default: "true"</dt> +<dd> +<p>Whether to output location information in proto output at all.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:output_rule_attrs"><code id="proto:output_rule_attrs"><a href="#cquery-flag--proto:output_rule_attrs">--proto:output_rule_attrs</a>=<comma-separated list of options></code> default: "all"</dt> +<dd> +<p>Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:rule_classes"><code id="proto:rule_classes"><a href="#cquery-flag--proto:rule_classes">--[no]proto:rule_classes</a></code> default: "false"</dt> +<dd> +<p>Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--proto:rule_inputs_and_outputs"><code id="proto:rule_inputs_and_outputs"><a href="#cquery-flag--proto:rule_inputs_and_outputs">--[no]proto:rule_inputs_and_outputs</a></code> default: "true"</dt> +<dd> +<p>Whether or not to populate the rule_input and rule_output fields.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--query_file"><code id="query_file"><a href="#cquery-flag--query_file">--query_file</a>=<a string></code> default: ""</dt> +<dd> +<p>If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="cquery-flag--relative_locations"><code id="relative_locations"><a href="#cquery-flag--relative_locations">--[no]relative_locations</a></code> default: "false"</dt> +<dd> +<p>If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--show_config_fragments"><code id="show_config_fragments"><a href="#cquery-flag--show_config_fragments">--show_config_fragments</a>=<off, direct or transitive></code> default: "off"</dt> +<dd> +<p>Shows the configuration fragments required by a rule and its transitive dependencies. This can be useful for evaluating how much a configured target graph can be trimmed.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="cquery-flag--starlark:expr"><code id="starlark:expr"><a href="#cquery-flag--starlark:expr">--starlark:expr</a>=<a string></code> default: ""</dt> +<dd> +<p>A Starlark expression to format each configured target in cquery's --output=starlark mode. The configured target is bound to 'target'. If neither --starlark:expr nor --starlark:file is specified, this option will default to 'str(target.label)'. It is an error to specify both --starlark:expr and --starlark:file.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--starlark:file"><code id="starlark:file"><a href="#cquery-flag--starlark:file">--starlark:file</a>=<a string></code> default: ""</dt> +<dd> +<p>The name of a file that defines a Starlark function called 'format', of one argument, that is applied to each configured target to format it as a string. It is an error to specify both --starlark:expr and --starlark:file. See help for --output=starlark for additional detail.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="cquery-flag--tool_deps"><code id="tool_deps"><a href="#cquery-flag--tool_deps">--[no]tool_deps</a></code> default: "true"</dt> +<dd> +<p>Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="cquery-flag--transitions"><code id="transitions"><a href="#cquery-flag--transitions">--transitions</a>=<full, lite or none></code> default: "none"</dt> +<dd> +<p>The format in which cquery will print transition information.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="cquery-flag--universe_scope"><code id="universe_scope"><a href="#cquery-flag--universe_scope">--universe_scope</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> + +<dl>Options that control build execution: +<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> +<dd> +<p>Enable persistent aar extractor by using workers.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> +<dd> +<p>Whether to make source manifest actions remotable</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> +<dd> +<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> +<dd> +<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> +<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> +<p>Examples: +'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> +<dd> +<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> +<dd> +<p>If true, use the target platform for running tests rather than the test exec group.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The Android target compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> +<dd> +<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The C++ compiler to use for compiling the target.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> +<dd> +<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> +<dd> +<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> +<dd> +<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> +<dd> +<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> +<dd> +<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>No-op flag. Will be removed in a future release.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> +<dd> +<p>The label of a platform rule that describes the host system.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> +<dd> +<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> +<dd> +<p>Whether to emit a strip action as part of objc linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> +<dd> +<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> +<dd> +<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> +<dd> +<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> +<dd> +<p>The minimum OS version which your compilation targets.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> +<dd> +<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>The labels of the platform rules describing the target platforms for the current command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> +<dd> +<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> +<dd> +<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> +<dd> +<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> +<dd> +<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> +<dl>Options that control the output of the command: +<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> +<dd> +<p>Whether to generate debug symbol(.dSYM) file(s).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> +<dd> +<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> +<dd> +<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> +<dd> +<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> +<dd> +<p>Sets the suffixes of header files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> +<dd> +<p>Sets the suffixes of source files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> +<dd> +<p>Run extra actions for alternative Java api versions in a proto_library.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> +<dd> +<p>Save the state of enabled and requested feautres as an output of compilation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> +<dd> +<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> +<dd> +<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> +<dd> +<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>List of flags for which the use in select() is disabled.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> +<dd> +<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> +<dd> +<p>Specifies whether to generate a linkmap file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> +<dd> +<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>Allowed values for the --cpu flag.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> +<dd> +<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> +<dd> +<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> +<dd> +<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> +<dd> +<p>Build python executable zip; on on Windows, off on other platforms</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> +<dd> +<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> +<dd> +<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> +<dd> +<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for FDO will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> +<dd> +<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> +<dd> +<p>Compress Java resources in APKs</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> +<dd> +<p>use rex tool to rewrite dex files</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will also generate collect coverage information for generated files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> +<dd> +<p>Uses these strings as objc fastbuild compiler options.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> +<dd> +<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> +<dd> +<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> +<dd> +<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> +<dd> +<p>py_binary targets include their label even when stamping is disabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> +<dd> +<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> +<dd> +<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use cache prefetch hints.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The fdo_profile representing the profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> +<dd> +<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> +<dd> +<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>The host CPU.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to linker when linking tools in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> +<dd> +<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> +<dd> +<p>If true, the genfiles directory is folded into the bin directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> +<dd> +<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> +<dd> +<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> +<dd> +<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> +</p></dd> +<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use memprof profile.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> +<dd> +<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> +<dd> +<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> +<dd> +<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> +<dd> +<p>If true, native libraries that contain identical functionality will be shared among different targets</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> +<dd> +<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> +<dd> +<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> +<dd> +<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> +<dd> +<p>Whether to desugar Java 8 bytecode before dexing.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> +<dd> +<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> +<dd> +<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> +<dd> +<p>Whether to double-check correct desugaring at Android binary level.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> +<dd> +<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> +<dd> +<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> +<dd> +<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> +<dd> +<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> +<dd> +<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> +<dd> +<p>No-op. Kept here for backwards compatibility.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> +<dd> +<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> +<dd> +<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> +<dd> +<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Options that affect the signing outputs of a build: +<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> +<dd> +<p>Implementation to use to sign APKs</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> +<dd> +<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> +<dd> +<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> +<dd> +<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> +<dd> +<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> +<dd> +<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that govern the behavior of the test environment or test runner: +<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> +<dd> +<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> +<dd> +<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> +<dd> +<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> +<dd> +<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> +</dd> +<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> +<dd> +<p>Use dex2oat in parallel to possibly speed up android_test.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> +<dd> +<p>Enable checking for memory leaks in ios_test targets.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> +<dd> +<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> +</dd> +<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> +<dd> +<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> +</dd> +<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, undeclared test outputs will be archived in a zip file.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +</dl> +<dl>Options that trigger optimizations of the build time: +<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> +<dd> +<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> +<dd> +<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> +<dd> +<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> +<dd> +<p>Does most of the work for dexing separately for each Jar file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> +<dd> +<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> +<dd> +<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> +<dd> +<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> +<dd> +<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> +<dd> +<p>If enabled, visibility errors include additional diagnostic information.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> +<dd> +<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> +<dd> +<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> +<dd> +<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> +</dd> +<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> +<dd> +<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> +<dd> +<p>If true, coverage for clang will generate an LCOV report.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> +<dd> +<p>Enables reduced classpaths for Java compilations.</p> +</dd> +<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> +<dd> +<p>Whether to validate java_* sources.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> +<dd> +<p>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.</p> +</dd> +<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher used by tools that are executed during a build.</p> +</dd> +<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac when building tools that are executed during a build.</p> +</dd> +<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> +<dd> +<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> +<dd> +<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the J2ObjC tool.</p> +</dd> +<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> +<dd> +<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> +<p>Expands to: +<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> +<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> +<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> +<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> +<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> +</p></dd> +<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> +<dd> +<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> +</dd> +<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> +<dd> +<p>Compile ijars directly from source.</p> +</dd> +<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version</p> +</dd> +<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> +</dd> +<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> +<dd> +<p>The Java runtime version</p> +</dd> +<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac.</p> +</dd> +<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> +</dd> +<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to do dexing without sharding.</p> +</dd> +<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Plugins to use in the build. Currently works with java_plugin.</p> +</dd> +<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> +</dd> +<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> +<dd> +<p>The label of the proto-compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> +<dd> +<p>Whether to pass profile_path to the proto compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the protobuf compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> +<dd> +<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> +</dd> +<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> +<dd> +<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> +</dd> +<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> +</dd> +<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>This option is deprecated and has no effect.</p> +</dd> +<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> +<dd> +<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> +</dd> +<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> +<dd> +<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> +</dd> +<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version used to execute the tools that are needed during a build</p> +</dd> +<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> +<dd> +<p>The Java runtime version used to execute tools during the build</p> +</dd> +<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> +<dd> +<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> +</dd> +</dl> + +<h2><a name="dump">Dump Options</a></h2> +<dl>Options that control the output of the command: +<dt id="dump-flag--action_cache"><code id="action_cache"><a href="#dump-flag--action_cache">--[no]action_cache</a></code> default: "false"</dt> +<dd> +<p>Dump action cache content.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="dump-flag--memory"><code id="memory"><a href="#dump-flag--memory">--memory</a>=<memory mode></code> default: see description</dt> +<dd> +<p>Dump the memory use of the given Skyframe node.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="dump-flag--packages"><code id="packages"><a href="#dump-flag--packages">--[no]packages</a></code> default: "false"</dt> +<dd> +<p>Dump package cache content.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="dump-flag--rule_classes"><code id="rule_classes"><a href="#dump-flag--rule_classes">--[no]rule_classes</a></code> default: "false"</dt> +<dd> +<p>Dump rule classes.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="dump-flag--rules"><code id="rules"><a href="#dump-flag--rules">--[no]rules</a></code> default: "false"</dt> +<dd> +<p>Dump rules, including counts and memory usage (if memory is tracked).</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="dump-flag--skyframe"><code id="skyframe"><a href="#dump-flag--skyframe">--skyframe</a>=<off, summary, count, value, deps, rdeps, function_graph, active_directories or active_directories_frontier_deps></code> default: "off"</dt> +<dd> +<p>Dump the Skyframe graph.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="dump-flag--skykey_filter"><code id="skykey_filter"><a href="#dump-flag--skykey_filter">--skykey_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: ".*"</dt> +<dd> +<p>Regex filter of SkyKey names to output. Only used with --skyframe=deps, rdeps, function_graph.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +<dt id="dump-flag--skylark_memory"><code id="skylark_memory"><a href="#dump-flag--skylark_memory">--skylark_memory</a>=<a string></code> default: see description</dt> +<dd> +<p>Dumps a pprof-compatible memory profile to the specified path. To learn more please see https://github.com/google/pprof.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +</dl> + +<h2><a name="fetch">Fetch Options</a></h2> +<p>Inherits all options from <a href="#test">test</a>.</p> + +<dl>Options that control build execution: +<dt id="fetch-flag--all"><code id="all"><a href="#fetch-flag--all">--[no]all</a></code> default: "false"</dt> +<dd> +<p>Fetches all external repositories necessary for building any target or repository. This is the default if no other flags and arguments are provided. Only works when --enable_bzlmod is on.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="fetch-flag--keep_going"><code id="keep_going"><a href="#fetch-flag--keep_going">--[no]keep_going</a></code> [<code>-k</code>] default: "false"</dt> +<dd> +<p>Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="fetch-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#fetch-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> +<dd> +<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="fetch-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#fetch-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> +<dd> +<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="fetch-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#fetch-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> +<dd> +<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options relating to Bzlmod output and semantics: +<dt id="fetch-flag--configure"><code id="configure"><a href="#fetch-flag--configure">--[no]configure</a></code> default: "false"</dt> +<dd> +<p>Only fetches repositories marked as 'configure' for system-configuration purpose. Only works when --enable_bzlmod is on.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="fetch-flag--force"><code id="force"><a href="#fetch-flag--force">--[no]force</a></code> default: "false"</dt> +<dd> +<p>Ignore existing repository if any and force fetch the repository again. Only works when --enable_bzlmod is on.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="fetch-flag--repo"><code id="repo"><a href="#fetch-flag--repo">--repo</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Only fetches the specified repository, which can be either {@apparent_repo_name} or {@@canonical_repo_name}. Only works when --enable_bzlmod is on.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="fetch-flag--deleted_packages"><code id="deleted_packages"><a href="#fetch-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> +<dd> +<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> +</dd> +<dt id="fetch-flag--fetch"><code id="fetch"><a href="#fetch-flag--fetch">--[no]fetch</a></code> default: "true"</dt> +<dd> +<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> +</dd> +<dt id="fetch-flag--package_path"><code id="package_path"><a href="#fetch-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> +<dd> +<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> +</dd> +<dt id="fetch-flag--show_loading_progress"><code id="show_loading_progress"><a href="#fetch-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> +<dd> +<p>If enabled, causes Bazel to print "Loading package:" messages.</p> +</dd> +</dl> + +<dl>Options that control build execution: +<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> +<dd> +<p>Enable persistent aar extractor by using workers.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> +<dd> +<p>Whether to make source manifest actions remotable</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> +<dd> +<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> +<dd> +<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> +<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> +<p>Examples: +'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> +<dd> +<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> +<dd> +<p>If true, use the target platform for running tests rather than the test exec group.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The Android target compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> +<dd> +<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The C++ compiler to use for compiling the target.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> +<dd> +<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> +<dd> +<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> +<dd> +<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> +<dd> +<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> +<dd> +<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>No-op flag. Will be removed in a future release.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> +<dd> +<p>The label of a platform rule that describes the host system.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> +<dd> +<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> +<dd> +<p>Whether to emit a strip action as part of objc linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> +<dd> +<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> +<dd> +<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> +<dd> +<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> +<dd> +<p>The minimum OS version which your compilation targets.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> +<dd> +<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>The labels of the platform rules describing the target platforms for the current command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> +<dd> +<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> +<dd> +<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> +<dd> +<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> +<dd> +<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> +<dl>Options that control the output of the command: +<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> +<dd> +<p>Whether to generate debug symbol(.dSYM) file(s).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> +<dd> +<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> +<dd> +<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> +<dd> +<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> +<dd> +<p>Sets the suffixes of header files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> +<dd> +<p>Sets the suffixes of source files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> +<dd> +<p>Run extra actions for alternative Java api versions in a proto_library.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> +<dd> +<p>Save the state of enabled and requested feautres as an output of compilation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> +<dd> +<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> +<dd> +<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> +<dd> +<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>List of flags for which the use in select() is disabled.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> +<dd> +<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> +<dd> +<p>Specifies whether to generate a linkmap file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> +<dd> +<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>Allowed values for the --cpu flag.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> +<dd> +<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> +<dd> +<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> +<dd> +<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> +<dd> +<p>Build python executable zip; on on Windows, off on other platforms</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> +<dd> +<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> +<dd> +<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> +<dd> +<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for FDO will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> +<dd> +<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> +<dd> +<p>Compress Java resources in APKs</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> +<dd> +<p>use rex tool to rewrite dex files</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will also generate collect coverage information for generated files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> +<dd> +<p>Uses these strings as objc fastbuild compiler options.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> +<dd> +<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> +<dd> +<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> +<dd> +<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> +<dd> +<p>py_binary targets include their label even when stamping is disabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> +<dd> +<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> +<dd> +<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use cache prefetch hints.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The fdo_profile representing the profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> +<dd> +<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> +<dd> +<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>The host CPU.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to linker when linking tools in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> +<dd> +<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> +<dd> +<p>If true, the genfiles directory is folded into the bin directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> +<dd> +<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> +<dd> +<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> +<dd> +<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> +</p></dd> +<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use memprof profile.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> +<dd> +<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> +<dd> +<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> +<dd> +<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> +<dd> +<p>If true, native libraries that contain identical functionality will be shared among different targets</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> +<dd> +<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> +<dd> +<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> +<dd> +<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> +<dd> +<p>Whether to desugar Java 8 bytecode before dexing.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> +<dd> +<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> +<dd> +<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> +<dd> +<p>Whether to double-check correct desugaring at Android binary level.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> +<dd> +<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> +<dd> +<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> +<dd> +<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> +<dd> +<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> +<dd> +<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> +<dd> +<p>No-op. Kept here for backwards compatibility.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> +<dd> +<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> +<dd> +<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> +<dd> +<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Options that affect the signing outputs of a build: +<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> +<dd> +<p>Implementation to use to sign APKs</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> +<dd> +<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> +<dd> +<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> +<dd> +<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> +<dd> +<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> +<dd> +<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that govern the behavior of the test environment or test runner: +<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> +<dd> +<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> +<dd> +<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> +<dd> +<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> +<dd> +<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> +</dd> +<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> +<dd> +<p>Use dex2oat in parallel to possibly speed up android_test.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> +<dd> +<p>Enable checking for memory leaks in ios_test targets.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> +<dd> +<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> +</dd> +<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> +<dd> +<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> +</dd> +<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, undeclared test outputs will be archived in a zip file.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +</dl> +<dl>Options that trigger optimizations of the build time: +<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> +<dd> +<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> +<dd> +<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> +<dd> +<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> +<dd> +<p>Does most of the work for dexing separately for each Jar file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> +<dd> +<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> +<dd> +<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> +<dd> +<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> +<dd> +<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> +<dd> +<p>If enabled, visibility errors include additional diagnostic information.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> +<dd> +<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> +<dd> +<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> +<dd> +<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> +</dd> +<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> +<dd> +<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> +<dd> +<p>If true, coverage for clang will generate an LCOV report.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> +<dd> +<p>Enables reduced classpaths for Java compilations.</p> +</dd> +<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> +<dd> +<p>Whether to validate java_* sources.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> +<dd> +<p>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.</p> +</dd> +<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher used by tools that are executed during a build.</p> +</dd> +<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac when building tools that are executed during a build.</p> +</dd> +<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> +<dd> +<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> +<dd> +<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the J2ObjC tool.</p> +</dd> +<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> +<dd> +<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> +<p>Expands to: +<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> +<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> +<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> +<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> +<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> +</p></dd> +<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> +<dd> +<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> +</dd> +<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> +<dd> +<p>Compile ijars directly from source.</p> +</dd> +<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version</p> +</dd> +<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> +</dd> +<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> +<dd> +<p>The Java runtime version</p> +</dd> +<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac.</p> +</dd> +<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> +</dd> +<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to do dexing without sharding.</p> +</dd> +<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Plugins to use in the build. Currently works with java_plugin.</p> +</dd> +<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> +</dd> +<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> +<dd> +<p>The label of the proto-compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> +<dd> +<p>Whether to pass profile_path to the proto compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the protobuf compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> +<dd> +<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> +</dd> +<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> +<dd> +<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> +</dd> +<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> +</dd> +<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>This option is deprecated and has no effect.</p> +</dd> +<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> +<dd> +<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> +</dd> +<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> +<dd> +<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> +</dd> +<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version used to execute the tools that are needed during a build</p> +</dd> +<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> +<dd> +<p>The Java runtime version used to execute tools during the build</p> +</dd> +<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> +<dd> +<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> +</dd> +</dl> + +<h2><a name="help">Help Options</a></h2> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="help-flag--help_verbosity"><code id="help_verbosity"><a href="#help-flag--help_verbosity">--help_verbosity</a>=<long, medium or short></code> default: "medium"</dt> +<dd> +<p>Select the verbosity of the help command.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="help-flag--long"><code id="long"><a href="#help-flag--long">--long</a></code> [<code>-l</code>]</dt> +<dd> +<p>Show full description of each option, instead of just its name.</p> +<p>Expands to: +<br/>  <code><a href="#flag--help_verbosity">--help_verbosity=long</a></code> +</p><p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="help-flag--short"><code id="short"><a href="#help-flag--short">--short</a></code></dt> +<dd> +<p>Show only the names of the options, not their types or meanings.</p> +<p>Expands to: +<br/>  <code><a href="#flag--help_verbosity">--help_verbosity=short</a></code> +</p><p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +</dl> + +<h2><a name="info">Info Options</a></h2> +<p>Inherits all options from <a href="#build">build</a>.</p> + +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="info-flag--info_output_type"><code id="info_output_type"><a href="#info-flag--info_output_type">--info_output_type</a>=<stdout or response_proto></code> default: "stdout"</dt> +<dd> +<p>If stdout, results are directly printed to the console. If response_proto, the info command results are packed in response extensions.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="info-flag--show_make_env"><code id="show_make_env"><a href="#info-flag--show_make_env">--[no]show_make_env</a></code> default: "false"</dt> +<dd> +<p>Include the "Make" environment in the output.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +</dl> + +<h2><a name="license">License Options</a></h2> + +<h2><a name="mobile-install">Mobile-install Options</a></h2> +<p>Inherits all options from <a href="#build">build</a>.</p> + +<dl>Options that control build execution: +<dt id="mobile-install-flag--mode"><code id="mode"><a href="#mobile-install-flag--mode">--mode</a>=<classic, classic_internal_test_do_not_use or skylark></code> default: "skylark"</dt> +<dd> +<p>Deprecated no-effect flag. Only skylark mode is still supported.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="mobile-install-flag--adb"><code id="adb"><a href="#mobile-install-flag--adb">--adb</a>=<a string></code> default: ""</dt> +<dd> +<p>adb binary to use for the 'mobile-install' command. If unspecified, the one in the Android SDK specified by the --android_sdk_channel command line option (or the default SDK if --android_sdk_channel is not specified) is used.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Options that control the output of the command: +<dt id="mobile-install-flag--incremental"><code id="incremental"><a href="#mobile-install-flag--incremental">--[no]incremental</a></code> default: "false"</dt> +<dd> +<p>Whether to do an incremental install. If true, try to avoid unnecessary additional work by reading the state of the device the code is to be installed on and using that information to avoid unnecessary work. If false (the default), always do a full install.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="mobile-install-flag--split_apks"><code id="split_apks"><a href="#mobile-install-flag--split_apks">--[no]split_apks</a></code> default: "false"</dt> +<dd> +<p>Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="mobile-install-flag--adb_arg"><code id="adb_arg"><a href="#mobile-install-flag--adb_arg">--adb_arg</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Extra arguments to pass to adb. Usually used to designate a device to install to.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="mobile-install-flag--debug_app"><code id="debug_app"><a href="#mobile-install-flag--debug_app">--debug_app</a></code></dt> +<dd> +<p>Whether to wait for the debugger before starting the app.</p> +<p>Expands to: +<br/>  <code><a href="#flag--start">--start=DEBUG</a></code> +</p><p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="mobile-install-flag--device"><code id="device"><a href="#mobile-install-flag--device">--device</a>=<a string></code> default: ""</dt> +<dd> +<p>The adb device serial number. If not specified, the first device will be used.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="mobile-install-flag--start"><code id="start"><a href="#mobile-install-flag--start">--start</a>=<no, cold, warm or debug></code> default: "NO"</dt> +<dd> +<p>How the app should be started after installing it. Set to WARM to preserve and restore application state on incremental installs.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="mobile-install-flag--start_app"><code id="start_app"><a href="#mobile-install-flag--start_app">--start_app</a></code></dt> +<dd> +<p>Whether to start the app after installing it.</p> +<p>Expands to: +<br/>  <code><a href="#flag--start">--start=COLD</a></code> +</p><p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="mobile-install-flag--incremental_install_verbosity"><code id="incremental_install_verbosity"><a href="#mobile-install-flag--incremental_install_verbosity">--incremental_install_verbosity</a>=<a string></code> default: ""</dt> +<dd> +<p>The verbosity for incremental install. Set to 1 for debug logging.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> +</p></dd> +</dl> + +<h2><a name="mod">Mod Options</a></h2> +<dl>Options that control build execution: +<dt id="mod-flag--experimental_remotable_source_manifests"><code id="experimental_remotable_source_manifests"><a href="#mod-flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> +<dd> +<p>Whether to make source manifest actions remotable</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--experimental_strict_fileset_output"><code id="experimental_strict_fileset_output"><a href="#mod-flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--incompatible_modify_execution_info_additive"><code id="incompatible_modify_execution_info_additive"><a href="#mod-flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> +<dd> +<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="mod-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#mod-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> +<dd> +<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="mod-flag--modify_execution_info"><code id="modify_execution_info"><a href="#mod-flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> +<dd> +<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> +<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> +<p>Examples: +'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="mod-flag--use_target_platform_for_tests"><code id="use_target_platform_for_tests"><a href="#mod-flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> +<dd> +<p>If true, use the target platform for running tests rather than the test exec group.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="mod-flag--incompatible_bazel_test_exec_run_under"><code id="incompatible_bazel_test_exec_run_under"><a href="#mod-flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> +<dd> +<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that control the output of the command: +<dt id="mod-flag--build_runfile_links"><code id="build_runfile_links"><a href="#mod-flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> +<dd> +<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--build_runfile_manifests"><code id="build_runfile_manifests"><a href="#mod-flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> +<dd> +<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--incompatible_always_include_files_in_data"><code id="incompatible_always_include_files_in_data"><a href="#mod-flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> +<dd> +<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="mod-flag--incompatible_compact_repo_mapping_manifest"><code id="incompatible_compact_repo_mapping_manifest"><a href="#mod-flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> +<dd> +<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="mod-flag--incompatible_disable_select_on"><code id="incompatible_disable_select_on"><a href="#mod-flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>List of flags for which the use in select() is disabled.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="mod-flag--incompatible_filegroup_runfiles_for_data"><code id="incompatible_filegroup_runfiles_for_data"><a href="#mod-flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> +<dd> +<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="mod-flag--action_env"><code id="action_env"><a href="#mod-flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="mod-flag--allowed_cpu_values"><code id="allowed_cpu_values"><a href="#mod-flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>Allowed values for the --cpu flag.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--collect_code_coverage"><code id="collect_code_coverage"><a href="#mod-flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--compilation_mode"><code id="compilation_mode"><a href="#mod-flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> +<dd> +<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="mod-flag--cpu"><code id="cpu"><a href="#mod-flag--cpu">--cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--define"><code id="define"><a href="#mod-flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--enable_runfiles"><code id="enable_runfiles"><a href="#mod-flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> +<dd> +<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--exec_aspects"><code id="exec_aspects"><a href="#mod-flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="mod-flag--experimental_action_listener"><code id="experimental_action_listener"><a href="#mod-flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--experimental_collect_code_coverage_for_generated_files"><code id="experimental_collect_code_coverage_for_generated_files"><a href="#mod-flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will also generate collect coverage information for generated files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--experimental_output_paths"><code id="experimental_output_paths"><a href="#mod-flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> +<dd> +<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="mod-flag--experimental_override_platform_cpu_name"><code id="experimental_override_platform_cpu_name"><a href="#mod-flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--experimental_platform_in_output_dir"><code id="experimental_platform_in_output_dir"><a href="#mod-flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> +<dd> +<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code id="experimental_use_platforms_in_output_dir_legacy_heuristic"><a href="#mod-flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> +<dd> +<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--features"><code id="features"><a href="#mod-flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--host_action_env"><code id="host_action_env"><a href="#mod-flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="mod-flag--host_compilation_mode"><code id="host_compilation_mode"><a href="#mod-flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> +<dd> +<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="mod-flag--host_cpu"><code id="host_cpu"><a href="#mod-flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>The host CPU.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--host_features"><code id="host_features"><a href="#mod-flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--incompatible_auto_exec_groups"><code id="incompatible_auto_exec_groups"><a href="#mod-flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> +<dd> +<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="mod-flag--incompatible_merge_genfiles_directory"><code id="incompatible_merge_genfiles_directory"><a href="#mod-flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> +<dd> +<p>If true, the genfiles directory is folded into the bin directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="mod-flag--incompatible_target_cpu_from_platform"><code id="incompatible_target_cpu_from_platform"><a href="#mod-flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> +<dd> +<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="mod-flag--instrument_test_targets"><code id="instrument_test_targets"><a href="#mod-flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> +<dd> +<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--instrumentation_filter"><code id="instrumentation_filter"><a href="#mod-flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> +<dd> +<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="mod-flag--platform_suffix"><code id="platform_suffix"><a href="#mod-flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="mod-flag--run_under"><code id="run_under"><a href="#mod-flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> +<dd> +<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="mod-flag--stamp"><code id="stamp"><a href="#mod-flag--stamp">--[no]stamp</a></code> default: "false"</dt> +<dd> +<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="mod-flag--check_visibility"><code id="check_visibility"><a href="#mod-flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> +<dd> +<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="mod-flag--enforce_constraints"><code id="enforce_constraints"><a href="#mod-flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> +<dd> +<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="mod-flag--experimental_enforce_transitive_visibility"><code id="experimental_enforce_transitive_visibility"><a href="#mod-flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> +<dd> +<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--incompatible_check_testonly_for_output_files"><code id="incompatible_check_testonly_for_output_files"><a href="#mod-flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> +<dd> +<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="mod-flag--strict_filesets"><code id="strict_filesets"><a href="#mod-flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="mod-flag--target_environment"><code id="target_environment"><a href="#mod-flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="mod-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#mod-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> +<dd> +<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="mod-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#mod-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> +<dd> +<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that govern the behavior of the test environment or test runner: +<dt id="mod-flag--allow_analysis_failures"><code id="allow_analysis_failures"><a href="#mod-flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> +<dd> +<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="mod-flag--analysis_testing_deps_limit"><code id="analysis_testing_deps_limit"><a href="#mod-flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> +<dd> +<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> +<dl>Options relating to the output and semantics of the `mod` subcommand: +<dt id="mod-flag--base_module"><code id="base_module"><a href="#mod-flag--base_module">--base_module</a>=<"<root>" for the root module; <module>@<version> for a specific version of a module; <module> for all versions of a module; @<name> for a repo with the given apparent name; or @@<name> for a repo with the given canonical name></code> default: "<root>"</dt> +<dd> +<p>Specify a module relative to which the specified target repos will be interpreted.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--charset"><code id="charset"><a href="#mod-flag--charset">--charset</a>=<utf8 or ascii></code> default: "utf8"</dt> +<dd> +<p>Chooses the character set to use for the tree. Only affects text output. Valid values are "utf8" or "ascii". Default is "utf8"</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--cycles"><code id="cycles"><a href="#mod-flag--cycles">--[no]cycles</a></code> default: "true"</dt> +<dd> +<p>Points out dependency cycles inside the displayed tree.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--depth"><code id="depth"><a href="#mod-flag--depth">--depth</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>Maximum display depth of the dependency tree. A depth of 1 displays the direct dependencies, for example. For tree, path and all_paths it defaults to Integer.MAX_VALUE, while for deps and explain it defaults to 1 (only displays direct deps of the root besides the target leaves and their parents).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--extension_filter"><code id="extension_filter"><a href="#mod-flag--extension_filter">--extension_filter</a>=<a comma-separated list of <extension>s></code> default: see description</dt> +<dd> +<p>Only display the usages of these module extensions and the repos generated by them if their respective flags are set. If set, the result graph will only include paths that contain modules using the specified extensions. An empty list disables the filter, effectively specifying all possible extensions.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--extension_info"><code id="extension_info"><a href="#mod-flag--extension_info">--extension_info</a>=<hidden, usages, repos or all></code> default: "hidden"</dt> +<dd> +<p>Specify how much detail about extension usages to include in the query result. "Usages" will only show the extensions names, "repos" will also include repos imported with use_repo, and "all" will also show the other repositories generated by extensions.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--extension_usages"><code id="extension_usages"><a href="#mod-flag--extension_usages">--extension_usages</a>=<a comma-separated list of <module>s></code> default: ""</dt> +<dd> +<p>Specify modules whose extension usages will be displayed in the show_extension query.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--from"><code id="from"><a href="#mod-flag--from">--from</a>=<a comma-separated list of <module>s></code> default: "<root>"</dt> +<dd> +<p>The module(s) starting from which the dependency graph query will be displayed. Check each query’s description for the exact semantics. Defaults to <root>.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--include_builtin"><code id="include_builtin"><a href="#mod-flag--include_builtin">--[no]include_builtin</a></code> default: "false"</dt> +<dd> +<p>Include built-in modules in the dependency graph. Disabled by default because it is quite noisy.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--include_unused"><code id="include_unused"><a href="#mod-flag--include_unused">--[no]include_unused</a></code> default: "false"</dt> +<dd> +<p>The queries will also take into account and display the unused modules, which are not present in the module resolution graph after selection (due to the Minimal-Version Selection or override rules). This can have different effects for each of the query types i.e. include new paths in the all_paths command, or extra dependants in the explain command.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--output"><code id="output"><a href="#mod-flag--output">--output</a>=<text, json or graph></code> default: "text"</dt> +<dd> +<p>The format in which the query results should be printed. Allowed values for query are: text, json, graph</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="mod-flag--verbose"><code id="verbose"><a href="#mod-flag--verbose">--[no]verbose</a></code> default: "false"</dt> +<dd> +<p>The queries will also display the reason why modules were resolved to their current version (if changed). Defaults to true only for the explain query.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="mod-flag--verbose_visibility_errors"><code id="verbose_visibility_errors"><a href="#mod-flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> +<dd> +<p>If enabled, visibility errors include additional diagnostic information.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="mod-flag--flag_alias"><code id="flag_alias"><a href="#mod-flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> +<dd> +<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="mod-flag--deleted_packages"><code id="deleted_packages"><a href="#mod-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> +<dd> +<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> +</dd> +<dt id="mod-flag--fetch"><code id="fetch"><a href="#mod-flag--fetch">--[no]fetch</a></code> default: "true"</dt> +<dd> +<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> +</dd> +<dt id="mod-flag--package_path"><code id="package_path"><a href="#mod-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> +<dd> +<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> +</dd> +<dt id="mod-flag--show_loading_progress"><code id="show_loading_progress"><a href="#mod-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> +<dd> +<p>If enabled, causes Bazel to print "Loading package:" messages.</p> +</dd> +</dl> + +<h2><a name="print_action">Print_action Options</a></h2> +<p>Inherits all options from <a href="#build">build</a>.</p> + +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="print_action-flag--print_action_mnemonics"><code id="print_action_mnemonics"><a href="#print_action-flag--print_action_mnemonics">--print_action_mnemonics</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Lists which mnemonics to filter print_action data by, no filtering takes place when left empty.</p> +</dd> +</dl> + +<h2><a name="query">Query Options</a></h2> +<dl>Options that control build execution: +<dt id="query-flag--experimental_remotable_source_manifests"><code id="experimental_remotable_source_manifests"><a href="#query-flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> +<dd> +<p>Whether to make source manifest actions remotable</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--experimental_strict_fileset_output"><code id="experimental_strict_fileset_output"><a href="#query-flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--incompatible_modify_execution_info_additive"><code id="incompatible_modify_execution_info_additive"><a href="#query-flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> +<dd> +<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--keep_going"><code id="keep_going"><a href="#query-flag--keep_going">--[no]keep_going</a></code> [<code>-k</code>] default: "false"</dt> +<dd> +<p>Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="query-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#query-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> +<dd> +<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +<dt id="query-flag--modify_execution_info"><code id="modify_execution_info"><a href="#query-flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> +<dd> +<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> +<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> +<p>Examples: +'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="query-flag--use_target_platform_for_tests"><code id="use_target_platform_for_tests"><a href="#query-flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> +<dd> +<p>If true, use the target platform for running tests rather than the test exec group.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="query-flag--incompatible_bazel_test_exec_run_under"><code id="incompatible_bazel_test_exec_run_under"><a href="#query-flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> +<dd> +<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that control the output of the command: +<dt id="query-flag--build_runfile_links"><code id="build_runfile_links"><a href="#query-flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> +<dd> +<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--build_runfile_manifests"><code id="build_runfile_manifests"><a href="#query-flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> +<dd> +<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--incompatible_always_include_files_in_data"><code id="incompatible_always_include_files_in_data"><a href="#query-flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> +<dd> +<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--incompatible_compact_repo_mapping_manifest"><code id="incompatible_compact_repo_mapping_manifest"><a href="#query-flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> +<dd> +<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--incompatible_disable_select_on"><code id="incompatible_disable_select_on"><a href="#query-flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>List of flags for which the use in select() is disabled.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="query-flag--incompatible_filegroup_runfiles_for_data"><code id="incompatible_filegroup_runfiles_for_data"><a href="#query-flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> +<dd> +<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="query-flag--action_env"><code id="action_env"><a href="#query-flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="query-flag--allowed_cpu_values"><code id="allowed_cpu_values"><a href="#query-flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>Allowed values for the --cpu flag.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--collect_code_coverage"><code id="collect_code_coverage"><a href="#query-flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--compilation_mode"><code id="compilation_mode"><a href="#query-flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> +<dd> +<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="query-flag--cpu"><code id="cpu"><a href="#query-flag--cpu">--cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--define"><code id="define"><a href="#query-flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--enable_runfiles"><code id="enable_runfiles"><a href="#query-flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> +<dd> +<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--exec_aspects"><code id="exec_aspects"><a href="#query-flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="query-flag--experimental_action_listener"><code id="experimental_action_listener"><a href="#query-flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--experimental_collect_code_coverage_for_generated_files"><code id="experimental_collect_code_coverage_for_generated_files"><a href="#query-flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will also generate collect coverage information for generated files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--experimental_output_paths"><code id="experimental_output_paths"><a href="#query-flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> +<dd> +<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="query-flag--experimental_override_platform_cpu_name"><code id="experimental_override_platform_cpu_name"><a href="#query-flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--experimental_platform_in_output_dir"><code id="experimental_platform_in_output_dir"><a href="#query-flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> +<dd> +<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code id="experimental_use_platforms_in_output_dir_legacy_heuristic"><a href="#query-flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> +<dd> +<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--features"><code id="features"><a href="#query-flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--host_action_env"><code id="host_action_env"><a href="#query-flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="query-flag--host_compilation_mode"><code id="host_compilation_mode"><a href="#query-flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> +<dd> +<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="query-flag--host_cpu"><code id="host_cpu"><a href="#query-flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>The host CPU.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--host_features"><code id="host_features"><a href="#query-flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--incompatible_auto_exec_groups"><code id="incompatible_auto_exec_groups"><a href="#query-flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> +<dd> +<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--incompatible_merge_genfiles_directory"><code id="incompatible_merge_genfiles_directory"><a href="#query-flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> +<dd> +<p>If true, the genfiles directory is folded into the bin directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--incompatible_target_cpu_from_platform"><code id="incompatible_target_cpu_from_platform"><a href="#query-flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> +<dd> +<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--instrument_test_targets"><code id="instrument_test_targets"><a href="#query-flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> +<dd> +<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--instrumentation_filter"><code id="instrumentation_filter"><a href="#query-flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> +<dd> +<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="query-flag--platform_suffix"><code id="platform_suffix"><a href="#query-flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="query-flag--run_under"><code id="run_under"><a href="#query-flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> +<dd> +<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="query-flag--stamp"><code id="stamp"><a href="#query-flag--stamp">--[no]stamp</a></code> default: "false"</dt> +<dd> +<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="query-flag--check_visibility"><code id="check_visibility"><a href="#query-flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> +<dd> +<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="query-flag--enforce_constraints"><code id="enforce_constraints"><a href="#query-flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> +<dd> +<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="query-flag--experimental_enforce_transitive_visibility"><code id="experimental_enforce_transitive_visibility"><a href="#query-flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> +<dd> +<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--incompatible_check_testonly_for_output_files"><code id="incompatible_check_testonly_for_output_files"><a href="#query-flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> +<dd> +<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--strict_filesets"><code id="strict_filesets"><a href="#query-flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="query-flag--target_environment"><code id="target_environment"><a href="#query-flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="query-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#query-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> +<dd> +<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#query-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> +<dd> +<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that govern the behavior of the test environment or test runner: +<dt id="query-flag--allow_analysis_failures"><code id="allow_analysis_failures"><a href="#query-flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> +<dd> +<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="query-flag--analysis_testing_deps_limit"><code id="analysis_testing_deps_limit"><a href="#query-flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> +<dd> +<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> +<dl>Options relating to query output and semantics: +<dt id="query-flag--aspect_deps"><code id="aspect_deps"><a href="#query-flag--aspect_deps">--aspect_deps</a>=<off, conservative or precise></code> default: "conservative"</dt> +<dd> +<p>How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="query-flag--consistent_labels"><code id="consistent_labels"><a href="#query-flag--consistent_labels">--[no]consistent_labels</a></code> default: "false"</dt> +<dd> +<p>If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--experimental_explicit_aspects"><code id="experimental_explicit_aspects"><a href="#query-flag--experimental_explicit_aspects">--[no]experimental_explicit_aspects</a></code> default: "false"</dt> +<dd> +<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--experimental_graphless_query"><code id="experimental_graphless_query"><a href="#query-flag--experimental_graphless_query">--[no]experimental_graphless_query</a></code> default: "auto"</dt> +<dd> +<p>If true, uses a Query implementation that does not make a copy of the graph. The new implementation only supports --order_output=no, as well as only a subset of output formatters.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="query-flag--graph:conditional_edges_limit"><code id="graph:conditional_edges_limit"><a href="#query-flag--graph:conditional_edges_limit">--graph:conditional_edges_limit</a>=<an integer></code> default: "4"</dt> +<dd> +<p>The maximum number of condition labels to show. -1 means no truncation and 0 means no annotation. This option is only applicable to --output=graph.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--graph:factored"><code id="graph:factored"><a href="#query-flag--graph:factored">--[no]graph:factored</a></code> default: "true"</dt> +<dd> +<p>If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--graph:node_limit"><code id="graph:node_limit"><a href="#query-flag--graph:node_limit">--graph:node_limit</a>=<an integer></code> default: "512"</dt> +<dd> +<p>The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--implicit_deps"><code id="implicit_deps"><a href="#query-flag--implicit_deps">--[no]implicit_deps</a></code> default: "true"</dt> +<dd> +<p>If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="query-flag--include_aspects"><code id="include_aspects"><a href="#query-flag--include_aspects">--[no]include_aspects</a></code> default: "true"</dt> +<dd> +<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--incompatible_lexicographical_output"><code id="incompatible_lexicographical_output"><a href="#query-flag--incompatible_lexicographical_output">--[no]incompatible_lexicographical_output</a></code> default: "true"</dt> +<dd> +<p>If this option is set, sorts --order_output=auto output in lexicographical order.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--incompatible_package_group_includes_double_slash"><code id="incompatible_package_group_includes_double_slash"><a href="#query-flag--incompatible_package_group_includes_double_slash">--[no]incompatible_package_group_includes_double_slash</a></code> default: "true"</dt> +<dd> +<p>If enabled, when outputting package_group's <code>packages</code> attribute, the leading <code>//</code> will not be omitted.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="query-flag--infer_universe_scope"><code id="infer_universe_scope"><a href="#query-flag--infer_universe_scope">--[no]infer_universe_scope</a></code> default: "false"</dt> +<dd> +<p>If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.<code>allrdeps</code>) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to <code>query</code> (i.e. not <code>cquery</code>).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="query-flag--line_terminator_null"><code id="line_terminator_null"><a href="#query-flag--line_terminator_null">--[no]line_terminator_null</a></code> default: "false"</dt> +<dd> +<p>Whether each format is terminated with \0 instead of newline.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--nodep_deps"><code id="nodep_deps"><a href="#query-flag--nodep_deps">--[no]nodep_deps</a></code> default: "true"</dt> +<dd> +<p>If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of <code>info build-language</code> to learn about all the "nodep" attributes in the build language.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="query-flag--noorder_results"><code id="noorder_results"><a href="#query-flag--noorder_results">--noorder_results</a></code></dt> +<dd> +<p>Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph.</p> +<p>Expands to: +<br/>  <code><a href="#flag--order_output">--order_output=no</a></code> +</p><p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--null"><code id="null"><a href="#query-flag--null">--null</a></code></dt> +<dd> +<p>Whether each format is terminated with \0 instead of newline.</p> +<p>Expands to: +<br/>  <code><a href="#flag--line_terminator_null">--line_terminator_null=true</a></code> +</p><p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--order_output"><code id="order_output"><a href="#query-flag--order_output">--order_output</a>=<no, deps, auto or full></code> default: "auto"</dt> +<dd> +<p>Output the results unordered (no), dependency-ordered (deps), or fully ordered (full). The default is 'auto', meaning that results are output either dependency-ordered or fully ordered, depending on the output formatter (dependency-ordered for proto, minrank, maxrank, and graph, fully ordered for all others). When output is fully ordered, nodes are printed in a fully deterministic (total) order. First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a post-order depth-first search in which outgoing edges to unvisited nodes are traversed in alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order in which they were visited.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--order_results"><code id="order_results"><a href="#query-flag--order_results">--order_results</a></code></dt> +<dd> +<p>Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph.</p> +<p>Expands to: +<br/>  <code><a href="#flag--order_output">--order_output=auto</a></code> +</p><p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--output"><code id="output"><a href="#query-flag--output">--output</a>=<a string></code> default: "label"</dt> +<dd> +<p>The format in which the query results should be printed. Allowed values for query are: build, graph, streamed_jsonproto, label, label_kind, location, maxrank, minrank, package, proto, streamed_proto, xml.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--output_file"><code id="output_file"><a href="#query-flag--output_file">--output_file</a>=<a string></code> default: ""</dt> +<dd> +<p>When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query &gt; file</code>.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:default_values"><code id="proto:default_values"><a href="#query-flag--proto:default_values">--[no]proto:default_values</a></code> default: "true"</dt> +<dd> +<p>If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:definition_stack"><code id="proto:definition_stack"><a href="#query-flag--proto:definition_stack">--[no]proto:definition_stack</a></code> default: "false"</dt> +<dd> +<p>Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:flatten_selects"><code id="proto:flatten_selects"><a href="#query-flag--proto:flatten_selects">--[no]proto:flatten_selects</a></code> default: "true"</dt> +<dd> +<p>If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="query-flag--proto:include_attribute_source_aspects"><code id="proto:include_attribute_source_aspects"><a href="#query-flag--proto:include_attribute_source_aspects">--[no]proto:include_attribute_source_aspects</a></code> default: "false"</dt> +<dd> +<p>Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not).</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:include_starlark_rule_env"><code id="proto:include_starlark_rule_env"><a href="#query-flag--proto:include_starlark_rule_env">--[no]proto:include_starlark_rule_env</a></code> default: "true"</dt> +<dd> +<p>Use the starlark environment in the value of the generated $internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:include_synthetic_attribute_hash"><code id="proto:include_synthetic_attribute_hash"><a href="#query-flag--proto:include_synthetic_attribute_hash">--[no]proto:include_synthetic_attribute_hash</a></code> default: "false"</dt> +<dd> +<p>Whether or not to calculate and populate the $internal_attr_hash attribute.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:instantiation_stack"><code id="proto:instantiation_stack"><a href="#query-flag--proto:instantiation_stack">--[no]proto:instantiation_stack</a></code> default: "false"</dt> +<dd> +<p>Populate the instantiation call stack of each rule. Note that this requires the stack to be present</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:locations"><code id="proto:locations"><a href="#query-flag--proto:locations">--[no]proto:locations</a></code> default: "true"</dt> +<dd> +<p>Whether to output location information in proto output at all.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:output_rule_attrs"><code id="proto:output_rule_attrs"><a href="#query-flag--proto:output_rule_attrs">--proto:output_rule_attrs</a>=<comma-separated list of options></code> default: "all"</dt> +<dd> +<p>Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:rule_classes"><code id="proto:rule_classes"><a href="#query-flag--proto:rule_classes">--[no]proto:rule_classes</a></code> default: "false"</dt> +<dd> +<p>Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--proto:rule_inputs_and_outputs"><code id="proto:rule_inputs_and_outputs"><a href="#query-flag--proto:rule_inputs_and_outputs">--[no]proto:rule_inputs_and_outputs</a></code> default: "true"</dt> +<dd> +<p>Whether or not to populate the rule_input and rule_output fields.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--query_file"><code id="query_file"><a href="#query-flag--query_file">--query_file</a>=<a string></code> default: ""</dt> +<dd> +<p>If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="query-flag--relative_locations"><code id="relative_locations"><a href="#query-flag--relative_locations">--[no]relative_locations</a></code> default: "false"</dt> +<dd> +<p>If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--strict_test_suite"><code id="strict_test_suite"><a href="#query-flag--strict_test_suite">--[no]strict_test_suite</a></code> default: "false"</dt> +<dd> +<p>If true, the tests() expression gives an error if it encounters a test_suite containing non-test targets.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="query-flag--tool_deps"><code id="tool_deps"><a href="#query-flag--tool_deps">--[no]tool_deps</a></code> default: "true"</dt> +<dd> +<p>Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="query-flag--universe_scope"><code id="universe_scope"><a href="#query-flag--universe_scope">--universe_scope</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="query-flag--xml:default_values"><code id="xml:default_values"><a href="#query-flag--xml:default_values">--[no]xml:default_values</a></code> default: "false"</dt> +<dd> +<p>If true, rule attributes whose value is not explicitly specified in the BUILD file are printed; otherwise they are omitted.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="query-flag--xml:line_numbers"><code id="xml:line_numbers"><a href="#query-flag--xml:line_numbers">--[no]xml:line_numbers</a></code> default: "true"</dt> +<dd> +<p>If true, XML output contains line numbers. Disabling this option may make diffs easier to read. This option is only applicable to --output=xml.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="query-flag--verbose_visibility_errors"><code id="verbose_visibility_errors"><a href="#query-flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> +<dd> +<p>If enabled, visibility errors include additional diagnostic information.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="query-flag--flag_alias"><code id="flag_alias"><a href="#query-flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> +<dd> +<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="query-flag--deleted_packages"><code id="deleted_packages"><a href="#query-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> +<dd> +<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> +</dd> +<dt id="query-flag--fetch"><code id="fetch"><a href="#query-flag--fetch">--[no]fetch</a></code> default: "true"</dt> +<dd> +<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> +</dd> +<dt id="query-flag--package_path"><code id="package_path"><a href="#query-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> +<dd> +<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> +</dd> +<dt id="query-flag--show_loading_progress"><code id="show_loading_progress"><a href="#query-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> +<dd> +<p>If enabled, causes Bazel to print "Loading package:" messages.</p> +</dd> +</dl> + +<h2><a name="run">Run Options</a></h2> +<p>Inherits all options from <a href="#build">build</a>.</p> + +<dl>Options that appear before the command and are parsed by the client: +<dt id="run-flag--portable_paths"><code id="portable_paths"><a href="#run-flag--portable_paths">--[no]portable_paths</a></code> default: "false"</dt> +<dd> +<p>If true, includes paths to replace in ExecRequest to make the resulting paths portable.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="run-flag--run"><code id="run"><a href="#run-flag--run">--[no]run</a></code> default: "true"</dt> +<dd> +<p>If false, skip running the command line constructed for the built target. Note that this flag is ignored for all --script_path builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="run-flag--run_env"><code id="run_env"><a href="#run-flag--run_env">--run_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to the target to run. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. Note that the executed target will generally see the full environment of the host except for those variables that have been explicitly unset.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="run-flag--script_path"><code id="script_path"><a href="#run-flag--script_path">--script_path</a>=<a path></code> default: see description</dt> +<dd> +<p>If set, write a shell script to the given file which invokes the target. If this option is set, the target is not run from bazel. Use 'bazel run --script_path=foo //foo && ./foo' to invoke target '//foo' This differs from 'bazel run //foo' in that the bazel lock is released and the executable is connected to the terminal's stdin.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> + +<h2><a name="shutdown">Shutdown Options</a></h2> +<dl>Options that control the output of the command: +<dt id="shutdown-flag--iff_heap_size_greater_than"><code id="iff_heap_size_greater_than"><a href="#shutdown-flag--iff_heap_size_greater_than">--iff_heap_size_greater_than</a>=<an integer></code> default: "0"</dt> +<dd> +<p>Iff non-zero, then shutdown will only shut down the server if the total memory (in MB) consumed by the JVM exceeds this value.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +</dl> + +<h2><a name="test">Test Options</a></h2> +<p>Inherits all options from <a href="#build">build</a>.</p> + +<dl>Options that affect the verbosity, format or location of logging: +<dt id="test-flag--print_relative_test_log_paths"><code id="print_relative_test_log_paths"><a href="#test-flag--print_relative_test_log_paths">--[no]print_relative_test_log_paths</a></code> default: "false"</dt> +<dd> +<p>If true, when printing the path to a test log, use relative path that makes use of the 'testlogs' convenience symlink. N.B. - A subsequent 'build'/'test'/etc invocation with a different configuration can cause the target of this symlink to change, making the path printed previously no longer useful.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="test-flag--test_verbose_timeout_warnings"><code id="test_verbose_timeout_warnings"><a href="#test-flag--test_verbose_timeout_warnings">--[no]test_verbose_timeout_warnings</a></code> default: "false"</dt> +<dd> +<p>If true, print additional warnings when the actual test execution time does not match the timeout defined by the test (whether implied or explicit).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="test-flag--verbose_test_summary"><code id="verbose_test_summary"><a href="#test-flag--verbose_test_summary">--[no]verbose_test_summary</a></code> default: "true"</dt> +<dd> +<p>If true, print additional information (timing, number of failed runs, etc) in the test summary.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> + +<h2><a name="vendor">Vendor Options</a></h2> +<p>Inherits all options from <a href="#test">test</a>.</p> + +<dl>Options that control build execution: +<dt id="vendor-flag--keep_going"><code id="keep_going"><a href="#vendor-flag--keep_going">--[no]keep_going</a></code> [<code>-k</code>] default: "false"</dt> +<dd> +<p>Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="vendor-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#vendor-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> +<dd> +<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> +<p>Tags: +<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="vendor-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#vendor-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> +<dd> +<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="vendor-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#vendor-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> +<dd> +<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options relating to Bzlmod output and semantics: +<dt id="vendor-flag--repo"><code id="repo"><a href="#vendor-flag--repo">--repo</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Only vendors the specified repository, which can be either <code>@apparent_repo_name</code> or <code>@@canonical_repo_name</code>. This option can be set multiple times</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="vendor-flag--deleted_packages"><code id="deleted_packages"><a href="#vendor-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> +<dd> +<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> +</dd> +<dt id="vendor-flag--fetch"><code id="fetch"><a href="#vendor-flag--fetch">--[no]fetch</a></code> default: "true"</dt> +<dd> +<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> +</dd> +<dt id="vendor-flag--package_path"><code id="package_path"><a href="#vendor-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> +<dd> +<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> +</dd> +<dt id="vendor-flag--show_loading_progress"><code id="show_loading_progress"><a href="#vendor-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> +<dd> +<p>If enabled, causes Bazel to print "Loading package:" messages.</p> +</dd> +</dl> + +<dl>Options that control build execution: +<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> +<dd> +<p>Enable persistent aar extractor by using workers.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> +<dd> +<p>Whether to make source manifest actions remotable</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> +<dd> +<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> +<dd> +<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> +<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> +<p>Examples: +'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> +<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> +<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> +<dd> +<p>Enable persistent multiplexed Android resource processor by using workers.</p> +<p>Expands to: +<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> +<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> +<dd> +<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> +<p>Expands to: +<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> +<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> +</p><p>Tags: +<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> +<dd> +<p>If true, use the target platform for running tests rather than the test exec group.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> +<dl>Options that configure the toolchain used for action execution: +<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The Android target compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> +<dd> +<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>The C++ compiler to use for compiling the target.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> +<dd> +<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> +<dd> +<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> +<dd> +<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> +<dd> +<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> +<dd> +<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> +<dd> +<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> +<dd> +<p>No-op flag. Will be removed in a future release.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> +<dd> +<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> +<dd> +<p>The label of a platform rule that describes the host system.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> +<dd> +<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> +<dd> +<p>Whether to emit a strip action as part of objc linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> +<dd> +<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> +<dd> +<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> +<dd> +<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> +<dd> +<p>The minimum OS version which your compilation targets.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> +<dd> +<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> +<dd> +<p>The labels of the platform rules describing the target platforms for the current command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> +<dd> +<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> +<dd> +<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> +<dd> +<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> +<dd> +<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +</dl> +<dl>Options that control the output of the command: +<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> +<dd> +<p>Whether to generate debug symbol(.dSYM) file(s).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> +<dd> +<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> +<dd> +<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> +<dd> +<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> +<dd> +<p>Sets the suffixes of header files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> +<dd> +<p>Sets the suffixes of source files that a cc_proto_library creates.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> +<dd> +<p>Run extra actions for alternative Java api versions in a proto_library.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> +<dd> +<p>Save the state of enabled and requested feautres as an output of compilation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> +<dd> +<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> +<dd> +<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> +<dd> +<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>List of flags for which the use in select() is disabled.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> +<dd> +<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> +<dd> +<p>Specifies whether to generate a linkmap file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> +<dd> +<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> +<dd> +<p>Allowed values for the --cpu flag.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> +<dd> +<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> +<dd> +<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> +<dd> +<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> +<dd> +<p>Build python executable zip; on on Windows, off on other platforms</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> +<dd> +<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> +<dd> +<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when compiling C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> +<dd> +<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> +<dd> +<p>If set, any use of absolute paths for FDO will raise an error.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> +<dd> +<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> +<dd> +<p>Compress Java resources in APKs</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> +<dd> +<p>Use android databinding v2. This flag is a no-op.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> +<dd> +<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> +<dd> +<p>use rex tool to rewrite dex files</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will also generate collect coverage information for generated files.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> +<dd> +<p>Uses these strings as objc fastbuild compiler options.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> +<dd> +<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> +<dd> +<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> +<dd> +<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> +<dd> +<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> +<dd> +<p>py_binary targets include their label even when stamping is disabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> +<dd> +<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> +<dd> +<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> +<dd> +<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> +<dd> +<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use cache prefetch hints.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The fdo_profile representing the profile to be used for optimization.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> +<dd> +<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> +<dd> +<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> +<dd> +<p>The host CPU.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to linker when linking tools in the exec configurations.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> +<dd> +<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> +<dd> +<p>If true, the genfiles directory is folded into the bin directory.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> +<dd> +<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> +<dd> +<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> +<dd> +<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> +<dd> +<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> +</p></dd> +<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to gcc when linking.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use memprof profile.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> +<dd> +<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> +<dd> +<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a suffix to be added to the configuration directory.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> +<dd> +<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> +<dd> +<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> +<dd> +<p>If true, native libraries that contain identical functionality will be shared among different targets</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> +<dd> +<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> +<dd> +<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> +<p>Tags: +<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +</dl> +<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> +<dd> +<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> +<dd> +<p>Whether to desugar Java 8 bytecode before dexing.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> +<dd> +<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> +<dd> +<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> +</p></dd> +<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> +<dd> +<p>Whether to double-check correct desugaring at Android binary level.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> +<dd> +<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> +<dd> +<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> +<dd> +<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> +<dd> +<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> +<dd> +<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> +<dd> +<p>No-op. Kept here for backwards compatibility.</p> +<p>Tags: +<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> +<dd> +<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> +<dd> +<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> +<dd> +<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> +<dd> +<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> +<dd> +<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> +</p></dd> +<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +</dl> +<dl>Options that affect the signing outputs of a build: +<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> +<dd> +<p>Implementation to use to sign APKs</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> +<dd> +<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> +</p></dd> +<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> +<dd> +<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +</dl> +<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> +<dd> +<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> +<dd> +<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> +<dd> +<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Options that govern the behavior of the test environment or test runner: +<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> +<dd> +<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> +<dd> +<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> +<dd> +<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> +<dd> +<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> +</dd> +<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> +<dd> +<p>Use dex2oat in parallel to possibly speed up android_test.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> +<dd> +<p>Enable checking for memory leaks in ios_test targets.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> +</p></dd> +<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> +<dd> +<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> +<dd> +<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> +</dd> +<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> +<dd> +<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> +</dd> +<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, undeclared test outputs will be archived in a zip file.</p> +<p>Tags: +<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> +</p></dd> +</dl> +<dl>Options that trigger optimizations of the build time: +<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> +<dd> +<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> +<p>Tags: +<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> +<dd> +<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> +<dd> +<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> +<dd> +<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> +<dd> +<p>Does most of the work for dexing separately for each Jar file.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> +<dd> +<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> +<dd> +<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> +<p>Tags: +<a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> +<dd> +<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> +</p></dd> +</dl> +<dl>Options that affect the verbosity, format or location of logging: +<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> +<dd> +<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> +<p>Tags: +<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> +</p></dd> +<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> +<dd> +<p>If enabled, visibility errors include additional diagnostic information.</p> +<p>Tags: +<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +</dl> +<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> +<dd> +<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> +<p>Tags: +<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> +</p></dd> +<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> +<dd> +<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +</dl> +<dl>Miscellaneous options, not otherwise categorized.: +<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> +<dd> +<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> +</dd> +<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> +<dd> +<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> +<dd> +<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> +<dd> +<p>If true, coverage for clang will generate an LCOV report.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> +<dd> +<p>Enables reduced classpaths for Java compilations.</p> +</dd> +<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> +<dd> +<p>Whether to validate java_* sources.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> +</p></dd> +<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> +<dd> +<p>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.</p> +</dd> +<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher used by tools that are executed during a build.</p> +</dd> +<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac when building tools that are executed during a build.</p> +</dd> +<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> +<dd> +<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> +<dd> +<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> +<p>Tags: +<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> +<dd> +<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> +</p></dd> +<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the J2ObjC tool.</p> +</dd> +<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> +<dd> +<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> +<p>Expands to: +<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> +<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> +<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> +<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> +<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> +</p></dd> +<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> +<dd> +<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> +</dd> +<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> +<dd> +<p>Compile ijars directly from source.</p> +</dd> +<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version</p> +</dd> +<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> +</dd> +<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> +<dd> +<p>The Java runtime version</p> +</dd> +<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to javac.</p> +</dd> +<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> +</dd> +<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> +</dd> +<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies a binary to use to do dexing without sharding.</p> +</dd> +<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> +<dd> +<p>Plugins to use in the build. Currently works with java_plugin.</p> +</dd> +<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> +<dd> +<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> +</dd> +<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> +<dd> +<p>The label of the proto-compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> +<dd> +<p>Whether to pass profile_path to the proto compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> +<dd> +<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> +<dd> +<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Additional options to pass to the protobuf compiler.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> +</p></dd> +<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> +<dd> +<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> +</dd> +<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> +<dd> +<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> +<p>Tags: +<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> +</p></dd> +<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> +<dd> +<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> +</dd> +<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> +<dd> +<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> +</dd> +<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> +<dd> +<p>This option is deprecated and has no effect.</p> +</dd> +<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> +<dd> +<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> +</dd> +<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> +<dd> +<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> +</dd> +<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> +<dd> +<p>The Java language version used to execute the tools that are needed during a build</p> +</dd> +<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> +<dd> +<p>The Java runtime version used to execute tools during the build</p> +</dd> +<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> +<dd> +<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> +</dd> +</dl> + +<h2><a name="version">Version Options</a></h2> +<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: +<dt id="version-flag--gnu_format"><code id="gnu_format"><a href="#version-flag--gnu_format">--[no]gnu_format</a></code> default: "false"</dt> +<dd> +<p>If set, write the version to stdout using the conventions described in the GNU standards.</p> +<p>Tags: +<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> +</p></dd> +</dl> + +<h3>Option Effect Tags</h3> +<table> +<tr> +<td id="effect_tag_UNKNOWN"><code>unknown</code></td> +<td>This option has unknown, or undocumented, effect.</td> +</tr> +<tr> +<td id="effect_tag_NO_OP"><code>no_op</code></td> +<td>This option has literally no effect.</td> +</tr> +<tr> +<td id="effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></td> +<td>Changing the value of this option can cause significant loss of incremental state, which slows builds. State could be lost due to a server restart or to invalidation of a large part of the dependency graph.</td> +</tr> +<tr> +<td id="effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></td> +<td>This option actively changes the inputs that bazel considers for the build, such as filesystem restrictions, repository versions, or other options.</td> +</tr> +<tr> +<td id="effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></td> +<td>This option affects bazel's outputs. This tag is intentionally broad, can include transitive affects, and does not specify the type of output it affects.</td> +</tr> +<tr> +<td id="effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></td> +<td>This option affects the semantics of BUILD or .bzl files.</td> +</tr> +<tr> +<td id="effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></td> +<td>This option affects settings of bazel-internal machinery. This tag does not, on its own, mean that build artifacts are affected.</td> +</tr> +<tr> +<td id="effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></td> +<td>This option affects the loading and analysis of dependencies, and the building of the dependency graph.</td> +</tr> +<tr> +<td id="effect_tag_EXECUTION"><code>execution</code></td> +<td>This option affects the execution phase, such as sandboxing or remote execution related options.</td> +</tr> +<tr> +<td id="effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></td> +<td>This option triggers an optimization that may be machine specific and is not guaranteed to work on all machines. The optimization could include a tradeoff with other aspects of performance, such as memory or cpu cost.</td> +</tr> +<tr> +<td id="effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></td> +<td>This option changes how eagerly bazel will exit from a failure, where a choice between continuing despite the failure and ending the invocation exists.</td> +</tr> +<tr> +<td id="effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></td> +<td>This option is used to monitor bazel's behavior and performance.</td> +</tr> +<tr> +<td id="effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></td> +<td>This option affects bazel's terminal output.</td> +</tr> +<tr> +<td id="effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></td> +<td>This option changes the command line arguments of one or more build actions.</td> +</tr> +<tr> +<td id="effect_tag_TEST_RUNNER"><code>test_runner</code></td> +<td>This option changes the testrunner environment of the build.</td> +</tr> +</table> +<h3>Option Metadata Tags</h3> +<table> +<tr> +<td id="metadata_tag_EXPERIMENTAL"><code>experimental</code></td> +<td>This option triggers an experimental feature with no guarantees of functionality.</td> +</tr> +<tr> +<td id="metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></td> +<td>This option triggers a breaking change. Use this option to test your migration readiness or get early access to the new feature</td> +</tr> +<tr> +<td id="metadata_tag_DEPRECATED"><code>deprecated</code></td> +<td>This option is deprecated. It might be that the feature it affects is deprecated, or that another method of supplying the information is preferred.</td> +</tr> +<tr> +<td id="metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></td> +<td>This option cannot be changed in a transition or be used in a select() statement.</td> +</tr> +</table> + +<br/><br/><br/><br/> +</body> +</html> diff --git a/rules/lib/builtins.mdx b/rules/lib/builtins.mdx new file mode 100644 index 0000000..5878e15 --- /dev/null +++ b/rules/lib/builtins.mdx @@ -0,0 +1,140 @@ +--- +title: 'builtins' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> +<h1 class="page-title">Built-in Types</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +This section lists types of Starlark objects. With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. + +<ul> + +<li><a href="/rules/lib/builtins/Action">Action</a></li> + +<li><a href="/rules/lib/builtins/actions">actions</a></li> + +<li><a href="/rules/lib/builtins/apple_platform">apple_platform</a></li> + +<li><a href="/rules/lib/builtins/Args">Args</a></li> + +<li><a href="/rules/lib/builtins/Aspect">Aspect</a></li> + +<li><a href="/rules/lib/builtins/Attribute">Attribute</a></li> + +<li><a href="/rules/lib/builtins/bazel_module">bazel_module</a></li> + +<li><a href="/rules/lib/builtins/bazel_module_tags">bazel_module_tags</a></li> + +<li><a href="/rules/lib/builtins/BuildSetting">BuildSetting</a></li> + +<li><a href="/rules/lib/builtins/CcCompilationOutputs">CcCompilationOutputs</a></li> + +<li><a href="/rules/lib/builtins/CcLinkingOutputs">CcLinkingOutputs</a></li> + +<li><a href="/rules/lib/builtins/CompilationContext">CompilationContext</a></li> + +<li><a href="/rules/lib/builtins/configuration">configuration</a></li> + +<li><a href="/rules/lib/builtins/ctx">ctx</a></li> + +<li><a href="/rules/lib/builtins/depset">depset</a></li> + +<li><a href="/rules/lib/builtins/DirectoryExpander">DirectoryExpander</a></li> + +<li><a href="/rules/lib/builtins/DottedVersion">DottedVersion</a></li> + +<li><a href="/rules/lib/builtins/exec_result">exec_result</a></li> + +<li><a href="/rules/lib/builtins/ExecGroupCollection">ExecGroupCollection</a></li> + +<li><a href="/rules/lib/builtins/ExecGroupContext">ExecGroupContext</a></li> + +<li><a href="/rules/lib/builtins/ExecTransitionFactory">ExecTransitionFactory</a></li> + +<li><a href="/rules/lib/builtins/ExpandedDirectory">ExpandedDirectory</a></li> + +<li><a href="/rules/lib/builtins/extension_metadata">extension_metadata</a></li> + +<li><a href="/rules/lib/builtins/FeatureConfiguration">FeatureConfiguration</a></li> + +<li><a href="/rules/lib/builtins/File">File</a></li> + +<li><a href="/rules/lib/builtins/fragments">fragments</a></li> + +<li><a href="/rules/lib/builtins/java_annotation_processing">java_annotation_processing</a></li> + +<li><a href="/rules/lib/builtins/Label">Label</a></li> + +<li><a href="/rules/lib/builtins/LateBoundDefault">LateBoundDefault</a></li> + +<li><a href="/rules/lib/builtins/LibraryToLink">LibraryToLink</a></li> + +<li><a href="/rules/lib/builtins/License">License</a></li> + +<li><a href="/rules/lib/builtins/LinkerInput">LinkerInput</a></li> + +<li><a href="/rules/lib/builtins/LinkingContext">LinkingContext</a></li> + +<li><a href="/rules/lib/builtins/macro">macro</a></li> + +<li><a href="/rules/lib/builtins/mapped_root">mapped_root</a></li> + +<li><a href="/rules/lib/builtins/module_ctx">module_ctx</a></li> + +<li><a href="/rules/lib/builtins/path">path</a></li> + +<li><a href="/rules/lib/builtins/propagation_ctx">propagation_ctx</a></li> + +<li><a href="/rules/lib/builtins/Provider">Provider</a></li> + +<li><a href="/rules/lib/builtins/repo_metadata">repo_metadata</a></li> + +<li><a href="/rules/lib/builtins/repository_ctx">repository_ctx</a></li> + +<li><a href="/rules/lib/builtins/repository_os">repository_os</a></li> + +<li><a href="/rules/lib/builtins/repository_rule">repository_rule</a></li> + +<li><a href="/rules/lib/builtins/root">root</a></li> + +<li><a href="/rules/lib/builtins/rule">rule</a></li> + +<li><a href="/rules/lib/builtins/rule_attributes">rule_attributes</a></li> + +<li><a href="/rules/lib/builtins/runfiles">runfiles</a></li> + +<li><a href="/rules/lib/builtins/struct">struct</a></li> + +<li><a href="/rules/lib/builtins/Subrule">Subrule</a></li> + +<li><a href="/rules/lib/builtins/subrule_ctx">subrule_ctx</a></li> + +<li><a href="/rules/lib/builtins/SymlinkEntry">SymlinkEntry</a></li> + +<li><a href="/rules/lib/builtins/tag_class">tag_class</a></li> + +<li><a href="/rules/lib/builtins/Target">Target</a></li> + +<li><a href="/rules/lib/builtins/template_ctx">template_ctx</a></li> + +<li><a href="/rules/lib/builtins/TemplateDict">TemplateDict</a></li> + +<li><a href="/rules/lib/builtins/toolchain_type">toolchain_type</a></li> + +<li><a href="/rules/lib/builtins/ToolchainContext">ToolchainContext</a></li> + +<li><a href="/rules/lib/builtins/transition">transition</a></li> + +<li><a href="/rules/lib/builtins/wasm_exec_result">wasm_exec_result</a></li> + +<li><a href="/rules/lib/builtins/wasm_module">wasm_module</a></li> +</ul> +</body> +</html> diff --git a/rules/lib/builtins/Action.mdx b/rules/lib/builtins/Action.mdx new file mode 100644 index 0000000..9683390 --- /dev/null +++ b/rules/lib/builtins/Action.mdx @@ -0,0 +1,96 @@ +--- +title: 'Action' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.Action">Action</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +An action created during rule analysis.<p>This object is visible for the purpose of testing, and may be obtained from an <code>Actions</code> provider. It is normally not necessary to access <code>Action</code> objects or their fields within a rule's implementation function. You may instead want to see the <a href='https://bazel.build/extending/rules#actions'>Rules page</a> for a general discussion of how to use actions when defining custom rules, or the <a href='../builtins/actions.html'>API reference</a> for creating actions.<p>Some fields of this object are only applicable for certain kinds of actions. Fields that are inapplicable are set to <code>None</code>. + +<h2>Members</h2> +<ul> + <li> + <a href="#args">args</a> + </li> + <li> + <a href="#argv">argv</a> + </li> + <li> + <a href="#content">content</a> + </li> + <li> + <a href="#env">env</a> + </li> + <li> + <a href="#inputs">inputs</a> + </li> + <li> + <a href="#mnemonic">mnemonic</a> + </li> + <li> + <a href="#outputs">outputs</a> + </li> + <li> + <a href="#substitutions">substitutions</a> + </li> + </ul> + + <h2 id="args">args</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> Action.args</pre></p> + + A list of frozen <a href="../builtins/Args.html">Args</a> objects containing information about the action arguments. These objects contain accurate argument information, including arguments involving expanded action output directories. However, <a href="../builtins/Args.html">Args</a> objects are not readable in the analysis phase. For a less accurate account of arguments which is available in the analysis phase, see <a href="#argv">argv</a>. <p>Note that some types of actions do not yet support exposure of this field. For such action types, this is <code>None</code>. + May return <code>None</code>. + + <h2 id="argv">argv</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> Action.argv</pre></p> + + For actions created by <a href="../builtins/actions.html#run">ctx.actions.run()</a> or <a href="../builtins/actions.html#run_shell">ctx.actions.run_shell()</a> an immutable list of the arguments for the command line to be executed. Note that for shell actions the first two arguments will be the shell path and <code>"-c"</code>. + May return <code>None</code>. + + <h2 id="content">content</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Action.content</pre></p> + + For actions created by <a href="../builtins/actions.html#write">ctx.actions.write()</a> or <a href="../builtins/actions.html#expand_template">ctx.actions.expand_template()</a>, the contents of the file to be written, if those contents can be computed during the analysis phase. The value is <code>None</code> if the contents cannot be determined until the execution phase, such as when a directory in an <a href="../builtins/Args.html">Args</a> object needs to be expanded. + May return <code>None</code>. + + <h2 id="env">env</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> Action.env</pre></p> + + The 'fixed' environment variables for this action. This includes only environment settings which are explicitly set by the action definition, and thus omits settings which are only pre-set in the execution environment. + + <h2 id="inputs">inputs</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> Action.inputs</pre></p> + + A set of the input files of this action. + + <h2 id="mnemonic">mnemonic</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Action.mnemonic</pre></p> + + The mnemonic for this action. + + <h2 id="outputs">outputs</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> Action.outputs</pre></p> + + A set of the output files of this action. + + <h2 id="substitutions">substitutions</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> Action.substitutions</pre></p> + + For actions created by <a href="../builtins/actions.html#expand_template">ctx.actions.expand_template()</a>, an immutable dict holding the substitution mapping. + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/Args.mdx b/rules/lib/builtins/Args.mdx new file mode 100644 index 0000000..452f141 --- /dev/null +++ b/rules/lib/builtins/Args.mdx @@ -0,0 +1,423 @@ +--- +title: 'Args' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.Args">Args</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +An object that encapsulates, in a memory-efficient way, the data needed to build part or all of a command line.<p>It often happens that an action requires a large command line containing values accumulated from transitive dependencies. For example, a linker command line might list every object file needed by all of the libraries being linked. It is best practice to store such transitive data in <a href='../builtins/depset.html'><code>depset</code></a>s, so that they can be shared by multiple targets. However, if the rule author had to convert these depsets into lists of strings in order to construct an action command line, it would defeat this memory-sharing optimization.<p>For this reason, the action-constructing functions accept <code>Args</code> objects in addition to strings. Each <code>Args</code> object represents a concatenation of strings and depsets, with optional transformations for manipulating the data. <code>Args</code> objects do not process the depsets they encapsulate until the execution phase, when it comes time to calculate the command line. This helps defer any expensive copying until after the analysis phase is complete. See the <a href='https://bazel.build/rules/performance'>Optimizing Performance</a> page for more information.<p><code>Args</code> are constructed by calling <a href='../builtins/actions.html#args'><code>ctx.actions.args()</code></a>. They can be passed as the <code>arguments</code> parameter of <a href='../builtins/actions.html#run'><code>ctx.actions.run()</code></a> or <a href='../builtins/actions.html#run_shell'><code>ctx.actions.run_shell()</code></a>. Each mutation of an <code>Args</code> object appends values to the eventual command line.<p>The <code>map_each</code> feature allows you to customize how items are transformed into strings. If you do not provide a <code>map_each</code> function, the standard conversion is as follows: <ul><li>Values that are already strings are left as-is.<li><a href='../builtins/File.html'><code>File</code></a> objects are turned into their <code>File.path</code> values.<li><a href='../builtins/Label.html'><code>Label</code></a> objects are turned into a string representation that resolves back to the same object when resolved in the context of the main repository. If possible, the string representation uses the apparent name of a repository in favor of the repository's canonical name, which makes this representation suited for use in BUILD files. While the exact form of the representation is not guaranteed, typical examples are <code>//foo:bar</code>, <code>@repo//foo:bar</code> and <code>@@canonical_name+//foo:bar.bzl</code>.<li>All other types are turned into strings in an <i>unspecified</i> manner. For this reason, you should avoid passing values that are not of string or <code>File</code> type to <code>add()</code>, and if you pass them to <code>add_all()</code> or <code>add_joined()</code> then you should provide a <code>map_each</code> function.</ul><p>When using string formatting (<code>format</code>, <code>format_each</code>, and <code>format_joined</code> params of the <code>add*()</code> methods), the format template is interpreted in the same way as <code>%</code>-substitution on strings, except that the template must have exactly one substitution placeholder and it must be <code>%s</code>. Literal percents may be escaped as <code>%%</code>. Formatting is applied after the value is converted to a string as per the above.<p>Each of the <code>add*()</code> methods have an alternate form that accepts an extra positional parameter, an "arg name" string to insert before the rest of the arguments. For <code>add_all</code> and <code>add_joined</code> the extra string will not be added if the sequence turns out to be empty. For instance, the same usage can add either <code>--foo val1 val2 val3 --bar</code> or just <code>--bar</code> to the command line, depending on whether the given sequence contains <code>val1..val3</code> or is empty.<p>If the size of the command line can grow longer than the maximum size allowed by the system, the arguments can be spilled over into parameter files. See <a href='#use_param_file'><code>use_param_file()</code></a> and <a href='#set_param_file_format'><code>set_param_file_format()</code></a>.<p>Example: Suppose we wanted to generate the command line: <pre> +--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz +</pre>We could use the following <code>Args</code> object: <pre class=language-python> +# foo_deps and bar_deps are depsets containing +# File objects for the foo and bar .txt files. +args = ctx.actions.args() +args.add_all("--foo", foo_deps) +args.add_joined("--bar", bar_deps, join_with=",") +args.add("--baz") +ctx.actions.run( + ... + arguments = [args], + ... +) +</pre> + +<h2>Members</h2> +<ul> + <li> + <a href="#add">add</a> + </li> + <li> + <a href="#add_all">add_all</a> + </li> + <li> + <a href="#add_joined">add_joined</a> + </li> + <li> + <a href="#set_param_file_format">set_param_file_format</a> + </li> + <li> + <a href="#use_param_file">use_param_file</a> + </li> + </ul> + + <h2 id="add">add</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.add(arg_name_or_value, value=unbound, *, format=None)</pre></p> + + Appends an argument to this command line. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="add.arg_name_or_value"> + <code>arg_name_or_value</code> + </td> + <td> + required<br/> + If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the value without any processing. If only one positional parameter is passed, it is interpreted as <code>value</code> (see below). + </td> + </tr> + <tr> + <td id="add.value"> + <code>value</code> + </td> + <td> + default is <code>unbound</code><br/> + The object to append. It will be converted to a string using the standard conversion mentioned above. Since there is no <code>map_each</code> parameter for this function, <code>value</code> should be either a string or a <code>File</code>. A list, tuple, depset, or directory <code>File</code> must be passed to <a href='#add_all'><code>add_all()</code> or <a href='#add_joined'><code>add_joined()</code></a> instead of this method. + </td> + </tr> + <tr> + <td id="add.format"> + <code>format</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A format string pattern, to be applied to the stringified version of <code>value</code>. + </td> + </tr> + </tbody> + </table> + + <h2 id="add_all">add_all</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)</pre></p> + + Appends multiple arguments to this command line. The items are processed lazily during the execution phase.<p>Most of the processing occurs over a list of arguments to be appended, as per the following steps:<ol><li>Each directory <code>File</code> item is replaced by all <code>File</code>s recursively contained in that directory.</li><li>If <code>map_each</code> is given, it is applied to each item, and the resulting lists of strings are concatenated to form the initial argument list. Otherwise, the initial argument list is the result of applying the standard conversion to each item.<li>Each argument in the list is formatted with <code>format_each</code>, if present.<li>If <code>uniquify</code> is true, duplicate arguments are removed. The first occurrence is the one that remains.<li>If a <code>before_each</code> string is given, it is inserted as a new argument before each existing argument in the list. This effectively doubles the number of arguments to be appended by this point.<li>Except in the case that the list is empty and <code>omit_if_empty</code> is true (the default), the arg name and <code>terminate_with</code> are inserted as the first and last arguments, respectively, if they are given.</ol>Note that empty strings are valid arguments that are subject to all these processing steps. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="add_all.arg_name_or_values"> + <code>arg_name_or_values</code> + </td> + <td> + required<br/> + If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the <code>values</code> as a separate argument without any processing. This arg name will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below). + </td> + </tr> + <tr> + <td id="add_all.values"> + <code>values</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>unbound</code><br/> + The list, tuple, or depset whose items will be appended. + </td> + </tr> + <tr> + <td id="add_all.map_each"> + <code>map_each</code> + </td> + <td> + callable; or <code>None</code>; + default is <code>None</code><br/> + A function that converts each item to zero or more strings, which may be further processed before appending. If this param is not provided, the standard conversion is used.<p>The function is passed either one or two positional arguments: the item to convert, followed by an optional <a href='../builtins/DirectoryExpander.html'><code>DirectoryExpander</code></a>. The second argument will be passed only if the supplied function is user-defined (not built-in) and declares more than one parameter.<p>The return value's type depends on how many arguments are to be produced for the item:<ul><li>In the common case when each item turns into one string, the function should return that string.<li>If the item is to be filtered out entirely, the function should return <code>None</code>.<li>If the item turns into multiple strings, the function returns a list of those strings.</ul>Returning a single string or <code>None</code> has the same effect as returning a list of length 1 or length 0 respectively. However, it is more efficient and readable to avoid creating a list where it is not needed.<p>Ordinarily, items that are directories are automatically expanded to their contents when <code>expand_directories=True</code> is set. However, this will not expand directories contained inside other values -- for instance, when the items are structs that have directories as fields. In this situation, the <code>DirectoryExpander</code> argument can be applied to manually obtain the files of a given directory.<p>To avoid unintended retention of large analysis-phase data structures into the execution phase, the <code>map_each</code> function must be declared by a top-level <code>def</code> statement; it may not be a nested function closure by default.<p><i>Warning:</i> <a href='../globals/all.html#print'><code>print()</code></a> statements that are executed during the call to <code>map_each</code> will not produce any visible output. + </td> + </tr> + <tr> + <td id="add_all.format_each"> + <code>format_each</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + An optional format string pattern, applied to each string returned by the <code>map_each</code> function. The format string must have exactly one '%s' placeholder. + </td> + </tr> + <tr> + <td id="add_all.before_each"> + <code>before_each</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + An optional argument to append before each argument derived from <code>values</code> is appended. + </td> + </tr> + <tr> + <td id="add_all.omit_if_empty"> + <code>omit_if_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + If true, if there are no arguments derived from <code>values</code> to be appended, then all further processing is suppressed and the command line will be unchanged. If false, the arg name and <code>terminate_with</code>, if provided, will still be appended regardless of whether or not there are other arguments. + </td> + </tr> + <tr> + <td id="add_all.uniquify"> + <code>uniquify</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, duplicate arguments that are derived from <code>values</code> will be omitted. Only the first occurrence of each argument will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items. + </td> + </tr> + <tr> + <td id="add_all.expand_directories"> + <code>expand_directories</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + If true, any directories in <code>values</code> will be expanded to a flat list of files. This happens before <code>map_each</code> is applied. + </td> + </tr> + <tr> + <td id="add_all.terminate_with"> + <code>terminate_with</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + An optional argument to append after all other arguments. This argument will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered). + </td> + </tr> + <tr> + <td id="add_all.allow_closure"> + <code>allow_closure</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. + </td> + </tr> + </tbody> + </table> + + <h2 id="add_joined">add_joined</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)</pre></p> + + Appends an argument to this command line by concatenating together multiple values using a separator. The items are processed lazily during the execution phase.<p>Processing is similar to <a href='#add_all'><code>add_all()</code></a>, but the list of arguments derived from <code>values</code> is combined into a single argument as if by <code>join_with.join(...)</code>, and then formatted using the given <code>format_joined</code> string template. Unlike <code>add_all()</code>, there is no <code>before_each</code> or <code>terminate_with</code> parameter since these are not generally useful when the items are combined into a single argument.<p>If after filtering there are no strings to join into an argument, and if <code>omit_if_empty</code> is true (the default), no processing is done. Otherwise if there are no strings to join but <code>omit_if_empty</code> is false, the joined string will be an empty string. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="add_joined.arg_name_or_values"> + <code>arg_name_or_values</code> + </td> + <td> + required<br/> + If two positional parameters are passed this is interpreted as the arg name. The arg name is added before <code>values</code> without any processing. This arg will not be added if <code>omit_if_empty</code> is true (the default) and there are no strings derived from <code>values</code> to join together (which can happen if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below). + </td> + </tr> + <tr> + <td id="add_joined.values"> + <code>values</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>unbound</code><br/> + The list, tuple, or depset whose items will be joined. + </td> + </tr> + <tr> + <td id="add_joined.join_with"> + <code>join_with</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A delimiter string used to join together the strings obtained from applying <code>map_each</code> and <code>format_each</code>, in the same manner as <a href='../core/string.html#join'><code>string.join()</code></a>. + </td> + </tr> + <tr> + <td id="add_joined.map_each"> + <code>map_each</code> + </td> + <td> + callable; or <code>None</code>; + default is <code>None</code><br/> + Same as for <a href='#add_all.map_each'><code>add_all</code></a>. + </td> + </tr> + <tr> + <td id="add_joined.format_each"> + <code>format_each</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Same as for <a href='#add_all.format_each'><code>add_all</code></a>. + </td> + </tr> + <tr> + <td id="add_joined.format_joined"> + <code>format_joined</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. + </td> + </tr> + <tr> + <td id="add_joined.omit_if_empty"> + <code>omit_if_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + If true, if there are no strings to join together (either because <code>values</code> is empty or all its items are filtered), then all further processing is suppressed and the command line will be unchanged. If false, then even if there are no strings to join together, two arguments will be appended: the arg name followed by an empty string (which is the logical join of zero strings). + </td> + </tr> + <tr> + <td id="add_joined.uniquify"> + <code>uniquify</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Same as for <a href='#add_all.uniquify'><code>add_all</code></a>. + </td> + </tr> + <tr> + <td id="add_joined.expand_directories"> + <code>expand_directories</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + Same as for <a href='#add_all.expand_directories'><code>add_all</code></a>. + </td> + </tr> + <tr> + <td id="add_joined.allow_closure"> + <code>allow_closure</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Same as for <a href='#add_all.allow_closure'><code>add_all</code></a>. + </td> + </tr> + </tbody> + </table> + + <h2 id="set_param_file_format">set_param_file_format</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.set_param_file_format(format)</pre></p> + + Sets the format of the param file, if one is used + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="set_param_file_format.format"> + <code>format</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Must be one of:<ul><li>"multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it.</li><li>"shell": Same as "multiline", but the items are shell-quoted</li><li>"flag_per_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library.</li></ul><p>The format defaults to "shell" if not called. + </td> + </tr> + </tbody> + </table> + + <h2 id="use_param_file">use_param_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.use_param_file(param_file_arg, *, use_always=False)</pre></p> + + Spills the args to a params file, replacing them with a pointer to the param file. Use when your args may be too large for the system's command length limits.<p>Bazel may choose to elide writing the params file to the output tree during execution for efficiency. If you are debugging actions and want to inspect the param file, pass <code>--materialize_param_files</code> to your build. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="use_param_file.param_file_arg"> + <code>param_file_arg</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A format string with a single "%s". If the args are spilled to a params file then they are replaced with an argument consisting of this string formatted with the path of the params file.<p>For example, if the args are spilled to a params file "params.txt", then specifying "--file=%s" would cause the action command line to contain "--file=params.txt". + </td> + </tr> + <tr> + <td id="use_param_file.use_always"> + <code>use_always</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether to always spill the args to a params file. If false, bazel will decide whether the arguments need to be spilled based on your system and arg length. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/Aspect.mdx b/rules/lib/builtins/Aspect.mdx new file mode 100644 index 0000000..84fc178 --- /dev/null +++ b/rules/lib/builtins/Aspect.mdx @@ -0,0 +1,27 @@ +--- +title: 'Aspect' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.Aspect">Aspect</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +For more information about Aspects, please consult the +<a href="../globals/bzl.html#aspect">documentation of the aspect function</a> or the <a href="https://bazel.build/extending/aspects">introduction to Aspects</a>. + + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/Attribute.mdx b/rules/lib/builtins/Attribute.mdx new file mode 100644 index 0000000..f1bfab9 --- /dev/null +++ b/rules/lib/builtins/Attribute.mdx @@ -0,0 +1,25 @@ +--- +title: 'Attribute' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.Attribute">Attribute</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Representation of a definition of an attribute. Use the <a href="../toplevel/attr.html">attr</a> module to create an Attribute. They are only for use with a <a href="../globals/bzl.html#rule">rule</a> or an <a href="../globals/bzl.html#aspect">aspect</a>. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/BuildSetting.mdx b/rules/lib/builtins/BuildSetting.mdx new file mode 100644 index 0000000..d9f72b4 --- /dev/null +++ b/rules/lib/builtins/BuildSetting.mdx @@ -0,0 +1,25 @@ +--- +title: 'BuildSetting' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.BuildSetting">BuildSetting</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The descriptor for a single piece of configuration information. If configuration is a key-value map of settings like {'cpu': 'ppc', 'copt': '-DFoo'}, this describes a single entry in that map. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/CcCompilationOutputs.mdx b/rules/lib/builtins/CcCompilationOutputs.mdx new file mode 100644 index 0000000..0208207 --- /dev/null +++ b/rules/lib/builtins/CcCompilationOutputs.mdx @@ -0,0 +1,44 @@ +--- +title: 'CcCompilationOutputs' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.CcCompilationOutputs">CcCompilationOutputs</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationOutputsApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Helper class containing CC compilation outputs. + +<h2>Members</h2> +<ul> + <li> + <a href="#objects">objects</a> + </li> + <li> + <a href="#pic_objects">pic_objects</a> + </li> + </ul> + + <h2 id="objects">objects</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> CcCompilationOutputs.objects</pre></p> + + Non-PIC object files. + + <h2 id="pic_objects">pic_objects</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> CcCompilationOutputs.pic_objects</pre></p> + + PIC object files. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/CcLinkingOutputs.mdx b/rules/lib/builtins/CcLinkingOutputs.mdx new file mode 100644 index 0000000..55d6e98 --- /dev/null +++ b/rules/lib/builtins/CcLinkingOutputs.mdx @@ -0,0 +1,46 @@ +--- +title: 'CcLinkingOutputs' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.CcLinkingOutputs">CcLinkingOutputs</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Helper class containing CC compilation outputs. + +<h2>Members</h2> +<ul> + <li> + <a href="#executable">executable</a> + </li> + <li> + <a href="#library_to_link">library_to_link</a> + </li> + </ul> + + <h2 id="executable">executable</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> CcLinkingOutputs.executable</pre></p> + + Represents the linked executable. + May return <code>None</code>. + + <h2 id="library_to_link">library_to_link</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/LibraryToLink.html">LibraryToLink</a> CcLinkingOutputs.library_to_link</pre></p> + + <code>LibraryToLink</code> for including these outputs in further linking. + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/CompilationContext.mdx b/rules/lib/builtins/CompilationContext.mdx new file mode 100644 index 0000000..1b3bbfe --- /dev/null +++ b/rules/lib/builtins/CompilationContext.mdx @@ -0,0 +1,132 @@ +--- +title: 'CompilationContext' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.CompilationContext">CompilationContext</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Immutable store of information needed for C++ compilation that is aggregated across dependencies. + +<h2>Members</h2> +<ul> + <li> + <a href="#defines">defines</a> + </li> + <li> + <a href="#direct_headers">direct_headers</a> + </li> + <li> + <a href="#direct_private_headers">direct_private_headers</a> + </li> + <li> + <a href="#direct_public_headers">direct_public_headers</a> + </li> + <li> + <a href="#direct_textual_headers">direct_textual_headers</a> + </li> + <li> + <a href="#external_includes">external_includes</a> + </li> + <li> + <a href="#framework_includes">framework_includes</a> + </li> + <li> + <a href="#headers">headers</a> + </li> + <li> + <a href="#includes">includes</a> + </li> + <li> + <a href="#local_defines">local_defines</a> + </li> + <li> + <a href="#quote_includes">quote_includes</a> + </li> + <li> + <a href="#system_includes">system_includes</a> + </li> + <li> + <a href="#validation_artifacts">validation_artifacts</a> + </li> + </ul> + + <h2 id="defines">defines</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.defines</pre></p> + + Returns the set of defines needed to compile this target. Each define is a string. These values are propagated to the target's transitive dependents, that is, any rules that depend on this target. + + <h2 id="direct_headers">direct_headers</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> CompilationContext.direct_headers</pre></p> + + Returns the list of modular headers that are declared by this target. This includes both public headers (such as those listed in "hdrs") and private headers (such as those listed in "srcs"). + + <h2 id="direct_private_headers">direct_private_headers</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> CompilationContext.direct_private_headers</pre></p> + + Returns the list of modular private headers (those listed in "srcs") that are declared by this target. + + <h2 id="direct_public_headers">direct_public_headers</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> CompilationContext.direct_public_headers</pre></p> + + Returns the list of modular public headers (those listed in "hdrs") that are declared by this target. + + <h2 id="direct_textual_headers">direct_textual_headers</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> CompilationContext.direct_textual_headers</pre></p> + + Returns the list of textual headers that are declared by this target. + + <h2 id="external_includes">external_includes</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.external_includes</pre></p> + + Returns the set of search paths (as strings) for external header files referenced by angle bracket. Usually passed with -isystem. + + <h2 id="framework_includes">framework_includes</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.framework_includes</pre></p> + + Returns the set of search paths (as strings) for framework header files. Usually passed with -F. + + <h2 id="headers">headers</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.headers</pre></p> + + Returns the set of headers needed to compile this target. + + <h2 id="includes">includes</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.includes</pre></p> + + Returns the set of search paths (as strings) for header files referenced both by angle bracket and quotes. Usually passed with -I. + + <h2 id="local_defines">local_defines</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.local_defines</pre></p> + + Returns the set of defines needed to compile this target. Each define is a string. These values are not propagated to the target's transitive dependents. + + <h2 id="quote_includes">quote_includes</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.quote_includes</pre></p> + + Returns the set of search paths (as strings) for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. + + <h2 id="system_includes">system_includes</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.system_includes</pre></p> + + Returns the set of search paths (as strings) for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. + + <h2 id="validation_artifacts">validation_artifacts</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.validation_artifacts</pre></p> + + Returns the set of validation artifacts. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/DirectoryExpander.mdx b/rules/lib/builtins/DirectoryExpander.mdx new file mode 100644 index 0000000..921b35a --- /dev/null +++ b/rules/lib/builtins/DirectoryExpander.mdx @@ -0,0 +1,63 @@ +--- +title: 'DirectoryExpander' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.DirectoryExpander">DirectoryExpander</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Expands directories created by <a href='../builtins/actions.html#declare_directory'><code>ctx.actions.declare_directory</code></a> during the execution phase. This is useful to expand directories in <a href='../builtins/Args.html#add_all.map_each'><code>map_each</code></a>. + +<h2>Members</h2> +<ul> + <li> + <a href="#expand">expand</a> + </li> + </ul> + + <h2 id="expand">expand</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> DirectoryExpander.expand(file)</pre></p> + + If the given <code>File</code> is a directory, this returns a list of <code>File</code>s recursively underneath the directory. Otherwise, this returns a list containing just the given <code>File</code> itself. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="expand.file"> + <code>file</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The directory or file to expand. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/DottedVersion.mdx b/rules/lib/builtins/DottedVersion.mdx new file mode 100644 index 0000000..05363bb --- /dev/null +++ b/rules/lib/builtins/DottedVersion.mdx @@ -0,0 +1,63 @@ +--- +title: 'DottedVersion' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.DottedVersion">DottedVersion</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/DottedVersionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A value representing a version with multiple components, separated by periods, such as 1.2.3.4. + +<h2>Members</h2> +<ul> + <li> + <a href="#compare_to">compare_to</a> + </li> + </ul> + + <h2 id="compare_to">compare_to</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> DottedVersion.compare_to(other)</pre></p> + + Compares based on most significant (first) not-matching version component. So, for example, 1.2.3 < 1.2.4 + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="compare_to.other"> + <code>other</code> + </td> + <td> + <a class="anchor" href="../builtins/DottedVersion.html">DottedVersion</a>; + required<br/> + The other dotted version. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/ExecGroupCollection.mdx b/rules/lib/builtins/ExecGroupCollection.mdx new file mode 100644 index 0000000..ad4d800 --- /dev/null +++ b/rules/lib/builtins/ExecGroupCollection.mdx @@ -0,0 +1,25 @@ +--- +title: 'ExecGroupCollection' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ExecGroupCollection">ExecGroupCollection</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ExecGroupCollectionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Stores exec groups available to a given rule. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/ExecGroupContext.mdx b/rules/lib/builtins/ExecGroupContext.mdx new file mode 100644 index 0000000..63f5421 --- /dev/null +++ b/rules/lib/builtins/ExecGroupContext.mdx @@ -0,0 +1,36 @@ +--- +title: 'ExecGroupContext' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ExecGroupContext">ExecGroupContext</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ExecGroupCollectionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Stores information about an exec group. + +<h2>Members</h2> +<ul> + <li> + <a href="#toolchains">toolchains</a> + </li> + </ul> + + <h2 id="toolchains">toolchains</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/ToolchainContext.html">ToolchainContext</a> ExecGroupContext.toolchains</pre></p> + + Toolchains required for this exec group + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/ExecTransitionFactory.mdx b/rules/lib/builtins/ExecTransitionFactory.mdx new file mode 100644 index 0000000..efad8bc --- /dev/null +++ b/rules/lib/builtins/ExecTransitionFactory.mdx @@ -0,0 +1,25 @@ +--- +title: 'ExecTransitionFactory' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ExecTransitionFactory">ExecTransitionFactory</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +an execution transition. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/ExpandedDirectory.mdx b/rules/lib/builtins/ExpandedDirectory.mdx new file mode 100644 index 0000000..9008d95 --- /dev/null +++ b/rules/lib/builtins/ExpandedDirectory.mdx @@ -0,0 +1,44 @@ +--- +title: 'ExpandedDirectory' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ExpandedDirectory">ExpandedDirectory</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ExpandedDirectoryApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Represents an expanded directory that makes the files within the it directly accessible. + +<h2>Members</h2> +<ul> + <li> + <a href="#children">children</a> + </li> + <li> + <a href="#directory">directory</a> + </li> + </ul> + + <h2 id="children">children</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> ExpandedDirectory.children</pre></p> + + Contains the files within the directory. + + <h2 id="directory">directory</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> ExpandedDirectory.directory</pre></p> + + The input directory that was expanded. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/FeatureConfiguration.mdx b/rules/lib/builtins/FeatureConfiguration.mdx new file mode 100644 index 0000000..da61d12 --- /dev/null +++ b/rules/lib/builtins/FeatureConfiguration.mdx @@ -0,0 +1,25 @@ +--- +title: 'FeatureConfiguration' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.FeatureConfiguration">FeatureConfiguration</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/FeatureConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Class used to construct command lines from CROSSTOOL features. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/File.mdx b/rules/lib/builtins/File.mdx new file mode 100644 index 0000000..98d1f8a --- /dev/null +++ b/rules/lib/builtins/File.mdx @@ -0,0 +1,117 @@ +--- +title: 'File' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.File">File</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +This object is created during the analysis phase to represent a file or directory that will be read or written during the execution phase. It is not an open file handle, and cannot be used to directly read or write file contents. Rather, you use it to construct the action graph in a rule implementation function by passing it to action-creating functions. See the <a href='https://bazel.build/extending/rules#files'>Rules page</a> for more information.<p>When a <code>File</code> is passed to an <a href='../builtins/Args.html'><code>Args</code></a> object without using a <code>map_each</code> function, it is converted to a string by taking the value of its <code>path</code> field. + +<h2>Members</h2> +<ul> + <li> + <a href="#basename">basename</a> + </li> + <li> + <a href="#dirname">dirname</a> + </li> + <li> + <a href="#extension">extension</a> + </li> + <li> + <a href="#is_directory">is_directory</a> + </li> + <li> + <a href="#is_source">is_source</a> + </li> + <li> + <a href="#is_symlink">is_symlink</a> + </li> + <li> + <a href="#owner">owner</a> + </li> + <li> + <a href="#path">path</a> + </li> + <li> + <a href="#root">root</a> + </li> + <li> + <a href="#short_path">short_path</a> + </li> + <li> + <a href="#tree_relative_path">tree_relative_path</a> + </li> + </ul> + + <h2 id="basename">basename</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.basename</pre></p> + + The base name of this file. This is the name of the file inside the directory. + + <h2 id="dirname">dirname</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.dirname</pre></p> + + The name of the directory containing this file. It's taken from <a href="#path">path</a> and is always relative to the execution directory. + + <h2 id="extension">extension</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.extension</pre></p> + + The file extension of this file, following (not including) the rightmost period. Empty string if the file's basename includes no periods. + + <h2 id="is_directory">is_directory</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_directory</pre></p> + + Returns true if this is a directory. This reflects the type the file was declared as (i.e. ctx.actions.declare_directory), not its type on the filesystem, which might differ. + + <h2 id="is_source">is_source</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_source</pre></p> + + Returns true if this is a source file, i.e. it is not generated. + + <h2 id="is_symlink">is_symlink</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_symlink</pre></p> + + Returns true if this was declared as a symlink. This reflects the type the file was declared as (i.e. ctx.actions.declare_symlink), not its type on the filesystem, which might differ. + + <h2 id="owner">owner</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> File.owner</pre></p> + + A label of a target that produces this File. + May return <code>None</code>. + + <h2 id="path">path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.path</pre></p> + + The execution path of this file, relative to the workspace's execution directory. It consists of two parts, an optional first part called the <i>root</i> (see also the <a href="../builtins/root.html">root</a> module), and the second part which is the <code>short_path</code>. The root may be empty, which it usually is for non-generated files. For generated files it usually contains a configuration-specific path fragment that encodes things like the target CPU architecture that was used while building said file. Use the <code>short_path</code> for the path under which the file is mapped if it's in the runfiles of a binary. + + <h2 id="root">root</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/root.html">root</a> File.root</pre></p> + + The root beneath which this file resides. + + <h2 id="short_path">short_path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.short_path</pre></p> + + The path of this file relative to its root. This excludes the aforementioned <i>root</i>, i.e. configuration-specific fragments of the path. This is also the path under which the file is mapped if it's in the runfiles of a binary. + + <h2 id="tree_relative_path">tree_relative_path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.tree_relative_path</pre></p> + + The path of this file relative to the root of the ancestor's tree, if the ancestor's <a href="#is_directory">is_directory</a> field is true. <code>tree_relative_path</code> is only available for expanded files of a directory in an action command, i.e. <a href="../builtins/Args.html#add_all">Args.add_all()</a>. For other types of files, it is an error to access this field. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/Label.mdx b/rules/lib/builtins/Label.mdx new file mode 100644 index 0000000..be83e2f --- /dev/null +++ b/rules/lib/builtins/Label.mdx @@ -0,0 +1,181 @@ +--- +title: 'Label' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.Label">Label</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/cmdline/Label.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A BUILD target identifier.<p>For every <code>Label</code> instance <code>l</code>, the string representation <code>str(l)</code> has the property that <code>Label(str(l)) == l</code>, regardless of where the <code>Label()</code> call occurs.<p>When passed as positional arguments to <code>print()</code> or <code>fail()</code>, <code>Label</code> use a string representation optimized for human readability instead. This representation uses an <a href="/external/overview#apparent-repo-name">apparent repository name</a> from the perspective of the main repository if possible. + +<h2>Members</h2> +<ul> + <li> + <a href="#Label">Label</a> + </li> + <li> + <a href="#name">name</a> + </li> + <li> + <a href="#package">package</a> + </li> + <li> + <a href="#relative">relative</a> + </li> + <li> + <a href="#repo_name">repo_name</a> + </li> + <li> + <a href="#same_package_label">same_package_label</a> + </li> + <li> + <a href="#workspace_name">workspace_name</a> + </li> + <li> + <a href="#workspace_root">workspace_root</a> + </li> + </ul> + + <h2 id="Label">Label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> Label(input)</pre></p> + + Converts a label string into a <code>Label</code> object, in the context of the package where the calling <code>.bzl</code> source file lives. If the given value is already a <code>Label</code>, it is returned unchanged.<p>For macros, a related function, <code><a href='../toplevel/native.html#package_relative_label'>native.package_relative_label()</a></code>, converts the input into a <code>Label</code> in the context of the package currently being constructed. Use that function to mimic the string-to-label conversion that is automatically done by label-valued rule attributes. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="Label.input"> + <code>input</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; + required<br/> + The input label string or Label object. If a Label object is passed, it's returned as is. + </td> + </tr> + </tbody> + </table> + + <h2 id="name">name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.name</pre></p> + + The name of the target referred to by this label. For instance:<br><pre class=language-python>Label("@@foo//pkg/foo:abc").name == "abc"</pre> + + <h2 id="package">package</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.package</pre></p> + + The name of the package containing the target referred to by this label, without the repository name. For instance:<br><pre class=language-python>Label("@@repo//pkg/foo:abc").package == "pkg/foo"</pre> + + <h2 id="relative">relative</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> Label.relative(relName)</pre></p> + + <b>Experimental</b>. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--+incompatible_enable_deprecated_label_apis</code> <br><strong>Deprecated.</strong> This method behaves surprisingly when used with an argument containing an apparent repo name. Prefer <a href="#same_package_label"><code>Label.same_package_label()</code></a>, <a href="../toplevel/native.html#package_relative_label"><code>native.package_relative_label()</code></a>, or <a href="#Label"><code>Label()</code></a> instead.<p>Resolves a label that is either absolute (starts with <code>//</code>) or relative to the current package. If this label is in a remote repository, the argument will be resolved relative to that repository. If the argument contains a repository name, the current label is ignored and the argument is returned as-is, except that the repository name is rewritten if it is in the current repository mapping. Reserved labels will also be returned as-is.<br>For example:<br><pre class=language-python> +Label("//foo/bar:baz").relative(":quux") == Label("//foo/bar:quux") +Label("//foo/bar:baz").relative("//wiz:quux") == Label("//wiz:quux") +Label("@repo//foo/bar:baz").relative("//wiz:quux") == Label("@repo//wiz:quux") +Label("@repo//foo/bar:baz").relative("//visibility:public") == Label("//visibility:public") +Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@other//wiz:quux") +</pre><p>If the repository mapping passed in is <code>{'@other' : '@remapped'}</code>, then the following remapping will take place:<br><pre class=language-python> +Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@remapped//wiz:quux") +</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="relative.relName"> + <code>relName</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The label that will be resolved relative to this one. + </td> + </tr> + </tbody> + </table> + + <h2 id="repo_name">repo_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.repo_name</pre></p> + + The canonical name of the repository containing the target referred to by this label, without any leading at-signs (<code>@</code>). For instance, <pre class=language-python>Label("@@foo//bar:baz").repo_name == "foo"</pre> + + <h2 id="same_package_label">same_package_label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> Label.same_package_label(target_name)</pre></p> + + Creates a label in the same package as this label with the given target name. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="same_package_label.target_name"> + <code>target_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The target name of the new label. + </td> + </tr> + </tbody> + </table> + + <h2 id="workspace_name">workspace_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.workspace_name</pre></p> + + <b>Experimental</b>. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--+incompatible_enable_deprecated_label_apis</code> <br><strong>Deprecated.</strong> The field name "workspace name" is a misnomer here; use the identically-behaving <a href="#repo_name"><code>Label.repo_name</code></a> instead.<p>The canonical name of the repository containing the target referred to by this label, without any leading at-signs (<code>@</code>). For instance, <pre class=language-python>Label("@@foo//bar:baz").workspace_name == "foo"</pre> + + <h2 id="workspace_root">workspace_root</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.workspace_root</pre></p> + + Returns the execution root for the repository containing the target referred to by this label, relative to the execroot. For instance:<br><pre class=language-python>Label("@repo//pkg/foo:abc").workspace_root == "external/repo"</pre> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/LateBoundDefault.mdx b/rules/lib/builtins/LateBoundDefault.mdx new file mode 100644 index 0000000..443f34e --- /dev/null +++ b/rules/lib/builtins/LateBoundDefault.mdx @@ -0,0 +1,25 @@ +--- +title: 'LateBoundDefault' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.LateBoundDefault">LateBoundDefault</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Represents a late-bound default attribute value of type 'Label'. The value of a LateBoundDefault is only resolvable in the context of a rule implementation function, and depends on the current build configuration. For example, a LateBoundDefault might represent the Label of the java toolchain in the current build configuration. <p>See <a href="../globals/bzl.html#configuration_field">configuration_field</a> for example usage. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/LibraryToLink.mdx b/rules/lib/builtins/LibraryToLink.mdx new file mode 100644 index 0000000..88374ef --- /dev/null +++ b/rules/lib/builtins/LibraryToLink.mdx @@ -0,0 +1,126 @@ +--- +title: 'LibraryToLink' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.LibraryToLink">LibraryToLink</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/LibraryToLinkApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A library the user can link against. + +<h2>Members</h2> +<ul> + <li> + <a href="#alwayslink">alwayslink</a> + </li> + <li> + <a href="#dynamic_library">dynamic_library</a> + </li> + <li> + <a href="#interface_library">interface_library</a> + </li> + <li> + <a href="#lto_bitcode_files">lto_bitcode_files</a> + </li> + <li> + <a href="#objects">objects</a> + </li> + <li> + <a href="#pic_lto_bitcode_files">pic_lto_bitcode_files</a> + </li> + <li> + <a href="#pic_objects">pic_objects</a> + </li> + <li> + <a href="#pic_static_library">pic_static_library</a> + </li> + <li> + <a href="#resolved_symlink_dynamic_library">resolved_symlink_dynamic_library</a> + </li> + <li> + <a href="#resolved_symlink_interface_library">resolved_symlink_interface_library</a> + </li> + <li> + <a href="#static_library">static_library</a> + </li> + </ul> + + <h2 id="alwayslink">alwayslink</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> LibraryToLink.alwayslink</pre></p> + + Whether to link the static library/objects in the --whole_archive block. + + <h2 id="dynamic_library">dynamic_library</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.dynamic_library</pre></p> + + <code>Artifact</code> of dynamic library to be linked. Always used for runtime and used for linking if <code>interface_library</code> is not passed. + May return <code>None</code>. + + <h2 id="interface_library">interface_library</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.interface_library</pre></p> + + <code>Artifact</code> of interface library to be linked. + May return <code>None</code>. + + <h2 id="lto_bitcode_files">lto_bitcode_files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LibraryToLink.lto_bitcode_files</pre></p> + + <code>List</code> of LTO bitcode files in the library. + May return <code>None</code>. + + <h2 id="objects">objects</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LibraryToLink.objects</pre></p> + + <code>List</code> of object files in the library. + May return <code>None</code>. + + <h2 id="pic_lto_bitcode_files">pic_lto_bitcode_files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LibraryToLink.pic_lto_bitcode_files</pre></p> + + <code>List</code> of pic LTO bitcode files in the library. + May return <code>None</code>. + + <h2 id="pic_objects">pic_objects</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LibraryToLink.pic_objects</pre></p> + + <code>List</code> of pic object files in the library. + May return <code>None</code>. + + <h2 id="pic_static_library">pic_static_library</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.pic_static_library</pre></p> + + <code>Artifact</code> of pic static library to be linked. + May return <code>None</code>. + + <h2 id="resolved_symlink_dynamic_library">resolved_symlink_dynamic_library</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.resolved_symlink_dynamic_library</pre></p> + + The resolved <code>Artifact</code> of the dynamic library to be linked if <code>dynamic_library</code> is a symlink, otherwise this is None. + May return <code>None</code>. + + <h2 id="resolved_symlink_interface_library">resolved_symlink_interface_library</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.resolved_symlink_interface_library</pre></p> + + The resolved <code>Artifact</code> of the interface library to be linked if <code>interface_library</code> is a symlink, otherwise this is None. + May return <code>None</code>. + + <h2 id="static_library">static_library</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.static_library</pre></p> + + <code>Artifact</code> of static library to be linked. + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/License.mdx b/rules/lib/builtins/License.mdx new file mode 100644 index 0000000..42229c5 --- /dev/null +++ b/rules/lib/builtins/License.mdx @@ -0,0 +1,25 @@ +--- +title: 'License' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.License">License</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LicenseApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +This API is deprecated and will be removed. Please do not depend on it. This object represents the value of a license attribute. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/LinkerInput.mdx b/rules/lib/builtins/LinkerInput.mdx new file mode 100644 index 0000000..8a26564 --- /dev/null +++ b/rules/lib/builtins/LinkerInput.mdx @@ -0,0 +1,60 @@ +--- +title: 'LinkerInput' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.LinkerInput">LinkerInput</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/LinkerInputApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Either libraries, flags or other files that may be passed to the linker as inputs. + +<h2>Members</h2> +<ul> + <li> + <a href="#additional_inputs">additional_inputs</a> + </li> + <li> + <a href="#libraries">libraries</a> + </li> + <li> + <a href="#owner">owner</a> + </li> + <li> + <a href="#user_link_flags">user_link_flags</a> + </li> + </ul> + + <h2 id="additional_inputs">additional_inputs</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LinkerInput.additional_inputs</pre></p> + + Returns the depset of additional inputs, e.g.: linker scripts. + + <h2 id="libraries">libraries</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LinkerInput.libraries</pre></p> + + Returns the depset of <code>LibraryToLink</code>. May return a list but this is deprecated. See #8118. + + <h2 id="owner">owner</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> LinkerInput.owner</pre></p> + + Returns the owner of this LinkerInput. + + <h2 id="user_link_flags">user_link_flags</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LinkerInput.user_link_flags</pre></p> + + Returns the list of user link flags passed as strings. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/LinkingContext.mdx b/rules/lib/builtins/LinkingContext.mdx new file mode 100644 index 0000000..67e1369 --- /dev/null +++ b/rules/lib/builtins/LinkingContext.mdx @@ -0,0 +1,36 @@ +--- +title: 'LinkingContext' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.LinkingContext">LinkingContext</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingContextApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Immutable store of information needed for C++ linking that is aggregated across dependencies. + +<h2>Members</h2> +<ul> + <li> + <a href="#linker_inputs">linker_inputs</a> + </li> + </ul> + + <h2 id="linker_inputs">linker_inputs</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> LinkingContext.linker_inputs</pre></p> + + Returns the depset of linker inputs. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/Provider.mdx b/rules/lib/builtins/Provider.mdx new file mode 100644 index 0000000..7206e4d --- /dev/null +++ b/rules/lib/builtins/Provider.mdx @@ -0,0 +1,29 @@ +--- +title: 'Provider' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.Provider">Provider</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A constructor for simple value objects, known as provider instances.<br>This value has a dual purpose: <ul> <li>It is a function that can be called to construct 'struct'-like values:<pre class="language-python">DataInfo = provider() +d = DataInfo(x = 2, y = 3) +print(d.x + d.y) # prints 5</pre> Note: Some providers, defined internally, do not allow instance creation </li> <li>It is a <i>key</i> to access a provider instance on a <a href="../builtins/Target.html">Target</a><pre class="language-python">DataInfo = provider() +def _rule_impl(ctx) + ... ctx.attr.dep[DataInfo]</pre> </li> </ul>Create a new <code>Provider</code> using the <a href="../globals/bzl.html#provider">provider</a> function. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/Subrule.mdx b/rules/lib/builtins/Subrule.mdx new file mode 100644 index 0000000..9fd6128 --- /dev/null +++ b/rules/lib/builtins/Subrule.mdx @@ -0,0 +1,25 @@ +--- +title: 'Subrule' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.Subrule">Subrule</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkSubruleApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Experimental: a building block for writing rules with shared code. For more information, please see the subrule proposal: https://docs.google.com/document/d/1RbNC88QieKvBEwir7iV5zZU08AaMlOzxhVkPnmKDedQ + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/SymlinkEntry.mdx b/rules/lib/builtins/SymlinkEntry.mdx new file mode 100644 index 0000000..5fadd60 --- /dev/null +++ b/rules/lib/builtins/SymlinkEntry.mdx @@ -0,0 +1,44 @@ +--- +title: 'SymlinkEntry' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.SymlinkEntry">SymlinkEntry</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/SymlinkEntryApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A single runfiles symlink represented by a link name and target. + +<h2>Members</h2> +<ul> + <li> + <a href="#path">path</a> + </li> + <li> + <a href="#target_file">target_file</a> + </li> + </ul> + + <h2 id="path">path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> SymlinkEntry.path</pre></p> + + The path of the symlink in the runfiles tree + + <h2 id="target_file">target_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> SymlinkEntry.target_file</pre></p> + + Target file of the symlink + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/Target.mdx b/rules/lib/builtins/Target.mdx new file mode 100644 index 0000000..0fa26fc --- /dev/null +++ b/rules/lib/builtins/Target.mdx @@ -0,0 +1,33 @@ +--- +title: 'Target' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.Target">Target</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The BUILD target for a dependency. Appears in the fields of <code><a href='../builtins/ctx.html#attr'>ctx.attr</a></code> corresponding to <a href='https://bazel.build/extending/rules#dependency_attributes'>dependency attributes</a> (<code><a href='../toplevel/attr.html#label'>label</a></code> or <code><a href='../toplevel/attr.html#label_list'>label_list</a></code>). Has the following fields: +<ul> +<li><h3 id='modules.Target.label'>label</h3> +<code><a href='../builtins/Label.html'>Label</a> Target.label</code><br/> +The identifier of the target.</li> +<li><h3 id='modules.Target.providers'>Providers</h3> +The <a href='https://bazel.build/extending/rules#providers'>providers</a> of a rule target can be accessed by type using index notation (<code>target[DefaultInfo]</code>). The presence of providers can be checked using the <code>in</code> operator (<code>SomeInfo in target</code>).<br/> +<br/> +</ul> + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/TemplateDict.mdx b/rules/lib/builtins/TemplateDict.mdx new file mode 100644 index 0000000..6735156 --- /dev/null +++ b/rules/lib/builtins/TemplateDict.mdx @@ -0,0 +1,168 @@ +--- +title: 'TemplateDict' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.TemplateDict">TemplateDict</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +An Args-like structure for use in ctx.actions.expand_template(), which allows for deferring evaluation of values till the execution phase. + +<h2>Members</h2> +<ul> + <li> + <a href="#add">add</a> + </li> + <li> + <a href="#add_joined">add_joined</a> + </li> + </ul> + + <h2 id="add">add</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/TemplateDict.html">TemplateDict</a> TemplateDict.add(key, value)</pre></p> + + Add a String value + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="add.key"> + <code>key</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A String key + </td> + </tr> + <tr> + <td id="add.value"> + <code>value</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A String value + </td> + </tr> + </tbody> + </table> + + <h2 id="add_joined">add_joined</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/TemplateDict.html">TemplateDict</a> TemplateDict.add_joined(key, values, *, join_with, map_each, uniquify=False, format_joined=None, allow_closure=False)</pre></p> + + Add depset of values + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="add_joined.key"> + <code>key</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A String key + </td> + </tr> + <tr> + <td id="add_joined.values"> + <code>values</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; + required<br/> + The depset whose items will be joined. + </td> + </tr> + <tr> + <td id="add_joined.join_with"> + <code>join_with</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A delimiter string used to join together the strings obtained from applying <code>map_each</code>, in the same manner as <a href='../core/string.html#join'><code>string.join()</code></a>. + </td> + </tr> + <tr> + <td id="add_joined.map_each"> + <code>map_each</code> + </td> + <td> + callable; + required<br/> + A Starlark function accepting a single argument and returning either a string, <code>None</code>, or a list of strings. This function is applied to each item of the depset specified in the <code>values</code> parameter + </td> + </tr> + <tr> + <td id="add_joined.uniquify"> + <code>uniquify</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, duplicate strings derived from <code>values</code> will be omitted. Only the first occurrence of each string will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items. + </td> + </tr> + <tr> + <td id="add_joined.format_joined"> + <code>format_joined</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. + </td> + </tr> + <tr> + <td id="add_joined.allow_closure"> + <code>allow_closure</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/ToolchainContext.mdx b/rules/lib/builtins/ToolchainContext.mdx new file mode 100644 index 0000000..7420c07 --- /dev/null +++ b/rules/lib/builtins/ToolchainContext.mdx @@ -0,0 +1,25 @@ +--- +title: 'ToolchainContext' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ToolchainContext">ToolchainContext</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainContextApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in <code>ctx.toolchains["//pkg:my_toolchain_type"]</code>. If the toolchain was optional and no toolchain was resolved, this will return <code>None</code>. Accessing toolchains of an aspect or rule via <code>ctx.toolchains</code> returns the indexed toolchain as a <code>ToolchainInfo</code> provider. While when using aspects, <code>ToolchainContext</code> is also used to hold the toolchains of the base target. It can be accessed by <code>ctx.rule.toolchains["//pkg:my_toolchain_type"]</code> and it returns the list of providers resulted from applying the aspects on these toolchain targets. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/actions.mdx b/rules/lib/builtins/actions.mdx new file mode 100644 index 0000000..fff1554 --- /dev/null +++ b/rules/lib/builtins/actions.mdx @@ -0,0 +1,988 @@ +--- +title: 'actions' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.actions">actions</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Module providing functions to create actions. Access this module using <a href="../builtins/ctx.html#actions"><code>ctx.actions</code></a>. + +<h2>Members</h2> +<ul> + <li> + <a href="#args">args</a> + </li> + <li> + <a href="#declare_directory">declare_directory</a> + </li> + <li> + <a href="#declare_file">declare_file</a> + </li> + <li> + <a href="#declare_symlink">declare_symlink</a> + </li> + <li> + <a href="#do_nothing">do_nothing</a> + </li> + <li> + <a href="#expand_template">expand_template</a> + </li> + <li> + <a href="#map_directory">map_directory</a> + </li> + <li> + <a href="#run">run</a> + </li> + <li> + <a href="#run_shell">run_shell</a> + </li> + <li> + <a href="#symlink">symlink</a> + </li> + <li> + <a href="#template_dict">template_dict</a> + </li> + <li> + <a href="#write">write</a> + </li> + </ul> + + <h2 id="args">args</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> actions.args()</pre></p> + + Returns an Args object that can be used to build memory-efficient command lines. + + <h2 id="declare_directory">declare_directory</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> actions.declare_directory(filename, *, sibling=None)</pre></p> + + Declares that the rule or aspect creates a directory with the given name, in the current package. You must create an action that generates the directory. The contents of the directory are not directly accessible from Starlark, but can be expanded in an action command with <a href="../builtins/Args.html#add_all"><code>Args.add_all()</code></a>. Only regular files and directories can be in the expanded contents of a declare_directory. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="declare_directory.filename"> + <code>filename</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + If no 'sibling' provided, path of the new directory, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). + </td> + </tr> + <tr> + <td id="declare_directory.sibling"> + <code>sibling</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + A file that lives in the same directory as the newly declared directory. The file must be in the current package. + </td> + </tr> + </tbody> + </table> + + <h2 id="declare_file">declare_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> actions.declare_file(filename, *, sibling=None)</pre></p> + + Declares that the rule or aspect creates a file with the given filename. If <code>sibling</code> is not specified, the file name is relative to the package directory, otherwise the file is in the same directory as <code>sibling</code>. Files cannot be created outside of the current package.<p>Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned <code>File</code> object to the action's construction function.<p>Note that <a href='https://bazel.build/extending/rules#files'>predeclared output files</a> do not need to be (and cannot be) declared using this function. You can obtain their <code>File</code> objects from <a href="../builtins/ctx.html#outputs"><code>ctx.outputs</code></a> instead. <a href="https://github.com/bazelbuild/examples/tree/main/rules/computed_dependencies/hash.bzl">See example of use</a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="declare_file.filename"> + <code>filename</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + If no 'sibling' provided, path of the new file, relative to the current package. Otherwise a base name for a file ('sibling' determines a directory). + </td> + </tr> + <tr> + <td id="declare_file.sibling"> + <code>sibling</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + A file that lives in the same directory as the newly created file. The file must be in the current package. + </td> + </tr> + </tbody> + </table> + + <h2 id="declare_symlink">declare_symlink</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> actions.declare_symlink(filename, *, sibling=None)</pre></p> + + Declares that the rule or aspect creates a symlink with the given name in the current package. You must create an action that generates this symlink. Bazel will never dereference this symlink and will transfer it verbatim to sandboxes or remote executors. Symlinks inside tree artifacts are not currently supported. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="declare_symlink.filename"> + <code>filename</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + If no 'sibling' provided, path of the new symlink, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). + </td> + </tr> + <tr> + <td id="declare_symlink.sibling"> + <code>sibling</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + A file that lives in the same directory as the newly declared symlink. + </td> + </tr> + </tbody> + </table> + + <h2 id="do_nothing">do_nothing</h2> + <p><pre class="rule-signature"><code>None</code> actions.do_nothing(*, mnemonic, inputs=[])</pre></p> + + Creates an empty action that neither executes a command nor produces any output, but that is useful for inserting 'extra actions'. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="do_nothing.mnemonic"> + <code>mnemonic</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A one-word description of the action, for example, CppCompile or GoLink. + </td> + </tr> + <tr> + <td id="do_nothing.inputs"> + <code>inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>[]</code><br/> + List of the input files of the action. + </td> + </tr> + </tbody> + </table> + + <h2 id="expand_template">expand_template</h2> + <p><pre class="rule-signature"><code>None</code> actions.expand_template(*, template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)</pre></p> + + Creates a template expansion action. When the action is executed, it will generate a file based on a template. Parts of the template will be replaced using the <code>substitutions</code> dictionary, in the order the substitutions are specified. Whenever a key of the dictionary appears in the template (or a result of a previous substitution), it is replaced with the associated value. There is no special syntax for the keys. You may, for example, use curly braces to avoid conflicts (for example, <code>{KEY}</code>). <a href="https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl">See example of use</a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="expand_template.template"> + <code>template</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The template file, which is a UTF-8 encoded text file. + </td> + </tr> + <tr> + <td id="expand_template.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The output file, which is a UTF-8 encoded text file. + </td> + </tr> + <tr> + <td id="expand_template.substitutions"> + <code>substitutions</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + Substitutions to make when expanding the template. + </td> + </tr> + <tr> + <td id="expand_template.is_executable"> + <code>is_executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether the output file should be executable. + </td> + </tr> + <tr> + <td id="expand_template.computed_substitutions"> + <code>computed_substitutions</code> + </td> + <td> + <a class="anchor" href="../builtins/TemplateDict.html">TemplateDict</a>; + default is <code>unbound</code><br/> + Substitutions to make when expanding the template. + </td> + </tr> + </tbody> + </table> + + <h2 id="map_directory">map_directory</h2> + <p><pre class="rule-signature"><code>None</code> actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation)</pre></p> + + Creates multiple actions based on the files within one or more input directories, to output one or more output directories. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="map_directory.input_directories"> + <code>input_directories</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + required<br/> + A dictionary mapping of strings to input directories, as declared by <code>ctx.actions.declare_directory()</code> (only directories are allowed as values here). The values specify the directories that we want expanded to access their files in the implementation function. The keys (strings) act as identifiers to easily reference a specific directory in the implementation function. + </td> + </tr> + <tr> + <td id="map_directory.additional_inputs"> + <code>additional_inputs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary of mapping of strings to additional inputs (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify any additional inputs that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific input from within the implementation function. + </td> + </tr> + <tr> + <td id="map_directory.output_directories"> + <code>output_directories</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + required<br/> + A dictionary mapping of strings to output directories, as declared by <code>ctx.actions.declare_directory()</code>. The values specify the output directories that we want to generate by the actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific output directory from within the implementation function. + </td> + </tr> + <tr> + <td id="map_directory.tools"> + <code>tools</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + required<br/> + A dictionary mapping of strings to tools (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify the tools that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific tool from within the implementation function. + </td> + </tr> + <tr> + <td id="map_directory.additional_params"> + <code>additional_params</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary mapping of strings to additional parameters (only string, boolean and integer values are allowed here). The values specify any additional parameters that we want to make accessible to the implementation function that could be used to influence its behavior. The keys (strings) act as identifiers to easily reference a specific parameter from within the implementation function. + </td> + </tr> + <tr> + <td id="map_directory.execution_requirements"> + <code>execution_requirements</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Information for scheduling the created actions. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys. + </td> + </tr> + <tr> + <td id="map_directory.exec_group"> + <code>exec_group</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Run the created actions on the given exec group's execution platform. If none, uses the target's default execution platform. + </td> + </tr> + <tr> + <td id="map_directory.toolchain"> + <code>toolchain</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + <p>Toolchain type of the executable or tools used by the created actions.</p><p>If executable and tools are not coming from a toolchain, set this parameter to <code>None</code>.</p><p>If executable and tools are coming from a toolchain, toolchain type must be set so that the created actions execute on the correct execution platform.</p><p>Note that the rule which creates these actions needs to define this toolchain inside its 'rule()' function.</p><p>When <code>toolchain</code> and <code>exec_group</code> parameters are both set, <code>exec_group</code> will be used. An error is raised in case the <code>exec_group</code> doesn't specify the same toolchain.</p> + </td> + </tr> + <tr> + <td id="map_directory.use_default_shell_env"> + <code>use_default_shell_env</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether the created actions should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. + </td> + </tr> + <tr> + <td id="map_directory.env"> + <code>env</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Sets the dictionary of environment variables.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. + </td> + </tr> + <tr> + <td id="map_directory.mnemonic"> + <code>mnemonic</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A one-word description of the created actions, for example, CppCompile or GoLink. + </td> + </tr> + <tr> + <td id="map_directory.implementation"> + <code>implementation</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + required<br/> + A Starlark function that gets called after input directories have been built to generate actions +that output files to the specified output directories. This function is passed the following +arguments: + +<ul> + <li><code>template_ctx</code> (positional): A <a + href='../builtins/template_ctx.html'><code>template_ctx</code></a> object that can be used to + create actions.</li> + <li><code>input_directories</code> (keyword-only): A dictionary mapping from the string keys of + the <code>input_directories</code> argument of <code>actions.map_directory()</code> to their + values' corresponding <a href='../builtins/File.html'><code>ExpandedDirectory</code></a> + objects.</li> + <li><code>output_directories</code> (keyword-only): The value of the + <code>output_directories</code> argument of <code>actions.map_directory()</code>; a + dictionary mapping from strings to output directories.</li> + <li><code>additional_inputs</code> (keyword-only): The value of the + <code>additional_inputs</code> argument of <code>actions.map_directory()</code>; a + dictionary mapping from strings to input files.</li> + <li><code>tools</code> (keyword-only): The value of the <code>tools</code> argument of + <code>actions.map_directory()</code>; a dictionary mapping from strings to tools.</li> + <li><code>additional_params</code> (keyword-only): The value of the + <code>additional_params</code> argument of <code>actions.map_directory()</code>; a + dictionary mapping from strings to strings, booleans, or integers.</li> +</ul> + +This function must be top-level, i.e. lambdas and nested functions are not allowed. + + </td> + </tr> + </tbody> + </table> + + <h2 id="run">run</h2> + <p><pre class="rule-signature"><code>None</code> 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)</pre></p> + + Creates an action that runs an executable. <a href="https://github.com/bazelbuild/examples/tree/main/rules/actions_run/execute.bzl">See example of use</a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="run.outputs"> + <code>outputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + required<br/> + List of the output files of the action. + </td> + </tr> + <tr> + <td id="run.inputs"> + <code>inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>[]</code><br/> + List or depset of the input files of the action. + </td> + </tr> + <tr> + <td id="run.unused_inputs_list"> + <code>unused_inputs_list</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + File containing list of inputs unused by the action. <p>The content of this file (generally one of the outputs of the action) corresponds to the list of input files that were not used during the whole action execution. Any change in those files must not affect in any way the outputs of the action. + </td> + </tr> + <tr> + <td id="run.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a>; + required<br/> + The executable file to be called by the action. + </td> + </tr> + <tr> + <td id="run.tools"> + <code>tools</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>unbound</code><br/> + List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. <p> +When a list is provided, it can be a heterogenous collection of: +<ul> + <li><code>File</code>s</li> + <li><code>FilesToRunProvider</code> instances</li> + <li><code>depset</code>s of <code>File</code>s</li> +</ul> +<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. +</p> + + </td> + </tr> + <tr> + <td id="run.arguments"> + <code>arguments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects. + </td> + </tr> + <tr> + <td id="run.mnemonic"> + <code>mnemonic</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A one-word description of the action, for example, CppCompile or GoLink. + </td> + </tr> + <tr> + <td id="run.progress_message"> + <code>progress_message</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain <code>%{label}</code>, <code>%{input}</code>, or <code>%{output}</code> patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. + </td> + </tr> + <tr> + <td id="run.use_default_shell_env"> + <code>use_default_shell_env</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. + </td> + </tr> + <tr> + <td id="run.env"> + <code>env</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Sets the dictionary of environment variables.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. + </td> + </tr> + <tr> + <td id="run.execution_requirements"> + <code>execution_requirements</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Information for scheduling the action. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys. + </td> + </tr> + <tr> + <td id="run.input_manifests"> + <code>input_manifests</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; + default is <code>None</code><br/> + Legacy argument. Ignored. + </td> + </tr> + <tr> + <td id="run.exec_group"> + <code>exec_group</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. + </td> + </tr> + <tr> + <td id="run.shadowed_action"> + <code>shadowed_action</code> + </td> + <td> + <a class="anchor" href="../builtins/Action.html">Action</a>; + default is <code>None</code><br/> + 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. + </td> + </tr> + <tr> + <td id="run.resource_set"> + <code>resource_set</code> + </td> + <td> + callable; or <code>None</code>; + default is <code>None</code><br/> + A callback function that returns a resource set dictionary, used to estimate resource usage at execution time if this action is run locally.<p>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:<ul><li>"cpu": number of CPUs; default 1<li>"memory": in MB; default 250<li>"local_test": number of local tests; default 1</ul><p>If this parameter is set to <code>None</code> , the default values are used.<p>The callback must be top-level (lambda and nested functions aren't allowed). + </td> + </tr> + <tr> + <td id="run.toolchain"> + <code>toolchain</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>unbound</code><br/> + <p>Toolchain type of the executable or tools used in this action.</p><p>If executable and tools are not coming from a toolchain, set this parameter to `None`.</p><p>If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform.</p><p>Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function.</p><p>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.</p> + </td> + </tr> + </tbody> + </table> + + <h2 id="run_shell">run_shell</h2> + <p><pre class="rule-signature"><code>None</code> 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)</pre></p> + + Creates an action that runs a shell command. <a href="https://github.com/bazelbuild/examples/tree/main/rules/shell_command/rules.bzl">See example of use</a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="run_shell.outputs"> + <code>outputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + required<br/> + List of the output files of the action. + </td> + </tr> + <tr> + <td id="run_shell.inputs"> + <code>inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>[]</code><br/> + List or depset of the input files of the action. + </td> + </tr> + <tr> + <td id="run_shell.tools"> + <code>tools</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>unbound</code><br/> + List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. <p> +When a list is provided, it can be a heterogenous collection of: +<ul> + <li><code>File</code>s</li> + <li><code>FilesToRunProvider</code> instances</li> + <li><code>depset</code>s of <code>File</code>s</li> +</ul> +<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. +</p> + + </td> + </tr> + <tr> + <td id="run_shell.arguments"> + <code>arguments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects.<p>Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as <code>$1</code>, <code>$2</code>, etc. Note that since Args objects are flattened before indexing, if there is an Args object of unknown size then all subsequent strings will be at unpredictable indices. It may be useful to use <code>$@</code> (to retrieve all arguments) in conjunction with Args objects of indeterminate size.<p>In the case where <code>command</code> is a list of strings, this parameter may not be used. + </td> + </tr> + <tr> + <td id="run_shell.mnemonic"> + <code>mnemonic</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A one-word description of the action, for example, CppCompile or GoLink. + </td> + </tr> + <tr> + <td id="run_shell.command"> + <code>command</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + Shell command to execute. This may either be a string (preferred) or a sequence of strings <b>(deprecated)</b>.<p>If <code>command</code> is a string, then it is executed as if by <code>sh -c <command> "" <arguments></code> -- that is, the elements in <code>arguments</code> are made available to the command as <code>$1</code>, <code>$2</code> (or <code>%1</code>, <code>%2</code> if using Windows batch), etc. If <code>arguments</code> contains any <a href="#args"><code>actions.args()</code></a> objects, their contents are appended one by one to the command line, so <code>$</code><i>i</i> can refer to individual strings within an Args object. Note that if an Args object of unknown size is passed as part of <code>arguments</code>, then the strings will be at unknown indices; in this case the <code>$@</code> shell substitution (retrieve all arguments) may be useful.<p><b>(Deprecated)</b> If <code>command</code> is a sequence of strings, the first item is the executable to run and the remaining items are its arguments. If this form is used, the <code>arguments</code> parameter must not be supplied. <i>Note that this form is deprecated and will soon be removed. It is disabled with `--incompatible_run_shell_command_string`. Use this flag to verify your code is compatible. </i><p>Bazel uses the same shell to execute the command as it does for genrules. + </td> + </tr> + <tr> + <td id="run_shell.progress_message"> + <code>progress_message</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain <code>%{label}</code>, <code>%{input}</code>, or <code>%{output}</code> patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. + </td> + </tr> + <tr> + <td id="run_shell.use_default_shell_env"> + <code>use_default_shell_env</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. + </td> + </tr> + <tr> + <td id="run_shell.env"> + <code>env</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Sets the dictionary of environment variables.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. + </td> + </tr> + <tr> + <td id="run_shell.execution_requirements"> + <code>execution_requirements</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Information for scheduling the action. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys. + </td> + </tr> + <tr> + <td id="run_shell.input_manifests"> + <code>input_manifests</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; + default is <code>None</code><br/> + Legacy argument. Ignored. + </td> + </tr> + <tr> + <td id="run_shell.exec_group"> + <code>exec_group</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. + </td> + </tr> + <tr> + <td id="run_shell.shadowed_action"> + <code>shadowed_action</code> + </td> + <td> + <a class="anchor" href="../builtins/Action.html">Action</a>; + default is <code>None</code><br/> + 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. + </td> + </tr> + <tr> + <td id="run_shell.resource_set"> + <code>resource_set</code> + </td> + <td> + callable; or <code>None</code>; + default is <code>None</code><br/> + A callback function for estimating resource usage if run locally. See<a href="#run.resource_set"><code>ctx.actions.run()</code></a>. + </td> + </tr> + <tr> + <td id="run_shell.toolchain"> + <code>toolchain</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>unbound</code><br/> + <p>Toolchain type of the executable or tools used in this action.</p><p>If executable and tools are not coming from a toolchain, set this parameter to `None`.</p><p>If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform.</p><p>Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function.</p><p>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.</p> + </td> + </tr> + </tbody> + </table> + + <h2 id="symlink">symlink</h2> + <p><pre class="rule-signature"><code>None</code> actions.symlink(*, output, target_file=None, target_path=None, is_executable=False, progress_message=None)</pre></p> + + Creates an action that writes a symlink in the file system.<p>This function must be called with exactly one of <code>target_file</code> or <code>target_path</code> specified.</p><p>When you use <code>target_file</code>, declare <code>output</code> with <a href="#declare_file"><code>declare_file()</code></a> or <a href="#declare_directory"><code>declare_directory()</code></a> and match the type of <code>target_file</code>. This makes the symlink point to <code>target_file</code>. Bazel invalidates the output of this action whenever the target of the symlink or its contents change.</p><p>Otherwise, when you use <code>target_path</code>, declare <code>output</code> with <a href="#declare_symlink"><code>declare_symlink()</code></a>). In this case, the symlink points to <code>target_path</code>. Bazel never resolves the symlink and the output of this action is invalidated only when the text contents of the symlink (that is, the value of <code>readlink()</code>) changes. In particular, this can be used to create a dangling symlink.</p> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="symlink.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The output of this action. + </td> + </tr> + <tr> + <td id="symlink.target_file"> + <code>target_file</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + The File that the output symlink will point to. + </td> + </tr> + <tr> + <td id="symlink.target_path"> + <code>target_path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The exact path that the output symlink will point to. No normalization or other processing is applied. + </td> + </tr> + <tr> + <td id="symlink.is_executable"> + <code>is_executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + May only be used with <code>target_file</code>, not <code>target_path</code>. If true, when the action is executed, the <code>target_file</code>'s path is checked to confirm that it is executable, and an error is reported if it is not. Setting <code>is_executable</code> to False does not mean the target is not executable, just that no verification is done.<p>This feature does not make sense for <code>target_path</code> because dangling symlinks might not exist at build time.</p> + </td> + </tr> + <tr> + <td id="symlink.progress_message"> + <code>progress_message</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Progress message to show to the user during the build. + </td> + </tr> + </tbody> + </table> + + <h2 id="template_dict">template_dict</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/TemplateDict.html">TemplateDict</a> actions.template_dict()</pre></p> + + Returns a TemplateDict object for memory-efficient template expansion. + + <h2 id="write">write</h2> + <p><pre class="rule-signature"><code>None</code> actions.write(output, content, is_executable=False, *, mnemonic=None)</pre></p> + + Creates a file write action. When the action is executed, it will write the given content to a file. This is used to generate files using information available in the analysis phase. If the file is large and with a lot of static content, consider using <a href="#expand_template"><code>expand_template</code></a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="write.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The output file. + </td> + </tr> + <tr> + <td id="write.content"> + <code>content</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Args.html">Args</a>; + required<br/> + the contents of the file. May be a either a string or an <a href="#args"><code>actions.args()</code></a> object. + </td> + </tr> + <tr> + <td id="write.is_executable"> + <code>is_executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether the output file should be executable. + </td> + </tr> + <tr> + <td id="write.mnemonic"> + <code>mnemonic</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A one-word description of the action, for example, CppCompile or GoLink. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/apple_platform.mdx b/rules/lib/builtins/apple_platform.mdx new file mode 100644 index 0000000..7dd45d1 --- /dev/null +++ b/rules/lib/builtins/apple_platform.mdx @@ -0,0 +1,63 @@ +--- +title: 'apple_platform' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.apple_platform">apple_platform</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Corresponds to Xcode's notion of a platform as would be found in <code>Xcode.app/Contents/Developer/Platforms</code>. Each platform represents an Apple platform type (such as iOS or tvOS) combined with one or more related CPU architectures. For example, the iOS simulator platform supports <code>x86_64</code> and <code>i386</code> architectures.<p>Specific instances of this type can be retrieved from the fields of the <a href='../toplevel/apple_common.html#platform'>apple_common.platform</a> struct:<br><ul><li><code>apple_common.platform.ios_device</code></li><li><code>apple_common.platform.ios_simulator</code></li><li><code>apple_common.platform.macos</code></li><li><code>apple_common.platform.tvos_device</code></li><li><code>apple_common.platform.tvos_simulator</code></li><li><code>apple_common.platform.watchos_device</code></li><li><code>apple_common.platform.watchos_simulator</code></li></ul><p>More commonly, however, the <a href='../fragments/apple.html'>apple</a> configuration fragment has fields/methods that allow rules to determine the platform for which a target is being built.<p>Example:<br><pre class='language-python'> +p = apple_common.platform.ios_device +print(p.name_in_plist) # 'iPhoneOS' +</pre> + +<h2>Members</h2> +<ul> + <li> + <a href="#is_device">is_device</a> + </li> + <li> + <a href="#name">name</a> + </li> + <li> + <a href="#name_in_plist">name_in_plist</a> + </li> + <li> + <a href="#platform_type">platform_type</a> + </li> + </ul> + + <h2 id="is_device">is_device</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> apple_platform.is_device</pre></p> + + Returns <code>True</code> if this platform is a device platform or <code>False</code> if it is a simulator platform. + + <h2 id="name">name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> apple_platform.name</pre></p> + + Returns the name aka starlarkKey of this platform. + + <h2 id="name_in_plist">name_in_plist</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> apple_platform.name_in_plist</pre></p> + + The name of the platform as it appears in the <code>CFBundleSupportedPlatforms</code> entry of an Info.plist file and in Xcode's platforms directory, without the extension (for example, <code>iPhoneOS</code> or <code>iPhoneSimulator</code>).<br>This name, when converted to lowercase (e.g., <code>iphoneos</code>, <code>iphonesimulator</code>), can be passed to Xcode's command-line tools like <code>ibtool</code> and <code>actool</code> when they expect a platform name. + + <h2 id="platform_type">platform_type</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> apple_platform.platform_type</pre></p> + + Returns the platform type of this platform. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/bazel_module.mdx b/rules/lib/builtins/bazel_module.mdx new file mode 100644 index 0000000..66167cb --- /dev/null +++ b/rules/lib/builtins/bazel_module.mdx @@ -0,0 +1,60 @@ +--- +title: 'bazel_module' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.bazel_module">bazel_module</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Represents a Bazel module in the external dependency graph. + +<h2>Members</h2> +<ul> + <li> + <a href="#is_root">is_root</a> + </li> + <li> + <a href="#name">name</a> + </li> + <li> + <a href="#tags">tags</a> + </li> + <li> + <a href="#version">version</a> + </li> + </ul> + + <h2 id="is_root">is_root</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> bazel_module.is_root</pre></p> + + Whether this module is the root module. + + <h2 id="name">name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> bazel_module.name</pre></p> + + The name of the module. + + <h2 id="tags">tags</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/bazel_module_tags.html">bazel_module_tags</a> bazel_module.tags</pre></p> + + The tags in the module related to the module extension currently being processed. + + <h2 id="version">version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> bazel_module.version</pre></p> + + The version of the module. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/bazel_module_tags.mdx b/rules/lib/builtins/bazel_module_tags.mdx new file mode 100644 index 0000000..40f42b6 --- /dev/null +++ b/rules/lib/builtins/bazel_module_tags.mdx @@ -0,0 +1,27 @@ +--- +title: 'bazel_module_tags' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.bazel_module_tags">bazel_module_tags</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Contains the tags in a module for the module extension currently being processed. This object has a field for each tag class of the extension, and the value of the field is a list containing an object for each tag instance. This "tag instance" object in turn has a field for each attribute of the tag class. + +When passed as positional arguments to <code>print()</code> or <code>fail()</code>, tag instance objects turn into a meaningful string representation of the form "'install' tag at /home/user/workspace/MODULE.bazel:3:4". This can be used to construct error messages that point to the location of the tag in the module file, e.g. <code>fail("Conflict between", tag1, "and", tag2)</code>. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/configuration.mdx b/rules/lib/builtins/configuration.mdx new file mode 100644 index 0000000..4410f93 --- /dev/null +++ b/rules/lib/builtins/configuration.mdx @@ -0,0 +1,70 @@ +--- +title: 'configuration' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.configuration">configuration</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +This object holds information about the environment in which the build is running. See the <a href='https://bazel.build/extending/rules#configurations'>Rules page</a> for more on the general concept of configurations. + +<h2>Members</h2> +<ul> + <li> + <a href="#coverage_enabled">coverage_enabled</a> + </li> + <li> + <a href="#default_shell_env">default_shell_env</a> + </li> + <li> + <a href="#host_path_separator">host_path_separator</a> + </li> + <li> + <a href="#short_id">short_id</a> + </li> + <li> + <a href="#test_env">test_env</a> + </li> + </ul> + + <h2 id="coverage_enabled">coverage_enabled</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> configuration.coverage_enabled</pre></p> + + A boolean that tells whether code coverage is enabled for this run. Note that this does not compute whether a specific rule should be instrumented for code coverage data collection. For that, see the <a href="../builtins/ctx.html#coverage_instrumented"><code>ctx.coverage_instrumented</code></a> function. + + <h2 id="default_shell_env">default_shell_env</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> configuration.default_shell_env</pre></p> + + A dictionary representing the static local shell environment. It maps variables to their values (strings). + + <h2 id="host_path_separator">host_path_separator</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> configuration.host_path_separator</pre></p> + + Returns the separator for PATH environment variable, which is ':' on Unix. + + <h2 id="short_id">short_id</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> configuration.short_id</pre></p> + + A short identifier for this configuration understood by the <code>config</code> and </code>query</code> subcommands. +<p>Use this to distinguish different configurations for the same target in a way that is friendly to humans and tool usage, for example in an aspect used by an IDE. Keep in mind the following caveats: <ul> <li>The value may differ across Bazel versions, including patch releases. <li>The value encodes the value of <b>every</b> flag, including those that aren't otherwise relevant for the current target and may thus invalidate caches more frequently. + + + <h2 id="test_env">test_env</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> configuration.test_env</pre></p> + + A dictionary containing user-specified test environment variables and their values, as set by the --test_env options. DO NOT USE! This is not the complete environment! + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/ctx.mdx b/rules/lib/builtins/ctx.mdx new file mode 100644 index 0000000..1e9ebc2 --- /dev/null +++ b/rules/lib/builtins/ctx.mdx @@ -0,0 +1,625 @@ +--- +title: 'ctx' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ctx">ctx</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A context object that is passed to the implementation function for a rule or aspect. It provides access to the information and methods needed to analyze the current target.<p>In particular, it lets the implementation function access the current target's label, attributes, configuration, and the providers of its dependencies. It has methods for declaring output files and the actions that produce them.<p>Context objects essentially live for the duration of the call to the implementation function. It is not useful to access these objects outside of their associated function. See the <a href='https://bazel.build/extending/rules#implementation_function'>Rules page</a> for more information. + +<h2>Members</h2> +<ul> + <li> + <a href="#actions">actions</a> + </li> + <li> + <a href="#aspect_ids">aspect_ids</a> + </li> + <li> + <a href="#attr">attr</a> + </li> + <li> + <a href="#bin_dir">bin_dir</a> + </li> + <li> + <a href="#build_file_path">build_file_path</a> + </li> + <li> + <a href="#build_setting_value">build_setting_value</a> + </li> + <li> + <a href="#configuration">configuration</a> + </li> + <li> + <a href="#coverage_instrumented">coverage_instrumented</a> + </li> + <li> + <a href="#created_actions">created_actions</a> + </li> + <li> + <a href="#disabled_features">disabled_features</a> + </li> + <li> + <a href="#exec_groups">exec_groups</a> + </li> + <li> + <a href="#executable">executable</a> + </li> + <li> + <a href="#expand_location">expand_location</a> + </li> + <li> + <a href="#expand_make_variables">expand_make_variables</a> + </li> + <li> + <a href="#features">features</a> + </li> + <li> + <a href="#file">file</a> + </li> + <li> + <a href="#files">files</a> + </li> + <li> + <a href="#fragments">fragments</a> + </li> + <li> + <a href="#genfiles_dir">genfiles_dir</a> + </li> + <li> + <a href="#info_file">info_file</a> + </li> + <li> + <a href="#label">label</a> + </li> + <li> + <a href="#outputs">outputs</a> + </li> + <li> + <a href="#resolve_command">resolve_command</a> + </li> + <li> + <a href="#resolve_tools">resolve_tools</a> + </li> + <li> + <a href="#rule">rule</a> + </li> + <li> + <a href="#runfiles">runfiles</a> + </li> + <li> + <a href="#split_attr">split_attr</a> + </li> + <li> + <a href="#super">super</a> + </li> + <li> + <a href="#target_platform_has_constraint">target_platform_has_constraint</a> + </li> + <li> + <a href="#toolchains">toolchains</a> + </li> + <li> + <a href="#var">var</a> + </li> + <li> + <a href="#version_file">version_file</a> + </li> + <li> + <a href="#workspace_name">workspace_name</a> + </li> + </ul> + + <h2 id="actions">actions</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/actions.html">actions</a> ctx.actions</pre></p> + + Contains methods for declaring output files and the actions that produce them. + + <h2 id="aspect_ids">aspect_ids</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> ctx.aspect_ids</pre></p> + + A list of ids for all aspects applied to the target. Only available in aspect implementation functions. + + <h2 id="attr">attr</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.attr</pre></p> + + A struct to access the values of the <a href='https://bazel.build/extending/rules#attributes'>attributes</a>. The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the <a href='../globals/bzl.html#rule.attrs'><code>attrs</code> dict</a> provided to the <a href='../globals/bzl.html#rule'><code>rule</code> function</a>. <a href="https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl">See example of use</a>. + + <h2 id="bin_dir">bin_dir</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/root.html">root</a> ctx.bin_dir</pre></p> + + The root corresponding to bin directory. + + <h2 id="build_file_path">build_file_path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ctx.build_file_path</pre></p> + + Deprecated: Use <code>ctx.label.package + '/BUILD'</code>. The path to the BUILD file for this rule, relative to the source root. + + <h2 id="build_setting_value">build_setting_value</h2> + <p><pre class="rule-signature">unknown ctx.build_setting_value</pre></p> + + Value of the build setting represented by the current target. If this isn't the context for an instance of a rule that sets the <a href="https://bazel.build/extending/config#rule-parameter"><code>build_setting</code></a> attribute, reading this is an error. + + <h2 id="configuration">configuration</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/configuration.html">configuration</a> ctx.configuration</pre></p> + + The default configuration. See the <a href="../builtins/configuration.html">configuration</a> type for more details. + + <h2 id="coverage_instrumented">coverage_instrumented</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> ctx.coverage_instrumented(target=None)</pre></p> + + Returns whether code coverage instrumentation should be generated when performing compilation actions for this rule or, if <code>target</code> is provided, the rule specified by that Target. (If a non-rule or a Starlark rule Target is provided, this returns False.) Checks if the sources of the current rule (if no Target is provided) or the sources of Target should be instrumented based on the --instrumentation_filter and --instrument_test_targets config settings. This differs from <code>coverage_enabled</code> in the <a href="../builtins/configuration.html">configuration</a>, which notes whether coverage data collection is enabled for the entire run, but not whether a specific target should be instrumented. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="coverage_instrumented.target"> + <code>target</code> + </td> + <td> + <a class="anchor" href="../builtins/Target.html">Target</a>; or <code>None</code>; + default is <code>None</code><br/> + A Target specifying a rule. If not provided, defaults to the current rule. + </td> + </tr> + </tbody> + </table> + + <h2 id="created_actions">created_actions</h2> + <p><pre class="rule-signature">StarlarkValue ctx.created_actions()</pre></p> + + For rules with <a href="../globals/bzl.html#rule._skylark_testable">_skylark_testable</a> set to <code>True</code>, this returns an <code>Actions</code> provider representing all actions created so far for the current rule. For all other rules, returns <code>None</code>. Note that the provider is not updated when subsequent actions are created, so you will have to call this function again if you wish to inspect them. <br/><br/>This is intended to help write tests for rule-implementation helper functions, which may take in a <code>ctx</code> object and create actions on it. + + <h2 id="disabled_features">disabled_features</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> ctx.disabled_features</pre></p> + + The set of features that are explicitly disabled by the user for this rule. + + <h2 id="exec_groups">exec_groups</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/ExecGroupCollection.html">ExecGroupCollection</a> ctx.exec_groups</pre></p> + + A collection of the execution groups available for this rule, indexed by their name. Access with <code>ctx.exec_groups[name_of_group]</code>. + + <h2 id="executable">executable</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.executable</pre></p> + + A <code>struct</code> containing executable files defined in <a href='../toplevel/attr.html#label'>label type attributes</a> marked as <a href='../toplevel/attr.html#label.executable'><code>executable=True</code></a>. The struct fields correspond to the attribute names. Each value in the struct is either a <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an optional attribute is not specified in the rule then the corresponding struct value is <code>None</code>. If a label type is not marked as <code>executable=True</code>, no corresponding struct field is generated. <a href="https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl">See example of use</a>. + + <h2 id="expand_location">expand_location</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ctx.expand_location(input, targets=[])</pre></p> + + Expands all <code>$(location ...)</code> templates in the given string by replacing <code>$(location //x)</code> with the path of the output file of target //x. Expansion only works for labels that point to direct dependencies of this rule or that are explicitly listed in the optional argument <code>targets</code>. <br/><br/><code>$(location ...)</code> will cause an error if the referenced target has multiple outputs. In this case, please use <code>$(locations ...)</code> since it produces a space-separated list of output paths. It can be safely used for a single output file, too.<br/><br/>This function is useful to let the user specify a command in a BUILD file (like for <code>genrule</code>). In other cases, it is often better to manipulate labels directly. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="expand_location.input"> + <code>input</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + String to be expanded. + </td> + </tr> + <tr> + <td id="expand_location.targets"> + <code>targets</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Target.html">Target</a>s; + default is <code>[]</code><br/> + List of targets for additional lookup information. These are expanded as follows: A target with a single file in <code>DefaultInfo.files</code> expands to that file. Other targets expand to their <code>DefaultInfo.executable</code> file if set and if <code>--incompatible_locations_prefers_executable</code> is enabled, otherwise they expand to <code>DefaultInfo.files</code>. + </td> + </tr> + </tbody> + </table> + May return <code>None</code>. + + <h2 id="expand_make_variables">expand_make_variables</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ctx.expand_make_variables(attribute_name, command, additional_substitutions)</pre></p> + + <b>Deprecated.</b> Use <a href="../builtins/ctx.html#var">ctx.var</a> to access the variables instead.<br>Returns a string after expanding all references to "Make variables". The variables must have the following format: <code>$(VAR_NAME)</code>. Also, <code>$$VAR_NAME</code> expands to <code>$VAR_NAME</code>. Examples:<pre class=language-python> +ctx.expand_make_variables("cmd", "$(MY_VAR)", {"MY_VAR": "Hi"}) # == "Hi" +ctx.expand_make_variables("cmd", "$$PWD", {}) # == "$PWD" +</pre>Additional variables may come from other places, such as configurations. Note that this function is experimental. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="expand_make_variables.attribute_name"> + <code>attribute_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The attribute name. Used for error reporting. + </td> + </tr> + <tr> + <td id="expand_make_variables.command"> + <code>command</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The expression to expand. It can contain references to "Make variables". + </td> + </tr> + <tr> + <td id="expand_make_variables.additional_substitutions"> + <code>additional_substitutions</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + required<br/> + Additional substitutions to make beyond the default make variables. + </td> + </tr> + </tbody> + </table> + + <h2 id="features">features</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> ctx.features</pre></p> + + The set of features that are explicitly enabled by the user for this rule. <a href="https://github.com/bazelbuild/examples/blob/main/rules/features/rule.bzl">See example of use</a>. + + <h2 id="file">file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.file</pre></p> + + A <code>struct</code> containing files defined in <a href='../toplevel/attr.html#label'>label type attributes</a> marked as <a href='../toplevel/attr.html#label.allow_single_file'><code>allow_single_file</code></a>. The struct fields correspond to the attribute names. The struct value is always a <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an optional attribute is not specified in the rule then the corresponding struct value is <code>None</code>. If a label type is not marked as <code>allow_single_file</code>, no corresponding struct field is generated. It is a shortcut for:<pre class=language-python>list(ctx.attr.<ATTR>.files)[0]</pre>In other words, use <code>file</code> to access the (singular) <a href="https://bazel.build/extending/rules#requesting_output_files">default output</a> of a dependency. <a href="https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl">See example of use</a>. + + <h2 id="files">files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.files</pre></p> + + A <code>struct</code> containing files defined in <a href='../toplevel/attr.html#label'>label</a> or <a href='../toplevel/attr.html#label_list'>label list</a> type attributes. The struct fields correspond to the attribute names. The struct values are <code>list</code> of <a href='../builtins/File.html'><code>File</code></a>s. It is a shortcut for:<pre class=language-python>[f for t in ctx.attr.<ATTR> for f in t.files]</pre> In other words, use <code>files</code> to access the <a href="https://bazel.build/extending/rules#requesting_output_files"> default outputs</a> of a dependency. <a href="https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl">See example of use</a>. + + <h2 id="fragments">fragments</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/fragments.html">fragments</a> ctx.fragments</pre></p> + + Allows access to configuration fragments in target configuration. + + <h2 id="genfiles_dir">genfiles_dir</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/root.html">root</a> ctx.genfiles_dir</pre></p> + + The root corresponding to genfiles directory. + + <h2 id="info_file">info_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> ctx.info_file</pre></p> + + The file that is used to hold the non-volatile workspace status for the current build request. See documentation for --workspace_status_command for more information. + + <h2 id="label">label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> ctx.label</pre></p> + + The label of the target currently being analyzed. + + <h2 id="outputs">outputs</h2> + <p><pre class="rule-signature">structure ctx.outputs</pre></p> + + A pseudo-struct containing all the predeclared output files, represented by <a href='../builtins/File.html'><code>File</code></a> objects. See the <a href='https://bazel.build/extending/rules#files'>Rules page</a> for more information and examples.<p>This field does not exist on aspect contexts, since aspects do not have predeclared outputs.<p>The fields of this object are defined as follows. It is an error if two outputs produce the same field name or have the same label.<ul><li> If the rule declares an <a href='../globals/bzl.html#rule.outputs'><code>outputs</code></a> dict, then for every entry in the dict, there is a field whose name is the key and whose value is the corresponding <code>File</code>.<li>For every attribute of type <a href='../toplevel/attr.html#output'><code>attr.output</code></a> that the rule declares, there is a field whose name is the attribute's name. If the target specified a label for that attribute, then the field value is the corresponding <code>File</code>; otherwise the field value is <code>None</code>.<li>For every attribute of type <a href='../toplevel/attr.html#output_list'><code>attr.output_list</code></a> that the rule declares, there is a field whose name is the attribute's name. The field value is a list of <code>File</code> objects corresponding to the labels given for that attribute in the target, or an empty list if the attribute was not specified in the target.<li><b>(Deprecated)</b> If the rule is marked <a href='../globals/bzl.html#rule.executable'><code>executable</code></a> or <a href='../globals/bzl.html#rule.test'><code>test</code></a>, there is a field named <code>"executable"</code>, which is the default executable. It is recommended that instead of using this, you pass another file (either predeclared or not) to the <code>executable</code> arg of <a href='../providers/DefaultInfo.html'><code>DefaultInfo</code></a>.</ul> + + <h2 id="resolve_command">resolve_command</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> ctx.resolve_command(*, command='', attribute=None, expand_locations=False, make_variables=None, tools=[], label_dict={}, execution_requirements={})</pre></p> + + <i>(Experimental)</i> Returns a tuple <code>(inputs, command, empty list)</code> of the list of resolved inputs and the argv list for the resolved command both of them suitable for passing as the same-named arguments of the <code>ctx.action</code> method.<br/><b>Note for Windows users</b>: this method requires Bash (MSYS2). Consider using <code>resolve_tools()</code> instead (if that fits your needs). The empty list is returned as the third member of the tuple for backwards compatibility. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="resolve_command.command"> + <code>command</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Command to resolve. + </td> + </tr> + <tr> + <td id="resolve_command.attribute"> + <code>attribute</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Name of the associated attribute for which to issue an error, or None. + </td> + </tr> + <tr> + <td id="resolve_command.expand_locations"> + <code>expand_locations</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Shall we expand $(location) variables? See <a href="#expand_location">ctx.expand_location()</a> for more details. + </td> + </tr> + <tr> + <td id="resolve_command.make_variables"> + <code>make_variables</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Make variables to expand, or None. + </td> + </tr> + <tr> + <td id="resolve_command.tools"> + <code>tools</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Target.html">Target</a>s; + default is <code>[]</code><br/> + List of tools (list of targets). + </td> + </tr> + <tr> + <td id="resolve_command.label_dict"> + <code>label_dict</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + Dictionary of resolved labels and the corresponding list of Files (a dict of Label : list of Files). + </td> + </tr> + <tr> + <td id="resolve_command.execution_requirements"> + <code>execution_requirements</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + Information for scheduling the action to resolve this command. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys. + </td> + </tr> + </tbody> + </table> + + <h2 id="resolve_tools">resolve_tools</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> ctx.resolve_tools(*, tools=[])</pre></p> + + Returns a tuple <code>(inputs, empty list)</code> of the depset of resolved inputs required to run the tools, suitable for passing as the same-named argument of the <code>ctx.actions.run</code> and <code>ctx.actions.run_shell</code> methods. <br/><br/>In contrast to <code>ctx.resolve_command</code>, this method does not require that Bash be installed on the machine, so it's suitable for rules built on Windows. The empty list is returned as part of the tuple for backward compatibility. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="resolve_tools.tools"> + <code>tools</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Target.html">Target</a>s; + default is <code>[]</code><br/> + List of tools (list of targets). + </td> + </tr> + </tbody> + </table> + + <h2 id="rule">rule</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/rule_attributes.html">rule_attributes</a> ctx.rule</pre></p> + + Rule attributes descriptor for the rule that the aspect is applied to. Only available in aspect implementation functions. + + <h2 id="runfiles">runfiles</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> ctx.runfiles(files=[], transitive_files=None, collect_data=False, collect_default=False, symlinks={}, root_symlinks={})</pre></p> + + Creates a runfiles object. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="runfiles.files"> + <code>files</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + The list of files to be added to the runfiles. + </td> + </tr> + <tr> + <td id="runfiles.transitive_files"> + <code>transitive_files</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <code>None</code>; + default is <code>None</code><br/> + The (transitive) set of files to be added to the runfiles. The depset should use the <code>default</code> order (which, as the name implies, is the default). + </td> + </tr> + <tr> + <td id="runfiles.collect_data"> + <code>collect_data</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + <b>Use of this parameter is not recommended. See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a></b>. <p>Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes. + </td> + </tr> + <tr> + <td id="runfiles.collect_default"> + <code>collect_default</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + <b>Use of this parameter is not recommended. See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a></b>. <p>Whether to collect the default runfiles from the dependencies in srcs, data and deps attributes. + </td> + </tr> + <tr> + <td id="runfiles.symlinks"> + <code>symlinks</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <a class="anchor" href="../builtins/depset.html">depset</a> of <a class="anchor" href="../builtins/SymlinkEntry.html">SymlinkEntry</a>s; + default is <code>{}</code><br/> + Either a SymlinkEntry depset or the map of symlinks to be added to the runfiles. Symlinks are always added under the main workspace's runfiles directory (e.g. <code><runfiles_root>/_main/<symlink_path></code>, <b>not</b> the directory corresponding to the current target's repository. See <a href="https://bazel.build/extending/rules#runfiles_symlinks">Runfiles symlinks</a> in the rules guide. + </td> + </tr> + <tr> + <td id="runfiles.root_symlinks"> + <code>root_symlinks</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <a class="anchor" href="../builtins/depset.html">depset</a> of <a class="anchor" href="../builtins/SymlinkEntry.html">SymlinkEntry</a>s; + default is <code>{}</code><br/> + Either a SymlinkEntry depset or a map of symlinks to be added to the runfiles. See <a href="https://bazel.build/extending/rules#runfiles_symlinks">Runfiles symlinks</a> in the rules guide. + </td> + </tr> + </tbody> + </table> + + <h2 id="split_attr">split_attr</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.split_attr</pre></p> + + A struct to access the values of attributes with split configurations. If the attribute is a label list, the value of split_attr is a dict of the keys of the split (as strings) to lists of the ConfiguredTargets in that branch of the split. If the attribute is a label, then the value of split_attr is a dict of the keys of the split (as strings) to single ConfiguredTargets. Attributes with split configurations still appear in the attr struct, but their values will be single lists with all the branches of the split merged together. + + <h2 id="super">super</h2> + <p><pre class="rule-signature">unknown ctx.super()</pre></p> + + Experimental: Calls parent's implementation function and returns its providers + + <h2 id="target_platform_has_constraint">target_platform_has_constraint</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> ctx.target_platform_has_constraint(constraintValue)</pre></p> + + Returns true if the given constraint value is part of the current target platform. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="target_platform_has_constraint.constraintValue"> + <code>constraintValue</code> + </td> + <td> + <a class="anchor" href="../providers/ConstraintValueInfo.html">ConstraintValueInfo</a>; + required<br/> + The constraint value to check the target platform against. + </td> + </tr> + </tbody> + </table> + + <h2 id="toolchains">toolchains</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/ToolchainContext.html">ToolchainContext</a> ctx.toolchains</pre></p> + + Toolchains for the default exec group of this rule. + + <h2 id="var">var</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> ctx.var</pre></p> + + Dictionary (String to String) of configuration variables. + + <h2 id="version_file">version_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> ctx.version_file</pre></p> + + The file that is used to hold the volatile workspace status for the current build request. See documentation for --workspace_status_command for more information. + + <h2 id="workspace_name">workspace_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ctx.workspace_name</pre></p> + + The name of the workspace, which is effectively the execution root name and runfiles prefix for the main repo. If <code>--enable_bzlmod</code> is on, this is the fixed string <code>_main</code>. Otherwise, this is the workspace name as defined in the WORKSPACE file. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/depset.mdx b/rules/lib/builtins/depset.mdx new file mode 100644 index 0000000..2740279 --- /dev/null +++ b/rules/lib/builtins/depset.mdx @@ -0,0 +1,86 @@ +--- +title: 'depset' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.depset">depset</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +<p>A specialized data structure that supports efficient merge operations and has a defined traversal +order. Commonly used for accumulating data from transitive dependencies in rules and aspects. For +more information see <a href="/extending/depsets">here</a>. + +<p>The elements of a depset must be hashable and all of the same type (as defined by the built-in +<a href="../globals/all#type"><code>type(x)</code></a> function), but depsets are not simply hash +sets and do not support fast membership tests. If you need a general set datatype, use the core +<a href="../core/set">Starlark set</a> type (available since Bazel 8.1); if your .bzl file needs to +be compatible with older Bazel releases, you can simulate a set by using a dictionary where all keys +map to <code>True</code>. + +<p>When tested for truth (that is, when used in a Boolean context such as <code>if d:</code> where +<code>d</code> is a depset), a depset is True if and only if it is non-empty; this check is an O(1) +operation. + +<p>Depsets are immutable. They should be created using their +<a href="../globals/bzl.html#depset">constructor function</a> and merged or augmented with other +depsets via the <code>transitive</code> argument. + +<p>The <code>order</code> parameter determines the kind of traversal that is done to convert the +depset to an iterable. There are four possible values: + +<ul> + <li> + <code>"default"</code> (formerly <code>"stable"</code>): Order is unspecified (but + deterministic). + </li> + <li> + <code>"postorder"</code> (formerly <code>"compile"</code>): A left-to-right post-ordering. + Precisely, this recursively traverses all children leftmost-first, then the direct elements + leftmost-first. + </li> + <li> + <code>"preorder"</code> (formerly <code>"naive_link"</code>): A left-to-right pre-ordering. + Precisely, this traverses the direct elements leftmost-first, then recursively traverses the + children leftmost-first. + </li> + <li> + <code>"topological"</code> (formerly <code>"link"</code>): A topological ordering from the root + down to the leaves. There is no left-to-right guarantee. + </li> +</ul> + +<p>Two depsets may only be merged if either both depsets have the same order, or one of them has +<code>"default"</code> order. In the latter case the resulting depset's order will be the same as +the other's order. + +<p>Depsets may contain duplicate values but these will be suppressed when iterating (using +<a href="#to_list"><code>to_list()</code></a>). Duplicates may interfere with the ordering +semantics. + + +<h2>Members</h2> +<ul> + <li> + <a href="#to_list">to_list</a> + </li> + </ul> + + <h2 id="to_list">to_list</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> depset.to_list()</pre></p> + + Returns a list of the elements, without duplicates, in the depset's traversal order. Note that order is unspecified (but deterministic) for elements that were added more than once to the depset. Order is also unspecified for <code>"default"</code>-ordered depsets, and for elements of child depsets whose order differs from that of the parent depset. The list is a copy; modifying it has no effect on the depset and vice versa. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/exec_result.mdx b/rules/lib/builtins/exec_result.mdx new file mode 100644 index 0000000..605d041 --- /dev/null +++ b/rules/lib/builtins/exec_result.mdx @@ -0,0 +1,54 @@ +--- +title: 'exec_result' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.exec_result">exec_result</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkExecutionResult.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A structure storing result of repository_ctx.execute() method. It contains the standard output stream content, the standard error stream content and the execution return code. + + +<h2>Members</h2> +<ul> + <li> + <a href="#return_code">return_code</a> + </li> + <li> + <a href="#stderr">stderr</a> + </li> + <li> + <a href="#stdout">stdout</a> + </li> + </ul> + + <h2 id="return_code">return_code</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> exec_result.return_code</pre></p> + + The return code returned after the execution of the program. 256 if the process was terminated by a time out; values larger than 128 indicate termination by a signal. + + + <h2 id="stderr">stderr</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> exec_result.stderr</pre></p> + + The content of the standard error output returned by the execution. + + <h2 id="stdout">stdout</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> exec_result.stdout</pre></p> + + The content of the standard output returned by the execution. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/extension_metadata.mdx b/rules/lib/builtins/extension_metadata.mdx new file mode 100644 index 0000000..a518c56 --- /dev/null +++ b/rules/lib/builtins/extension_metadata.mdx @@ -0,0 +1,25 @@ +--- +title: 'extension_metadata' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.extension_metadata">extension_metadata</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionMetadata.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Return values of this type from a module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/fragments.mdx b/rules/lib/builtins/fragments.mdx new file mode 100644 index 0000000..24e47fa --- /dev/null +++ b/rules/lib/builtins/fragments.mdx @@ -0,0 +1,25 @@ +--- +title: 'fragments' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.fragments">fragments</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A collection of configuration fragments available in the current rule implementation context. Access a specific fragment by its field name. For example, <code>ctx.fragments.java</code> <p>Only configuration fragments which are declared in the rule definition may be accessed in this collection.</p><p>See the <a href="../fragments.html">configuration fragment reference</a> for a list of available fragments and the <a href="https://bazel.build/extending/rules#configuration_fragments">rules documentation</a> for how to use them. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/java_annotation_processing.mdx b/rules/lib/builtins/java_annotation_processing.mdx new file mode 100644 index 0000000..696cf91 --- /dev/null +++ b/rules/lib/builtins/java_annotation_processing.mdx @@ -0,0 +1,86 @@ +--- +title: 'java_annotation_processing' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.java_annotation_processing">java_annotation_processing</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaAnnotationProcessingApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Information about jars that are a result of annotation processing for a Java rule. + +<h2>Members</h2> +<ul> + <li> + <a href="#class_jar">class_jar</a> + </li> + <li> + <a href="#enabled">enabled</a> + </li> + <li> + <a href="#processor_classnames">processor_classnames</a> + </li> + <li> + <a href="#processor_classpath">processor_classpath</a> + </li> + <li> + <a href="#source_jar">source_jar</a> + </li> + <li> + <a href="#transitive_class_jars">transitive_class_jars</a> + </li> + <li> + <a href="#transitive_source_jars">transitive_source_jars</a> + </li> + </ul> + + <h2 id="class_jar">class_jar</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_annotation_processing.class_jar</pre></p> + + Deprecated: Please use <code>JavaInfo.java_outputs.generated_class_jar</code> instead. + May return <code>None</code>. + + <h2 id="enabled">enabled</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java_annotation_processing.enabled</pre></p> + + Deprecated. Returns true if annotation processing was applied on this target. + + <h2 id="processor_classnames">processor_classnames</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java_annotation_processing.processor_classnames</pre></p> + + Deprecated: Please use <code>JavaInfo.plugins</code> instead. Returns class names of annotation processors applied to this rule. + + <h2 id="processor_classpath">processor_classpath</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_annotation_processing.processor_classpath</pre></p> + + Deprecated: Please use <code>JavaInfo.plugins</code> instead. Returns a classpath of annotation processors applied to this rule. + + <h2 id="source_jar">source_jar</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_annotation_processing.source_jar</pre></p> + + Deprecated: Please use <code>JavaInfo.java_outputs.generated_source_jar</code> instead. + May return <code>None</code>. + + <h2 id="transitive_class_jars">transitive_class_jars</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_annotation_processing.transitive_class_jars</pre></p> + + Deprecated. Returns a transitive set of class file jars resulting from annotation processing of this rule and its dependencies. + + <h2 id="transitive_source_jars">transitive_source_jars</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_annotation_processing.transitive_source_jars</pre></p> + + Deprecated. Returns a transitive set of source archives resulting from annotation processing of this rule and its dependencies. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/macro.mdx b/rules/lib/builtins/macro.mdx new file mode 100644 index 0000000..ef43a43 --- /dev/null +++ b/rules/lib/builtins/macro.mdx @@ -0,0 +1,31 @@ +--- +title: 'macro' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.macro">macro</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/MacroFunctionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A callable Starlark value representing a symbolic macro; in other words, the return value of +<a href="../globals/bzl.html#macro"><code>macro()</code></a>. Invoking this value during package +construction time will instantiate the macro, and cause the macro's implementation function to be +evaluated (in a separate context, different from the context in which the macro value was invoked), +in most cases causing targets to be added to the package's target set. For more information, see +<a href="https://bazel.build/extending/macros">Macros</a>. + + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/mapped_root.mdx b/rules/lib/builtins/mapped_root.mdx new file mode 100644 index 0000000..4e16d8e --- /dev/null +++ b/rules/lib/builtins/mapped_root.mdx @@ -0,0 +1,36 @@ +--- +title: 'mapped_root' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.mapped_root">mapped_root</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/actions/PathMapper.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A root for files that have been subject to path mapping + +<h2>Members</h2> +<ul> + <li> + <a href="#path">path</a> + </li> + </ul> + + <h2 id="path">path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> mapped_root.path</pre></p> + + Returns the relative path from the exec root to the actual root. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/module_ctx.mdx b/rules/lib/builtins/module_ctx.mdx new file mode 100644 index 0000000..1089f19 --- /dev/null +++ b/rules/lib/builtins/module_ctx.mdx @@ -0,0 +1,889 @@ +--- +title: 'module_ctx' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.module_ctx">module_ctx</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The context of the module extension containing helper functions and information about pertinent tags across the dependency graph. You get a module_ctx object as an argument to the <code>implementation</code> function when you create a module extension. + +<h2>Members</h2> +<ul> + <li> + <a href="#download">download</a> + </li> + <li> + <a href="#download_and_extract">download_and_extract</a> + </li> + <li> + <a href="#execute">execute</a> + </li> + <li> + <a href="#extension_metadata">extension_metadata</a> + </li> + <li> + <a href="#extract">extract</a> + </li> + <li> + <a href="#file">file</a> + </li> + <li> + <a href="#getenv">getenv</a> + </li> + <li> + <a href="#is_dev_dependency">is_dev_dependency</a> + </li> + <li> + <a href="#modules">modules</a> + </li> + <li> + <a href="#os">os</a> + </li> + <li> + <a href="#path">path</a> + </li> + <li> + <a href="#read">read</a> + </li> + <li> + <a href="#report_progress">report_progress</a> + </li> + <li> + <a href="#root_module_has_non_dev_dependency">root_module_has_non_dev_dependency</a> + </li> + <li> + <a href="#watch">watch</a> + </li> + <li> + <a href="#which">which</a> + </li> + </ul> + + <h2 id="download">download</h2> + <p><pre class="rule-signature">unknown module_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True)</pre></p> + + Downloads a file to the output path for the provided url and returns a struct containing <code>success</code>, a flag which is <code>true</code> if the download completed successfully, and if successful, a hash of the file with the fields <code>sha256</code> and <code>integrity</code>. When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit <code>canonical_id</code> is highly recommended. e.g. <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="download.url"> + <code>url</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or Iterable of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + List of mirror URLs referencing the same file. + </td> + </tr> + <tr> + <td id="download.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + default is <code>''</code><br/> + path to the output file, relative to the repository directory. + </td> + </tr> + <tr> + <td id="download.sha256"> + <code>sha256</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + </td> + </tr> + <tr> + <td id="download.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Set the executable flag on the created file, false by default. + </td> + </tr> + <tr> + <td id="download.allow_fail"> + <code>allow_fail</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If set, indicate the error in the return value instead of raising an error for failed downloads. + + </td> + </tr> + <tr> + <td id="download.canonical_id"> + <code>canonical_id</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (<code>sha256</code> or <code>integrity</code>). + + </td> + </tr> + <tr> + <td id="download.auth"> + <code>auth</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying authentication information for some of the URLs. + </td> + </tr> + <tr> + <td id="download.headers"> + <code>headers</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying http headers for all URLs. + </td> + </tr> + <tr> + <td id="download.integrity"> + <code>integrity</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + </td> + </tr> + <tr> + <td id="download.block"> + <code>block</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. + + </td> + </tr> + </tbody> + </table> + + <h2 id="download_and_extract">download_and_extract</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> module_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={})</pre></p> + + Downloads a file to the output path for the provided url, extracts it, and returns a struct containing <code>success</code>, a flag which is <code>true</code> if the download completed successfully, and if successful, a hash of the file with the fields <code>sha256</code> and <code>integrity</code>. When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit <code>canonical_id</code> is highly recommended. e.g. <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="download_and_extract.url"> + <code>url</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or Iterable of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + List of mirror URLs referencing the same file. + </td> + </tr> + <tr> + <td id="download_and_extract.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + default is <code>''</code><br/> + Path to the directory where the archive will be unpacked, relative to the repository directory. + + </td> + </tr> + <tr> + <td id="download_and_extract.sha256"> + <code>sha256</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + </td> + </tr> + <tr> + <td id="download_and_extract.type"> + <code>type</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. + + </td> + </tr> + <tr> + <td id="download_and_extract.strip_prefix"> + <code>strip_prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + A directory prefix to strip from the extracted files. Many archives contain a +top-level directory that contains all files in the archive. Instead of needing to +specify this prefix over and over in the <code>build_file</code>, this field can +be used to strip it from extracted files. + +<p>For compatibility, this parameter may also be used under the deprecated name +<code>stripPrefix</code>. + + </td> + </tr> + <tr> + <td id="download_and_extract.allow_fail"> + <code>allow_fail</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If set, indicate the error in the return value instead of raising an error for failed downloads. + + </td> + </tr> + <tr> + <td id="download_and_extract.canonical_id"> + <code>canonical_id</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum +(<code>sha256</code> or <code>integrity</code>). + + </td> + </tr> + <tr> + <td id="download_and_extract.auth"> + <code>auth</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying authentication information for some of the URLs. + </td> + </tr> + <tr> + <td id="download_and_extract.headers"> + <code>headers</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying http headers for all URLs. + </td> + </tr> + <tr> + <td id="download_and_extract.integrity"> + <code>integrity</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + </td> + </tr> + <tr> + <td id="download_and_extract.rename_files"> + <code>rename_files</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. + + </td> + </tr> + </tbody> + </table> + + <h2 id="execute">execute</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/exec_result.html">exec_result</a> module_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="")</pre></p> + + Executes the command given by the list of arguments. The execution time of the command is limited by <code>timeout</code> (in seconds, default 600 seconds). This method returns an <code>exec_result</code> structure containing the output of the command. The <code>environment</code> map can be used to override some environment variables to be passed to the process. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="execute.arguments"> + <code>arguments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + required<br/> + List of arguments, the first element should be the path to the program to execute. + + </td> + </tr> + <tr> + <td id="execute.timeout"> + <code>timeout</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>600</code><br/> + Maximum duration of the command in seconds (default is 600 seconds). + </td> + </tr> + <tr> + <td id="execute.environment"> + <code>environment</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + Force some environment variables to be set to be passed to the process. The value can be <code>None</code> to remove the environment variable. + + </td> + </tr> + <tr> + <td id="execute.quiet"> + <code>quiet</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + If stdout and stderr should be printed to the terminal. + </td> + </tr> + <tr> + <td id="execute.working_directory"> + <code>working_directory</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>""</code><br/> + Working directory for command execution. +Can be relative to the repository root or absolute. +The default is the repository root. + + </td> + </tr> + </tbody> + </table> + + <h2 id="extension_metadata">extension_metadata</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/extension_metadata.html">extension_metadata</a> module_ctx.extension_metadata(*, root_module_direct_deps=None, root_module_direct_dev_deps=None, reproducible=False)</pre></p> + + Constructs an opaque object that can be returned from the module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="extension_metadata.root_module_direct_deps"> + <code>root_module_direct_deps</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The names of the repositories that the extension considers to be direct dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via <a href="../globals/module.html#use_repo"><code>use_repo</code></a>, Bazel will print a warning when the extension is evaluated, instructing the user to run <code>bazel mod tidy</code> to fix the <code>use_repo</code> calls automatically. <p>If one of <code>root_module_direct_deps</code> and will print a warning and a fixup command when the extension is evaluated.<p>If one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> is specified, the other has to be as well. The lists specified by these two parameters must be disjoint.<p>Exactly one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> can be set to the special value <code>"all"</code>, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. + </td> + </tr> + <tr> + <td id="extension_metadata.root_module_direct_dev_deps"> + <code>root_module_direct_dev_deps</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The names of the repositories that the extension considers to be direct dev dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via <a href="../globals/module.html#use_repo"><code>use_repo</code></a> on an extension proxy created with <code><a href="../globals/module.html#use_extension">use_extension</a>(..., dev_dependency = True)</code>, Bazel will print a warning when the extension is evaluated, instructing the user to run <code>bazel mod tidy</code> to fix the <code>use_repo</code> calls automatically. <p>If one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> is specified, the other has to be as well. The lists specified by these two parameters must be disjoint.<p>Exactly one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> can be set to the special value <code>"all"</code>, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. + </td> + </tr> + <tr> + <td id="extension_metadata.reproducible"> + <code>reproducible</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + States that this module extension ensures complete reproducibility, thereby it should not be stored in the lockfile. + </td> + </tr> + </tbody> + </table> + + <h2 id="extract">extract</h2> + <p><pre class="rule-signature"><code>None</code> module_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto')</pre></p> + + Extract an archive to the repository directory. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="extract.archive"> + <code>archive</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + path to the archive that will be unpacked, relative to the repository directory. + </td> + </tr> + <tr> + <td id="extract.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + default is <code>''</code><br/> + path to the directory where the archive will be unpacked, relative to the repository directory. + </td> + </tr> + <tr> + <td id="extract.strip_prefix"> + <code>strip_prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + a directory prefix to strip from the extracted files. Many archives contain a +top-level directory that contains all files in the archive. Instead of needing to +specify this prefix over and over in the <code>build_file</code>, this field can be +used to strip it from extracted files. + +<p>For compatibility, this parameter may also be used under the deprecated name +<code>stripPrefix</code>. + + </td> + </tr> + <tr> + <td id="extract.rename_files"> + <code>rename_files</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. + </td> + </tr> + <tr> + <td id="extract.watch_archive"> + <code>watch_archive</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'auto'</code><br/> + whether to <a href="#watch">watch</a> the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. + </td> + </tr> + </tbody> + </table> + + <h2 id="file">file</h2> + <p><pre class="rule-signature"><code>None</code> module_ctx.file(path, content='', executable=True, legacy_utf8=False)</pre></p> + + Generates a file in the repository directory with the provided content. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="file.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the file to create, relative to the repository directory. + </td> + </tr> + <tr> + <td id="file.content"> + <code>content</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The content of the file to create, empty by default. + </td> + </tr> + <tr> + <td id="file.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + Set the executable flag on the created file, true by default. + </td> + </tr> + <tr> + <td id="file.legacy_utf8"> + <code>legacy_utf8</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + No-op. This parameter is deprecated and will be removed in a future version of Bazel. + + </td> + </tr> + </tbody> + </table> + + <h2 id="getenv">getenv</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> module_ctx.getenv(name, default=None)</pre></p> + + Returns the value of an environment variable <code>name</code> as a string if exists, or <code>default</code> if it doesn't. <p>When building incrementally, any change to the value of the variable named by <code>name</code> will cause this repository to be re-fetched. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="getenv.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of desired environment variable. + </td> + </tr> + <tr> + <td id="getenv.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Default value to return if <code>name</code> is not found. + </td> + </tr> + </tbody> + </table> + May return <code>None</code>. + + <h2 id="is_dev_dependency">is_dev_dependency</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> module_ctx.is_dev_dependency(tag)</pre></p> + + Returns whether the given tag was specified on the result of a <a href="../globals/module.html#use_extension">use_extension</a> call with <code>devDependency = True</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="is_dev_dependency.tag"> + <code>tag</code> + </td> + <td> + bazel_module_tag; + required<br/> + A tag obtained from <a href="../builtins/bazel_module.html#tags">bazel_module.tags</a>. + </td> + </tr> + </tbody> + </table> + + <h2 id="modules">modules</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> module_ctx.modules</pre></p> + + A list of all the Bazel modules in the external dependency graph that use this module extension, each of which is a <a href="../builtins/bazel_module.html">bazel_module</a> object that exposes all the tags it specified for this extension. The iteration order of this dictionary is guaranteed to be the same as breadth-first search starting from the root module. + + <h2 id="os">os</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/repository_os.html">repository_os</a> module_ctx.os</pre></p> + + A struct to access information from the system. + + <h2 id="path">path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> module_ctx.path(path)</pre></p> + + Returns a path from a string, label, or path. If this context is a <code>repository_ctx</code>, a relative path will resolve relative to the repository directory. If it is a <code>module_ctx</code>, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="path.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + <code>string</code>, <code>Label</code> or <code>path</code> from which to create a path from. + </td> + </tr> + </tbody> + </table> + + <h2 id="read">read</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> module_ctx.read(path, *, watch='auto')</pre></p> + + Reads the content of a file on the filesystem. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="read.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the file to read from. + </td> + </tr> + <tr> + <td id="read.watch"> + <code>watch</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'auto'</code><br/> + Whether to <a href="#watch">watch</a> the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. + + </td> + </tr> + </tbody> + </table> + + <h2 id="report_progress">report_progress</h2> + <p><pre class="rule-signature"><code>None</code> module_ctx.report_progress(status='')</pre></p> + + Updates the progress status for the fetching of this repository or module extension. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="report_progress.status"> + <code>status</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + <code>string</code> describing the current status of the fetch progress. + </td> + </tr> + </tbody> + </table> + + <h2 id="root_module_has_non_dev_dependency">root_module_has_non_dev_dependency</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> module_ctx.root_module_has_non_dev_dependency</pre></p> + + Whether the root module uses this extension as a non-dev dependency. + + <h2 id="watch">watch</h2> + <p><pre class="rule-signature"><code>None</code> module_ctx.watch(path)</pre></p> + + Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time.<p>"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does <em>not</em> include changes to any files under the directory if the path is a directory. For that, use <a href="path.html#readdir"><code>path.readdir()</code></a> instead.<p>Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="watch.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the file to watch. + </td> + </tr> + </tbody> + </table> + + <h2 id="which">which</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> module_ctx.which(program)</pre></p> + + Returns the <code>path</code> of the corresponding program or <code>None</code> if there is no such program in the path. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="which.program"> + <code>program</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Program to find in the path. + </td> + </tr> + </tbody> + </table> + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/path.mdx b/rules/lib/builtins/path.mdx new file mode 100644 index 0000000..5e47bed --- /dev/null +++ b/rules/lib/builtins/path.mdx @@ -0,0 +1,144 @@ +--- +title: 'path' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.path">path</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkPath.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A structure representing a file to be used inside a repository. + +<h2>Members</h2> +<ul> + <li> + <a href="#basename">basename</a> + </li> + <li> + <a href="#dirname">dirname</a> + </li> + <li> + <a href="#exists">exists</a> + </li> + <li> + <a href="#get_child">get_child</a> + </li> + <li> + <a href="#is_dir">is_dir</a> + </li> + <li> + <a href="#readdir">readdir</a> + </li> + <li> + <a href="#realpath">realpath</a> + </li> + </ul> + + <h2 id="basename">basename</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> path.basename</pre></p> + + A string giving the basename of the file. + + <h2 id="dirname">dirname</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> path.dirname</pre></p> + + The parent directory of this file, or None if this file does not have a parent. + May return <code>None</code>. + + <h2 id="exists">exists</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> path.exists</pre></p> + + Returns true if the file or directory denoted by this path exists.<p>Note that accessing this field does <em>not</em> cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to the path's existence, use the <code>watch()</code> method on the context object. + + + <h2 id="get_child">get_child</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> path.get_child(*relative_paths)</pre></p> + + Returns the path obtained by joining this path with the given relative paths. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="get_child.relative_paths"> + <code>relative_paths</code> + </td> + <td> + required<br/> + Zero or more relative path strings to append to this path with path separators added as needed. + + </td> + </tr> + </tbody> + </table> + + <h2 id="is_dir">is_dir</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> path.is_dir</pre></p> + + Returns true if this path points to a directory.<p>Note that accessing this field does <em>not</em> cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to whether the path is a directory or a file, use the <code>watch()</code> method on the context object. + + + <h2 id="readdir">readdir</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> path.readdir(*, watch='auto')</pre></p> + + Returns the list of entries in the directory denoted by this path. Each entry is a <code>path</code> object itself. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="readdir.watch"> + <code>watch</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'auto'</code><br/> + whether Bazel should watch the list of entries in this directory and refetch the repository or re-evaluate the module extension next time when any changes are detected. Changes to detect include entry creation, deletion, and renaming. Note that this doesn't watch the <em>contents</em> of any entries in the directory.<p>Can be the string 'yes', 'no', or 'auto'. If set to 'auto', Bazel will only watch this directory when it is legal to do so (see <a href="repository_ctx.html#watch"><code>repository_ctx.watch()</code></a> docs for more information). + + </td> + </tr> + </tbody> + </table> + + <h2 id="realpath">realpath</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> path.realpath</pre></p> + + Returns the canonical path for this path by repeatedly replacing all symbolic links with their referents. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/propagation_ctx.mdx b/rules/lib/builtins/propagation_ctx.mdx new file mode 100644 index 0000000..7caad00 --- /dev/null +++ b/rules/lib/builtins/propagation_ctx.mdx @@ -0,0 +1,44 @@ +--- +title: 'propagation_ctx' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.propagation_ctx">propagation_ctx</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectPropagationContextApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A context object that is passed to the <code>propagation_predicate</code>, <code>attr_aspects</code> and <code>toolchains_aspects</code> functions of aspects. It provides access to the information needed to determine whether the aspect should be propagated to the target and what attributes or toolchain types it should be propagated to next. + +<h2>Members</h2> +<ul> + <li> + <a href="#attr">attr</a> + </li> + <li> + <a href="#rule">rule</a> + </li> + </ul> + + <h2 id="attr">attr</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> propagation_ctx.attr</pre></p> + + A struct to access only the public parameters of the aspect. The keys and values of the struct are the parameters names and values. + + <h2 id="rule">rule</h2> + <p><pre class="rule-signature">StarlarkAspectPropagationRuleApi propagation_ctx.rule</pre></p> + + Allows access to the details of the rule. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/repo_metadata.mdx b/rules/lib/builtins/repo_metadata.mdx new file mode 100644 index 0000000..7220273 --- /dev/null +++ b/rules/lib/builtins/repo_metadata.mdx @@ -0,0 +1,26 @@ +--- +title: 'repo_metadata' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.repo_metadata">repo_metadata</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/RepoMetadata.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +See <a href="repository_ctx#repo_metadata"><code>repository_ctx.repo_metadata</code></a>. + + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/repository_ctx.mdx b/rules/lib/builtins/repository_ctx.mdx new file mode 100644 index 0000000..1e538a8 --- /dev/null +++ b/rules/lib/builtins/repository_ctx.mdx @@ -0,0 +1,1169 @@ +--- +title: 'repository_ctx' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.repository_ctx">repository_ctx</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryContext.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The context of the repository rule containing helper functions and information about attributes. You get a repository_ctx object as an argument to the <code>implementation</code> function when you create a repository rule. + + +<h2>Members</h2> +<ul> + <li> + <a href="#attr">attr</a> + </li> + <li> + <a href="#delete">delete</a> + </li> + <li> + <a href="#download">download</a> + </li> + <li> + <a href="#download_and_extract">download_and_extract</a> + </li> + <li> + <a href="#execute">execute</a> + </li> + <li> + <a href="#extract">extract</a> + </li> + <li> + <a href="#file">file</a> + </li> + <li> + <a href="#getenv">getenv</a> + </li> + <li> + <a href="#name">name</a> + </li> + <li> + <a href="#original_name">original_name</a> + </li> + <li> + <a href="#os">os</a> + </li> + <li> + <a href="#patch">patch</a> + </li> + <li> + <a href="#path">path</a> + </li> + <li> + <a href="#read">read</a> + </li> + <li> + <a href="#rename">rename</a> + </li> + <li> + <a href="#repo_metadata">repo_metadata</a> + </li> + <li> + <a href="#report_progress">report_progress</a> + </li> + <li> + <a href="#symlink">symlink</a> + </li> + <li> + <a href="#template">template</a> + </li> + <li> + <a href="#watch">watch</a> + </li> + <li> + <a href="#watch_tree">watch_tree</a> + </li> + <li> + <a href="#which">which</a> + </li> + <li> + <a href="#workspace_root">workspace_root</a> + </li> + </ul> + + <h2 id="attr">attr</h2> + <p><pre class="rule-signature">structure repository_ctx.attr</pre></p> + + A struct to access the values of the attributes. The values are provided by the user (if not, a default value is used). + + + <h2 id="delete">delete</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> repository_ctx.delete(path)</pre></p> + + Deletes a file or a directory. Returns a bool, indicating whether the file or directory was actually deleted by this call. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="delete.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string. + + </td> + </tr> + </tbody> + </table> + + <h2 id="download">download</h2> + <p><pre class="rule-signature">unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True)</pre></p> + + Downloads a file to the output path for the provided url and returns a struct containing <code>success</code>, a flag which is <code>true</code> if the download completed successfully, and if successful, a hash of the file with the fields <code>sha256</code> and <code>integrity</code>. When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit <code>canonical_id</code> is highly recommended. e.g. <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="download.url"> + <code>url</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or Iterable of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + List of mirror URLs referencing the same file. + </td> + </tr> + <tr> + <td id="download.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + default is <code>''</code><br/> + path to the output file, relative to the repository directory. + </td> + </tr> + <tr> + <td id="download.sha256"> + <code>sha256</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + </td> + </tr> + <tr> + <td id="download.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Set the executable flag on the created file, false by default. + </td> + </tr> + <tr> + <td id="download.allow_fail"> + <code>allow_fail</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If set, indicate the error in the return value instead of raising an error for failed downloads. + + </td> + </tr> + <tr> + <td id="download.canonical_id"> + <code>canonical_id</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (<code>sha256</code> or <code>integrity</code>). + + </td> + </tr> + <tr> + <td id="download.auth"> + <code>auth</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying authentication information for some of the URLs. + </td> + </tr> + <tr> + <td id="download.headers"> + <code>headers</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying http headers for all URLs. + </td> + </tr> + <tr> + <td id="download.integrity"> + <code>integrity</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + </td> + </tr> + <tr> + <td id="download.block"> + <code>block</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. + + </td> + </tr> + </tbody> + </table> + + <h2 id="download_and_extract">download_and_extract</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={})</pre></p> + + Downloads a file to the output path for the provided url, extracts it, and returns a struct containing <code>success</code>, a flag which is <code>true</code> if the download completed successfully, and if successful, a hash of the file with the fields <code>sha256</code> and <code>integrity</code>. When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit <code>canonical_id</code> is highly recommended. e.g. <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="download_and_extract.url"> + <code>url</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or Iterable of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + List of mirror URLs referencing the same file. + </td> + </tr> + <tr> + <td id="download_and_extract.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + default is <code>''</code><br/> + Path to the directory where the archive will be unpacked, relative to the repository directory. + + </td> + </tr> + <tr> + <td id="download_and_extract.sha256"> + <code>sha256</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + </td> + </tr> + <tr> + <td id="download_and_extract.type"> + <code>type</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. + + </td> + </tr> + <tr> + <td id="download_and_extract.strip_prefix"> + <code>strip_prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + A directory prefix to strip from the extracted files. Many archives contain a +top-level directory that contains all files in the archive. Instead of needing to +specify this prefix over and over in the <code>build_file</code>, this field can +be used to strip it from extracted files. + +<p>For compatibility, this parameter may also be used under the deprecated name +<code>stripPrefix</code>. + + </td> + </tr> + <tr> + <td id="download_and_extract.allow_fail"> + <code>allow_fail</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If set, indicate the error in the return value instead of raising an error for failed downloads. + + </td> + </tr> + <tr> + <td id="download_and_extract.canonical_id"> + <code>canonical_id</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum +(<code>sha256</code> or <code>integrity</code>). + + </td> + </tr> + <tr> + <td id="download_and_extract.auth"> + <code>auth</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying authentication information for some of the URLs. + </td> + </tr> + <tr> + <td id="download_and_extract.headers"> + <code>headers</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying http headers for all URLs. + </td> + </tr> + <tr> + <td id="download_and_extract.integrity"> + <code>integrity</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + </td> + </tr> + <tr> + <td id="download_and_extract.rename_files"> + <code>rename_files</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. + + </td> + </tr> + </tbody> + </table> + + <h2 id="execute">execute</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/exec_result.html">exec_result</a> repository_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="")</pre></p> + + Executes the command given by the list of arguments. The execution time of the command is limited by <code>timeout</code> (in seconds, default 600 seconds). This method returns an <code>exec_result</code> structure containing the output of the command. The <code>environment</code> map can be used to override some environment variables to be passed to the process. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="execute.arguments"> + <code>arguments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + required<br/> + List of arguments, the first element should be the path to the program to execute. + + </td> + </tr> + <tr> + <td id="execute.timeout"> + <code>timeout</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>600</code><br/> + Maximum duration of the command in seconds (default is 600 seconds). + </td> + </tr> + <tr> + <td id="execute.environment"> + <code>environment</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + Force some environment variables to be set to be passed to the process. The value can be <code>None</code> to remove the environment variable. + + </td> + </tr> + <tr> + <td id="execute.quiet"> + <code>quiet</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + If stdout and stderr should be printed to the terminal. + </td> + </tr> + <tr> + <td id="execute.working_directory"> + <code>working_directory</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>""</code><br/> + Working directory for command execution. +Can be relative to the repository root or absolute. +The default is the repository root. + + </td> + </tr> + </tbody> + </table> + + <h2 id="extract">extract</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto')</pre></p> + + Extract an archive to the repository directory. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="extract.archive"> + <code>archive</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + path to the archive that will be unpacked, relative to the repository directory. + </td> + </tr> + <tr> + <td id="extract.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + default is <code>''</code><br/> + path to the directory where the archive will be unpacked, relative to the repository directory. + </td> + </tr> + <tr> + <td id="extract.strip_prefix"> + <code>strip_prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + a directory prefix to strip from the extracted files. Many archives contain a +top-level directory that contains all files in the archive. Instead of needing to +specify this prefix over and over in the <code>build_file</code>, this field can be +used to strip it from extracted files. + +<p>For compatibility, this parameter may also be used under the deprecated name +<code>stripPrefix</code>. + + </td> + </tr> + <tr> + <td id="extract.rename_files"> + <code>rename_files</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. + </td> + </tr> + <tr> + <td id="extract.watch_archive"> + <code>watch_archive</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'auto'</code><br/> + whether to <a href="#watch">watch</a> the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. + </td> + </tr> + </tbody> + </table> + + <h2 id="file">file</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.file(path, content='', executable=True, legacy_utf8=False)</pre></p> + + Generates a file in the repository directory with the provided content. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="file.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the file to create, relative to the repository directory. + </td> + </tr> + <tr> + <td id="file.content"> + <code>content</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The content of the file to create, empty by default. + </td> + </tr> + <tr> + <td id="file.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + Set the executable flag on the created file, true by default. + </td> + </tr> + <tr> + <td id="file.legacy_utf8"> + <code>legacy_utf8</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + No-op. This parameter is deprecated and will be removed in a future version of Bazel. + + </td> + </tr> + </tbody> + </table> + + <h2 id="getenv">getenv</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_ctx.getenv(name, default=None)</pre></p> + + Returns the value of an environment variable <code>name</code> as a string if exists, or <code>default</code> if it doesn't. <p>When building incrementally, any change to the value of the variable named by <code>name</code> will cause this repository to be re-fetched. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="getenv.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of desired environment variable. + </td> + </tr> + <tr> + <td id="getenv.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Default value to return if <code>name</code> is not found. + </td> + </tr> + </tbody> + </table> + May return <code>None</code>. + + <h2 id="name">name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_ctx.name</pre></p> + + The canonical name of the external repository created by this rule. This name is guaranteed to be unique among all external repositories, but its exact format is not specified. Use <a href='#original_name'><code>original_name</code></a> instead to get the name that was originally specified as the <code>name</code> when this repository rule was instantiated. + + <h2 id="original_name">original_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_ctx.original_name</pre></p> + + The name that was originally specified as the <code>name</code> attribute when this repository rule was instantiated. This name is not necessarily unique among external repositories. Use <a href='#name'><code>name</code></a> instead to get the canonical name of the external repository. + + <h2 id="os">os</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/repository_os.html">repository_os</a> repository_ctx.os</pre></p> + + A struct to access information from the system. + + <h2 id="patch">patch</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.patch(patch_file, strip=0, *, watch_patch='auto')</pre></p> + + Apply a patch file to the root directory of external repository. The patch file should be a standard <a href="https://en.wikipedia.org/wiki/Diff#Unified_format"> unified diff format</a> file. The Bazel-native patch implementation doesn't support fuzz match and binary patch like the patch command line tool. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="patch.patch_file"> + <code>patch_file</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + The patch file to apply, it can be label, relative path or absolute path. If it's a relative path, it will resolve to the repository directory. + + </td> + </tr> + <tr> + <td id="patch.strip"> + <code>strip</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>0</code><br/> + Strip the specified number of leading components from file names. + </td> + </tr> + <tr> + <td id="patch.watch_patch"> + <code>watch_patch</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'auto'</code><br/> + Whether to <a href="#watch">watch</a> the patch file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. + + </td> + </tr> + </tbody> + </table> + + <h2 id="path">path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> repository_ctx.path(path)</pre></p> + + Returns a path from a string, label, or path. If this context is a <code>repository_ctx</code>, a relative path will resolve relative to the repository directory. If it is a <code>module_ctx</code>, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="path.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + <code>string</code>, <code>Label</code> or <code>path</code> from which to create a path from. + </td> + </tr> + </tbody> + </table> + + <h2 id="read">read</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_ctx.read(path, *, watch='auto')</pre></p> + + Reads the content of a file on the filesystem. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="read.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the file to read from. + </td> + </tr> + <tr> + <td id="read.watch"> + <code>watch</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'auto'</code><br/> + Whether to <a href="#watch">watch</a> the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. + + </td> + </tr> + </tbody> + </table> + + <h2 id="rename">rename</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.rename(src, dst)</pre></p> + + Renames the file or directory from <code>src</code> to <code>dst</code>. Parent directories are created as needed. Fails if the destination path +already exists. Both paths must be located within the repository. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="rename.src"> + <code>src</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + The path of the existing file or directory to rename, relative +to the repository directory. + + </td> + </tr> + <tr> + <td id="rename.dst"> + <code>dst</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + The new name to which the file or directory will be renamed to, +relative to the repository directory. + + </td> + </tr> + </tbody> + </table> + + <h2 id="repo_metadata">repo_metadata</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/repo_metadata.html">repo_metadata</a> repository_ctx.repo_metadata(*, reproducible=False, attrs_for_reproducibility={})</pre></p> + + Constructs an opaque object that can be returned from the repo rule's implementation function to provide metadata about its reproducibility. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="repo_metadata.reproducible"> + <code>reproducible</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + States that this repo can be reproducibly refetched; that is, if it were fetched another time with exactly the same input attributes, repo rule definition, watched files and environment variables, etc., then exactly the same output would be produced. This property needs to hold even if other untracked conditions change, such as information from the internet, the path of the workspace root, output from running arbitrary executables, etc. If set to True, this allows the fetched repo contents to be cached across workspaces. <p>Note that setting this to True does not guarantee caching in the repo contents cache; for example, local repo rules are never cached. + + </td> + </tr> + <tr> + <td id="repo_metadata.attrs_for_reproducibility"> + <code>attrs_for_reproducibility</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + If <code>reproducible</code> is False, this can be specified to tell Bazel which attributes of the original repo rule to change to make it reproducible. + + </td> + </tr> + </tbody> + </table> + + <h2 id="report_progress">report_progress</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.report_progress(status='')</pre></p> + + Updates the progress status for the fetching of this repository or module extension. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="report_progress.status"> + <code>status</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + <code>string</code> describing the current status of the fetch progress. + </td> + </tr> + </tbody> + </table> + + <h2 id="symlink">symlink</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.symlink(target, link_name)</pre></p> + + Creates a symlink on the filesystem. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="symlink.target"> + <code>target</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + The path that the symlink should point to. + </td> + </tr> + <tr> + <td id="symlink.link_name"> + <code>link_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + The path of the symlink to create. + </td> + </tr> + </tbody> + </table> + + <h2 id="template">template</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.template(path, template, substitutions={}, executable=True, *, watch_template='auto')</pre></p> + + Generates a new file using a <code>template</code>. Every occurrence in <code>template</code> of a key of <code>substitutions</code> will be replaced by the corresponding value. The result is written in <code>path</code>. An optional <code>executable</code> argument (default to true) can be set to turn on or off the executable bit. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="template.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the file to create, relative to the repository directory. + </td> + </tr> + <tr> + <td id="template.template"> + <code>template</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path to the template file. + </td> + </tr> + <tr> + <td id="template.substitutions"> + <code>substitutions</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + Substitutions to make when expanding the template. + </td> + </tr> + <tr> + <td id="template.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + Set the executable flag on the created file, true by default. + </td> + </tr> + <tr> + <td id="template.watch_template"> + <code>watch_template</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'auto'</code><br/> + Whether to <a href="#watch">watch</a> the template file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. + + </td> + </tr> + </tbody> + </table> + + <h2 id="watch">watch</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.watch(path)</pre></p> + + Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time.<p>"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does <em>not</em> include changes to any files under the directory if the path is a directory. For that, use <a href="path.html#readdir"><code>path.readdir()</code></a> instead.<p>Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="watch.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the file to watch. + </td> + </tr> + </tbody> + </table> + + <h2 id="watch_tree">watch_tree</h2> + <p><pre class="rule-signature"><code>None</code> repository_ctx.watch_tree(path)</pre></p> + + Tells Bazel to watch for changes to any files or directories transitively under the given path. Any changes to the contents of files, the existence of files or directories, file names or directory names, will cause this repo to be refetched.<p>Note that attempting to watch paths inside the repo currently being fetched will result in an error. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="watch_tree.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; + required<br/> + Path of the directory tree to watch. + </td> + </tr> + </tbody> + </table> + + <h2 id="which">which</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> repository_ctx.which(program)</pre></p> + + Returns the <code>path</code> of the corresponding program or <code>None</code> if there is no such program in the path. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="which.program"> + <code>program</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Program to find in the path. + </td> + </tr> + </tbody> + </table> + May return <code>None</code>. + + <h2 id="workspace_root">workspace_root</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> repository_ctx.workspace_root</pre></p> + + The path to the root workspace of the bazel invocation. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/repository_os.mdx b/rules/lib/builtins/repository_os.mdx new file mode 100644 index 0000000..debe4c8 --- /dev/null +++ b/rules/lib/builtins/repository_os.mdx @@ -0,0 +1,55 @@ +--- +title: 'repository_os' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.repository_os">repository_os</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkOS.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Various data about the current platform Bazel is running on. + +<h2>Members</h2> +<ul> + <li> + <a href="#arch">arch</a> + </li> + <li> + <a href="#environ">environ</a> + </li> + <li> + <a href="#name">name</a> + </li> + </ul> + + <h2 id="arch">arch</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_os.arch</pre></p> + + A string identifying the architecture Bazel is running on (the value of the <code>"os.arch"</code> Java property converted to lower case). + + + <h2 id="environ">environ</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> repository_os.environ</pre></p> + + The dictionary of environment variables. <p><b>NOTE</b>: Retrieving an environment variable from this dictionary does not establish a dependency from a repository rule or module extension to the environment variable. To establish a dependency when looking up an environment variable, use either <code>repository_ctx.getenv</code> or <code>module_ctx.getenv</code> instead. + + + <h2 id="name">name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_os.name</pre></p> + + A string identifying the operating system Bazel is running on (the value of the <code>"os.name"</code> Java property converted to lower case). + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/repository_rule.mdx b/rules/lib/builtins/repository_rule.mdx new file mode 100644 index 0000000..79db2a3 --- /dev/null +++ b/rules/lib/builtins/repository_rule.mdx @@ -0,0 +1,26 @@ +--- +title: 'repository_rule' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.repository_rule">repository_rule</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A callable value that may be invoked within the implementation function of a module extension to instantiate and return a repository rule. Created by <a href="../globals/bzl.html#repository_rule"><code>repository_rule()</code></a>. + + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/root.mdx b/rules/lib/builtins/root.mdx new file mode 100644 index 0000000..08e3e50 --- /dev/null +++ b/rules/lib/builtins/root.mdx @@ -0,0 +1,36 @@ +--- +title: 'root' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.root">root</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileRootApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A root for files. The roots are the directories containing files, and they are mapped together into a single directory tree to form the execution environment. + +<h2>Members</h2> +<ul> + <li> + <a href="#path">path</a> + </li> + </ul> + + <h2 id="path">path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> root.path</pre></p> + + Returns the relative path from the exec root to the actual root. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/rule.mdx b/rules/lib/builtins/rule.mdx new file mode 100644 index 0000000..7c6069e --- /dev/null +++ b/rules/lib/builtins/rule.mdx @@ -0,0 +1,30 @@ +--- +title: 'rule' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.rule">rule</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RuleFunctionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A callable value representing the type of a native or Starlark rule (created by +<a href="../globals/bzl.html#rule"><code>rule()</code></a>). Calling the value during +evaluation of a package's BUILD file creates an instance of the rule and adds it to the +package's target set. For more information, visit this page about +<a href ="https://bazel.build/extending/rules">Rules</a>. + + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/rule_attributes.mdx b/rules/lib/builtins/rule_attributes.mdx new file mode 100644 index 0000000..8b444c4 --- /dev/null +++ b/rules/lib/builtins/rule_attributes.mdx @@ -0,0 +1,92 @@ +--- +title: 'rule_attributes' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.rule_attributes">rule_attributes</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttributesCollectionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Information about attributes of a rule an aspect is applied to. + +<h2>Members</h2> +<ul> + <li> + <a href="#attr">attr</a> + </li> + <li> + <a href="#exec_groups">exec_groups</a> + </li> + <li> + <a href="#executable">executable</a> + </li> + <li> + <a href="#file">file</a> + </li> + <li> + <a href="#files">files</a> + </li> + <li> + <a href="#kind">kind</a> + </li> + <li> + <a href="#toolchains">toolchains</a> + </li> + <li> + <a href="#var">var</a> + </li> + </ul> + + <h2 id="attr">attr</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> rule_attributes.attr</pre></p> + + A struct to access the values of the <a href='https://bazel.build/extending/rules#attributes'>attributes</a>. The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the <a href='../globals/bzl.html#rule.attrs'><code>attrs</code> dict</a> provided to the <a href='../globals/bzl.html#rule'><code>rule</code> function</a>. <a href="https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl">See example of use</a>. + + <h2 id="exec_groups">exec_groups</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/ExecGroupCollection.html">ExecGroupCollection</a> rule_attributes.exec_groups</pre></p> + + A collection of the execution groups available for the rule the aspect is applied to, indexed by their names. + + <h2 id="executable">executable</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> rule_attributes.executable</pre></p> + + A <code>struct</code> containing executable files defined in <a href='../toplevel/attr.html#label'>label type attributes</a> marked as <a href='../toplevel/attr.html#label.executable'><code>executable=True</code></a>. The struct fields correspond to the attribute names. Each value in the struct is either a <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an optional attribute is not specified in the rule then the corresponding struct value is <code>None</code>. If a label type is not marked as <code>executable=True</code>, no corresponding struct field is generated. <a href="https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl">See example of use</a>. + + <h2 id="file">file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> rule_attributes.file</pre></p> + + A <code>struct</code> containing files defined in <a href='../toplevel/attr.html#label'>label type attributes</a> marked as <a href='../toplevel/attr.html#label.allow_single_file'><code>allow_single_file</code></a>. The struct fields correspond to the attribute names. The struct value is always a <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an optional attribute is not specified in the rule then the corresponding struct value is <code>None</code>. If a label type is not marked as <code>allow_single_file</code>, no corresponding struct field is generated. It is a shortcut for:<pre class=language-python>list(ctx.attr.<ATTR>.files)[0]</pre>In other words, use <code>file</code> to access the (singular) <a href="https://bazel.build/extending/rules#requesting_output_files">default output</a> of a dependency. <a href="https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl">See example of use</a>. + + <h2 id="files">files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> rule_attributes.files</pre></p> + + A <code>struct</code> containing files defined in <a href='../toplevel/attr.html#label'>label</a> or <a href='../toplevel/attr.html#label_list'>label list</a> type attributes. The struct fields correspond to the attribute names. The struct values are <code>list</code> of <a href='../builtins/File.html'><code>File</code></a>s. It is a shortcut for:<pre class=language-python>[f for t in ctx.attr.<ATTR> for f in t.files]</pre> In other words, use <code>files</code> to access the <a href="https://bazel.build/extending/rules#requesting_output_files"> default outputs</a> of a dependency. <a href="https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl">See example of use</a>. + + <h2 id="kind">kind</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> rule_attributes.kind</pre></p> + + The kind of a rule, such as 'cc_library' + + <h2 id="toolchains">toolchains</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/ToolchainContext.html">ToolchainContext</a> rule_attributes.toolchains</pre></p> + + Toolchains for the default exec group of the rule the aspect is applied to. + + <h2 id="var">var</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> rule_attributes.var</pre></p> + + Dictionary (String to String) of configuration variables. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/runfiles.mdx b/rules/lib/builtins/runfiles.mdx new file mode 100644 index 0000000..0333826 --- /dev/null +++ b/rules/lib/builtins/runfiles.mdx @@ -0,0 +1,136 @@ +--- +title: 'runfiles' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.runfiles">runfiles</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A container of information regarding a set of files required at runtime by an executable. This object should be passed via <a href="../providers/DefaultInfo.html"><code>DefaultInfo</code></a> in order to tell the build system about the runfiles needed by the outputs produced by the rule. +<p> + See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a> for details. </p> + + +<h2>Members</h2> +<ul> + <li> + <a href="#empty_filenames">empty_filenames</a> + </li> + <li> + <a href="#files">files</a> + </li> + <li> + <a href="#merge">merge</a> + </li> + <li> + <a href="#merge_all">merge_all</a> + </li> + <li> + <a href="#root_symlinks">root_symlinks</a> + </li> + <li> + <a href="#symlinks">symlinks</a> + </li> + </ul> + + <h2 id="empty_filenames">empty_filenames</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> runfiles.empty_filenames</pre></p> + + Returns names of empty files to create. + + <h2 id="files">files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> runfiles.files</pre></p> + + Returns the set of runfiles as files. + + <h2 id="merge">merge</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> runfiles.merge(other)</pre></p> + + Returns a new runfiles object that includes all the contents of this one and the argument. <p> +<i>Note:</i> When you have many runfiles objects to merge, use <a href="#merge_all"><code>merge_all()</code></a> rather than calling <code>merge</code> in a loop. This avoids constructing deep depset structures which can cause build failures. </p> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="merge.other"> + <code>other</code> + </td> + <td> + <a class="anchor" href="../builtins/runfiles.html">runfiles</a>; + required<br/> + The runfiles object to merge into this. + </td> + </tr> + </tbody> + </table> + + <h2 id="merge_all">merge_all</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> runfiles.merge_all(other)</pre></p> + + Returns a new runfiles object that includes all the contents of this one and of the runfiles objects in the argument. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="merge_all.other"> + <code>other</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/runfiles.html">runfiles</a>s; + required<br/> + The sequence of runfiles objects to merge into this. + </td> + </tr> + </tbody> + </table> + + <h2 id="root_symlinks">root_symlinks</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> runfiles.root_symlinks</pre></p> + + Returns the set of root symlinks. + + <h2 id="symlinks">symlinks</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> runfiles.symlinks</pre></p> + + Returns the set of symlinks. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/struct.mdx b/rules/lib/builtins/struct.mdx new file mode 100644 index 0000000..66a4b38 --- /dev/null +++ b/rules/lib/builtins/struct.mdx @@ -0,0 +1,63 @@ +--- +title: 'struct' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.struct">struct</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/StructApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A generic object with fields.<p>Structs fields cannot be reassigned once the struct is created. Two structs are equal if they have the same fields and if corresponding field values are equal. + +<h2>Members</h2> +<ul> + <li> + <a href="#struct">struct</a> + </li> + </ul> + + <h2 id="struct">struct</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> struct(**kwargs)</pre></p> + + Creates an immutable struct using the keyword arguments as attributes. It is used to group multiple values together. Example:<br><pre class="language-python">s = struct(x = 2, y = 3) +return s.x + getattr(s, "y") # returns 5</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="struct.kwargs"> + <code>kwargs</code> + </td> + <td> + default is <code>{}</code><br/> + Dictionary of arguments. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/subrule_ctx.mdx b/rules/lib/builtins/subrule_ctx.mdx new file mode 100644 index 0000000..c28d21d --- /dev/null +++ b/rules/lib/builtins/subrule_ctx.mdx @@ -0,0 +1,60 @@ +--- +title: 'subrule_ctx' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.subrule_ctx">subrule_ctx</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkSubrule.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A context object passed to the implementation function of a subrule. + +<h2>Members</h2> +<ul> + <li> + <a href="#actions">actions</a> + </li> + <li> + <a href="#fragments">fragments</a> + </li> + <li> + <a href="#label">label</a> + </li> + <li> + <a href="#toolchains">toolchains</a> + </li> + </ul> + + <h2 id="actions">actions</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/actions.html">actions</a> subrule_ctx.actions</pre></p> + + Contains methods for declaring output files and the actions that produce them + + <h2 id="fragments">fragments</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/fragments.html">fragments</a> subrule_ctx.fragments</pre></p> + + Allows access to configuration fragments in target configuration. + + <h2 id="label">label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> subrule_ctx.label</pre></p> + + The label of the target currently being analyzed + + <h2 id="toolchains">toolchains</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/ToolchainContext.html">ToolchainContext</a> subrule_ctx.toolchains</pre></p> + + Contains methods for declaring output files and the actions that produce them + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/tag_class.mdx b/rules/lib/builtins/tag_class.mdx new file mode 100644 index 0000000..07f5547 --- /dev/null +++ b/rules/lib/builtins/tag_class.mdx @@ -0,0 +1,26 @@ +--- +title: 'tag_class' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.tag_class">tag_class</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Defines a schema of attributes for a tag, created by <a href="../globals/bzl.html#tag_class"><code>tag_class()</code></a>. + + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/template_ctx.mdx b/rules/lib/builtins/template_ctx.mdx new file mode 100644 index 0000000..bd42877 --- /dev/null +++ b/rules/lib/builtins/template_ctx.mdx @@ -0,0 +1,175 @@ +--- +title: 'template_ctx' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.template_ctx">template_ctx</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkTemplateContextApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A context object that is passed to the action template expansion function. + +<h2>Members</h2> +<ul> + <li> + <a href="#args">args</a> + </li> + <li> + <a href="#declare_file">declare_file</a> + </li> + <li> + <a href="#run">run</a> + </li> + </ul> + + <h2 id="args">args</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> template_ctx.args()</pre></p> + + Returns an Args object that can be used to build memory-efficient command lines. + + <h2 id="declare_file">declare_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> template_ctx.declare_file(filename, *, directory)</pre></p> + + Declares that implementation creates a file with the given filename within the specified directory.<p>Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned <code>File</code> object to the action's construction function. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="declare_file.filename"> + <code>filename</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The relative path of the file within the directory. + </td> + </tr> + <tr> + <td id="declare_file.directory"> + <code>directory</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The directory in which the file should be created. + </td> + </tr> + </tbody> + </table> + + <h2 id="run">run</h2> + <p><pre class="rule-signature"><code>None</code> template_ctx.run(*, outputs, inputs=[], executable, tools=None, arguments=[], progress_message=None)</pre></p> + + Creates an action that runs an executable. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="run.outputs"> + <code>outputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + required<br/> + List of the output files of the action. + </td> + </tr> + <tr> + <td id="run.inputs"> + <code>inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>[]</code><br/> + List or depset of the input files of the action. + </td> + </tr> + <tr> + <td id="run.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a>; + required<br/> + The executable file to be called by the action. + </td> + </tr> + <tr> + <td id="run.tools"> + <code>tools</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. <p> +When a list is provided, it can be a heterogenous collection of: +<ul> + <li><code>File</code>s</li> + <li><code>FilesToRunProvider</code> instances</li> + <li><code>depset</code>s of <code>File</code>s</li> +</ul> +<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. +</p> + + </td> + </tr> + <tr> + <td id="run.arguments"> + <code>arguments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects. + </td> + </tr> + <tr> + <td id="run.progress_message"> + <code>progress_message</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Progress message to show to the user during the build. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/toolchain_type.mdx b/rules/lib/builtins/toolchain_type.mdx new file mode 100644 index 0000000..490100e --- /dev/null +++ b/rules/lib/builtins/toolchain_type.mdx @@ -0,0 +1,44 @@ +--- +title: 'toolchain_type' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.toolchain_type">toolchain_type</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkToolchainTypeRequirement.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A data type describing a dependency on a specific toolchain type. + +<h2>Members</h2> +<ul> + <li> + <a href="#mandatory">mandatory</a> + </li> + <li> + <a href="#toolchain_type">toolchain_type</a> + </li> + </ul> + + <h2 id="mandatory">mandatory</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> toolchain_type.mandatory</pre></p> + + Whether the toolchain type is mandatory or optional. + + <h2 id="toolchain_type">toolchain_type</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> toolchain_type.toolchain_type</pre></p> + + The toolchain type that is required. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/transition.mdx b/rules/lib/builtins/transition.mdx new file mode 100644 index 0000000..cd002fc --- /dev/null +++ b/rules/lib/builtins/transition.mdx @@ -0,0 +1,94 @@ +--- +title: 'transition' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.transition">transition</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigurationTransitionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +<p>Represents a configuration transition across a dependency edge. For example, if <code>//package:foo</code> depends on <code>//package:bar</code> with a configuration transition, then the configuration of <code>//package:bar</code> (and its dependencies) will be <code>//package:foo</code>'s configuration plus the changes specified by the transition function. + +<h2>Members</h2> +<ul> + <li> + <a href="#transition">transition</a> + </li> + </ul> + + <h2 id="transition">transition</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> transition(*, implementation, inputs, outputs)</pre></p> + + A transition that reads a set of input build settings and writes a set of output build settings.<p>Example:</p><p><pre class="language-python"> +def _transition_impl(settings, attr): + # This transition just reads the current CPU value as a demonstration. + # A real transition could incorporate this into its followup logic. + current_cpu = settings["//command_line_option:cpu"] + return {"//command_line_option:compilation_mode": "dbg"} + +build_in_debug_mode = transition( + implementation = _transition_impl, + inputs = ["//command_line_option:cpu"], + outputs = ["//command_line_option:compilation_mode"], +)</pre></p><p>For more details see <a href="https://bazel.build/rules/config#user-defined-transitions">here</a>.</p> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="transition.implementation"> + <code>implementation</code> + </td> + <td> + callable; + required<br/> + The function implementing this transition. This function always has two parameters: <code>settings</code> and <code>attr</code>. The <code>settings</code> param is a dictionary whose set of keys is defined by the inputs parameter. So, for each build setting <code>--//foo=bar</code>, if <code>inputs</code> contains <code>//foo</code>, <code>settings</code> will have an entry <code>settings['//foo']='bar'</code>.<p>The <code>attr</code> param is a reference to <code>ctx.attr</code>. This gives the implementation function access to the rule's attributes to make attribute-parameterized transitions possible.<p>This function must return a <code>dict</code> from build setting identifier to build setting value; this represents the configuration transition: for each entry in the returned <code>dict</code>, the transition updates that setting to the new value. All other settings are unchanged. This function can also return a <code>list</code> of <code>dict</code>s or a <code>dict</code> of <code>dict</code>s in the case of a split transition. + </td> + </tr> + <tr> + <td id="transition.inputs"> + <code>inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + List of build settings that can be read by this transition. This becomes the key set of the settings parameter of the implementation function parameter. + </td> + </tr> + <tr> + <td id="transition.outputs"> + <code>outputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + List of build settings that can be written by this transition. This must be a superset of the key set of the dictionary returned by this transition. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/wasm_exec_result.mdx b/rules/lib/builtins/wasm_exec_result.mdx new file mode 100644 index 0000000..b598a24 --- /dev/null +++ b/rules/lib/builtins/wasm_exec_result.mdx @@ -0,0 +1,60 @@ +--- +title: 'wasm_exec_result' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.wasm_exec_result">wasm_exec_result</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkWasmExecutionResult.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The result of executing a WebAssembly function with +<code>repository_ctx.execute_wasm()</code>. It contains the function's +return value and output buffer. + +<p>If execution failed before the function returned then the return code will be negative +and the <code>error_message</code> field will be set. + + +<h2>Members</h2> +<ul> + <li> + <a href="#error_message">error_message</a> + </li> + <li> + <a href="#output">output</a> + </li> + <li> + <a href="#return_code">return_code</a> + </li> + </ul> + + <h2 id="error_message">error_message</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> wasm_exec_result.error_message</pre></p> + + Contains an error message if execution failed before the function returned. + + <h2 id="output">output</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> wasm_exec_result.output</pre></p> + + The content of the output buffer returned by the WebAssembly function. + + <h2 id="return_code">return_code</h2> + <p><pre class="rule-signature">long wasm_exec_result.return_code</pre></p> + + The return value of the WebAssembly function, or a negative value if execution +was terminated before the function returned. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/builtins/wasm_module.mdx b/rules/lib/builtins/wasm_module.mdx new file mode 100644 index 0000000..24c8de3 --- /dev/null +++ b/rules/lib/builtins/wasm_module.mdx @@ -0,0 +1,36 @@ +--- +title: 'wasm_module' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.wasm_module">wasm_module</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkWasmModule.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A WebAssembly module loaded by <code>repository_ctx.load_wasm()</code>. + +<h2>Members</h2> +<ul> + <li> + <a href="#path">path</a> + </li> + </ul> + + <h2 id="path">path</h2> + <p><pre class="rule-signature">unknown wasm_module.path</pre></p> + + The path this WebAssembly module was loaded from. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core.mdx b/rules/lib/core.mdx new file mode 100644 index 0000000..ecaeaba --- /dev/null +++ b/rules/lib/core.mdx @@ -0,0 +1,44 @@ +--- +title: 'core' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> +<h1 class="page-title">Core Starlark data types</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +This section lists the data types of the <a href='https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions'>Starlark core language</a>. With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. + +<ul> + +<li><a href="/rules/lib/core/bool">bool</a></li> + +<li><a href="/rules/lib/core/builtin_function_or_method">builtin_function_or_method</a></li> + +<li><a href="/rules/lib/core/dict">dict</a></li> + +<li><a href="/rules/lib/core/float">float</a></li> + +<li><a href="/rules/lib/core/function">function</a></li> + +<li><a href="/rules/lib/core/int">int</a></li> + +<li><a href="/rules/lib/core/json">json</a></li> + +<li><a href="/rules/lib/core/list">list</a></li> + +<li><a href="/rules/lib/core/range">range</a></li> + +<li><a href="/rules/lib/core/set">set</a></li> + +<li><a href="/rules/lib/core/string">string</a></li> + +<li><a href="/rules/lib/core/tuple">tuple</a></li> +</ul> +</body> +</html> diff --git a/rules/lib/core/bool.mdx b/rules/lib/core/bool.mdx new file mode 100644 index 0000000..00b44be --- /dev/null +++ b/rules/lib/core/bool.mdx @@ -0,0 +1,25 @@ +--- +title: 'bool' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.bool">bool</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/MethodLibrary.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A type to represent booleans. There are only two possible values: True and False. Any value can be converted to a boolean using the <a href="../globals/all.html#bool">bool</a> function. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/builtin_function_or_method.mdx b/rules/lib/core/builtin_function_or_method.mdx new file mode 100644 index 0000000..66dc664 --- /dev/null +++ b/rules/lib/core/builtin_function_or_method.mdx @@ -0,0 +1,25 @@ +--- +title: 'builtin_function_or_method' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.builtin_function_or_method">builtin_function_or_method</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/BuiltinFunction.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The type of a built-in function, defined by Java code. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/dict.mdx b/rules/lib/core/dict.mdx new file mode 100644 index 0000000..83b5c4e --- /dev/null +++ b/rules/lib/core/dict.mdx @@ -0,0 +1,267 @@ +--- +title: 'dict' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.dict">dict</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/Dict.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +dict is a built-in type representing an associative mapping or <i>dictionary</i>. A dictionary supports indexing using <code>d[k]</code> and key membership testing using <code>k in d</code>; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to <code>d[k]</code> or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key. +<pre>d = {0: "x", 2: "z", 1: "y"} +[k for k in d] # [0, 2, 1] +d.pop(2) +d[0], d[2] = "a", "b" +0 in d, "a" in d # (True, False) +[(k, v) for k, v in d.items()] # [(0, "a"), (1, "y"), (2, "b")] +</pre> +<p>There are four ways to construct a dictionary: +<ol> +<li>A dictionary expression <code>{k: v, ...}</code> yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value. +<li>A dictionary comprehension <code>{k: v for vars in seq}</code> yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value. +<pre class="language-python"> +{k: v for k, v in (("a", 0), ("b", 1), ("a", 2))} # {"a": 2, "b": 1} +{i: 2*i for i in range(3)} # {0: 0, 1: 2, 2: 4} +</pre> +<li>A call to the built-in <a href="../globals/all.html#dict">dict</a> function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted. +<li>The union expression <code>x | y</code> yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key <code>k</code> in common, the right hand side dictionary's value of the key (in other words, <code>y[k]</code>) wins. The <code>|=</code> variant of the union operator modifies a dictionary in-place. Example:<br><pre class=language-python>d = {"foo": "FOO", "bar": "BAR"} | {"foo": "FOO2", "baz": "BAZ"} +# d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"} +d = {"a": 1, "b": 2} +d |= {"b": 3, "c": 4} +# d == {"a": 1, "b": 3, "c": 4}</pre></ol> + +<h2>Members</h2> +<ul> + <li> + <a href="#clear">clear</a> + </li> + <li> + <a href="#get">get</a> + </li> + <li> + <a href="#items">items</a> + </li> + <li> + <a href="#keys">keys</a> + </li> + <li> + <a href="#pop">pop</a> + </li> + <li> + <a href="#popitem">popitem</a> + </li> + <li> + <a href="#setdefault">setdefault</a> + </li> + <li> + <a href="#update">update</a> + </li> + <li> + <a href="#values">values</a> + </li> + </ul> + + <h2 id="clear">clear</h2> + <p><pre class="rule-signature"><code>None</code> dict.clear()</pre></p> + + Remove all items from the dictionary. + + <h2 id="get">get</h2> + <p><pre class="rule-signature">unknown dict.get(key, default=None)</pre></p> + + Returns the value for <code>key</code> if <code>key</code> is in the dictionary, else <code>default</code>. If <code>default</code> is not given, it defaults to <code>None</code>, so that this method never throws an error. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="get.key"> + <code>key</code> + </td> + <td> + required<br/> + The key to look for. + </td> + </tr> + <tr> + <td id="get.default"> + <code>default</code> + </td> + <td> + default is <code>None</code><br/> + The default value to use (instead of None) if the key is not found. + </td> + </tr> + </tbody> + </table> + + <h2 id="items">items</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.items()</pre></p> + + Returns the list of key-value tuples:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")]</pre> + + + <h2 id="keys">keys</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.keys()</pre></p> + + Returns the list of keys:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1]</pre> + + + <h2 id="pop">pop</h2> + <p><pre class="rule-signature">unknown dict.pop(key, default=unbound)</pre></p> + + Removes a <code>key</code> from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified <code>default</code> value; if no default value was specified, fail instead. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="pop.key"> + <code>key</code> + </td> + <td> + required<br/> + The key. + </td> + </tr> + <tr> + <td id="pop.default"> + <code>default</code> + </td> + <td> + default is <code>unbound</code><br/> + a default value if the key is absent. + </td> + </tr> + </tbody> + </table> + + <h2 id="popitem">popitem</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> dict.popitem()</pre></p> + + Remove and return the first <code>(key, value)</code> pair from the dictionary. <code>popitem</code> is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the <code>popitem</code> call fails. + + <h2 id="setdefault">setdefault</h2> + <p><pre class="rule-signature">unknown dict.setdefault(key, default=None)</pre></p> + + If <code>key</code> is in the dictionary, return its value. If not, insert key with a value of <code>default</code> and return <code>default</code>. <code>default</code> defaults to <code>None</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="setdefault.key"> + <code>key</code> + </td> + <td> + required<br/> + The key. + </td> + </tr> + <tr> + <td id="setdefault.default"> + <code>default</code> + </td> + <td> + default is <code>None</code><br/> + a default value if the key is absent. + </td> + </tr> + </tbody> + </table> + + <h2 id="update">update</h2> + <p><pre class="rule-signature"><code>None</code> dict.update(pairs=[], **kwargs)</pre></p> + + Updates the dictionary first with the optional positional argument, <code>pairs</code>, then with the optional keyword arguments +If the positional argument is present, it must be a dict, iterable, or None. +If it is a dict, then its key/value pairs are inserted into this dict. If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2), each of which is treated as a key/value pair to be inserted. +Each keyword argument <code>name=value</code> causes the name/value pair to be inserted into this dict. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="update.pairs"> + <code>pairs</code> + </td> + <td> + default is <code>[]</code><br/> + Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value. + </td> + </tr> + <tr> + <td id="update.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + Dictionary of additional entries. + </td> + </tr> + </tbody> + </table> + + <h2 id="values">values</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.values()</pre></p> + + Returns the list of values:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"]</pre> + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/float.mdx b/rules/lib/core/float.mdx new file mode 100644 index 0000000..156305f --- /dev/null +++ b/rules/lib/core/float.mdx @@ -0,0 +1,25 @@ +--- +title: 'float' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.float">float</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkFloat.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The type of floating-point numbers in Starlark. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/function.mdx b/rules/lib/core/function.mdx new file mode 100644 index 0000000..b35e701 --- /dev/null +++ b/rules/lib/core/function.mdx @@ -0,0 +1,25 @@ +--- +title: 'function' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.function">function</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkFunction.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The type of functions declared in Starlark. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/int.mdx b/rules/lib/core/int.mdx new file mode 100644 index 0000000..5a0792e --- /dev/null +++ b/rules/lib/core/int.mdx @@ -0,0 +1,32 @@ +--- +title: 'int' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.int">int</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkInt.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The type of integers in Starlark. Starlark integers may be of any magnitude; arithmetic is exact. Examples of integer expressions:<br><pre class="language-python">153 +0x2A # hexadecimal literal +0o54 # octal literal +23 * 2 + 5 +100 / -7 +100 % -7 # -5 (unlike in some other languages) +int("18") +</pre> + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/json.mdx b/rules/lib/core/json.mdx new file mode 100644 index 0000000..720a305 --- /dev/null +++ b/rules/lib/core/json.mdx @@ -0,0 +1,241 @@ +--- +title: 'json' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.json">json</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/lib/json/Json.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Module json is a Starlark module of JSON-related functions. + +<h2>Members</h2> +<ul> + <li> + <a href="#decode">decode</a> + </li> + <li> + <a href="#encode">encode</a> + </li> + <li> + <a href="#encode_indent">encode_indent</a> + </li> + <li> + <a href="#indent">indent</a> + </li> + </ul> + + <h2 id="decode">decode</h2> + <p><pre class="rule-signature">unknown json.decode(x, default=unbound)</pre></p> + + The decode function has one required positional parameter: a JSON string. +It returns the Starlark value that the string denotes. +<ul><li><code>"null"</code>, <code>"true"</code> and <code>"false"</code> are parsed as <code>None</code>, <code>True</code>, and <code>False</code>. +<li>Numbers are parsed as int, or as a float if they contain a decimal point or an exponent. Although JSON has no syntax for non-finite values, very large values may be decoded as infinity. +<li>a JSON object is parsed as a new unfrozen Starlark dict. If the same key string occurs more than once in the object, the last value for the key is kept. +<li>a JSON array is parsed as new unfrozen Starlark list. +</ul> +If <code>x</code> is not a valid JSON encoding and the optional <code>default</code> parameter is specified (including specified as <code>None</code>), this function returns the <code>default</code> value. +If <code>x</code> is not a valid JSON encoding and the optional <code>default</code> parameter is <em>not</em> specified, this function fails. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="decode.x"> + <code>x</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + JSON string to decode. + </td> + </tr> + <tr> + <td id="decode.default"> + <code>default</code> + </td> + <td> + default is <code>unbound</code><br/> + If specified, the value to return when <code>x</code> cannot be decoded. + </td> + </tr> + </tbody> + </table> + + <h2 id="encode">encode</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> json.encode(x)</pre></p> + + <p>The encode function accepts one required positional argument, which it converts to JSON by cases: +<ul> +<li>None, True, and False are converted to 'null', 'true', and 'false', respectively. +<li>An int, no matter how large, is encoded as a decimal integer. Some decoders may not be able to decode very large integers. +<li>A float is encoded using a decimal point or an exponent or both, even if its numeric value is an integer. It is an error to encode a non-finite floating-point value. +<li>A string value is encoded as a JSON string literal that denotes the value. Each unpaired surrogate is replaced by U+FFFD. +<li>A dict is encoded as a JSON object, in lexicographical key order. It is an error if any key is not a string. +<li>A list or tuple is encoded as a JSON array. +<li>A struct-like value is encoded as a JSON object, in field name order. +</ul> +An application-defined type may define its own JSON encoding. +Encoding any other value yields an error. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="encode.x"> + <code>x</code> + </td> + <td> + required<br/> + + </td> + </tr> + </tbody> + </table> + + <h2 id="encode_indent">encode_indent</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> json.encode_indent(x, *, prefix='', indent='\t')</pre></p> + + The encode_indent function is equivalent to <code>json.indent(json.encode(x), ...)</code>. See <code>indent</code> for description of formatting parameters. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="encode_indent.x"> + <code>x</code> + </td> + <td> + required<br/> + + </td> + </tr> + <tr> + <td id="encode_indent.prefix"> + <code>prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + + </td> + </tr> + <tr> + <td id="encode_indent.indent"> + <code>indent</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'\t'</code><br/> + + </td> + </tr> + </tbody> + </table> + + <h2 id="indent">indent</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> json.indent(s, *, prefix='', indent='\t')</pre></p> + + The indent function returns the indented form of a valid JSON-encoded string. +Each array element or object field appears on a new line, beginning with the prefix string followed by one or more copies of the indent string, according to its nesting depth. +The function accepts one required positional parameter, the JSON string, +and two optional keyword-only string parameters, prefix and indent, +that specify a prefix of each new line, and the unit of indentation. +If the input is not valid, the function may fail or return invalid output. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="indent.s"> + <code>s</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + + </td> + </tr> + <tr> + <td id="indent.prefix"> + <code>prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + + </td> + </tr> + <tr> + <td id="indent.indent"> + <code>indent</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'\t'</code><br/> + + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/list.mdx b/rules/lib/core/list.mdx new file mode 100644 index 0000000..6e27002 --- /dev/null +++ b/rules/lib/core/list.mdx @@ -0,0 +1,276 @@ +--- +title: 'list' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.list">list</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkList.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The built-in list type. Example list expressions:<br><pre class=language-python>x = [1, 2, 3]</pre>Accessing elements is possible using indexing (starts from <code>0</code>):<br><pre class=language-python>e = x[1] # e == 2</pre>Lists support the <code>+</code> operator to concatenate two lists. Example:<br><pre class=language-python>x = [1, 2] + [3, 4] # x == [1, 2, 3, 4] +x = ["a", "b"] +x += ["c"] # x == ["a", "b", "c"]</pre>Similar to strings, lists support slice operations:<pre class=language-python>['a', 'b', 'c', 'd'][1:3] # ['b', 'c'] +['a', 'b', 'c', 'd'][::2] # ['a', 'c'] +['a', 'b', 'c', 'd'][3:0:-1] # ['d', 'c', 'b']</pre>Lists are mutable, as in Python. + +<h2>Members</h2> +<ul> + <li> + <a href="#append">append</a> + </li> + <li> + <a href="#clear">clear</a> + </li> + <li> + <a href="#extend">extend</a> + </li> + <li> + <a href="#index">index</a> + </li> + <li> + <a href="#insert">insert</a> + </li> + <li> + <a href="#pop">pop</a> + </li> + <li> + <a href="#remove">remove</a> + </li> + </ul> + + <h2 id="append">append</h2> + <p><pre class="rule-signature"><code>None</code> list.append(item)</pre></p> + + Adds an item to the end of the list. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="append.item"> + <code>item</code> + </td> + <td> + required<br/> + Item to add at the end. + </td> + </tr> + </tbody> + </table> + + <h2 id="clear">clear</h2> + <p><pre class="rule-signature"><code>None</code> list.clear()</pre></p> + + Removes all the elements of the list. + + <h2 id="extend">extend</h2> + <p><pre class="rule-signature"><code>None</code> list.extend(items)</pre></p> + + Adds all items to the end of the list. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="extend.items"> + <code>items</code> + </td> + <td> + iterable; + required<br/> + Items to add at the end. + </td> + </tr> + </tbody> + </table> + + <h2 id="index">index</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> list.index(x, start=unbound, end=unbound)</pre></p> + + Returns the index in the list of the first item whose value is x. It is an error if there is no such item. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="index.x"> + <code>x</code> + </td> + <td> + required<br/> + The object to search. + </td> + </tr> + <tr> + <td id="index.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>unbound</code><br/> + The start index of the list portion to inspect. + </td> + </tr> + <tr> + <td id="index.end"> + <code>end</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>unbound</code><br/> + The end index of the list portion to inspect. + </td> + </tr> + </tbody> + </table> + + <h2 id="insert">insert</h2> + <p><pre class="rule-signature"><code>None</code> list.insert(index, item)</pre></p> + + Inserts an item at a given position. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="insert.index"> + <code>index</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + required<br/> + The index of the given position. + </td> + </tr> + <tr> + <td id="insert.item"> + <code>item</code> + </td> + <td> + required<br/> + The item. + </td> + </tr> + </tbody> + </table> + + <h2 id="pop">pop</h2> + <p><pre class="rule-signature">unknown list.pop(i=-1)</pre></p> + + Removes the item at the given position in the list, and returns it. If no <code>index</code> is specified, it removes and returns the last item in the list. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="pop.i"> + <code>i</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>-1</code><br/> + The index of the item. + </td> + </tr> + </tbody> + </table> + + <h2 id="remove">remove</h2> + <p><pre class="rule-signature"><code>None</code> list.remove(x)</pre></p> + + Removes the first item from the list whose value is x. It is an error if there is no such item. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="remove.x"> + <code>x</code> + </td> + <td> + required<br/> + The object to remove. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/range.mdx b/rules/lib/core/range.mdx new file mode 100644 index 0000000..ca91cf4 --- /dev/null +++ b/rules/lib/core/range.mdx @@ -0,0 +1,27 @@ +--- +title: 'range' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.range">range</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/RangeList.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A language built-in type to support ranges. Example of range literal:<br><pre class=language-python>x = range(1, 10, 3)</pre>Accessing elements is possible using indexing (starts from <code>0</code>):<br><pre class=language-python>e = x[1] # e == 2</pre>Ranges do not support the <code>+</code> operator for concatenation.Similar to strings, ranges support slice operations:<pre class=language-python>range(10)[1:3] # range(1, 3) +range(10)[::2] # range(0, 10, 2) +range(10)[3:0:-1] # range(3, 0, -1)</pre>Ranges are immutable, as in Python 3. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/set.mdx b/rules/lib/core/set.mdx new file mode 100644 index 0000000..910b749 --- /dev/null +++ b/rules/lib/core/set.mdx @@ -0,0 +1,809 @@ +--- +title: 'set' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.set">set</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkSet.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The built-in set type. A set is a mutable collection of unique values – the set's +<em>elements</em>. The <a href="../globals/all#type">type name</a> of a set is <code>"set"</code>. + +<p>Sets provide constant-time operations to insert, remove, or check for the presence of a value. +Sets are implemented using a hash table, and therefore, just like keys of a +<a href="../dict">dictionary</a>, elements of a set must be hashable. A value may be used as an +element of a set if and only if it may be used as a key of a dictionary. + +<p>Sets may be constructed using the <a href="../globals/all#set"><code>set()</code></a> built-in +function, which returns a new set containing the unique elements of its optional argument, which +must be an iterable. Calling <code>set()</code> without an argument constructs an empty set. Sets +have no literal syntax. + +<p>The <code>in</code> and <code>not in</code> operations check whether a value is (or is not) in a +set: + +<pre class=language-python> +s = set(["a", "b", "c"]) +"a" in s # True +"z" in s # False +</pre> + +<p>A set is iterable, and thus may be used as the operand of a <code>for</code> loop, a list +comprehension, and the various built-in functions that operate on iterables. Its length can be +retrieved using the <a href="../globals/all#len"><code>len()</code></a> built-in function, and the +order of iteration is the order in which elements were first added to the set: + +<pre class=language-python> +s = set(["z", "y", "z", "y"]) +len(s) # prints 2 +s.add("x") +len(s) # prints 3 +for e in s: + print e # prints "z", "y", "x" +</pre> + +<p>A set used in Boolean context is true if and only if it is non-empty. + +<pre class=language-python> +s = set() +"non-empty" if s else "empty" # "empty" +t = set(["x", "y"]) +"non-empty" if t else "empty" # "non-empty" +</pre> + +<p>Sets may be compared for equality or inequality using <code>==</code> and <code>!=</code>. A set +<code>s</code> is equal to <code>t</code> if and only if <code>t</code> is a set containing the same +elements; iteration order is not significant. In particular, a set is <em>not</em> equal to the list +of its elements. Sets are not ordered with respect to other sets, and an attempt to compare two sets +using <code><</code>, <code><=</code>, <code>></code>, <code>>=</code>, or to sort a +sequence of sets, will fail. + +<pre class=language-python> +set() == set() # True +set() != [] # True +set([1, 2]) == set([2, 1]) # True +set([1, 2]) != [1, 2] # True +</pre> + +<p>The <code>|</code> operation on two sets returns the union of the two sets: a set containing the +elements found in either one or both of the original sets. + +<pre class=language-python> +set([1, 2]) | set([3, 2]) # set([1, 2, 3]) +</pre> + +<p>The <code>&</code> operation on two sets returns the intersection of the two sets: a set +containing only the elements found in both of the original sets. + +<pre class=language-python> +set([1, 2]) & set([2, 3]) # set([2]) +set([1, 2]) & set([3, 4]) # set() +</pre> + +<p>The <code>-</code> operation on two sets returns the difference of the two sets: a set containing +the elements found in the left-hand side set but not the right-hand side set. + +<pre class=language-python> +set([1, 2]) - set([2, 3]) # set([1]) +set([1, 2]) - set([3, 4]) # set([1, 2]) +</pre> + +<p>The <code>^</code> operation on two sets returns the symmetric difference of the two sets: a set +containing the elements found in exactly one of the two original sets, but not in both. + +<pre class=language-python> +set([1, 2]) ^ set([2, 3]) # set([1, 3]) +set([1, 2]) ^ set([3, 4]) # set([1, 2, 3, 4]) +</pre> + +<p>In each of the above operations, the elements of the resulting set retain their order from the +two operand sets, with all elements that were drawn from the left-hand side ordered before any +element that was only present in the right-hand side. + +<p>The corresponding augmented assignments, <code>|=</code>, <code>&=</code>, <code>-=</code>, +and <code>^=</code>, modify the left-hand set in place. + +<pre class=language-python> +s = set([1, 2]) +s |= set([2, 3, 4]) # s now equals set([1, 2, 3, 4]) +s &= set([0, 1, 2, 3]) # s now equals set([1, 2, 3]) +s -= set([0, 1]) # s now equals set([2, 3]) +s ^= set([3, 4]) # s now equals set([2, 4]) +</pre> + +<p>Like all mutable values in Starlark, a set can be frozen, and once frozen, all subsequent +operations that attempt to update it will fail. + + +<h2>Members</h2> +<ul> + <li> + <a href="#add">add</a> + </li> + <li> + <a href="#clear">clear</a> + </li> + <li> + <a href="#difference">difference</a> + </li> + <li> + <a href="#difference_update">difference_update</a> + </li> + <li> + <a href="#discard">discard</a> + </li> + <li> + <a href="#intersection">intersection</a> + </li> + <li> + <a href="#intersection_update">intersection_update</a> + </li> + <li> + <a href="#isdisjoint">isdisjoint</a> + </li> + <li> + <a href="#issubset">issubset</a> + </li> + <li> + <a href="#issuperset">issuperset</a> + </li> + <li> + <a href="#pop">pop</a> + </li> + <li> + <a href="#remove">remove</a> + </li> + <li> + <a href="#symmetric_difference">symmetric_difference</a> + </li> + <li> + <a href="#symmetric_difference_update">symmetric_difference_update</a> + </li> + <li> + <a href="#union">union</a> + </li> + <li> + <a href="#update">update</a> + </li> + </ul> + + <h2 id="add">add</h2> + <p><pre class="rule-signature"><code>None</code> set.add(element)</pre></p> + + Adds an element to the set. + +<p>It is permissible to <code>add</code> a value already present in the set; this leaves the set +unchanged. + +<p>If you need to add multiple elements to a set, see <a href="#update"><code>update</code></a> or +the <code>|=</code> augmented assignment operation. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="add.element"> + <code>element</code> + </td> + <td> + required<br/> + Element to add. + </td> + </tr> + </tbody> + </table> + + <h2 id="clear">clear</h2> + <p><pre class="rule-signature"><code>None</code> set.clear()</pre></p> + + Removes all the elements of the set. + + <h2 id="difference">difference</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set.difference(*others)</pre></p> + + Returns a new mutable set containing the difference of this set with others. + +<p>If <code>s</code> and <code>t</code> are sets, <code>s.difference(t)</code> is equivalent to +<code>s - t</code>; however, note that the <code>-</code> operation requires both sides to be sets, +while the <code>difference</code> method also accepts sequences and dicts. + +<p>It is permissible to call <code>difference</code> without any arguments; this returns a copy of +the set. + +<p>For example, +<pre class=language-python> +set([1, 2, 3]).difference([2]) # set([1, 3]) +set([1, 2, 3]).difference([0, 1], [3, 4]) # set([2]) +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="difference.others"> + <code>others</code> + </td> + <td> + required<br/> + Collections of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="difference_update">difference_update</h2> + <p><pre class="rule-signature"><code>None</code> set.difference_update(*others)</pre></p> + + Removes any elements found in any others from this set. + +<p>If <code>s</code> and <code>t</code> are sets, <code>s.difference_update(t)</code> is equivalent +to <code>s -= t</code>; however, note that the <code>-=</code> augmented assignment requires both +sides to be sets, while the <code>difference_update</code> method also accepts sequences and dicts. + +<p>It is permissible to call <code>difference_update</code> without any arguments; this leaves the +set unchanged. + +<p>For example, +<pre class=language-python> +s = set([1, 2, 3, 4]) +s.difference_update([2]) # None; s is set([1, 3, 4]) +s.difference_update([0, 1], [4, 5]) # None; s is set([3]) +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="difference_update.others"> + <code>others</code> + </td> + <td> + required<br/> + Collections of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="discard">discard</h2> + <p><pre class="rule-signature"><code>None</code> set.discard(element)</pre></p> + + Removes an element from the set if it is present. + +<p>It is permissible to <code>discard</code> a value not present in the set; this leaves the set +unchanged. If you want to fail on an attempt to remove a non-present element, use +<a href="#remove"><code>remove</code></a> instead. If you need to remove multiple elements from a +set, see <a href="#difference_update"><code>difference_update</code></a> or the <code>-=</code> +augmented assignment operation. + +<p>For example, +<pre class=language-python> +s = set(["x", "y"]) +s.discard("y") # None; s == set(["x"]) +s.discard("y") # None; s == set(["x"]) +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="discard.element"> + <code>element</code> + </td> + <td> + required<br/> + Element to discard. Must be hashable. + </td> + </tr> + </tbody> + </table> + + <h2 id="intersection">intersection</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set.intersection(*others)</pre></p> + + Returns a new mutable set containing the intersection of this set with others. + +<p>If <code>s</code> and <code>t</code> are sets, <code>s.intersection(t)</code> is equivalent to +<code>s & t</code>; however, note that the <code>&</code> operation requires both sides to +be sets, while the <code>intersection</code> method also accepts sequences and dicts. + +<p>It is permissible to call <code>intersection</code> without any arguments; this returns a copy of +the set. + +<p>For example, +<pre class=language-python> +set([1, 2]).intersection([2, 3]) # set([2]) +set([1, 2, 3]).intersection([0, 1], [1, 2]) # set([1]) +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="intersection.others"> + <code>others</code> + </td> + <td> + required<br/> + Collections of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="intersection_update">intersection_update</h2> + <p><pre class="rule-signature"><code>None</code> set.intersection_update(*others)</pre></p> + + Removes any elements not found in all others from this set. + +<p>If <code>s</code> and <code>t</code> are sets, <code>s.intersection_update(t)</code> is +equivalent to <code>s &= t</code>; however, note that the <code>&=</code> augmented +assignment requires both sides to be sets, while the <code>intersection_update</code> method also +accepts sequences and dicts. + +<p>It is permissible to call <code>intersection_update</code> without any arguments; this leaves the +set unchanged. + +<p>For example, +<pre class=language-python> +s = set([1, 2, 3, 4]) +s.intersection_update([0, 1, 2]) # None; s is set([1, 2]) +s.intersection_update([0, 1], [1, 2]) # None; s is set([1]) +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="intersection_update.others"> + <code>others</code> + </td> + <td> + required<br/> + Collections of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="isdisjoint">isdisjoint</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> set.isdisjoint(other)</pre></p> + + Returns true if this set has no elements in common with another. + +<p>For example, +<pre class=language-python> +set([1, 2]).isdisjoint([3, 4]) # True +set().isdisjoint(set()) # True +set([1, 2]).isdisjoint([2, 3]) # False +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="isdisjoint.other"> + <code>other</code> + </td> + <td> + required<br/> + A collection of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="issubset">issubset</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> set.issubset(other)</pre></p> + + Returns true of this set is a subset of another. + +<p>Note that a set is always considered to be a subset of itself. + +<p>For example, +<pre class=language-python> +set([1, 2]).issubset([1, 2, 3]) # True +set([1, 2]).issubset([1, 2]) # True +set([1, 2]).issubset([2, 3]) # False +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="issubset.other"> + <code>other</code> + </td> + <td> + required<br/> + A collection of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="issuperset">issuperset</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> set.issuperset(other)</pre></p> + + Returns true of this set is a superset of another. + +<p>Note that a set is always considered to be a superset of itself. + +<p>For example, +<pre class=language-python> +set([1, 2, 3]).issuperset([1, 2]) # True +set([1, 2, 3]).issuperset([1, 2, 3]) # True +set([1, 2, 3]).issuperset([2, 3, 4]) # False +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="issuperset.other"> + <code>other</code> + </td> + <td> + required<br/> + A collection of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="pop">pop</h2> + <p><pre class="rule-signature">unknown set.pop()</pre></p> + + Removes and returns the first element of the set (in iteration order, which is the order in which +elements were first added to the set). + +<p>Fails if the set is empty. + +<p>For example, +<pre class=language-python> +s = set([3, 1, 2]) +s.pop() # 3; s == set([1, 2]) +s.pop() # 1; s == set([2]) +s.pop() # 2; s == set() +s.pop() # error: empty set +</pre> + + + <h2 id="remove">remove</h2> + <p><pre class="rule-signature"><code>None</code> set.remove(element)</pre></p> + + Removes an element, which must be present in the set, from the set. + +<p><code>remove</code> fails if the element was not present in the set. If you don't want to fail on +an attempt to remove a non-present element, use <a href="#discard"><code>discard</code></a> instead. +If you need to remove multiple elements from a set, see +<a href="#difference_update"><code>difference_update</code></a> or the <code>-=</code> augmented +assignment operation. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="remove.element"> + <code>element</code> + </td> + <td> + required<br/> + Element to remove. Must be an element of the set (and hashable). + </td> + </tr> + </tbody> + </table> + + <h2 id="symmetric_difference">symmetric_difference</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set.symmetric_difference(other)</pre></p> + + Returns a new mutable set containing the symmetric difference of this set with another collection of +hashable elements. + +<p>If <code>s</code> and <code>t</code> are sets, <code>s.symmetric_difference(t)</code> is +equivalent to <code>s ^ t</code>; however, note that the <code>^</code> operation requires both +sides to be sets, while the <code>symmetric_difference</code> method also accepts a sequence or a +dict. + +<p>For example, +<pre class=language-python> +set([1, 2]).symmetric_difference([2, 3]) # set([1, 3]) +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="symmetric_difference.other"> + <code>other</code> + </td> + <td> + required<br/> + A collection of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="symmetric_difference_update">symmetric_difference_update</h2> + <p><pre class="rule-signature"><code>None</code> set.symmetric_difference_update(other)</pre></p> + + Returns a new mutable set containing the symmetric difference of this set with another collection of +hashable elements. + +<p>If <code>s</code> and <code>t</code> are sets, <code>s.symmetric_difference_update(t)</code> is +equivalent to `s ^= t<code>; however, note that the </code>^=` augmented assignment requires both +sides to be sets, while the <code>symmetric_difference_update</code> method also accepts a sequence +or a dict. + +<p>For example, +<pre class=language-python> +s = set([1, 2]) +s.symmetric_difference_update([2, 3]) # None; s == set([1, 3]) +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="symmetric_difference_update.other"> + <code>other</code> + </td> + <td> + required<br/> + A collection of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="union">union</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set.union(*others)</pre></p> + + Returns a new mutable set containing the union of this set with others. + +<p>If <code>s</code> and <code>t</code> are sets, <code>s.union(t)</code> is equivalent to +<code>s | t</code>; however, note that the <code>|</code> operation requires both sides to be sets, +while the <code>union</code> method also accepts sequences and dicts. + +<p>It is permissible to call <code>union</code> without any arguments; this returns a copy of the +set. + +<p>For example, +<pre class=language-python> +set([1, 2]).union([2, 3]) # set([1, 2, 3]) +set([1, 2]).union([2, 3], {3: "a", 4: "b"}) # set([1, 2, 3, 4]) +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="union.others"> + <code>others</code> + </td> + <td> + required<br/> + Collections of hashable elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="update">update</h2> + <p><pre class="rule-signature"><code>None</code> set.update(*others)</pre></p> + + Adds the elements found in others to this set. + +<p>For example, +<pre class=language-python> +s = set() +s.update([1, 2]) # None; s is set([1, 2]) +s.update([2, 3], [3, 4]) # None; s is set([1, 2, 3, 4]) +</pre> + +<p>If <code>s</code> and <code>t</code> are sets, <code>s.update(t)</code> is equivalent to +<code>s |= t</code>; however, note that the <code>|=</code> augmented assignment requires both sides +to be sets, while the <code>update</code> method also accepts sequences and dicts. + +<p>It is permissible to call <code>update</code> without any arguments; this leaves the set +unchanged. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="update.others"> + <code>others</code> + </td> + <td> + required<br/> + Collections of hashable elements. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/string.mdx b/rules/lib/core/string.mdx new file mode 100644 index 0000000..33d7a3b --- /dev/null +++ b/rules/lib/core/string.mdx @@ -0,0 +1,1031 @@ +--- +title: 'string' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.string">string</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StringModule.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A language built-in type to support strings. Examples of string literals:<br><pre class="language-python">a = 'abc\ndef' +b = "ab'cd" +c = """multiline string""" + +# Strings support slicing (negative index starts from the end): +x = "hello"[2:4] # "ll" +y = "hello"[1:-1] # "ell" +z = "hello"[:4] # "hell" +# Slice steps can be used, too: +s = "hello"[::2] # "hlo" +t = "hello"[3:0:-1] # "lle" +</pre>Strings are not directly iterable, use the <code>.elems()</code> method to iterate over their characters. Examples:<br><pre class="language-python">"bc" in "abcd" # evaluates to True +x = [c for c in "abc".elems()] # x == ["a", "b", "c"]</pre> +Implicit concatenation of strings is not allowed; use the <code>+</code> operator instead. Comparison operators perform a lexicographical comparison; use <code>==</code> to test for equality. + +<h2>Members</h2> +<ul> + <li> + <a href="#capitalize">capitalize</a> + </li> + <li> + <a href="#count">count</a> + </li> + <li> + <a href="#elems">elems</a> + </li> + <li> + <a href="#endswith">endswith</a> + </li> + <li> + <a href="#find">find</a> + </li> + <li> + <a href="#format">format</a> + </li> + <li> + <a href="#index">index</a> + </li> + <li> + <a href="#isalnum">isalnum</a> + </li> + <li> + <a href="#isalpha">isalpha</a> + </li> + <li> + <a href="#isdigit">isdigit</a> + </li> + <li> + <a href="#islower">islower</a> + </li> + <li> + <a href="#isspace">isspace</a> + </li> + <li> + <a href="#istitle">istitle</a> + </li> + <li> + <a href="#isupper">isupper</a> + </li> + <li> + <a href="#join">join</a> + </li> + <li> + <a href="#lower">lower</a> + </li> + <li> + <a href="#lstrip">lstrip</a> + </li> + <li> + <a href="#partition">partition</a> + </li> + <li> + <a href="#removeprefix">removeprefix</a> + </li> + <li> + <a href="#removesuffix">removesuffix</a> + </li> + <li> + <a href="#replace">replace</a> + </li> + <li> + <a href="#rfind">rfind</a> + </li> + <li> + <a href="#rindex">rindex</a> + </li> + <li> + <a href="#rpartition">rpartition</a> + </li> + <li> + <a href="#rsplit">rsplit</a> + </li> + <li> + <a href="#rstrip">rstrip</a> + </li> + <li> + <a href="#split">split</a> + </li> + <li> + <a href="#splitlines">splitlines</a> + </li> + <li> + <a href="#startswith">startswith</a> + </li> + <li> + <a href="#strip">strip</a> + </li> + <li> + <a href="#title">title</a> + </li> + <li> + <a href="#upper">upper</a> + </li> + </ul> + + <h2 id="capitalize">capitalize</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.capitalize()</pre></p> + + Returns a copy of the string with its first character (if any) capitalized and the rest lowercased. This method does not support non-ascii characters. + + <h2 id="count">count</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.count(sub, start=0, end=None)</pre></p> + + Returns the number of (non-overlapping) occurrences of substring <code>sub</code> in string, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="count.sub"> + <code>sub</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The substring to count. + </td> + </tr> + <tr> + <td id="count.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>0</code><br/> + Restrict to search from this position. + </td> + </tr> + <tr> + <td id="count.end"> + <code>end</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>None</code><br/> + optional position before which to restrict to search. + </td> + </tr> + </tbody> + </table> + + <h2 id="elems">elems</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> string.elems()</pre></p> + + Returns an iterable value containing successive 1-element substrings of the string. Equivalent to <code>[s[i] for i in range(len(s))]</code>, except that the returned value might not be a list. + + <h2 id="endswith">endswith</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.endswith(sub, start=0, end=None)</pre></p> + + Returns True if the string ends with <code>sub</code>, otherwise False, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="endswith.sub"> + <code>sub</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/tuple.html">tuple</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The suffix (or tuple of alternative suffixes) to match. + </td> + </tr> + <tr> + <td id="endswith.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>0</code><br/> + Test beginning at this position. + </td> + </tr> + <tr> + <td id="endswith.end"> + <code>end</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>None</code><br/> + optional position at which to stop comparing. + </td> + </tr> + </tbody> + </table> + + <h2 id="find">find</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.find(sub, start=0, end=None)</pre></p> + + Returns the first index where <code>sub</code> is found, or -1 if no such index exists, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="find.sub"> + <code>sub</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The substring to find. + </td> + </tr> + <tr> + <td id="find.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>0</code><br/> + Restrict to search from this position. + </td> + </tr> + <tr> + <td id="find.end"> + <code>end</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>None</code><br/> + optional position before which to restrict to search. + </td> + </tr> + </tbody> + </table> + + <h2 id="format">format</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.format(*args, **kwargs)</pre></p> + + Perform string interpolation. Format strings contain replacement fields surrounded by curly braces <code>{}</code>. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output.If you need to include a brace character in the literal text, it can be escaped by doubling: <code>{{</code> and <code>}}</code>A replacement field can be either a name, a number, or empty. Values are converted to strings using the <a href="../globals/all.html#str">str</a> function.<pre class="language-python"># Access in order: +"{} < {}".format(4, 5) == "4 < 5" +# Access by position: +"{1}, {0}".format(2, 1) == "1, 2" +# Access by name: +"x{key}x".format(key = 2) == "x2x"</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="format.args"> + <code>args</code> + </td> + <td> + default is <code>()</code><br/> + List of arguments. + </td> + </tr> + <tr> + <td id="format.kwargs"> + <code>kwargs</code> + </td> + <td> + default is <code>{}</code><br/> + Dictionary of arguments. + </td> + </tr> + </tbody> + </table> + + <h2 id="index">index</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.index(sub, start=0, end=None)</pre></p> + + Returns the first index where <code>sub</code> is found, or raises an error if no such index exists, optionally restricting to <code>[start:end]</code><code>start</code> being inclusive and <code>end</code> being exclusive. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="index.sub"> + <code>sub</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The substring to find. + </td> + </tr> + <tr> + <td id="index.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>0</code><br/> + Restrict to search from this position. + </td> + </tr> + <tr> + <td id="index.end"> + <code>end</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>None</code><br/> + optional position before which to restrict to search. + </td> + </tr> + </tbody> + </table> + + <h2 id="isalnum">isalnum</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isalnum()</pre></p> + + Returns True if all characters in the string are alphanumeric ([a-zA-Z0-9]) and there is at least one character. + + <h2 id="isalpha">isalpha</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isalpha()</pre></p> + + Returns True if all characters in the string are alphabetic ([a-zA-Z]) and there is at least one character. + + <h2 id="isdigit">isdigit</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isdigit()</pre></p> + + Returns True if all characters in the string are digits ([0-9]) and there is at least one character. + + <h2 id="islower">islower</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.islower()</pre></p> + + Returns True if all cased characters in the string are lowercase and there is at least one character. + + <h2 id="isspace">isspace</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isspace()</pre></p> + + Returns True if all characters are white space characters and the string contains at least one character. + + <h2 id="istitle">istitle</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.istitle()</pre></p> + + Returns True if the string is in title case and it contains at least one character. This means that every uppercase character must follow an uncased one (e.g. whitespace) and every lowercase character must follow a cased one (e.g. uppercase or lowercase). + + <h2 id="isupper">isupper</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isupper()</pre></p> + + Returns True if all cased characters in the string are uppercase and there is at least one character. + + <h2 id="join">join</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.join(elements)</pre></p> + + Returns a string in which the string elements of the argument have been joined by this string as a separator. Example:<br><pre class="language-python">"|".join(["a", "b", "c"]) == "a|b|c"</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="join.elements"> + <code>elements</code> + </td> + <td> + iterable of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The objects to join. + </td> + </tr> + </tbody> + </table> + + <h2 id="lower">lower</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.lower()</pre></p> + + Returns the lower case version of this string. + + <h2 id="lstrip">lstrip</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.lstrip(chars=None)</pre></p> + + Returns a copy of the string where leading characters that appear in <code>chars</code> are removed. Note that <code>chars</code> is not a prefix: all combinations of its value are removed:<pre class="language-python">"abcba".lstrip("ba") == "cba"</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="lstrip.chars"> + <code>chars</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The characters to remove, or all whitespace if None. + </td> + </tr> + </tbody> + </table> + + <h2 id="partition">partition</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> string.partition(sep)</pre></p> + + Splits the input string at the first occurrence of the separator <code>sep</code> and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, partition returns (self, '', ''). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="partition.sep"> + <code>sep</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The string to split on. + </td> + </tr> + </tbody> + </table> + + <h2 id="removeprefix">removeprefix</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.removeprefix(prefix)</pre></p> + + If the string starts with <code>prefix</code>, returns a new string with the prefix removed. Otherwise, returns the string. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="removeprefix.prefix"> + <code>prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The prefix to remove if present. + </td> + </tr> + </tbody> + </table> + + <h2 id="removesuffix">removesuffix</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.removesuffix(suffix)</pre></p> + + If the string ends with <code>suffix</code>, returns a new string with the suffix removed. Otherwise, returns the string. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="removesuffix.suffix"> + <code>suffix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The suffix to remove if present. + </td> + </tr> + </tbody> + </table> + + <h2 id="replace">replace</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.replace(old, new, count=-1)</pre></p> + + Returns a copy of the string in which the occurrences of <code>old</code> have been replaced with <code>new</code>, optionally restricting the number of replacements to <code>count</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="replace.old"> + <code>old</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The string to be replaced. + </td> + </tr> + <tr> + <td id="replace.new"> + <code>new</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The string to replace with. + </td> + </tr> + <tr> + <td id="replace.count"> + <code>count</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>-1</code><br/> + The maximum number of replacements. If omitted, or if the value is negative, there is no limit. + </td> + </tr> + </tbody> + </table> + + <h2 id="rfind">rfind</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.rfind(sub, start=0, end=None)</pre></p> + + Returns the last index where <code>sub</code> is found, or -1 if no such index exists, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="rfind.sub"> + <code>sub</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The substring to find. + </td> + </tr> + <tr> + <td id="rfind.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>0</code><br/> + Restrict to search from this position. + </td> + </tr> + <tr> + <td id="rfind.end"> + <code>end</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>None</code><br/> + optional position before which to restrict to search. + </td> + </tr> + </tbody> + </table> + + <h2 id="rindex">rindex</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.rindex(sub, start=0, end=None)</pre></p> + + Returns the last index where <code>sub</code> is found, or raises an error if no such index exists, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="rindex.sub"> + <code>sub</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The substring to find. + </td> + </tr> + <tr> + <td id="rindex.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>0</code><br/> + Restrict to search from this position. + </td> + </tr> + <tr> + <td id="rindex.end"> + <code>end</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>None</code><br/> + optional position before which to restrict to search. + </td> + </tr> + </tbody> + </table> + + <h2 id="rpartition">rpartition</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> string.rpartition(sep)</pre></p> + + Splits the input string at the last occurrence of the separator <code>sep</code> and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, rpartition returns ('', '', self). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="rpartition.sep"> + <code>sep</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The string to split on. + </td> + </tr> + </tbody> + </table> + + <h2 id="rsplit">rsplit</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> string.rsplit(sep, maxsplit=unbound)</pre></p> + + Returns a list of all the words in the string, using <code>sep</code> as the separator, optionally limiting the number of splits to <code>maxsplit</code>. Except for splitting from the right, this method behaves like split(). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="rsplit.sep"> + <code>sep</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The string to split on. + </td> + </tr> + <tr> + <td id="rsplit.maxsplit"> + <code>maxsplit</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>unbound</code><br/> + The maximum number of splits. + </td> + </tr> + </tbody> + </table> + + <h2 id="rstrip">rstrip</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.rstrip(chars=None)</pre></p> + + Returns a copy of the string where trailing characters that appear in <code>chars</code> are removed. Note that <code>chars</code> is not a suffix: all combinations of its value are removed:<pre class="language-python">"abcbaa".rstrip("ab") == "abc"</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="rstrip.chars"> + <code>chars</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The characters to remove, or all whitespace if None. + </td> + </tr> + </tbody> + </table> + + <h2 id="split">split</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> string.split(sep, maxsplit=unbound)</pre></p> + + Returns a list of all the words in the string, using <code>sep</code> as the separator, optionally limiting the number of splits to <code>maxsplit</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="split.sep"> + <code>sep</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The string to split on. + </td> + </tr> + <tr> + <td id="split.maxsplit"> + <code>maxsplit</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>unbound</code><br/> + The maximum number of splits. + </td> + </tr> + </tbody> + </table> + + <h2 id="splitlines">splitlines</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> string.splitlines(keepends=False)</pre></p> + + Splits the string at line boundaries ('\n', '\r\n', '\r') and returns the result as a new mutable list. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="splitlines.keepends"> + <code>keepends</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether the line breaks should be included in the resulting list. + </td> + </tr> + </tbody> + </table> + + <h2 id="startswith">startswith</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.startswith(sub, start=0, end=None)</pre></p> + + Returns True if the string starts with <code>sub</code>, otherwise False, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="startswith.sub"> + <code>sub</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/tuple.html">tuple</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The prefix (or tuple of alternative prefixes) to match. + </td> + </tr> + <tr> + <td id="startswith.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>0</code><br/> + Test beginning at this position. + </td> + </tr> + <tr> + <td id="startswith.end"> + <code>end</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; + default is <code>None</code><br/> + Stop comparing at this position. + </td> + </tr> + </tbody> + </table> + + <h2 id="strip">strip</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.strip(chars=None)</pre></p> + + Returns a copy of the string where leading or trailing characters that appear in <code>chars</code> are removed. Note that <code>chars</code> is neither a prefix nor a suffix: all combinations of its value are removed:<pre class="language-python">"aabcbcbaa".strip("ab") == "cbc"</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="strip.chars"> + <code>chars</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The characters to remove, or all whitespace if None. + </td> + </tr> + </tbody> + </table> + + <h2 id="title">title</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.title()</pre></p> + + Converts the input string into title case, i.e. every word starts with an uppercase letter while the remaining letters are lowercase. In this context, a word means strictly a sequence of letters. This method does not support supplementary Unicode characters. + + <h2 id="upper">upper</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.upper()</pre></p> + + Returns the upper case version of this string. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/core/tuple.mdx b/rules/lib/core/tuple.mdx new file mode 100644 index 0000000..c517520 --- /dev/null +++ b/rules/lib/core/tuple.mdx @@ -0,0 +1,29 @@ +--- +title: 'tuple' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.tuple">tuple</h1> + +{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/Tuple.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The built-in tuple type. Example tuple expressions:<br><pre class=language-python>x = (1, 2, 3)</pre>Accessing elements is possible using indexing (starts from <code>0</code>):<br><pre class=language-python>e = x[1] # e == 2</pre>Lists support the <code>+</code> operator to concatenate two tuples. Example:<br><pre class=language-python>x = (1, 2) + (3, 4) # x == (1, 2, 3, 4) +x = ("a", "b") +x += ("c",) # x == ("a", "b", "c")</pre>Similar to lists, tuples support slice operations:<pre class=language-python>('a', 'b', 'c', 'd')[1:3] # ('b', 'c') +('a', 'b', 'c', 'd')[::2] # ('a', 'c') +('a', 'b', 'c', 'd')[3:0:-1] # ('d', 'c', 'b')</pre>Tuples are immutable, therefore <code>x[1] = "a"</code> is not supported. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments.mdx b/rules/lib/fragments.mdx new file mode 100644 index 0000000..2578698 --- /dev/null +++ b/rules/lib/fragments.mdx @@ -0,0 +1,42 @@ +--- +title: 'fragments' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> +<h1 class="page-title">Configuration Fragments</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +Configuration fragments give rules access to language-specific parts of <a href="builtins/configuration.html">configuration</a>. <p>Rule implementations can get them using <code><a href="builtins/ctx.html#fragments">ctx.fragments</a>.<i>[fragment name]</i></code> + +<ul> + +<li><a href="/rules/lib/fragments/apple">apple</a></li> + +<li><a href="/rules/lib/fragments/bazel_android">bazel_android</a></li> + +<li><a href="/rules/lib/fragments/bazel_py">bazel_py</a></li> + +<li><a href="/rules/lib/fragments/coverage">coverage</a></li> + +<li><a href="/rules/lib/fragments/cpp">cpp</a></li> + +<li><a href="/rules/lib/fragments/j2objc">j2objc</a></li> + +<li><a href="/rules/lib/fragments/java">java</a></li> + +<li><a href="/rules/lib/fragments/objc">objc</a></li> + +<li><a href="/rules/lib/fragments/platform">platform</a></li> + +<li><a href="/rules/lib/fragments/proto">proto</a></li> + +<li><a href="/rules/lib/fragments/py">py</a></li> +</ul> +</body> +</html> diff --git a/rules/lib/fragments/apple.mdx b/rules/lib/fragments/apple.mdx new file mode 100644 index 0000000..c186887 --- /dev/null +++ b/rules/lib/fragments/apple.mdx @@ -0,0 +1,79 @@ +--- +title: 'apple' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.apple">apple</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A configuration fragment for Apple platforms. + +<h2>Members</h2> +<ul> + <li> + <a href="#multi_arch_platform">multi_arch_platform</a> + </li> + <li> + <a href="#single_arch_cpu">single_arch_cpu</a> + </li> + <li> + <a href="#single_arch_platform">single_arch_platform</a> + </li> + </ul> + + <h2 id="multi_arch_platform">multi_arch_platform</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/apple_platform.html">apple_platform</a> apple.multi_arch_platform(platform_type)</pre></p> + + The platform of the current configuration for the given platform type. This should only be invoked in a context where multiple architectures may be supported; consider <a href='#single_arch_platform'>single_arch_platform</a> for other cases. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="multi_arch_platform.platform_type"> + <code>platform_type</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The apple platform type. + </td> + </tr> + </tbody> + </table> + + <h2 id="single_arch_cpu">single_arch_cpu</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> apple.single_arch_cpu</pre></p> + + The single "effective" architecture for this configuration (e.g., <code>i386</code> or <code>arm64</code>) in the context of rule logic that is only concerned with a single architecture (such as <code>objc_library</code>, which registers single-architecture compile actions). + + <h2 id="single_arch_platform">single_arch_platform</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/apple_platform.html">apple_platform</a> apple.single_arch_platform</pre></p> + + The platform of the current configuration. This should only be invoked in a context where only a single architecture may be supported; consider <a href='#multi_arch_platform'>multi_arch_platform</a> for other cases. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/bazel_android.mdx b/rules/lib/fragments/bazel_android.mdx new file mode 100644 index 0000000..5077e73 --- /dev/null +++ b/rules/lib/fragments/bazel_android.mdx @@ -0,0 +1,36 @@ +--- +title: 'bazel_android' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.bazel_android">bazel_android</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/rules/android/BazelAndroidConfiguration.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + + + +<h2>Members</h2> +<ul> + <li> + <a href="#merge_android_manifest_permissions">merge_android_manifest_permissions</a> + </li> + </ul> + + <h2 id="merge_android_manifest_permissions">merge_android_manifest_permissions</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> bazel_android.merge_android_manifest_permissions</pre></p> + + The value of --merge_android_manifest_permissions flag. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/bazel_py.mdx b/rules/lib/fragments/bazel_py.mdx new file mode 100644 index 0000000..44e3174 --- /dev/null +++ b/rules/lib/fragments/bazel_py.mdx @@ -0,0 +1,44 @@ +--- +title: 'bazel_py' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.bazel_py">bazel_py</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + + + +<h2>Members</h2> +<ul> + <li> + <a href="#python_import_all_repositories">python_import_all_repositories</a> + </li> + <li> + <a href="#python_path">python_path</a> + </li> + </ul> + + <h2 id="python_import_all_repositories">python_import_all_repositories</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> bazel_py.python_import_all_repositories</pre></p> + + The value of the --experimental_python_import_all_repositories flag. + + <h2 id="python_path">python_path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> bazel_py.python_path</pre></p> + + The value of the --python_path flag. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/coverage.mdx b/rules/lib/fragments/coverage.mdx new file mode 100644 index 0000000..40a4ec7 --- /dev/null +++ b/rules/lib/fragments/coverage.mdx @@ -0,0 +1,37 @@ +--- +title: 'coverage' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.coverage">coverage</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A configuration fragment representing the coverage configuration. + +<h2>Members</h2> +<ul> + <li> + <a href="#output_generator">output_generator</a> + </li> + </ul> + + <h2 id="output_generator">output_generator</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> coverage.output_generator</pre></p> + + Returns the label pointed to by the <a href="https://bazel.build/reference/command-line-reference#flag--coverage_output_generator"><code>--coverage_output_generator</code></a> option if coverage collection is enabled, otherwise returns <code>None</code>. Can be accessed with <a href="../globals/bzl.html#configuration_field"><code>configuration_field</code></a>:<br/><pre>attr.label(<br/> default = configuration_field(<br/> fragment = "coverage",<br/> name = "output_generator"<br/> )<br/>)</pre> + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/cpp.mdx b/rules/lib/fragments/cpp.mdx new file mode 100644 index 0000000..385b7a5 --- /dev/null +++ b/rules/lib/fragments/cpp.mdx @@ -0,0 +1,101 @@ +--- +title: 'cpp' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.cpp">cpp</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A configuration fragment for C++. + +<h2>Members</h2> +<ul> + <li> + <a href="#apple_generate_dsym">apple_generate_dsym</a> + </li> + <li> + <a href="#conlyopts">conlyopts</a> + </li> + <li> + <a href="#copts">copts</a> + </li> + <li> + <a href="#custom_malloc">custom_malloc</a> + </li> + <li> + <a href="#cxxopts">cxxopts</a> + </li> + <li> + <a href="#linkopts">linkopts</a> + </li> + <li> + <a href="#objc_generate_linkmap">objc_generate_linkmap</a> + </li> + <li> + <a href="#objc_should_strip_binary">objc_should_strip_binary</a> + </li> + <li> + <a href="#objccopts">objccopts</a> + </li> + </ul> + + <h2 id="apple_generate_dsym">apple_generate_dsym</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cpp.apple_generate_dsym</pre></p> + + Whether to generate Apple debug symbol(.dSYM) artifacts. + + <h2 id="conlyopts">conlyopts</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.conlyopts</pre></p> + + The flags passed to Bazel by <a href="/docs/user-manual#flag--conlyopt"><code>--conlyopt</code></a> option. + + <h2 id="copts">copts</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.copts</pre></p> + + The flags passed to Bazel by <a href="/docs/user-manual#flag--copt"><code>--copt</code></a> option. + + <h2 id="custom_malloc">custom_malloc</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> cpp.custom_malloc</pre></p> + + Returns label pointed to by <a href="/docs/user-manual#flag--custom_malloc"><code>--custom_malloc</code></a> option. Can be accessed with <a href="../globals/bzl.html#configuration_field"><code>configuration_field</code></a>:<br/><pre>attr.label(<br/> default = configuration_field(<br/> fragment = "cpp",<br/> name = "custom_malloc"<br/> )<br/>)</pre> + May return <code>None</code>. + + <h2 id="cxxopts">cxxopts</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.cxxopts</pre></p> + + The flags passed to Bazel by <a href="/docs/user-manual#flag--cxxopt"><code>--cxxopt</code></a> option. + + <h2 id="linkopts">linkopts</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.linkopts</pre></p> + + The flags passed to Bazel by <a href="/docs/user-manual#flag--linkopt"><code>--linkopt</code></a> option. + + <h2 id="objc_generate_linkmap">objc_generate_linkmap</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cpp.objc_generate_linkmap</pre></p> + + (Apple-only) Whether to generate linkmap artifacts. + + <h2 id="objc_should_strip_binary">objc_should_strip_binary</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cpp.objc_should_strip_binary</pre></p> + + (Apple-only) whether to perform symbol and dead-code strippings on linked binaries. + + <h2 id="objccopts">objccopts</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.objccopts</pre></p> + + The flags passed to Bazel by <a href="/docs/user-manual#flag--objccopt"><code>--objccopt</code></a> option. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/j2objc.mdx b/rules/lib/fragments/j2objc.mdx new file mode 100644 index 0000000..05e9d79 --- /dev/null +++ b/rules/lib/fragments/j2objc.mdx @@ -0,0 +1,36 @@ +--- +title: 'j2objc' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.j2objc">j2objc</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/J2ObjcConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A configuration fragment for j2Objc. + +<h2>Members</h2> +<ul> + <li> + <a href="#translation_flags">translation_flags</a> + </li> + </ul> + + <h2 id="translation_flags">translation_flags</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> j2objc.translation_flags</pre></p> + + The list of flags to be used when the j2objc compiler is invoked. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/java.mdx b/rules/lib/fragments/java.mdx new file mode 100644 index 0000000..729eab5 --- /dev/null +++ b/rules/lib/fragments/java.mdx @@ -0,0 +1,140 @@ +--- +title: 'java' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.java">java</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A java compiler configuration. + +<h2>Members</h2> +<ul> + <li> + <a href="#bytecode_optimization_pass_actions">bytecode_optimization_pass_actions</a> + </li> + <li> + <a href="#bytecode_optimizer_mnemonic">bytecode_optimizer_mnemonic</a> + </li> + <li> + <a href="#default_javac_flags">default_javac_flags</a> + </li> + <li> + <a href="#default_javac_flags_depset">default_javac_flags_depset</a> + </li> + <li> + <a href="#default_jvm_opts">default_jvm_opts</a> + </li> + <li> + <a href="#disallow_java_import_exports">disallow_java_import_exports</a> + </li> + <li> + <a href="#multi_release_deploy_jars">multi_release_deploy_jars</a> + </li> + <li> + <a href="#one_version_enforcement_level">one_version_enforcement_level</a> + </li> + <li> + <a href="#plugins">plugins</a> + </li> + <li> + <a href="#run_android_lint">run_android_lint</a> + </li> + <li> + <a href="#split_bytecode_optimization_pass">split_bytecode_optimization_pass</a> + </li> + <li> + <a href="#strict_java_deps">strict_java_deps</a> + </li> + <li> + <a href="#use_header_compilation_direct_deps">use_header_compilation_direct_deps</a> + </li> + <li> + <a href="#use_ijars">use_ijars</a> + </li> + </ul> + + <h2 id="bytecode_optimization_pass_actions">bytecode_optimization_pass_actions</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> java.bytecode_optimization_pass_actions</pre></p> + + This specifies the number of actions to divide the OPTIMIZATION stage of the bytecode optimizer into. Note that if split_bytecode_optimization_pass is set, this will only change behavior if it is > 2. + + <h2 id="bytecode_optimizer_mnemonic">bytecode_optimizer_mnemonic</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> java.bytecode_optimizer_mnemonic</pre></p> + + The mnemonic for the bytecode optimizer. + + <h2 id="default_javac_flags">default_javac_flags</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java.default_javac_flags</pre></p> + + The default flags for the Java compiler. + + <h2 id="default_javac_flags_depset">default_javac_flags_depset</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java.default_javac_flags_depset</pre></p> + + The default flags for the Java compiler. + + <h2 id="default_jvm_opts">default_jvm_opts</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java.default_jvm_opts</pre></p> + + Additional options to pass to the Java VM for each java_binary target + + <h2 id="disallow_java_import_exports">disallow_java_import_exports</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.disallow_java_import_exports()</pre></p> + + Returns true if java_import exports are not allowed. + + <h2 id="multi_release_deploy_jars">multi_release_deploy_jars</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.multi_release_deploy_jars</pre></p> + + The value of the --incompatible_multi_release_deploy_jars flag. + + <h2 id="one_version_enforcement_level">one_version_enforcement_level</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> java.one_version_enforcement_level</pre></p> + + The value of the --experimental_one_version_enforcement flag. + + <h2 id="plugins">plugins</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java.plugins</pre></p> + + A list containing the labels provided with --plugins, if any. + + <h2 id="run_android_lint">run_android_lint</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.run_android_lint</pre></p> + + The value of the --experimental_run_android_lint_on_java_rules flag. + + <h2 id="split_bytecode_optimization_pass">split_bytecode_optimization_pass</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.split_bytecode_optimization_pass</pre></p> + + Returns whether the OPTIMIZATION stage of the bytecode optimizer will be split across two actions. + + <h2 id="strict_java_deps">strict_java_deps</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> java.strict_java_deps</pre></p> + + The value of the strict_java_deps flag. + + <h2 id="use_header_compilation_direct_deps">use_header_compilation_direct_deps</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.use_header_compilation_direct_deps()</pre></p> + + Returns true if Java header compilation should use separate outputs for direct deps. + + <h2 id="use_ijars">use_ijars</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.use_ijars()</pre></p> + + Returns true iff Java compilation should use ijars. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/objc.mdx b/rules/lib/fragments/objc.mdx new file mode 100644 index 0000000..d560201 --- /dev/null +++ b/rules/lib/fragments/objc.mdx @@ -0,0 +1,111 @@ +--- +title: 'objc' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.objc">objc</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ObjcConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A configuration fragment for Objective-C. + +<h2>Members</h2> +<ul> + <li> + <a href="#alwayslink_by_default">alwayslink_by_default</a> + </li> + <li> + <a href="#builtin_objc_strip_action">builtin_objc_strip_action</a> + </li> + <li> + <a href="#copts_for_current_compilation_mode">copts_for_current_compilation_mode</a> + </li> + <li> + <a href="#disallow_sdk_frameworks_attributes">disallow_sdk_frameworks_attributes</a> + </li> + <li> + <a href="#ios_simulator_device">ios_simulator_device</a> + </li> + <li> + <a href="#ios_simulator_version">ios_simulator_version</a> + </li> + <li> + <a href="#run_memleaks">run_memleaks</a> + </li> + <li> + <a href="#signing_certificate_name">signing_certificate_name</a> + </li> + <li> + <a href="#strip_executable_safely">strip_executable_safely</a> + </li> + <li> + <a href="#uses_device_debug_entitlements">uses_device_debug_entitlements</a> + </li> + </ul> + + <h2 id="alwayslink_by_default">alwayslink_by_default</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.alwayslink_by_default</pre></p> + + Returns whether objc_library and objc_import should default to alwayslink=True. + + <h2 id="builtin_objc_strip_action">builtin_objc_strip_action</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.builtin_objc_strip_action</pre></p> + + Returns whether to emit a strip action as part of objc linking. + + <h2 id="copts_for_current_compilation_mode">copts_for_current_compilation_mode</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> objc.copts_for_current_compilation_mode</pre></p> + + Returns a list of default options to use for compiling Objective-C in the current mode. + + <h2 id="disallow_sdk_frameworks_attributes">disallow_sdk_frameworks_attributes</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.disallow_sdk_frameworks_attributes</pre></p> + + Returns whether sdk_frameworks and weak_sdk_frameworks are disallowed attributes. + + <h2 id="ios_simulator_device">ios_simulator_device</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> objc.ios_simulator_device</pre></p> + + The type of device (e.g. 'iPhone 6') to use when running on the simulator. + May return <code>None</code>. + + <h2 id="ios_simulator_version">ios_simulator_version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/DottedVersion.html">DottedVersion</a> objc.ios_simulator_version</pre></p> + + The SDK version of the iOS simulator to use when running on the simulator. + May return <code>None</code>. + + <h2 id="run_memleaks">run_memleaks</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.run_memleaks</pre></p> + + Returns a boolean indicating whether memleaks should be run during tests or not. + + <h2 id="signing_certificate_name">signing_certificate_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> objc.signing_certificate_name</pre></p> + + Returns the flag-supplied certificate name to be used in signing, or None if no such certificate was specified. + May return <code>None</code>. + + <h2 id="strip_executable_safely">strip_executable_safely</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.strip_executable_safely</pre></p> + + Returns whether executable strip action should use flag -x, which does not break dynamic symbol resolution. + + <h2 id="uses_device_debug_entitlements">uses_device_debug_entitlements</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.uses_device_debug_entitlements</pre></p> + + Returns whether device debug entitlements should be included when signing an application. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/platform.mdx b/rules/lib/fragments/platform.mdx new file mode 100644 index 0000000..877d00c --- /dev/null +++ b/rules/lib/fragments/platform.mdx @@ -0,0 +1,44 @@ +--- +title: 'platform' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.platform">platform</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The platform configuration. + +<h2>Members</h2> +<ul> + <li> + <a href="#host_platform">host_platform</a> + </li> + <li> + <a href="#platform">platform</a> + </li> + </ul> + + <h2 id="host_platform">host_platform</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> platform.host_platform</pre></p> + + The current host platform + + <h2 id="platform">platform</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> platform.platform</pre></p> + + The current target platform + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/proto.mdx b/rules/lib/fragments/proto.mdx new file mode 100644 index 0000000..a9686e6 --- /dev/null +++ b/rules/lib/fragments/proto.mdx @@ -0,0 +1,25 @@ +--- +title: 'proto' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.proto">proto</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ProtoConfigurationApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A configuration fragment representing protocol buffers. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/fragments/py.mdx b/rules/lib/fragments/py.mdx new file mode 100644 index 0000000..06080f0 --- /dev/null +++ b/rules/lib/fragments/py.mdx @@ -0,0 +1,84 @@ +--- +title: 'py' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.py">py</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/rules/python/PythonConfiguration.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A configuration fragment for Python. + +<h2>Members</h2> +<ul> + <li> + <a href="#build_python_zip">build_python_zip</a> + </li> + <li> + <a href="#default_python_version">default_python_version</a> + </li> + <li> + <a href="#default_to_explicit_init_py">default_to_explicit_init_py</a> + </li> + <li> + <a href="#disable_py2">disable_py2</a> + </li> + <li> + <a href="#disallow_native_rules">disallow_native_rules</a> + </li> + <li> + <a href="#include_label_in_linkstamp">include_label_in_linkstamp</a> + </li> + <li> + <a href="#use_toolchains">use_toolchains</a> + </li> + </ul> + + <h2 id="build_python_zip">build_python_zip</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.build_python_zip</pre></p> + + The effective value of --build_python_zip + + <h2 id="default_python_version">default_python_version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> py.default_python_version</pre></p> + + No-op: PY3 is the default Python version. + + <h2 id="default_to_explicit_init_py">default_to_explicit_init_py</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.default_to_explicit_init_py</pre></p> + + The value from the --incompatible_default_to_explicit_init_py flag + + <h2 id="disable_py2">disable_py2</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.disable_py2</pre></p> + + No-op: PY2 is no longer supported. + + <h2 id="disallow_native_rules">disallow_native_rules</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.disallow_native_rules</pre></p> + + The value of the --incompatible_python_disallow_native_rules flag. + + <h2 id="include_label_in_linkstamp">include_label_in_linkstamp</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.include_label_in_linkstamp</pre></p> + + Whether the build label is included in unstamped builds. + + <h2 id="use_toolchains">use_toolchains</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.use_toolchains</pre></p> + + No-op: Python toolchains are always used. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/globals.mdx b/rules/lib/globals.mdx new file mode 100644 index 0000000..5d948e3 --- /dev/null +++ b/rules/lib/globals.mdx @@ -0,0 +1,32 @@ +--- +title: 'globals' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> +<h1 class="page-title">Global functions</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +This section lists the global functions available in Starlark. The list of available functions differs depending on the file type (whether a BUILD file, or a .bzl file, etc). + +<ul> + +<li><a href="/rules/lib/globals/bzl">.bzl files</a></li> + +<li><a href="/rules/lib/globals/all">All Bazel files</a></li> + +<li><a href="/rules/lib/globals/build">BUILD files</a></li> + +<li><a href="/rules/lib/globals/module">MODULE.bazel files</a></li> + +<li><a href="/rules/lib/globals/repo">REPO.bazel files</a></li> + +<li><a href="/rules/lib/globals/vendor">VENDOR.bazel files</a></li> +</ul> +</body> +</html> diff --git a/rules/lib/globals/all.mdx b/rules/lib/globals/all.mdx new file mode 100644 index 0000000..ee767ec --- /dev/null +++ b/rules/lib/globals/all.mdx @@ -0,0 +1,1169 @@ +--- +title: 'all' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.all">All Bazel files</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Methods available in all Bazel files, including .bzl files, BUILD, MODULE.bazel, VENDOR.bazel, and WORKSPACE. + +<h2>Members</h2> +<ul> + <li> + <a href="#abs">abs</a> + </li> + <li> + <a href="#all">all</a> + </li> + <li> + <a href="#any">any</a> + </li> + <li> + <a href="#bool">bool</a> + </li> + <li> + <a href="#dict">dict</a> + </li> + <li> + <a href="#dir">dir</a> + </li> + <li> + <a href="#enumerate">enumerate</a> + </li> + <li> + <a href="#fail">fail</a> + </li> + <li> + <a href="#float">float</a> + </li> + <li> + <a href="#getattr">getattr</a> + </li> + <li> + <a href="#hasattr">hasattr</a> + </li> + <li> + <a href="#hash">hash</a> + </li> + <li> + <a href="#int">int</a> + </li> + <li> + <a href="#len">len</a> + </li> + <li> + <a href="#list">list</a> + </li> + <li> + <a href="#max">max</a> + </li> + <li> + <a href="#min">min</a> + </li> + <li> + <a href="#print">print</a> + </li> + <li> + <a href="#range">range</a> + </li> + <li> + <a href="#repr">repr</a> + </li> + <li> + <a href="#reversed">reversed</a> + </li> + <li> + <a href="#set">set</a> + </li> + <li> + <a href="#sorted">sorted</a> + </li> + <li> + <a href="#str">str</a> + </li> + <li> + <a href="#tuple">tuple</a> + </li> + <li> + <a href="#type">type</a> + </li> + <li> + <a href="#zip">zip</a> + </li> + </ul> + + <h2 id="abs">abs</h2> + <p><pre class="rule-signature">unknown abs(x)</pre></p> + + Returns the absolute value of a number (a non-negative number with the same magnitude).<pre class="language-python">abs(-2.3) == 2.3</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="abs.x"> + <code>x</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; or <a class="anchor" href="../core/float.html">float</a>; + required<br/> + A number (int or float) + </td> + </tr> + </tbody> + </table> + + <h2 id="all">all</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> all(elements)</pre></p> + + Returns true if all elements evaluate to True or if the collection is empty. Elements are converted to boolean using the <a href="#bool">bool</a> function.<pre class="language-python">all(["hello", 3, True]) == True +all([-1, 0, 1]) == False</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="all.elements"> + <code>elements</code> + </td> + <td> + iterable; + required<br/> + A collection of elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="any">any</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> any(elements)</pre></p> + + Returns true if at least one element evaluates to True. Elements are converted to boolean using the <a href="#bool">bool</a> function.<pre class="language-python">any([-1, 0, 1]) == True +any([False, 0, ""]) == False</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="any.elements"> + <code>elements</code> + </td> + <td> + iterable; + required<br/> + A collection of elements. + </td> + </tr> + </tbody> + </table> + + <h2 id="bool">bool</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> bool(x=False)</pre></p> + + Constructor for the bool type. It returns <code>False</code> if the object is <code>None</code>, <code>False</code>, an empty string (<code>""</code>), the number <code>0</code>, or an empty collection (e.g. <code>()</code>, <code>[]</code>). Otherwise, it returns <code>True</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="bool.x"> + <code>x</code> + </td> + <td> + default is <code>False</code><br/> + The variable to convert. + </td> + </tr> + </tbody> + </table> + + <h2 id="dict">dict</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> dict(pairs=[], **kwargs)</pre></p> + + Creates a <a href="../core/dict.html">dictionary</a> from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="dict.pairs"> + <code>pairs</code> + </td> + <td> + default is <code>[]</code><br/> + A dict, or an iterable whose elements are each of length 2 (key, value). + </td> + </tr> + <tr> + <td id="dict.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + Dictionary of additional entries. + </td> + </tr> + </tbody> + </table> + + <h2 id="dir">dir</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dir(x)</pre></p> + + Returns a list of strings: the names of the attributes and methods of the parameter object. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="dir.x"> + <code>x</code> + </td> + <td> + required<br/> + The object to check. + </td> + </tr> + </tbody> + </table> + + <h2 id="enumerate">enumerate</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> enumerate(list, start=0)</pre></p> + + Returns a list of pairs (two-element tuples), with the index (int) and the item from the input sequence. +<pre class="language-python">enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="enumerate.list"> + <code>list</code> + </td> + <td> + required<br/> + input sequence. + </td> + </tr> + <tr> + <td id="enumerate.start"> + <code>start</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>0</code><br/> + start index. + </td> + </tr> + </tbody> + </table> + + <h2 id="fail">fail</h2> + <p><pre class="rule-signature"><code>None</code> fail(*args, msg=None, attr=None, sep=" ")</pre></p> + + Causes execution to fail with an error. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="fail.msg"> + <code>msg</code> + </td> + <td> + default is <code>None</code><br/> + Deprecated: use positional arguments instead. This argument acts like an implicit leading positional argument. + </td> + </tr> + <tr> + <td id="fail.attr"> + <code>attr</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Deprecated. Causes an optional prefix containing this string to be added to the error message. + </td> + </tr> + <tr> + <td id="fail.sep"> + <code>sep</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>" "</code><br/> + The separator string between the objects, default is space (" "). + </td> + </tr> + <tr> + <td id="fail.args"> + <code>args</code> + </td> + <td> + required<br/> + A list of values, formatted with debugPrint (which is equivalent to str by default) and joined with sep (defaults to " "), that appear in the error message. + </td> + </tr> + </tbody> + </table> + + <h2 id="float">float</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/float.html">float</a> float(x=unbound)</pre></p> + + Returns x as a float value. <ul><li>If <code>x</code> is already a float, <code>float</code> returns it unchanged. <li>If <code>x</code> is a bool, <code>float</code> returns 1.0 for True and 0.0 for False. <li>If <code>x</code> is an int, <code>float</code> returns the nearest finite floating-point value to x, or an error if the magnitude is too large. <li>If <code>x</code> is a string, it must be a valid floating-point literal, or be equal (ignoring case) to <code>NaN</code>, <code>Inf</code>, or <code>Infinity</code>, optionally preceded by a <code>+</code> or <code>-</code> sign. </ul>Any other value causes an error. With no argument, <code>float()</code> returns 0.0. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="float.x"> + <code>x</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/int.html">int</a>; or <a class="anchor" href="../core/float.html">float</a>; + default is <code>unbound</code><br/> + The value to convert. + </td> + </tr> + </tbody> + </table> + + <h2 id="getattr">getattr</h2> + <p><pre class="rule-signature">unknown getattr(x, name, default=unbound)</pre></p> + + Returns the struct's field of the given name if it exists. If not, it either returns <code>default</code> (if specified) or raises an error. <code>getattr(x, "foobar")</code> is equivalent to <code>x.foobar</code>.<pre class="language-python">getattr(ctx.attr, "myattr") +getattr(ctx.attr, "myattr", "mydefault")</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="getattr.x"> + <code>x</code> + </td> + <td> + required<br/> + The struct whose attribute is accessed. + </td> + </tr> + <tr> + <td id="getattr.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the struct attribute. + </td> + </tr> + <tr> + <td id="getattr.default"> + <code>default</code> + </td> + <td> + default is <code>unbound</code><br/> + The default value to return in case the struct doesn't have an attribute of the given name. + </td> + </tr> + </tbody> + </table> + + <h2 id="hasattr">hasattr</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> hasattr(x, name)</pre></p> + + Returns True if the object <code>x</code> has an attribute or method of the given <code>name</code>, otherwise False. Example:<br><pre class="language-python">hasattr(ctx.attr, "myattr")</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="hasattr.x"> + <code>x</code> + </td> + <td> + required<br/> + The object to check. + </td> + </tr> + <tr> + <td id="hasattr.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the attribute. + </td> + </tr> + </tbody> + </table> + + <h2 id="hash">hash</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> hash(value)</pre></p> + + Return a hash value for a string. This is computed deterministically using the same algorithm as Java's <code>String.hashCode()</code>, namely: <pre class="language-python">s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1]</pre> Hashing of values besides strings is not currently supported. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="hash.value"> + <code>value</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + String value to hash. + </td> + </tr> + </tbody> + </table> + + <h2 id="int">int</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> int(x, base=unbound)</pre></p> + + Returns x as an int value.<ul><li>If <code>x</code> is already an int, <code>int</code> returns it unchanged.<li>If <code>x</code> is a bool, <code>int</code> returns 1 for True and 0 for False.<li>If <code>x</code> is a string, it must have the format <code><sign><prefix><digits></code>. <code><sign></code> is either <code>"+"</code>, <code>"-"</code>, or empty (interpreted as positive). <code><digits></code> are a sequence of digits from 0 up to <code>base</code> - 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where <code>base</code> is 2/8/16, <code><prefix></code> is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the <code>base</code> is any other value besides these bases or the special value 0, the prefix must be empty. In the case where <code>base</code> is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If <code>base</code> is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type.<li>If <code>x</code> is a float, <code>int</code> returns the integer value of the float, rounding towards zero. It is an error if x is non-finite (NaN or infinity).</ul>This function fails if <code>x</code> is any other type, or if the value is a string not satisfying the above format. Unlike Python's <code>int</code> function, this function does not allow zero arguments, and does not allow extraneous whitespace for string arguments.<p>Examples:<pre class="language-python">int("123") == 123 +int("-123") == -123 +int("+123") == 123 +int("FF", 16) == 255 +int("0xFF", 16) == 255 +int("10", 0) == 10 +int("-0x10", 0) == -16 +int("-0x10", 0) == -16 +int("123.456") == 123 +</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="int.x"> + <code>x</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/int.html">int</a>; or <a class="anchor" href="../core/float.html">float</a>; + required<br/> + The string to convert. + </td> + </tr> + <tr> + <td id="int.base"> + <code>base</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>unbound</code><br/> + The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if <code>x</code> were an integer literal. This parameter must not be supplied if the value is not a string. + </td> + </tr> + </tbody> + </table> + + <h2 id="len">len</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> len(x)</pre></p> + + Returns the length of a string, sequence (such as a list or tuple), dict, set, or other iterable. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="len.x"> + <code>x</code> + </td> + <td> + iterable; or <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The value whose length to report. + </td> + </tr> + </tbody> + </table> + + <h2 id="list">list</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> list(x=[])</pre></p> + + Returns a new list with the same elements as the given iterable value.<pre class="language-python">list([1, 2]) == [1, 2] +list((2, 3, 2)) == [2, 3, 2] +list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4]</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="list.x"> + <code>x</code> + </td> + <td> + iterable; + default is <code>[]</code><br/> + The object to convert. + </td> + </tr> + </tbody> + </table> + + <h2 id="max">max</h2> + <p><pre class="rule-signature">unknown max(*args, key=None)</pre></p> + + Returns the largest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable.It is an error if elements are not comparable (for example int with string), or if no arguments are given.<pre class="language-python"> +max(2, 5, 4) == 5 +max([5, 6, 3]) == 6 +max("two", "three", "four", key = len) =="three" # the longest +max([1, -1, -2, 2], key = abs) == -2 # the first encountered with maximal key value +</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="max.key"> + <code>key</code> + </td> + <td> + callable; or <code>None</code>; + default is <code>None</code><br/> + An optional function applied to each element before comparison. + </td> + </tr> + <tr> + <td id="max.args"> + <code>args</code> + </td> + <td> + required<br/> + The elements to be checked. + </td> + </tr> + </tbody> + </table> + + <h2 id="min">min</h2> + <p><pre class="rule-signature">unknown min(*args, key=None)</pre></p> + + Returns the smallest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable. It is an error if elements are not comparable (for example int with string), or if no arguments are given.<pre class="language-python"> +min(2, 5, 4) == 2 +min([5, 6, 3]) == 3 +min("six", "three", "four", key = len) == "six" # the shortest +min([2, -2, -1, 1], key = abs) == -1 # the first encountered with minimal key value +</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="min.key"> + <code>key</code> + </td> + <td> + callable; or <code>None</code>; + default is <code>None</code><br/> + An optional function applied to each element before comparison. + </td> + </tr> + <tr> + <td id="min.args"> + <code>args</code> + </td> + <td> + required<br/> + The elements to be checked. + </td> + </tr> + </tbody> + </table> + + <h2 id="print">print</h2> + <p><pre class="rule-signature"><code>None</code> print(*args, sep=" ")</pre></p> + + Prints <code>args</code> as debug output. It will be prefixed with the string <code>"DEBUG"</code> and the location (file and line number) of this call. The exact way in which the arguments are converted to strings is unspecified and may change at any time. In particular, it may be different from (and more detailed than) the formatting done by <a href='#str'><code>str()</code></a> and <a href='#repr'><code>repr()</code></a>.<p>Using <code>print</code> in production code is discouraged due to the spam it creates for users. For deprecations, prefer a hard error using <a href="#fail"><code>fail()</code></a> whenever possible. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="print.sep"> + <code>sep</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>" "</code><br/> + The separator string between the objects, default is space (" "). + </td> + </tr> + <tr> + <td id="print.args"> + <code>args</code> + </td> + <td> + required<br/> + The objects to print. + </td> + </tr> + </tbody> + </table> + + <h2 id="range">range</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> range(start_or_stop, stop=unbound, step=1)</pre></p> + + Creates a list where items go from <code>start</code> to <code>stop</code>, using a <code>step</code> increment. If a single argument is provided, items will range from 0 to that element.<pre class="language-python">range(4) == [0, 1, 2, 3] +range(3, 9, 2) == [3, 5, 7] +range(3, 0, -1) == [3, 2, 1]</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="range.start_or_stop"> + <code>start_or_stop</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + required<br/> + Value of the start element if stop is provided, otherwise value of stop and the actual start is 0 + </td> + </tr> + <tr> + <td id="range.stop"> + <code>stop</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>unbound</code><br/> + optional index of the first item <i>not</i> to be included in the resulting list; generation of the list stops before <code>stop</code> is reached. + </td> + </tr> + <tr> + <td id="range.step"> + <code>step</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>1</code><br/> + The increment (default is 1). It may be negative. + </td> + </tr> + </tbody> + </table> + + <h2 id="repr">repr</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repr(x)</pre></p> + + Converts any object to a string representation. This is useful for debugging.<br><pre class="language-python">repr("ab") == '"ab"'</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="repr.x"> + <code>x</code> + </td> + <td> + required<br/> + The object to convert. + </td> + </tr> + </tbody> + </table> + + <h2 id="reversed">reversed</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> reversed(sequence)</pre></p> + + Returns a new, unfrozen list that contains the elements of the original iterable sequence in reversed order.<pre class="language-python">reversed([3, 5, 4]) == [4, 5, 3]</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="reversed.sequence"> + <code>sequence</code> + </td> + <td> + iterable; + required<br/> + The iterable sequence (e.g. list) to be reversed. + </td> + </tr> + </tbody> + </table> + + <h2 id="set">set</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set(elements=[])</pre></p> + + Creates a new <a href="../core/set.html">set</a> containing the unique elements of a given +iterable, preserving iteration order. + +<p>If called with no argument, <code>set()</code> returns a new empty set. + +<p>For example, +<pre class=language-python> +set() # an empty set +set([3, 1, 1, 2]) # set([3, 1, 2]), a set of three elements +set({"k1": "v1", "k2": "v2"}) # set(["k1", "k2"]), a set of two elements +</pre> + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="set.elements"> + <code>elements</code> + </td> + <td> + iterable; + default is <code>[]</code><br/> + An iterable of hashable values. + </td> + </tr> + </tbody> + </table> + + <h2 id="sorted">sorted</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> sorted(iterable, key=None, *, reverse=False)</pre></p> + + Returns a new sorted list containing all the elements of the supplied iterable sequence. An error may occur if any pair of elements x, y may not be compared using x < y. The elements are sorted into ascending order, unless the reverse argument is True, in which case the order is descending. + Sorting is stable: elements that compare equal retain their original relative order. +<pre class="language-python"> +sorted([3, 5, 4]) == [3, 4, 5] +sorted([3, 5, 4], reverse = True) == [5, 4, 3] +sorted(["two", "three", "four"], key = len) == ["two", "four", "three"] # sort by length +</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="sorted.iterable"> + <code>iterable</code> + </td> + <td> + iterable; + required<br/> + The iterable sequence to sort. + </td> + </tr> + <tr> + <td id="sorted.key"> + <code>key</code> + </td> + <td> + callable; or <code>None</code>; + default is <code>None</code><br/> + An optional function applied to each element before comparison. + </td> + </tr> + <tr> + <td id="sorted.reverse"> + <code>reverse</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Return results in descending order. + </td> + </tr> + </tbody> + </table> + + <h2 id="str">str</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> str(x)</pre></p> + + Converts any object to string. This is useful for debugging.<pre class="language-python">str("ab") == "ab" +str(8) == "8"</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="str.x"> + <code>x</code> + </td> + <td> + required<br/> + The object to convert. + </td> + </tr> + </tbody> + </table> + + <h2 id="tuple">tuple</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> tuple(x=())</pre></p> + + Returns a tuple with the same elements as the given iterable value.<pre class="language-python">tuple([1, 2]) == (1, 2) +tuple((2, 3, 2)) == (2, 3, 2) +tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4)</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="tuple.x"> + <code>x</code> + </td> + <td> + iterable; + default is <code>()</code><br/> + The object to convert. + </td> + </tr> + </tbody> + </table> + + <h2 id="type">type</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> type(x)</pre></p> + + Returns the type name of its argument. This is useful for debugging and type-checking. Examples:<pre class="language-python">type(2) == "int" +type([1]) == "list" +type(struct(a = 2)) == "struct"</pre>This function might change in the future. To write Python-compatible code and be future-proof, use it only to compare return values: <pre class="language-python">if type(x) == type([]): # if x is a list</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="type.x"> + <code>x</code> + </td> + <td> + required<br/> + The object to check type of. + </td> + </tr> + </tbody> + </table> + + <h2 id="zip">zip</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> zip(*args)</pre></p> + + Returns a <code>list</code> of <code>tuple</code>s, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The list has the size of the shortest input. With a single iterable argument, it returns a list of 1-tuples. With no arguments, it returns an empty list. Examples:<pre class="language-python">zip() # == [] +zip([1, 2]) # == [(1,), (2,)] +zip([1, 2], [3, 4]) # == [(1, 3), (2, 4)] +zip([1, 2], [3, 4, 5]) # == [(1, 3), (2, 4)]</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="zip.args"> + <code>args</code> + </td> + <td> + required<br/> + lists to zip. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/globals/build.mdx b/rules/lib/globals/build.mdx new file mode 100644 index 0000000..42eeec9 --- /dev/null +++ b/rules/lib/globals/build.mdx @@ -0,0 +1,526 @@ +--- +title: 'build' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.build">BUILD files</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Methods available in BUILD files. See also the Build Encyclopedia for extra <a href="/reference/be/functions">functions</a> and build rules, which can also be used in BUILD files. + +<h2>Members</h2> +<ul> + <li> + <a href="#depset">depset</a> + </li> + <li> + <a href="#existing_rule">existing_rule</a> + </li> + <li> + <a href="#existing_rules">existing_rules</a> + </li> + <li> + <a href="#exports_files">exports_files</a> + </li> + <li> + <a href="#glob">glob</a> + </li> + <li> + <a href="#module_name">module_name</a> + </li> + <li> + <a href="#module_version">module_version</a> + </li> + <li> + <a href="#package">package</a> + </li> + <li> + <a href="#package_default_visibility">package_default_visibility</a> + </li> + <li> + <a href="#package_group">package_group</a> + </li> + <li> + <a href="#package_name">package_name</a> + </li> + <li> + <a href="#package_relative_label">package_relative_label</a> + </li> + <li> + <a href="#repo_name">repo_name</a> + </li> + <li> + <a href="#repository_name">repository_name</a> + </li> + <li> + <a href="#select">select</a> + </li> + <li> + <a href="#subpackages">subpackages</a> + </li> + </ul> + + <h2 id="depset">depset</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> depset(direct=None, order="default", *, transitive=None)</pre></p> + + Creates a <a href="../builtins/depset.html">depset</a>. The <code>direct</code> parameter is a list of direct elements of the depset, and <code>transitive</code> parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the <code>order</code> parameter. See the <a href="https://bazel.build/extending/depsets">Depsets overview</a> for more information. +<p>All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression <a href="../globals/all#type"><code>type(x)</code></a>. +<p>Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see <a href='https://github.com/bazelbuild/bazel/issues/10313'>Issue 10313</a>. +<p>In addition, elements must currently be immutable, though this restriction will be relaxed in future. +<p> The order of the created depset should be <i>compatible</i> with the order of its <code>transitive</code> depsets. <code>"default"</code> order is compatible with any other order, all other orders are only compatible with themselves. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="depset.direct"> + <code>direct</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; + default is <code>None</code><br/> + A list of <i>direct</i> elements of a depset. + </td> + </tr> + <tr> + <td id="depset.order"> + <code>order</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>"default"</code><br/> + The traversal strategy for the new depset. See <a href="../builtins/depset.html">here</a> for the possible values. + </td> + </tr> + <tr> + <td id="depset.transitive"> + <code>transitive</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/depset.html">depset</a>s; or <code>None</code>; + default is <code>None</code><br/> + A list of depsets whose elements will become indirect elements of the depset. + </td> + </tr> + </tbody> + </table> + + <h2 id="existing_rule">existing_rule</h2> + <p><pre class="rule-signature">unknown existing_rule(name)</pre></p> + + Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or <code>None</code> if no rule instance of that name exists.<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>, <code>x.keys()</code>, and <code>x.values()</code>.<p>The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's <code>name</code> and <code>kind</code> (for example, <code>'cc_binary'</code>).<p>The values of the result represent attribute values as follows:<ul><li>Attributes of type str, int, and bool are represented as is.</li><li>Labels are converted to strings of the form <code>':foo'</code> for targets in the same package or <code>'//pkg:name'</code> for targets in a different package.</li><li>Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion.</li><li><code>select</code> values are returned with their contents transformed as described above.</li><li>Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.).</li></ul><p>If possible, use this function only in <a href="https://bazel.build/extending/macros#finalizers">implementation functions of rule finalizer symbolic macros</a>. Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes <code>BUILD</code> files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by <code>ctx.attr.foo</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="existing_rule.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the target. + </td> + </tr> + </tbody> + </table> + + <h2 id="existing_rules">existing_rules</h2> + <p><pre class="rule-signature">unknown existing_rules()</pre></p> + + Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by <code>existing_rule(name)</code>.<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>, <code>x.keys()</code>, and <code>x.values()</code>.<p>If possible, use this function only in <a href="https://bazel.build/extending/macros#finalizers">implementation functions of rule finalizer symbolic macros</a>. Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes <code>BUILD</code> files brittle and order-dependent. + + <h2 id="exports_files">exports_files</h2> + <p><pre class="rule-signature"><code>None</code> exports_files(srcs, visibility=None, licenses=None)</pre></p> + + Specifies a list of files belonging to this package that are exported to other packages. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="exports_files.srcs"> + <code>srcs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The list of files to export. + </td> + </tr> + <tr> + <td id="exports_files.visibility"> + <code>visibility</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; + default is <code>None</code><br/> + A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. + </td> + </tr> + <tr> + <td id="exports_files.licenses"> + <code>licenses</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Licenses to be specified. + </td> + </tr> + </tbody> + </table> + + <h2 id="glob">glob</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)</pre></p> + + Glob returns a new, mutable, sorted list of every file in the current package that:<ul> +<li>Matches at least one pattern in <code>include</code>.</li> +<li>Does not match any of the patterns in <code>exclude</code> (default <code>[]</code>).</li></ul> +If the <code>exclude_directories</code> argument is enabled (set to <code>1</code>), files of type directory will be omitted from the results (default <code>1</code>). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="glob.include"> + <code>include</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + The list of glob patterns to include. + </td> + </tr> + <tr> + <td id="glob.exclude"> + <code>exclude</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + The list of glob patterns to exclude. + </td> + </tr> + <tr> + <td id="glob.exclude_directories"> + <code>exclude_directories</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>1</code><br/> + A flag whether to exclude directories or not. + </td> + </tr> + <tr> + <td id="glob.allow_empty"> + <code>allow_empty</code> + </td> + <td> + default is <code>unbound</code><br/> + Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). + </td> + </tr> + </tbody> + </table> + + <h2 id="module_name">module_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> module_name()</pre></p> + + The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the <code>module.name</code> field seen in <code>module_ctx.modules</code>. + May return <code>None</code>. + + <h2 id="module_version">module_version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> module_version()</pre></p> + + The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the <code>module.version</code> field seen in <code>module_ctx.modules</code>. + May return <code>None</code>. + + <h2 id="package">package</h2> + <p><pre class="rule-signature">unknown package(**kwargs)</pre></p> + + Declares metadata that applies to every rule in the package. It must be called at most once within a package (BUILD file). If called, it should be the first call in the BUILD file, right after the <code>load()</code> statements. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="package.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + See the <a href="/reference/be/functions#package"><code>package()</code></a> function in the Build Encyclopedia for applicable arguments. + </td> + </tr> + </tbody> + </table> + + <h2 id="package_default_visibility">package_default_visibility</h2> + <p><pre class="rule-signature">List package_default_visibility()</pre></p> + + Returns the default visibility of the package being evaluated. This is the value of the <code>default_visibility</code> parameter of <code>package()</code>, extended to include the package itself. + + <h2 id="package_group">package_group</h2> + <p><pre class="rule-signature"><code>None</code> package_group(*, name, packages=[], includes=[])</pre></p> + + This function defines a set of packages and assigns a label to the group. The label can be referenced in <code>visibility</code> attributes. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="package_group.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The unique name for this rule. + </td> + </tr> + <tr> + <td id="package_group.packages"> + <code>packages</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A complete enumeration of packages in this group. + </td> + </tr> + <tr> + <td id="package_group.includes"> + <code>includes</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Other package groups that are included in this one. + </td> + </tr> + </tbody> + </table> + + <h2 id="package_name">package_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> package_name()</pre></p> + + The name of the package being evaluated, without the repository name. For example, in the BUILD file <code>some/package/BUILD</code>, its value will be <code>some/package</code>. If the BUILD file calls a function defined in a .bzl file, <code>package_name()</code> will match the caller BUILD file package. The value will always be an empty string for the root package. + + <h2 id="package_relative_label">package_relative_label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> package_relative_label(input)</pre></p> + + Converts the input string into a <a href='../builtins/Label.html'>Label</a> object, in the context of the package currently being initialized (that is, the <code>BUILD</code> file for which the current macro is executing). If the input is already a <code>Label</code>, it is returned unchanged.<p>This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. <p>The result of this function is the same <code>Label</code> value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file. <p><i>Usage note:</i> The difference between this function and <a href='../builtins/Label.html#Label'>Label()</a></code> is that <code>Label()</code> uses the context of the package of the <code>.bzl</code> file that called it, not the package of the <code>BUILD</code> file. Use <code>Label()</code> when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use <code>package_relative_label()</code> when you need to normalize a label string supplied by the BUILD file to a <code>Label</code> object. (There is no way to convert a string to a <code>Label</code> in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="package_relative_label.input"> + <code>input</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; + required<br/> + The input label string or Label object. If a Label object is passed, it's returned as is. + </td> + </tr> + </tbody> + </table> + + <h2 id="repo_name">repo_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repo_name()</pre></p> + + The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. + + <h2 id="repository_name">repository_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_name()</pre></p> + + <b>Experimental</b>. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--+incompatible_enable_deprecated_label_apis</code> <br><strong>Deprecated.</strong> Prefer to use <a href="#repo_name"><code>repo_name</code></a> instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise.<p>The canonical name of the repository containing the package currently being evaluated, with a single at-sign (<code>@</code>) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza <code>local_repository(name='local', path=...)</code> it will be set to <code>@local</code>. In packages in the main repository, it will be set to <code>@</code>. + + <h2 id="select">select</h2> + <p><pre class="rule-signature">unknown select(x, no_match_error='')</pre></p> + + <code>select()</code> is the helper function that makes a rule attribute <a href="/reference/be/common-definitions#configurable-attributes">configurable</a>. See <a href="/reference/be/functions#select">build encyclopedia</a> for details. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="select.x"> + <code>x</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + required<br/> + A dict that maps configuration conditions to values. Each key is a <a href="../builtins/Label.html">Label</a> or a label string that identifies a config_setting or constraint_value instance. See the <a href="https://bazel.build/extending/legacy-macros#label-resolution">documentation on macros</a> for when to use a Label instead of a string. If <code>--incompatible_resolve_select_keys_eagerly</code> is enabled, the keys are resolved to <code>Label</code> objects relative to the package of the file that contains this call to <code>select</code>. + </td> + </tr> + <tr> + <td id="select.no_match_error"> + <code>no_match_error</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Optional custom error to report if no condition matches. + </td> + </tr> + </tbody> + </table> + + <h2 id="subpackages">subpackages</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> subpackages(*, include, exclude=[], allow_empty=False)</pre></p> + + Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel_skylib.subpackages module rather than calling this function directly. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="subpackages.include"> + <code>include</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The list of glob patterns to include in subpackages scan. + </td> + </tr> + <tr> + <td id="subpackages.exclude"> + <code>exclude</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + The list of glob patterns to exclude from subpackages scan. + </td> + </tr> + <tr> + <td id="subpackages.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/globals/bzl.mdx b/rules/lib/globals/bzl.mdx new file mode 100644 index 0000000..d8f6105 --- /dev/null +++ b/rules/lib/globals/bzl.mdx @@ -0,0 +1,1446 @@ +--- +title: 'bzl' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.bzl">.bzl files</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Global methods available in all .bzl files. + +<h2>Members</h2> +<ul> + <li> + <a href="#analysis_test_transition">analysis_test_transition</a> + </li> + <li> + <a href="#aspect">aspect</a> + </li> + <li> + <a href="#configuration_field">configuration_field</a> + </li> + <li> + <a href="#depset">depset</a> + </li> + <li> + <a href="#exec_group">exec_group</a> + </li> + <li> + <a href="#exec_transition">exec_transition</a> + </li> + <li> + <a href="#macro">macro</a> + </li> + <li> + <a href="#materializer_rule">materializer_rule</a> + </li> + <li> + <a href="#module_extension">module_extension</a> + </li> + <li> + <a href="#provider">provider</a> + </li> + <li> + <a href="#repository_rule">repository_rule</a> + </li> + <li> + <a href="#rule">rule</a> + </li> + <li> + <a href="#select">select</a> + </li> + <li> + <a href="#subrule">subrule</a> + </li> + <li> + <a href="#tag_class">tag_class</a> + </li> + <li> + <a href="#visibility">visibility</a> + </li> + </ul> + + <h2 id="analysis_test_transition">analysis_test_transition</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> analysis_test_transition(*, settings)</pre></p> + + <p> Creates a configuration transition to be applied on an analysis-test rule's dependencies. This transition may only be applied on attributes of rules with <code>analysis_test = True</code>. Such rules are restricted in capabilities (for example, the size of their dependency tree is limited), so transitions created using this function are limited in potential scope as compared to transitions created using <a href="../builtins/transition.html"><code>transition()</code></a>. <p>This function is primarily designed to facilitate the <a href="https://bazel.build/rules/testing">Analysis Test Framework</a> core library. See its documentation (or its implementation) for best practices. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="analysis_test_transition.settings"> + <code>settings</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + required<br/> + A dictionary containing information about configuration settings which should be set by this configuration transition. Keys are build setting labels and values are their new post-transition values. All other settings are unchanged. Use this to declare specific configuration settings that an analysis test requires to be set in order to pass. + </td> + </tr> + </tbody> + </table> + + <h2 id="aspect">aspect</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Aspect.html">Aspect</a> aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], propagation_predicate=None, fragments=[], host_fragments=[], toolchains=[], doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])</pre></p> + + Creates a new aspect. The result of this function must be stored in a global value. Please see the <a href="https://bazel.build/extending/aspects">introduction to Aspects</a> for more details. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="aspect.implementation"> + <code>implementation</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + required<br/> + A Starlark function that implements this aspect, with exactly two parameters: <a href="../builtins/Target.html">Target</a> (the target to which the aspect is applied) and <a href="../builtins/ctx.html">ctx</a> (the rule context which the target is created from). Attributes of the target are available via the <code>ctx.rule</code> field. This function is evaluated during the analysis phase for each application of an aspect to a target. + </td> + </tr> + <tr> + <td id="aspect.attr_aspects"> + <code>attr_aspects</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/function.html">function</a>; + default is <code>[]</code><br/> + Accepts a list of attribute names or [Experimental] a function that returns the list of attribute names. The aspect propagates along dependencies specified in the attributes of a target with these names. Common values here include <code>deps</code> and <code>exports</code>. The list can also contain a single string <code>"*"</code> to propagate along all dependencies of a target. + </td> + </tr> + <tr> + <td id="aspect.toolchains_aspects"> + <code>toolchains_aspects</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../core/function.html">function</a>; + default is <code>[]</code><br/> + Accepts a list of toolchain types or [Experimental] a function that returns the list of toolchain types. The aspect propagates to target toolchains which match these toolchain types. + </td> + </tr> + <tr> + <td id="aspect.attrs"> + <code>attrs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary declaring all the attributes of the aspect. It maps from an attribute name to an attribute object, like <code>attr.label</code> or <code>attr.string</code> (see <a href="../toplevel/attr.html"><code>attr</code></a> module). Aspect attributes are available to implementation function as fields of <code>ctx</code> parameter. <p>Implicit attributes starting with <code>_</code> must have default values, and have type <code>label</code> or <code>label_list</code>.</p> <p>Explicit attributes must have type <code>string</code>, and must use the <code>values</code> restriction. Explicit attributes restrict the aspect to only be used with rules that have attributes of the same name, type, and valid values according to the restriction.</p> +<p>Declared attributes will convert <code>None</code> to the default value.</p> + + </td> + </tr> + <tr> + <td id="aspect.required_providers"> + <code>required_providers</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its required providers. The value must be a list containing either individual providers or lists of providers but not both. For example, <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code> is a valid value while <code>[FooInfo, BarInfo, [BazInfo, QuxInfo]]</code> is not valid.<p>An unnested list of providers will automatically be converted to a list containing one list of providers. That is, <code>[FooInfo, BarInfo]</code> will automatically be converted to <code>[[FooInfo, BarInfo]]</code>.<p>To make some rule (e.g. <code>some_rule</code>) targets visible to an aspect, <code>some_rule</code> must advertise all providers from at least one of the required providers lists. For example, if the <code>required_providers</code> of an aspect are <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code>, this aspect can see <code>some_rule</code> targets if and only if <code>some_rule</code> provides <code>FooInfo</code>, <em>or</em> <code>BarInfo</code>, <em>or</em> both <code>BazInfo</code> <em>and</em> <code>QuxInfo</code>. + </td> + </tr> + <tr> + <td id="aspect.required_aspect_providers"> + <code>required_aspect_providers</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + This attribute allows this aspect to inspect other aspects. The value must be a list containing either individual providers or lists of providers but not both. For example, <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code> is a valid value while <code>[FooInfo, BarInfo, [BazInfo, QuxInfo]]</code> is not valid.<p>An unnested list of providers will automatically be converted to a list containing one list of providers. That is, <code>[FooInfo, BarInfo]</code> will automatically be converted to <code>[[FooInfo, BarInfo]]</code>. <p>To make another aspect (e.g. <code>other_aspect</code>) visible to this aspect, <code>other_aspect</code> must provide all providers from at least one of the lists. In the example of <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code>, this aspect can see <code>other_aspect</code> if and only if <code>other_aspect</code> provides <code>FooInfo</code>, <em>or</em> <code>BarInfo</code>, <em>or</em> both <code>BazInfo</code> <em>and</em> <code>QuxInfo</code>. + </td> + </tr> + <tr> + <td id="aspect.provides"> + <code>provides</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + A list of providers that the implementation function must return.<p>It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.<p>Each element of the list is an <code>*Info</code> object returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a>. When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The <a href='../globals/bzl.html#aspect.required_providers'><code>required_providers</code></a> field of an <a href='../globals/bzl.html#aspect'>aspect</a> does, however, require that providers are specified here. + </td> + </tr> + <tr> + <td id="aspect.requires"> + <code>requires</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; + default is <code>[]</code><br/> + List of aspects required to be propagated before this aspect. + </td> + </tr> + <tr> + <td id="aspect.propagation_predicate"> + <code>propagation_predicate</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; or <code>None</code>; + default is <code>None</code><br/> + Experimental: a function that returns a boolean value indicating whether the aspect should be propagated to a target. + </td> + </tr> + <tr> + <td id="aspect.fragments"> + <code>fragments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + List of names of configuration fragments that the aspect requires in target configuration. + </td> + </tr> + <tr> + <td id="aspect.host_fragments"> + <code>host_fragments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + List of names of configuration fragments that the aspect requires in host configuration. + </td> + </tr> + <tr> + <td id="aspect.toolchains"> + <code>toolchains</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + If set, the set of toolchains this aspect requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the aspect implementation via <code>ctx.toolchain</code>. + </td> + </tr> + <tr> + <td id="aspect.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the aspect that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="aspect.apply_to_generating_rules"> + <code>apply_to_generating_rules</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the aspect will, when applied to an output file, instead apply to the output file's generating rule. <p>For example, suppose an aspect propagates transitively through attribute `deps` and it is applied to target `alpha`. Suppose `alpha` has `deps = [':beta_output']`, where `beta_output` is a declared output of a target `beta`. Suppose `beta` has a target `charlie` as one of its `deps`. If `apply_to_generating_rules=True` for the aspect, then the aspect will propagate through `alpha`, `beta`, and `charlie`. If False, then the aspect will propagate only to `alpha`. </p><p>False by default.</p> + </td> + </tr> + <tr> + <td id="aspect.exec_compatible_with"> + <code>exec_compatible_with</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A list of constraints on the execution platform that apply to all instances of this aspect. + </td> + </tr> + <tr> + <td id="aspect.exec_groups"> + <code>exec_groups</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Dict of execution group name (string) to <a href='../globals/bzl.html#exec_group'><code>exec_group</code>s</a>. If set, allows aspects to run actions on multiple execution platforms within a single instance. See <a href='/reference/exec-groups'>execution groups documentation</a> for more info. + </td> + </tr> + <tr> + <td id="aspect.subrules"> + <code>subrules</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Subrule.html">Subrule</a>s; + default is <code>[]</code><br/> + Experimental: list of subrules used by this aspect. + </td> + </tr> + </tbody> + </table> + + <h2 id="configuration_field">configuration_field</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/LateBoundDefault.html">LateBoundDefault</a> configuration_field(fragment, name)</pre></p> + + References a late-bound default value for an attribute of type <a href="../toplevel/attr.html#label">label</a>. A value is 'late-bound' if it requires the configuration to be built before determining the value. Any attribute using this as a value must <a href="https://bazel.build/extending/rules#private-attributes">be private</a>. <p>Example usage: <p>Defining a rule attribute: <br><pre class=language-python>'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))</pre><p>Accessing in rule implementation: <br><pre class=language-python> def _rule_impl(ctx): + foo_info = ctx.attr._foo + ...</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="configuration_field.fragment"> + <code>fragment</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of a configuration fragment which contains the late-bound value. + </td> + </tr> + <tr> + <td id="configuration_field.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the value to obtain from the configuration fragment. + </td> + </tr> + </tbody> + </table> + + <h2 id="depset">depset</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> depset(direct=None, order="default", *, transitive=None)</pre></p> + + Creates a <a href="../builtins/depset.html">depset</a>. The <code>direct</code> parameter is a list of direct elements of the depset, and <code>transitive</code> parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the <code>order</code> parameter. See the <a href="https://bazel.build/extending/depsets">Depsets overview</a> for more information. +<p>All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression <a href="../globals/all#type"><code>type(x)</code></a>. +<p>Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see <a href='https://github.com/bazelbuild/bazel/issues/10313'>Issue 10313</a>. +<p>In addition, elements must currently be immutable, though this restriction will be relaxed in future. +<p> The order of the created depset should be <i>compatible</i> with the order of its <code>transitive</code> depsets. <code>"default"</code> order is compatible with any other order, all other orders are only compatible with themselves. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="depset.direct"> + <code>direct</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; + default is <code>None</code><br/> + A list of <i>direct</i> elements of a depset. + </td> + </tr> + <tr> + <td id="depset.order"> + <code>order</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>"default"</code><br/> + The traversal strategy for the new depset. See <a href="../builtins/depset.html">here</a> for the possible values. + </td> + </tr> + <tr> + <td id="depset.transitive"> + <code>transitive</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/depset.html">depset</a>s; or <code>None</code>; + default is <code>None</code><br/> + A list of depsets whose elements will become indirect elements of the depset. + </td> + </tr> + </tbody> + </table> + + <h2 id="exec_group">exec_group</h2> + <p><pre class="rule-signature">exec_group exec_group(*, toolchains=[], exec_compatible_with=[])</pre></p> + + Creates an <a href='/reference/exec-groups'>execution group</a> which can be used to create actions for a specific execution platform during rule implementation. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="exec_group.toolchains"> + <code>toolchains</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + The set of toolchains this execution group requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. + </td> + </tr> + <tr> + <td id="exec_group.exec_compatible_with"> + <code>exec_compatible_with</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A list of constraints on the execution platform. + </td> + </tr> + </tbody> + </table> + + <h2 id="exec_transition">exec_transition</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> exec_transition(*, implementation, inputs, outputs)</pre></p> + + A specialized version of <a href="../builtins/transition.html"><code>transition()</code></a> used to define the exec transition. See its documentation (or its implementation) for best practices. Only usable from the Bazel builtins. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="exec_transition.implementation"> + <code>implementation</code> + </td> + <td> + callable; + required<br/> + + </td> + </tr> + <tr> + <td id="exec_transition.inputs"> + <code>inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + + </td> + </tr> + <tr> + <td id="exec_transition.outputs"> + <code>outputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + + </td> + </tr> + </tbody> + </table> + + <h2 id="macro">macro</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/macro.html">macro</a> macro(*, implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)</pre></p> + + Defines a symbolic macro, which may be called in <code>BUILD</code> files or macros (legacy or +symbolic) to define targets – possibly multiple ones. + +<p>The value returned by <code>macro(...)</code> must be assigned to a global variable in a .bzl +file; the name of the global variable will be the macro symbol's name. + +<p>See <a href="/extending/macros">Macros</a> for a comprehensive guide on how to use symbolic +macros. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="macro.implementation"> + <code>implementation</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + required<br/> + The Starlark function implementing this macro. The values of the macro's attributes are passed to +the implementation function as keyword arguments. The implementation function must have at least two +named parameters, <code>name</code> and <code>visibility</code>, and if the macro inherits +attributes (see <code>inherit_attrs</code> below), it must have a <code>**kwargs</code> residual +keyword parameter. + +<p>By convention, the implementation function should have a named parameter for any attribute that +the macro needs to examine, modify, or pass to non-"main" targets, while the "bulk" inherited +attributes which will be passed to the "main" target unchanged are passed as <code>**kwargs</code>. + +<p>The implementation function must not return a value. Instead, the implementation function +<em>declares targets</em> by calling rule or macro symbols. + +<p>The name of any target or inner symbolic macro declared by a symbolic macro (including by any +Starlark function that the macro's implementation function transitively calls) must either equal +<code>name</code> (this is referred to as the "main" target) or start with <code>name</code>, +followed by a separator chracter (<code>"_"</code>, <code>"-"</code>, or <code>"."</code>) and a +string suffix. (Targets violating this naming scheme are allowed to be declared, but cannot be +built, configured, or depended upon.) + +<p>By default, targets declared by a symbolic macro (including by any Starlark function that the +macro's implementation function transitively calls) are visible only in the package containing the +.bzl file defining the macro. To declare targets visible externally, <em>including to the caller of +the symbolic macro</em>, the implementation function must set <code>visibility</code> appropriately +– typically, by passing <code>visibility = visibility</code> to the rule or macro symbol being +called. + +<p>The following APIs are unavailable within a macro implementation function and any Starlark +function it transitively calls: +<ul> + <li><a href="/reference/be/functions#package"><code>package()</code>, <code>licenses()</code> + <li><code>environment_group()</code> + <li><a href="../toplevel/native#glob"><code>native.glob()</code></a> – instead, you may pass + a glob into the macro via a label list attribute + <li><a href="../toplevel/native#subpackages"><code>native.subpackages()</code></a> + <li>(allowed in rule finalizers only, see <code>finalizer</code> below) + <a href="../toplevel/native#existing_rules"><code>native.existing_rules()</code></a>, + <a href="../toplevel/native#existing_rule"><code>native.existing_rule()</code></a> + <li>(for <code>WORKSPACE</code> threads) + <a href="../globals/workspace#workspace"><code>workspace()</code></a>, + <a href="../globals/workspace#register_toolchains"><code>register_toolchains()</code></a>, + <a href="../globals/workspace#register_execution_platforms><code>register_execution_platforms()</code></a>, + <a href="../globals/workspace#bind"><code>bind()</code></a>, repository rule instantiation +</ul> + + </td> + </tr> + <tr> + <td id="macro.attrs"> + <code>attrs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary of the attributes this macro supports, analogous to +<a href="#rule.attrs">rule.attrs</a>. Keys are attribute names, and values are either attribute +objects like <code>attr.label_list(...)</code> (see the <a href="../toplevel/attr.html">attr</a> +module), or <code>None</code>. A <code>None</code> entry means that the macro does not have an +attribute by that name, even if it would have otherwise inherited one via <code>inherit_attrs</code> +(see below). + +<p>The special <code>name</code> attribute is predeclared and must not be included in the +dictionary. The <code>visibility</code> attribute name is reserved and must not be included in the +dictionary. + +<p>Attributes whose names start with <code>_</code> are private -- they cannot be passed at the call +site of the rule. Such attributes can be assigned a default value (as in +<code>attr.label(default="//pkg:foo")</code>) to create an implicit dependency on a label. + +<p>To limit memory usage, there is a cap on the number of attributes that may be declared. + + </td> + </tr> + <tr> + <td id="macro.inherit_attrs"> + <code>inherit_attrs</code> + </td> + <td> + <a class="anchor" href="../builtins/rule.html">rule</a>; or <a class="anchor" href="../builtins/macro.html">macro</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A rule symbol, macro symbol, or the name of a built-in common attribute list (see below) from which +the macro should inherit attributes. + +<p>If <code>inherit_attrs</code> is set to the string <code>"common"</code>, the macro will inherit +<a href="/reference/be/common-definitions#common-attributes">common rule attribute definitions</a> +used by all Starlark rules. + +<p>Note that if the return value of <code>rule()</code> or <code>macro()</code> was not assigned to +a global variable in a .bzl file, then such a value has not been registered as a rule or macro +symbol, and therefore cannot be used for <code>inherit_attrs</code>. + +<p>The inheritance mechanism works as follows:</p> +<ol> + <li>The special <code>name</code> and <code>visibility</code> attributes are never inherited; + <li>Hidden attributes (ones whose name starts with <code>"_"</code>) are never inherited; + <li>Attributes whose names are already defined in the <code>attrs</code> dictionary are never + inherited (the entry in <code>attrs</code> takes precedence; note that an entry may be set to + <code>None</code> to ensure that no attribute by that name gets defined on the macro); + <li>All other attributes are inherited from the rule or macro and effectively merged into the + <code>attrs</code> dict. +</ol> + +<p>When a non-mandatory attribute is inherited, the default value of the attribute is overridden +to be <code>None</code>, regardless of what it was specified in the original rule or macro. This +ensures that when the macro forwards the attribute's value to an instance of the wrapped rule or +macro – such as by passing in the unmodified <code>**kwargs</code> – a value that was +absent from the outer macro's call will also be absent in the inner rule or macro's call (since +passing <code>None</code> to an attribute is treated the same as omitting the attribute). +This is important because omitting an attribute has subtly different semantics from passing +its apparent default value. In particular, omitted attributes are not shown in some <code>bazel +query</code> output formats, and computed defaults only execute when the value is omitted. If the +macro needs to examine or modify an inherited attribute – for example, to add a value to an +inherited <code>tags</code> attribute – you must make sure to handle the <code>None</code> +case in the macro's implementation function. + +<p>For example, the following macro inherits all attributes from <code>native.cc_library</code>, +except for <code>cxxopts</code> (which is removed from the attribute list) and <code>copts</code> +(which is given a new definition). It also takes care to checks for the default <code>None</code> +value of the inherited <code>tags</code> attribute before appending an additional tag. + +<pre class="language-python"> +def _my_cc_library_impl(name, visibility, tags, **kwargs): + # Append a tag; tags attr was inherited from native.cc_library, and + # therefore is None unless explicitly set by the caller of my_cc_library() + my_tags = (tags or []) + ["my_custom_tag"] + native.cc_library( + name = name, + visibility = visibility, + tags = my_tags, + **kwargs + ) + +my_cc_library = macro( + implementation = _my_cc_library_impl, + inherit_attrs = native.cc_library, + attrs = { + "cxxopts": None, + "copts": attr.string_list(default = ["-D_FOO"]), + }, +) +</pre> + +<p>If <code>inherit_attrs</code> is set, the macro's implementation function <em>must</em> have a +<code>**kwargs</code> residual keyword parameter. + +<p>By convention, a macro should pass inherited, non-overridden attributes unchanged to the "main" +rule or macro symbol which the macro is wrapping. Typically, most inherited attributes will not have +a parameter in the implementation function's parameter list, and will simply be passed via +<code>**kwargs</code>. It can be convenient for the implementation function to have explicit +parameters for some inherited attributes (most commonly, <code>tags</code> and +<code>testonly</code>) if the macro needs to pass those attributes to both "main" and non-"main" +targets – but if the macro also needs to examine or manipulate those attributes, you must take +care to handle the <code>None</code> default value of non-mandatory inherited attributes. + + </td> + </tr> + <tr> + <td id="macro.finalizer"> + <code>finalizer</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether this macro is a rule finalizer, which is a macro that, regardless of its position in a +<code>BUILD</code> file, is evaluated at the end of package loading, after all non-finalizer targets +have been defined. + +<p>Unlike ordinary symbolic macros, rule finalizers may call +<a href="../toplevel/native#existing_rule"><code>native.existing_rule()</code></a> and +<a href="../toplevel/native#existing_rules"><code>native.existing_rules()</code></a> to query the +set of <em>non-finalizer</em> rule targets defined in the current package. Note that +<code>native.existing_rule()</code> and <code>native.existing_rules()</code> cannot access the +targets defined by any rule finalizer, including this one. + + </td> + </tr> + <tr> + <td id="macro.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the macro that can be extracted by documentation generating tools. + </td> + </tr> + </tbody> + </table> + + <h2 id="materializer_rule">materializer_rule</h2> + <p><pre class="rule-signature">callable materializer_rule(*, implementation, attrs={}, doc=None)</pre></p> + + Creates a new materializer rule, which can be called from a BUILD file or a macro to create materializer targets.<p>Materializer targets are used to dynamically select dependencies at analysis time. Targets which depend on a materializer target will see the materialized dependencies, rather than the materializer target itself. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="materializer_rule.implementation"> + <code>implementation</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + required<br/> + The Starlark function implementing this materializer rule. It must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. This function is called during the analysis phase for each instance of the rule. Materializer rules return exactly one and only one MaterializedDepsInfo provider which specifies the dependencies to materialize in place of any instance of this rule in the attributes of another target. + </td> + </tr> + <tr> + <td id="materializer_rule.attrs"> + <code>attrs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see +<a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label. The attribute <code>name</code> is implicitly added and must not be specified. Attributes <code>visibility</code>, <code>deprecation</code>, <code>tags</code>, <code>testonly</code>, and <code>features</code> are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. +<p>Declared attributes will convert <code>None</code> to the default value.</p> + + </td> + </tr> + <tr> + <td id="materializer_rule.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the rule that can be extracted by documentation generating tools. + </td> + </tr> + </tbody> + </table> + + <h2 id="module_extension">module_extension</h2> + <p><pre class="rule-signature">unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)</pre></p> + + Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with <code><a href="../globals/module.html#use_extension">use_extension</a></code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="module_extension.implementation"> + <code>implementation</code> + </td> + <td> + callable; + required<br/> + The function that implements this module extension. Must take a single parameter, <code><a href="../builtins/module_ctx.html">module_ctx</a></code>. The function is called once at the beginning of a build to determine the set of available repos. + </td> + </tr> + <tr> + <td id="module_extension.tag_classes"> + <code>tag_classes</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary to declare all the tag classes used by the extension. It maps from the name of the tag class to a <code><a href="../builtins/tag_class.html">tag_class</a></code> object. + </td> + </tr> + <tr> + <td id="module_extension.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the module extension that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="module_extension.environ"> + <code>environ</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated. + </td> + </tr> + <tr> + <td id="module_extension.os_dependent"> + <code>os_dependent</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Indicates whether this extension is OS-dependent or not + </td> + </tr> + <tr> + <td id="module_extension.arch_dependent"> + <code>arch_dependent</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Indicates whether this extension is architecture-dependent or not + </td> + </tr> + </tbody> + </table> + + <h2 id="provider">provider</h2> + <p><pre class="rule-signature">unknown provider(doc=None, *, fields=None, init=None)</pre></p> + + Defines a provider symbol. The resulting value of this function must be stored in a global value to be usable in a rule or aspect implementation. Providers can be instantiated by calling the resulting value as a function, or used directly as an index key for retrieving an instance of that provider from a target. Example:<br><pre class="language-python">MyInfo = provider() +... +def _my_library_impl(ctx): + ... + my_info = MyInfo(x = 2, y = 3) + # my_info.x == 2 + # my_info.y == 3 + ...</pre><p>See <a href='https://bazel.build/extending/rules#providers'>Rules (Providers)</a> for a comprehensive guide on how to use providers.<p>Returns a <a href='../builtins/Provider.html'><code>Provider</code></a> callable value if <code>init</code> is not specified.<p>If <code>init</code> is specified, returns a tuple of 2 elements: a <a href='../builtins/Provider.html'><code>Provider</code></a> callable value and a <em>raw constructor</em> callable value. See <a href='https://bazel.build/extending/rules#custom_initialization_of_providers'> Rules (Custom initialization of custom providers)</a> and the discussion of the <code>init</code> parameter below for details. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="provider.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the provider that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="provider.fields"> + <code>fields</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + If specified, restricts the set of allowed fields. <br>Possible values are:<ul> <li> list of fields:<br> <pre class="language-python">provider(fields = ['a', 'b'])</pre><p> <li> dictionary field name -> documentation:<br> <pre class="language-python">provider( + fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })</pre></ul>All fields are optional. + </td> + </tr> + <tr> + <td id="provider.init"> + <code>init</code> + </td> + <td> + callable; or <code>None</code>; + default is <code>None</code><br/> + An optional callback for preprocessing and validating the provider's field values during instantiation. If <code>init</code> is specified, <code>provider()</code> returns a tuple of 2 elements: the normal provider symbol and a <em>raw constructor</em>.<p>A precise description follows; see <a href='https://bazel.build/extending/rules#custom_initialization_of_providers'>Rules (Custom initialization of providers)</a> for an intuitive discussion and use cases.<p>Let <code>P</code> be the provider symbol created by calling <code>provider()</code>. Conceptually, an instance of <code>P</code> is generated by calling a default constructor function <code>c(*args, **kwargs)</code>, which does the following:<ul><li>If <code>args</code> is non-empty, an error occurs.</li><li>If the <code>fields</code> parameter was specified when <code>provider()</code> was called, and if <code>kwargs</code> contains any key that was not listed in <code>fields</code>, an error occurs.</li><li>Otherwise, <code>c</code> returns a new instance that has, for each <code>k: v</code> entry in <code>kwargs</code>, a field named <code>k</code> with value <code>v</code>.</ul>In the case where an <code>init</code> callback is <em>not</em> given, a call to the symbol <code>P</code> itself acts as a call to the default constructor function <code>c</code>; in other words, <code>P(*args, **kwargs)</code> returns <code>c(*args, **kwargs)</code>. For example,<pre class="language-python">MyInfo = provider() +m = MyInfo(foo = 1)</pre>will straightforwardly make it so that <code>m</code> is a <code>MyInfo</code> instance with <code>m.foo == 1</code>.<p>But in the case where <code>init</code> is specified, the call <code>P(*args, **kwargs)</code> will perform the following steps instead:<ol><li>The callback is invoked as <code>init(*args, **kwargs)</code>, that is, with the exact same positional and keyword arguments as were passed to <code>P</code>.</li><li>The return value of <code>init</code> is expected to be a dictionary, <code>d</code>, whose keys are field name strings. If it is not, an error occurs.</li><li>A new instance of <code>P</code> is generated as if by calling the default constructor with <code>d</code>'s entries as keyword arguments, as in <code>c(**d)</code>.</li></ol><p>NB: the above steps imply that an error occurs if <code>*args</code> or <code>**kwargs</code> does not match <code>init</code>'s signature, or the evaluation of <code>init</code>'s body fails (perhaps intentionally via a call to <a href="../globals/all.html#fail"><code>fail()</code></a>), or if the return value of <code>init</code> is not a dictionary with the expected schema.<p>In this way, the <code>init</code> callback generalizes normal provider construction by allowing positional arguments and arbitrary logic for preprocessing and validation. It does <em>not</em> enable circumventing the list of allowed <code>fields</code>.<p>When <code>init</code> is specified, the return value of <code>provider()</code> becomes a tuple <code>(P, r)</code>, where <code>r</code> is the <em>raw constructor</em>. In fact, the behavior of <code>r</code> is exactly that of the default constructor function <code>c</code> discussed above. Typically, <code>r</code> is bound to a variable whose name is prefixed with an underscore, so that only the current .bzl file has direct access to it:<pre class="language-python">MyInfo, _new_myinfo = provider(init = ...)</pre> + </td> + </tr> + </tbody> + </table> + + <h2 id="repository_rule">repository_rule</h2> + <p><pre class="rule-signature">callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)</pre></p> + + Creates a new repository rule. Store it in a global value, so that it can be loaded and called from a <a href="#module_extension"><code>module_extension()</code></a> implementation function, or used by <a href="../globals/module.html#use_repo_rule"><code>use_repo_rule()</code></a>. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="repository_rule.implementation"> + <code>implementation</code> + </td> + <td> + callable; + required<br/> + the function that implements this rule. Must have a single parameter, <code><a href="../builtins/repository_ctx.html">repository_ctx</a></code>. The function is called during the loading phase for each instance of the rule. + </td> + </tr> + <tr> + <td id="repository_rule.attrs"> + <code>attrs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + A dictionary to declare all the attributes of the repository rule. It maps from an attribute name to an attribute object (see +<a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label to a file (a repository rule cannot depend on a generated artifact). The attribute <code>name</code> is implicitly added and must not be specified. +<p>Declared attributes will convert <code>None</code> to the default value.</p> + + </td> + </tr> + <tr> + <td id="repository_rule.local"> + <code>local</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch. + </td> + </tr> + <tr> + <td id="repository_rule.environ"> + <code>environ</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + <b>Deprecated</b>. This parameter has been deprecated. Migrate to <code>repository_ctx.getenv</code> instead.<br/>Provides a list of environment variable that this repository rule depends on. If an environment variable in that list change, the repository will be refetched. + </td> + </tr> + <tr> + <td id="repository_rule.configure"> + <code>configure</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Indicate that the repository inspects the system for configuration purpose + </td> + </tr> + <tr> + <td id="repository_rule.remotable"> + <code>remotable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + <b>Experimental</b>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_repo_remote_exec</code> <br>Compatible with remote execution + </td> + </tr> + <tr> + <td id="repository_rule.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the repository rule that can be extracted by documentation generating tools. + </td> + </tr> + </tbody> + </table> + + <h2 id="rule">rule</h2> + <p><pre class="rule-signature">callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])</pre></p> + + Creates a new rule, which can be called from a BUILD file or a macro to create targets.<p>Rules must be assigned to global variables in a .bzl file; the name of the global variable is the rule's name.<p>Test rules are required to have a name ending in <code>_test</code>, while all other rules must not have this suffix. (This restriction applies only to rules, not to their targets.) + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="rule.implementation"> + <code>implementation</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + required<br/> + the Starlark function implementing this rule, must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. The function is called during the analysis phase for each instance of the rule. It can access the attributes provided by the user. It must create actions to generate all the declared outputs. + </td> + </tr> + <tr> + <td id="rule.test"> + <code>test</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>unbound</code><br/> + Whether this rule is a test rule, that is, whether it may be the subject of a <code>bazel test</code> command. All test rules are automatically considered <a href='#rule.executable'>executable</a>; it is unnecessary (and discouraged) to explicitly set <code>executable = True</code> for a test rule. The value defaults to <code>False</code>. See the <a href='https://bazel.build/extending/rules#executable_rules_and_test_rules'> Rules page</a> for more information. + </td> + </tr> + <tr> + <td id="rule.attrs"> + <code>attrs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see +<a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label. The attribute <code>name</code> is implicitly added and must not be specified. Attributes <code>visibility</code>, <code>deprecation</code>, <code>tags</code>, <code>testonly</code>, and <code>features</code> are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. +<p>Declared attributes will convert <code>None</code> to the default value.</p> + + </td> + </tr> + <tr> + <td id="rule.outputs"> + <code>outputs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; or <a class="anchor" href="../core/function.html">function</a>; + default is <code>None</code><br/> + <b>Deprecated</b>. This parameter is deprecated and will be removed soon. Please do not depend on it. It is <i>disabled</i> with <code>--incompatible_no_rule_outputs_param</code>. Use this flag to verify your code is compatible with its imminent removal. <br>This parameter has been deprecated. Migrate rules to use <code>OutputGroupInfo</code> or <code>attr.output</code> instead. <p>A schema for defining predeclared outputs. Unlike <a href='../toplevel/attr.html#output'><code>output</code></a> and <a href='../toplevel/attr.html#output_list'><code>output_list</code></a> attributes, the user does not specify the labels for these files. See the <a href='https://bazel.build/extending/rules#files'>Rules page</a> for more on predeclared outputs.<p>The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass <code>outputs = _my_func</code> with the definition <code>def _my_func(srcs, deps): ...</code>, the function has access to the attributes <code>srcs</code> and <code>deps</code>. Whether the dictionary is specified directly or via a function, it is interpreted as follows.<p>Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's <a href='../builtins/File.html'><code>File</code></a> in <a href='../builtins/ctx.html#outputs'><code>ctx.outputs</code></a>. The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form <code>"%{ATTR}"</code> with a string formed from the value of the attribute <code>ATTR</code>:<ul><li>String-typed attributes are substituted verbatim.<li>Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label <code>"//pkg:a/b.c"</code> becomes <code>"a/b"</code>.<li>Output-typed attributes become the part of the label after the package, including the file extension (for the above example, <code>"a/b.c"</code>).<li>All list-typed attributes (for example, <code>attr.label_list</code>) used in placeholders are required to have <i>exactly one element</i>. Their conversion is the same as their non-list version (<code>attr.label</code>).<li>Other attribute types may not appear in placeholders.<li>The special non-attribute placeholders <code>%{dirname}</code> and <code>%{basename}</code> expand to those parts of the rule's label, excluding its package. For example, in <code>"//pkg:a/b.c"</code>, the dirname is <code>a</code> and the basename is <code>b.c</code>.</ul><p>In practice, the most common substitution placeholder is <code>"%{name}"</code>. For example, for a target named "foo", the outputs dict <code>{"bin": "%{name}.exe"}</code> predeclares an output named <code>foo.exe</code> that is accessible in the implementation function as <code>ctx.outputs.bin</code>. + </td> + </tr> + <tr> + <td id="rule.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>unbound</code><br/> + Whether this rule is considered executable, that is, whether it may be the subject of a <code>bazel run</code> command. It defaults to <code>False</code>. See the <a href='https://bazel.build/extending/rules#executable_rules_and_test_rules'> Rules page</a> for more information. + </td> + </tr> + <tr> + <td id="rule.output_to_genfiles"> + <code>output_to_genfiles</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the files will be generated in the genfiles directory instead of the bin directory. Unless you need it for compatibility with existing rules (e.g. when generating header files for C++), do not set this flag. + </td> + </tr> + <tr> + <td id="rule.fragments"> + <code>fragments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + List of names of configuration fragments that the rule requires in target configuration. + </td> + </tr> + <tr> + <td id="rule.host_fragments"> + <code>host_fragments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + List of names of configuration fragments that the rule requires in host configuration. + </td> + </tr> + <tr> + <td id="rule._skylark_testable"> + <code>_skylark_testable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + <i>(Experimental)</i><br/><br/>If true, this rule will expose its actions for inspection by rules that depend on it via an <code>Actions</code> provider. The provider is also available to the rule itself by calling <a href="../builtins/ctx.html#created_actions">ctx.created_actions()</a>.<br/><br/>This should only be used for testing the analysis-time behavior of Starlark rules. This flag may be removed in the future. + </td> + </tr> + <tr> + <td id="rule.toolchains"> + <code>toolchains</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + If set, the set of toolchains this rule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the rule implementation via <code>ctx.toolchain</code>. + </td> + </tr> + <tr> + <td id="rule.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the rule that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="rule.provides"> + <code>provides</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + A list of providers that the implementation function must return.<p>It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.<p>Each element of the list is an <code>*Info</code> object returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a>. When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The <a href='../globals/bzl.html#aspect.required_providers'><code>required_providers</code></a> field of an <a href='../globals/bzl.html#aspect'>aspect</a> does, however, require that providers are specified here. + </td> + </tr> + <tr> + <td id="rule.dependency_resolution_rule"> + <code>dependency_resolution_rule</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If set, the rule can be a dependency through attributes also marked as available in materializers. Every attribute of rules with this flag set must be marked as available in materializers also. This is so that rules so marked cannot depend on rules that are not so marked. + </td> + </tr> + <tr> + <td id="rule.exec_compatible_with"> + <code>exec_compatible_with</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A list of constraints on the execution platform that apply to all targets of this rule type. + </td> + </tr> + <tr> + <td id="rule.analysis_test"> + <code>analysis_test</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, then this rule is treated as an analysis test. <p>Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See <a href="https://bazel.build/rules/testing#testing-rules">Testing</a> for guidance. <p>If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using <a href="#analysis_test_transition">analysis_test_transition</a> on its attributes, but opts into some restrictions: <ul><li>Targets of this rule are limited in the number of transitive dependencies they may have. <li>The rule is considered a test rule (as if <code>test=True</code> were set). This supersedes the value of <code>test</code></li> <li>The rule implementation function may not register actions. Instead, it must register a pass/fail result via providing <a href='../providers/AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>.</li></ul> + </td> + </tr> + <tr> + <td id="rule.build_setting"> + <code>build_setting</code> + </td> + <td> + <a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a>; or <code>None</code>; + default is <code>None</code><br/> + If set, describes what kind of <a href='/rules/config#user-defined-build-settings'><code>build setting</code></a> this rule is. See the <a href='../toplevel/config.html'><code>config</code></a> module. If this is set, a mandatory attribute named "build_setting_default" is automatically added to this rule, with a type corresponding to the value passed in here. + </td> + </tr> + <tr> + <td id="rule.cfg"> + <code>cfg</code> + </td> + <td> + default is <code>None</code><br/> + If set, points to the configuration transition the rule will apply to its own configuration before analysis. + </td> + </tr> + <tr> + <td id="rule.exec_groups"> + <code>exec_groups</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; + default is <code>None</code><br/> + Dict of execution group name (string) to <a href='../globals/bzl.html#exec_group'><code>exec_group</code>s</a>. If set, allows rules to run actions on multiple execution platforms within a single target. See <a href='/reference/exec-groups'>execution groups documentation</a> for more info. + </td> + </tr> + <tr> + <td id="rule.initializer"> + <code>initializer</code> + </td> + <td> + default is <code>None</code><br/> + Experimental: the Stalark function initializing the attributes of the rule. <p>The function is called at load time for each instance of the rule. It's called with <code>name</code> and the values of public attributes defined by the rule (not with generic attributes, for example <code>tags</code>). <p>It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning <code>None</code> as value results in using the default value specified in the attribute definition. <p>Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning <code>None</code>). <p>Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases. <p>It's a good practice to use <code>**kwargs</code> for attributes that are not handled.<p>In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about. + </td> + </tr> + <tr> + <td id="rule.parent"> + <code>parent</code> + </td> + <td> + default is <code>None</code><br/> + Experimental: the Stalark rule that is extended. When set the public attributes are merged as well as advertised providers. The rule matches <code>executable</code> and <code>test</code> from the parent. Values of <code>fragments</code>, <code>toolchains</code>, <code>exec_compatible_with</code>, and <code>exec_groups</code> are merged. Legacy or deprecated parameters may not be set. Incoming configuration transition <code>cfg</code> of parent is applied after thisrule's incoming configuration. + </td> + </tr> + <tr> + <td id="rule.extendable"> + <code>extendable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Experimental: A label of an allowlist defining which rules can extending this rule. It can be set also to True/False to always allow/disallow extending. Bazel defaults to always allowing extensions. + </td> + </tr> + <tr> + <td id="rule.subrules"> + <code>subrules</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Subrule.html">Subrule</a>s; + default is <code>[]</code><br/> + Experimental: List of subrules used by this rule. + </td> + </tr> + </tbody> + </table> + + <h2 id="select">select</h2> + <p><pre class="rule-signature">unknown select(x, no_match_error='')</pre></p> + + <code>select()</code> is the helper function that makes a rule attribute <a href="/reference/be/common-definitions#configurable-attributes">configurable</a>. See <a href="/reference/be/functions#select">build encyclopedia</a> for details. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="select.x"> + <code>x</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + required<br/> + A dict that maps configuration conditions to values. Each key is a <a href="../builtins/Label.html">Label</a> or a label string that identifies a config_setting or constraint_value instance. See the <a href="https://bazel.build/extending/legacy-macros#label-resolution">documentation on macros</a> for when to use a Label instead of a string. If <code>--incompatible_resolve_select_keys_eagerly</code> is enabled, the keys are resolved to <code>Label</code> objects relative to the package of the file that contains this call to <code>select</code>. + </td> + </tr> + <tr> + <td id="select.no_match_error"> + <code>no_match_error</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Optional custom error to report if no condition matches. + </td> + </tr> + </tbody> + </table> + + <h2 id="subrule">subrule</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Subrule.html">Subrule</a> subrule(*, implementation, attrs={}, toolchains=[], fragments=[], subrules=[])</pre></p> + + Constructs a new instance of a subrule. The result of this function must be stored in a global variable before it can be used. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="subrule.implementation"> + <code>implementation</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + required<br/> + The Starlark function implementing this subrule + </td> + </tr> + <tr> + <td id="subrule.attrs"> + <code>attrs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary to declare all the (private) attributes of the subrule. <p/>Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be: <ul><li><code>FilesToRunProvider</code> for label attributes with <code>executable=True</code></li><li><code>File</code> for label attributes with <code>allow_single_file=True</code></li><li><code>Target</code> for all other label attributes</li><li><code>[Target]</code> for all label-list attributes</li></ul> + </td> + </tr> + <tr> + <td id="subrule.toolchains"> + <code>toolchains</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + If set, the set of toolchains this subrule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the subrule implementation via <code>ctx.toolchains</code>. Note that AEGs need to be enabled on the consuming rule(s) if this parameter is set. In case you haven't migrated to AEGs yet, see https://bazel.build/extending/auto-exec-groups#migration-aegs. + </td> + </tr> + <tr> + <td id="subrule.fragments"> + <code>fragments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + List of names of configuration fragments that the subrule requires in target configuration. + </td> + </tr> + <tr> + <td id="subrule.subrules"> + <code>subrules</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Subrule.html">Subrule</a>s; + default is <code>[]</code><br/> + List of other subrules needed by this subrule. + </td> + </tr> + </tbody> + </table> + + <h2 id="tag_class">tag_class</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/tag_class.html">tag_class</a> tag_class(attrs={}, *, doc=None)</pre></p> + + Creates a new tag_class object, which defines an attribute schema for a class of tags, which are data objects usable by a module extension. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="tag_class.attrs"> + <code>attrs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dictionary to declare all the attributes of this tag class. It maps from an attribute name to an attribute object (see <a href="../toplevel/attr.html"> +attr</a> module). +<p>Note that unlike <a href="../globals/bzl.html#rule"><code>rule()</code></a>, <a href="../globals/bzl.html#aspect"><code>aspect()</code></a> and <a href="../globals/bzl.html#repository_rule"><code>repository_rule()</code></a>, +declared attributes will not convert <code>None</code> to the default value. For the default to be used, the attribute must be omitted entirely by the caller.</p> + + </td> + </tr> + <tr> + <td id="tag_class.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the tag class that can be extracted by documentation generating tools. + </td> + </tr> + </tbody> + </table> + + <h2 id="visibility">visibility</h2> + <p><pre class="rule-signature"><code>None</code> visibility(value)</pre></p> + + <p>Sets the load visibility of the .bzl module currently being initialized.<p>The load visibility of a module governs whether or not other BUILD and .bzl files may load it. (This is distinct from the target visibility of the underlying .bzl source file, which governs whether the file may appear as a dependency of other targets.) Load visibility works at the level of packages: To load a module the file doing the loading must live in a package that has been granted visibility to the module. A module can always be loaded within its own package, regardless of its visibility.<p><code>visibility()</code> may only be called once per .bzl file, and only at the top level, not inside a function. The preferred style is to put this call immediately below the <code>load()</code> statements and any brief logic needed to determine the argument.<p>If the flag <code>--check_bzl_visibility</code> is set to false, load visibility violations will emit warnings but not fail the build. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="visibility.value"> + <code>value</code> + </td> + <td> + required<br/> + A list of package specification strings, or a single package specification string.<p>Package specifications follow the same format as for <code><a href='/reference/be/functions#package_group'>package_group</a></code>, except that negative package specifications are not permitted. That is, a specification may have the forms:<ul><li><code>"//foo"</code>: the package <code>//foo</code><li><code>"//foo/..."</code>: the package <code>//foo</code> and all of its subpackages.<li><code>"public"</code> or <code>"private"</code>: all packages or no packages, respectively</ul><p>The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository.<p>If <code>value</code> is a list of strings, the set of packages granted visibility to this module is the union of the packages represented by each specification. (An empty list has the same effect as <code>private</code>.) If <code>value</code> is a single string, it is treated as if it were the singleton list <code>[value]</code>.<p>Note that the flags <code>--incompatible_package_group_has_public_syntax</code> and <code>--incompatible_fix_package_group_reporoot_syntax</code> have no effect on this argument. The <code>"public"</code> and <code>"private"</code> values are always available, and <code>"//..."</code> is always interpreted as "all packages in the current repository". + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/globals/module.mdx b/rules/lib/globals/module.mdx new file mode 100644 index 0000000..43c378b --- /dev/null +++ b/rules/lib/globals/module.mdx @@ -0,0 +1,947 @@ +--- +title: 'module' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.module">MODULE.bazel files</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Methods available in MODULE.bazel files. + +<h2>Members</h2> +<ul> + <li> + <a href="#archive_override">archive_override</a> + </li> + <li> + <a href="#bazel_dep">bazel_dep</a> + </li> + <li> + <a href="#flag_alias">flag_alias</a> + </li> + <li> + <a href="#git_override">git_override</a> + </li> + <li> + <a href="#include">include</a> + </li> + <li> + <a href="#inject_repo">inject_repo</a> + </li> + <li> + <a href="#local_path_override">local_path_override</a> + </li> + <li> + <a href="#module">module</a> + </li> + <li> + <a href="#multiple_version_override">multiple_version_override</a> + </li> + <li> + <a href="#override_repo">override_repo</a> + </li> + <li> + <a href="#register_execution_platforms">register_execution_platforms</a> + </li> + <li> + <a href="#register_toolchains">register_toolchains</a> + </li> + <li> + <a href="#single_version_override">single_version_override</a> + </li> + <li> + <a href="#use_extension">use_extension</a> + </li> + <li> + <a href="#use_repo">use_repo</a> + </li> + <li> + <a href="#use_repo_rule">use_repo_rule</a> + </li> + </ul> + + <h2 id="archive_override">archive_override</h2> + <p><pre class="rule-signature"><code>None</code> archive_override(*, module_name, **kwargs)</pre></p> + + Specifies that this dependency should come from an archive file (zip, gzip, etc) at a +certain location, instead of from a registry. Effectively, this dependency will be +backed by an <a href="../repo/http#http_archive"><code>http_archive</code></a> rule. + +<p>This directive only takes effect in the root module; in other words, if a module is +used as a dependency by others, its own overrides are ignored. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="archive_override.module_name"> + <code>module_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the Bazel module dependency to apply this override to. + </td> + </tr> + <tr> + <td id="archive_override.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + All other arguments are forwarded to the underlying <code>http_archive</code> repo +rule. Note that the <code>name</code> attribute shouldn't be specified; use +<code>module_name</code> instead. + </td> + </tr> + </tbody> + </table> + + <h2 id="bazel_dep">bazel_dep</h2> + <p><pre class="rule-signature"><code>None</code> bazel_dep(*, name, version='', max_compatibility_level=-1, repo_name='', dev_dependency=False)</pre></p> + + Declares a direct dependency on another Bazel module. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="bazel_dep.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the module to be added as a direct dependency. + </td> + </tr> + <tr> + <td id="bazel_dep.version"> + <code>version</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The version of the module to be added as a direct dependency. + </td> + </tr> + <tr> + <td id="bazel_dep.max_compatibility_level"> + <code>max_compatibility_level</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>-1</code><br/> + The maximum <code>compatibility_level</code> supported for the module to be added as a direct dependency. The version of the module implies the minimum compatibility_level supported, as well as the maximum if this attribute is not specified. + </td> + </tr> + <tr> + <td id="bazel_dep.repo_name"> + <code>repo_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>''</code><br/> + The name of the external repo representing this dependency. This is by default the +name of the module. Can be set to <code>None</code> to make this dependency a +"<em>nodep</em>" dependency: in this case, this <code>bazel_dep</code> specification +is only honored if the target module already exists in the dependency graph by some +other means. + + </td> + </tr> + <tr> + <td id="bazel_dep.dev_dependency"> + <code>dev_dependency</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, this dependency will be ignored if the current module is not the root module or <code>--ignore_dev_dependency</code> is enabled. + </td> + </tr> + </tbody> + </table> + + <h2 id="flag_alias">flag_alias</h2> + <p><pre class="rule-signature"><code>None</code> flag_alias(name, starlark_flag)</pre></p> + + Maps a command-line flag --foo to a Starlark flag --@repo//defs:foo. Bazel translates all + instances of $ bazel build //target --foo to $ bazel build //target --@repo//defs:foo. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="flag_alias.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the flag. + </td> + </tr> + <tr> + <td id="flag_alias.starlark_flag"> + <code>starlark_flag</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The label of the Starlark flag to alias to. + </td> + </tr> + </tbody> + </table> + + <h2 id="git_override">git_override</h2> + <p><pre class="rule-signature"><code>None</code> git_override(*, module_name, **kwargs)</pre></p> + + Specifies that this dependency should come from a certain commit in a Git repository, +instead of from a registry. Effectively, this dependency will be backed by a +<a href="../repo/git#git_repository"><code>git_repository</code></a> rule. + +<p>This directive only takes effect in the root module; in other words, if a module is +used as a dependency by others, its own overrides are ignored. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="git_override.module_name"> + <code>module_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the Bazel module dependency to apply this override to. + </td> + </tr> + <tr> + <td id="git_override.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + All other arguments are forwarded to the underlying <code>git_repository</code> +repo rule. Note that the <code>name</code> attribute shouldn't be specified; use +<code>module_name</code> instead. + </td> + </tr> + </tbody> + </table> + + <h2 id="include">include</h2> + <p><pre class="rule-signature"><code>None</code> include(label)</pre></p> + + Includes the contents of another MODULE.bazel-like file. Effectively, <code>include()</code> behaves as if the included file is textually placed at the location of the <code>include()</code> call, except that variable bindings (such as those used for <code>use_extension</code>) are only ever visible in the file they occur in, not in any included or including files.<p>Only the root module may use <code>include()</code>; it is an error if a <code>bazel_dep</code>'s MODULE file uses <code>include()</code>.<p>Only files in the main repo may be included.<p><code>include()</code> allows you to segment the root module file into multiple parts, to avoid having an enormous MODULE.bazel file or to better manage access control for individual semantic segments. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="include.label"> + <code>label</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The label pointing to the file to include. The label must point to a file in the main repo; in other words, it <strong>must<strong> start with double slashes (<code>//</code>). The name of the file must end with <code>.MODULE.bazel</code> and must not start with <code>.</code>. + </td> + </tr> + </tbody> + </table> + + <h2 id="inject_repo">inject_repo</h2> + <p><pre class="rule-signature"><code>None</code> inject_repo(extension_proxy, *args, **kwargs)</pre></p> + + Injects one or more new repos into the given module extension. +This is ignored if the current module is not the root module or +<code>--ignore_dev_dependency</code> is enabled. + +<p>Use <a href="#override_repo"><code>override_repo</code></a> instead to override an +existing repo. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="inject_repo.extension_proxy"> + <code>extension_proxy</code> + </td> + <td> + module_extension_proxy; + required<br/> + A module extension proxy object returned by a <code>use_extension</code> call. + </td> + </tr> + <tr> + <td id="inject_repo.args"> + <code>args</code> + </td> + <td> + required<br/> + The repos visible to the current module that should be injected into the +extension under the same name. + </td> + </tr> + <tr> + <td id="inject_repo.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + The new repos to inject into the extension, where the values are the names of +repos in the scope of the current module and the keys are the name they will be +visible under in the extension. +<p>Keys that are not valid identifiers can be specified via a literal dict +passed as extra keyword arguments, e.g., +<code>inject_repo(extension_proxy, **{"foo.2": "foo"})</code>. + + </td> + </tr> + </tbody> + </table> + + <h2 id="local_path_override">local_path_override</h2> + <p><pre class="rule-signature"><code>None</code> local_path_override(*, module_name, path)</pre></p> + + Specifies that this dependency should come from a certain directory on local disk, +instead of from a registry. Effectively, this dependency will be backed by a +<a href="../repo/local#local_repository"><code>local_repository</code></a> rule. + +<p>This directive only takes effect in the root module; in other words, if a module is +used as a dependency by others, its own overrides are ignored. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="local_path_override.module_name"> + <code>module_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the Bazel module dependency to apply this override to. + </td> + </tr> + <tr> + <td id="local_path_override.path"> + <code>path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The path to the directory where this module is. + </td> + </tr> + </tbody> + </table> + + <h2 id="module">module</h2> + <p><pre class="rule-signature"><code>None</code> module(*, name='', version='', compatibility_level=0, repo_name='', bazel_compatibility=[])</pre></p> + + Declares certain properties of the Bazel module represented by the current Bazel repo. These properties are either essential metadata of the module (such as the name and version), or affect behavior of the current module and its dependents. <p>It should be called at most once, and if called, it must be the very first directive in the MODULE.bazel file. It can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="module.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The name of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). A valid module name must: 1) only contain lowercase letters (a-z), digits (0-9), dots (.), hyphens (-), and underscores (_); 2) begin with a lowercase letter; 3) end with a lowercase letter or digit. + </td> + </tr> + <tr> + <td id="module.version"> + <code>version</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The version of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). The version must be in a relaxed SemVer format; see <a href="/external/module#version_format">the documentation</a> for more details. + </td> + </tr> + <tr> + <td id="module.compatibility_level"> + <code>compatibility_level</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>0</code><br/> + The compatibility level of the module; this should be changed every time a major incompatible change is introduced. This is essentially the "major version" of the module in terms of SemVer, except that it's not embedded in the version string itself, but exists as a separate field. Modules with different compatibility levels participate in version resolution as if they're modules with different names, but the final dependency graph cannot contain multiple modules with the same name but different compatibility levels (unless <code>multiple_version_override</code> is in effect). See <a href="/external/module#compatibility_level">the documentation</a> for more details. + </td> + </tr> + <tr> + <td id="module.repo_name"> + <code>repo_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The name of the repository representing this module, as seen by the module itself. By default, the name of the repo is the name of the module. This can be specified to ease migration for projects that have been using a repo name for itself that differs from its module name. + </td> + </tr> + <tr> + <td id="module.bazel_compatibility"> + <code>bazel_compatibility</code> + </td> + <td> + Iterable of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A list of bazel versions that allows users to declare which Bazel versions are compatible with this module. It does NOT affect dependency resolution, but bzlmod will use this information to check if your current Bazel version is compatible. The format of this value is a string of some constraint values separated by comma. Three constraints are supported: <=X.X.X: The Bazel version must be equal or older than X.X.X. Used when there is a known incompatible change in a newer version. >=X.X.X: The Bazel version must be equal or newer than X.X.X.Used when you depend on some features that are only available since X.X.X. -X.X.X: The Bazel version X.X.X is not compatible. Used when there is a bug in X.X.X that breaks you, but fixed in later versions. + </td> + </tr> + </tbody> + </table> + + <h2 id="multiple_version_override">multiple_version_override</h2> + <p><pre class="rule-signature"><code>None</code> multiple_version_override(*, module_name, versions, registry='')</pre></p> + + Specifies that a dependency should still come from a registry, but multiple versions of it should be allowed to coexist. See <a href="/external/module#multiple-version_override">the documentation</a> for more details. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="multiple_version_override.module_name"> + <code>module_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the Bazel module dependency to apply this override to. + </td> + </tr> + <tr> + <td id="multiple_version_override.versions"> + <code>versions</code> + </td> + <td> + Iterable of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + Explicitly specifies the versions allowed to coexist. These versions must already be present in the dependency graph pre-selection. Dependencies on this module will be "upgraded" to the nearest higher allowed version at the same compatibility level, whereas dependencies that have a higher version than any allowed versions at the same compatibility level will cause an error. + </td> + </tr> + <tr> + <td id="multiple_version_override.registry"> + <code>registry</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. + </td> + </tr> + </tbody> + </table> + + <h2 id="override_repo">override_repo</h2> + <p><pre class="rule-signature"><code>None</code> override_repo(extension_proxy, *args, **kwargs)</pre></p> + + Overrides one or more repos defined by the given module extension with the given repos +visible to the current module. This is ignored if the current module is not the root +module or `--ignore_dev_dependency` is enabled. + +<p>Use <a href="#inject_repo"><code>inject_repo</code></a> instead to add a new repo. + + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="override_repo.extension_proxy"> + <code>extension_proxy</code> + </td> + <td> + module_extension_proxy; + required<br/> + A module extension proxy object returned by a <code>use_extension</code> call. + </td> + </tr> + <tr> + <td id="override_repo.args"> + <code>args</code> + </td> + <td> + required<br/> + The repos in the extension that should be overridden with the repos of the same +name in the current module. + </td> + </tr> + <tr> + <td id="override_repo.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + The overrides to apply to the repos generated by the extension, where the values +are the names of repos in the scope of the current module and the keys are the +names of the repos they will override in the extension. +<p>Keys that are not valid identifiers can be specified via a literal dict +passed as extra keyword arguments, e.g., +<code>override_repo(extension_proxy, **{"foo.2": "foo"})</code>. + + </td> + </tr> + </tbody> + </table> + + <h2 id="register_execution_platforms">register_execution_platforms</h2> + <p><pre class="rule-signature"><code>None</code> register_execution_platforms(*platform_labels, dev_dependency=False)</pre></p> + + Specifies already-defined execution platforms to be registered when this module is selected. Should be absolute <a href='https://bazel.build/reference/glossary#target-pattern'>target patterns</a> (ie. beginning with either <code>@</code> or <code>//</code>). See <a href="/docs/toolchains">toolchain resolution</a> for more information. Patterns that expand to multiple targets, such as <code>:all</code>, will be registered in lexicographical order by name. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="register_execution_platforms.dev_dependency"> + <code>dev_dependency</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the execution platforms will not be registered if the current module is not the root module or `--ignore_dev_dependency` is enabled. + </td> + </tr> + <tr> + <td id="register_execution_platforms.platform_labels"> + <code>platform_labels</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The target patterns to register. + </td> + </tr> + </tbody> + </table> + + <h2 id="register_toolchains">register_toolchains</h2> + <p><pre class="rule-signature"><code>None</code> register_toolchains(*toolchain_labels, dev_dependency=False)</pre></p> + + Specifies already-defined toolchains to be registered when this module is selected. Should be absolute <a href='https://bazel.build/reference/glossary#target-pattern'>target patterns</a> (ie. beginning with either <code>@</code> or <code>//</code>). See <a href="/docs/toolchains">toolchain resolution</a> for more information. Patterns that expand to multiple targets, such as <code>:all</code>, will be registered in lexicographical order by target name (not the name of the toolchain implementation). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="register_toolchains.dev_dependency"> + <code>dev_dependency</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the toolchains will not be registered if the current module is not the root module or `--ignore_dev_dependency` is enabled. + </td> + </tr> + <tr> + <td id="register_toolchains.toolchain_labels"> + <code>toolchain_labels</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The target patterns to register. + </td> + </tr> + </tbody> + </table> + + <h2 id="single_version_override">single_version_override</h2> + <p><pre class="rule-signature"><code>None</code> single_version_override(*, module_name, version='', registry='', patches=[], patch_cmds=[], patch_strip=0)</pre></p> + + Specifies that a dependency should still come from a registry, but its version should be pinned, or its registry overridden, or a list of patches applied. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="single_version_override.module_name"> + <code>module_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the Bazel module dependency to apply this override to. + </td> + </tr> + <tr> + <td id="single_version_override.version"> + <code>version</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Overrides the declared version of this module in the dependency graph. In other words, this module will be "pinned" to this override version. This attribute can be omitted if all one wants to override is the registry or the patches. + </td> + </tr> + <tr> + <td id="single_version_override.registry"> + <code>registry</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. + </td> + </tr> + <tr> + <td id="single_version_override.patches"> + <code>patches</code> + </td> + <td> + Iterable of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A list of labels pointing to patch files to apply for this module. The patch files must exist in the source tree of the top level project. They are applied in the list order.<p>If a patch makes changes to the MODULE.bazel file, these changes will only be effective if the patch file is provided by the root module. + </td> + </tr> + <tr> + <td id="single_version_override.patch_cmds"> + <code>patch_cmds</code> + </td> + <td> + Iterable of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Sequence of Bash commands to be applied on Linux/Macos after patches are applied.<p>Changes to the MODULE.bazel file will not be effective. + </td> + </tr> + <tr> + <td id="single_version_override.patch_strip"> + <code>patch_strip</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>0</code><br/> + Same as the --strip argument of Unix patch. + </td> + </tr> + </tbody> + </table> + + <h2 id="use_extension">use_extension</h2> + <p><pre class="rule-signature">module_extension_proxy use_extension(extension_bzl_file, extension_name, *, dev_dependency=False, isolate=False)</pre></p> + + Returns a proxy object representing a module extension; its methods can be invoked to create module extension tags. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="use_extension.extension_bzl_file"> + <code>extension_bzl_file</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A label to the Starlark file defining the module extension. + </td> + </tr> + <tr> + <td id="use_extension.extension_name"> + <code>extension_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the module extension to use. A symbol with this name must be exported by the Starlark file. + </td> + </tr> + <tr> + <td id="use_extension.dev_dependency"> + <code>dev_dependency</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, this usage of the module extension will be ignored if the current module is not the root module or `--ignore_dev_dependency` is enabled. + </td> + </tr> + <tr> + <td id="use_extension.isolate"> + <code>isolate</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + <b>Experimental</b>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_isolated_extension_usages</code> <br>If true, this usage of the module extension will be isolated from all other usages, both in this and other modules. Tags created for this usage do not affect other usages and the repositories generated by the extension for this usage will be distinct from all other repositories generated by the extension.<p>This parameter is currently experimental and only available with the flag <code>--experimental_isolated_extension_usages</code>. + </td> + </tr> + </tbody> + </table> + + <h2 id="use_repo">use_repo</h2> + <p><pre class="rule-signature"><code>None</code> use_repo(extension_proxy, *args, **kwargs)</pre></p> + + Imports one or more repos generated by the given module extension into the scope of the current module. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="use_repo.extension_proxy"> + <code>extension_proxy</code> + </td> + <td> + module_extension_proxy; + required<br/> + A module extension proxy object returned by a <code>use_extension</code> call. + </td> + </tr> + <tr> + <td id="use_repo.args"> + <code>args</code> + </td> + <td> + required<br/> + The names of the repos to import. + </td> + </tr> + <tr> + <td id="use_repo.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + Specifies certain repos to import into the scope of the current module with +different names. The keys should be the name to use in the current scope, +whereas the values should be the original names exported by the module +extension. +<p>Keys that are not valid identifiers can be specified via a literal dict +passed as extra keyword arguments, e.g., +<code>use_repo(extension_proxy, **{"foo.2": "foo"})</code>. + + </td> + </tr> + </tbody> + </table> + + <h2 id="use_repo_rule">use_repo_rule</h2> + <p><pre class="rule-signature">repo_rule_proxy use_repo_rule(repo_rule_bzl_file, repo_rule_name)</pre></p> + + Returns a proxy value that can be directly invoked in the MODULE.bazel file as a repository rule, one or more times. Repos created in such a way are only visible to the current module, under the name declared using the <code>name</code> attribute on the proxy. The implicit Boolean <code>dev_dependency</code> attribute can also be used on the proxy to denote that a certain repo is only to be created when the current module is the root module. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="use_repo_rule.repo_rule_bzl_file"> + <code>repo_rule_bzl_file</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A label to the Starlark file defining the repo rule. + </td> + </tr> + <tr> + <td id="use_repo_rule.repo_rule_name"> + <code>repo_rule_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the repo rule to use. A symbol with this name must be exported by the Starlark file. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/globals/repo.mdx b/rules/lib/globals/repo.mdx new file mode 100644 index 0000000..7bd98fd --- /dev/null +++ b/rules/lib/globals/repo.mdx @@ -0,0 +1,97 @@ +--- +title: 'repo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.repo">REPO.bazel files</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Methods available in REPO.bazel files. + +<h2>Members</h2> +<ul> + <li> + <a href="#ignore_directories">ignore_directories</a> + </li> + <li> + <a href="#repo">repo</a> + </li> + </ul> + + <h2 id="ignore_directories">ignore_directories</h2> + <p><pre class="rule-signature"><code>None</code> ignore_directories(dirs)</pre></p> + + The list of directories to ignore in this repository. <p>This function takes a list of strings and a directory is ignored if any of the given strings matches its repository-relative path according to the semantics of the <code>glob()</code> function. This function can be used to ignore directories that are implementation details of source control systems, output files of other build systems, etc. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="ignore_directories.dirs"> + <code>dirs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + + </td> + </tr> + </tbody> + </table> + + <h2 id="repo">repo</h2> + <p><pre class="rule-signature"><code>None</code> repo(**kwargs)</pre></p> + + Declares metadata that applies to every rule in the repository. It must be called at most once per REPO.bazel file. If called, it must be the first call in the REPO.bazel file. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="repo.kwargs"> + <code>kwargs</code> + </td> + <td> + required<br/> + The <code>repo()</code> function accepts exactly the same arguments as the <a href="/reference/be/functions#package"><code>package()</code></a> function in BUILD files. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/globals/vendor.mdx b/rules/lib/globals/vendor.mdx new file mode 100644 index 0000000..8cc6169 --- /dev/null +++ b/rules/lib/globals/vendor.mdx @@ -0,0 +1,96 @@ +--- +title: 'vendor' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.vendor">VENDOR.bazel files</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Methods available in VENDOR.bazel files. + +<h2>Members</h2> +<ul> + <li> + <a href="#ignore">ignore</a> + </li> + <li> + <a href="#pin">pin</a> + </li> + </ul> + + <h2 id="ignore">ignore</h2> + <p><pre class="rule-signature"><code>None</code> ignore(*args)</pre></p> + + Ignore this repo from vendoring. Bazel will never vendor it or use the corresponding directory (if exists) while building in vendor mode. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="ignore.args"> + <code>args</code> + </td> + <td> + required<br/> + The canonical repo names of the repos to ignore. + </td> + </tr> + </tbody> + </table> + + <h2 id="pin">pin</h2> + <p><pre class="rule-signature"><code>None</code> pin(*args)</pre></p> + + Pin the contents of this repo under the vendor directory. Bazel will not update this repo while vendoring, and will use the vendored source as if there is a --override_repository flag when building in vendor mode + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="pin.args"> + <code>args</code> + </td> + <td> + required<br/> + The canonical repo names of the repos to pin. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/overview.mdx b/rules/lib/overview.mdx new file mode 100644 index 0000000..523d812 --- /dev/null +++ b/rules/lib/overview.mdx @@ -0,0 +1,1094 @@ +--- +title: 'overview' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> +<h1 class="page-title">One-Page Overview</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm" %} +{% include "_buttons.html" %} +<h2> + + + <a href="/rules/lib/globals">Global functions</a> + + +</h2> +<ul> + + <li> + + + <a href="/rules/lib/globals/bzl">.bzl files</a> + + </li> + + + <li> + + + <a href="/rules/lib/globals/all">All Bazel files</a> + + </li> + + + <li> + + + <a href="/rules/lib/globals/build">BUILD files</a> + + </li> + + + <li> + + + <a href="/rules/lib/globals/module">MODULE.bazel files</a> + + </li> + + + <li> + + + <a href="/rules/lib/globals/repo">REPO.bazel files</a> + + </li> + + + <li> + + + <a href="/rules/lib/globals/vendor">VENDOR.bazel files</a> + + </li> + +</ul> +<h2> + + + <a href="/rules/lib/fragments">Configuration Fragments</a> + + +</h2> +<ul> + + <li> + + + <a href="/rules/lib/fragments/apple">apple</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/bazel_android">bazel_android</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/bazel_py">bazel_py</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/coverage">coverage</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/cpp">cpp</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/j2objc">j2objc</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/java">java</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/objc">objc</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/platform">platform</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/proto">proto</a> + + </li> + + + <li> + + + <a href="/rules/lib/fragments/py">py</a> + + </li> + +</ul> +<h2> + + + <a href="/rules/lib/providers">Providers</a> + + +</h2> +<ul> + + <li> + + + <a href="/rules/lib/providers/AnalysisTestResultInfo">AnalysisTestResultInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/CcInfo">CcInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/CcToolchainConfigInfo">CcToolchainConfigInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/CcToolchainInfo">CcToolchainInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/ConstraintCollection">ConstraintCollection</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/ConstraintSettingInfo">ConstraintSettingInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/ConstraintValueInfo">ConstraintValueInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/DebugPackageInfo">DebugPackageInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/DefaultInfo">DefaultInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/ExecutionInfo">ExecutionInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/FeatureFlagInfo">FeatureFlagInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/file_provider">file_provider</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/FilesToRunProvider">FilesToRunProvider</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/IncompatiblePlatformProvider">IncompatiblePlatformProvider</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/InstrumentedFilesInfo">InstrumentedFilesInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/java_compilation_info">java_compilation_info</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/java_output_jars">java_output_jars</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/JavaRuntimeInfo">JavaRuntimeInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/JavaToolchainInfo">JavaToolchainInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/MaterializedDepsInfo">MaterializedDepsInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/ObjcProvider">ObjcProvider</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/OutputGroupInfo">OutputGroupInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/PackageSpecificationInfo">PackageSpecificationInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/PlatformInfo">PlatformInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/RunEnvironmentInfo">RunEnvironmentInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/TemplateVariableInfo">TemplateVariableInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/ToolchainInfo">ToolchainInfo</a> + + </li> + + + <li> + + + <a href="/rules/lib/providers/ToolchainTypeInfo">ToolchainTypeInfo</a> + + </li> + +</ul> +<h2> + + + <a href="/rules/lib/builtins">Built-in Types</a> + + +</h2> +<ul> + + <li> + + + <a href="/rules/lib/builtins/Action">Action</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/actions">actions</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/apple_platform">apple_platform</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/Args">Args</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/Aspect">Aspect</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/Attribute">Attribute</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/bazel_module">bazel_module</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/bazel_module_tags">bazel_module_tags</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/BuildSetting">BuildSetting</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/CcCompilationOutputs">CcCompilationOutputs</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/CcLinkingOutputs">CcLinkingOutputs</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/CompilationContext">CompilationContext</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/configuration">configuration</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/ctx">ctx</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/depset">depset</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/DirectoryExpander">DirectoryExpander</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/DottedVersion">DottedVersion</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/exec_result">exec_result</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/ExecGroupCollection">ExecGroupCollection</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/ExecGroupContext">ExecGroupContext</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/ExecTransitionFactory">ExecTransitionFactory</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/ExpandedDirectory">ExpandedDirectory</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/extension_metadata">extension_metadata</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/FeatureConfiguration">FeatureConfiguration</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/File">File</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/fragments">fragments</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/java_annotation_processing">java_annotation_processing</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/Label">Label</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/LateBoundDefault">LateBoundDefault</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/LibraryToLink">LibraryToLink</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/License">License</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/LinkerInput">LinkerInput</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/LinkingContext">LinkingContext</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/macro">macro</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/mapped_root">mapped_root</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/module_ctx">module_ctx</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/path">path</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/propagation_ctx">propagation_ctx</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/Provider">Provider</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/repo_metadata">repo_metadata</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/repository_ctx">repository_ctx</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/repository_os">repository_os</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/repository_rule">repository_rule</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/root">root</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/rule">rule</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/rule_attributes">rule_attributes</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/runfiles">runfiles</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/struct">struct</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/Subrule">Subrule</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/subrule_ctx">subrule_ctx</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/SymlinkEntry">SymlinkEntry</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/tag_class">tag_class</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/Target">Target</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/template_ctx">template_ctx</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/TemplateDict">TemplateDict</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/toolchain_type">toolchain_type</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/ToolchainContext">ToolchainContext</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/transition">transition</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/wasm_exec_result">wasm_exec_result</a> + + </li> + + + <li> + + + <a href="/rules/lib/builtins/wasm_module">wasm_module</a> + + </li> + +</ul> +<h2> + + + <a href="/rules/lib/toplevel">Top-level Modules</a> + + +</h2> +<ul> + + <li> + + + <a href="/rules/lib/toplevel/apple_common">apple_common</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/attr">attr</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/cc_common">cc_common</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/config">config</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/config_common">config_common</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/coverage_common">coverage_common</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/java_common">java_common</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/native">native</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/platform_common">platform_common</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/proto">proto</a> + + </li> + + + <li> + + + <a href="/rules/lib/toplevel/testing">testing</a> + + </li> + +</ul> +<h2> + + + <a href="/rules/lib/core">Core Starlark data types</a> + + +</h2> +<ul> + + <li> + + + <a href="/rules/lib/core/bool">bool</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/builtin_function_or_method">builtin_function_or_method</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/dict">dict</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/float">float</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/function">function</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/int">int</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/json">json</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/list">list</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/range">range</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/set">set</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/string">string</a> + + </li> + + + <li> + + + <a href="/rules/lib/core/tuple">tuple</a> + + </li> + +</ul> +</body> +</html> diff --git a/rules/lib/providers.mdx b/rules/lib/providers.mdx new file mode 100644 index 0000000..4254fc1 --- /dev/null +++ b/rules/lib/providers.mdx @@ -0,0 +1,76 @@ +--- +title: 'providers' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> +<h1 class="page-title">Providers</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +This section lists providers available on built-in rules. See the <a href='https://bazel.build/extending/rules#providers'>Rules page</a> for more on providers. These symbols are available only in .bzl files. + +<ul> + +<li><a href="/rules/lib/providers/AnalysisTestResultInfo">AnalysisTestResultInfo</a></li> + +<li><a href="/rules/lib/providers/CcInfo">CcInfo</a></li> + +<li><a href="/rules/lib/providers/CcToolchainConfigInfo">CcToolchainConfigInfo</a></li> + +<li><a href="/rules/lib/providers/CcToolchainInfo">CcToolchainInfo</a></li> + +<li><a href="/rules/lib/providers/ConstraintCollection">ConstraintCollection</a></li> + +<li><a href="/rules/lib/providers/ConstraintSettingInfo">ConstraintSettingInfo</a></li> + +<li><a href="/rules/lib/providers/ConstraintValueInfo">ConstraintValueInfo</a></li> + +<li><a href="/rules/lib/providers/DebugPackageInfo">DebugPackageInfo</a></li> + +<li><a href="/rules/lib/providers/DefaultInfo">DefaultInfo</a></li> + +<li><a href="/rules/lib/providers/ExecutionInfo">ExecutionInfo</a></li> + +<li><a href="/rules/lib/providers/FeatureFlagInfo">FeatureFlagInfo</a></li> + +<li><a href="/rules/lib/providers/file_provider">file_provider</a></li> + +<li><a href="/rules/lib/providers/FilesToRunProvider">FilesToRunProvider</a></li> + +<li><a href="/rules/lib/providers/IncompatiblePlatformProvider">IncompatiblePlatformProvider</a></li> + +<li><a href="/rules/lib/providers/InstrumentedFilesInfo">InstrumentedFilesInfo</a></li> + +<li><a href="/rules/lib/providers/java_compilation_info">java_compilation_info</a></li> + +<li><a href="/rules/lib/providers/java_output_jars">java_output_jars</a></li> + +<li><a href="/rules/lib/providers/JavaRuntimeInfo">JavaRuntimeInfo</a></li> + +<li><a href="/rules/lib/providers/JavaToolchainInfo">JavaToolchainInfo</a></li> + +<li><a href="/rules/lib/providers/MaterializedDepsInfo">MaterializedDepsInfo</a></li> + +<li><a href="/rules/lib/providers/ObjcProvider">ObjcProvider</a></li> + +<li><a href="/rules/lib/providers/OutputGroupInfo">OutputGroupInfo</a></li> + +<li><a href="/rules/lib/providers/PackageSpecificationInfo">PackageSpecificationInfo</a></li> + +<li><a href="/rules/lib/providers/PlatformInfo">PlatformInfo</a></li> + +<li><a href="/rules/lib/providers/RunEnvironmentInfo">RunEnvironmentInfo</a></li> + +<li><a href="/rules/lib/providers/TemplateVariableInfo">TemplateVariableInfo</a></li> + +<li><a href="/rules/lib/providers/ToolchainInfo">ToolchainInfo</a></li> + +<li><a href="/rules/lib/providers/ToolchainTypeInfo">ToolchainTypeInfo</a></li> +</ul> +</body> +</html> diff --git a/rules/lib/providers/AnalysisTestResultInfo.mdx b/rules/lib/providers/AnalysisTestResultInfo.mdx new file mode 100644 index 0000000..0121624 --- /dev/null +++ b/rules/lib/providers/AnalysisTestResultInfo.mdx @@ -0,0 +1,89 @@ +--- +title: 'AnalysisTestResultInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.AnalysisTestResultInfo">AnalysisTestResultInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/AnalysisTestResultInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Encapsulates the result of analyis-phase testing. Build targets which return an instance of this provider signal to the build system that it should generate a 'stub' test executable which generates the equivalent test result. Analysis test rules (rules created with <code>analysis_test=True</code> <b>must</b> return an instance of this provider, and non-analysis-phase test rules <b>cannot</b> return this provider. + +<h2>Members</h2> +<ul> + <li> + <a href="#AnalysisTestResultInfo">AnalysisTestResultInfo</a> + </li> + <li> + <a href="#message">message</a> + </li> + <li> + <a href="#success">success</a> + </li> + </ul> + + <h2 id="AnalysisTestResultInfo">AnalysisTestResultInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/AnalysisTestResultInfo.html">AnalysisTestResultInfo</a> AnalysisTestResultInfo(success, message)</pre></p> + + The <code>AnalysisTestResultInfo</code> constructor. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="AnalysisTestResultInfo.success"> + <code>success</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + required<br/> + If true, then the analysis-phase test represented by this target should pass. If false, the test should fail. + </td> + </tr> + <tr> + <td id="AnalysisTestResultInfo.message"> + <code>message</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A descriptive message containing information about the test and its success/failure. + </td> + </tr> + </tbody> + </table> + + <h2 id="message">message</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> AnalysisTestResultInfo.message</pre></p> + + A descriptive message containing information about the test and its success/failure. + + <h2 id="success">success</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> AnalysisTestResultInfo.success</pre></p> + + If true, then the analysis-phase test represented by this target passed. If false, the test failed. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/CcInfo.mdx b/rules/lib/providers/CcInfo.mdx new file mode 100644 index 0000000..fb7fc77 --- /dev/null +++ b/rules/lib/providers/CcInfo.mdx @@ -0,0 +1,99 @@ +--- +title: 'CcInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.CcInfo">CcInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A provider for compilation and linking of C++. This is also a marking provider telling C++ rules that they can depend on the rule with this provider. If it is not intended for the rule to be depended on by C++, the rule should wrap the CcInfo in some other provider. + +<h2>Members</h2> +<ul> + <li> + <a href="#CcInfo">CcInfo</a> + </li> + <li> + <a href="#compilation_context">compilation_context</a> + </li> + <li> + <a href="#linking_context">linking_context</a> + </li> + </ul> + + <h2 id="CcInfo">CcInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/CcInfo.html">CcInfo</a> CcInfo(*, compilation_context=None, linking_context=None, debug_context=None)</pre></p> + + The <code>CcInfo</code> constructor. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="CcInfo.compilation_context"> + <code>compilation_context</code> + </td> + <td> + <a class="anchor" href="../builtins/CompilationContext.html">CompilationContext</a>; or <code>None</code>; + default is <code>None</code><br/> + The <code>CompilationContext</code>. + </td> + </tr> + <tr> + <td id="CcInfo.linking_context"> + <code>linking_context</code> + </td> + <td> + <a class="anchor" href="../builtins/struct.html">struct</a>; or <code>None</code>; + default is <code>None</code><br/> + The <code>LinkingContext</code>. + </td> + </tr> + <tr> + <td id="CcInfo.debug_context"> + <code>debug_context</code> + </td> + <td> + <a class="anchor" href="../builtins/struct.html">struct</a>; or <code>None</code>; + default is <code>None</code><br/> + The <code>DebugContext</code>. + </td> + </tr> + </tbody> + </table> + + <h2 id="compilation_context">compilation_context</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/CompilationContext.html">CompilationContext</a> CcInfo.compilation_context</pre></p> + + Returns the <code>CompilationContext</code> + + <h2 id="linking_context">linking_context</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> CcInfo.linking_context</pre></p> + + Returns the <code>LinkingContext</code> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/CcToolchainConfigInfo.mdx b/rules/lib/providers/CcToolchainConfigInfo.mdx new file mode 100644 index 0000000..2b5d5c5 --- /dev/null +++ b/rules/lib/providers/CcToolchainConfigInfo.mdx @@ -0,0 +1,25 @@ +--- +title: 'CcToolchainConfigInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.CcToolchainConfigInfo">CcToolchainConfigInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcToolchainConfigInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Additional layer of configurability for C++ rules. Encapsulates platform-dependent specifics of C++ actions through features and action configs. It is used to configure the C++ toolchain, and later on for command line construction. Replaces the functionality of CROSSTOOL file. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/CcToolchainInfo.mdx b/rules/lib/providers/CcToolchainInfo.mdx new file mode 100644 index 0000000..495d795 --- /dev/null +++ b/rules/lib/providers/CcToolchainInfo.mdx @@ -0,0 +1,258 @@ +--- +title: 'CcToolchainInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.CcToolchainInfo">CcToolchainInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcToolchainProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Information about the C++ compiler being used. + +<h2>Members</h2> +<ul> + <li> + <a href="#all_files">all_files</a> + </li> + <li> + <a href="#ar_executable">ar_executable</a> + </li> + <li> + <a href="#built_in_include_directories">built_in_include_directories</a> + </li> + <li> + <a href="#compiler">compiler</a> + </li> + <li> + <a href="#compiler_executable">compiler_executable</a> + </li> + <li> + <a href="#cpu">cpu</a> + </li> + <li> + <a href="#dynamic_runtime_lib">dynamic_runtime_lib</a> + </li> + <li> + <a href="#gcov_executable">gcov_executable</a> + </li> + <li> + <a href="#ld_executable">ld_executable</a> + </li> + <li> + <a href="#libc">libc</a> + </li> + <li> + <a href="#needs_pic_for_dynamic_libraries">needs_pic_for_dynamic_libraries</a> + </li> + <li> + <a href="#nm_executable">nm_executable</a> + </li> + <li> + <a href="#objcopy_executable">objcopy_executable</a> + </li> + <li> + <a href="#objdump_executable">objdump_executable</a> + </li> + <li> + <a href="#preprocessor_executable">preprocessor_executable</a> + </li> + <li> + <a href="#static_runtime_lib">static_runtime_lib</a> + </li> + <li> + <a href="#strip_executable">strip_executable</a> + </li> + <li> + <a href="#sysroot">sysroot</a> + </li> + <li> + <a href="#target_gnu_system_name">target_gnu_system_name</a> + </li> + </ul> + + <h2 id="all_files">all_files</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.all_files</pre></p> + + Returns all toolchain files (so they can be passed to actions using this toolchain as inputs). + + <h2 id="ar_executable">ar_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.ar_executable</pre></p> + + The path to the ar binary. + + <h2 id="built_in_include_directories">built_in_include_directories</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.built_in_include_directories</pre></p> + + Returns the list of built-in directories of the compiler. + + <h2 id="compiler">compiler</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.compiler</pre></p> + + C++ compiler. + + <h2 id="compiler_executable">compiler_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.compiler_executable</pre></p> + + The path to the compiler binary. + + <h2 id="cpu">cpu</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.cpu</pre></p> + + Target CPU of the C++ toolchain. + + <h2 id="dynamic_runtime_lib">dynamic_runtime_lib</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.dynamic_runtime_lib(*, feature_configuration)</pre></p> + + Returns the files from `dynamic_runtime_lib` attribute (so they can be passed to actions using this toolchain as inputs). The caller can check whether the feature_configuration enables `static_link_cpp_runtimes` feature (if not, neither `static_runtime_lib` nor `dynamic_runtime_lib` have to be used), and use `static_runtime_lib` if static linking mode is active. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="dynamic_runtime_lib.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + required<br/> + Feature configuration to be queried. + </td> + </tr> + </tbody> + </table> + + <h2 id="gcov_executable">gcov_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.gcov_executable</pre></p> + + The path to the gcov binary. + + <h2 id="ld_executable">ld_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.ld_executable</pre></p> + + The path to the ld binary. + + <h2 id="libc">libc</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.libc</pre></p> + + libc version string. + + <h2 id="needs_pic_for_dynamic_libraries">needs_pic_for_dynamic_libraries</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.needs_pic_for_dynamic_libraries(*, feature_configuration)</pre></p> + + Returns true if this rule's compilations should apply -fPIC, false otherwise. Determines if we should apply -fPIC for this rule's C++ compilations depending on the C++ toolchain and presence of `--force_pic` Bazel option. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="needs_pic_for_dynamic_libraries.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + required<br/> + Feature configuration to be queried. + </td> + </tr> + </tbody> + </table> + + <h2 id="nm_executable">nm_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.nm_executable</pre></p> + + The path to the nm binary. + + <h2 id="objcopy_executable">objcopy_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.objcopy_executable</pre></p> + + The path to the objcopy binary. + + <h2 id="objdump_executable">objdump_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.objdump_executable</pre></p> + + The path to the objdump binary. + + <h2 id="preprocessor_executable">preprocessor_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.preprocessor_executable</pre></p> + + The path to the preprocessor binary. + + <h2 id="static_runtime_lib">static_runtime_lib</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.static_runtime_lib(*, feature_configuration)</pre></p> + + Returns the files from `static_runtime_lib` attribute (so they can be passed to actions using this toolchain as inputs). The caller should check whether the feature_configuration enables `static_link_cpp_runtimes` feature (if not, neither `static_runtime_lib` nor `dynamic_runtime_lib` should be used), and use `dynamic_runtime_lib` if dynamic linking mode is active. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="static_runtime_lib.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + required<br/> + Feature configuration to be queried. + </td> + </tr> + </tbody> + </table> + + <h2 id="strip_executable">strip_executable</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.strip_executable</pre></p> + + The path to the strip binary. + + <h2 id="sysroot">sysroot</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.sysroot</pre></p> + + Returns the sysroot to be used. If the toolchain compiler does not support different sysroots, or the sysroot is the same as the default sysroot, then this method returns <code>None</code>. + + <h2 id="target_gnu_system_name">target_gnu_system_name</h2> + <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.target_gnu_system_name</pre></p> + + The GNU System Name. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/ConstraintCollection.mdx b/rules/lib/providers/ConstraintCollection.mdx new file mode 100644 index 0000000..899e483 --- /dev/null +++ b/rules/lib/providers/ConstraintCollection.mdx @@ -0,0 +1,25 @@ +--- +title: 'ConstraintCollection' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ConstraintCollection">ConstraintCollection</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintCollectionApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Provides access to data about a collection of ConstraintValueInfo providers. <br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/ConstraintSettingInfo.mdx b/rules/lib/providers/ConstraintSettingInfo.mdx new file mode 100644 index 0000000..51825f5 --- /dev/null +++ b/rules/lib/providers/ConstraintSettingInfo.mdx @@ -0,0 +1,36 @@ +--- +title: 'ConstraintSettingInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ConstraintSettingInfo">ConstraintSettingInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintSettingInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A specific constraint setting that may be used to define a platform. See <a href='/docs/platforms#constraints-platforms'>Defining Constraints and Platforms</a> for more information.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> + +<h2>Members</h2> +<ul> + <li> + <a href="#has_default_constraint_value">has_default_constraint_value</a> + </li> + </ul> + + <h2 id="has_default_constraint_value">has_default_constraint_value</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> ConstraintSettingInfo.has_default_constraint_value</pre></p> + + Whether there is a default constraint_value for this setting. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/ConstraintValueInfo.mdx b/rules/lib/providers/ConstraintValueInfo.mdx new file mode 100644 index 0000000..e37a096 --- /dev/null +++ b/rules/lib/providers/ConstraintValueInfo.mdx @@ -0,0 +1,25 @@ +--- +title: 'ConstraintValueInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ConstraintValueInfo">ConstraintValueInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintValueInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A value for a constraint setting that can be used to define a platform. See <a href='/docs/platforms#constraints-platforms'>Defining Constraints and Platforms</a> for more information.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/DebugPackageInfo.mdx b/rules/lib/providers/DebugPackageInfo.mdx new file mode 100644 index 0000000..ba5c589 --- /dev/null +++ b/rules/lib/providers/DebugPackageInfo.mdx @@ -0,0 +1,127 @@ +--- +title: 'DebugPackageInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.DebugPackageInfo">DebugPackageInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/DebugPackageInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A provider for the binary file and its associated .dwp files, if fission is enabled.If Fission ({@url https://gcc.gnu.org/wiki/DebugFission}) is not enabled, the dwp file will be null. + +<h2>Members</h2> +<ul> + <li> + <a href="#DebugPackageInfo">DebugPackageInfo</a> + </li> + <li> + <a href="#dwp_file">dwp_file</a> + </li> + <li> + <a href="#stripped_file">stripped_file</a> + </li> + <li> + <a href="#target_label">target_label</a> + </li> + <li> + <a href="#unstripped_file">unstripped_file</a> + </li> + </ul> + + <h2 id="DebugPackageInfo">DebugPackageInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/DebugPackageInfo.html">DebugPackageInfo</a> DebugPackageInfo(*, target_label, stripped_file=None, unstripped_file, dwp_file=None)</pre></p> + + The <code>DebugPackageInfo</code> constructor. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="DebugPackageInfo.target_label"> + <code>target_label</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; + required<br/> + The label for the *_binary target + </td> + </tr> + <tr> + <td id="DebugPackageInfo.stripped_file"> + <code>stripped_file</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + The stripped file (the explicit ".stripped" target) + </td> + </tr> + <tr> + <td id="DebugPackageInfo.unstripped_file"> + <code>unstripped_file</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The unstripped file (the default executable target). + </td> + </tr> + <tr> + <td id="DebugPackageInfo.dwp_file"> + <code>dwp_file</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + The .dwp file (for fission builds) or null if --fission=no. + </td> + </tr> + </tbody> + </table> + + <h2 id="dwp_file">dwp_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> DebugPackageInfo.dwp_file</pre></p> + + Returns the .dwp file (for fission builds) or null if --fission=no. + May return <code>None</code>. + + <h2 id="stripped_file">stripped_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> DebugPackageInfo.stripped_file</pre></p> + + Returns the stripped file (the explicit ".stripped" target). + May return <code>None</code>. + + <h2 id="target_label">target_label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> DebugPackageInfo.target_label</pre></p> + + Returns the label for the *_binary target + + <h2 id="unstripped_file">unstripped_file</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> DebugPackageInfo.unstripped_file</pre></p> + + Returns the unstripped file (the default executable target) + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/DefaultInfo.mdx b/rules/lib/providers/DefaultInfo.mdx new file mode 100644 index 0000000..5544755 --- /dev/null +++ b/rules/lib/providers/DefaultInfo.mdx @@ -0,0 +1,144 @@ +--- +title: 'DefaultInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.DefaultInfo">DefaultInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A provider that gives general information about a target's direct and transitive files. Every rule type has this provider, even if it is not returned explicitly by the rule's implementation function. +<p> +See the <a href="https://bazel.build/extending/rules">rules</a> page for extensive guides on how to use this provider. +</p> + + +<h2>Members</h2> +<ul> + <li> + <a href="#DefaultInfo">DefaultInfo</a> + </li> + <li> + <a href="#data_runfiles">data_runfiles</a> + </li> + <li> + <a href="#default_runfiles">default_runfiles</a> + </li> + <li> + <a href="#files">files</a> + </li> + <li> + <a href="#files_to_run">files_to_run</a> + </li> + </ul> + + <h2 id="DefaultInfo">DefaultInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/DefaultInfo.html">DefaultInfo</a> DefaultInfo(*, files=None, runfiles=None, data_runfiles=None, default_runfiles=None, executable=None)</pre></p> + + The <code>DefaultInfo</code> constructor. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="DefaultInfo.files"> + <code>files</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + A <a href='../builtins/depset.html'><code>depset</code></a> of <a href='../builtins/File.html'><code>File</code></a> objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. + </td> + </tr> + <tr> + <td id="DefaultInfo.runfiles"> + <code>runfiles</code> + </td> + <td> + <a class="anchor" href="../builtins/runfiles.html">runfiles</a>; or <code>None</code>; + default is <code>None</code><br/> + <a href="../builtins/runfiles.html"><code>runfiles</code></a> descriptor describing the files that this target needs when run (e.g. via the <code>run</code> command or as a tool dependency for an action). + + </td> + </tr> + <tr> + <td id="DefaultInfo.data_runfiles"> + <code>data_runfiles</code> + </td> + <td> + <a class="anchor" href="../builtins/runfiles.html">runfiles</a>; or <code>None</code>; + default is <code>None</code><br/> + <p><b>It is recommended that you avoid using this parameter (see <a href='https://bazel.build/extending/rules#runfiles_features_to_avoid'>"runfiles features to avoid"</a>)</b></p> runfiles descriptor describing the runfiles this target needs to run when it is a dependency via the <code>data</code> attribute. + </td> + </tr> + <tr> + <td id="DefaultInfo.default_runfiles"> + <code>default_runfiles</code> + </td> + <td> + <a class="anchor" href="../builtins/runfiles.html">runfiles</a>; or <code>None</code>; + default is <code>None</code><br/> + <p><b>It is recommended that you avoid using this parameter (see <a href='https://bazel.build/extending/rules#runfiles_features_to_avoid'>"runfiles features to avoid"</a>)</b></p> runfiles descriptor describing the runfiles this target needs to run when it is a dependency via any attribute other than the <code>data</code> attribute. + </td> + </tr> + <tr> + <td id="DefaultInfo.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + If this rule is marked <a href='../globals/bzl.html#rule.executable'><code>executable</code></a> or <a href='../globals/bzl.html#rule.test'><code>test</code></a>, this is a <a href='../builtins/File.html'><code>File</code></a> object representing the file that should be executed to run the target. By default it is the predeclared output <code>ctx.outputs.executable</code> but it is recommended to pass another file (either predeclared or not) explicitly. + </td> + </tr> + </tbody> + </table> + + <h2 id="data_runfiles">data_runfiles</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> DefaultInfo.data_runfiles</pre></p> + + runfiles descriptor describing the files that this target needs when run in the condition that it is a <code>data</code> dependency attribute. Under most circumstances, use the <code>default_runfiles</code> parameter instead. See <a href='https://bazel.build/extending/rules#runfiles_features_to_avoid'>"runfiles features to avoid"</a> for details. + May return <code>None</code>. + + <h2 id="default_runfiles">default_runfiles</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> DefaultInfo.default_runfiles</pre></p> + + runfiles descriptor describing the files that this target needs when run (via the <code>run</code> command or as a tool dependency). + May return <code>None</code>. + + <h2 id="files">files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> DefaultInfo.files</pre></p> + + A <a href='../builtins/depset.html'><code>depset</code></a> of <a href='../builtins/File.html'><code>File</code></a> objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. + May return <code>None</code>. + + <h2 id="files_to_run">files_to_run</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> DefaultInfo.files_to_run</pre></p> + + A <a href='../providers/FilesToRunProvider.html'><code>FilesToRunProvider</code></a> object containing information about the executable and runfiles of the target. + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/ExecutionInfo.mdx b/rules/lib/providers/ExecutionInfo.mdx new file mode 100644 index 0000000..2c57ccd --- /dev/null +++ b/rules/lib/providers/ExecutionInfo.mdx @@ -0,0 +1,89 @@ +--- +title: 'ExecutionInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ExecutionInfo">ExecutionInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/ExecutionInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Use this provider to specify special environment requirements needed to run tests. + +<h2>Members</h2> +<ul> + <li> + <a href="#ExecutionInfo">ExecutionInfo</a> + </li> + <li> + <a href="#exec_group">exec_group</a> + </li> + <li> + <a href="#requirements">requirements</a> + </li> + </ul> + + <h2 id="ExecutionInfo">ExecutionInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/ExecutionInfo.html">ExecutionInfo</a> ExecutionInfo(requirements={}, exec_group='test')</pre></p> + + Creates an instance. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="ExecutionInfo.requirements"> + <code>requirements</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A dict indicating special execution requirements, such as hardware platforms. + </td> + </tr> + <tr> + <td id="ExecutionInfo.exec_group"> + <code>exec_group</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'test'</code><br/> + The name of the exec group that is used to execute the test. + </td> + </tr> + </tbody> + </table> + + <h2 id="exec_group">exec_group</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ExecutionInfo.exec_group</pre></p> + + The name of the exec group that is used to execute the test. + + <h2 id="requirements">requirements</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> ExecutionInfo.requirements</pre></p> + + A dict indicating special execution requirements, such as hardware platforms. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/FeatureFlagInfo.mdx b/rules/lib/providers/FeatureFlagInfo.mdx new file mode 100644 index 0000000..fb2e9da --- /dev/null +++ b/rules/lib/providers/FeatureFlagInfo.mdx @@ -0,0 +1,81 @@ +--- +title: 'FeatureFlagInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.FeatureFlagInfo">FeatureFlagInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigFeatureFlagProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A provider used to access information about config_feature_flag rules. + +<h2>Members</h2> +<ul> + <li> + <a href="#error">error</a> + </li> + <li> + <a href="#is_valid_value">is_valid_value</a> + </li> + <li> + <a href="#value">value</a> + </li> + </ul> + + <h2 id="error">error</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> FeatureFlagInfo.error</pre></p> + + If non-None, this error was generated when trying to compute current value of flag. + May return <code>None</code>. + + <h2 id="is_valid_value">is_valid_value</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> FeatureFlagInfo.is_valid_value(value)</pre></p> + + The value of the flag in the configuration used by the flag rule. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="is_valid_value.value"> + <code>value</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + String, the value to check for validity for this flag. + </td> + </tr> + </tbody> + </table> + + <h2 id="value">value</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> FeatureFlagInfo.value</pre></p> + + The current value of the flag in the flag's current configuration. None if there is an error. + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/FilesToRunProvider.mdx b/rules/lib/providers/FilesToRunProvider.mdx new file mode 100644 index 0000000..efed2c0 --- /dev/null +++ b/rules/lib/providers/FilesToRunProvider.mdx @@ -0,0 +1,56 @@ +--- +title: 'FilesToRunProvider' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.FilesToRunProvider">FilesToRunProvider</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FilesToRunProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Contains information about executables produced by a target and the files needed to run it. This provider can not be created directly, it is an implicit output of executable targets accessible via <a href="../providers/DefaultInfo.html#files_to_run"><code>DefaultInfo.files_to_run</code></a>. + + +<h2>Members</h2> +<ul> + <li> + <a href="#executable">executable</a> + </li> + <li> + <a href="#repo_mapping_manifest">repo_mapping_manifest</a> + </li> + <li> + <a href="#runfiles_manifest">runfiles_manifest</a> + </li> + </ul> + + <h2 id="executable">executable</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> FilesToRunProvider.executable</pre></p> + + The main executable or None if it does not exist. + May return <code>None</code>. + + <h2 id="repo_mapping_manifest">repo_mapping_manifest</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> FilesToRunProvider.repo_mapping_manifest</pre></p> + + The repo mapping manifest or None if it does not exist. + May return <code>None</code>. + + <h2 id="runfiles_manifest">runfiles_manifest</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> FilesToRunProvider.runfiles_manifest</pre></p> + + The runfiles manifest or None if it does not exist. + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/IncompatiblePlatformProvider.mdx b/rules/lib/providers/IncompatiblePlatformProvider.mdx new file mode 100644 index 0000000..979502e --- /dev/null +++ b/rules/lib/providers/IncompatiblePlatformProvider.mdx @@ -0,0 +1,25 @@ +--- +title: 'IncompatiblePlatformProvider' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.IncompatiblePlatformProvider">IncompatiblePlatformProvider</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/IncompatiblePlatformProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A provider for targets that are incompatible with the target platform. See <a href='/docs/platforms#detecting-incompatible-targets-using-bazel-cquery'>Detecting incompatible targets using <code>bazel cquery</code></a> for more information. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/InstrumentedFilesInfo.mdx b/rules/lib/providers/InstrumentedFilesInfo.mdx new file mode 100644 index 0000000..4b82296 --- /dev/null +++ b/rules/lib/providers/InstrumentedFilesInfo.mdx @@ -0,0 +1,44 @@ +--- +title: 'InstrumentedFilesInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.InstrumentedFilesInfo">InstrumentedFilesInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Contains information about source files and instrumentation metadata files for rule targets matched by <a href="https://bazel.build/reference/command-line-reference#flag--instrumentation_filter"><code>--instrumentation_filter</code></a> for purposes of <a href="https://bazel.build/extending/rules#code_coverage">code coverage data collection</a>. When coverage data collection is enabled, a manifest containing the combined paths in <a href="#instrumented_files"><code>instrumented_files</code></a> and <a href="#metadata_files"><code>metadata_files</code></a> are passed to the test action as inputs, with the manifest's path noted in the environment variable <code>COVERAGE_MANIFEST</code>. The metadata files, but not the source files, are also passed to the test action as inputs. When <code>InstrumentedFilesInfo</code> is returned by an <a href="https://bazel.build/extending/aspects">aspect</a>'s implementation function, any <code>InstrumentedFilesInfo</code> from the base rule target is ignored. + +<h2>Members</h2> +<ul> + <li> + <a href="#instrumented_files">instrumented_files</a> + </li> + <li> + <a href="#metadata_files">metadata_files</a> + </li> + </ul> + + <h2 id="instrumented_files">instrumented_files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> InstrumentedFilesInfo.instrumented_files</pre></p> + + <a href="../builtins/depset.html"><code>depset</code></a> of <a href="../builtins/File.html"><code>File</code></a> objects representing instrumented source files for this target and its dependencies. + + <h2 id="metadata_files">metadata_files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> InstrumentedFilesInfo.metadata_files</pre></p> + + <a href="../builtins/depset.html"><code>depset</code></a> of <a href="../builtins/File.html"><code>File</code></a> objects representing coverage metadata files for this target and its dependencies. These files contain additional information required to generate LCOV-format coverage output after the code is executed, e.g. the <code>.gcno</code> files generated when <code>gcc</code> is run with <code>-ftest-coverage</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/JavaRuntimeInfo.mdx b/rules/lib/providers/JavaRuntimeInfo.mdx new file mode 100644 index 0000000..1d63277 --- /dev/null +++ b/rules/lib/providers/JavaRuntimeInfo.mdx @@ -0,0 +1,119 @@ +--- +title: 'JavaRuntimeInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.JavaRuntimeInfo">JavaRuntimeInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaRuntimeInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Information about the Java runtime being used. + +<h2>Members</h2> +<ul> + <li> + <a href="#default_cds">default_cds</a> + </li> + <li> + <a href="#files">files</a> + </li> + <li> + <a href="#hermetic_files">hermetic_files</a> + </li> + <li> + <a href="#hermetic_static_libs">hermetic_static_libs</a> + </li> + <li> + <a href="#java_executable_exec_path">java_executable_exec_path</a> + </li> + <li> + <a href="#java_executable_runfiles_path">java_executable_runfiles_path</a> + </li> + <li> + <a href="#java_home">java_home</a> + </li> + <li> + <a href="#java_home_runfiles_path">java_home_runfiles_path</a> + </li> + <li> + <a href="#lib_ct_sym">lib_ct_sym</a> + </li> + <li> + <a href="#lib_modules">lib_modules</a> + </li> + <li> + <a href="#version">version</a> + </li> + </ul> + + <h2 id="default_cds">default_cds</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> JavaRuntimeInfo.default_cds</pre></p> + + Returns the JDK default CDS archive. + May return <code>None</code>. + + <h2 id="files">files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaRuntimeInfo.files</pre></p> + + Returns the files in the Java runtime. + + <h2 id="hermetic_files">hermetic_files</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaRuntimeInfo.hermetic_files</pre></p> + + Returns the files in the Java runtime needed for hermetic deployments. + + <h2 id="hermetic_static_libs">hermetic_static_libs</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> JavaRuntimeInfo.hermetic_static_libs</pre></p> + + Returns the JDK static libraries. + + <h2 id="java_executable_exec_path">java_executable_exec_path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaRuntimeInfo.java_executable_exec_path</pre></p> + + Returns the execpath of the Java executable. + + <h2 id="java_executable_runfiles_path">java_executable_runfiles_path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaRuntimeInfo.java_executable_runfiles_path</pre></p> + + Returns the path of the Java executable in runfiles trees. This should only be used when one needs to access the JVM during the execution of a binary or a test built by Bazel. In particular, when one needs to invoke the JVM during an action, java_executable_exec_path should be used instead. + + <h2 id="java_home">java_home</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaRuntimeInfo.java_home</pre></p> + + Returns the execpath of the root of the Java installation. + + <h2 id="java_home_runfiles_path">java_home_runfiles_path</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaRuntimeInfo.java_home_runfiles_path</pre></p> + + Returns the path of the Java installation in runfiles trees. This should only be used when one needs to access the JDK during the execution of a binary or a test built by Bazel. In particular, when one needs the JDK during an action, java_home should be used instead. + + <h2 id="lib_ct_sym">lib_ct_sym</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> JavaRuntimeInfo.lib_ct_sym</pre></p> + + Returns the lib/ct.sym file. + May return <code>None</code>. + + <h2 id="lib_modules">lib_modules</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> JavaRuntimeInfo.lib_modules</pre></p> + + Returns the lib/modules file. + May return <code>None</code>. + + <h2 id="version">version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> JavaRuntimeInfo.version</pre></p> + + The Java feature version of the runtime. This is 0 if the version is unknown. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/JavaToolchainInfo.mdx b/rules/lib/providers/JavaToolchainInfo.mdx new file mode 100644 index 0000000..969e061 --- /dev/null +++ b/rules/lib/providers/JavaToolchainInfo.mdx @@ -0,0 +1,118 @@ +--- +title: 'JavaToolchainInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.JavaToolchainInfo">JavaToolchainInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaToolchainStarlarkApiProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Provides access to information about the Java toolchain rule. Accessible as a 'java_toolchain' field on a Target struct. + +<h2>Members</h2> +<ul> + <li> + <a href="#bootclasspath">bootclasspath</a> + </li> + <li> + <a href="#ijar">ijar</a> + </li> + <li> + <a href="#jacocorunner">jacocorunner</a> + </li> + <li> + <a href="#java_runtime">java_runtime</a> + </li> + <li> + <a href="#jvm_opt">jvm_opt</a> + </li> + <li> + <a href="#label">label</a> + </li> + <li> + <a href="#proguard_allowlister">proguard_allowlister</a> + </li> + <li> + <a href="#single_jar">single_jar</a> + </li> + <li> + <a href="#source_version">source_version</a> + </li> + <li> + <a href="#target_version">target_version</a> + </li> + <li> + <a href="#tools">tools</a> + </li> + </ul> + + <h2 id="bootclasspath">bootclasspath</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaToolchainInfo.bootclasspath</pre></p> + + The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. + + <h2 id="ijar">ijar</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> JavaToolchainInfo.ijar</pre></p> + + A FilesToRunProvider representing the ijar executable. + + <h2 id="jacocorunner">jacocorunner</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> JavaToolchainInfo.jacocorunner</pre></p> + + The jacocorunner used by the toolchain. + May return <code>None</code>. + + <h2 id="java_runtime">java_runtime</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/JavaRuntimeInfo.html">JavaRuntimeInfo</a> JavaToolchainInfo.java_runtime</pre></p> + + The java runtime information. + + <h2 id="jvm_opt">jvm_opt</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaToolchainInfo.jvm_opt</pre></p> + + The default options for the JVM running the java compiler and associated tools. + + <h2 id="label">label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> JavaToolchainInfo.label</pre></p> + + The toolchain label. + + <h2 id="proguard_allowlister">proguard_allowlister</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> JavaToolchainInfo.proguard_allowlister</pre></p> + + Return the binary to validate proguard configuration + May return <code>None</code>. + + <h2 id="single_jar">single_jar</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> JavaToolchainInfo.single_jar</pre></p> + + The SingleJar deploy jar. + + <h2 id="source_version">source_version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaToolchainInfo.source_version</pre></p> + + The java source version. + + <h2 id="target_version">target_version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaToolchainInfo.target_version</pre></p> + + The java target version. + + <h2 id="tools">tools</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaToolchainInfo.tools</pre></p> + + The compilation tools. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/MaterializedDepsInfo.mdx b/rules/lib/providers/MaterializedDepsInfo.mdx new file mode 100644 index 0000000..71dab22 --- /dev/null +++ b/rules/lib/providers/MaterializedDepsInfo.mdx @@ -0,0 +1,36 @@ +--- +title: 'MaterializedDepsInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.MaterializedDepsInfo">MaterializedDepsInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/MaterializedDepsInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +The provider returned from materializer rules to materialize dependencies. + +<h2>Members</h2> +<ul> + <li> + <a href="#deps">deps</a> + </li> + </ul> + + <h2 id="deps">deps</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> MaterializedDepsInfo.deps</pre></p> + + The list of dependencies. These may be ConfiguredTarget or DormantDependency objects. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/ObjcProvider.mdx b/rules/lib/providers/ObjcProvider.mdx new file mode 100644 index 0000000..9f19344 --- /dev/null +++ b/rules/lib/providers/ObjcProvider.mdx @@ -0,0 +1,84 @@ +--- +title: 'ObjcProvider' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ObjcProvider">ObjcProvider</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/ObjcProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A provider for compilation and linking of objc. + +<h2>Members</h2> +<ul> + <li> + <a href="#direct_module_maps">direct_module_maps</a> + </li> + <li> + <a href="#direct_sources">direct_sources</a> + </li> + <li> + <a href="#j2objc_library">j2objc_library</a> + </li> + <li> + <a href="#module_map">module_map</a> + </li> + <li> + <a href="#source">source</a> + </li> + <li> + <a href="#strict_include">strict_include</a> + </li> + <li> + <a href="#umbrella_header">umbrella_header</a> + </li> + </ul> + + <h2 id="direct_module_maps">direct_module_maps</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> ObjcProvider.direct_module_maps</pre></p> + + Module map files from this target directly (no transitive module maps). Used to enforce proper use of private header files and for Swift compilation. + + <h2 id="direct_sources">direct_sources</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> ObjcProvider.direct_sources</pre></p> + + All direct source files from this target (no transitive files), including any headers in the 'srcs' attribute. + + <h2 id="j2objc_library">j2objc_library</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.j2objc_library</pre></p> + + Static libraries that are built from J2ObjC-translated Java code. + + <h2 id="module_map">module_map</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.module_map</pre></p> + + Clang module maps, used to enforce proper use of private header files. + + <h2 id="source">source</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.source</pre></p> + + All transitive source files. + + <h2 id="strict_include">strict_include</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.strict_include</pre></p> + + Non-propagated include search paths specified with '-I' on the command line. Also known as header search paths (and distinct from <em>user</em> header search paths). + + <h2 id="umbrella_header">umbrella_header</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.umbrella_header</pre></p> + + Clang umbrella header. Public headers are #included in umbrella headers to be compatible with J2ObjC segmented headers. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/OutputGroupInfo.mdx b/rules/lib/providers/OutputGroupInfo.mdx new file mode 100644 index 0000000..5d7c1de --- /dev/null +++ b/rules/lib/providers/OutputGroupInfo.mdx @@ -0,0 +1,62 @@ +--- +title: 'OutputGroupInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.OutputGroupInfo">OutputGroupInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/OutputGroupInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A provider that indicates what output groups a rule has.<br>See <a href="https://bazel.build/extending/rules#requesting_output_files">Requesting output files</a> for more information. + +<h2>Members</h2> +<ul> + <li> + <a href="#OutputGroupInfo">OutputGroupInfo</a> + </li> + </ul> + + <h2 id="OutputGroupInfo">OutputGroupInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/OutputGroupInfo.html">OutputGroupInfo</a> OutputGroupInfo(**kwargs)</pre></p> + + Instantiate this provider with <br><pre class=language-python>OutputGroupInfo(group1 = <files>, group2 = <files>...)</pre>See <a href="https://bazel.build/extending/rules#requesting_output_files">Requesting output files </a> for more information. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="OutputGroupInfo.kwargs"> + <code>kwargs</code> + </td> + <td> + default is <code>{}</code><br/> + Dictionary of arguments. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/PackageSpecificationInfo.mdx b/rules/lib/providers/PackageSpecificationInfo.mdx new file mode 100644 index 0000000..d2437e4 --- /dev/null +++ b/rules/lib/providers/PackageSpecificationInfo.mdx @@ -0,0 +1,63 @@ +--- +title: 'PackageSpecificationInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.PackageSpecificationInfo">PackageSpecificationInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/PackageSpecificationProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Information about transitive package specifications used in package groups. + +<h2>Members</h2> +<ul> + <li> + <a href="#contains">contains</a> + </li> + </ul> + + <h2 id="contains">contains</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> PackageSpecificationInfo.contains(target)</pre></p> + + Checks if a target exists in a package group. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="contains.target"> + <code>target</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; + required<br/> + A target which is checked if it exists inside the package group. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/PlatformInfo.mdx b/rules/lib/providers/PlatformInfo.mdx new file mode 100644 index 0000000..27aaf6b --- /dev/null +++ b/rules/lib/providers/PlatformInfo.mdx @@ -0,0 +1,25 @@ +--- +title: 'PlatformInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.PlatformInfo">PlatformInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Provides access to data about a specific platform. See <a href='/docs/platforms#constraints-platforms'>Defining Constraints and Platforms</a> for more information.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/RunEnvironmentInfo.mdx b/rules/lib/providers/RunEnvironmentInfo.mdx new file mode 100644 index 0000000..6df0bd6 --- /dev/null +++ b/rules/lib/providers/RunEnvironmentInfo.mdx @@ -0,0 +1,44 @@ +--- +title: 'RunEnvironmentInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.RunEnvironmentInfo">RunEnvironmentInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunEnvironmentInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A provider that can be returned from executable rules to control the environment in which their executable is executed. + +<h2>Members</h2> +<ul> + <li> + <a href="#environment">environment</a> + </li> + <li> + <a href="#inherited_environment">inherited_environment</a> + </li> + </ul> + + <h2 id="environment">environment</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> RunEnvironmentInfo.environment</pre></p> + + A map of string keys and values that represent environment variables and their values. These will be made available when the target that returns this provider is executed, either as a test or via the run command. + + <h2 id="inherited_environment">inherited_environment</h2> + <p><pre class="rule-signature">List RunEnvironmentInfo.inherited_environment</pre></p> + + A sequence of names of environment variables. These variables are made available with their current value taken from the shell environment when the target that returns this provider is executed, either as a test or via the run command. If a variable is contained in both <code>environment</code> and <code>inherited_environment</code>, the value inherited from the shell environment will take precedence if set. This is most useful for test rules, which run with a hermetic environment under <code>bazel test</code> and can use this mechanism to non-hermetically include a variable from the outer environment. By contrast, <code>bazel run</code> already forwards the outer environment. Note, though, that it may be surprising for an otherwise hermetic test to hardcode a non-hermetic dependency on the environment, and that this may even accidentally expose sensitive information. Prefer setting the test environment explicitly with the <code>--test_env</code> flag, and even then prefer to avoid using this flag and instead populate the environment explicitly. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/TemplateVariableInfo.mdx b/rules/lib/providers/TemplateVariableInfo.mdx new file mode 100644 index 0000000..d603e39 --- /dev/null +++ b/rules/lib/providers/TemplateVariableInfo.mdx @@ -0,0 +1,36 @@ +--- +title: 'TemplateVariableInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.TemplateVariableInfo">TemplateVariableInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateVariableInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Encapsulates template variables, that is, variables that can be referenced by strings like <code>$(VARIABLE)</code> in BUILD files and expanded by <code>ctx.expand_make_variables</code> and implicitly in certain attributes of built-in rules.</p><p><code>TemplateVariableInfo</code> can be created by calling its eponymous constructor with a string-to-string dict as an argument that specifies the variables provided.</p><p>Example: <code>platform_common.TemplateVariableInfo({'FOO': 'bar'})</code></p> + +<h2>Members</h2> +<ul> + <li> + <a href="#variables">variables</a> + </li> + </ul> + + <h2 id="variables">variables</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> TemplateVariableInfo.variables</pre></p> + + Returns the make variables defined by this target as a dictionary with string keys and string values + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/ToolchainInfo.mdx b/rules/lib/providers/ToolchainInfo.mdx new file mode 100644 index 0000000..67dc9c5 --- /dev/null +++ b/rules/lib/providers/ToolchainInfo.mdx @@ -0,0 +1,25 @@ +--- +title: 'ToolchainInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ToolchainInfo">ToolchainInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Provider returned by <a href="/docs/toolchains#defining-toolchains">toolchain rules</a> to share data with <a href="/docs/toolchains#writing-rules-that-use-toolchains">rules which depend on toolchains</a>. Read about <a href='/docs/toolchains'>toolchains</a> for more information. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/ToolchainTypeInfo.mdx b/rules/lib/providers/ToolchainTypeInfo.mdx new file mode 100644 index 0000000..a03d6b4 --- /dev/null +++ b/rules/lib/providers/ToolchainTypeInfo.mdx @@ -0,0 +1,36 @@ +--- +title: 'ToolchainTypeInfo' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.ToolchainTypeInfo">ToolchainTypeInfo</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainTypeInfoApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Provides access to data about a specific toolchain type. <br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> + +<h2>Members</h2> +<ul> + <li> + <a href="#type_label">type_label</a> + </li> + </ul> + + <h2 id="type_label">type_label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> ToolchainTypeInfo.type_label</pre></p> + + The label uniquely identifying this toolchain type. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/file_provider.mdx b/rules/lib/providers/file_provider.mdx new file mode 100644 index 0000000..61c05f6 --- /dev/null +++ b/rules/lib/providers/file_provider.mdx @@ -0,0 +1,25 @@ +--- +title: 'file_provider' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.file_provider">file_provider</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +An interface for rules that provide files. + + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/java_compilation_info.mdx b/rules/lib/providers/java_compilation_info.mdx new file mode 100644 index 0000000..01961c0 --- /dev/null +++ b/rules/lib/providers/java_compilation_info.mdx @@ -0,0 +1,60 @@ +--- +title: 'java_compilation_info' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.java_compilation_info">java_compilation_info</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCompilationInfoProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Provides access to compilation information for Java rules. + +<h2>Members</h2> +<ul> + <li> + <a href="#boot_classpath">boot_classpath</a> + </li> + <li> + <a href="#compilation_classpath">compilation_classpath</a> + </li> + <li> + <a href="#javac_options">javac_options</a> + </li> + <li> + <a href="#runtime_classpath">runtime_classpath</a> + </li> + </ul> + + <h2 id="boot_classpath">boot_classpath</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java_compilation_info.boot_classpath</pre></p> + + Boot classpath for this Java target. + + <h2 id="compilation_classpath">compilation_classpath</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_compilation_info.compilation_classpath</pre></p> + + Compilation classpath for this Java target. + + <h2 id="javac_options">javac_options</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_compilation_info.javac_options</pre></p> + + A depset of options to java compiler. To get the exact list of options passed to javac in the correct order, use the tokenize_javacopts utility in rules_java + + <h2 id="runtime_classpath">runtime_classpath</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_compilation_info.runtime_classpath</pre></p> + + Run-time classpath for this Java target. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/providers/java_output_jars.mdx b/rules/lib/providers/java_output_jars.mdx new file mode 100644 index 0000000..3074340 --- /dev/null +++ b/rules/lib/providers/java_output_jars.mdx @@ -0,0 +1,54 @@ +--- +title: 'java_output_jars' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.java_output_jars">java_output_jars</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaRuleOutputJarsProviderApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Information about outputs of a Java rule. Deprecated: use java_info.java_outputs. + +<h2>Members</h2> +<ul> + <li> + <a href="#jars">jars</a> + </li> + <li> + <a href="#jdeps">jdeps</a> + </li> + <li> + <a href="#native_headers">native_headers</a> + </li> + </ul> + + <h2 id="jars">jars</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java_output_jars.jars</pre></p> + + Returns information about outputs of this Java/Java-like target. Deprecated: Use java_info.java_outputs. + + <h2 id="jdeps">jdeps</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_output_jars.jdeps</pre></p> + + A manifest proto file. The protobuf file containing the manifest generated from JavaBuilder. This function returns a value when exactly one manifest proto file is present in the outputs. Deprecated: Use java_info.java_outputs[i].jdeps. + May return <code>None</code>. + + <h2 id="native_headers">native_headers</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_output_jars.native_headers</pre></p> + + A jar containing CC header files supporting native method implementation. This function returns a value when exactly one native headers jar file is present in the outputs. Deprecated: Use java_info.java_outputs[i].native_headers_jar. + May return <code>None</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel.mdx b/rules/lib/toplevel.mdx new file mode 100644 index 0000000..b0cc8ce --- /dev/null +++ b/rules/lib/toplevel.mdx @@ -0,0 +1,42 @@ +--- +title: 'toplevel' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> +<h1 class="page-title">Top-level Modules</h1> + +{% dynamic setvar source_file "NONE" %} +{% include "_buttons.html" %} +This section lists top-level modules. These symbols are available only in .bzl files. + +<ul> + +<li><a href="/rules/lib/toplevel/apple_common">apple_common</a></li> + +<li><a href="/rules/lib/toplevel/attr">attr</a></li> + +<li><a href="/rules/lib/toplevel/cc_common">cc_common</a></li> + +<li><a href="/rules/lib/toplevel/config">config</a></li> + +<li><a href="/rules/lib/toplevel/config_common">config_common</a></li> + +<li><a href="/rules/lib/toplevel/coverage_common">coverage_common</a></li> + +<li><a href="/rules/lib/toplevel/java_common">java_common</a></li> + +<li><a href="/rules/lib/toplevel/native">native</a></li> + +<li><a href="/rules/lib/toplevel/platform_common">platform_common</a></li> + +<li><a href="/rules/lib/toplevel/proto">proto</a></li> + +<li><a href="/rules/lib/toplevel/testing">testing</a></li> +</ul> +</body> +</html> diff --git a/rules/lib/toplevel/apple_common.mdx b/rules/lib/toplevel/apple_common.mdx new file mode 100644 index 0000000..d6cb53e --- /dev/null +++ b/rules/lib/toplevel/apple_common.mdx @@ -0,0 +1,185 @@ +--- +title: 'apple_common' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.apple_common">apple_common</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Functions for Starlark to access internals of the apple rule implementations. + +<h2>Members</h2> +<ul> + <li> + <a href="#apple_host_system_env">apple_host_system_env</a> + </li> + <li> + <a href="#apple_toolchain">apple_toolchain</a> + </li> + <li> + <a href="#dotted_version">dotted_version</a> + </li> + <li> + <a href="#platform">platform</a> + </li> + <li> + <a href="#platform_type">platform_type</a> + </li> + <li> + <a href="#target_apple_env">target_apple_env</a> + </li> + <li> + <a href="#XcodeProperties">XcodeProperties</a> + </li> + <li> + <a href="#XcodeVersionConfig">XcodeVersionConfig</a> + </li> + </ul> + + <h2 id="apple_host_system_env">apple_host_system_env</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> apple_common.apple_host_system_env(xcode_config)</pre></p> + + Returns a <a href='../core/dict.html'>dict</a> of environment variables that should be set for actions that need to run build tools on an Apple host system, such as the version of Xcode that should be used. The keys are variable names and the values are their corresponding values. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="apple_host_system_env.xcode_config"> + <code>xcode_config</code> + </td> + <td> + required<br/> + A provider containing information about the Xcode configuration. + </td> + </tr> + </tbody> + </table> + + <h2 id="apple_toolchain">apple_toolchain</h2> + <p><pre class="rule-signature">unknown apple_common.apple_toolchain()</pre></p> + + Utilities for resolving items from the apple toolchain. + + <h2 id="dotted_version">dotted_version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/DottedVersion.html">DottedVersion</a> apple_common.dotted_version(version)</pre></p> + + Creates a new <a href="../builtins/DottedVersion.html">DottedVersion</a> instance. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="dotted_version.version"> + <code>version</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The string representation of the DottedVersion. + </td> + </tr> + </tbody> + </table> + + <h2 id="platform">platform</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> apple_common.platform</pre></p> + + An enum-like struct that contains the following fields corresponding to Apple platforms:<br><ul><li><code>ios_device</code></li><li><code>ios_simulator</code></li><li><code>macos</code></li><li><code>tvos_device</code></li><li><code>tvos_simulator</code></li><li><code>visionos_device</code></li><li><code>visionos_simulator</code></li><li><code>watchos_device</code></li><li><code>watchos_simulator</code></li></ul><p>These values can be passed to methods that expect a platform, like <a href='../providers/XcodeVersionConfig.html#sdk_version_for_platform'>XcodeVersionConfig.sdk_version_for_platform</a>. + + <h2 id="platform_type">platform_type</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> apple_common.platform_type</pre></p> + + An enum-like struct that contains the following fields corresponding to Apple platform types:<br><ul><li><code>ios</code></li><li><code>macos</code></li><li><code>tvos</code></li><li><code>visionos</code></li><li><code>watchos</code></li></ul><p>These values can be passed to methods that expect a platform type, like the 'apple' configuration fragment's <a href='../fragments/apple.html#multi_arch_platform'>multi_arch_platform</a> method.<p>Example:<p><pre class='language-python'> +ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios) +</pre> + + <h2 id="target_apple_env">target_apple_env</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> apple_common.target_apple_env(xcode_config, platform)</pre></p> + + Returns a <code>dict</code> of environment variables that should be set for actions that build targets of the given Apple platform type. For example, this dictionary contains variables that denote the platform name and SDK version with which to build. The keys are variable names and the values are their corresponding values. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="target_apple_env.xcode_config"> + <code>xcode_config</code> + </td> + <td> + required<br/> + A provider containing information about the Xcode configuration. + </td> + </tr> + <tr> + <td id="target_apple_env.platform"> + <code>platform</code> + </td> + <td> + required<br/> + The apple platform. + </td> + </tr> + </tbody> + </table> + + <h2 id="XcodeProperties">XcodeProperties</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> apple_common.XcodeProperties</pre></p> + + The constructor/key for the <code>XcodeVersionProperties</code> provider.<p>If a target propagates the <code>XcodeVersionProperties</code> provider, use this as the key with which to retrieve it. Example:<br><pre class='language-python'> +dep = ctx.attr.deps[0] +p = dep[apple_common.XcodeVersionProperties] +</pre> + + <h2 id="XcodeVersionConfig">XcodeVersionConfig</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> apple_common.XcodeVersionConfig</pre></p> + + The constructor/key for the <code>XcodeVersionConfig</code> provider. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/attr.mdx b/rules/lib/toplevel/attr.mdx new file mode 100644 index 0000000..87bef4a --- /dev/null +++ b/rules/lib/toplevel/attr.mdx @@ -0,0 +1,1276 @@ +--- +title: 'attr' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.attr">attr</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +This is a top-level module for defining the attribute schemas of a rule or aspect. Each function returns an object representing the schema of a single attribute. These objects are used as the values of the <code>attrs</code> dictionary argument of <a href="../globals/bzl.html#rule"><code>rule()</code></a>, <a href="../globals/bzl.html#aspect"><code>aspect()</code></a>, <a href="../globals/bzl.html#repository_rule"><code>repository_rule()</code></a> and <a href="../globals/bzl.html#tag_class"><code>tag_class()</code></a>. <p>See the Rules page for more on <a href="https://bazel.build/extending/rules#attributes">defining</a> +and <a href="https://bazel.build/extending/rules#implementation_function">using</a> attributes.</p> + + +<h2>Members</h2> +<ul> + <li> + <a href="#bool">bool</a> + </li> + <li> + <a href="#int">int</a> + </li> + <li> + <a href="#int_list">int_list</a> + </li> + <li> + <a href="#label">label</a> + </li> + <li> + <a href="#label_keyed_string_dict">label_keyed_string_dict</a> + </li> + <li> + <a href="#label_list">label_list</a> + </li> + <li> + <a href="#output">output</a> + </li> + <li> + <a href="#output_list">output_list</a> + </li> + <li> + <a href="#string">string</a> + </li> + <li> + <a href="#string_dict">string_dict</a> + </li> + <li> + <a href="#string_keyed_label_dict">string_keyed_label_dict</a> + </li> + <li> + <a href="#string_list">string_list</a> + </li> + <li> + <a href="#string_list_dict">string_list_dict</a> + </li> + </ul> + + <h2 id="bool">bool</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.bool(*, configurable=unbound, default=False, doc=None, mandatory=False)</pre></p> + + Creates a schema for a boolean attribute. The corresponding <a href='../builtins/ctx.html#attr'><code>ctx.attr</code></a> attribute will be of type <a href='../core/bool.html'><code>bool</code></a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="bool.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="bool.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule. + </td> + </tr> + <tr> + <td id="bool.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="bool.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + </tbody> + </table> + + <h2 id="int">int</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.int(*, configurable=unbound, default=0, doc=None, mandatory=False, values=[])</pre></p> + + Creates a schema for an integer attribute. The value must be in the signed 32-bit range. The corresponding <a href='../builtins/ctx.html#attr'><code>ctx.attr</code></a> attribute will be of type <a href='../core/int.html'><code>int</code></a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="int.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="int.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>0</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule. + </td> + </tr> + <tr> + <td id="int.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="int.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + <tr> + <td id="int.values"> + <code>values</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/int.html">int</a>s; + default is <code>[]</code><br/> + The list of allowed values for the attribute. An error is raised if any other value is given. + </td> + </tr> + </tbody> + </table> + + <h2 id="int_list">int_list</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.int_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None)</pre></p> + + Creates a schema for a list-of-integers attribute. Each element must be in the signed 32-bit range. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="int_list.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + <tr> + <td id="int_list.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True if the attribute can be empty. + </td> + </tr> + <tr> + <td id="int_list.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="int_list.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/int.html">int</a>s; + default is <code>[]</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule. + </td> + </tr> + <tr> + <td id="int_list.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + </tbody> + </table> + + <h2 id="label">label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.label(*, configurable=unbound, default=None, materializer=None, doc=None, executable=False, allow_files=None, allow_single_file=None, mandatory=False, skip_validations=False, providers=[], for_dependency_resolution=unbound, allow_rules=None, cfg=None, aspects=[], flags=[])</pre></p> + + <p>Creates a schema for a label attribute. This is a dependency attribute.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time (within the rule's implementation function), when retrieving the attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access the providers of the current target's dependencies.<p>In addition to ordinary source files, this kind of attribute is often used to refer to a tool -- for example, a compiler. Such tools are considered to be dependencies, just like source files. To avoid requiring users to specify the tool's label every time they use the rule in their BUILD files, you can hard-code the label of a canonical tool as the <code>default</code> value of this attribute. If you also want to prevent users from overriding this default, you can make the attribute private by giving it a name that starts with an underscore. See the <a href='https://bazel.build/extending/rules#private-attributes'>Rules</a> page for more information. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="label.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="label.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/LateBoundDefault.html">LateBoundDefault</a>; or NativeComputedDefault; or <a class="anchor" href="../core/function.html">function</a>; or <code>None</code>; + default is <code>None</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify a default value, for example, <code>attr.label(default = "//a:b")</code>. + </td> + </tr> + <tr> + <td id="label.materializer"> + <code>materializer</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + default is <code>None</code><br/> + <b>Experimental</b>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_dormant_deps</code> <br>If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute + </td> + </tr> + <tr> + <td id="label.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="label.executable"> + <code>executable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + True if the dependency has to be executable. This means the label must refer to an executable file, or to a rule that outputs an executable file. Access the label with <code>ctx.executable.<attribute_name></code>. + </td> + </tr> + <tr> + <td id="label.allow_files"> + <code>allow_files</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>). + </td> + </tr> + <tr> + <td id="label.allow_single_file"> + <code>allow_single_file</code> + </td> + <td> + default is <code>None</code><br/> + This is similar to <code>allow_files</code>, with the restriction that the label must correspond to a single <a href="../builtins/File.html">File</a>. Access it through <code>ctx.file.<attribute_name></code>. + </td> + </tr> + <tr> + <td id="label.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + <tr> + <td id="label.skip_validations"> + <code>skip_validations</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. + </td> + </tr> + <tr> + <td id="label.providers"> + <code>providers</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + The providers that must be given by any dependency appearing in this attribute.<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice. + </td> + </tr> + <tr> + <td id="label.for_dependency_resolution"> + <code>for_dependency_resolution</code> + </td> + <td> + default is <code>unbound</code><br/> + If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. + </td> + </tr> + <tr> + <td id="label.allow_rules"> + <code>allow_rules</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. + </td> + </tr> + <tr> + <td id="label.cfg"> + <code>cfg</code> + </td> + <td> + default is <code>None</code><br/> + <a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. This parameter is required if <code>executable</code> is True to guard against accidentally building host tools in the target configuration. <code>"target"</code> has no semantic effect, so don't set it when <code>executable</code> is False unless it really helps clarify your intentions. + </td> + </tr> + <tr> + <td id="label.aspects"> + <code>aspects</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; + default is <code>[]</code><br/> + Aspects that should be applied to the dependency or dependencies specified by this attribute. + </td> + </tr> + <tr> + <td id="label.flags"> + <code>flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Deprecated, will be removed. + </td> + </tr> + </tbody> + </table> + + <h2 id="label_keyed_string_dict">label_keyed_string_dict</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.label_keyed_string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[])</pre></p> + + <p>Creates a schema for an attribute holding a dictionary, where the keys are labels and the values are strings. This is a dependency attribute.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time (within the rule's implementation function), when retrieving the attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access the providers of the current target's dependencies. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="label_keyed_string_dict.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True if the attribute can be empty. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <a class="anchor" href="../core/function.html">function</a>; + default is <code>{}</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"})</code>. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.allow_files"> + <code>allow_files</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>). + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.allow_rules"> + <code>allow_rules</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.providers"> + <code>providers</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + The providers that must be given by any dependency appearing in this attribute.<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.for_dependency_resolution"> + <code>for_dependency_resolution</code> + </td> + <td> + default is <code>unbound</code><br/> + If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.flags"> + <code>flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Deprecated, will be removed. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.skip_validations"> + <code>skip_validations</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.cfg"> + <code>cfg</code> + </td> + <td> + default is <code>None</code><br/> + <a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. + </td> + </tr> + <tr> + <td id="label_keyed_string_dict.aspects"> + <code>aspects</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; + default is <code>[]</code><br/> + Aspects that should be applied to the dependency or dependencies specified by this attribute. + </td> + </tr> + </tbody> + </table> + + <h2 id="label_list">label_list</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.label_list(allow_empty=True, *, configurable=unbound, default=[], materializer=None, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[])</pre></p> + + <p>Creates a schema for a list-of-labels attribute. This is a dependency attribute. The corresponding <a href='../builtins/ctx.html#attr'><code>ctx.attr</code></a> attribute will be of type <a href='../core/list.html'>list</a> of <a href='../builtins/Target.html'><code>Target</code>s</a>.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time (within the rule's implementation function), when retrieving the attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access the providers of the current target's dependencies. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="label_list.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True if the attribute can be empty. + </td> + </tr> + <tr> + <td id="label_list.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="label_list.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Label.html">Label</a>s; or <a class="anchor" href="../core/function.html">function</a>; + default is <code>[]</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.label_list(default = ["//a:b", "//a:c"])</code>. + </td> + </tr> + <tr> + <td id="label_list.materializer"> + <code>materializer</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + default is <code>None</code><br/> + <b>Experimental</b>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_dormant_deps</code> <br>If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute + </td> + </tr> + <tr> + <td id="label_list.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="label_list.allow_files"> + <code>allow_files</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>). + </td> + </tr> + <tr> + <td id="label_list.allow_rules"> + <code>allow_rules</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. + </td> + </tr> + <tr> + <td id="label_list.providers"> + <code>providers</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + The providers that must be given by any dependency appearing in this attribute.<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice. + </td> + </tr> + <tr> + <td id="label_list.for_dependency_resolution"> + <code>for_dependency_resolution</code> + </td> + <td> + default is <code>unbound</code><br/> + If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. + </td> + </tr> + <tr> + <td id="label_list.flags"> + <code>flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Deprecated, will be removed. + </td> + </tr> + <tr> + <td id="label_list.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + <tr> + <td id="label_list.skip_validations"> + <code>skip_validations</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. + </td> + </tr> + <tr> + <td id="label_list.cfg"> + <code>cfg</code> + </td> + <td> + default is <code>None</code><br/> + <a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. + </td> + </tr> + <tr> + <td id="label_list.aspects"> + <code>aspects</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; + default is <code>[]</code><br/> + Aspects that should be applied to the dependency or dependencies specified by this attribute. + </td> + </tr> + </tbody> + </table> + + <h2 id="output">output</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.output(*, doc=None, mandatory=False)</pre></p> + + <p>Creates a schema for an output (label) attribute.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time, the corresponding <a href='../builtins/File.html'><code>File</code></a> can be retrieved using <a href='../builtins/ctx.html#outputs'><code>ctx.outputs</code></a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="output.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="output.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + </tbody> + </table> + + <h2 id="output_list">output_list</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.output_list(allow_empty=True, *, doc=None, mandatory=False)</pre></p> + + Creates a schema for a list-of-outputs attribute.<p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time, the corresponding <a href='../builtins/File.html'><code>File</code></a> can be retrieved using <a href='../builtins/ctx.html#outputs'><code>ctx.outputs</code></a>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="output_list.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True if the attribute can be empty. + </td> + </tr> + <tr> + <td id="output_list.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="output_list.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + </tbody> + </table> + + <h2 id="string">string</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string(*, configurable=unbound, default='', doc=None, mandatory=False, values=[])</pre></p> + + Creates a schema for a <a href='../core/string.html#attr'>string</a> attribute. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="string.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="string.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or NativeComputedDefault; + default is <code>''</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule. + </td> + </tr> + <tr> + <td id="string.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="string.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + <tr> + <td id="string.values"> + <code>values</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + The list of allowed values for the attribute. An error is raised if any other value is given. + </td> + </tr> + </tbody> + </table> + + <h2 id="string_dict">string_dict</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False)</pre></p> + + Creates a schema for an attribute holding a dictionary, where the keys and values are strings. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="string_dict.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True if the attribute can be empty. + </td> + </tr> + <tr> + <td id="string_dict.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="string_dict.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule. + </td> + </tr> + <tr> + <td id="string_dict.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="string_dict.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + </tbody> + </table> + + <h2 id="string_keyed_label_dict">string_keyed_label_dict</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string_keyed_label_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, cfg=None, aspects=[])</pre></p> + + <p>Creates a schema for an attribute whose value is a dictionary where the keys are strings and the values are labels. This is a dependency attribute.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time (within the rule's implementation function), when retrieving the attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access the providers of the current target's dependencies. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="string_keyed_label_dict.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True if the attribute can be empty. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; or <a class="anchor" href="../core/function.html">function</a>; + default is <code>{}</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.string_keyed_label_dict(default = {"foo": "//a:b", "bar": "//a:c"})</code>. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.allow_files"> + <code>allow_files</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>). + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.allow_rules"> + <code>allow_rules</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.providers"> + <code>providers</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + The providers that must be given by any dependency appearing in this attribute.<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.for_dependency_resolution"> + <code>for_dependency_resolution</code> + </td> + <td> + default is <code>unbound</code><br/> + If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.flags"> + <code>flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Deprecated, will be removed. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.cfg"> + <code>cfg</code> + </td> + <td> + default is <code>None</code><br/> + <a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. + </td> + </tr> + <tr> + <td id="string_keyed_label_dict.aspects"> + <code>aspects</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; + default is <code>[]</code><br/> + Aspects that should be applied to the dependency or dependencies specified by this attribute. + </td> + </tr> + </tbody> + </table> + + <h2 id="string_list">string_list</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None)</pre></p> + + Creates a schema for a list-of-strings attribute. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="string_list.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + <tr> + <td id="string_list.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True if the attribute can be empty. + </td> + </tr> + <tr> + <td id="string_list.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="string_list.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or NativeComputedDefault; + default is <code>[]</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule. + </td> + </tr> + <tr> + <td id="string_list.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + </tbody> + </table> + + <h2 id="string_list_dict">string_list_dict</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string_list_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False)</pre></p> + + Creates a schema for an attribute holding a dictionary, where the keys are strings and the values are lists of strings. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="string_list_dict.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True if the attribute can be empty. + </td> + </tr> + <tr> + <td id="string_list_dict.configurable"> + <code>configurable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; or unbound; + default is <code>unbound</code><br/> + This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. + </td> + </tr> + <tr> + <td id="string_list_dict.default"> + <code>default</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + A default value to use if no value for this attribute is given when instantiating the rule. + </td> + </tr> + <tr> + <td id="string_list_dict.doc"> + <code>doc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + A description of the attribute that can be extracted by documentation generating tools. + </td> + </tr> + <tr> + <td id="string_list_dict.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If true, the value must be specified explicitly (even if it has a <code>default</code>). + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/cc_common.mdx b/rules/lib/toplevel/cc_common.mdx new file mode 100644 index 0000000..0f63f0d --- /dev/null +++ b/rules/lib/toplevel/cc_common.mdx @@ -0,0 +1,2022 @@ +--- +title: 'cc_common' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.cc_common">cc_common</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcModuleApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Utilities for C++ compilation, linking, and command line generation. + +<h2>Members</h2> +<ul> + <li> + <a href="#action_is_enabled">action_is_enabled</a> + </li> + <li> + <a href="#CcToolchainInfo">CcToolchainInfo</a> + </li> + <li> + <a href="#compile">compile</a> + </li> + <li> + <a href="#configure_features">configure_features</a> + </li> + <li> + <a href="#create_cc_toolchain_config_info">create_cc_toolchain_config_info</a> + </li> + <li> + <a href="#create_compilation_context">create_compilation_context</a> + </li> + <li> + <a href="#create_compilation_outputs">create_compilation_outputs</a> + </li> + <li> + <a href="#create_compile_variables">create_compile_variables</a> + </li> + <li> + <a href="#create_library_to_link">create_library_to_link</a> + </li> + <li> + <a href="#create_link_variables">create_link_variables</a> + </li> + <li> + <a href="#create_linker_input">create_linker_input</a> + </li> + <li> + <a href="#create_linking_context">create_linking_context</a> + </li> + <li> + <a href="#create_linking_context_from_compilation_outputs">create_linking_context_from_compilation_outputs</a> + </li> + <li> + <a href="#create_lto_compilation_context">create_lto_compilation_context</a> + </li> + <li> + <a href="#do_not_use_tools_cpp_compiler_present">do_not_use_tools_cpp_compiler_present</a> + </li> + <li> + <a href="#get_environment_variables">get_environment_variables</a> + </li> + <li> + <a href="#get_execution_requirements">get_execution_requirements</a> + </li> + <li> + <a href="#get_memory_inefficient_command_line">get_memory_inefficient_command_line</a> + </li> + <li> + <a href="#get_tool_for_action">get_tool_for_action</a> + </li> + <li> + <a href="#is_enabled">is_enabled</a> + </li> + <li> + <a href="#link">link</a> + </li> + <li> + <a href="#merge_cc_infos">merge_cc_infos</a> + </li> + <li> + <a href="#merge_compilation_contexts">merge_compilation_contexts</a> + </li> + <li> + <a href="#merge_compilation_outputs">merge_compilation_outputs</a> + </li> + </ul> + + <h2 id="action_is_enabled">action_is_enabled</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cc_common.action_is_enabled(*, feature_configuration, action_name)</pre></p> + + Returns True if given action_config is enabled in the feature configuration. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="action_is_enabled.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + Feature configuration to be queried. + </td> + </tr> + <tr> + <td id="action_is_enabled.action_name"> + <code>action_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of the action_config. + </td> + </tr> + </tbody> + </table> + + <h2 id="CcToolchainInfo">CcToolchainInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> cc_common.CcToolchainInfo</pre></p> + + The key used to retrieve the provider that contains information about the C++ toolchain being used + + <h2 id="compile">compile</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> cc_common.compile(*, actions, feature_configuration, cc_toolchain, srcs=[], public_hdrs=[], private_hdrs=[], includes=[], quote_includes=[], system_includes=[], framework_includes=[], defines=[], local_defines=[], include_prefix='', strip_include_prefix='', user_compile_flags=[], conly_flags=[], cxx_flags=[], compilation_contexts=[], name, disallow_pic_outputs=False, disallow_nopic_outputs=False, additional_inputs=[], module_interfaces=unbound)</pre></p> + + Should be used for C++ compilation. Returns tuple of (<code>CompilationContext</code>, <code>CcCompilationOutputs</code>). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="compile.actions"> + <code>actions</code> + </td> + <td> + <a class="anchor" href="../builtins/actions.html">actions</a>; + required<br/> + <code>actions</code> object. + </td> + </tr> + <tr> + <td id="compile.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + <code>feature_configuration</code> to be queried. + </td> + </tr> + <tr> + <td id="compile.cc_toolchain"> + <code>cc_toolchain</code> + </td> + <td> + Info; + required<br/> + <code>CcToolchainInfo</code> provider to be used. + </td> + </tr> + <tr> + <td id="compile.srcs"> + <code>srcs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + The list of source files to be compiled. + </td> + </tr> + <tr> + <td id="compile.public_hdrs"> + <code>public_hdrs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of headers needed for compilation of srcs and may be included by dependent rules transitively. + </td> + </tr> + <tr> + <td id="compile.private_hdrs"> + <code>private_hdrs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of headers needed for compilation of srcs and NOT to be included by dependent rules. + </td> + </tr> + <tr> + <td id="compile.includes"> + <code>includes</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>[]</code><br/> + Search paths for header files referenced both by angle bracket and quotes. Usually passed with -I. Propagated to dependents transitively. + </td> + </tr> + <tr> + <td id="compile.quote_includes"> + <code>quote_includes</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Search paths for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. Propagated to dependents transitively. + </td> + </tr> + <tr> + <td id="compile.system_includes"> + <code>system_includes</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Search paths for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. Propagated to dependents transitively. + </td> + </tr> + <tr> + <td id="compile.framework_includes"> + <code>framework_includes</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Search paths for header files from Apple frameworks. They can be either relative to the exec root or absolute. Usually passed with -F. Propagated to dependents transitively. + </td> + </tr> + <tr> + <td id="compile.defines"> + <code>defines</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Set of defines needed to compile this target. Each define is a string. Propagated to dependents transitively. + </td> + </tr> + <tr> + <td id="compile.local_defines"> + <code>local_defines</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Set of defines needed to compile this target. Each define is a string. Not propagated to dependents transitively. + </td> + </tr> + <tr> + <td id="compile.include_prefix"> + <code>include_prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the strip_include_prefix attribute is removed before this prefix is added. + </td> + </tr> + <tr> + <td id="compile.strip_include_prefix"> + <code>strip_include_prefix</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the include_prefix attribute is added after this prefix is stripped. + </td> + </tr> + <tr> + <td id="compile.user_compile_flags"> + <code>user_compile_flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Additional list of compilation options. + </td> + </tr> + <tr> + <td id="compile.conly_flags"> + <code>conly_flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Additional list of compilation options for C compiles. + </td> + </tr> + <tr> + <td id="compile.cxx_flags"> + <code>cxx_flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Additional list of compilation options for C++ compiles. + </td> + </tr> + <tr> + <td id="compile.compilation_contexts"> + <code>compilation_contexts</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Headers from dependencies used for compilation. + </td> + </tr> + <tr> + <td id="compile.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + This is used for naming the output artifacts of actions created by this method. See also the `main_output` arg. + </td> + </tr> + <tr> + <td id="compile.disallow_pic_outputs"> + <code>disallow_pic_outputs</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether PIC outputs should be created. + </td> + </tr> + <tr> + <td id="compile.disallow_nopic_outputs"> + <code>disallow_nopic_outputs</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether NOPIC outputs should be created. + </td> + </tr> + <tr> + <td id="compile.additional_inputs"> + <code>additional_inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of additional files needed for compilation of srcs + </td> + </tr> + <tr> + <td id="compile.module_interfaces"> + <code>module_interfaces</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>unbound</code><br/> + The list of module interfaces source files to be compiled. Note: this is an experimental feature, only enabled with --experimental_cpp_modules + </td> + </tr> + </tbody> + </table> + + <h2 id="configure_features">configure_features</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a> cc_common.configure_features(*, ctx, cc_toolchain, language=None, requested_features=[], unsupported_features=[])</pre></p> + + Creates a feature_configuration instance. Requires the cpp configuration fragment. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="configure_features.ctx"> + <code>ctx</code> + </td> + <td> + <a class="anchor" href="../builtins/ctx.html">ctx</a>; + required<br/> + The rule context. + </td> + </tr> + <tr> + <td id="configure_features.cc_toolchain"> + <code>cc_toolchain</code> + </td> + <td> + Info; + required<br/> + cc_toolchain for which we configure features. + </td> + </tr> + <tr> + <td id="configure_features.language"> + <code>language</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The language to configure for: either c++ or objc (default c++) + </td> + </tr> + <tr> + <td id="configure_features.requested_features"> + <code>requested_features</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of features to be enabled. + </td> + </tr> + <tr> + <td id="configure_features.unsupported_features"> + <code>unsupported_features</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of features that are unsupported by the current rule. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_cc_toolchain_config_info">create_cc_toolchain_config_info</h2> + <p><pre class="rule-signature"><code>None</code> cc_common.create_cc_toolchain_config_info(*, ctx, features=[], action_configs=[], artifact_name_patterns=[], cxx_builtin_include_directories=[], toolchain_identifier, host_system_name=None, target_system_name=None, target_cpu=None, target_libc=None, compiler, abi_version=None, abi_libc_version=None, tool_paths=[], make_variables=[], builtin_sysroot=None)</pre></p> + + Creates a <code>CcToolchainConfigInfo</code> provider + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_cc_toolchain_config_info.ctx"> + <code>ctx</code> + </td> + <td> + <a class="anchor" href="../builtins/ctx.html">ctx</a>; + required<br/> + The rule context. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.features"> + <code>features</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Contains all flag specifications for one feature.<p>Arguments:</p><p><code>name</code>: The feature's name. It is possible to introduce a feature without a change to Bazel by adding a 'feature' section to the toolchain and adding the corresponding string as feature in the <code>BUILD</code> file.</p><p><code>enabled</code>: If 'True', this feature is enabled unless a rule type explicitly marks it as unsupported.</p><p><code>flag_sets</code>: A FlagSet list. If the given feature is enabled, the flag sets will be applied for the actions are specified for. </p><p><code>env_sets</code>: an EnvSet list. If the given feature is enabled, the env sets will be applied for the actions they are specified for. </p><p><code>requires</code>: A list of feature sets defining when this feature is supported by the toolchain. The feature is supported if any of the feature sets fully apply, that is, when all features of a feature set are enabled. If <code>requires</code> is omitted, the feature is supported independently of which other features are enabled. Use this for example to filter flags depending on the build mode enabled (opt / fastbuild / dbg). </p><p><code>implies</code>: A string list of features or action configs that are automatically enabled when this feature is enabled. If any of the implied features or action configs cannot be enabled, this feature will (silently) not be enabled either. </p><p><code>provides</code>: A list of names this feature conflicts with. </p>A feature cannot be enabled if:</br>- <code>provides</code> contains the name of a different feature or action config that we want to enable.</br>- <code>provides</code> contains the same value as a 'provides' in a different feature or action config that we want to enable. Use this in order to ensure that incompatible features cannot be accidentally activated at the same time, leading to hard to diagnose compiler errors. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.action_configs"> + <code>action_configs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + An action config corresponds to a Bazel action, and allows selection of a tool based on activated features. Action config activation occurs by the same semantics as features: a feature can 'require' or 'imply' an action config in the same way that it would another feature.<p>Arguments:</p><p><code>action_name</code>: The name of the Bazel action that this config applies to, e.g. 'c-compile' or 'c-module-compile'.</p><p><code>enabled</code>: If 'True', this action is enabled unless a rule type explicitly marks it as unsupported.</p><p><code>tools</code>: The tool applied to the action will be the first tool with a feature set that matches the feature configuration. An error will be thrown if no tool matches a provided feature configuration - for that reason, it's a good idea to provide a default tool with an empty feature set.</p><p><code>flag_sets</code>: If the given action config is enabled, the flag sets will be applied to the corresponding action.</p><p><code>implies</code>: A list of features or action configs that are automatically enabled when this action config is enabled. If any of the implied features or action configs cannot be enabled, this action config will (silently) not be enabled either.</p> + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.artifact_name_patterns"> + <code>artifact_name_patterns</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + The name for an artifact of a given category of input or output artifacts to an action.<p>Arguments:</p><p><code>category_name</code>: The category of artifacts that this selection applies to. This field is compared against a list of categories defined in Bazel. Example categories include "linked_output" or the artifact for this selection. Together with the extension it is used to create an artifact name based on the target name.</p><p><code>extension</code>: The extension for creating the artifact for this selection. Together with the prefix it is used to create an artifact name based on the target name.</p> + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.cxx_builtin_include_directories"> + <code>cxx_builtin_include_directories</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + <p>Built-in include directories for C++ compilation. These should be the exact paths used by the compiler, and are generally relative to the exec root.</p><p>The paths used by the compiler can be determined by 'gcc -E -xc++ - -v'.</p><p>We currently use the C++ paths also for C compilation, which is safe as long as there are no name clashes between C++ and C header files.</p><p>Relative paths are resolved relative to the configuration file directory.</p><p>If the compiler has --sysroot support, then these paths should use %sysroot% rather than the include path, and specify the sysroot attribute in order to give blaze the information necessary to make the correct replacements.</p> + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.toolchain_identifier"> + <code>toolchain_identifier</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + <p>The unique identifier of the toolchain within the crosstool release. It must be possible to use this as a directory name in a path.</p><p>It has to match the following regex: [a-zA-Z_][\.\- \w]*</p> + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.host_system_name"> + <code>host_system_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Ignored. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.target_system_name"> + <code>target_system_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Deprecated. The GNU System Name. The string is exposed to CcToolchainInfo.target_gnu_system_name. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.target_cpu"> + <code>target_cpu</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Deprecated: Use cpu based constraints instead. If the string is "k8", `target_cpu` will be omitted from the filename of raw FDO profile data. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.target_libc"> + <code>target_libc</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Deprecated: Use OS based constraints instead. The libc version string (e.g. "glibc-2.2.2"). If the string is "macosx", platform is assumed to be MacOS. Otherwise, Linux. The string is exposed to CcToolchainInfo.libc. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.compiler"> + <code>compiler</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The compiler string (e.g. "gcc"). The current toolchain's compiler is exposed to `@bazel_tools//tools/cpp:compiler (compiler_flag)` as a flag value. Targets that require compiler-specific flags can use the config_settings in https://github.com/bazelbuild/rules_cc/blob/main/cc/compiler/BUILD in select() statements or create custom config_setting if the existing settings don't suffice. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.abi_version"> + <code>abi_version</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The abi in use, which is a gcc version. E.g.: "gcc-3.4". The string is set to C++ toolchain variable ABI. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.abi_libc_version"> + <code>abi_libc_version</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The glibc version used by the abi we're using. The string is set to C++ toolchain variable ABI_LIBC_VERSION. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.tool_paths"> + <code>tool_paths</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Tool locations.<p>Arguments:</p><p><code>name</code>: Name of the tool.</p><p><code>path</code>: Location of the tool; Can be absolute path (in case of non hermetic toolchain), or path relative to the cc_toolchain's package.</p> + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.make_variables"> + <code>make_variables</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + A make variable that is made accessible to rules. + </td> + </tr> + <tr> + <td id="create_cc_toolchain_config_info.builtin_sysroot"> + <code>builtin_sysroot</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The built-in sysroot. If this attribute is not present, Bazel does not allow using a different sysroot, i.e. through the --grte_top option. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_compilation_context">create_compilation_context</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/CompilationContext.html">CompilationContext</a> cc_common.create_compilation_context(*, headers=unbound, system_includes=unbound, includes=unbound, quote_includes=unbound, framework_includes=unbound, defines=unbound, local_defines=unbound)</pre></p> + + Creates a <code>CompilationContext</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_compilation_context.headers"> + <code>headers</code> + </td> + <td> + default is <code>unbound</code><br/> + Set of headers needed to compile this target + </td> + </tr> + <tr> + <td id="create_compilation_context.system_includes"> + <code>system_includes</code> + </td> + <td> + default is <code>unbound</code><br/> + Set of search paths for header files referenced by angle brackets, i.e. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem + </td> + </tr> + <tr> + <td id="create_compilation_context.includes"> + <code>includes</code> + </td> + <td> + default is <code>unbound</code><br/> + Set of search paths for header files referenced both by angle bracket and quotes.Usually passed with -I + </td> + </tr> + <tr> + <td id="create_compilation_context.quote_includes"> + <code>quote_includes</code> + </td> + <td> + default is <code>unbound</code><br/> + Set of search paths for header files referenced by quotes, i.e. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote + </td> + </tr> + <tr> + <td id="create_compilation_context.framework_includes"> + <code>framework_includes</code> + </td> + <td> + default is <code>unbound</code><br/> + Set of framework search paths for header files (Apple platform only) + </td> + </tr> + <tr> + <td id="create_compilation_context.defines"> + <code>defines</code> + </td> + <td> + default is <code>unbound</code><br/> + Set of defines needed to compile this target. Each define is a string. Propagated transitively to dependents. + </td> + </tr> + <tr> + <td id="create_compilation_context.local_defines"> + <code>local_defines</code> + </td> + <td> + default is <code>unbound</code><br/> + Set of defines needed to compile this target. Each define is a string. Not propagated transitively to dependents. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_compilation_outputs">create_compilation_outputs</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/CcCompilationOutputs.html">CcCompilationOutputs</a> cc_common.create_compilation_outputs(*, objects=None, pic_objects=None)</pre></p> + + Create compilation outputs object. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_compilation_outputs.objects"> + <code>objects</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + List of object files. + </td> + </tr> + <tr> + <td id="create_compilation_outputs.pic_objects"> + <code>pic_objects</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + List of pic object files. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_compile_variables">create_compile_variables</h2> + <p><pre class="rule-signature">Variables cc_common.create_compile_variables(*, cc_toolchain, feature_configuration, source_file=None, output_file=None, user_compile_flags=None, include_directories=None, quote_include_directories=None, system_include_directories=None, framework_include_directories=None, preprocessor_defines=None, thinlto_index=None, thinlto_input_bitcode_file=None, thinlto_output_object_file=None, use_pic=False, add_legacy_cxx_options=False, variables_extension=unbound)</pre></p> + + Returns variables used for compilation actions. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_compile_variables.cc_toolchain"> + <code>cc_toolchain</code> + </td> + <td> + Info; + required<br/> + cc_toolchain for which we are creating build variables. + </td> + </tr> + <tr> + <td id="create_compile_variables.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + Feature configuration to be queried. + </td> + </tr> + <tr> + <td id="create_compile_variables.source_file"> + <code>source_file</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Optional source file path for the compilation. Please prefer passing source_file here over appending it to the end of the command line generated from cc_common.get_memory_inefficient_command_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. + </td> + </tr> + <tr> + <td id="create_compile_variables.output_file"> + <code>output_file</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Optional output file path of the compilation. Please prefer passing output_file here over appending it to the end of the command line generated from cc_common.get_memory_inefficient_command_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. + </td> + </tr> + <tr> + <td id="create_compile_variables.user_compile_flags"> + <code>user_compile_flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + List of additional compilation flags (copts). + </td> + </tr> + <tr> + <td id="create_compile_variables.include_directories"> + <code>include_directories</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + Depset of include directories. + </td> + </tr> + <tr> + <td id="create_compile_variables.quote_include_directories"> + <code>quote_include_directories</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + Depset of quote include directories. + </td> + </tr> + <tr> + <td id="create_compile_variables.system_include_directories"> + <code>system_include_directories</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + Depset of system include directories. + </td> + </tr> + <tr> + <td id="create_compile_variables.framework_include_directories"> + <code>framework_include_directories</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + Depset of framework include directories. + </td> + </tr> + <tr> + <td id="create_compile_variables.preprocessor_defines"> + <code>preprocessor_defines</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; + default is <code>None</code><br/> + Depset of preprocessor defines. + </td> + </tr> + <tr> + <td id="create_compile_variables.thinlto_index"> + <code>thinlto_index</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + LTO index file path. + </td> + </tr> + <tr> + <td id="create_compile_variables.thinlto_input_bitcode_file"> + <code>thinlto_input_bitcode_file</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Bitcode file that is input to LTO backend. + </td> + </tr> + <tr> + <td id="create_compile_variables.thinlto_output_object_file"> + <code>thinlto_output_object_file</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + Object file that is output by LTO backend. + </td> + </tr> + <tr> + <td id="create_compile_variables.use_pic"> + <code>use_pic</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + When true the compilation will generate position independent code. + </td> + </tr> + <tr> + <td id="create_compile_variables.add_legacy_cxx_options"> + <code>add_legacy_cxx_options</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Unused. + </td> + </tr> + <tr> + <td id="create_compile_variables.variables_extension"> + <code>variables_extension</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>unbound</code><br/> + A dictionary of additional variables used by compile actions. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_library_to_link">create_library_to_link</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/LibraryToLink.html">LibraryToLink</a> cc_common.create_library_to_link(*, actions, feature_configuration=None, cc_toolchain=None, static_library=None, pic_static_library=None, dynamic_library=None, interface_library=None, pic_objects=unbound, objects=unbound, alwayslink=False, dynamic_library_symlink_path='', interface_library_symlink_path='')</pre></p> + + Creates <code>LibraryToLink</code> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_library_to_link.actions"> + <code>actions</code> + </td> + <td> + required<br/> + <code>actions</code> object. + </td> + </tr> + <tr> + <td id="create_library_to_link.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + default is <code>None</code><br/> + <code>feature_configuration</code> to be queried. + </td> + </tr> + <tr> + <td id="create_library_to_link.cc_toolchain"> + <code>cc_toolchain</code> + </td> + <td> + default is <code>None</code><br/> + <code>CcToolchainInfo</code> provider to be used. + </td> + </tr> + <tr> + <td id="create_library_to_link.static_library"> + <code>static_library</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + <code>File</code> of static library to be linked. + </td> + </tr> + <tr> + <td id="create_library_to_link.pic_static_library"> + <code>pic_static_library</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + <code>File</code> of pic static library to be linked. + </td> + </tr> + <tr> + <td id="create_library_to_link.dynamic_library"> + <code>dynamic_library</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + <code>File</code> of dynamic library to be linked. Always used for runtime and used for linking if <code>interface_library</code> is not passed. + </td> + </tr> + <tr> + <td id="create_library_to_link.interface_library"> + <code>interface_library</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + <code>File</code> of interface library to be linked. + </td> + </tr> + <tr> + <td id="create_library_to_link.pic_objects"> + <code>pic_objects</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>unbound</code><br/> + Experimental, do not use + </td> + </tr> + <tr> + <td id="create_library_to_link.objects"> + <code>objects</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>unbound</code><br/> + Experimental, do not use + </td> + </tr> + <tr> + <td id="create_library_to_link.alwayslink"> + <code>alwayslink</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether to link the static library/objects in the --whole_archive block. + </td> + </tr> + <tr> + <td id="create_library_to_link.dynamic_library_symlink_path"> + <code>dynamic_library_symlink_path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Override the default path of the dynamic library link in the solib directory. Empty string to use the default. + </td> + </tr> + <tr> + <td id="create_library_to_link.interface_library_symlink_path"> + <code>interface_library_symlink_path</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>''</code><br/> + Override the default path of the interface library link in the solib directory. Empty string to use the default. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_link_variables">create_link_variables</h2> + <p><pre class="rule-signature">Variables cc_common.create_link_variables(*, cc_toolchain, feature_configuration, library_search_directories=[], runtime_library_search_directories=[], user_link_flags=[], output_file=None, param_file=None, is_using_linker=True, is_linking_dynamic_library=False, must_keep_debug=True, use_test_only_flags=False, is_static_linking_mode=True)</pre></p> + + Returns link variables used for linking actions. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_link_variables.cc_toolchain"> + <code>cc_toolchain</code> + </td> + <td> + Info; + required<br/> + cc_toolchain for which we are creating build variables. + </td> + </tr> + <tr> + <td id="create_link_variables.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + Feature configuration to be queried. + </td> + </tr> + <tr> + <td id="create_link_variables.library_search_directories"> + <code>library_search_directories</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>[]</code><br/> + Depset of directories where linker will look for libraries at link time. + </td> + </tr> + <tr> + <td id="create_link_variables.runtime_library_search_directories"> + <code>runtime_library_search_directories</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>[]</code><br/> + Depset of directories where loader will look for libraries at runtime. + </td> + </tr> + <tr> + <td id="create_link_variables.user_link_flags"> + <code>user_link_flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of additional link flags (linkopts). + </td> + </tr> + <tr> + <td id="create_link_variables.output_file"> + <code>output_file</code> + </td> + <td> + default is <code>None</code><br/> + Optional output file path. + </td> + </tr> + <tr> + <td id="create_link_variables.param_file"> + <code>param_file</code> + </td> + <td> + default is <code>None</code><br/> + Optional param file path. + </td> + </tr> + <tr> + <td id="create_link_variables.is_using_linker"> + <code>is_using_linker</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True when using linker, False when archiver. Caller is responsible for keeping this in sync with action name used (is_using_linker = True for linking executable or dynamic library, is_using_linker = False for archiving static library). + </td> + </tr> + <tr> + <td id="create_link_variables.is_linking_dynamic_library"> + <code>is_linking_dynamic_library</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + True when creating dynamic library, False when executable or static library. Caller is responsible for keeping this in sync with action name used. This field will be removed once b/65151735 is fixed. + </td> + </tr> + <tr> + <td id="create_link_variables.must_keep_debug"> + <code>must_keep_debug</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + When set to False, bazel will expose 'strip_debug_symbols' variable, which is usually used to use the linker to strip debug symbols from the output file. + </td> + </tr> + <tr> + <td id="create_link_variables.use_test_only_flags"> + <code>use_test_only_flags</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + When set to true, 'is_cc_test' variable will be set. + </td> + </tr> + <tr> + <td id="create_link_variables.is_static_linking_mode"> + <code>is_static_linking_mode</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + Unused. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_linker_input">create_linker_input</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/LinkerInput.html">LinkerInput</a> cc_common.create_linker_input(*, owner, libraries=None, user_link_flags=None, additional_inputs=None)</pre></p> + + Creates a <code>LinkerInput</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_linker_input.owner"> + <code>owner</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; + required<br/> + The label of the target that produced all files used in this input. + </td> + </tr> + <tr> + <td id="create_linker_input.libraries"> + <code>libraries</code> + </td> + <td> + <code>None</code>; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>None</code><br/> + List of <code>LibraryToLink</code>. + </td> + </tr> + <tr> + <td id="create_linker_input.user_link_flags"> + <code>user_link_flags</code> + </td> + <td> + <code>None</code>; or <a class="anchor" href="../builtins/depset.html">depset</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>None</code><br/> + User link flags passed as strings. Accepts either [String], [[String]] or depset(String). The latter is discouraged as it's only kept for compatibility purposes, the depset is flattened. If you want to propagate user_link_flags via unflattened depsets() wrap them in a LinkerInput so that they are not flattened till the end. + </td> + </tr> + <tr> + <td id="create_linker_input.additional_inputs"> + <code>additional_inputs</code> + </td> + <td> + <code>None</code>; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>None</code><br/> + For additional inputs to the linking action, e.g.: linking scripts. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_linking_context">create_linking_context</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/LinkingContext.html">LinkingContext</a> cc_common.create_linking_context(*, linker_inputs)</pre></p> + + Creates a <code>LinkingContext</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_linking_context.linker_inputs"> + <code>linker_inputs</code> + </td> + <td> + <a class="anchor" href="../builtins/depset.html">depset</a>; + required<br/> + Depset of <code>LinkerInput</code>. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_linking_context_from_compilation_outputs">create_linking_context_from_compilation_outputs</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> cc_common.create_linking_context_from_compilation_outputs(*, actions, name, feature_configuration, cc_toolchain, language='c++', disallow_static_libraries=False, disallow_dynamic_library=False, compilation_outputs, linking_contexts=[], user_link_flags=[], alwayslink=False, additional_inputs=[], variables_extension=unbound)</pre></p> + + Should be used for creating library rules that can propagate information downstream in order to be linked later by a top level rule that does transitive linking to create an executable or a dynamic library. Returns tuple of (<code>CcLinkingContext</code>, <code>CcLinkingOutputs</code>). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_linking_context_from_compilation_outputs.actions"> + <code>actions</code> + </td> + <td> + <a class="anchor" href="../builtins/actions.html">actions</a>; + required<br/> + <code>actions</code> object. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + This is used for naming the output artifacts of actions created by this method. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + <code>feature_configuration</code> to be queried. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.cc_toolchain"> + <code>cc_toolchain</code> + </td> + <td> + Info; + required<br/> + <code>CcToolchainInfo</code> provider to be used. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.language"> + <code>language</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'c++'</code><br/> + Only C++ supported for now. Do not use this parameter. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.disallow_static_libraries"> + <code>disallow_static_libraries</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether static libraries should be created. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.disallow_dynamic_library"> + <code>disallow_dynamic_library</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether a dynamic library should be created. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.compilation_outputs"> + <code>compilation_outputs</code> + </td> + <td> + <a class="anchor" href="../builtins/CcCompilationOutputs.html">CcCompilationOutputs</a>; + required<br/> + Compilation outputs containing object files to link. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.linking_contexts"> + <code>linking_contexts</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Libraries from dependencies. These libraries will be linked into the output artifact of the link() call, be it a binary or a library. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.user_link_flags"> + <code>user_link_flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Additional list of linking options. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.alwayslink"> + <code>alwayslink</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether this library should always be linked. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.additional_inputs"> + <code>additional_inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + For additional inputs to the linking action, e.g.: linking scripts. + </td> + </tr> + <tr> + <td id="create_linking_context_from_compilation_outputs.variables_extension"> + <code>variables_extension</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>unbound</code><br/> + Additional variables to pass to the toolchain configuration when creating link command line. + </td> + </tr> + </tbody> + </table> + + <h2 id="create_lto_compilation_context">create_lto_compilation_context</h2> + <p><pre class="rule-signature">LtoCompilationContext cc_common.create_lto_compilation_context(*, objects={})</pre></p> + + Create LTO compilation context + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="create_lto_compilation_context.objects"> + <code>objects</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + map of full object to index object + </td> + </tr> + </tbody> + </table> + + <h2 id="do_not_use_tools_cpp_compiler_present">do_not_use_tools_cpp_compiler_present</h2> + <p><pre class="rule-signature"><code>None</code> cc_common.do_not_use_tools_cpp_compiler_present</pre></p> + + Do not use this field, its only purpose is to help with migration from config_setting.values{'compiler') to config_settings.flag_values{'@bazel_tools//tools/cpp:compiler'} + + <h2 id="get_environment_variables">get_environment_variables</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> cc_common.get_environment_variables(*, feature_configuration, action_name, variables)</pre></p> + + Returns environment variables to be set for given action. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="get_environment_variables.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + Feature configuration to be queried. + </td> + </tr> + <tr> + <td id="get_environment_variables.action_name"> + <code>action_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl) + </td> + </tr> + <tr> + <td id="get_environment_variables.variables"> + <code>variables</code> + </td> + <td> + Variables; + required<br/> + Build variables to be used for template expansion. + </td> + </tr> + </tbody> + </table> + + <h2 id="get_execution_requirements">get_execution_requirements</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> cc_common.get_execution_requirements(*, feature_configuration, action_name)</pre></p> + + Returns execution requirements for given action. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="get_execution_requirements.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + Feature configuration to be queried. + </td> + </tr> + <tr> + <td id="get_execution_requirements.action_name"> + <code>action_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl) + </td> + </tr> + </tbody> + </table> + + <h2 id="get_memory_inefficient_command_line">get_memory_inefficient_command_line</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> cc_common.get_memory_inefficient_command_line(*, feature_configuration, action_name, variables)</pre></p> + + Returns flattened command line flags for given action, using given variables for expansion. Flattens nested sets and ideally should not be used, or at least should not outlive analysis. Work on memory efficient function returning Args is ongoing. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="get_memory_inefficient_command_line.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + Feature configuration to be queried. + </td> + </tr> + <tr> + <td id="get_memory_inefficient_command_line.action_name"> + <code>action_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl) + </td> + </tr> + <tr> + <td id="get_memory_inefficient_command_line.variables"> + <code>variables</code> + </td> + <td> + Variables; + required<br/> + Build variables to be used for template expansions. + </td> + </tr> + </tbody> + </table> + + <h2 id="get_tool_for_action">get_tool_for_action</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> cc_common.get_tool_for_action(*, feature_configuration, action_name)</pre></p> + + Returns tool path for given action. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="get_tool_for_action.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + Feature configuration to be queried. + </td> + </tr> + <tr> + <td id="get_tool_for_action.action_name"> + <code>action_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl) + </td> + </tr> + </tbody> + </table> + + <h2 id="is_enabled">is_enabled</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cc_common.is_enabled(*, feature_configuration, feature_name)</pre></p> + + Returns True if given feature is enabled in the feature configuration. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="is_enabled.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + Feature configuration to be queried. + </td> + </tr> + <tr> + <td id="is_enabled.feature_name"> + <code>feature_name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of the feature. + </td> + </tr> + </tbody> + </table> + + <h2 id="link">link</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/CcLinkingOutputs.html">CcLinkingOutputs</a> cc_common.link(*, actions, name, feature_configuration, cc_toolchain, language='c++', output_type='executable', link_deps_statically=True, compilation_outputs=None, linking_contexts=[], user_link_flags=[], stamp=0, additional_inputs=[], additional_outputs=[], variables_extension={})</pre></p> + + Should be used for C++ transitive linking. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="link.actions"> + <code>actions</code> + </td> + <td> + <a class="anchor" href="../builtins/actions.html">actions</a>; + required<br/> + <code>actions</code> object. + </td> + </tr> + <tr> + <td id="link.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + This is used for naming the output artifacts of actions created by this method. + </td> + </tr> + <tr> + <td id="link.feature_configuration"> + <code>feature_configuration</code> + </td> + <td> + <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; + required<br/> + <code>feature_configuration</code> to be queried. + </td> + </tr> + <tr> + <td id="link.cc_toolchain"> + <code>cc_toolchain</code> + </td> + <td> + Info; + required<br/> + <code>CcToolchainInfo</code> provider to be used. + </td> + </tr> + <tr> + <td id="link.language"> + <code>language</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'c++'</code><br/> + Only C++ supported for now. Do not use this parameter. + </td> + </tr> + <tr> + <td id="link.output_type"> + <code>output_type</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'executable'</code><br/> + Can be either 'executable' or 'dynamic_library'. + </td> + </tr> + <tr> + <td id="link.link_deps_statically"> + <code>link_deps_statically</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + True to link dependencies statically, False dynamically. + </td> + </tr> + <tr> + <td id="link.compilation_outputs"> + <code>compilation_outputs</code> + </td> + <td> + <a class="anchor" href="../builtins/CcCompilationOutputs.html">CcCompilationOutputs</a>; or <code>None</code>; + default is <code>None</code><br/> + Compilation outputs containing object files to link. + </td> + </tr> + <tr> + <td id="link.linking_contexts"> + <code>linking_contexts</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Linking contexts from dependencies to be linked into the linking context generated by this rule. + </td> + </tr> + <tr> + <td id="link.user_link_flags"> + <code>user_link_flags</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + Additional list of linker options. + </td> + </tr> + <tr> + <td id="link.stamp"> + <code>stamp</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>0</code><br/> + Whether to include build information in the linked executable, if output_type is 'executable'. If 1, build information is always included. If 0 (the default build information is always excluded. If -1, uses the default behavior, which may be overridden by the --[no]stamp flag. This should be unset (or set to 0) when generating the executable output for test rules. + </td> + </tr> + <tr> + <td id="link.additional_inputs"> + <code>additional_inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; + default is <code>[]</code><br/> + For additional inputs to the linking action, e.g.: linking scripts. + </td> + </tr> + <tr> + <td id="link.additional_outputs"> + <code>additional_outputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + For additional outputs to the linking action, e.g.: map files. + </td> + </tr> + <tr> + <td id="link.variables_extension"> + <code>variables_extension</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + Additional variables to pass to the toolchain configuration when create link command line. + </td> + </tr> + </tbody> + </table> + + <h2 id="merge_cc_infos">merge_cc_infos</h2> + <p><pre class="rule-signature">unknown cc_common.merge_cc_infos(*, direct_cc_infos=[], cc_infos=[])</pre></p> + + Merges multiple <code>CcInfo</code>s into one. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="merge_cc_infos.direct_cc_infos"> + <code>direct_cc_infos</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of <code>CcInfo</code>s to be merged, whose headers will be exported by the direct fields in the returned provider. + </td> + </tr> + <tr> + <td id="merge_cc_infos.cc_infos"> + <code>cc_infos</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of <code>CcInfo</code>s to be merged, whose headers will not be exported by the direct fields in the returned provider. + </td> + </tr> + </tbody> + </table> + + <h2 id="merge_compilation_contexts">merge_compilation_contexts</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/CompilationContext.html">CompilationContext</a> cc_common.merge_compilation_contexts(*, compilation_contexts=[])</pre></p> + + Merges multiple <code>CompilationContexts</code>s into one. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="merge_compilation_contexts.compilation_contexts"> + <code>compilation_contexts</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + List of <code>CompilationContexts</code>s to be merged. The headers of each context will be exported by the direct fields in the returned provider. + </td> + </tr> + </tbody> + </table> + + <h2 id="merge_compilation_outputs">merge_compilation_outputs</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/CcCompilationOutputs.html">CcCompilationOutputs</a> cc_common.merge_compilation_outputs(*, compilation_outputs=[])</pre></p> + + Merge compilation outputs. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="merge_compilation_outputs.compilation_outputs"> + <code>compilation_outputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/config.mdx b/rules/lib/toplevel/config.mdx new file mode 100644 index 0000000..ed66e77 --- /dev/null +++ b/rules/lib/toplevel/config.mdx @@ -0,0 +1,288 @@ +--- +title: 'config' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.config">config</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +This is a top-level module for creating configuration transitions and build setting descriptors which describe what kind of build setting (if any) a rule is. <p>ex: the following rule is marked as a build setting by setting the <code>build_setting</code> parameter of the <code>rule()</code> function. Specifically it is a build setting of type <code>int</code> and is a <code>flag</code> which means this build setting is callable on the command line.<br><pre class=language-python> my_rule = rule( + implementation = _impl, + build_setting = config.int(flag = True), + ... + )</pre> + +<h2>Members</h2> +<ul> + <li> + <a href="#bool">bool</a> + </li> + <li> + <a href="#exec">exec</a> + </li> + <li> + <a href="#int">int</a> + </li> + <li> + <a href="#none">none</a> + </li> + <li> + <a href="#string">string</a> + </li> + <li> + <a href="#string_list">string_list</a> + </li> + <li> + <a href="#string_set">string_set</a> + </li> + <li> + <a href="#target">target</a> + </li> + </ul> + + <h2 id="bool">bool</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.bool(*, flag=False)</pre></p> + + A bool-typed build setting + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="bool.flag"> + <code>flag</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether or not this build setting is callable on the command line. + </td> + </tr> + </tbody> + </table> + + <h2 id="exec">exec</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/ExecTransitionFactory.html">ExecTransitionFactory</a> config.exec(exec_group=None)</pre></p> + + Creates an execution transition. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="exec.exec_group"> + <code>exec_group</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; + default is <code>None</code><br/> + The name of the exec group whose execution platform this transition will use. If not provided, this exec transition will use the target's default execution platform. + </td> + </tr> + </tbody> + </table> + + <h2 id="int">int</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.int(*, flag=False)</pre></p> + + An integer-typed build setting + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="int.flag"> + <code>flag</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether or not this build setting is callable on the command line. + </td> + </tr> + </tbody> + </table> + + <h2 id="none">none</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> config.none()</pre></p> + + Creates a transition which removes all configuration, unsetting all flags. Intended for the case where a dependency is data-only and contains no code that needs to be built, but should only be analyzed once. + + <h2 id="string">string</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.string(*, flag=False, allow_multiple=False)</pre></p> + + A string-typed build setting + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="string.flag"> + <code>flag</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether or not this build setting is callable on the command line. + </td> + </tr> + <tr> + <td id="string.allow_multiple"> + <code>allow_multiple</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Deprecated, use a <code>string_list</code> setting with <code>repeatable = True</code> instead. If set, this flag is allowed to be set multiple times on the command line. The Value of the flag as accessed in transitions and build setting implementation function will be a list of strings. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. + </td> + </tr> + </tbody> + </table> + + <h2 id="string_list">string_list</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.string_list(*, flag=False, repeatable=False)</pre></p> + + A string list-typed build setting. On the command line pass a list using comma-separated value like <code>--//my/setting=foo,bar</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="string_list.flag"> + <code>flag</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether or not this build setting is callable on the command line. + </td> + </tr> + <tr> + <td id="string_list.repeatable"> + <code>repeatable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the list value. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. + </td> + </tr> + </tbody> + </table> + + <h2 id="string_set">string_set</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.string_set(*, flag=False, repeatable=False)</pre></p> + + A string set-typed build setting. The value of this setting will be a <a href='https://bazel.build/rules/lib/core/set'>set</a> of strings in Starlark. On the command line, pass a set using a comma-separated value like <code>--//my/setting=foo,bar</code>.<p>Unlike with a <code>string_list</code>, the order of the elements doesn't matter and only a single instance of each element is maintained. This is recommended over <code>string_list</code> for flags where these properties are not needed as it can improve build performance by avoiding unnecessary configurations forking. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="string_set.flag"> + <code>flag</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether or not this build setting is callable on the command line. + </td> + </tr> + <tr> + <td id="string_set.repeatable"> + <code>repeatable</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the set value. Only a single instance of repeated values is maintained and the insertion order does not matter. + </td> + </tr> + </tbody> + </table> + + <h2 id="target">target</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> config.target()</pre></p> + + Creates a target transition. This is a no-op transition intended for the case where a transition object is needed, but doesn't want to actually change anything. Equivalent to <code>cfg = "target"</code> in <code>attr.label()</code>. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/config_common.mdx b/rules/lib/toplevel/config_common.mdx new file mode 100644 index 0000000..49cc61a --- /dev/null +++ b/rules/lib/toplevel/config_common.mdx @@ -0,0 +1,81 @@ +--- +title: 'config_common' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.config_common">config_common</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigStarlarkCommonApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Functions for Starlark to interact with Blaze's configurability APIs. + +<h2>Members</h2> +<ul> + <li> + <a href="#FeatureFlagInfo">FeatureFlagInfo</a> + </li> + <li> + <a href="#toolchain_type">toolchain_type</a> + </li> + </ul> + + <h2 id="FeatureFlagInfo">FeatureFlagInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> config_common.FeatureFlagInfo</pre></p> + + The key used to retrieve the provider containing config_feature_flag's value. + + <h2 id="toolchain_type">toolchain_type</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/toolchain_type.html">toolchain_type</a> config_common.toolchain_type(name, *, mandatory=True)</pre></p> + + Declare a rule's dependency on a toolchain type. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="toolchain_type.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; + required<br/> + The toolchain type that is required. + </td> + </tr> + <tr> + <td id="toolchain_type.mandatory"> + <code>mandatory</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + Whether the toolchain type is mandatory or optional. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/coverage_common.mdx b/rules/lib/toplevel/coverage_common.mdx new file mode 100644 index 0000000..b843290 --- /dev/null +++ b/rules/lib/toplevel/coverage_common.mdx @@ -0,0 +1,113 @@ +--- +title: 'coverage_common' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.coverage_common">coverage_common</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Helper functions to access coverage-related infrastructure. + +<h2>Members</h2> +<ul> + <li> + <a href="#instrumented_files_info">instrumented_files_info</a> + </li> + </ul> + + <h2 id="instrumented_files_info">instrumented_files_info</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/InstrumentedFilesInfo.html">InstrumentedFilesInfo</a> coverage_common.instrumented_files_info(ctx, *, source_attributes=[], dependency_attributes=[], extensions=None, metadata_files=[], baseline_coverage_files=None)</pre></p> + + Creates a new <a class="anchor" href="../providers/InstrumentedFilesInfo.html">InstrumentedFilesInfo</a> instance. Use this provider to communicate coverage-related attributes of the current build rule. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="instrumented_files_info.ctx"> + <code>ctx</code> + </td> + <td> + <a class="anchor" href="../builtins/ctx.html">ctx</a>; + required<br/> + The rule context. + </td> + </tr> + <tr> + <td id="instrumented_files_info.source_attributes"> + <code>source_attributes</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + A list of attribute names which contain source files processed by this rule. + </td> + </tr> + <tr> + <td id="instrumented_files_info.dependency_attributes"> + <code>dependency_attributes</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + A list of attribute names which might provide runtime dependencies (either code dependencies or runfiles). + </td> + </tr> + <tr> + <td id="instrumented_files_info.extensions"> + <code>extensions</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + File extensions used to filter files from source_attributes. For example, 'js'. If not provided (or None), then all files from source_attributes will be added to instrumented files, if an empty list is provided, then no files from source attributes will be added. + </td> + </tr> + <tr> + <td id="instrumented_files_info.metadata_files"> + <code>metadata_files</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + Additional files required to generate coverage LCOV files after code execution. e.g. .gcno files for C++. + </td> + </tr> + <tr> + <td id="instrumented_files_info.baseline_coverage_files"> + <code>baseline_coverage_files</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <code>None</code>; + default is <code>None</code><br/> + + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/java_common.mdx b/rules/lib/toplevel/java_common.mdx new file mode 100644 index 0000000..d3ccc53 --- /dev/null +++ b/rules/lib/toplevel/java_common.mdx @@ -0,0 +1,576 @@ +--- +title: 'java_common' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.java_common">java_common</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Utilities for Java compilation support in Starlark. + +<h2>Members</h2> +<ul> + <li> + <a href="#BootClassPathInfo">BootClassPathInfo</a> + </li> + <li> + <a href="#compile">compile</a> + </li> + <li> + <a href="#JavaRuntimeInfo">JavaRuntimeInfo</a> + </li> + <li> + <a href="#JavaToolchainInfo">JavaToolchainInfo</a> + </li> + <li> + <a href="#merge">merge</a> + </li> + <li> + <a href="#pack_sources">pack_sources</a> + </li> + <li> + <a href="#run_ijar">run_ijar</a> + </li> + <li> + <a href="#stamp_jar">stamp_jar</a> + </li> + </ul> + + <h2 id="BootClassPathInfo">BootClassPathInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> java_common.BootClassPathInfo</pre></p> + + The provider used to supply bootclasspath information + + <h2 id="compile">compile</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> java_common.compile(ctx, *, source_jars=[], source_files=[], output, output_source_jar=None, javac_opts=[], deps=[], runtime_deps=[], exports=[], plugins=[], exported_plugins=[], native_libraries=[], annotation_processor_additional_inputs=[], annotation_processor_additional_outputs=[], strict_deps='ERROR', java_toolchain, bootclasspath=None, sourcepath=[], resources=[], resource_jars=[], classpath_resources=[], neverlink=False, enable_annotation_processing=True, enable_compile_jar_action=True, add_exports=[], add_opens=[])</pre></p> + + Compiles Java source files/jars from the implementation of a Starlark rule and returns a provider that represents the results of the compilation and can be added to the set of providers emitted by this rule. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="compile.ctx"> + <code>ctx</code> + </td> + <td> + <a class="anchor" href="../builtins/ctx.html">ctx</a>; + required<br/> + The rule context. + </td> + </tr> + <tr> + <td id="compile.source_jars"> + <code>source_jars</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + A list of the jars to be compiled. At least one of source_jars or source_files should be specified. + </td> + </tr> + <tr> + <td id="compile.source_files"> + <code>source_files</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + A list of the Java source files to be compiled. At least one of source_jars or source_files should be specified. + </td> + </tr> + <tr> + <td id="compile.output"> + <code>output</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + + </td> + </tr> + <tr> + <td id="compile.output_source_jar"> + <code>output_source_jar</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + The output source jar. Defaults to `{output_jar}-src.jar` if unset. + </td> + </tr> + <tr> + <td id="compile.javac_opts"> + <code>javac_opts</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A list of the desired javac options. + </td> + </tr> + <tr> + <td id="compile.deps"> + <code>deps</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; + default is <code>[]</code><br/> + A list of dependencies. + </td> + </tr> + <tr> + <td id="compile.runtime_deps"> + <code>runtime_deps</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; + default is <code>[]</code><br/> + A list of runtime dependencies. + </td> + </tr> + <tr> + <td id="compile.exports"> + <code>exports</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; + default is <code>[]</code><br/> + A list of exports. + </td> + </tr> + <tr> + <td id="compile.plugins"> + <code>plugins</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; + default is <code>[]</code><br/> + A list of plugins. + </td> + </tr> + <tr> + <td id="compile.exported_plugins"> + <code>exported_plugins</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; + default is <code>[]</code><br/> + A list of exported plugins. + </td> + </tr> + <tr> + <td id="compile.native_libraries"> + <code>native_libraries</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../providers/CcInfo.html">CcInfo</a>s; + default is <code>[]</code><br/> + CC native library dependencies that are needed for this library. + </td> + </tr> + <tr> + <td id="compile.annotation_processor_additional_inputs"> + <code>annotation_processor_additional_inputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + A list of inputs that the Java compilation action will take in addition to the Java sources for annotation processing. + </td> + </tr> + <tr> + <td id="compile.annotation_processor_additional_outputs"> + <code>annotation_processor_additional_outputs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + A list of outputs that the Java compilation action will output in addition to the class jar from annotation processing. + </td> + </tr> + <tr> + <td id="compile.strict_deps"> + <code>strict_deps</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + default is <code>'ERROR'</code><br/> + A string that specifies how to handle strict deps. Possible values: 'OFF', 'ERROR', 'WARN' and 'DEFAULT'. For more details see <a href="/docs/user-manual#flag--strict_java_deps"><code>--strict_java_deps<code> flag</a>. By default 'ERROR'. + </td> + </tr> + <tr> + <td id="compile.java_toolchain"> + <code>java_toolchain</code> + </td> + <td> + Info; + required<br/> + A JavaToolchainInfo to be used for this compilation. Mandatory. + </td> + </tr> + <tr> + <td id="compile.bootclasspath"> + <code>bootclasspath</code> + </td> + <td> + default is <code>None</code><br/> + A BootClassPathInfo to be used for this compilation. If present, overrides the bootclasspath associated with the provided java_toolchain. + </td> + </tr> + <tr> + <td id="compile.sourcepath"> + <code>sourcepath</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + + </td> + </tr> + <tr> + <td id="compile.resources"> + <code>resources</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + + </td> + </tr> + <tr> + <td id="compile.resource_jars"> + <code>resource_jars</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + + </td> + </tr> + <tr> + <td id="compile.classpath_resources"> + <code>classpath_resources</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + + </td> + </tr> + <tr> + <td id="compile.neverlink"> + <code>neverlink</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + + </td> + </tr> + <tr> + <td id="compile.enable_annotation_processing"> + <code>enable_annotation_processing</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + Disables annotation processing in this compilation, causing any annotation processors provided in plugins or in exported_plugins of deps to be ignored. + </td> + </tr> + <tr> + <td id="compile.enable_compile_jar_action"> + <code>enable_compile_jar_action</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>True</code><br/> + Enables header compilation or ijar creation. If set to False, it forces use of the full class jar in the compilation classpaths of any dependants. Doing so is intended for use by non-library targets such as binaries that do not have dependants. + </td> + </tr> + <tr> + <td id="compile.add_exports"> + <code>add_exports</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Allow this library to access the given <module>/<package>. + </td> + </tr> + <tr> + <td id="compile.add_opens"> + <code>add_opens</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Allow this library to reflectively access the given <module>/<package>. + </td> + </tr> + </tbody> + </table> + + <h2 id="JavaRuntimeInfo">JavaRuntimeInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> java_common.JavaRuntimeInfo</pre></p> + + The key used to retrieve the provider that contains information about the Java runtime being used. + + <h2 id="JavaToolchainInfo">JavaToolchainInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> java_common.JavaToolchainInfo</pre></p> + + The key used to retrieve the provider that contains information about the Java toolchain being used. + + <h2 id="merge">merge</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> java_common.merge(providers)</pre></p> + + Merges the given providers into a single JavaInfo. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="merge.providers"> + <code>providers</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; + required<br/> + The list of providers to merge. + </td> + </tr> + </tbody> + </table> + + <h2 id="pack_sources">pack_sources</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_common.pack_sources(actions, *, output_source_jar=None, sources=[], source_jars=[], java_toolchain)</pre></p> + + Packs sources and source jars into a single source jar file. The return value is typically passed to<p><code><a class="anchor" href="../providers/JavaInfo.html">JavaInfo</a>#source_jar</code></p>.At least one of parameters output_jar or output_source_jar is required. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="pack_sources.actions"> + <code>actions</code> + </td> + <td> + <a class="anchor" href="../builtins/actions.html">actions</a>; + required<br/> + ctx.actions + </td> + </tr> + <tr> + <td id="pack_sources.output_source_jar"> + <code>output_source_jar</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; + default is <code>None</code><br/> + The output source jar. + </td> + </tr> + <tr> + <td id="pack_sources.sources"> + <code>sources</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + A list of Java source files to be packed into the source jar. + </td> + </tr> + <tr> + <td id="pack_sources.source_jars"> + <code>source_jars</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; + default is <code>[]</code><br/> + A list of source jars to be packed into the source jar. + </td> + </tr> + <tr> + <td id="pack_sources.java_toolchain"> + <code>java_toolchain</code> + </td> + <td> + Info; + required<br/> + A JavaToolchainInfo to used to find the ijar tool. + </td> + </tr> + </tbody> + </table> + + <h2 id="run_ijar">run_ijar</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_common.run_ijar(actions, *, jar, target_label=None, java_toolchain)</pre></p> + + Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding of dependent jars during any recompiles consisting only of simple changes to method implementations. The return value is typically passed to <code><a class="anchor" href="../providers/JavaInfo.html">JavaInfo</a>#compile_jar</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="run_ijar.actions"> + <code>actions</code> + </td> + <td> + <a class="anchor" href="../builtins/actions.html">actions</a>; + required<br/> + ctx.actions + </td> + </tr> + <tr> + <td id="run_ijar.jar"> + <code>jar</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The jar to run ijar on. + </td> + </tr> + <tr> + <td id="run_ijar.target_label"> + <code>target_label</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; or <code>None</code>; + default is <code>None</code><br/> + A target label to stamp the jar with. Used for <code>add_dep</code> support. Typically, you would pass <code>ctx.label</code> to stamp the jar with the current rule's label. + </td> + </tr> + <tr> + <td id="run_ijar.java_toolchain"> + <code>java_toolchain</code> + </td> + <td> + Info; + required<br/> + A JavaToolchainInfo to used to find the ijar tool. + </td> + </tr> + </tbody> + </table> + + <h2 id="stamp_jar">stamp_jar</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_common.stamp_jar(actions, *, jar, target_label, java_toolchain)</pre></p> + + Stamps a jar with a target label for <code>add_dep</code> support. The return value is typically passed to <code><a class="anchor" href="../providers/JavaInfo.html">JavaInfo</a>#compile_jar</code>. Prefer to use <code><a class="anchor" href="#run_ijar">run_ijar</a></code> when possible. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="stamp_jar.actions"> + <code>actions</code> + </td> + <td> + <a class="anchor" href="../builtins/actions.html">actions</a>; + required<br/> + ctx.actions + </td> + </tr> + <tr> + <td id="stamp_jar.jar"> + <code>jar</code> + </td> + <td> + <a class="anchor" href="../builtins/File.html">File</a>; + required<br/> + The jar to run stamp_jar on. + </td> + </tr> + <tr> + <td id="stamp_jar.target_label"> + <code>target_label</code> + </td> + <td> + <a class="anchor" href="../builtins/Label.html">Label</a>; + required<br/> + A target label to stamp the jar with. Used for <code>add_dep</code> support. Typically, you would pass <code>ctx.label</code> to stamp the jar with the current rule's label. + </td> + </tr> + <tr> + <td id="stamp_jar.java_toolchain"> + <code>java_toolchain</code> + </td> + <td> + Info; + required<br/> + A JavaToolchainInfo to used to find the stamp_jar tool. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/native.mdx b/rules/lib/toplevel/native.mdx new file mode 100644 index 0000000..c96a2c2 --- /dev/null +++ b/rules/lib/toplevel/native.mdx @@ -0,0 +1,388 @@ +--- +title: 'native' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.native">native</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A built-in module to support native rules and other package helper functions. All native rules appear as functions in this module, e.g. <code>native.cc_library</code>. Note that the native module is only available in the loading phase (i.e. for macros, not for rule implementations). Attributes will ignore <code>None</code> values, and treat them as if the attribute was unset.<br>The following functions are also available: + +<h2>Members</h2> +<ul> + <li> + <a href="#existing_rule">existing_rule</a> + </li> + <li> + <a href="#existing_rules">existing_rules</a> + </li> + <li> + <a href="#exports_files">exports_files</a> + </li> + <li> + <a href="#glob">glob</a> + </li> + <li> + <a href="#module_name">module_name</a> + </li> + <li> + <a href="#module_version">module_version</a> + </li> + <li> + <a href="#package_default_visibility">package_default_visibility</a> + </li> + <li> + <a href="#package_group">package_group</a> + </li> + <li> + <a href="#package_name">package_name</a> + </li> + <li> + <a href="#package_relative_label">package_relative_label</a> + </li> + <li> + <a href="#repo_name">repo_name</a> + </li> + <li> + <a href="#repository_name">repository_name</a> + </li> + <li> + <a href="#subpackages">subpackages</a> + </li> + </ul> + + <h2 id="existing_rule">existing_rule</h2> + <p><pre class="rule-signature">unknown native.existing_rule(name)</pre></p> + + Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or <code>None</code> if no rule instance of that name exists.<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>, <code>x.keys()</code>, and <code>x.values()</code>.<p>The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's <code>name</code> and <code>kind</code> (for example, <code>'cc_binary'</code>).<p>The values of the result represent attribute values as follows:<ul><li>Attributes of type str, int, and bool are represented as is.</li><li>Labels are converted to strings of the form <code>':foo'</code> for targets in the same package or <code>'//pkg:name'</code> for targets in a different package.</li><li>Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion.</li><li><code>select</code> values are returned with their contents transformed as described above.</li><li>Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.).</li></ul><p>If possible, use this function only in <a href="https://bazel.build/extending/macros#finalizers">implementation functions of rule finalizer symbolic macros</a>. Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes <code>BUILD</code> files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by <code>ctx.attr.foo</code>. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="existing_rule.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The name of the target. + </td> + </tr> + </tbody> + </table> + + <h2 id="existing_rules">existing_rules</h2> + <p><pre class="rule-signature">unknown native.existing_rules()</pre></p> + + Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by <code>existing_rule(name)</code>.<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>, <code>x.keys()</code>, and <code>x.values()</code>.<p>If possible, use this function only in <a href="https://bazel.build/extending/macros#finalizers">implementation functions of rule finalizer symbolic macros</a>. Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes <code>BUILD</code> files brittle and order-dependent. + + <h2 id="exports_files">exports_files</h2> + <p><pre class="rule-signature"><code>None</code> native.exports_files(srcs, visibility=None, licenses=None)</pre></p> + + Specifies a list of files belonging to this package that are exported to other packages. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="exports_files.srcs"> + <code>srcs</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The list of files to export. + </td> + </tr> + <tr> + <td id="exports_files.visibility"> + <code>visibility</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; + default is <code>None</code><br/> + A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. + </td> + </tr> + <tr> + <td id="exports_files.licenses"> + <code>licenses</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; + default is <code>None</code><br/> + Licenses to be specified. + </td> + </tr> + </tbody> + </table> + + <h2 id="glob">glob</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> native.glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)</pre></p> + + Glob returns a new, mutable, sorted list of every file in the current package that:<ul> +<li>Matches at least one pattern in <code>include</code>.</li> +<li>Does not match any of the patterns in <code>exclude</code> (default <code>[]</code>).</li></ul> +If the <code>exclude_directories</code> argument is enabled (set to <code>1</code>), files of type directory will be omitted from the results (default <code>1</code>). + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="glob.include"> + <code>include</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + The list of glob patterns to include. + </td> + </tr> + <tr> + <td id="glob.exclude"> + <code>exclude</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + The list of glob patterns to exclude. + </td> + </tr> + <tr> + <td id="glob.exclude_directories"> + <code>exclude_directories</code> + </td> + <td> + <a class="anchor" href="../core/int.html">int</a>; + default is <code>1</code><br/> + A flag whether to exclude directories or not. + </td> + </tr> + <tr> + <td id="glob.allow_empty"> + <code>allow_empty</code> + </td> + <td> + default is <code>unbound</code><br/> + Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). + </td> + </tr> + </tbody> + </table> + + <h2 id="module_name">module_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.module_name()</pre></p> + + The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the <code>module.name</code> field seen in <code>module_ctx.modules</code>. + May return <code>None</code>. + + <h2 id="module_version">module_version</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.module_version()</pre></p> + + The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the <code>module.version</code> field seen in <code>module_ctx.modules</code>. + May return <code>None</code>. + + <h2 id="package_default_visibility">package_default_visibility</h2> + <p><pre class="rule-signature">List native.package_default_visibility()</pre></p> + + Returns the default visibility of the package being evaluated. This is the value of the <code>default_visibility</code> parameter of <code>package()</code>, extended to include the package itself. + + <h2 id="package_group">package_group</h2> + <p><pre class="rule-signature"><code>None</code> native.package_group(*, name, packages=[], includes=[])</pre></p> + + This function defines a set of packages and assigns a label to the group. The label can be referenced in <code>visibility</code> attributes. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="package_group.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + The unique name for this rule. + </td> + </tr> + <tr> + <td id="package_group.packages"> + <code>packages</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A complete enumeration of packages in this group. + </td> + </tr> + <tr> + <td id="package_group.includes"> + <code>includes</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + Other package groups that are included in this one. + </td> + </tr> + </tbody> + </table> + + <h2 id="package_name">package_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.package_name()</pre></p> + + The name of the package being evaluated, without the repository name. For example, in the BUILD file <code>some/package/BUILD</code>, its value will be <code>some/package</code>. If the BUILD file calls a function defined in a .bzl file, <code>package_name()</code> will match the caller BUILD file package. The value will always be an empty string for the root package. + + <h2 id="package_relative_label">package_relative_label</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> native.package_relative_label(input)</pre></p> + + Converts the input string into a <a href='../builtins/Label.html'>Label</a> object, in the context of the package currently being initialized (that is, the <code>BUILD</code> file for which the current macro is executing). If the input is already a <code>Label</code>, it is returned unchanged.<p>This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. <p>The result of this function is the same <code>Label</code> value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file. <p><i>Usage note:</i> The difference between this function and <a href='../builtins/Label.html#Label'>Label()</a></code> is that <code>Label()</code> uses the context of the package of the <code>.bzl</code> file that called it, not the package of the <code>BUILD</code> file. Use <code>Label()</code> when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use <code>package_relative_label()</code> when you need to normalize a label string supplied by the BUILD file to a <code>Label</code> object. (There is no way to convert a string to a <code>Label</code> in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="package_relative_label.input"> + <code>input</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; + required<br/> + The input label string or Label object. If a Label object is passed, it's returned as is. + </td> + </tr> + </tbody> + </table> + + <h2 id="repo_name">repo_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.repo_name()</pre></p> + + The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. + + <h2 id="repository_name">repository_name</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.repository_name()</pre></p> + + <b>Experimental</b>. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--+incompatible_enable_deprecated_label_apis</code> <br><strong>Deprecated.</strong> Prefer to use <a href="#repo_name"><code>repo_name</code></a> instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise.<p>The canonical name of the repository containing the package currently being evaluated, with a single at-sign (<code>@</code>) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza <code>local_repository(name='local', path=...)</code> it will be set to <code>@local</code>. In packages in the main repository, it will be set to <code>@</code>. + + <h2 id="subpackages">subpackages</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> native.subpackages(*, include, exclude=[], allow_empty=False)</pre></p> + + Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel_skylib.subpackages module rather than calling this function directly. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="subpackages.include"> + <code>include</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + required<br/> + The list of glob patterns to include in subpackages scan. + </td> + </tr> + <tr> + <td id="subpackages.exclude"> + <code>exclude</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + The list of glob patterns to exclude from subpackages scan. + </td> + </tr> + <tr> + <td id="subpackages.allow_empty"> + <code>allow_empty</code> + </td> + <td> + <a class="anchor" href="../core/bool.html">bool</a>; + default is <code>False</code><br/> + Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/platform_common.mdx b/rules/lib/toplevel/platform_common.mdx new file mode 100644 index 0000000..0fe55bc --- /dev/null +++ b/rules/lib/toplevel/platform_common.mdx @@ -0,0 +1,68 @@ +--- +title: 'platform_common' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.platform_common">platform_common</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Functions for Starlark to interact with the platform APIs. + +<h2>Members</h2> +<ul> + <li> + <a href="#ConstraintSettingInfo">ConstraintSettingInfo</a> + </li> + <li> + <a href="#ConstraintValueInfo">ConstraintValueInfo</a> + </li> + <li> + <a href="#PlatformInfo">PlatformInfo</a> + </li> + <li> + <a href="#TemplateVariableInfo">TemplateVariableInfo</a> + </li> + <li> + <a href="#ToolchainInfo">ToolchainInfo</a> + </li> + </ul> + + <h2 id="ConstraintSettingInfo">ConstraintSettingInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.ConstraintSettingInfo</pre></p> + + The constructor/key for the <a href='../providers/ConstraintSettingInfo.html'>ConstraintSettingInfo</a> provider.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> + + <h2 id="ConstraintValueInfo">ConstraintValueInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.ConstraintValueInfo</pre></p> + + The constructor/key for the <a href='../providers/ConstraintValueInfo.html'>ConstraintValueInfo</a> provider.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> + + <h2 id="PlatformInfo">PlatformInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.PlatformInfo</pre></p> + + The constructor/key for the <a href='../providers/PlatformInfo.html'>PlatformInfo</a> provider.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> + + <h2 id="TemplateVariableInfo">TemplateVariableInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.TemplateVariableInfo</pre></p> + + The constructor/key for the <a href='../providers/TemplateVariableInfo.html'>TemplateVariableInfo</a> provider. + + <h2 id="ToolchainInfo">ToolchainInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.ToolchainInfo</pre></p> + + The constructor/key for the <a href='../providers/ToolchainInfo.html'>ToolchainInfo</a> provider. + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/proto.mdx b/rules/lib/toplevel/proto.mdx new file mode 100644 index 0000000..8ff60a7 --- /dev/null +++ b/rules/lib/toplevel/proto.mdx @@ -0,0 +1,115 @@ +--- +title: 'proto' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.proto">proto</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/packages/Proto.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +A module for protocol message processing. + +<h2>Members</h2> +<ul> + <li> + <a href="#encode_text">encode_text</a> + </li> + </ul> + + <h2 id="encode_text">encode_text</h2> + <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> proto.encode_text(x)</pre></p> + + Returns the struct argument's encoding as a text-format protocol message. +The data structure must be recursively composed of strings, ints, floats, or bools, or structs, sequences, and dicts of these types. +<p>A struct is converted to a message. Fields are emitted in name order. +Each struct field whose value is None is ignored. +<p>A sequence (such as a list or tuple) is converted to a repeated field. +Its elements must not be sequences or dicts. +<p>A dict is converted to a repeated field of messages with fields named 'key' and 'value'. +Entries are emitted in iteration (insertion) order. +The dict's keys must be strings or ints, and its values must not be sequences or dicts. +Examples:<br><pre class=language-python>proto.encode_text(struct(field=123)) +# field: 123 + +proto.encode_text(struct(field=True)) +# field: true + +proto.encode_text(struct(field=[1, 2, 3])) +# field: 1 +# field: 2 +# field: 3 + +proto.encode_text(struct(field='text', ignored_field=None)) +# field: "text" + +proto.encode_text(struct(field=struct(inner_field='text', ignored_field=None))) +# field { +# inner_field: "text" +# } + +proto.encode_text(struct(field=[struct(inner_field=1), struct(inner_field=2)])) +# field { +# inner_field: 1 +# } +# field { +# inner_field: 2 +# } + +proto.encode_text(struct(field=struct(inner_field=struct(inner_inner_field='text')))) +# field { +# inner_field { +# inner_inner_field: "text" +# } +# } + +proto.encode_text(struct(foo={4: 3, 2: 1})) +# foo: { +# key: 4 +# value: 3 +# } +# foo: { +# key: 2 +# value: 1 +# } +</pre> + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="encode_text.x"> + <code>x</code> + </td> + <td> + structure; or NativeInfo; + required<br/> + + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> diff --git a/rules/lib/toplevel/testing.mdx b/rules/lib/toplevel/testing.mdx new file mode 100644 index 0000000..17d4e68 --- /dev/null +++ b/rules/lib/toplevel/testing.mdx @@ -0,0 +1,166 @@ +--- +title: 'testing' +--- + +<html devsite> +<head> + <meta name="project_path" value="/_project.yaml"> + <meta name="book_path" value="/_book.yaml"> +</head> +<body> + +<h1 class="page-title" id="modules.testing">testing</h1> + +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java" %} +{% include "_buttons.html" %} +<!-- {% raw %} --> + +Helper methods for Starlark to access testing infrastructure. + +<h2>Members</h2> +<ul> + <li> + <a href="#analysis_test">analysis_test</a> + </li> + <li> + <a href="#ExecutionInfo">ExecutionInfo</a> + </li> + <li> + <a href="#TestEnvironment">TestEnvironment</a> + </li> + </ul> + + <h2 id="analysis_test">analysis_test</h2> + <p><pre class="rule-signature"><code>None</code> testing.analysis_test(name, implementation, attrs={}, fragments=[], toolchains=[], attr_values={})</pre></p> + + Creates a new analysis test target. <p>The number of transitive dependencies of the test are limited. The limit is controlled by <code>--analysis_testing_deps_limit</code> flag. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="analysis_test.name"> + <code>name</code> + </td> + <td> + <a class="anchor" href="../core/string.html">string</a>; + required<br/> + Name of the target. It should be a Starlark identifier, matching pattern '[A-Za-z_][A-Za-z0-9_]*'. + </td> + </tr> + <tr> + <td id="analysis_test.implementation"> + <code>implementation</code> + </td> + <td> + <a class="anchor" href="../core/function.html">function</a>; + required<br/> + The Starlark function implementing this analysis test. It must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. The function is called during the analysis phase. It can access the attributes declared by <code>attrs</code> and populated via <code>attr_values</code>. The implementation function may not register actions. Instead, it must register a pass/fail result via providing <a href='../providers/AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>. + </td> + </tr> + <tr> + <td id="analysis_test.attrs"> + <code>attrs</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + default is <code>{}</code><br/> + Dictionary declaring the attributes. See the <a href="../globals/bzl.html#rule">rule</a> call. Attributes are allowed to use configuration transitions defined using <a href="../globals/bzl.html#analysis_test_transition">analysis_test_transition</a>. + </td> + </tr> + <tr> + <td id="analysis_test.fragments"> + <code>fragments</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + List of configuration fragments that are available to the implementation of the analysis test. + </td> + </tr> + <tr> + <td id="analysis_test.toolchains"> + <code>toolchains</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a>; + default is <code>[]</code><br/> + The set of toolchains the test requires. See the <a href="../globals/bzl.html#rule">rule</a> call. + </td> + </tr> + <tr> + <td id="analysis_test.attr_values"> + <code>attr_values</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>{}</code><br/> + Dictionary of attribute values to pass to the implementation. + </td> + </tr> + </tbody> + </table> + + <h2 id="ExecutionInfo">ExecutionInfo</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/ExecutionInfo.html">ExecutionInfo</a> testing.ExecutionInfo</pre></p> + + <a href='../providers/ExecutionInfo.html'>testing.ExecutionInfo</a> provider key/constructor + + <h2 id="TestEnvironment">TestEnvironment</h2> + <p><pre class="rule-signature"><a class="anchor" href="../providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> testing.TestEnvironment(environment, inherited_environment=[])</pre></p> + + <b>Deprecated: Use RunEnvironmentInfo instead.</b> Creates a new test environment provider. Use this provider to specify extra environment variables to be made available during test execution. + <!-- hide-from-toc is a class used by DevSite for the public Bazel site + (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> + <h3 class="hide-from-toc">Parameters</h3> + <table class="table table-bordered table-condensed table-params"> + <colgroup> + <col class="col-param"> + <col class="param-description"> + </colgroup> + <thead> + <tr> + <th>Parameter</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="TestEnvironment.environment"> + <code>environment</code> + </td> + <td> + <a class="anchor" href="../core/dict.html">dict</a>; + required<br/> + A map of string keys and values that represent environment variables and their values. These will be made available during the test execution. + </td> + </tr> + <tr> + <td id="TestEnvironment.inherited_environment"> + <code>inherited_environment</code> + </td> + <td> + <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; + default is <code>[]</code><br/> + A sequence of names of environment variables. These variables are made available during the test execution with their current value taken from the shell environment. If a variable is contained in both <code>environment</code> and <code>inherited_environment</code>, the value inherited from the shell environment will take precedence if set. + </td> + </tr> + </tbody> + </table> + + +</body> +</html> + +<!-- {% endraw %} --> From 59a29d537b8fa3b75e28f01330413e85b7c540b8 Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sat, 4 Oct 2025 14:29:17 -0700 Subject: [PATCH 05/14] use html -> mdx pandoc converter --- .github/workflows/pull-from-bazel-build.yml | 7 +- process-reference-docs.sh | 106 +- reference/be/be-nav.mdx | 83 +- reference/be/c-cpp.mdx | 4176 ++- reference/be/common-definitions.mdx | 1568 +- reference/be/extra-actions.mdx | 507 +- reference/be/functions.mdx | 1016 +- reference/be/general.mdx | 2357 +- reference/be/java.mdx | 3720 +-- reference/be/make-variables.mdx | 861 +- reference/be/objective-c.mdx | 703 +- reference/be/overview.mdx | 451 +- reference/be/platforms-and-toolchains.mdx | 1040 +- reference/be/protocol-buffer.mdx | 1082 +- reference/be/python.mdx | 1531 +- reference/be/shell.mdx | 507 +- reference/command-line-reference.mdx | 24104 ++++++++-------- rules/lib/builtins.mdx | 194 +- rules/lib/builtins/Action.mdx | 136 +- rules/lib/builtins/Args.mdx | 733 +- rules/lib/builtins/Aspect.mdx | 23 +- rules/lib/builtins/Attribute.mdx | 22 +- rules/lib/builtins/BuildSetting.mdx | 20 +- rules/lib/builtins/CcCompilationOutputs.mdx | 44 +- rules/lib/builtins/CcLinkingOutputs.mdx | 48 +- rules/lib/builtins/CompilationContext.mdx | 187 +- rules/lib/builtins/DirectoryExpander.mdx | 91 +- rules/lib/builtins/DottedVersion.mdx | 87 +- rules/lib/builtins/ExecGroupCollection.mdx | 20 +- rules/lib/builtins/ExecGroupContext.mdx | 33 +- rules/lib/builtins/ExecTransitionFactory.mdx | 20 +- rules/lib/builtins/ExpandedDirectory.mdx | 44 +- rules/lib/builtins/FeatureConfiguration.mdx | 20 +- rules/lib/builtins/File.mdx | 165 +- rules/lib/builtins/Label.mdx | 347 +- rules/lib/builtins/LateBoundDefault.mdx | 22 +- rules/lib/builtins/LibraryToLink.mdx | 229 +- rules/lib/builtins/License.mdx | 20 +- rules/lib/builtins/LinkerInput.mdx | 70 +- rules/lib/builtins/LinkingContext.mdx | 33 +- rules/lib/builtins/Provider.mdx | 37 +- rules/lib/builtins/Subrule.mdx | 20 +- rules/lib/builtins/SymlinkEntry.mdx | 44 +- rules/lib/builtins/Target.mdx | 32 +- rules/lib/builtins/TemplateDict.mdx | 248 +- rules/lib/builtins/ToolchainContext.mdx | 22 +- rules/lib/builtins/actions.mdx | 1679 +- rules/lib/builtins/apple_platform.mdx | 90 +- rules/lib/builtins/bazel_module.mdx | 70 +- rules/lib/builtins/bazel_module_tags.mdx | 23 +- rules/lib/builtins/configuration.mdx | 89 +- rules/lib/builtins/ctx.mdx | 1182 +- rules/lib/builtins/depset.mdx | 97 +- rules/lib/builtins/exec_result.mdx | 57 +- rules/lib/builtins/extension_metadata.mdx | 20 +- rules/lib/builtins/fragments.mdx | 22 +- .../builtins/java_annotation_processing.mdx | 113 +- rules/lib/builtins/macro.mdx | 25 +- rules/lib/builtins/mapped_root.mdx | 33 +- rules/lib/builtins/module_ctx.mdx | 1494 +- rules/lib/builtins/path.mdx | 246 +- rules/lib/builtins/propagation_ctx.mdx | 46 +- rules/lib/builtins/repo_metadata.mdx | 23 +- rules/lib/builtins/repository_ctx.mdx | 1971 +- rules/lib/builtins/repository_os.mdx | 58 +- rules/lib/builtins/repository_rule.mdx | 23 +- rules/lib/builtins/root.mdx | 33 +- rules/lib/builtins/rule.mdx | 25 +- rules/lib/builtins/rule_attributes.mdx | 134 +- rules/lib/builtins/runfiles.mdx | 232 +- rules/lib/builtins/struct.mdx | 97 +- rules/lib/builtins/subrule_ctx.mdx | 70 +- rules/lib/builtins/tag_class.mdx | 23 +- rules/lib/builtins/template_ctx.mdx | 277 +- rules/lib/builtins/toolchain_type.mdx | 44 +- rules/lib/builtins/transition.mdx | 122 +- rules/lib/builtins/wasm_exec_result.mdx | 65 +- rules/lib/builtins/wasm_module.mdx | 35 +- rules/lib/core.mdx | 54 +- rules/lib/core/bool.mdx | 22 +- rules/lib/core/builtin_function_or_method.mdx | 20 +- rules/lib/core/dict.mdx | 482 +- rules/lib/core/float.mdx | 20 +- rules/lib/core/function.mdx | 20 +- rules/lib/core/int.mdx | 25 +- rules/lib/core/json.mdx | 381 +- rules/lib/core/list.mdx | 489 +- rules/lib/core/range.mdx | 34 +- rules/lib/core/set.mdx | 1235 +- rules/lib/core/string.mdx | 1831 +- rules/lib/core/tuple.mdx | 44 +- rules/lib/fragments.mdx | 53 +- rules/lib/fragments/apple.mdx | 103 +- rules/lib/fragments/bazel_android.mdx | 34 +- rules/lib/fragments/bazel_py.mdx | 45 +- rules/lib/fragments/coverage.mdx | 41 +- rules/lib/fragments/cpp.mdx | 145 +- rules/lib/fragments/j2objc.mdx | 33 +- rules/lib/fragments/java.mdx | 200 +- rules/lib/fragments/objc.mdx | 154 +- rules/lib/fragments/platform.mdx | 44 +- rules/lib/fragments/proto.mdx | 20 +- rules/lib/fragments/py.mdx | 109 +- rules/lib/globals.mdx | 32 +- rules/lib/globals/all.mdx | 2087 +- rules/lib/globals/build.mdx | 953 +- rules/lib/globals/bzl.mdx | 2404 +- rules/lib/globals/module.mdx | 1566 +- rules/lib/globals/repo.mdx | 134 +- rules/lib/globals/vendor.mdx | 132 +- rules/lib/overview.mdx | 1236 +- rules/lib/providers.mdx | 102 +- .../lib/providers/AnalysisTestResultInfo.mdx | 119 +- rules/lib/providers/CcInfo.mdx | 135 +- rules/lib/providers/CcToolchainConfigInfo.mdx | 20 +- rules/lib/providers/CcToolchainInfo.mdx | 479 +- rules/lib/providers/ConstraintCollection.mdx | 23 +- rules/lib/providers/ConstraintSettingInfo.mdx | 36 +- rules/lib/providers/ConstraintValueInfo.mdx | 23 +- rules/lib/providers/DebugPackageInfo.mdx | 207 +- rules/lib/providers/DefaultInfo.mdx | 238 +- rules/lib/providers/ExecutionInfo.mdx | 119 +- rules/lib/providers/FeatureFlagInfo.mdx | 107 +- rules/lib/providers/FilesToRunProvider.mdx | 64 +- .../IncompatiblePlatformProvider.mdx | 22 +- rules/lib/providers/InstrumentedFilesInfo.mdx | 46 +- rules/lib/providers/JavaRuntimeInfo.mdx | 167 +- rules/lib/providers/JavaToolchainInfo.mdx | 165 +- rules/lib/providers/MaterializedDepsInfo.mdx | 33 +- rules/lib/providers/ObjcProvider.mdx | 109 +- rules/lib/providers/OutputGroupInfo.mdx | 96 +- .../providers/PackageSpecificationInfo.mdx | 87 +- rules/lib/providers/PlatformInfo.mdx | 23 +- rules/lib/providers/RunEnvironmentInfo.mdx | 44 +- rules/lib/providers/TemplateVariableInfo.mdx | 35 +- rules/lib/providers/ToolchainInfo.mdx | 22 +- rules/lib/providers/ToolchainTypeInfo.mdx | 36 +- rules/lib/providers/file_provider.mdx | 20 +- rules/lib/providers/java_compilation_info.mdx | 70 +- rules/lib/providers/java_output_jars.mdx | 61 +- rules/lib/toplevel.mdx | 47 +- rules/lib/toplevel/apple_common.mdx | 336 +- rules/lib/toplevel/attr.mdx | 2168 +- rules/lib/toplevel/cc_common.mdx | 3398 +-- rules/lib/toplevel/config.mdx | 496 +- rules/lib/toplevel/config_common.mdx | 120 +- rules/lib/toplevel/coverage_common.mdx | 155 +- rules/lib/toplevel/java_common.mdx | 954 +- rules/lib/toplevel/native.mdx | 707 +- rules/lib/toplevel/platform_common.mdx | 86 +- rules/lib/toplevel/proto.mdx | 99 +- rules/lib/toplevel/testing.mdx | 265 +- 152 files changed, 34966 insertions(+), 46103 deletions(-) diff --git a/.github/workflows/pull-from-bazel-build.yml b/.github/workflows/pull-from-bazel-build.yml index 185838c..f4afaf0 100644 --- a/.github/workflows/pull-from-bazel-build.yml +++ b/.github/workflows/pull-from-bazel-build.yml @@ -47,7 +47,12 @@ jobs: with: bazelisk-cache: true repository-cache: true - + + - name: Install pandoc + run: | + sudo apt-get update + sudo apt-get install -y pandoc + - name: Build reference documentation working-directory: upstream run: > diff --git a/process-reference-docs.sh b/process-reference-docs.sh index 9544e2f..4550598 100755 --- a/process-reference-docs.sh +++ b/process-reference-docs.sh @@ -2,6 +2,7 @@ # Script to process Bazel reference documentation from reference-docs.zip # Usage: ./process-reference-docs.sh <path-to-reference-docs.zip> +# Requirements: pandoc must be installed (brew install pandoc or apt-get install pandoc) set -o errexit -o nounset -o pipefail @@ -17,6 +18,16 @@ if [ ! -f "$ZIP_FILE" ]; then exit 1 fi +# Check if pandoc is installed +if ! command -v pandoc &> /dev/null; then + echo "Error: pandoc is not installed" + echo "Please install it first:" + echo " - macOS: brew install pandoc" + echo " - Ubuntu/Debian: sudo apt-get install pandoc" + echo " - Other: https://pandoc.org/installing.html" + exit 1 +fi + echo "Processing reference documentation from $ZIP_FILE..." # Create temporary directory for extraction @@ -42,6 +53,42 @@ if [ -n "$nested_zips" ]; then exit 1 fi +# Function to convert HTML to MDX using pandoc +html_to_mdx() { + local input_file="$1" + local output_file="$2" + + # Extract title from HTML + local title=$(grep -oP '<title>\K[^<]+' "$input_file" 2>/dev/null || echo "$(basename "${input_file%.html}")") + title=$(echo "$title" | sed "s/'/'\\\''/g") + + # Create temporary markdown file + local temp_md=$(mktemp) + + # Convert HTML to Markdown using pandoc + # Options: + # -f html: input format is HTML + # -t gfm: output format is GitHub Flavored Markdown + # --wrap=preserve: preserve line wrapping + # --extract-media=.: extract images to current directory (if any) + pandoc -f html -t gfm --wrap=preserve "$input_file" -o "$temp_md" 2>/dev/null || { + echo "Warning: pandoc conversion failed for $(basename "$input_file"), using fallback" + # Fallback: just copy the HTML content + cat "$input_file" > "$temp_md" + } + + # Write MDX file with frontmatter + { + echo "---" + echo "title: '$title'" + echo "---" + echo "" + cat "$temp_md" + } > "$output_file" + + rm "$temp_md" +} + # Process reference/be/ HTML files and convert to MDX echo "Processing Build Encyclopedia (reference/be/) files..." if [ -d "$TEMP_DIR/reference/be" ]; then @@ -54,25 +101,7 @@ if [ -d "$TEMP_DIR/reference/be" ]; then mdx_file="reference/be/${basename_file%.html}.mdx" echo " Converting $(basename "$html_file") to MDX..." - - # Extract title from HTML and create basic MDX structure - # This is a simple conversion - may need refinement - title=$(grep -oP '<title>\K[^<]+' "$html_file" 2>/dev/null || echo "$(basename "${html_file%.html}")") - - # Create MDX file with frontmatter - # Clean up the title to avoid issues with quotes - title=$(echo "$title" | sed "s/'/'\\\''/g") - - { - echo "---" - echo "title: '$title'" - echo "---" - echo "" - # For now, we'll keep the HTML content as-is - # The transform-docs.awk can be enhanced later for HTML->MDX conversion - cat "$html_file" - } > "$mdx_file" - + html_to_mdx "$html_file" "$mdx_file" echo " Created $mdx_file" fi done @@ -84,18 +113,9 @@ fi echo "Processing command-line reference..." if [ -f "$TEMP_DIR/reference/command-line-reference.html" ]; then mkdir -p reference - - title=$(grep -oP '<title>\K[^<]+' "$TEMP_DIR/reference/command-line-reference.html" 2>/dev/null || echo "Command-Line Reference") - title=$(echo "$title" | sed "s/'/'\\\''/g") - - { - echo "---" - echo "title: '$title'" - echo "---" - echo "" - cat "$TEMP_DIR/reference/command-line-reference.html" - } > "reference/command-line-reference.mdx" - + + echo " Converting command-line-reference.html to MDX..." + html_to_mdx "$TEMP_DIR/reference/command-line-reference.html" "reference/command-line-reference.mdx" echo " Created reference/command-line-reference.mdx" else echo "Warning: command-line-reference.html not found in zip" @@ -106,7 +126,8 @@ echo "Processing Starlark library documentation..." if [ -d "$TEMP_DIR/rules/lib" ]; then mkdir -p rules/lib - # Copy HTML files and convert to MDX + # Convert HTML files to MDX + file_count=0 find "$TEMP_DIR/rules/lib" -name "*.html" -type f | while read -r html_file; do relative_path="${html_file#$TEMP_DIR/rules/lib/}" mdx_file="rules/lib/${relative_path%.html}.mdx" @@ -114,26 +135,21 @@ if [ -d "$TEMP_DIR/rules/lib" ]; then # Create directory structure mkdir -p "$(dirname "$mdx_file")" - title=$(grep -oP '<title>\K[^<]+' "$html_file" 2>/dev/null || echo "$(basename "${html_file%.html}")") - title=$(echo "$title" | sed "s/'/'\\\''/g") - - { - echo "---" - echo "title: '$title'" - echo "---" - echo "" - cat "$html_file" - } > "$mdx_file" - - echo " Created $mdx_file" + html_to_mdx "$html_file" "$mdx_file" + file_count=$((file_count + 1)) done + + echo " Converted Starlark library documentation" else echo "Warning: No rules/lib/ directory found in zip" fi +echo "" echo "Reference documentation processing complete!" echo "" echo "Summary:" echo " - Build Encyclopedia: reference/be/*.mdx" echo " - Command-Line Reference: reference/command-line-reference.mdx" -echo " - Starlark Library: rules/lib/**/*.mdx" \ No newline at end of file +echo " - Starlark Library: rules/lib/**/*.mdx" +echo "" +echo "All files have been converted from HTML to Markdown format." \ No newline at end of file diff --git a/reference/be/be-nav.mdx b/reference/be/be-nav.mdx index beb817b..c19b399 100644 --- a/reference/be/be-nav.mdx +++ b/reference/be/be-nav.mdx @@ -2,56 +2,33 @@ title: 'be-nav' --- - -**Build Encyclopedia** - -<ul class="sidebar-nav"> - <li><a href="/reference/be/overview.html">Overview</a></li> - - <li> - - <a data-toggle="collapse" href="#be-menu" aria-expanded="false" - aria-controls="be-menu"> - Concepts <span class="caret"></span> - </a> - <ul class="collapse sidebar-nav sidebar-submenu" id="be-menu"> - <li><a href="/reference/be/common-definitions.html">Common Definitions</a></li> - <li><a href="/reference/be/make-variables.html">"Make" variables</a></li> - </ul> - </li> - - <li> - - <a data-toggle="collapse" href="#be-rules" aria-expanded="false" - aria-controls="be-rules"> - Rules <span class="caret"></span> - </a> - <ul class="collapse sidebar-nav sidebar-submenu" id="be-rules"> - <li><a href="/reference/be/functions.html">Functions</a></li> - <li><a href="/reference/be/c-cpp.html">C / C++</a></li> - <li><a href="/reference/be/java.html">Java</a></li> - <li><a href="/reference/be/objective-c.html">Objective-C</a></li> - <li><a href="/reference/be/protocol-buffer.html">Protocol Buffer</a></li> - <li><a href="/reference/be/python.html">Python</a></li> - <li><a href="/reference/be/shell.html">Shell</a></li> - <li><a href="/reference/be/extra-actions.html">Extra Actions</a></li> - <li><a href="/reference/be/general.html">General</a></li> - <li><a href="/reference/be/platforms-and-toolchains.html">Platforms and Toolchains</a></li> - - <li><a href="https://github.com/bazelbuild/rules_appengine" target="_blank" rel="noopener">AppEngine</a></li> - <li><a href="https://github.com/bazelbuild/rules_apple" target="_blank" rel="noopener">Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)</a></li> - <li><a href="https://github.com/bazelbuild/rules_dotnet" target="_blank" rel="noopener">C#</a></li> - <li><a href="https://github.com/bazelbuild/rules_d" target="_blank" rel="noopener">D</a></li> - <li><a href="https://github.com/bazelbuild/rules_docker" target="_blank" rel="noopener">Docker</a></li> - <li><a href="https://github.com/bazelbuild/rules_groovy" target="_blank" rel="noopener">Groovy</a></li> - <li><a href="https://github.com/bazelbuild/rules_go" target="_blank" rel="noopener">Go</a></li> - <li><a href="https://github.com/bazelbuild/rules_closure" target="_blank" rel="noopener">JavaScript (Closure)</a></li> - <li><a href="https://github.com/bazelbuild/rules_jsonnet" target="_blank" rel="noopener">Jsonnet</a></li> - <li><a href="/reference/be/pkg.html">Packaging</a></li> - <li><a href="https://github.com/bazelbuild/rules_rust" target="_blank" rel="noopener">Rust</a></li> - <li><a href="https://github.com/bazelbuild/rules_sass" target="_blank" rel="noopener">Sass</a></li> - <li><a href="https://github.com/bazelbuild/rules_scala" target="_blank" rel="noopener">Scala</a></li> - </ul> - </li> - -</ul> +\*\*Build Encyclopedia\*\* + +- [Overview](/reference/be/overview.html) +- <a href="#be-menu" data-toggle="collapse" aria-expanded="false" aria-controls="be-menu">Concepts <span class="caret"></span></a> + - [Common Definitions](/reference/be/common-definitions.html) + - ["Make" variables](/reference/be/make-variables.html) +- <a href="#be-rules" data-toggle="collapse" aria-expanded="false" aria-controls="be-rules">Rules <span class="caret"></span></a> + - [Functions](/reference/be/functions.html) + - [C / C++](/reference/be/c-cpp.html) + - [Java](/reference/be/java.html) + - [Objective-C](/reference/be/objective-c.html) + - [Protocol Buffer](/reference/be/protocol-buffer.html) + - [Python](/reference/be/python.html) + - [Shell](/reference/be/shell.html) + - [Extra Actions](/reference/be/extra-actions.html) + - [General](/reference/be/general.html) + - [Platforms and Toolchains](/reference/be/platforms-and-toolchains.html) + - <a href="https://github.com/bazelbuild/rules_appengine" target="_blank" rel="noopener">AppEngine</a> + - <a href="https://github.com/bazelbuild/rules_apple" target="_blank" rel="noopener">Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)</a> + - <a href="https://github.com/bazelbuild/rules_dotnet" target="_blank" rel="noopener">C#</a> + - <a href="https://github.com/bazelbuild/rules_d" target="_blank" rel="noopener">D</a> + - <a href="https://github.com/bazelbuild/rules_docker" target="_blank" rel="noopener">Docker</a> + - <a href="https://github.com/bazelbuild/rules_groovy" target="_blank" rel="noopener">Groovy</a> + - <a href="https://github.com/bazelbuild/rules_go" target="_blank" rel="noopener">Go</a> + - <a href="https://github.com/bazelbuild/rules_closure" target="_blank" rel="noopener">JavaScript (Closure)</a> + - <a href="https://github.com/bazelbuild/rules_jsonnet" target="_blank" rel="noopener">Jsonnet</a> + - [Packaging](/reference/be/pkg.html) + - <a href="https://github.com/bazelbuild/rules_rust" target="_blank" rel="noopener">Rust</a> + - <a href="https://github.com/bazelbuild/rules_sass" target="_blank" rel="noopener">Sass</a> + - <a href="https://github.com/bazelbuild/rules_scala" target="_blank" rel="noopener">Scala</a> diff --git a/reference/be/c-cpp.mdx b/reference/be/c-cpp.mdx index 1b436d4..9451859 100644 --- a/reference/be/c-cpp.mdx +++ b/reference/be/c-cpp.mdx @@ -2,347 +2,215 @@ title: 'c-cpp' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">C / C++ Rules</h1> +# C / C++ Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} +{% include "\_buttons.html" %} +## Rules +- [cc_binary](#cc_binary) +- [cc_import](#cc_import) +- [cc_library](#cc_library) +- [cc_shared_library](#cc_shared_library) +- [cc_static_library](#cc_static_library) +- [cc_test](#cc_test) +- [cc_toolchain](#cc_toolchain) +- [fdo_prefetch_hints](#fdo_prefetch_hints) +- [fdo_profile](#fdo_profile) +- [memprof_profile](#memprof_profile) +- [propeller_optimize](#propeller_optimize) +## cc_binary -<h2>Rules</h2> -<ul> - <li> - <a href="#cc_binary"> - cc_binary </a> - </li> - <li> - <a href="#cc_import"> - cc_import </a> - </li> - <li> - <a href="#cc_library"> - cc_library </a> - </li> - <li> - <a href="#cc_shared_library"> - cc_shared_library </a> - </li> - <li> - <a href="#cc_static_library"> - cc_static_library </a> - </li> - <li> - <a href="#cc_test"> - cc_test </a> - </li> - <li> - <a href="#cc_toolchain"> - cc_toolchain </a> - </li> - <li> - <a href="#fdo_prefetch_hints"> - fdo_prefetch_hints </a> - </li> - <li> - <a href="#fdo_profile"> - fdo_profile </a> - </li> - <li> - <a href="#memprof_profile"> - memprof_profile </a> - </li> - <li> - <a href="#propeller_optimize"> - propeller_optimize </a> - </li> -</ul> - - <h2 id="cc_binary"> - cc_binary - </h2> +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_binary.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_binary.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +``` rule-signature +cc_binary(name, deps, srcs, data, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local_defines, malloc, module_interfaces, nocopts, output_licenses, package_metadata, reexport_deps, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file) +``` - <pre class="rule-signature">cc_binary(<a href="#cc_binary.name">name</a>, <a href="#cc_binary.deps">deps</a>, <a href="#cc_binary.srcs">srcs</a>, <a href="#cc_binary.data">data</a>, <a href="#cc_binary.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_binary.conlyopts">conlyopts</a>, <a href="#cc_binary.copts">copts</a>, <a href="#cc_binary.cxxopts">cxxopts</a>, <a href="#cc_binary.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#cc_binary.distribs">distribs</a>, <a href="#cc_binary.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#cc_binary.hdrs_check">hdrs_check</a>, <a href="#cc_binary.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_binary.link_extra_lib">link_extra_lib</a>, <a href="#cc_binary.linkopts">linkopts</a>, <a href="#cc_binary.linkshared">linkshared</a>, <a href="#cc_binary.linkstatic">linkstatic</a>, <a href="#cc_binary.local_defines">local_defines</a>, <a href="#cc_binary.malloc">malloc</a>, <a href="#cc_binary.module_interfaces">module_interfaces</a>, <a href="#cc_binary.nocopts">nocopts</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#cc_binary.reexport_deps">reexport_deps</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_binary.stamp">stamp</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_binary.win_def_file">win_def_file</a>)</pre> +It produces an executable binary. - <p>It produces an executable binary.</p> - -<br/>The <code>name</code> of the target should be the same as the name of the + +The `name` of the target should be the same as the name of the source file that is the main entry point of the application (minus the extension). -For example, if your entry point is in <code>main.cc</code>, then your name should -be <code>main</code>. +For example, if your entry point is in `main.cc`, then your name should +be `main`. -<h4>Implicit output targets</h4> -<ul> -<li><code><var>name</var>.stripped</code> (only built if explicitly requested): A stripped - version of the binary. <code>strip -g</code> is run on the binary to remove debug - symbols. Additional strip options can be provided on the command line using - <code>--stripopt=-foo</code>.</li> -<li><code><var>name</var>.dwp</code> (only built if explicitly requested): If - <a href="https://gcc.gnu.org/wiki/DebugFission">Fission</a> is enabled: a debug - information package file suitable for debugging remotely deployed binaries. Else: an - empty file.</li> -</ul> +#### Implicit output targets - <h3 id="cc_binary_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="cc_binary.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="cc_binary.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries to be linked in to the binary target. +- `name``.stripped` (only built if explicitly requested): A stripped + version of the binary. `strip -g` is run on the binary to remove debug + symbols. Additional strip options can be provided on the command line using + `--stripopt=-foo`. +- `name``.dwp` (only built if explicitly requested): If + [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug + information package file suitable for debugging remotely deployed binaries. Else: an + empty file. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="cc_binary.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="cc_binary.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries to be linked in to the binary target. <p>These can be <code>cc_library</code> or <code>objc_library</code> targets.</p> - It is also allowed to put linker scripts (.lds) into deps, and reference them in -<a href="#cc_binary.linkopts">linkopts</a>. - </td> - </tr> - <tr> - <td id="cc_binary.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of C and C++ files that are processed to create the library target. +<a href="#cc_binary.linkopts">linkopts</a>.</td> +</tr> +<tr> +<td id="cc_binary.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. <p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will - be compiled. These might be generated files: if a named file is in - the <code>outs</code> of some other rule, this <code>cc_library</code> - will automatically depend on that other rule. -</p> +be compiled. These might be generated files: if a named file is in +the <code>outs</code> of some other rule, this <code>cc_library</code> +will automatically depend on that other rule.</p> <p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler. -</p> +using the C/C++ compiler.</p> <p>A <code>.h</code> file will not be compiled, but will be available for - inclusion by sources in this rule. Both <code>.cc</code> and - <code>.h</code> files can directly include headers listed in - these <code>srcs</code> or in the <code>hdrs</code> of this rule or any - rule listed in the <code>deps</code> argument. -</p> +inclusion by sources in this rule. Both <code>.cc</code> and +<code>.h</code> files can directly include headers listed in +these <code>srcs</code> or in the <code>hdrs</code> of this rule or any +rule listed in the <code>deps</code> argument.</p> <p>All <code>#include</code>d files must be mentioned in the - <code>hdrs</code> attribute of this or referenced <code>cc_library</code> - rules, or they should be listed in <code>srcs</code> if they are private - to this library. See <a href="#hdrs">"Header inclusion checking"</a> for - a more detailed description. -</p> +<code>hdrs</code> attribute of this or referenced <code>cc_library</code> +rules, or they should be listed in <code>srcs</code> if they are private +to this library. See <a href="#hdrs">"Header inclusion checking"</a> for +a more detailed description.</p> <p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are - pre-compiled files. Your library might have these as - <code>srcs</code> if it uses third-party code for which we don't - have source code. -</p> +pre-compiled files. Your library might have these as +<code>srcs</code> if it uses third-party code for which we don't +have source code.</p> <p>If the <code>srcs</code> attribute includes the label of another rule, - <code>cc_library</code> will use the output files of that rule as source files to - compile. This is useful for one-off generation of source code (for more than occasional - use, it's better to implement a Starlark rule class and use the <code>cc_common</code> - API) -</p> -<p> - Permitted <code>srcs</code> file types: -</p> +<code>cc_library</code> will use the output files of that rule as source files to +compile. This is useful for one-off generation of source code (for more than occasional +use, it's better to implement a Starlark rule class and use the <code>cc_common</code> +API)</p> +<p>Permitted <code>srcs</code> file types:</p> <ul> <li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, - <code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> +<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> <li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, - <code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> +<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> <li>Assembler with C preprocessor: <code>.S</code></li> <li>Archive: <code>.a</code>, <code>.pic.a</code></li> <li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> <li>Shared library, versioned or unversioned: <code>.so</code>, - <code>.so.<i>version</i></code></li> +<code>.so.</code><em><code>version</code></em></li> <li>Object file: <code>.o</code>, <code>.pic.o</code></li> </ul> - -<p> - ... and any rules that produce those files (e.g. <code>cc_embed_data</code>). - Different extensions denote different programming languages in - accordance with gcc convention. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this library at runtime. - +<p>... and any rules that produce those files (e.g. <code>cc_embed_data</code>). +Different extensions denote different programming languages in +accordance with gcc convention.</p></td> +</tr> +<tr> +<td id="cc_binary.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this library at runtime. See general comments about <code>data</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by most build rules</a>. <p>If a <code>data</code> is the name of a generated file, then this - <code>cc_library</code> rule automatically depends on the generating - rule. -</p> +<code>cc_library</code> rule automatically depends on the generating +rule.</p> <p>If a <code>data</code> is a rule name, then this - <code>cc_library</code> rule automatically depends on that rule, - and that rule's <code>outs</code> are automatically added to - this <code>cc_library</code>'s data files. -</p> +<code>cc_library</code> rule automatically depends on that rule, +and that rule's <code>outs</code> are automatically added to +this <code>cc_library</code>'s data files.</p> <p>Your C++ code can access these data files like so:</p> -<pre><code class="lang-starlark"> +<pre class="lang-starlark"><code> const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file"); -</code></pre> - </td> - </tr> - <tr> - <td id="cc_binary.additional_linker_inputs"> - <code>additional_linker_inputs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Pass these files to the C++ linker command. -<p> - For example, compiled Windows .res files can be provided here to be embedded in - the binary target. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.conlyopts"> - <code>conlyopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C compilation command. + "my/test/data/file");</code></pre></td> +</tr> +<tr> +<td id="cc_binary.additional_linker_inputs"><code>additional_linker_inputs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Pass these files to the C++ linker command. +<p>For example, compiled Windows .res files can be provided here to be embedded in +the binary target.</p></td> +</tr> +<tr> +<td id="cc_binary.conlyopts"><code>conlyopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. - </td> - </tr> - <tr> - <td id="cc_binary.copts"> - <code>copts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C/C++ compilation command. +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> +</tr> +<tr> +<td id="cc_binary.copts"><code>copts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C/C++ compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -<p> - Each string in this attribute is added in the given order to <code>COPTS</code> before - compiling the binary target. The flags take effect only for compiling this target, not - its dependencies, so be careful about header files included elsewhere. - All paths should be relative to the workspace, not to the current package. - This attribute should not be needed outside of <code>third_party</code>. -</p> -<p> - If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> - <code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings - that consist of a single "Make" variable. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.cxxopts"> - <code>cxxopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C++ compilation command. +<p>Each string in this attribute is added in the given order to <code>COPTS</code> before +compiling the binary target. The flags take effect only for compiling this target, not +its dependencies, so be careful about header files included elsewhere. +All paths should be relative to the workspace, not to the current package. +This attribute should not be needed outside of <code>third_party</code>.</p> +<p>If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> +<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings +that consist of a single "Make" variable.</p></td> +</tr> +<tr> +<td id="cc_binary.cxxopts"><code>cxxopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C++ compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. - </td> - </tr> - <tr> - <td id="cc_binary.defines"> - <code>defines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of defines to add to the compile line. +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> +</tr> +<tr> +<td id="cc_binary.defines"><code>defines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of defines to add to the compile line. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. Each string, which must consist of a single Bourne shell token, is prepended with <code>-D</code> and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects. When in doubt, add define values to -<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead. - </td> - </tr> - <tr> - <td id="cc_binary.distribs"> - <code>distribs</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_binary.dynamic_deps"> - <code>dynamic_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - These are other <code>cc_shared_library</code> dependencies the current target depends on. - -<p> -The <code>cc_shared_library</code> implementation will use the list of +far-reaching effects. When in doubt, add define values to +<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.</td> +</tr> +<tr> +<td id="cc_binary.distribs"><code>distribs</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_binary.dynamic_deps"><code>dynamic_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +These are other <code>cc_shared_library</code> dependencies the current target depends on. +<p>The <code>cc_shared_library</code> implementation will use the list of <code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in the transitive <code>deps</code> should not be linked in because they are already provided -by a different <code>cc_shared_library</code>. - </td> - </tr> - <tr> - <td id="cc_binary.hdrs_check"> - <code>hdrs_check</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Deprecated, no-op. - </td> - </tr> - <tr> - <td id="cc_binary.includes"> - <code>includes</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of include dirs to be added to the compile line. +by a different <code>cc_shared_library</code>.</p></td> +</tr> +<tr> +<td id="cc_binary.hdrs_check"><code>hdrs_check</code></td> +<td><p>String; default is <code>""</code></p> +Deprecated, no-op.</td> +</tr> +<tr> +<td id="cc_binary.includes"><code>includes</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of include dirs to be added to the compile line. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system @@ -352,272 +220,190 @@ This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add +very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. -<p> -The added <code>include</code> paths will include generated files as well as -files in the source tree. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.link_extra_lib"> - <code>link_extra_lib</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p> - Control linking of extra libraries. -<p> - By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>, - which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>. - Without setting the flag, this library is empty by default. Setting the label flag - allows linking optional dependencies, such as overrides for weak symbols, interceptors - for shared library functions, or special runtime libraries (for malloc replacements, - prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to - <code>None</code> disables this behaviour. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.linkopts"> - <code>linkopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these flags to the C++ linker command. +<p>The added <code>include</code> paths will include generated files as well as +files in the source tree.</p></td> +</tr> +<tr> +<td id="cc_binary.link_extra_lib"><code>link_extra_lib</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p> +Control linking of extra libraries. +<p>By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>, +which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>. +Without setting the flag, this library is empty by default. Setting the label flag +allows linking optional dependencies, such as overrides for weak symbols, interceptors +for shared library functions, or special runtime libraries (for malloc replacements, +prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to +<code>None</code> disables this behaviour.</p></td> +</tr> +<tr> +<td id="cc_binary.linkopts"><code>linkopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these flags to the C++ linker command. Subject to <a href="make-variables.html">"Make" variable</a> substitution, -<a href="common-definitions.html#sh-tokenization"> -Bourne shell tokenization</a> and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a> and <a href="common-definitions.html#label-expansion">label expansion</a>. Each string in this attribute is added to <code>LINKOPTS</code> before linking the binary target. -<p> - Each element of this list that does not start with <code>$</code> or <code>-</code> is - assumed to be the label of a target in <code>deps</code>. The - list of files generated by that target is appended to the linker - options. An error is reported if the label is invalid, or is - not declared in <code>deps</code>. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.linkshared"> - <code>linkshared</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Create a shared library. +<p>Each element of this list that does not start with <code>$</code> or <code>-</code> is +assumed to be the label of a target in <code>deps</code>. The +list of files generated by that target is appended to the linker +options. An error is reported if the label is invalid, or is +not declared in <code>deps</code>.</p></td> +</tr> +<tr> +<td id="cc_binary.linkshared"><code>linkshared</code></td> +<td><p>Boolean; default is <code>False</code></p> +Create a shared library. To enable this attribute, include <code>linkshared=True</code> in your rule. By default this option is off. -<p> - The presence of this flag means that linking occurs with the <code>-shared</code> flag - to <code>gcc</code>, and the resulting shared library is suitable for loading into for - example a Java program. However, for build purposes it will never be linked into the - dependent binary, as it is assumed that shared libraries built with a - <a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so - it should not be considered a substitute for the <a href="#cc_library">cc_library</a> - rule. For sake of scalability we recommend avoiding this approach altogether and - simply letting <code>java_library</code> depend on <code>cc_library</code> rules - instead. -</p> -<p> - If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>, - you get a single completely self-contained unit. If you specify both - <code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly - self-contained unit. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.linkstatic"> - <code>linkstatic</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and +<p>The presence of this flag means that linking occurs with the <code>-shared</code> flag +to <code>gcc</code>, and the resulting shared library is suitable for loading into for +example a Java program. However, for build purposes it will never be linked into the +dependent binary, as it is assumed that shared libraries built with a +<a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so +it should not be considered a substitute for the <a href="#cc_library">cc_library</a> +rule. For sake of scalability we recommend avoiding this approach altogether and +simply letting <code>java_library</code> depend on <code>cc_library</code> rules +instead.</p> +<p>If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>, +you get a single completely self-contained unit. If you specify both +<code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly +self-contained unit.</p></td> +</tr> +<tr> +<td id="cc_binary.linkstatic"><code>linkstatic</code></td> +<td><p>Boolean; default is <code>True</code></p> +For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and <a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static mode. For <code>cc_library.link_static</code>: see below. <p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> -<p> - If enabled and this is a binary or test, this option tells the build tool to link in - <code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. - System libraries such as libc (but <i>not</i> the C/C++ runtime libraries, - see below) are still linked dynamically, as are libraries for which - there is no static library. So the resulting executable will still be dynamically - linked, hence only <i>mostly</i> static. -</p> -<p> -There are really three different ways to link an executable: -</p> +<p>If enabled and this is a binary or test, this option tells the build tool to link in +<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. +System libraries such as libc (but <em>not</em> the C/C++ runtime libraries, +see below) are still linked dynamically, as are libraries for which +there is no static library. So the resulting executable will still be dynamically +linked, hence only <em>mostly</em> static.</p> +<p>There are really three different ways to link an executable:</p> <ul> -<li> STATIC with fully_static_link feature, in which everything is linked statically; - e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/> - This mode is enabled by specifying <code>fully_static_link</code> in the - <a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> -<li> STATIC, in which all user libraries are linked statically (if a static - version is available), but where system libraries (excluding C/C++ runtime libraries) - are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/> - This mode is enabled by specifying <code>linkstatic=True</code>.</li> -<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is - available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/> - This mode is enabled by specifying <code>linkstatic=False</code>.</li> +<li>STATIC with fully_static_link feature, in which everything is linked statically; +e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br /> +This mode is enabled by specifying <code>fully_static_link</code> in the +<a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> +<li>STATIC, in which all user libraries are linked statically (if a static +version is available), but where system libraries (excluding C/C++ runtime libraries) +are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br /> +This mode is enabled by specifying <code>linkstatic=True</code>.</li> +<li>DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is +available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br /> +This mode is enabled by specifying <code>linkstatic=False</code>.</li> </ul> -<p> -If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in +<p>If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in <code>features</code> is used outside of <code>//third_party</code> -please include a comment near the rule to explain why. -</p> -<p> -The <code>linkstatic</code> attribute has a different meaning if used on a +please include a comment near the rule to explain why.</p> +<p>The <code>linkstatic</code> attribute has a different meaning if used on a <a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. For a C++ library, <code>linkstatic=True</code> indicates that only static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries. -</p> -<p> -There should be very little code built with <code>linkstatic=False</code> in production. +creation of dynamic libraries.</p> +<p>There should be very little code built with <code>linkstatic=False</code> in production. If <code>linkstatic=False</code>, then the build tool will create symlinks to -depended-upon shared libraries in the <code>*.runfiles</code> area. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.local_defines"> - <code>local_defines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of defines to add to the compile line. +depended-upon shared libraries in the <code>*.runfiles</code> area.</p></td> +</tr> +<tr> +<td id="cc_binary.local_defines"><code>local_defines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of defines to add to the compile line. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. Each string, which must consist of a single Bourne shell token, is prepended with <code>-D</code> and added to the compile command line for this target, -but not to its dependents. - </td> - </tr> - <tr> - <td id="cc_binary.malloc"> - <code>malloc</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p> - Override the default dependency on malloc. -<p> - By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>, - which is an empty library so the binary ends up using libc malloc. - This label must refer to a <code>cc_library</code>. If compilation is for a non-C++ - rule, this option has no effect. The value of this attribute is ignored if - <code>linkshared=True</code> is specified. -</p> - </td> - </tr> - <tr> - <td id="cc_binary.module_interfaces"> - <code>module_interfaces</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files are regarded as C++20 Modules Interface. - -<p> -C++ Standard has no restriction about module interface file extension +but not to its dependents.</td> +</tr> +<tr> +<td id="cc_binary.malloc"><code>malloc</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p> +Override the default dependency on malloc. +<p>By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>, +which is an empty library so the binary ends up using libc malloc. +This label must refer to a <code>cc_library</code>. If compilation is for a non-C++ +rule, this option has no effect. The value of this attribute is ignored if +<code>linkshared=True</code> is specified.</p></td> +</tr> +<tr> +<td id="cc_binary.module_interfaces"><code>module_interfaces</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files are regarded as C++20 Modules Interface. +<p>C++ Standard has no restriction about module interface file extension</p> <ul> -<li>Clang use cppm </li> -<li>GCC can use any source file extension </li> -<li>MSVC use ixx </li> +<li>Clang use cppm</li> +<li>GCC can use any source file extension</li> +<li>MSVC use ixx</li> </ul> -</p> <p>The use is guarded by the flag -<code>--experimental_cpp_modules</code>.</p> - </td> - </tr> - <tr> - <td id="cc_binary.nocopts"> - <code>nocopts</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Remove matching options from the C++ compilation command. +<code>--experimental_cpp_modules</code>.</p></td> +</tr> +<tr> +<td id="cc_binary.nocopts"><code>nocopts</code></td> +<td><p>String; default is <code>""</code></p> +Remove matching options from the C++ compilation command. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. The value of this attribute is interpreted as a regular expression. Any preexisting <code>COPTS</code> that match this regular expression -(including values explicitly specified in the rule's <a -href="#cc_binary.copts">copts</a> attribute) +(including values explicitly specified in the rule's <a href="#cc_binary.copts">copts</a> attribute) will be removed from <code>COPTS</code> for purposes of compiling this rule. This attribute should not be needed or used -outside of <code>third_party</code>. The values are not preprocessed -in any way other than the "Make" variable substitution. - </td> - </tr> - <tr> - <td id="cc_binary.reexport_deps"> - <code>reexport_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_binary.stamp"> - <code>stamp</code> - </td> - <td> - <p>Integer; default is <code>-1</code></p> - Whether to encode build information into the binary. Possible values: +outside of <code>third_party</code>. The values are not preprocessed +in any way other than the "Make" variable substitution.</td> +</tr> +<tr> +<td id="cc_binary.reexport_deps"><code>reexport_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_binary.stamp"><code>stamp</code></td> +<td><p>Integer; default is <code>-1</code></p> +Whether to encode build information into the binary. Possible values: <ul> -<li> - <code>stamp = 1</code>: Always stamp the build information into the binary, even in - <a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This - setting should be avoided</b>, since it potentially kills remote caching for the - binary and any downstream actions that depend on it. -</li> -<li> - <code>stamp = 0</code>: Always replace build information by constant values. This - gives good build result caching. -</li> -<li> - <code>stamp = -1</code>: Embedding of build information is controlled by the - <a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag. -</li> +<li><code>stamp = 1</code>: Always stamp the build information into the binary, even in +<a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <strong>This +setting should be avoided</strong>, since it potentially kills remote caching for the +binary and any downstream actions that depend on it.</li> +<li><code>stamp = 0</code>: Always replace build information by constant values. This +gives good build result caching.</li> +<li><code>stamp = -1</code>: Embedding of build information is controlled by the +<a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.</li> </ul> -<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> - </td> - </tr> - <tr> - <td id="cc_binary.win_def_file"> - <code>win_def_file</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - The Windows DEF file to be passed to linker. +<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p></td> +</tr> +<tr> +<td id="cc_binary.win_def_file"><code>win_def_file</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +The Windows DEF file to be passed to linker. <p>This attribute should only be used when Windows is the target platform. -It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx"> -export symbols</a> during linking a shared library.</p> - </td> - </tr> - </tbody> - </table> - <h2 id="cc_import"> - cc_import - </h2> +It can be used to +<a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">export symbols</a> during linking a shared library.</p></td> +</tr> +</tbody> +</table> - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_import.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +## cc_import - <pre class="rule-signature">cc_import(<a href="#cc_import.name">name</a>, <a href="#cc_import.deps">deps</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#cc_import.hdrs">hdrs</a>, <a href="#cc_import.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#cc_import.includes">includes</a>, <a href="#cc_import.interface_library">interface_library</a>, <a href="#cc_import.linkopts">linkopts</a>, <a href="#cc_import.objects">objects</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#cc_import.pic_objects">pic_objects</a>, <a href="#cc_import.pic_static_library">pic_static_library</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_import.shared_library">shared_library</a>, <a href="#cc_import.static_library">static_library</a>, <a href="#cc_import.strip_include_prefix">strip_include_prefix</a>, <a href="#cc_import.system_provided">system_provided</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_import.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <p> -<code>cc_import</code> rules allows users to import precompiled C/C++ libraries. -</p> +``` rule-signature +cc_import(name, deps, data, hdrs, alwayslink, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, includes, interface_library, linkopts, objects, package_metadata, pic_objects, pic_static_library, restricted_to, shared_library, static_library, strip_include_prefix, system_provided, tags, target_compatible_with, testonly, toolchains, visibility) +``` -<p> -The following are the typical use cases: <br/> +`cc_import` rules allows users to import precompiled C/C++ libraries. +The following are the typical use cases: 1. Linking a static library -<pre><code class="lang-starlark"> + +``` lang-starlark + cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -626,21 +412,25 @@ cc_import( # libmylib.a will be forcely linked into any binary that depends on it. # alwayslink = 1, ) -</code></pre> +``` + +2\. Linking a shared library (Unix) + +``` lang-starlark -2. Linking a shared library (Unix) -<pre><code class="lang-starlark"> cc_import( name = "mylib", hdrs = ["mylib.h"], shared_library = "libmylib.so", ) -</code></pre> +``` -3. Linking a shared library with interface library +3\. Linking a shared library with interface library + +On Unix: + +``` lang-starlark -<p>On Unix: -<pre><code class="lang-starlark"> cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -649,10 +439,12 @@ cc_import( # libmylib.so will be available for runtime shared_library = "libmylib.so", ) -</code></pre> +``` + +On Windows: + +``` lang-starlark -<p>On Windows: -<pre><code class="lang-starlark"> cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -661,12 +453,14 @@ cc_import( # mylib.dll will be available for runtime shared_library = "mylib.dll", ) -</code></pre> +``` + +4\. Linking a shared library with `system_provided=True` -4. Linking a shared library with <code>system_provided=True</code> +On Unix: + +``` lang-starlark -<p>On Unix: -<pre><code class="lang-starlark"> cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -675,10 +469,12 @@ cc_import( # This indicates that Bazel is not responsible for making libmylib.so available. system_provided = 1, ) -</code></pre> +``` + +On Windows: + +``` lang-starlark -<p>On Windows: -<pre><code class="lang-starlark"> cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -688,22 +484,26 @@ cc_import( # This indicates that Bazel is not responsible for making mylib.dll available. system_provided = 1, ) -</code></pre> +``` + +5\. Linking to static or shared library -5. Linking to static or shared library +On Unix: + +``` lang-starlark -<p>On Unix: -<pre><code class="lang-starlark"> cc_import( name = "mylib", hdrs = ["mylib.h"], static_library = "libmylib.a", shared_library = "libmylib.so", ) -</code></pre> +``` + +On Windows: + +``` lang-starlark -<p>On Windows: -<pre><code class="lang-starlark"> cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -711,10 +511,12 @@ cc_import( interface_library = "mylib.lib", # An import library for mylib.dll shared_library = "mylib.dll", ) -</code></pre> +``` + +The remaining is the same on Unix and Windows: + +``` lang-starlark -<p>The remaining is the same on Unix and Windows: -<pre><code class="lang-starlark"> # first will link to libmylib.a (or libmylib.lib) cc_binary( name = "first", @@ -730,87 +532,65 @@ cc_binary( deps = [":mylib"], linkstatic = 0, ) -</code></pre> +``` + +`cc_import` supports an include attribute. For example: + +``` lang-starlark -<p> -<code>cc_import</code> supports an include attribute. For example: -<pre><code class="lang-starlark"> cc_import( name = "curl_lib", hdrs = glob(["vendor/curl/include/curl/*.h"]), includes = ["vendor/curl/include"], shared_library = "vendor/curl/lib/.libs/libcurl.dylib", ) -</code></pre> -</p> - - <h3 id="cc_import_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="cc_import.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="cc_import.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries that the target depends upon. +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="cc_import.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="cc_import.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries that the target depends upon. See general comments about <code>deps</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. - </td> - </tr> - <tr> - <td id="cc_import.hdrs"> - <code>hdrs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of header files published by -this precompiled library to be directly included by sources in dependent rules. - </td> - </tr> - <tr> - <td id="cc_import.alwayslink"> - <code>alwayslink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - If 1, any binary that depends (directly or indirectly) on this C++ +most build rules</a>.</td> +</tr> +<tr> +<td id="cc_import.hdrs"><code>hdrs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of header files published by +this precompiled library to be directly included by sources in dependent rules.</td> +</tr> +<tr> +<td id="cc_import.alwayslink"><code>alwayslink</code></td> +<td><p>Boolean; default is <code>False</code></p> +If 1, any binary that depends (directly or indirectly) on this C++ precompiled library will link in all the object files archived in the static library, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. - <p>If alwayslink doesn't work with VS 2017 on Windows, that is due to a <a href="https://github.com/bazelbuild/bazel/issues/3949">known issue</a>, -please upgrade your VS 2017 to the latest version.</p> - </td> - </tr> - <tr> - <td id="cc_import.includes"> - <code>includes</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of include dirs to be added to the compile line. +please upgrade your VS 2017 to the latest version.</p></td> +</tr> +<tr> +<td id="cc_import.includes"><code>includes</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of include dirs to be added to the compile line. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system @@ -820,207 +600,142 @@ This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add +very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. -<p> -The default <code>include</code> path doesn't include generated +<p>The default <code>include</code> path doesn't include generated files. If you need to <code>#include</code> a generated header -file, list it in the <code>srcs</code>. -</p> - </td> - </tr> - <tr> - <td id="cc_import.interface_library"> - <code>interface_library</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - A single interface library for linking the shared library. -<p> Permitted file types: - <code>.ifso</code>, - <code>.tbd</code>, - <code>.lib</code>, - <code>.so</code> - or <code>.dylib</code> -</p> - </td> - </tr> - <tr> - <td id="cc_import.linkopts"> - <code>linkopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these flags to the C++ linker command. +file, list it in the <code>srcs</code>.</p></td> +</tr> +<tr> +<td id="cc_import.interface_library"><code>interface_library</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +A single interface library for linking the shared library. +<p>Permitted file types: +<code>.ifso</code>, +<code>.tbd</code>, +<code>.lib</code>, +<code>.so</code> +or <code>.dylib</code></p></td> +</tr> +<tr> +<td id="cc_import.linkopts"><code>linkopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these flags to the C++ linker command. Subject to <a href="make-variables.html">"Make" variable</a> substitution, -<a href="common-definitions.html#sh-tokenization"> -Bourne shell tokenization</a> and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a> and <a href="common-definitions.html#label-expansion">label expansion</a>. Each string in this attribute is added to <code>LINKOPTS</code> before linking the binary target. -<p> - Each element of this list that does not start with <code>$</code> or <code>-</code> is - assumed to be the label of a target in <code>deps</code>. The - list of files generated by that target is appended to the linker - options. An error is reported if the label is invalid, or is - not declared in <code>deps</code>. -</p> - </td> - </tr> - <tr> - <td id="cc_import.objects"> - <code>objects</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_import.pic_objects"> - <code>pic_objects</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_import.pic_static_library"> - <code>pic_static_library</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - - </td> - </tr> - <tr> - <td id="cc_import.shared_library"> - <code>shared_library</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - A single precompiled shared library. Bazel ensures it is available to the +<p>Each element of this list that does not start with <code>$</code> or <code>-</code> is +assumed to be the label of a target in <code>deps</code>. The +list of files generated by that target is appended to the linker +options. An error is reported if the label is invalid, or is +not declared in <code>deps</code>.</p></td> +</tr> +<tr> +<td id="cc_import.objects"><code>objects</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_import.pic_objects"><code>pic_objects</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_import.pic_static_library"><code>pic_static_library</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> +</tr> +<tr> +<td id="cc_import.shared_library"><code>shared_library</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +A single precompiled shared library. Bazel ensures it is available to the binary that depends on it during runtime. -<p> Permitted file types: - <code>.so</code>, - <code>.dll</code> - or <code>.dylib</code> -</p> - </td> - </tr> - <tr> - <td id="cc_import.static_library"> - <code>static_library</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - A single precompiled static library. -<p> Permitted file types: - <code>.a</code>, - <code>.pic.a</code> - or <code>.lib</code> -</p> - </td> - </tr> - <tr> - <td id="cc_import.strip_include_prefix"> - <code>strip_include_prefix</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The prefix to strip from the paths of the headers of this rule. - +<p>Permitted file types: +<code>.so</code>, +<code>.dll</code> +or <code>.dylib</code></p></td> +</tr> +<tr> +<td id="cc_import.static_library"><code>static_library</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +A single precompiled static library. +<p>Permitted file types: +<code>.a</code>, +<code>.pic.a</code> +or <code>.lib</code></p></td> +</tr> +<tr> +<td id="cc_import.strip_include_prefix"><code>strip_include_prefix</code></td> +<td><p>String; default is <code>""</code></p> +The prefix to strip from the paths of the headers of this rule. <p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible -at their path with this prefix cut off. - +at their path with this prefix cut off.</p> <p>If it's a relative path, it's taken as a package-relative one. If it's an absolute one, -it's understood as a repository-relative path. - +it's understood as a repository-relative path.</p> <p>The prefix in the <code>include_prefix</code> attribute is added after this prefix is -stripped. - -<p>This attribute is only legal under <code>third_party</code>. - </td> - </tr> - <tr> - <td id="cc_import.system_provided"> - <code>system_provided</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - If 1, it indicates the shared library required at runtime is provided by the system. In +stripped.</p> +<p>This attribute is only legal under <code>third_party</code>.</p></td> +</tr> +<tr> +<td id="cc_import.system_provided"><code>system_provided</code></td> +<td><p>Boolean; default is <code>False</code></p> +If 1, it indicates the shared library required at runtime is provided by the system. In this case, <code>interface_library</code> should be specified and -<code>shared_library</code> should be empty. - </td> - </tr> - </tbody> - </table> - <h2 id="cc_library"> - cc_library - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">cc_library(<a href="#cc_library.name">name</a>, <a href="#cc_library.deps">deps</a>, <a href="#cc_library.srcs">srcs</a>, <a href="#cc_library.data">data</a>, <a href="#cc_library.hdrs">hdrs</a>, <a href="#cc_library.additional_compiler_inputs">additional_compiler_inputs</a>, <a href="#cc_library.additional_linker_inputs">additional_linker_inputs</a>, <a href="#cc_library.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_library.conlyopts">conlyopts</a>, <a href="#cc_library.copts">copts</a>, <a href="#cc_library.cxxopts">cxxopts</a>, <a href="#cc_library.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#cc_library.hdrs_check">hdrs_check</a>, <a href="#cc_library.implementation_deps">implementation_deps</a>, <a href="#cc_library.include_prefix">include_prefix</a>, <a href="#cc_library.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_library.linkopts">linkopts</a>, <a href="#cc_library.linkstamp">linkstamp</a>, <a href="#cc_library.linkstatic">linkstatic</a>, <a href="#cc_library.local_defines">local_defines</a>, <a href="#cc_library.module_interfaces">module_interfaces</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_library.strip_include_prefix">strip_include_prefix</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="#cc_library.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_library.win_def_file">win_def_file</a>)</pre> - - <p>Use <code>cc_library()</code> for C++-compiled libraries. - The result is either a <code>.so</code>, <code>.lo</code>, - or <code>.a</code>, depending on what is needed. -</p> - -<p> - If you build something with static linking that depends on - a <code>cc_library</code>, the output of a depended-on library rule - is the <code>.a</code> file. If you specify - <code>alwayslink=True</code>, you get the <code>.lo</code> file. -</p> - -<p> - The actual output file name is <code>lib<i>foo</i>.so</code> for - the shared library, where <i>foo</i> is the name of the rule. The - other kinds of libraries end with <code>.lo</code> and <code>.a</code>, - respectively. If you need a specific shared library name, for - example, to define a Python module, use a genrule to copy the library - to the desired name. -</p> - -<h4 id="hdrs">Header inclusion checking</h4> - -<p> - All header files that are used in the build must be declared in - the <code>hdrs</code> or <code>srcs</code> of <code>cc_*</code> rules. - This is enforced. -</p> - -<p> - For <code>cc_library</code> rules, headers in <code>hdrs</code> comprise the - public interface of the library and can be directly included both - from the files in <code>hdrs</code> and <code>srcs</code> of the library - itself as well as from files in <code>hdrs</code> and <code>srcs</code> - of <code>cc_*</code> rules that list the library in their <code>deps</code>. - Headers in <code>srcs</code> must only be directly included from the files - in <code>hdrs</code> and <code>srcs</code> of the library itself. When - deciding whether to put a header into <code>hdrs</code> or <code>srcs</code>, - you should ask whether you want consumers of this library to be able to - directly include it. This is roughly the same decision as - between <code>public</code> and <code>private</code> visibility in programming languages. -</p> - -<p> - <code>cc_binary</code> and <code>cc_test</code> rules do not have an exported - interface, so they also do not have a <code>hdrs</code> attribute. All headers - that belong to the binary or test directly should be listed in - the <code>srcs</code>. -</p> - -<p> - To illustrate these rules, look at the following example. -</p> - -<pre><code class="lang-starlark"> +<code>shared_library</code> should be empty.</td> +</tr> +</tbody> +</table> + +## cc_library + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, module_interfaces, package_metadata, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file) +``` + +Use `cc_library()` for C++-compiled libraries. +The result is either a `.so`, `.lo`, +or `.a`, depending on what is needed. + +If you build something with static linking that depends on +a `cc_library`, the output of a depended-on library rule +is the `.a` file. If you specify +`alwayslink=True`, you get the `.lo` file. + +The actual output file name is `lib`*`foo`*`.so` for +the shared library, where *foo* is the name of the rule. The +other kinds of libraries end with `.lo` and `.a`, +respectively. If you need a specific shared library name, for +example, to define a Python module, use a genrule to copy the library +to the desired name. + +#### Header inclusion checking + +All header files that are used in the build must be declared in +the `hdrs` or `srcs` of `cc_*` rules. +This is enforced. + +For `cc_library` rules, headers in `hdrs` comprise the +public interface of the library and can be directly included both +from the files in `hdrs` and `srcs` of the library +itself as well as from files in `hdrs` and `srcs` +of `cc_*` rules that list the library in their `deps`. +Headers in `srcs` must only be directly included from the files +in `hdrs` and `srcs` of the library itself. When +deciding whether to put a header into `hdrs` or `srcs`, +you should ask whether you want consumers of this library to be able to +directly include it. This is roughly the same decision as +between `public` and `private` visibility in programming languages. + +`cc_binary` and `cc_test` rules do not have an exported +interface, so they also do not have a `hdrs` attribute. All headers +that belong to the binary or test directly should be listed in +the `srcs`. + +To illustrate these rules, look at the following example. + +``` lang-starlark + cc_binary( name = "foo", srcs = [ @@ -1048,63 +763,51 @@ cc_library( ], hdrs = ["baz.h"], ) -</code></pre> - -<p> - The allowed direct inclusions in this example are listed in the table below. - For example <code>foo.cc</code> is allowed to directly - include <code>foo.h</code> and <code>bar.h</code>, but not <code>baz.h</code>. -</p> - -<table class="table table-striped table-bordered table-condensed"> - <thead> - <tr><th>Including file</th><th>Allowed inclusions</th></tr> - </thead> - <tbody> - <tr><td>foo.h</td><td>bar.h</td></tr> - <tr><td>foo.cc</td><td>foo.h bar.h</td></tr> - <tr><td>bar.h</td><td>bar-impl.h baz.h</td></tr> - <tr><td>bar-impl.h</td><td>bar.h baz.h</td></tr> - <tr><td>bar.cc</td><td>bar.h bar-impl.h baz.h</td></tr> - <tr><td>baz.h</td><td>baz-impl.h</td></tr> - <tr><td>baz-impl.h</td><td>baz.h</td></tr> - <tr><td>baz.cc</td><td>baz.h baz-impl.h</td></tr> - </tbody> -</table> +``` + +The allowed direct inclusions in this example are listed in the table below. +For example `foo.cc` is allowed to directly +include `foo.h` and `bar.h`, but not `baz.h`. + +| Including file | Allowed inclusions | +|----------------|------------------------| +| foo.h | bar.h | +| foo.cc | foo.h bar.h | +| bar.h | bar-impl.h baz.h | +| bar-impl.h | bar.h baz.h | +| bar.cc | bar.h bar-impl.h baz.h | +| baz.h | baz-impl.h | +| baz-impl.h | baz.h | +| baz.cc | baz.h baz-impl.h | + +The inclusion checking rules only apply to *direct* +inclusions. In the example above `foo.cc` is allowed to +include `bar.h`, which may include `baz.h`, which in +turn is allowed to include `baz-impl.h`. Technically, the +compilation of a `.cc` file may transitively include any header +file in the `hdrs` or `srcs` in +any `cc_library` in the transitive `deps` closure. In +this case the compiler may read `baz.h` and `baz-impl.h` +when compiling `foo.cc`, but `foo.cc` must not +contain `#include "baz.h"`. For that to be +allowed, `baz` must be added to the `deps` +of `foo`. + +Bazel depends on toolchain support to enforce the inclusion checking rules. +The `layering_check` feature has to be supported by the toolchain +and requested explicitly, for example via the +`--features=layering_check` command-line flag or the +`features` parameter of the +[`package`](/reference/be/functions.html#package) function. The toolchains +provided by Bazel only support this feature with clang on Unix and macOS. + +#### Examples + +We use the `alwayslink` flag to force the linker to link in +this code although the main binary code doesn't reference it. + +``` lang-starlark -<p> - The inclusion checking rules only apply to <em>direct</em> - inclusions. In the example above <code>foo.cc</code> is allowed to - include <code>bar.h</code>, which may include <code>baz.h</code>, which in - turn is allowed to include <code>baz-impl.h</code>. Technically, the - compilation of a <code>.cc</code> file may transitively include any header - file in the <code>hdrs</code> or <code>srcs</code> in - any <code>cc_library</code> in the transitive <code>deps</code> closure. In - this case the compiler may read <code>baz.h</code> and <code>baz-impl.h</code> - when compiling <code>foo.cc</code>, but <code>foo.cc</code> must not - contain <code>#include "baz.h"</code>. For that to be - allowed, <code>baz</code> must be added to the <code>deps</code> - of <code>foo</code>. -</p> - -<p> - Bazel depends on toolchain support to enforce the inclusion checking rules. - The <code>layering_check</code> feature has to be supported by the toolchain - and requested explicitly, for example via the - <code>--features=layering_check</code> command-line flag or the - <code>features</code> parameter of the - <a href="/reference/be/functions.html#package"><code>package</code></a> function. The toolchains - provided by Bazel only support this feature with clang on Unix and macOS. -</p> - -<h4 id="cc_library_examples">Examples</h4> - -<p id="alwayslink_lib_example"> - We use the <code>alwayslink</code> flag to force the linker to link in - this code although the main binary code doesn't reference it. -</p> - -<pre><code class="lang-starlark"> cc_library( name = "ast_inspector_lib", srcs = ["ast_inspector_lib.cc"], @@ -1115,18 +818,17 @@ cc_library( # debug time, even if they aren't used anywhere in the code. alwayslink = 1, ) -</code></pre> +``` +The following example comes from +`third_party/python2_4_3/BUILD`. +Some of the code uses the `dl` library (to load +another, dynamic library), so this +rule specifies the `-ldl` link option to link the +`dl` library. -<p>The following example comes from - <code>third_party/python2_4_3/BUILD</code>. - Some of the code uses the <code>dl</code> library (to load - another, dynamic library), so this - rule specifies the <code>-ldl</code> link option to link the - <code>dl</code> library. -</p> +``` lang-starlark -<pre><code class="lang-starlark"> cc_library( name = "python2_4_3", linkopts = [ @@ -1135,14 +837,14 @@ cc_library( ], deps = ["//third_party/expat"], ) -</code></pre> +``` + +The following example comes from `third_party/kde/BUILD`. +We keep pre-built `.so` files in the depot. +The header files live in a subdirectory named `include`. -<p>The following example comes from <code>third_party/kde/BUILD</code>. - We keep pre-built <code>.so</code> files in the depot. - The header files live in a subdirectory named <code>include</code>. -</p> +``` lang-starlark -<pre><code class="lang-starlark"> cc_library( name = "kde", srcs = [ @@ -1150,19 +852,19 @@ cc_library( "lib/libkdesu.so", "lib/libkhtml.so", "lib/libkparts.so", - <var>...more .so files...</var>, + ...more .so files..., ], includes = ["include"], deps = ["//third_party/X11"], ) -</code></pre> +``` + +The following example comes from `third_party/gles/BUILD`. +Third-party code often needs some `defines` and +`linkopts`. -<p>The following example comes from <code>third_party/gles/BUILD</code>. - Third-party code often needs some <code>defines</code> and - <code>linkopts</code>. -</p> +``` lang-starlark -<pre><code class="lang-starlark"> cc_library( name = "gles", srcs = [ @@ -1182,321 +884,223 @@ cc_library( "//third_party/X11", ], ) -</code></pre> - - <h3 id="cc_library_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="cc_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="cc_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries that the library target depends upon. - +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="cc_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="cc_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries that the library target depends upon. <p>These can be <code>cc_library</code> or <code>objc_library</code> targets.</p> - <p>See general comments about <code>deps</code> - at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by - most build rules</a>. -</p> +at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by +most build rules</a>.</p> <p>These should be names of C++ library rules. - When you build a binary that links this rule's library, - you will also link the libraries in <code>deps</code>. -</p> +When you build a binary that links this rule's library, +you will also link the libraries in <code>deps</code>.</p> <p>Despite the "deps" name, not all of this library's clients - belong here. Run-time data dependencies belong in <code>data</code>. - Source files generated by other rules belong in <code>srcs</code>. -</p> +belong here. Run-time data dependencies belong in <code>data</code>. +Source files generated by other rules belong in <code>srcs</code>.</p> <p>To link in a pre-compiled third-party library, add its name to - the <code>srcs</code> instead. -</p> +the <code>srcs</code> instead.</p> <p>To depend on something without linking it to this library, add its - name to the <code>data</code> instead. -</p> - </td> - </tr> - <tr> - <td id="cc_library.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of C and C++ files that are processed to create the library target. +name to the <code>data</code> instead.</p></td> +</tr> +<tr> +<td id="cc_library.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. <p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will - be compiled. These might be generated files: if a named file is in - the <code>outs</code> of some other rule, this <code>cc_library</code> - will automatically depend on that other rule. -</p> +be compiled. These might be generated files: if a named file is in +the <code>outs</code> of some other rule, this <code>cc_library</code> +will automatically depend on that other rule.</p> <p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler. -</p> +using the C/C++ compiler.</p> <p>A <code>.h</code> file will not be compiled, but will be available for - inclusion by sources in this rule. Both <code>.cc</code> and - <code>.h</code> files can directly include headers listed in - these <code>srcs</code> or in the <code>hdrs</code> of this rule or any - rule listed in the <code>deps</code> argument. -</p> +inclusion by sources in this rule. Both <code>.cc</code> and +<code>.h</code> files can directly include headers listed in +these <code>srcs</code> or in the <code>hdrs</code> of this rule or any +rule listed in the <code>deps</code> argument.</p> <p>All <code>#include</code>d files must be mentioned in the - <code>hdrs</code> attribute of this or referenced <code>cc_library</code> - rules, or they should be listed in <code>srcs</code> if they are private - to this library. See <a href="#hdrs">"Header inclusion checking"</a> for - a more detailed description. -</p> +<code>hdrs</code> attribute of this or referenced <code>cc_library</code> +rules, or they should be listed in <code>srcs</code> if they are private +to this library. See <a href="#hdrs">"Header inclusion checking"</a> for +a more detailed description.</p> <p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are - pre-compiled files. Your library might have these as - <code>srcs</code> if it uses third-party code for which we don't - have source code. -</p> +pre-compiled files. Your library might have these as +<code>srcs</code> if it uses third-party code for which we don't +have source code.</p> <p>If the <code>srcs</code> attribute includes the label of another rule, - <code>cc_library</code> will use the output files of that rule as source files to - compile. This is useful for one-off generation of source code (for more than occasional - use, it's better to implement a Starlark rule class and use the <code>cc_common</code> - API) -</p> -<p> - Permitted <code>srcs</code> file types: -</p> +<code>cc_library</code> will use the output files of that rule as source files to +compile. This is useful for one-off generation of source code (for more than occasional +use, it's better to implement a Starlark rule class and use the <code>cc_common</code> +API)</p> +<p>Permitted <code>srcs</code> file types:</p> <ul> <li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, - <code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> +<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> <li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, - <code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> +<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> <li>Assembler with C preprocessor: <code>.S</code></li> <li>Archive: <code>.a</code>, <code>.pic.a</code></li> <li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> <li>Shared library, versioned or unversioned: <code>.so</code>, - <code>.so.<i>version</i></code></li> +<code>.so.</code><em><code>version</code></em></li> <li>Object file: <code>.o</code>, <code>.pic.o</code></li> </ul> - -<p> - ... and any rules that produce those files (e.g. <code>cc_embed_data</code>). - Different extensions denote different programming languages in - accordance with gcc convention. -</p> - </td> - </tr> - <tr> - <td id="cc_library.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this library at runtime. - +<p>... and any rules that produce those files (e.g. <code>cc_embed_data</code>). +Different extensions denote different programming languages in +accordance with gcc convention.</p></td> +</tr> +<tr> +<td id="cc_library.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this library at runtime. See general comments about <code>data</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by most build rules</a>. <p>If a <code>data</code> is the name of a generated file, then this - <code>cc_library</code> rule automatically depends on the generating - rule. -</p> +<code>cc_library</code> rule automatically depends on the generating +rule.</p> <p>If a <code>data</code> is a rule name, then this - <code>cc_library</code> rule automatically depends on that rule, - and that rule's <code>outs</code> are automatically added to - this <code>cc_library</code>'s data files. -</p> +<code>cc_library</code> rule automatically depends on that rule, +and that rule's <code>outs</code> are automatically added to +this <code>cc_library</code>'s data files.</p> <p>Your C++ code can access these data files like so:</p> -<pre><code class="lang-starlark"> +<pre class="lang-starlark"><code> const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file"); -</code></pre> - </td> - </tr> - <tr> - <td id="cc_library.hdrs"> - <code>hdrs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of header files published by + "my/test/data/file");</code></pre></td> +</tr> +<tr> +<td id="cc_library.hdrs"><code>hdrs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of header files published by this library to be directly included by sources in dependent rules. <p>This is the strongly preferred location for declaring header files that - describe the interface for the library. These headers will be made - available for inclusion by sources in this rule or in dependent rules. - Headers not meant to be included by a client of this library should be - listed in the <code>srcs</code> attribute instead, even if they are - included by a published header. See <a href="#hdrs">"Header inclusion - checking"</a> for a more detailed description. </p> +describe the interface for the library. These headers will be made +available for inclusion by sources in this rule or in dependent rules. +Headers not meant to be included by a client of this library should be +listed in the <code>srcs</code> attribute instead, even if they are +included by a published header. See <a href="#hdrs">"Header inclusion +checking"</a> for a more detailed description.</p> <p>Permitted <code>headers</code> file types: - <code>.h</code>, - <code>.hh</code>, - <code>.hpp</code>, - <code>.hxx</code>. -</p> - </td> - </tr> - <tr> - <td id="cc_library.additional_compiler_inputs"> - <code>additional_compiler_inputs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Any additional files you might want to pass to the compiler command line, such as sanitizer +<code>.h</code>, +<code>.hh</code>, +<code>.hpp</code>, +<code>.hxx</code>.</p></td> +</tr> +<tr> +<td id="cc_library.additional_compiler_inputs"><code>additional_compiler_inputs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the -$(location) function. - </td> - </tr> - <tr> - <td id="cc_library.additional_linker_inputs"> - <code>additional_linker_inputs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Pass these files to the C++ linker command. -<p> - For example, compiled Windows .res files can be provided here to be embedded in - the binary target. -</p> - </td> - </tr> - <tr> - <td id="cc_library.alwayslink"> - <code>alwayslink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - If 1, any binary that depends (directly or indirectly) on this C++ +$(location) function.</td> +</tr> +<tr> +<td id="cc_library.additional_linker_inputs"><code>additional_linker_inputs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Pass these files to the C++ linker command. +<p>For example, compiled Windows .res files can be provided here to be embedded in +the binary target.</p></td> +</tr> +<tr> +<td id="cc_library.alwayslink"><code>alwayslink</code></td> +<td><p>Boolean; default is <code>False</code></p> +If 1, any binary that depends (directly or indirectly) on this C++ library will link in all the object files for the files listed in <code>srcs</code>, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. - <p>If alwayslink doesn't work with VS 2017 on Windows, that is due to a <a href="https://github.com/bazelbuild/bazel/issues/3949">known issue</a>, -please upgrade your VS 2017 to the latest version.</p> - </td> - </tr> - <tr> - <td id="cc_library.conlyopts"> - <code>conlyopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C compilation command. +please upgrade your VS 2017 to the latest version.</p></td> +</tr> +<tr> +<td id="cc_library.conlyopts"><code>conlyopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. - </td> - </tr> - <tr> - <td id="cc_library.copts"> - <code>copts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C/C++ compilation command. +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> +</tr> +<tr> +<td id="cc_library.copts"><code>copts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C/C++ compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -<p> - Each string in this attribute is added in the given order to <code>COPTS</code> before - compiling the binary target. The flags take effect only for compiling this target, not - its dependencies, so be careful about header files included elsewhere. - All paths should be relative to the workspace, not to the current package. - This attribute should not be needed outside of <code>third_party</code>. -</p> -<p> - If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> - <code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings - that consist of a single "Make" variable. -</p> - </td> - </tr> - <tr> - <td id="cc_library.cxxopts"> - <code>cxxopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C++ compilation command. +<p>Each string in this attribute is added in the given order to <code>COPTS</code> before +compiling the binary target. The flags take effect only for compiling this target, not +its dependencies, so be careful about header files included elsewhere. +All paths should be relative to the workspace, not to the current package. +This attribute should not be needed outside of <code>third_party</code>.</p> +<p>If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> +<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings +that consist of a single "Make" variable.</p></td> +</tr> +<tr> +<td id="cc_library.cxxopts"><code>cxxopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C++ compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. - </td> - </tr> - <tr> - <td id="cc_library.defines"> - <code>defines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of defines to add to the compile line. +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> +</tr> +<tr> +<td id="cc_library.defines"><code>defines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of defines to add to the compile line. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. Each string, which must consist of a single Bourne shell token, is prepended with <code>-D</code> and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects. When in doubt, add define values to -<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead. - </td> - </tr> - <tr> - <td id="cc_library.hdrs_check"> - <code>hdrs_check</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Deprecated, no-op. - </td> - </tr> - <tr> - <td id="cc_library.implementation_deps"> - <code>implementation_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries that the library target depends on. Unlike with +far-reaching effects. When in doubt, add define values to +<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.</td> +</tr> +<tr> +<td id="cc_library.hdrs_check"><code>hdrs_check</code></td> +<td><p>String; default is <code>""</code></p> +Deprecated, no-op.</td> +</tr> +<tr> +<td id="cc_library.implementation_deps"><code>implementation_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries that the library target depends on. Unlike with <code>deps</code>, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with <code>implementation_deps</code> are still linked in -binary targets that depend on this library. - </td> - </tr> - <tr> - <td id="cc_library.include_prefix"> - <code>include_prefix</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The prefix to add to the paths of the headers of this rule. - +binary targets that depend on this library.</td> +</tr> +<tr> +<td id="cc_library.include_prefix"><code>include_prefix</code></td> +<td><p>String; default is <code>""</code></p> +The prefix to add to the paths of the headers of this rule. <p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible -at is the value of this attribute prepended to their repository-relative path. - +at is the value of this attribute prepended to their repository-relative path.</p> <p>The prefix in the <code>strip_include_prefix</code> attribute is removed before this -prefix is added. - -<p>This attribute is only legal under <code>third_party</code>. - </td> - </tr> - <tr> - <td id="cc_library.includes"> - <code>includes</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of include dirs to be added to the compile line. +prefix is added.</p> +<p>This attribute is only legal under <code>third_party</code>.</p></td> +</tr> +<tr> +<td id="cc_library.includes"><code>includes</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of include dirs to be added to the compile line. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system @@ -1506,21 +1110,15 @@ This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add +very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. -<p> -The added <code>include</code> paths will include generated files as well as -files in the source tree. -</p> - </td> - </tr> - <tr> - <td id="cc_library.linkopts"> - <code>linkopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - See <a href="/reference/be/c-cpp.html#cc_binary.linkopts"><code>cc_binary.linkopts</code></a>. +<p>The added <code>include</code> paths will include generated files as well as +files in the source tree.</p></td> +</tr> +<tr> +<td id="cc_library.linkopts"><code>linkopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +See <a href="/reference/be/c-cpp.html#cc_binary.linkopts"><code>cc_binary.linkopts</code></a>. The <code>linkopts</code> attribute is also applied to any target that depends, directly or indirectly, on this library via <code>deps</code> attributes (or via other attributes that are treated similarly: @@ -1528,199 +1126,147 @@ the <a href="/reference/be/c-cpp.html#cc_binary.malloc"><code>malloc</code></a> attribute of <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a>). Dependency linkopts take precedence over dependent linkopts (i.e. dependency linkopts appear later in the command line). Linkopts specified in -<a href='../user-manual.html#flag--linkopt'><code>--linkopt</code></a> +<a href="../user-manual.html#flag--linkopt"><code>--linkopt</code></a> take precedence over rule linkopts. -</p> -<p> -Note that the <code>linkopts</code> attribute only applies +<p>Note that the <code>linkopts</code> attribute only applies when creating <code>.so</code> files or executables, not when creating <code>.a</code> or <code>.lo</code> files. So if the <code>linkstatic=True</code> attribute is set, the <code>linkopts</code> attribute has no effect on the creation of -this library, only on other targets which depend on this library. -</p> -<p> -Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" -options are not supported and should never be specified in this attribute. -</p> -<p> The <code>.so</code> files produced by <code>cc_library</code> +this library, only on other targets which depend on this library.</p> +<p>Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" +options are not supported and should never be specified in this attribute.</p> +<p>The <code>.so</code> files produced by <code>cc_library</code> rules are not linked against the libraries that they depend -on. If you're trying to create a shared library for use +on. If you're trying to create a shared library for use outside of the main repository, e.g. for manual use with <code>dlopen()</code> or <code>LD_PRELOAD</code>, it may be better to use a <code>cc_binary</code> rule with the <code>linkshared=True</code> attribute. -See <a href="/reference/be/c-cpp.html#cc_binary.linkshared"><code>cc_binary.linkshared</code></a>. -</p> - </td> - </tr> - <tr> - <td id="cc_library.linkstamp"> - <code>linkstamp</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Simultaneously compiles and links the specified C++ source file into the final +See <a href="/reference/be/c-cpp.html#cc_binary.linkshared"><code>cc_binary.linkshared</code></a>.</p></td> +</tr> +<tr> +<td id="cc_library.linkstamp"><code>linkstamp</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Simultaneously compiles and links the specified C++ source file into the final binary. This trickery is required to introduce timestamp information into binaries; if we compiled the source file to an object file in the usual way, the timestamp would be incorrect. A linkstamp compilation may not include any particular set of compiler flags and so should not depend on any particular header, compiler option, or other build variable. -<em class='harmful'>This option should only be needed in the -<code>base</code> package.</em> - </td> - </tr> - <tr> - <td id="cc_library.linkstatic"> - <code>linkstatic</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and +<em>This option should only be needed in the +<code>base</code> package.</em></td> +</tr> +<tr> +<td id="cc_library.linkstatic"><code>linkstatic</code></td> +<td><p>Boolean; default is <code>False</code></p> +For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and <a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static mode. For <code>cc_library.link_static</code>: see below. <p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> -<p> - If enabled and this is a binary or test, this option tells the build tool to link in - <code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. - System libraries such as libc (but <i>not</i> the C/C++ runtime libraries, - see below) are still linked dynamically, as are libraries for which - there is no static library. So the resulting executable will still be dynamically - linked, hence only <i>mostly</i> static. -</p> -<p> -There are really three different ways to link an executable: -</p> +<p>If enabled and this is a binary or test, this option tells the build tool to link in +<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. +System libraries such as libc (but <em>not</em> the C/C++ runtime libraries, +see below) are still linked dynamically, as are libraries for which +there is no static library. So the resulting executable will still be dynamically +linked, hence only <em>mostly</em> static.</p> +<p>There are really three different ways to link an executable:</p> <ul> -<li> STATIC with fully_static_link feature, in which everything is linked statically; - e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/> - This mode is enabled by specifying <code>fully_static_link</code> in the - <a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> -<li> STATIC, in which all user libraries are linked statically (if a static - version is available), but where system libraries (excluding C/C++ runtime libraries) - are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/> - This mode is enabled by specifying <code>linkstatic=True</code>.</li> -<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is - available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/> - This mode is enabled by specifying <code>linkstatic=False</code>.</li> +<li>STATIC with fully_static_link feature, in which everything is linked statically; +e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br /> +This mode is enabled by specifying <code>fully_static_link</code> in the +<a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> +<li>STATIC, in which all user libraries are linked statically (if a static +version is available), but where system libraries (excluding C/C++ runtime libraries) +are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br /> +This mode is enabled by specifying <code>linkstatic=True</code>.</li> +<li>DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is +available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br /> +This mode is enabled by specifying <code>linkstatic=False</code>.</li> </ul> -<p> -If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in +<p>If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in <code>features</code> is used outside of <code>//third_party</code> -please include a comment near the rule to explain why. -</p> -<p> -The <code>linkstatic</code> attribute has a different meaning if used on a +please include a comment near the rule to explain why.</p> +<p>The <code>linkstatic</code> attribute has a different meaning if used on a <a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. For a C++ library, <code>linkstatic=True</code> indicates that only static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries. -</p> -<p> -There should be very little code built with <code>linkstatic=False</code> in production. +creation of dynamic libraries.</p> +<p>There should be very little code built with <code>linkstatic=False</code> in production. If <code>linkstatic=False</code>, then the build tool will create symlinks to -depended-upon shared libraries in the <code>*.runfiles</code> area. -</p> - </td> - </tr> - <tr> - <td id="cc_library.local_defines"> - <code>local_defines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of defines to add to the compile line. +depended-upon shared libraries in the <code>*.runfiles</code> area.</p></td> +</tr> +<tr> +<td id="cc_library.local_defines"><code>local_defines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of defines to add to the compile line. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. Each string, which must consist of a single Bourne shell token, is prepended with <code>-D</code> and added to the compile command line for this target, -but not to its dependents. - </td> - </tr> - <tr> - <td id="cc_library.module_interfaces"> - <code>module_interfaces</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files are regarded as C++20 Modules Interface. - -<p> -C++ Standard has no restriction about module interface file extension +but not to its dependents.</td> +</tr> +<tr> +<td id="cc_library.module_interfaces"><code>module_interfaces</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files are regarded as C++20 Modules Interface. +<p>C++ Standard has no restriction about module interface file extension</p> <ul> -<li>Clang use cppm </li> -<li>GCC can use any source file extension </li> -<li>MSVC use ixx </li> +<li>Clang use cppm</li> +<li>GCC can use any source file extension</li> +<li>MSVC use ixx</li> </ul> -</p> <p>The use is guarded by the flag -<code>--experimental_cpp_modules</code>.</p> - </td> - </tr> - <tr> - <td id="cc_library.strip_include_prefix"> - <code>strip_include_prefix</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The prefix to strip from the paths of the headers of this rule. - +<code>--experimental_cpp_modules</code>.</p></td> +</tr> +<tr> +<td id="cc_library.strip_include_prefix"><code>strip_include_prefix</code></td> +<td><p>String; default is <code>""</code></p> +The prefix to strip from the paths of the headers of this rule. <p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible -at their path with this prefix cut off. - +at their path with this prefix cut off.</p> <p>If it's a relative path, it's taken as a package-relative one. If it's an absolute one, -it's understood as a repository-relative path. - +it's understood as a repository-relative path.</p> <p>The prefix in the <code>include_prefix</code> attribute is added after this prefix is -stripped. - -<p>This attribute is only legal under <code>third_party</code>. - </td> - </tr> - <tr> - <td id="cc_library.textual_hdrs"> - <code>textual_hdrs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of header files published by +stripped.</p> +<p>This attribute is only legal under <code>third_party</code>.</p></td> +</tr> +<tr> +<td id="cc_library.textual_hdrs"><code>textual_hdrs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of header files published by this library to be textually included by sources in dependent rules. <p>This is the location for declaring header files that cannot be compiled on their own; - that is, they always need to be textually included by other source files to build valid - code.</p> - </td> - </tr> - <tr> - <td id="cc_library.win_def_file"> - <code>win_def_file</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - The Windows DEF file to be passed to linker. +that is, they always need to be textually included by other source files to build valid +code.</p></td> +</tr> +<tr> +<td id="cc_library.win_def_file"><code>win_def_file</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +The Windows DEF file to be passed to linker. <p>This attribute should only be used when Windows is the target platform. -It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx"> -export symbols</a> during linking a shared library.</p> - </td> - </tr> - </tbody> - </table> - <h2 id="cc_shared_library"> - cc_shared_library - </h2> +It can be used to +<a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">export symbols</a> during linking a shared library.</p></td> +</tr> +</tbody> +</table> - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_shared_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +## cc_shared_library - <pre class="rule-signature">cc_shared_library(<a href="#cc_shared_library.name">name</a>, <a href="#cc_shared_library.deps">deps</a>, <a href="#cc_shared_library.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#cc_shared_library.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#cc_shared_library.experimental_disable_topo_sort_do_not_use_remove_before_7_0">experimental_disable_topo_sort_do_not_use_remove_before_7_0</a>, <a href="#cc_shared_library.exports_filter">exports_filter</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_shared_library.roots">roots</a>, <a href="#cc_shared_library.shared_lib_name">shared_lib_name</a>, <a href="#cc_shared_library.static_deps">static_deps</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.toolchains">toolchains</a>, <a href="#cc_shared_library.user_link_flags">user_link_flags</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_shared_library.win_def_file">win_def_file</a>)</pre> +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_shared_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <p>It produces a shared library.</p> +``` rule-signature +cc_shared_library(name, deps, additional_linker_inputs, aspect_hints, compatible_with, deprecation, dynamic_deps, exec_compatible_with, exec_group_compatible_with, exec_properties, experimental_disable_topo_sort_do_not_use_remove_before_7_0, exports_filter, features, package_metadata, restricted_to, roots, shared_lib_name, static_deps, tags, target_compatible_with, testonly, toolchains, user_link_flags, visibility, win_def_file) +``` -<h4 id="cc_shard_library_examples">Example</h4> +It produces a shared library. + +#### Example + +``` code -<pre class="code"> cc_shared_library( name = "foo_shared", deps = [ @@ -1760,644 +1306,484 @@ cc_library( srcs = ["baz.cc"], hdrs = ["baz.h"], ) -</pre> +``` -<p>In the example <code>foo_shared</code> statically links <code>foo</code> -and <code>baz</code>, the latter being a transitive dependency. It doesn't -link <code>bar</code> because it is already provided dynamically by the -<code>dynamic_dep</code> <code>bar_shared</code>.</p> +In the example `foo_shared` statically links `foo` +and `baz`, the latter being a transitive dependency. It doesn't +link `bar` because it is already provided dynamically by the +`dynamic_dep` `bar_shared`. -<p><code>foo_shared</code> uses a linker script *.lds file to control which -symbols should be exported. The <code>cc_shared_library</code> rule logic does +`foo_shared` uses a linker script \*.lds file to control which +symbols should be exported. The `cc_shared_library` rule logic does not control which symbols get exported, it only uses what is assumed to be exported to give errors during analysis phase if two shared libraries export the -same targets.</p> +same targets. + +Every direct dependency of `cc_shared_library` is assumed to be +exported. Therefore, Bazel assumes during analysis that `foo` is being +exported by `foo_shared`. `baz` is not assumed to be exported +by `foo_shared`. Every target matched by the `exports_filter` +is also assumed to be exported. -<p>Every direct dependency of <code>cc_shared_library</code> is assumed to be -exported. Therefore, Bazel assumes during analysis that <code>foo</code> is being -exported by <code>foo_shared</code>. <code>baz</code> is not assumed to be exported -by <code>foo_shared</code>. Every target matched by the <code>exports_filter</code> -is also assumed to be exported.</p> +Every single `cc_library` in the example should appear at most in one +`cc_shared_library`. If we wanted to link `baz` also into +`bar_shared` we would need to add +`tags = ["LINKABLE_MORE_THAN_ONCE"]` to `baz`. -<p>Every single <code>cc_library</code> in the example should appear at most in one -<code>cc_shared_library</code>. If we wanted to link <code>baz</code> also into -<code>bar_shared</code> we would need to add -<code>tags = ["LINKABLE_MORE_THAN_ONCE"]</code> to <code>baz</code>.</p> +Due to the `shared_lib_name` attribute, the file produced by +`bar_shared` will have the name `bar.so` as opposed +to the name `libbar.so` that it would have by default on Linux. -<p>Due to the <code>shared_lib_name</code> attribute, the file produced by -<code>bar_shared</code> will have the name <code>bar.so</code> as opposed -to the name <code>libbar.so</code> that it would have by default on Linux.</p> +#### Errors -<h4 id="cc_shard_library_examples">Errors</h4> -<h5><code>Two shared libraries in dependencies export the same symbols.</code></h5> +##### `Two shared libraries in dependencies export the same symbols.` -<p>This will happen whenever you are creating a target with two different -<code>cc_shared_library</code> dependencies that export the same target. To fix this +This will happen whenever you are creating a target with two different +`cc_shared_library` dependencies that export the same target. To fix this you need to stop the libraries from being exported in one of the -<code>cc_shared_library</code> dependencies.</p> +`cc_shared_library` dependencies. -<h5><code>Two shared libraries in dependencies link the same library statically</code></h5> +##### `Two shared libraries in dependencies link the same library statically` -<p>This will happen whenever you are creating a new <code>cc_shared_library</code> with two -different <code>cc_shared_library</code> dependencies that link the same target statically. -Similar to the error with exports.</p> +This will happen whenever you are creating a new `cc_shared_library` with two +different `cc_shared_library` dependencies that link the same target statically. +Similar to the error with exports. -<p>One way to fix this is to stop linking the library into one of the -<code>cc_shared_library</code> dependencies. At the same time, the one that still links it +One way to fix this is to stop linking the library into one of the +`cc_shared_library` dependencies. At the same time, the one that still links it needs to export the library so that the one not linking it keeps visibility to the symbols. Another way is to pull out a third library that exports the target. -A third way is to tag the culprit <code>cc_library</code> with <code>LINKABLE_MORE_THAN_ONCE</code> +A third way is to tag the culprit `cc_library` with `LINKABLE_MORE_THAN_ONCE` but this fix should be rare and you should absolutely make sure that the -<code>cc_library</code> is indeed safe to link more than once.</p> - -<h5><code>'//foo:foo' is already linked statically in '//bar:bar' but not exported`</code></h5> - -<p>This means that a library in the transitive closure of your <code>deps</code> is reachable -without going through one of the <code>cc_shared_library</code> dependencies but is already -linked into a different <code>cc_shared_library</code> in <code>dynamic_deps</code> and is not -exported.</p> - -<p>The solution is to export it from the <code>cc_shared_library</code> dependency or pull out -a third <code>cc_shared_library</code> that exports it.</p> - -<h5><code>Do not place libraries which only contain a precompiled dynamic library in deps. -</code></h5> - -<p>If you have a precompiled dynamic library, this doesn't need to and cannot be -linked statically into the current <code>cc_shared_library</code> target that you are -currently creating. Therefore, it doesn't belong in <code>deps</code> of the -<code>cc_shared_library</code>. If this precompiled dynamic library is a dependency of one -of your <code>cc_libraries</code>, then the <code>cc_library</code> needs to depend on it -directly.</p> - -<h5><code>Trying to export a library already exported by a different shared library</code></h5> - -<p>You will see this error if on the current rule you are claiming to export a -target that is already being exported by one of your dynamic dependencies.</p> - -<p>To fix this, remove the target from <code>deps</code> and just rely on it from the dynamic -dependency or make sure that the <code>exports_filter</code> doesn't catch this target.</p> - - <h3 id="cc_shared_library_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="cc_shared_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="cc_shared_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Top level libraries that will unconditionally be statically linked into the shared library +`cc_library` is indeed safe to link more than once. + +##### `` '//foo:foo' is already linked statically in '//bar:bar' but not exported` `` + +This means that a library in the transitive closure of your `deps` is reachable +without going through one of the `cc_shared_library` dependencies but is already +linked into a different `cc_shared_library` in `dynamic_deps` and is not +exported. + +The solution is to export it from the `cc_shared_library` dependency or pull out +a third `cc_shared_library` that exports it. + +##### `Do not place libraries which only contain a precompiled dynamic library in deps. ` + +If you have a precompiled dynamic library, this doesn't need to and cannot be +linked statically into the current `cc_shared_library` target that you are +currently creating. Therefore, it doesn't belong in `deps` of the +`cc_shared_library`. If this precompiled dynamic library is a dependency of one +of your `cc_libraries`, then the `cc_library` needs to depend on it +directly. + +##### `Trying to export a library already exported by a different shared library` + +You will see this error if on the current rule you are claiming to export a +target that is already being exported by one of your dynamic dependencies. + +To fix this, remove the target from `deps` and just rely on it from the dynamic +dependency or make sure that the `exports_filter` doesn't catch this target. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="cc_shared_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="cc_shared_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Top level libraries that will unconditionally be statically linked into the shared library after being whole-archived. - -<p> -Any transitive library dependency of these direct deps will be linked into this shared +<p>Any transitive library dependency of these direct deps will be linked into this shared library as long as they have not already been linked by a <code>cc_shared_library</code> in <code>dynamic_deps</code>.</p> - -<p> -During analysis, the rule implementation will consider any target listed in +<p>During analysis, the rule implementation will consider any target listed in <code>deps</code> as being exported by the shared library in order to give errors when multiple <code>cc_shared_libraries</code> export the same targets. The rule implementation does not take care of informing the linker about which symbols should be exported by the shared object. The user should take care of this via linker scripts or visibility declarations in the source code.</p> - -<p> -The implementation will also trigger errors whenever the same library is linked statically +<p>The implementation will also trigger errors whenever the same library is linked statically into more than one <code>cc_shared_library</code>. This can be avoided by adding <code>"LINKABLE_MORE_THAN_ONCE"</code> to the <code>cc_library.tags</code> or by listing the `cc_library` as an export of one of the shared libraries so that one can be made a -<code>dynamic_dep</code> of the other. -</p> - </td> - </tr> - <tr> - <td id="cc_shared_library.additional_linker_inputs"> - <code>additional_linker_inputs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Any additional files that you may want to pass to the linker, for example, linker scripts. +<code>dynamic_dep</code> of the other.</p></td> +</tr> +<tr> +<td id="cc_shared_library.additional_linker_inputs"><code>additional_linker_inputs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Any additional files that you may want to pass to the linker, for example, linker scripts. You have to separately pass any linker flags that the linker needs in order to be aware -of this file. You can do so via the <code>user_link_flags</code> attribute. - </td> - </tr> - <tr> - <td id="cc_shared_library.dynamic_deps"> - <code>dynamic_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - These are other <code>cc_shared_library</code> dependencies the current target depends on. - -<p> -The <code>cc_shared_library</code> implementation will use the list of +of this file. You can do so via the <code>user_link_flags</code> attribute.</td> +</tr> +<tr> +<td id="cc_shared_library.dynamic_deps"><code>dynamic_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +These are other <code>cc_shared_library</code> dependencies the current target depends on. +<p>The <code>cc_shared_library</code> implementation will use the list of <code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in the transitive <code>deps</code> should not be linked in because they are already provided -by a different <code>cc_shared_library</code>. -</p> - </td> - </tr> - <tr> - <td id="cc_shared_library.experimental_disable_topo_sort_do_not_use_remove_before_7_0"> - <code>experimental_disable_topo_sort_do_not_use_remove_before_7_0</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - - </td> - </tr> - <tr> - <td id="cc_shared_library.exports_filter"> - <code>exports_filter</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - This attribute contains a list of targets that are claimed to be exported by the current +by a different <code>cc_shared_library</code>.</p></td> +</tr> +<tr> +<td id="cc_shared_library.experimental_disable_topo_sort_do_not_use_remove_before_7_0"><code>experimental_disable_topo_sort_do_not_use_remove_before_7_0</code></td> +<td><p>Boolean; default is <code>False</code></p></td> +</tr> +<tr> +<td id="cc_shared_library.exports_filter"><code>exports_filter</code></td> +<td><p>List of strings; default is <code>[]</code></p> +This attribute contains a list of targets that are claimed to be exported by the current shared library. - -<p> -Any target <code>deps</code> is already understood to be exported by the shared library. +<p>Any target <code>deps</code> is already understood to be exported by the shared library. This attribute should be used to list any targets that are exported by the shared library -but are transitive dependencies of <code>deps</code>. -</p> - -<p> -Note that this attribute is not actually adding a dependency edge to those targets, the +but are transitive dependencies of <code>deps</code>.</p> +<p>Note that this attribute is not actually adding a dependency edge to those targets, the dependency edge should instead be created by <code>deps</code>.The entries in this attribute are just strings. Keep in mind that when placing a target in this attribute, this is considered a claim that the shared library exports the symbols from that target. -The <code>cc_shared_library</code> logic doesn't actually handle telling the linker which -symbols should be exported. -</p> - +The <code>cc_shared_library</code> logic doesn't actually handle telling the linker which +symbols should be exported.</p> <p>The following syntax is allowed:</p> <p><code>//foo:__pkg__</code> to account for any target in foo/BUILD</p> <p><code>//foo:__subpackages__</code> to account for any target in foo/BUILD or any other -package below foo/ like foo/bar/BUILD</p> - </td> - </tr> - <tr> - <td id="cc_shared_library.roots"> - <code>roots</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_shared_library.shared_lib_name"> - <code>shared_lib_name</code> - </td> - <td> - <p>String; default is <code>""</code></p> - By default cc_shared_library will use a name for the shared library output file based on +package below foo/ like foo/bar/BUILD</p></td> +</tr> +<tr> +<td id="cc_shared_library.roots"><code>roots</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_shared_library.shared_lib_name"><code>shared_lib_name</code></td> +<td><p>String; default is <code>""</code></p> +By default cc_shared_library will use a name for the shared library output file based on the target's name and the platform. This includes an extension and sometimes a prefix. Sometimes you may not want the default name, for example, when loading C++ shared libraries for Python the default lib* prefix is often not desired, in which case you can use this -attribute to choose a custom name. - </td> - </tr> - <tr> - <td id="cc_shared_library.static_deps"> - <code>static_deps</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_shared_library.user_link_flags"> - <code>user_link_flags</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Any additional flags that you may want to pass to the linker. For example, to make the +attribute to choose a custom name.</td> +</tr> +<tr> +<td id="cc_shared_library.static_deps"><code>static_deps</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_shared_library.user_link_flags"><code>user_link_flags</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Any additional flags that you may want to pass to the linker. For example, to make the linker aware of a linker script passed via additional_linker_inputs you can use the following: - -<pre><code class="lang-starlark"> +<pre class="lang-starlark"><code> cc_shared_library( - name = "foo_shared", + name = "foo_shared", additional_linker_inputs = select({ - "//src/conditions:linux": [ - ":foo.lds", - ":additional_script.txt", + "//src/conditions:linux": [ + ":foo.lds", + ":additional_script.txt", ], - "//conditions:default": []}), + "//conditions:default": []}), user_link_flags = select({ - "//src/conditions:linux": [ - "-Wl,-rpath,kittens", - "-Wl,--version-script=$(location :foo.lds)", - "-Wl,--script=$(location :additional_script.txt)", + "//src/conditions:linux": [ + "-Wl,-rpath,kittens", + "-Wl,--version-script=$(location :foo.lds)", + "-Wl,--script=$(location :additional_script.txt)", ], - "//conditions:default": []}), + "//conditions:default": []}), ... - ) -</code></pre> - </td> - </tr> - <tr> - <td id="cc_shared_library.win_def_file"> - <code>win_def_file</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - The Windows DEF file to be passed to linker. + )</code></pre></td> +</tr> +<tr> +<td id="cc_shared_library.win_def_file"><code>win_def_file</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +The Windows DEF file to be passed to linker. <p>This attribute should only be used when Windows is the target platform. -It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx"> -export symbols</a> during linking a shared library.</p> - </td> - </tr> - </tbody> - </table> - <h2 id="cc_static_library"> - cc_static_library - </h2> +It can be used to +<a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">export symbols</a> during linking a shared library.</p></td> +</tr> +</tbody> +</table> - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_static_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +## cc_static_library - <pre class="rule-signature">cc_static_library(<a href="#cc_static_library.name">name</a>, <a href="#cc_static_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_static_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - Produces a static library from a list of targets and their transitive dependencies. +``` rule-signature +cc_static_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` -<p>The resulting static library contains the object files of the targets listed in -<code>deps</code> as well as their transitive dependencies, with preference given to -<code>PIC</code> objects.</p> +Produces a static library from a list of targets and their transitive dependencies. -<h4 id="cc_static_library_output_groups">Output groups</h4> +The resulting static library contains the object files of the targets listed in +`deps` as well as their transitive dependencies, with preference given to +`PIC` objects. -<h5><code>linkdeps</code></h5> -<p>A text file containing the labels of those transitive dependencies of targets listed in -<code>deps</code> that did not contribute any object files to the static library, but do +#### Output groups + +##### `linkdeps` + +A text file containing the labels of those transitive dependencies of targets listed in +`deps` that did not contribute any object files to the static library, but do provide at least one static, dynamic or interface library. The resulting static library -may require these libraries to be available at link time.</p> +may require these libraries to be available at link time. + +##### `linkopts` + +A text file containing the user-provided `linkopts` of all transitive +dependencies of targets listed in `deps`. -<h5><code>linkopts</code></h5> -<p>A text file containing the user-provided <code>linkopts</code> of all transitive -dependencies of targets listed in <code>deps</code>. +#### Duplicate symbols -<h4 id="cc_static_library_symbol_check">Duplicate symbols</h4> -<p>By default, the <code>cc_static_library</code> rule checks that the resulting static +By default, the `cc_static_library` rule checks that the resulting static library does not contain any duplicate symbols. If it does, the build fails with an error -message that lists the duplicate symbols and the object files containing them.</p> +message that lists the duplicate symbols and the object files containing them. -<p>This check can be disabled per target or per package by setting -<code>features = ["-symbol_check"]</code> or globally via -<code>--features=-symbol_check</code>.</p> +This check can be disabled per target or per package by setting +`features = ["-symbol_check"]` or globally via +`--features=-symbol_check`. -<h5 id="cc_static_library_symbol_check_toolchain">Toolchain support for <code>symbol_check</code></h5> -<p>The auto-configured C++ toolchains shipped with Bazel support the -<code>symbol_check</code> feature on all platforms. Custom toolchains can add support for -it in one of two ways:</p> -<ul> - <li>Implementing the <code>ACTION_NAMES.validate_static_library</code> action and - enabling it with the <code>symbol_check</code> feature. The tool set in the action is - invoked with two arguments, the static library to check for duplicate symbols and the - path of a file that must be created if the check passes.</li> - <li>Having the <code>symbol_check</code> feature add archiver flags that cause the - action creating the static library to fail on duplicate symbols.</li> -</ul> +##### Toolchain support for `symbol_check` - <h3 id="cc_static_library_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="cc_static_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="cc_static_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of targets to combine into a static library, including all their transitive -dependencies. +The auto-configured C++ toolchains shipped with Bazel support the +`symbol_check` feature on all platforms. Custom toolchains can add support for +it in one of two ways: +- Implementing the `ACTION_NAMES.validate_static_library` action and + enabling it with the `symbol_check` feature. The tool set in the action is + invoked with two arguments, the static library to check for duplicate symbols and the + path of a file that must be created if the check passes. +- Having the `symbol_check` feature add archiver flags that cause the + action creating the static library to fail on duplicate symbols. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="cc_static_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="cc_static_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of targets to combine into a static library, including all their transitive +dependencies. <p>Dependencies that do not provide any object files are not included in the static library, but their labels are collected in the file provided by the -<code>linkdeps</code> output group.</p> - </td> - </tr> - </tbody> - </table> - <h2 id="cc_test"> - cc_test - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_test.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">cc_test(<a href="#cc_test.name">name</a>, <a href="#cc_test.deps">deps</a>, <a href="#cc_test.srcs">srcs</a>, <a href="#cc_test.data">data</a>, <a href="#cc_test.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_test.conlyopts">conlyopts</a>, <a href="#cc_test.copts">copts</a>, <a href="#cc_test.cxxopts">cxxopts</a>, <a href="#cc_test.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#cc_test.distribs">distribs</a>, <a href="#cc_test.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#test.flaky">flaky</a>, <a href="#cc_test.hdrs_check">hdrs_check</a>, <a href="#cc_test.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_test.link_extra_lib">link_extra_lib</a>, <a href="#cc_test.linkopts">linkopts</a>, <a href="#cc_test.linkshared">linkshared</a>, <a href="#cc_test.linkstatic">linkstatic</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#cc_test.local_defines">local_defines</a>, <a href="#cc_test.malloc">malloc</a>, <a href="#cc_test.module_interfaces">module_interfaces</a>, <a href="#cc_test.nocopts">nocopts</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#cc_test.reexport_deps">reexport_deps</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#cc_test.stamp">stamp</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#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_test.win_def_file">win_def_file</a>)</pre> - - <p> -A <code>cc_test()</code> rule compiles a test. Here, a test +<code>linkdeps</code> output group.</p></td> +</tr> +</tbody> +</table> + +## cc_test + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_test.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +cc_test(name, deps, srcs, data, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local, local_defines, malloc, module_interfaces, nocopts, package_metadata, reexport_deps, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file) +``` + +A `cc_test()` rule compiles a test. Here, a test is a binary wrapper around some testing code. -</p> -<p><i>By default, C++ tests are dynamically linked.</i><br/> - To statically link a unit test, specify - <a href="/reference/be/c-cpp.html#cc_binary.linkstatic"><code>linkstatic=True</code></a>. - It would probably be good to comment why your test needs - <code>linkstatic</code>; this is probably not obvious.</p> +*By default, C++ tests are dynamically linked.* +To statically link a unit test, specify +[`linkstatic=True`](/reference/be/c-cpp.html#cc_binary.linkstatic). +It would probably be good to comment why your test needs +`linkstatic`; this is probably not obvious. -<h4>Implicit output targets</h4> -<ul> -<li><code><var>name</var>.stripped</code> (only built if explicitly requested): A stripped - version of the binary. <code>strip -g</code> is run on the binary to remove debug - symbols. Additional strip options can be provided on the command line using - <code>--stripopt=-foo</code>.</li> -<li><code><var>name</var>.dwp</code> (only built if explicitly requested): If - <a href="https://gcc.gnu.org/wiki/DebugFission">Fission</a> is enabled: a debug - information package file suitable for debugging remotely deployed binaries. Else: an - empty file.</li> -</ul> +#### Implicit output targets -<p> -See the <a href="/reference/be/c-cpp.html#cc_binary_args">cc_binary()</a> arguments, except that -the <code>stamp</code> argument is set to 0 by default for tests and -that <code>cc_test</code> has extra <a href="/reference/be/common-definitions#common-attributes-tests"> -attributes common to all test rules (*_test)</a>.</p> - - <h3 id="cc_test_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="cc_test.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="cc_test.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries to be linked in to the binary target. +- `name``.stripped` (only built if explicitly requested): A stripped + version of the binary. `strip -g` is run on the binary to remove debug + symbols. Additional strip options can be provided on the command line using + `--stripopt=-foo`. +- `name``.dwp` (only built if explicitly requested): If + [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug + information package file suitable for debugging remotely deployed binaries. Else: an + empty file. + +See the [cc_binary()](/reference/be/c-cpp.html#cc_binary_args) arguments, except that +the `stamp` argument is set to 0 by default for tests and +that `cc_test` has extra +[attributes common to all test rules (\*\_test)](/reference/be/common-definitions#common-attributes-tests). + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="cc_test.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="cc_test.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries to be linked in to the binary target. <p>These can be <code>cc_library</code> or <code>objc_library</code> targets.</p> - It is also allowed to put linker scripts (.lds) into deps, and reference them in -<a href="#cc_binary.linkopts">linkopts</a>. - </td> - </tr> - <tr> - <td id="cc_test.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of C and C++ files that are processed to create the library target. +<a href="#cc_binary.linkopts">linkopts</a>.</td> +</tr> +<tr> +<td id="cc_test.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. <p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will - be compiled. These might be generated files: if a named file is in - the <code>outs</code> of some other rule, this <code>cc_library</code> - will automatically depend on that other rule. -</p> +be compiled. These might be generated files: if a named file is in +the <code>outs</code> of some other rule, this <code>cc_library</code> +will automatically depend on that other rule.</p> <p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler. -</p> +using the C/C++ compiler.</p> <p>A <code>.h</code> file will not be compiled, but will be available for - inclusion by sources in this rule. Both <code>.cc</code> and - <code>.h</code> files can directly include headers listed in - these <code>srcs</code> or in the <code>hdrs</code> of this rule or any - rule listed in the <code>deps</code> argument. -</p> +inclusion by sources in this rule. Both <code>.cc</code> and +<code>.h</code> files can directly include headers listed in +these <code>srcs</code> or in the <code>hdrs</code> of this rule or any +rule listed in the <code>deps</code> argument.</p> <p>All <code>#include</code>d files must be mentioned in the - <code>hdrs</code> attribute of this or referenced <code>cc_library</code> - rules, or they should be listed in <code>srcs</code> if they are private - to this library. See <a href="#hdrs">"Header inclusion checking"</a> for - a more detailed description. -</p> +<code>hdrs</code> attribute of this or referenced <code>cc_library</code> +rules, or they should be listed in <code>srcs</code> if they are private +to this library. See <a href="#hdrs">"Header inclusion checking"</a> for +a more detailed description.</p> <p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are - pre-compiled files. Your library might have these as - <code>srcs</code> if it uses third-party code for which we don't - have source code. -</p> +pre-compiled files. Your library might have these as +<code>srcs</code> if it uses third-party code for which we don't +have source code.</p> <p>If the <code>srcs</code> attribute includes the label of another rule, - <code>cc_library</code> will use the output files of that rule as source files to - compile. This is useful for one-off generation of source code (for more than occasional - use, it's better to implement a Starlark rule class and use the <code>cc_common</code> - API) -</p> -<p> - Permitted <code>srcs</code> file types: -</p> +<code>cc_library</code> will use the output files of that rule as source files to +compile. This is useful for one-off generation of source code (for more than occasional +use, it's better to implement a Starlark rule class and use the <code>cc_common</code> +API)</p> +<p>Permitted <code>srcs</code> file types:</p> <ul> <li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, - <code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> +<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> <li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, - <code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> +<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> <li>Assembler with C preprocessor: <code>.S</code></li> <li>Archive: <code>.a</code>, <code>.pic.a</code></li> <li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> <li>Shared library, versioned or unversioned: <code>.so</code>, - <code>.so.<i>version</i></code></li> +<code>.so.</code><em><code>version</code></em></li> <li>Object file: <code>.o</code>, <code>.pic.o</code></li> </ul> - -<p> - ... and any rules that produce those files (e.g. <code>cc_embed_data</code>). - Different extensions denote different programming languages in - accordance with gcc convention. -</p> - </td> - </tr> - <tr> - <td id="cc_test.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this library at runtime. - +<p>... and any rules that produce those files (e.g. <code>cc_embed_data</code>). +Different extensions denote different programming languages in +accordance with gcc convention.</p></td> +</tr> +<tr> +<td id="cc_test.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this library at runtime. See general comments about <code>data</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by most build rules</a>. <p>If a <code>data</code> is the name of a generated file, then this - <code>cc_library</code> rule automatically depends on the generating - rule. -</p> +<code>cc_library</code> rule automatically depends on the generating +rule.</p> <p>If a <code>data</code> is a rule name, then this - <code>cc_library</code> rule automatically depends on that rule, - and that rule's <code>outs</code> are automatically added to - this <code>cc_library</code>'s data files. -</p> +<code>cc_library</code> rule automatically depends on that rule, +and that rule's <code>outs</code> are automatically added to +this <code>cc_library</code>'s data files.</p> <p>Your C++ code can access these data files like so:</p> -<pre><code class="lang-starlark"> +<pre class="lang-starlark"><code> const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file"); -</code></pre> - </td> - </tr> - <tr> - <td id="cc_test.additional_linker_inputs"> - <code>additional_linker_inputs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Pass these files to the C++ linker command. -<p> - For example, compiled Windows .res files can be provided here to be embedded in - the binary target. -</p> - </td> - </tr> - <tr> - <td id="cc_test.conlyopts"> - <code>conlyopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C compilation command. + "my/test/data/file");</code></pre></td> +</tr> +<tr> +<td id="cc_test.additional_linker_inputs"><code>additional_linker_inputs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Pass these files to the C++ linker command. +<p>For example, compiled Windows .res files can be provided here to be embedded in +the binary target.</p></td> +</tr> +<tr> +<td id="cc_test.conlyopts"><code>conlyopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. - </td> - </tr> - <tr> - <td id="cc_test.copts"> - <code>copts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C/C++ compilation command. +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> +</tr> +<tr> +<td id="cc_test.copts"><code>copts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C/C++ compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -<p> - Each string in this attribute is added in the given order to <code>COPTS</code> before - compiling the binary target. The flags take effect only for compiling this target, not - its dependencies, so be careful about header files included elsewhere. - All paths should be relative to the workspace, not to the current package. - This attribute should not be needed outside of <code>third_party</code>. -</p> -<p> - If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> - <code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings - that consist of a single "Make" variable. -</p> - </td> - </tr> - <tr> - <td id="cc_test.cxxopts"> - <code>cxxopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these options to the C++ compilation command. +<p>Each string in this attribute is added in the given order to <code>COPTS</code> before +compiling the binary target. The flags take effect only for compiling this target, not +its dependencies, so be careful about header files included elsewhere. +All paths should be relative to the workspace, not to the current package. +This attribute should not be needed outside of <code>third_party</code>.</p> +<p>If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> +<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings +that consist of a single "Make" variable.</p></td> +</tr> +<tr> +<td id="cc_test.cxxopts"><code>cxxopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these options to the C++ compilation command. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. - </td> - </tr> - <tr> - <td id="cc_test.defines"> - <code>defines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of defines to add to the compile line. +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> +</tr> +<tr> +<td id="cc_test.defines"><code>defines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of defines to add to the compile line. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. Each string, which must consist of a single Bourne shell token, is prepended with <code>-D</code> and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects. When in doubt, add define values to -<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead. - </td> - </tr> - <tr> - <td id="cc_test.distribs"> - <code>distribs</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_test.dynamic_deps"> - <code>dynamic_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - These are other <code>cc_shared_library</code> dependencies the current target depends on. - -<p> -The <code>cc_shared_library</code> implementation will use the list of +far-reaching effects. When in doubt, add define values to +<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.</td> +</tr> +<tr> +<td id="cc_test.distribs"><code>distribs</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_test.dynamic_deps"><code>dynamic_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +These are other <code>cc_shared_library</code> dependencies the current target depends on. +<p>The <code>cc_shared_library</code> implementation will use the list of <code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in the transitive <code>deps</code> should not be linked in because they are already provided -by a different <code>cc_shared_library</code>. - </td> - </tr> - <tr> - <td id="cc_test.hdrs_check"> - <code>hdrs_check</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Deprecated, no-op. - </td> - </tr> - <tr> - <td id="cc_test.includes"> - <code>includes</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of include dirs to be added to the compile line. +by a different <code>cc_shared_library</code>.</p></td> +</tr> +<tr> +<td id="cc_test.hdrs_check"><code>hdrs_check</code></td> +<td><p>String; default is <code>""</code></p> +Deprecated, no-op.</td> +</tr> +<tr> +<td id="cc_test.includes"><code>includes</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of include dirs to be added to the compile line. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system @@ -2407,766 +1793,524 @@ This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add +very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. -<p> -The added <code>include</code> paths will include generated files as well as -files in the source tree. -</p> - </td> - </tr> - <tr> - <td id="cc_test.link_extra_lib"> - <code>link_extra_lib</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p> - Control linking of extra libraries. -<p> - By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>, - which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>. - Without setting the flag, this library is empty by default. Setting the label flag - allows linking optional dependencies, such as overrides for weak symbols, interceptors - for shared library functions, or special runtime libraries (for malloc replacements, - prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to - <code>None</code> disables this behaviour. -</p> - </td> - </tr> - <tr> - <td id="cc_test.linkopts"> - <code>linkopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Add these flags to the C++ linker command. +<p>The added <code>include</code> paths will include generated files as well as +files in the source tree.</p></td> +</tr> +<tr> +<td id="cc_test.link_extra_lib"><code>link_extra_lib</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p> +Control linking of extra libraries. +<p>By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>, +which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>. +Without setting the flag, this library is empty by default. Setting the label flag +allows linking optional dependencies, such as overrides for weak symbols, interceptors +for shared library functions, or special runtime libraries (for malloc replacements, +prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to +<code>None</code> disables this behaviour.</p></td> +</tr> +<tr> +<td id="cc_test.linkopts"><code>linkopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Add these flags to the C++ linker command. Subject to <a href="make-variables.html">"Make" variable</a> substitution, -<a href="common-definitions.html#sh-tokenization"> -Bourne shell tokenization</a> and +<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a> and <a href="common-definitions.html#label-expansion">label expansion</a>. Each string in this attribute is added to <code>LINKOPTS</code> before linking the binary target. -<p> - Each element of this list that does not start with <code>$</code> or <code>-</code> is - assumed to be the label of a target in <code>deps</code>. The - list of files generated by that target is appended to the linker - options. An error is reported if the label is invalid, or is - not declared in <code>deps</code>. -</p> - </td> - </tr> - <tr> - <td id="cc_test.linkshared"> - <code>linkshared</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Create a shared library. +<p>Each element of this list that does not start with <code>$</code> or <code>-</code> is +assumed to be the label of a target in <code>deps</code>. The +list of files generated by that target is appended to the linker +options. An error is reported if the label is invalid, or is +not declared in <code>deps</code>.</p></td> +</tr> +<tr> +<td id="cc_test.linkshared"><code>linkshared</code></td> +<td><p>Boolean; default is <code>False</code></p> +Create a shared library. To enable this attribute, include <code>linkshared=True</code> in your rule. By default this option is off. -<p> - The presence of this flag means that linking occurs with the <code>-shared</code> flag - to <code>gcc</code>, and the resulting shared library is suitable for loading into for - example a Java program. However, for build purposes it will never be linked into the - dependent binary, as it is assumed that shared libraries built with a - <a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so - it should not be considered a substitute for the <a href="#cc_library">cc_library</a> - rule. For sake of scalability we recommend avoiding this approach altogether and - simply letting <code>java_library</code> depend on <code>cc_library</code> rules - instead. -</p> -<p> - If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>, - you get a single completely self-contained unit. If you specify both - <code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly - self-contained unit. -</p> - </td> - </tr> - <tr> - <td id="cc_test.linkstatic"> - <code>linkstatic</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and +<p>The presence of this flag means that linking occurs with the <code>-shared</code> flag +to <code>gcc</code>, and the resulting shared library is suitable for loading into for +example a Java program. However, for build purposes it will never be linked into the +dependent binary, as it is assumed that shared libraries built with a +<a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so +it should not be considered a substitute for the <a href="#cc_library">cc_library</a> +rule. For sake of scalability we recommend avoiding this approach altogether and +simply letting <code>java_library</code> depend on <code>cc_library</code> rules +instead.</p> +<p>If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>, +you get a single completely self-contained unit. If you specify both +<code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly +self-contained unit.</p></td> +</tr> +<tr> +<td id="cc_test.linkstatic"><code>linkstatic</code></td> +<td><p>Boolean; default is <code>False</code></p> +For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and <a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static mode. For <code>cc_library.link_static</code>: see below. <p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> -<p> - If enabled and this is a binary or test, this option tells the build tool to link in - <code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. - System libraries such as libc (but <i>not</i> the C/C++ runtime libraries, - see below) are still linked dynamically, as are libraries for which - there is no static library. So the resulting executable will still be dynamically - linked, hence only <i>mostly</i> static. -</p> -<p> -There are really three different ways to link an executable: -</p> +<p>If enabled and this is a binary or test, this option tells the build tool to link in +<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. +System libraries such as libc (but <em>not</em> the C/C++ runtime libraries, +see below) are still linked dynamically, as are libraries for which +there is no static library. So the resulting executable will still be dynamically +linked, hence only <em>mostly</em> static.</p> +<p>There are really three different ways to link an executable:</p> <ul> -<li> STATIC with fully_static_link feature, in which everything is linked statically; - e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/> - This mode is enabled by specifying <code>fully_static_link</code> in the - <a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> -<li> STATIC, in which all user libraries are linked statically (if a static - version is available), but where system libraries (excluding C/C++ runtime libraries) - are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/> - This mode is enabled by specifying <code>linkstatic=True</code>.</li> -<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is - available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/> - This mode is enabled by specifying <code>linkstatic=False</code>.</li> +<li>STATIC with fully_static_link feature, in which everything is linked statically; +e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br /> +This mode is enabled by specifying <code>fully_static_link</code> in the +<a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> +<li>STATIC, in which all user libraries are linked statically (if a static +version is available), but where system libraries (excluding C/C++ runtime libraries) +are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br /> +This mode is enabled by specifying <code>linkstatic=True</code>.</li> +<li>DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is +available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br /> +This mode is enabled by specifying <code>linkstatic=False</code>.</li> </ul> -<p> -If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in +<p>If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in <code>features</code> is used outside of <code>//third_party</code> -please include a comment near the rule to explain why. -</p> -<p> -The <code>linkstatic</code> attribute has a different meaning if used on a +please include a comment near the rule to explain why.</p> +<p>The <code>linkstatic</code> attribute has a different meaning if used on a <a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. For a C++ library, <code>linkstatic=True</code> indicates that only static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries. -</p> -<p> -There should be very little code built with <code>linkstatic=False</code> in production. +creation of dynamic libraries.</p> +<p>There should be very little code built with <code>linkstatic=False</code> in production. If <code>linkstatic=False</code>, then the build tool will create symlinks to -depended-upon shared libraries in the <code>*.runfiles</code> area. -</p> - </td> - </tr> - <tr> - <td id="cc_test.local_defines"> - <code>local_defines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of defines to add to the compile line. +depended-upon shared libraries in the <code>*.runfiles</code> area.</p></td> +</tr> +<tr> +<td id="cc_test.local_defines"><code>local_defines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of defines to add to the compile line. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. Each string, which must consist of a single Bourne shell token, is prepended with <code>-D</code> and added to the compile command line for this target, -but not to its dependents. - </td> - </tr> - <tr> - <td id="cc_test.malloc"> - <code>malloc</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p> - Override the default dependency on malloc. -<p> - By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>, - which is an empty library so the binary ends up using libc malloc. - This label must refer to a <code>cc_library</code>. If compilation is for a non-C++ - rule, this option has no effect. The value of this attribute is ignored if - <code>linkshared=True</code> is specified. -</p> - </td> - </tr> - <tr> - <td id="cc_test.module_interfaces"> - <code>module_interfaces</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files are regarded as C++20 Modules Interface. - -<p> -C++ Standard has no restriction about module interface file extension +but not to its dependents.</td> +</tr> +<tr> +<td id="cc_test.malloc"><code>malloc</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p> +Override the default dependency on malloc. +<p>By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>, +which is an empty library so the binary ends up using libc malloc. +This label must refer to a <code>cc_library</code>. If compilation is for a non-C++ +rule, this option has no effect. The value of this attribute is ignored if +<code>linkshared=True</code> is specified.</p></td> +</tr> +<tr> +<td id="cc_test.module_interfaces"><code>module_interfaces</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files are regarded as C++20 Modules Interface. +<p>C++ Standard has no restriction about module interface file extension</p> <ul> -<li>Clang use cppm </li> -<li>GCC can use any source file extension </li> -<li>MSVC use ixx </li> +<li>Clang use cppm</li> +<li>GCC can use any source file extension</li> +<li>MSVC use ixx</li> </ul> -</p> <p>The use is guarded by the flag -<code>--experimental_cpp_modules</code>.</p> - </td> - </tr> - <tr> - <td id="cc_test.nocopts"> - <code>nocopts</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Remove matching options from the C++ compilation command. +<code>--experimental_cpp_modules</code>.</p></td> +</tr> +<tr> +<td id="cc_test.nocopts"><code>nocopts</code></td> +<td><p>String; default is <code>""</code></p> +Remove matching options from the C++ compilation command. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. The value of this attribute is interpreted as a regular expression. Any preexisting <code>COPTS</code> that match this regular expression -(including values explicitly specified in the rule's <a -href="#cc_binary.copts">copts</a> attribute) +(including values explicitly specified in the rule's <a href="#cc_binary.copts">copts</a> attribute) will be removed from <code>COPTS</code> for purposes of compiling this rule. This attribute should not be needed or used -outside of <code>third_party</code>. The values are not preprocessed -in any way other than the "Make" variable substitution. - </td> - </tr> - <tr> - <td id="cc_test.reexport_deps"> - <code>reexport_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_test.stamp"> - <code>stamp</code> - </td> - <td> - <p>Integer; default is <code>0</code></p> - Whether to encode build information into the binary. Possible values: +outside of <code>third_party</code>. The values are not preprocessed +in any way other than the "Make" variable substitution.</td> +</tr> +<tr> +<td id="cc_test.reexport_deps"><code>reexport_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_test.stamp"><code>stamp</code></td> +<td><p>Integer; default is <code>0</code></p> +Whether to encode build information into the binary. Possible values: <ul> -<li> - <code>stamp = 1</code>: Always stamp the build information into the binary, even in - <a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This - setting should be avoided</b>, since it potentially kills remote caching for the - binary and any downstream actions that depend on it. -</li> -<li> - <code>stamp = 0</code>: Always replace build information by constant values. This - gives good build result caching. -</li> -<li> - <code>stamp = -1</code>: Embedding of build information is controlled by the - <a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag. -</li> +<li><code>stamp = 1</code>: Always stamp the build information into the binary, even in +<a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <strong>This +setting should be avoided</strong>, since it potentially kills remote caching for the +binary and any downstream actions that depend on it.</li> +<li><code>stamp = 0</code>: Always replace build information by constant values. This +gives good build result caching.</li> +<li><code>stamp = -1</code>: Embedding of build information is controlled by the +<a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.</li> </ul> -<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> - </td> - </tr> - <tr> - <td id="cc_test.win_def_file"> - <code>win_def_file</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - The Windows DEF file to be passed to linker. +<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p></td> +</tr> +<tr> +<td id="cc_test.win_def_file"><code>win_def_file</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +The Windows DEF file to be passed to linker. <p>This attribute should only be used when Windows is the target platform. -It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx"> -export symbols</a> during linking a shared library.</p> - </td> - </tr> - </tbody> - </table> - <h2 id="cc_toolchain"> - cc_toolchain - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_toolchain.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">cc_toolchain(<a href="#cc_toolchain.name">name</a>, <a href="#cc_toolchain.all_files">all_files</a>, <a href="#cc_toolchain.ar_files">ar_files</a>, <a href="#cc_toolchain.as_files">as_files</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_toolchain.compiler_files">compiler_files</a>, <a href="#cc_toolchain.compiler_files_without_includes">compiler_files_without_includes</a>, <a href="#cc_toolchain.coverage_files">coverage_files</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#cc_toolchain.dwp_files">dwp_files</a>, <a href="#cc_toolchain.dynamic_runtime_lib">dynamic_runtime_lib</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#cc_toolchain.exec_transition_for_inputs">exec_transition_for_inputs</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#cc_toolchain.libc_top">libc_top</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_toolchain.linker_files">linker_files</a>, <a href="#cc_toolchain.module_map">module_map</a>, <a href="#cc_toolchain.objcopy_files">objcopy_files</a>, <a href="#cc_toolchain.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_toolchain.static_runtime_lib">static_runtime_lib</a>, <a href="#cc_toolchain.strip_files">strip_files</a>, <a href="#cc_toolchain.supports_header_parsing">supports_header_parsing</a>, <a href="#cc_toolchain.supports_param_files">supports_param_files</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="#cc_toolchain.toolchain_config">toolchain_config</a>, <a href="#cc_toolchain.toolchain_identifier">toolchain_identifier</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p>Represents a C++ toolchain.</p> - -<p> - This rule is responsible for: - - <ul> - <li> - Collecting all artifacts needed for C++ actions to run. This is done by - attributes such as <code>all_files</code>, <code>compiler_files</code>, - <code>linker_files</code>, or other attributes ending with <code>_files</code>). These are - most commonly filegroups globbing all required files. - </li> - <li> - Generating correct command lines for C++ actions. This is done using - <code>CcToolchainConfigInfo</code> provider (details below). - </li> - </ul> -</p> -<p> - Use <code>toolchain_config</code> attribute to configure the C++ toolchain. - See also this - <a href="https://bazel.build/docs/cc-toolchain-config-reference"> - page - </a> for elaborate C++ toolchain configuration and toolchain selection documentation. -</p> -<p> - Use <code>tags = ["manual"]</code> in order to prevent toolchains from being built and configured - unnecessarily when invoking <code>bazel build //...</code> -</p> - - <h3 id="cc_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="cc_toolchain.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="cc_toolchain.all_files"> - <code>all_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Collection of all cc_toolchain artifacts. These artifacts will be added as inputs to all +It can be used to +<a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">export symbols</a> during linking a shared library.</p></td> +</tr> +</tbody> +</table> + +## cc_toolchain + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_toolchain.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +cc_toolchain(name, all_files, ar_files, as_files, aspect_hints, compatible_with, compiler_files, compiler_files_without_includes, coverage_files, deprecation, dwp_files, dynamic_runtime_lib, exec_compatible_with, exec_group_compatible_with, exec_properties, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, output_licenses, package_metadata, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, toolchains, visibility) +``` + +Represents a C++ toolchain. + +This rule is responsible for: + +- Collecting all artifacts needed for C++ actions to run. This is done by + attributes such as `all_files`, `compiler_files`, + `linker_files`, or other attributes ending with `_files`). These are + most commonly filegroups globbing all required files. +- Generating correct command lines for C++ actions. This is done using + `CcToolchainConfigInfo` provider (details below). + +Use `toolchain_config` attribute to configure the C++ toolchain. +See also this +[page](https://bazel.build/docs/cc-toolchain-config-reference) +for elaborate C++ toolchain configuration and toolchain selection documentation. + +Use `tags = ["manual"]` in order to prevent toolchains from being built and configured +unnecessarily when invoking `bazel build //...` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="cc_toolchain.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="cc_toolchain.all_files"><code>all_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Collection of all cc_toolchain artifacts. These artifacts will be added as inputs to all rules_cc related actions (with the exception of actions that are using more precise sets of artifacts from attributes below). Bazel assumes that <code>all_files</code> is a superset of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile and link files, so it takes <code>all_files</code>). - -<p> -This is what <code>cc_toolchain.files</code> contains, and this is used by all Starlark -rules using C++ toolchain.</p> - </td> - </tr> - <tr> - <td id="cc_toolchain.ar_files"> - <code>ar_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Collection of all cc_toolchain artifacts required for archiving actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.as_files"> - <code>as_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Collection of all cc_toolchain artifacts required for assembly actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.compiler_files"> - <code>compiler_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Collection of all cc_toolchain artifacts required for compile actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.compiler_files_without_includes"> - <code>compiler_files_without_includes</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Collection of all cc_toolchain artifacts required for compile actions in case when -input discovery is supported (currently Google-only). - </td> - </tr> - <tr> - <td id="cc_toolchain.coverage_files"> - <code>coverage_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Collection of all cc_toolchain artifacts required for coverage actions. If not specified, -all_files are used. - </td> - </tr> - <tr> - <td id="cc_toolchain.dwp_files"> - <code>dwp_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Collection of all cc_toolchain artifacts required for dwp actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.dynamic_runtime_lib"> - <code>dynamic_runtime_lib</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). - +<p>This is what <code>cc_toolchain.files</code> contains, and this is used by all Starlark +rules using C++ toolchain.</p></td> +</tr> +<tr> +<td id="cc_toolchain.ar_files"><code>ar_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Collection of all cc_toolchain artifacts required for archiving actions.</td> +</tr> +<tr> +<td id="cc_toolchain.as_files"><code>as_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Collection of all cc_toolchain artifacts required for assembly actions.</td> +</tr> +<tr> +<td id="cc_toolchain.compiler_files"><code>compiler_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Collection of all cc_toolchain artifacts required for compile actions.</td> +</tr> +<tr> +<td id="cc_toolchain.compiler_files_without_includes"><code>compiler_files_without_includes</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Collection of all cc_toolchain artifacts required for compile actions in case when +input discovery is supported (currently Google-only).</td> +</tr> +<tr> +<td id="cc_toolchain.coverage_files"><code>coverage_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Collection of all cc_toolchain artifacts required for coverage actions. If not specified, +all_files are used.</td> +</tr> +<tr> +<td id="cc_toolchain.dwp_files"><code>dwp_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Collection of all cc_toolchain artifacts required for dwp actions.</td> +</tr> +<tr> +<td id="cc_toolchain.dynamic_runtime_lib"><code>dynamic_runtime_lib</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). <p>This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking -dependencies dynamically.</p> - </td> - </tr> - <tr> - <td id="cc_toolchain.exec_transition_for_inputs"> - <code>exec_transition_for_inputs</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Deprecated. No-op. - </td> - </tr> - <tr> - <td id="cc_toolchain.libc_top"> - <code>libc_top</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - A collection of artifacts for libc passed as inputs to compile/linking actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.linker_files"> - <code>linker_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Collection of all cc_toolchain artifacts required for linking actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.module_map"> - <code>module_map</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Module map artifact to be used for modular builds. - </td> - </tr> - <tr> - <td id="cc_toolchain.objcopy_files"> - <code>objcopy_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Collection of all cc_toolchain artifacts required for objcopy actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.output_licenses"> - <code>output_licenses</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="cc_toolchain.static_runtime_lib"> - <code>static_runtime_lib</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Static library artifact for the C++ runtime library (e.g. libstdc++.a). - +dependencies dynamically.</p></td> +</tr> +<tr> +<td id="cc_toolchain.exec_transition_for_inputs"><code>exec_transition_for_inputs</code></td> +<td><p>Boolean; default is <code>False</code></p> +Deprecated. No-op.</td> +</tr> +<tr> +<td id="cc_toolchain.libc_top"><code>libc_top</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +A collection of artifacts for libc passed as inputs to compile/linking actions.</td> +</tr> +<tr> +<td id="cc_toolchain.linker_files"><code>linker_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Collection of all cc_toolchain artifacts required for linking actions.</td> +</tr> +<tr> +<td id="cc_toolchain.module_map"><code>module_map</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Module map artifact to be used for modular builds.</td> +</tr> +<tr> +<td id="cc_toolchain.objcopy_files"><code>objcopy_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Collection of all cc_toolchain artifacts required for objcopy actions.</td> +</tr> +<tr> +<td id="cc_toolchain.output_licenses"><code>output_licenses</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="cc_toolchain.static_runtime_lib"><code>static_runtime_lib</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Static library artifact for the C++ runtime library (e.g. libstdc++.a). <p>This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking -dependencies statically.</p> - </td> - </tr> - <tr> - <td id="cc_toolchain.strip_files"> - <code>strip_files</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Collection of all cc_toolchain artifacts required for strip actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.supports_header_parsing"> - <code>supports_header_parsing</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Set to True when cc_toolchain supports header parsing actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.supports_param_files"> - <code>supports_param_files</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - Set to True when cc_toolchain supports using param files for linking actions. - </td> - </tr> - <tr> - <td id="cc_toolchain.toolchain_config"> - <code>toolchain_config</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - The label of the rule providing <code>cc_toolchain_config_info</code>. - </td> - </tr> - <tr> - <td id="cc_toolchain.toolchain_identifier"> - <code>toolchain_identifier</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The identifier used to match this cc_toolchain with the corresponding +dependencies statically.</p></td> +</tr> +<tr> +<td id="cc_toolchain.strip_files"><code>strip_files</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Collection of all cc_toolchain artifacts required for strip actions.</td> +</tr> +<tr> +<td id="cc_toolchain.supports_header_parsing"><code>supports_header_parsing</code></td> +<td><p>Boolean; default is <code>False</code></p> +Set to True when cc_toolchain supports header parsing actions.</td> +</tr> +<tr> +<td id="cc_toolchain.supports_param_files"><code>supports_param_files</code></td> +<td><p>Boolean; default is <code>True</code></p> +Set to True when cc_toolchain supports using param files for linking actions.</td> +</tr> +<tr> +<td id="cc_toolchain.toolchain_config"><code>toolchain_config</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +The label of the rule providing <code>cc_toolchain_config_info</code>.</td> +</tr> +<tr> +<td id="cc_toolchain.toolchain_identifier"><code>toolchain_identifier</code></td> +<td><p>String; default is <code>""</code></p> +The identifier used to match this cc_toolchain with the corresponding crosstool_config.toolchain. +<p>Until issue <a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a> is fixed +this is the recommended way of associating <code>cc_toolchain</code> with +<code>CROSSTOOL.toolchain</code>. It will be replaced by the <code>toolchain_config</code> +attribute (<a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a>).</p></td> +</tr> +</tbody> +</table> + +## fdo_prefetch_hints + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_prefetch_hints.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +fdo_prefetch_hints(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Represents an FDO prefetch hints profile that is either in the workspace. +Examples: + +``` lang-starlark -<p> - Until issue <a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a> is fixed - this is the recommended way of associating <code>cc_toolchain</code> with - <code>CROSSTOOL.toolchain</code>. It will be replaced by the <code>toolchain_config</code> - attribute (<a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a>).</p> - </td> - </tr> - </tbody> - </table> - <h2 id="fdo_prefetch_hints"> - fdo_prefetch_hints - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_prefetch_hints.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">fdo_prefetch_hints(<a href="#fdo_prefetch_hints.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</a>, <a href="#fdo_prefetch_hints.profile">profile</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p>Represents an FDO prefetch hints profile that is either in the workspace. -Examples:</p> - -<pre><code class="lang-starlark"> fdo_prefetch_hints( name = "hints", profile = "//path/to/hints:profile.afdo", ) -</code></pre> - - <h3 id="fdo_prefetch_hints_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="fdo_prefetch_hints.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="fdo_prefetch_hints.profile"> - <code>profile</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Label of the hints profile. The hints file has the .afdo extension -The label can also point to an fdo_absolute_path_profile rule. - </td> - </tr> - </tbody> - </table> - <h2 id="fdo_profile"> - fdo_profile - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_profile.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">fdo_profile(<a href="#fdo_profile.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#fdo_profile.memprof_profile">memprof_profile</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#fdo_profile.profile">profile</a>, <a href="#fdo_profile.proto_profile">proto_profile</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p>Represents an FDO profile that is in the workspace. -Example:</p> - -<pre><code class="lang-starlark"> +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="fdo_prefetch_hints.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="fdo_prefetch_hints.profile"><code>profile</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Label of the hints profile. The hints file has the .afdo extension +The label can also point to an fdo_absolute_path_profile rule.</td> +</tr> +</tbody> +</table> + +## fdo_profile + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_profile.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +fdo_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, memprof_profile, package_metadata, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Represents an FDO profile that is in the workspace. +Example: + +``` lang-starlark + fdo_profile( name = "fdo", profile = "//path/to/fdo:profile.zip", ) -</code></pre> - - <h3 id="fdo_profile_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="fdo_profile.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="fdo_profile.memprof_profile"> - <code>memprof_profile</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the MemProf profile. The profile is expected to have +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="fdo_profile.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="fdo_profile.memprof_profile"><code>memprof_profile</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the MemProf profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata -file. - </td> - </tr> - <tr> - <td id="fdo_profile.profile"> - <code>profile</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Label of the FDO profile or a rule which generates it. The FDO file can have one of the +file.</td> +</tr> +<tr> +<td id="fdo_profile.profile"><code>profile</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Label of the FDO profile or a rule which generates it. The FDO file can have one of the following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for -XBinary profile. The label can also point to an fdo_absolute_path_profile rule. - </td> - </tr> - <tr> - <td id="fdo_profile.proto_profile"> - <code>proto_profile</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the protobuf profile. - </td> - </tr> - </tbody> - </table> - <h2 id="memprof_profile"> - memprof_profile - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/memprof_profile.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">memprof_profile(<a href="#memprof_profile.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</a>, <a href="#memprof_profile.profile">profile</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p>Represents a MEMPROF profile that is in the workspace. -Example:</p> - -<pre><code class="lang-starlark"> +XBinary profile. The label can also point to an fdo_absolute_path_profile rule.</td> +</tr> +<tr> +<td id="fdo_profile.proto_profile"><code>proto_profile</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the protobuf profile.</td> +</tr> +</tbody> +</table> + +## memprof_profile + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/memprof_profile.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +memprof_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Represents a MEMPROF profile that is in the workspace. +Example: + +``` lang-starlark + memprof_profile( name = "memprof", profile = "//path/to/memprof:profile.afdo", ) - -</code></pre> - - <h3 id="memprof_profile_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="memprof_profile.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="memprof_profile.profile"> - <code>profile</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Label of the MEMPROF profile. The profile is expected to have +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="memprof_profile.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="memprof_profile.profile"><code>profile</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Label of the MEMPROF profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file. -The label can also point to an fdo_absolute_path_profile rule. - </td> - </tr> - </tbody> - </table> - <h2 id="propeller_optimize"> - propeller_optimize - </h2> +The label can also point to an fdo_absolute_path_profile rule.</td> +</tr> +</tbody> +</table> + +## propeller_optimize - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/propeller_optimize.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/propeller_optimize.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <pre class="rule-signature">propeller_optimize(<a href="#propeller_optimize.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#propeller_optimize.cc_profile">cc_profile</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#propeller_optimize.ld_profile">ld_profile</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +``` rule-signature +propeller_optimize(name, aspect_hints, cc_profile, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, ld_profile, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` - <p>Represents a Propeller optimization profile in the workspace. -Example:</p> +Represents a Propeller optimization profile in the workspace. +Example: + +``` lang-starlark -<pre><code class="lang-starlark"> propeller_optimize( name = "layout", cc_profile = "//path:cc_profile.txt", ld_profile = "//path:ld_profile.txt" ) -</code></pre> - - <h3 id="propeller_optimize_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="propeller_optimize.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="propeller_optimize.cc_profile"> - <code>cc_profile</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Label of the profile passed to the various compile actions. This file has -the .txt extension. - </td> - </tr> - <tr> - <td id="propeller_optimize.ld_profile"> - <code>ld_profile</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - Label of the profile passed to the link action. This file has -the .txt extension. - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="propeller_optimize.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="propeller_optimize.cc_profile"><code>cc_profile</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Label of the profile passed to the various compile actions. This file has +the .txt extension.</td> +</tr> +<tr> +<td id="propeller_optimize.ld_profile"><code>ld_profile</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +Label of the profile passed to the link action. This file has +the .txt extension.</td> +</tr> +</tbody> +</table> diff --git a/reference/be/common-definitions.mdx b/reference/be/common-definitions.mdx index 7c437c3..02d2e4a 100644 --- a/reference/be/common-definitions.mdx +++ b/reference/be/common-definitions.mdx @@ -2,229 +2,162 @@ title: 'common-definitions' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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 --> - -<h1 class="page-title" id="common-definitions">Common definitions</h1> +# Common definitions {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm" %} -{% include "_buttons.html" %} -<p>This section defines various terms and concepts that are common to -many functions or build rules. -</p> - -<h2>Contents</h2> -<ul> - <li><a href="#sh-tokenization">Bourne shell tokenization</a></li> - <li><a href="#label-expansion">Label Expansion</a></li> - <li><a href="#typical-attributes">Typical attributes defined by most build rules</a></li> - <li><a href="#common-attributes">Attributes common to all build rules</a></li> - <li><a href="#common-attributes-tests">Attributes common to all test rules (*_test)</a></li> - <li><a href="#common-attributes-binaries">Attributes common to all binary rules (*_binary)</a></li> - <li><a href="#configurable-attributes">Configurable attributes</a></li> - <li><a href="#implicit-outputs">Implicit output targets</a></li> -</ul> -<h2 id='sh-tokenization'>Bourne shell tokenization</h2> -<p> - Certain string attributes of some rules are split into multiple - words according to the tokenization rules of the Bourne shell: - unquoted spaces delimit separate words, and single- and - double-quotes characters and backslashes are used to prevent - tokenization. -</p> -<p> - Those attributes that are subject to this tokenization are - explicitly indicated as such in their definitions in this document. -</p> -<p> - Attributes subject to "Make" variable expansion and Bourne shell - tokenization are typically used for passing arbitrary options to - compilers and other tools. Examples of such attributes are - <code>cc_library.copts</code> and <code>java_library.javacopts</code>. - Together these substitutions allow a - single string variable to expand into a configuration-specific list - of option words. -</p> - -<h2 id='label-expansion'>Label expansion</h2> -<p> - Some string attributes of a very few rules are subject to label - expansion: if those strings contain a valid label as a - substring, such as <code>//mypkg:target</code>, and that label is a - declared prerequisite of the current rule, it is expanded into the - pathname of the file represented by the - <a href="https://bazel.build/reference/glossary#target">target</a> - <code>//mypkg:target</code>. -</p> - -<p> - Example attributes include <code>genrule.cmd</code> and - <code>cc_binary.linkopts</code>. The details may vary significantly in - each case, over such issues as: whether relative labels are - expanded; how labels that expand to multiple files are - treated, etc. Consult the rule attribute documentation for - specifics. -</p> +{% include "\_buttons.html" %} +This section defines various terms and concepts that are common to +many functions or build rules. -<h2 id="typical-attributes">Typical attributes defined by most build rules</h2> - -<p>This section describes attributes that are defined by many build rules, +## Contents + +- [Bourne shell tokenization](#sh-tokenization) +- [Label Expansion](#label-expansion) +- [Typical attributes defined by most build rules](#typical-attributes) +- [Attributes common to all build rules](#common-attributes) +- [Attributes common to all test rules (\*\_test)](#common-attributes-tests) +- [Attributes common to all binary rules (\*\_binary)](#common-attributes-binaries) +- [Configurable attributes](#configurable-attributes) +- [Implicit output targets](#implicit-outputs) + +## Bourne shell tokenization + +Certain string attributes of some rules are split into multiple +words according to the tokenization rules of the Bourne shell: +unquoted spaces delimit separate words, and single- and +double-quotes characters and backslashes are used to prevent +tokenization. + +Those attributes that are subject to this tokenization are +explicitly indicated as such in their definitions in this document. + +Attributes subject to "Make" variable expansion and Bourne shell +tokenization are typically used for passing arbitrary options to +compilers and other tools. Examples of such attributes are +`cc_library.copts` and `java_library.javacopts`. +Together these substitutions allow a +single string variable to expand into a configuration-specific list +of option words. + +## Label expansion + +Some string attributes of a very few rules are subject to label +expansion: if those strings contain a valid label as a +substring, such as `//mypkg:target`, and that label is a +declared prerequisite of the current rule, it is expanded into the +pathname of the file represented by the +[target](https://bazel.build/reference/glossary#target) +`//mypkg:target`. + +Example attributes include `genrule.cmd` and +`cc_binary.linkopts`. The details may vary significantly in +each case, over such issues as: whether relative labels are +expanded; how labels that expand to multiple files are +treated, etc. Consult the rule attribute documentation for +specifics. + +## Typical attributes defined by most build rules + +This section describes attributes that are defined by many build rules, but not all. -</p> - <table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="typical.data"><code>data</code></td> - <td><a name="common.data"></a> +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th>Attribute</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="typical.data"><code>data</code></td> +<td><span id="common.data"></span> <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - -<p> -Files needed by this rule at runtime. May list file or rule targets. Generally -allows any target. -</p> - -<p> -The default outputs and runfiles of targets in the <code>data</code> attribute +<p>Files needed by this rule at runtime. May list file or rule targets. Generally +allows any target.</p> +<p>The default outputs and runfiles of targets in the <code>data</code> attribute should appear in the <code>*.runfiles</code> area of any executable which is output by or has a runtime dependency on this target. This may include data files or binaries used when this target's <a href="#typical.srcs"><code>srcs</code></a> are executed. See the <a href="/concepts/dependencies#data-dependencies">data dependencies</a> -section for more information about how to depend on and use data files. -</p> - -<p> -New rules should define a <code>data</code> attribute if they process +section for more information about how to depend on and use data files.</p> +<p>New rules should define a <code>data</code> attribute if they process inputs which might use other inputs at runtime. Rules' implementation functions must also <a href="https://bazel.build/rules/rules#runfiles">populate the target's runfiles</a> from the outputs and runfiles of any <code>data</code> attribute, as well as runfiles from any dependency attribute which provides either -source code or runtime dependencies. -</p> -</td> - </tr> - <tr> - <td id="typical.deps"><code>deps</code></td> - <td><a name="common.deps"></a> +source code or runtime dependencies.</p></td> +</tr> +<tr> +<td id="typical.deps"><code>deps</code></td> +<td><span id="common.deps"></span> <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - -<p> -Dependencies for this target. Generally should only list rule targets. (Though +<p>Dependencies for this target. Generally should only list rule targets. (Though some rules permit files to be listed directly in <code>deps</code>, this -should be avoided when possible.) -</p> - -<p> -Language-specific rules generally limit the listed targets to those with +should be avoided when possible.)</p> +<p>Language-specific rules generally limit the listed targets to those with specific <a href="https://bazel.build/extending/rules#providers">providers</a>.</p> - -<p> -The precise semantics of what it means for a target to depend on another using +<p>The precise semantics of what it means for a target to depend on another using <code>deps</code> are specific to the kind of rule, and the rule-specific documentation goes into more detail. For rules which process source code, <code>deps</code> generally specifies code dependencies used by the code in -<a href="#typical.srcs"><code>srcs</code></a>. -</p> - -<p> -Most often, a <code>deps</code> dependency is used to allow one module to use +<a href="#typical.srcs"><code>srcs</code></a>.</p> +<p>Most often, a <code>deps</code> dependency is used to allow one module to use symbols defined in another module written in the same programming language and -separately compiled. Cross-language dependencies are also permitted in many +separately compiled. Cross-language dependencies are also permitted in many cases: For example, a <code>java_library</code> target may depend on C++ code in a <code>cc_library</code> target, by listing the latter in the -<code>deps</code> attribute. See the definition of +<code>deps</code> attribute. See the definition of <a href="/concepts/build-ref#deps">dependencies</a> -for more information. -</p> -</td> - </tr> - <tr> - <td id="typical.licenses"><code>licenses</code></td> - <td><a name="common.licenses"></a> +for more information.</p></td> +</tr> +<tr> +<td id="typical.licenses"><code>licenses</code></td> +<td><span id="common.licenses"></span> <p>List of strings; <a href="#configurable-attributes">nonconfigurable</a>; - default is <code>["none"]</code></p> - -<p> - A list of license-type strings to be used for this particular target. - +default is <code>["none"]</code></p> +<p>A list of license-type strings to be used for this particular target. This is part of a deprecated licensing API that Bazel no longer uses. Don't -use this. -</p> -</td> - </tr> - <tr> - <td id="typical.srcs"><code>srcs</code></td> - <td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - -<p> -Files processed or included by this rule. Generally lists files directly, but +use this.</p></td> +</tr> +<tr> +<td id="typical.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +<p>Files processed or included by this rule. Generally lists files directly, but may list rule targets (like <code>filegroup</code> or <code>genrule</code>) to -include their default outputs. -</p> - -<p> -Language-specific rules often require that the listed files have particular -file extensions. -</p> -</td> - </tr> - </tbody> - </table> +include their default outputs.</p> +<p>Language-specific rules often require that the listed files have particular +file extensions.</p></td> +</tr> +</tbody> +</table> -<h2 id="common-attributes">Attributes common to all build rules</h2> +## Attributes common to all build rules -<p>This section describes attributes that are implicitly added to all build +This section describes attributes that are implicitly added to all build rules. -</p> - - <table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="common.aspect_hints"><code>aspect_hints</code></td> - <td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th>Attribute</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="common.aspect_hints"><code>aspect_hints</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> <p>A list of arbitrary labels which is exposed to <a href="/extending/aspects">aspects</a> (in particular - aspects invoked by this rule's reverse dependencies), but isn't exposed to this rule's own implementation. Consult documentation for language-specific rule sets for details about what effect a particular aspect hint would have.</p> - <p>You could think of an aspect hint as a richer alternative to a <a href="#common.tags">tag</a>: while a tag conveys only a boolean state (the tag is either present or absent in the <code>tags</code> list), an aspect hint can convey arbitrary structured information in its <a href="/extending/rules#providers">providers</a>.</p> - <p>In practice, aspect hints are used for interoperability between different language-specific rule sets. For example, imagine you have a <code>mylang_binary</code> target which needs to depend on an <code>otherlang_library</code> target. The MyLang-specific logic needs some additional @@ -234,330 +167,219 @@ the MyLang rule set to define a <code>mylang_hint</code> rule which can be used additional information; the user can add the hint to their <code>otherlang_library</code>'s <code>aspect_hints</code>, and <code>mylang_binary</code> can use an aspect to collect the additional information from a MyLang-specific provider in the <code>mylang_hint</code>.</p> - <p>For a concrete example, see <a href="https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_interop_hint"><code>swift_interop_hint</code></a> and <a href="https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_overlay"><code>swift_overlay</code></a> in <code>rules_swift</code>.</p> - <p>Best practices:</p> <ul> - <li>Targets listed in <code>aspect_hints</code> should be lightweight and minimal.</li> - <li>Language-specific logic should consider only aspect hints having providers relevant to that - language, and should ignore any other aspect hints.</li> +<li>Targets listed in <code>aspect_hints</code> should be lightweight and minimal.</li> +<li>Language-specific logic should consider only aspect hints having providers relevant to that +language, and should ignore any other aspect hints.</li> </ul></td> - </tr> - <tr> - <td id="common.compatible_with"><code>compatible_with</code></td> - <td><p>List of <a href="/concepts/labels">labels</a>; - <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> - -<p> -The list of environments this target can be built for, in addition to -default-supported environments. -</p> - -<p> -This is part of Bazel's constraint system, which lets users declare which +</tr> +<tr> +<td id="common.compatible_with"><code>compatible_with</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; +<a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +<p>The list of environments this target can be built for, in addition to +default-supported environments.</p> +<p>This is part of Bazel's constraint system, which lets users declare which targets can and cannot depend on each other. For example, externally deployable binaries shouldn't depend on libraries with company-secret code. See -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46"> -ConstraintSemantics</a> for details. -</p> -</td> - </tr> - <tr> - <td id="common.deprecation"><code>deprecation</code></td> - <td><p>String; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>None</code></p> - -<p> -An explanatory warning message associated with this target. +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46">ConstraintSemantics</a> for details.</p></td> +</tr> +<tr> +<td id="common.deprecation"><code>deprecation</code></td> +<td><p>String; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>None</code></p> +<p>An explanatory warning message associated with this target. Typically this is used to notify users that a target has become obsolete, or has become superseded by another rule, is private to a package, or is perhaps considered harmful for some reason. It is a good idea to include some reference (like a webpage, a bug number or example migration CLs) so that one can easily find out what changes are required to avoid the message. If there is a new target that can be used as a drop in replacement, it is a -good idea to just migrate all users of the old target. -</p> - -<p> -This attribute has no effect on the way things are built, but it -may affect a build tool's diagnostic output. The build tool issues a +good idea to just migrate all users of the old target.</p> +<p>This attribute has no effect on the way things are built, but it +may affect a build tool's diagnostic output. The build tool issues a warning when a rule with a <code>deprecation</code> attribute is -depended upon by a target in another package. -</p> - -<p> -Intra-package dependencies are exempt from this warning, so that, +depended upon by a target in another package.</p> +<p>Intra-package dependencies are exempt from this warning, so that, for example, building the tests of a deprecated rule does not -encounter a warning. -</p> - -<p> -If a deprecated target depends on another deprecated target, no warning -message is issued. -</p> - -<p> -Once people have stopped using it, the target can be removed. -</p> -</td> - </tr> - <tr> - <td id="common.exec_compatible_with"><code>exec_compatible_with</code></td> - <td><p>List of <a href="/concepts/labels">labels</a>; - <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code> -</p> - -<p> -A list of -<code><a href="platforms-and-toolchains.html#constraint_value">constraint_values</a></code> +encounter a warning.</p> +<p>If a deprecated target depends on another deprecated target, no warning +message is issued.</p> +<p>Once people have stopped using it, the target can be removed.</p></td> +</tr> +<tr> +<td id="common.exec_compatible_with"><code>exec_compatible_with</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; +<a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +<p>A list of +<a href="platforms-and-toolchains.html#constraint_value"><code>constraint_values</code></a> that must be present in the execution platform of this target's default exec group. This is in addition to any constraints already set by the rule type. Constraints are used to restrict the list of available execution platforms. - For more details, see the description of - <a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>. - and - <a href="/extending/exec-groups">exec groups</a> - -</p> -</td> - </tr> - <tr> - <td id="common.exec_group_compatible_with"><code>exec_group_compatible_with</code></td> - <td><p>Dictionary of strings to lists of <a href="/concepts/labels">labels</a>; - <a href="#configurable-attributes">nonconfigurable</a>; default is <code>{}</code> -</p> - -<p> -A dictionary of exec group names to lists of -<code><a href="platforms-and-toolchains.html#constraint_value">constraint_values</a></code> +<a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>. +and +<a href="/extending/exec-groups">exec groups</a></p></td> +</tr> +<tr> +<td id="common.exec_group_compatible_with"><code>exec_group_compatible_with</code></td> +<td><p>Dictionary of strings to lists of <a href="/concepts/labels">labels</a>; +<a href="#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> +<p>A dictionary of exec group names to lists of +<a href="platforms-and-toolchains.html#constraint_value"><code>constraint_values</code></a> that must be present in the execution platform for the given exec group. This is in addition to any constraints already set on the exec group's definition. Constraints are used to restrict the list of available execution platforms. - For more details, see the description of - <a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>. - and - <a href="/extending/exec-groups">exec groups</a> - -</p> -</td> - </tr> - <tr> - <td id="common.exec_properties"><code>exec_properties</code></td> - <td><p>Dictionary of strings; default is <code>{}</code></p> - -<p> A dictionary of strings that will be added to the <code>exec_properties</code> of a platform selected for this target. See <code>exec_properties</code> of the <a href="platforms-and-toolchains.html#platform">platform</a> rule.</p> - +<a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>. +and +<a href="/extending/exec-groups">exec groups</a></p></td> +</tr> +<tr> +<td id="common.exec_properties"><code>exec_properties</code></td> +<td><p>Dictionary of strings; default is <code>{}</code></p> +<p>A dictionary of strings that will be added to the <code>exec_properties</code> of a platform selected for this target. See <code>exec_properties</code> of the <a href="platforms-and-toolchains.html#platform">platform</a> rule.</p> <p>If a key is present in both the platform and target-level properties, the value will be taken from the target.</p> - -<p>Keys can be prefixed with the name of an execution group followed by a <code>.</code> to apply them only to that particular exec group.</p> -</td> - </tr> - <tr> - <td id="common.features"><code>features</code></td> - <td><p>List of <i>feature</i> strings; default is <code>[]</code></p> - +<p>Keys can be prefixed with the name of an execution group followed by a <code>.</code> to apply them only to that particular exec group.</p></td> +</tr> +<tr> +<td id="common.features"><code>features</code></td> +<td><p>List of <em>feature</em> strings; default is <code>[]</code></p> <p>A feature is string tag that can be enabled or disabled on a target. The - meaning of a feature depends on the rule itself.</p> - -<p>This <code>features</code> attribute is combined with the <a href="/reference/be/functions.html#package"> -package</a> level <code>features</code> attribute. For example, if +meaning of a feature depends on the rule itself.</p> +<p>This <code>features</code> attribute is combined with the +<a href="/reference/be/functions.html#package">package</a> level <code>features</code> attribute. For example, if the features ["a", "b"] are enabled on the package level, and a target's <code>features</code> attribute contains ["-a", "c"], the features enabled for the rule will be "b" and "c". - <a href="https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD"> - See example</a>. -</p> - -</td> - </tr> - <tr> - <td id="common.package_metadata"><code>package_metadata</code></td> - <td><p>List of <a href="/concepts/labels">labels</a>; - <a href="#configurable-attributes">nonconfigurable</a>; default is the package's - <code><a href="/reference/be/functions.html#package.default_package_metadata">default_package_metadata</a></code> -</p> - -<p> -A list of labels that are associated metadata about this target. +<a href="https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD">See example</a>.</p></td> +</tr> +<tr> +<td id="common.package_metadata"><code>package_metadata</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; +<a href="#configurable-attributes">nonconfigurable</a>; default is the package's +<a href="/reference/be/functions.html#package.default_package_metadata"><code>default_package_metadata</code></a></p> +<p>A list of labels that are associated metadata about this target. Typically, the labels are simple rules that return a provider of constant values. Rules and aspects may use these labels to perform some -additional analysis on the build graph. -</p> - -<p> -The canonical use case is that of +additional analysis on the build graph.</p> +<p>The canonical use case is that of <a href="https://github.com/bazelbuild/rules_license">rules_license</a>. For that use case, <code>package_metadata</code> and <code>default_package_metadata</code> is used to attach information about a package's licence or version to targets. An aspect applied to a top-level binary can be used to gather those and produce -compliance reports. -</p> -</td> - </tr> - <tr> - <td id="common.restricted_to"><code>restricted_to</code></td> - <td><p>List of <a href="/concepts/labels">labels</a>; - <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> - -<p> -The list of environments this target can be built for, <i>instead</i> of -default-supported environments. -</p> - -<p> -This is part of Bazel's constraint system. See -<code><a href="#common.compatible_with">compatible_with</a></code> -for details. -</p> -</td> - </tr> - <tr> - <td id="common.tags"><code>tags</code></td> - <td><p> - List of strings; <a href="#configurable-attributes">nonconfigurable</a>; - default is <code>[]</code> -</p> - -<p> - <i>Tags</i> can be used on any rule. <i>Tags</i> on test and - <code>test_suite</code> rules are useful for categorizing the tests. - <i>Tags</i> on non-test targets are used to control sandboxed execution of - <code>genrule</code>s and - +compliance reports.</p></td> +</tr> +<tr> +<td id="common.restricted_to"><code>restricted_to</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; +<a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +<p>The list of environments this target can be built for, <em>instead</em> of +default-supported environments.</p> +<p>This is part of Bazel's constraint system. See +<a href="#common.compatible_with"><code>compatible_with</code></a> +for details.</p></td> +</tr> +<tr> +<td id="common.tags"><code>tags</code></td> +<td><p>List of strings; <a href="#configurable-attributes">nonconfigurable</a>; +default is <code>[]</code></p> +<p><em>Tags</em> can be used on any rule. <em>Tags</em> on test and +<code>test_suite</code> rules are useful for categorizing the tests. +<em>Tags</em> on non-test targets are used to control sandboxed execution of +<code>genrule</code>s and <a href="/rules/concepts">Starlark</a> - actions, and for parsing by humans and/or external tools. -</p> - -<p> - Bazel modifies the behavior of its sandboxing code if it finds the following - keywords in the <code>tags</code> attribute of any test or <code>genrule</code> - target, or the keys of <code>execution_requirements</code> for any Starlark - action. -</p> - +actions, and for parsing by humans and/or external tools.</p> +<p>Bazel modifies the behavior of its sandboxing code if it finds the following +keywords in the <code>tags</code> attribute of any test or <code>genrule</code> +target, or the keys of <code>execution_requirements</code> for any Starlark +action.</p> <ul> - <li><code>no-sandbox</code> keyword results in the action or test never being - sandboxed; it can still be cached or run remotely - use <code>no-cache</code> - or <code>no-remote</code> to prevent either or both of those. - </li> - <li><code>no-cache</code> keyword results in the action or test never being - cached (locally or remotely). Note: for the purposes of this tag, the disk cache - is considered a local cache, whereas the HTTP and gRPC caches are considered - remote. Other caches, such as Skyframe or the persistent action cache, are not - affected. - </li> - <li><code>no-remote-cache</code> keyword results in the action or test never being - cached remotely (but it may be cached locally; it may also be executed remotely). - Note: for the purposes of this tag, the disk cache is considered a local cache, - whereas the HTTP and gRPC caches are considered remote. Other caches, such as - Skyframe or the persistent action cache, are not affected. - If a combination of local disk cache and remote cache are used (combined cache), - it's treated as a remote cache and disabled entirely unless <code>--incompatible_remote_results_ignore_disk</code> - is set in which case the local components will be used. - </li> - <li><code>no-remote-exec</code> keyword results in the action or test never being - executed remotely (but it may be cached remotely). - </li> - - <li><code>no-remote</code> keyword prevents the action or test from being executed remotely or - cached remotely. This is equivalent to using both - <code>no-remote-cache</code> and <code>no-remote-exec</code>. - </li> - <li><code>no-remote-cache-upload</code> keyword disables upload part of remote caching of a spawn. - it does not disable remote execution. - </li> - <li><code>local</code> keyword precludes the action or test from being remotely cached, - remotely executed, or run inside the sandbox. - For genrules and tests, marking the rule with the <code>local = True</code> - attribute has the same effect. - </li> - - <li><code>requires-network</code> keyword allows access to the external - network from inside the sandbox. This tag only has an effect if sandboxing - is enabled. - </li> - - <li><code>block-network</code> keyword blocks access to the external - network from inside the sandbox. In this case, only communication - with localhost is allowed. This tag only has an effect if sandboxing is - enabled. - </li> - - <li><code>requires-fakeroot</code> runs the test or action as uid and gid 0 (i.e., the root - user). This is only supported on Linux. This tag takes precedence over the - <code class='flag'>--sandbox_fake_username</code> command-line option. - </li> +<li><code>no-sandbox</code> keyword results in the action or test never being +sandboxed; it can still be cached or run remotely - use <code>no-cache</code> +or <code>no-remote</code> to prevent either or both of those.</li> +<li><code>no-cache</code> keyword results in the action or test never being +cached (locally or remotely). Note: for the purposes of this tag, the disk cache +is considered a local cache, whereas the HTTP and gRPC caches are considered +remote. Other caches, such as Skyframe or the persistent action cache, are not +affected.</li> +<li><code>no-remote-cache</code> keyword results in the action or test never being +cached remotely (but it may be cached locally; it may also be executed remotely). +Note: for the purposes of this tag, the disk cache is considered a local cache, +whereas the HTTP and gRPC caches are considered remote. Other caches, such as +Skyframe or the persistent action cache, are not affected. +If a combination of local disk cache and remote cache are used (combined cache), +it's treated as a remote cache and disabled entirely unless <code>--incompatible_remote_results_ignore_disk</code> +is set in which case the local components will be used.</li> +<li><code>no-remote-exec</code> keyword results in the action or test never being +executed remotely (but it may be cached remotely).</li> +<li><code>no-remote</code> keyword prevents the action or test from being executed remotely or +cached remotely. This is equivalent to using both +<code>no-remote-cache</code> and <code>no-remote-exec</code>.</li> +<li><code>no-remote-cache-upload</code> keyword disables upload part of remote caching of a spawn. +it does not disable remote execution.</li> +<li><code>local</code> keyword precludes the action or test from being remotely cached, +remotely executed, or run inside the sandbox. +For genrules and tests, marking the rule with the <code>local = True</code> +attribute has the same effect.</li> +<li><code>requires-network</code> keyword allows access to the external +network from inside the sandbox. This tag only has an effect if sandboxing +is enabled.</li> +<li><code>block-network</code> keyword blocks access to the external +network from inside the sandbox. In this case, only communication +with localhost is allowed. This tag only has an effect if sandboxing is +enabled.</li> +<li><code>requires-fakeroot</code> runs the test or action as uid and gid 0 (i.e., the root +user). This is only supported on Linux. This tag takes precedence over the +<code class="flag">--sandbox_fake_username</code> command-line option.</li> </ul> - -<p> - <i>Tags</i> on tests are generally used to annotate a test's role in your - debug and release process. Typically, tags are most useful for C++ and Python - tests, which lack any runtime annotation ability. The use of tags and size - elements gives flexibility in assembling suites of tests based around codebase - check-in policy. -</p> - -<p> - Bazel modifies test running behavior if it finds the following keywords in the - <code>tags</code> attribute of the test rule: -</p> - +<p><em>Tags</em> on tests are generally used to annotate a test's role in your +debug and release process. Typically, tags are most useful for C++ and Python +tests, which lack any runtime annotation ability. The use of tags and size +elements gives flexibility in assembling suites of tests based around codebase +check-in policy.</p> +<p>Bazel modifies test running behavior if it finds the following keywords in the +<code>tags</code> attribute of the test rule:</p> <ul> - <li><code>exclusive</code> will force the test to be run in the - "exclusive" mode, ensuring that no other tests are running at the - same time. Such tests will be executed in serial fashion after all build - activity and non-exclusive tests have been completed. Remote execution is - disabled for such tests because Bazel doesn't have control over what's - running on a remote machine. - </li> - - <li><code>exclusive-if-local</code> will force the test to be run in the - "exclusive" mode if it is executed locally, but will run the test in parallel if it's - executed remotely. - </li> - - <li><code>manual</code> keyword will exclude the target from expansion of target pattern wildcards - (<code>...</code>, <code>:*</code>, <code>:all</code>, etc.) and <code>test_suite</code> rules - which do not list the test explicitly when computing the set of top-level targets to build/run - for the <code>build</code>, <code>test</code>, and <code>coverage</code> commands. It does not - affect target wildcard or test suite expansion in other contexts, including the - <code>query</code> command. Note that <code>manual</code> does not imply that a target should - not be built/run automatically by continuous build/test systems. For example, it may be - desirable to exclude a target from <code>bazel test ...</code> because it requires specific - Bazel flags, but still have it included in properly-configured presubmit or continuous test - runs. - - </li> - - <li><code>external</code> keyword will force test to be unconditionally - executed (regardless of <code class='flag'>--cache_test_results</code> - value). - </li> - - </ul> - +<li><code>exclusive</code> will force the test to be run in the +"exclusive" mode, ensuring that no other tests are running at the +same time. Such tests will be executed in serial fashion after all build +activity and non-exclusive tests have been completed. Remote execution is +disabled for such tests because Bazel doesn't have control over what's +running on a remote machine.</li> +<li><code>exclusive-if-local</code> will force the test to be run in the +"exclusive" mode if it is executed locally, but will run the test in parallel if it's +executed remotely.</li> +<li><code>manual</code> keyword will exclude the target from expansion of target pattern wildcards +(<code>...</code>, <code>:*</code>, <code>:all</code>, etc.) and <code>test_suite</code> rules +which do not list the test explicitly when computing the set of top-level targets to build/run +for the <code>build</code>, <code>test</code>, and <code>coverage</code> commands. It does not +affect target wildcard or test suite expansion in other contexts, including the +<code>query</code> command. Note that <code>manual</code> does not imply that a target should +not be built/run automatically by continuous build/test systems. For example, it may be +desirable to exclude a target from <code>bazel test ...</code> because it requires specific +Bazel flags, but still have it included in properly-configured presubmit or continuous test +runs.</li> +<li><code>external</code> keyword will force test to be unconditionally +executed (regardless of <code class="flag">--cache_test_results</code> +value).</li> +</ul> See <a href="/reference/test-encyclopedia#tag-conventions">Tag Conventions</a> - in the Test Encyclopedia for more conventions on tags attached to test targets. -</td> - </tr> - <tr> - <td id="common.target_compatible_with"><code>target_compatible_with</code></td> - <td><p> -List of <a href="/concepts/labels">labels</a>; default is <code>[]</code> -</p> - -<p> -A list of -<code><a href="platforms-and-toolchains.html#constraint_value">constraint_value</a></code>s +in the Test Encyclopedia for more conventions on tags attached to test targets.</td> +</tr> +<tr> +<td id="common.target_compatible_with"><code>target_compatible_with</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +<p>A list of +<a href="platforms-and-toolchains.html#constraint_value"><code>constraint_value</code></a>s that must be present in the target platform for this target to be considered <em>compatible</em>. This is in addition to any constraints already set by the rule type. If the target platform does not satisfy all listed constraints then @@ -565,472 +387,333 @@ the target is considered <em>incompatible</em>. Incompatible targets are skipped for building and testing when the target pattern is expanded (e.g. <code>//...</code>, <code>:all</code>). When explicitly specified on the command line, incompatible targets cause Bazel to print an error and cause a -build or test failure. -</p> - -<p> -Targets that transitively depend on incompatible targets are themselves -considered incompatible. They are also skipped for building and testing. -</p> - -<p> -An empty list (which is the default) signifies that the target is compatible -with all platforms. -<p> - -<p> -All rules other than <a href="workspace.html">Workspace Rules</a> support this +build or test failure.</p> +<p>Targets that transitively depend on incompatible targets are themselves +considered incompatible. They are also skipped for building and testing.</p> +<p>An empty list (which is the default) signifies that the target is compatible +with all platforms.</p> +<p>All rules other than <a href="workspace.html">Workspace Rules</a> support this attribute. For some rules this attribute has no effect. For example, specifying <code>target_compatible_with</code> for a -<code><a href="c-cpp.html#cc_toolchain">cc_toolchain</a></code> is not useful. -<p> - -<p> -See the +<a href="c-cpp.html#cc_toolchain"><code>cc_toolchain</code></a> is not useful.</p> +<p>See the <a href="/docs/platforms#skipping-incompatible-targets">Platforms</a> -page for more information about incompatible target skipping. -</p> -</td> - </tr> - <tr> - <td id="common.testonly"><code>testonly</code></td> - <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>False</code> - except for test and test suite targets</p> - -<p> -If <code>True</code>, only testonly targets (such as tests) can depend on this target. -</p> - -<p> -Equivalently, a rule that is not <code>testonly</code> is not allowed to -depend on any rule that is <code>testonly</code>. -</p> - -<p> -Tests (<code>*_test</code> rules) +page for more information about incompatible target skipping.</p></td> +</tr> +<tr> +<td id="common.testonly"><code>testonly</code></td> +<td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>False</code> +except for test and test suite targets</p> +<p>If <code>True</code>, only testonly targets (such as tests) can depend on this target.</p> +<p>Equivalently, a rule that is not <code>testonly</code> is not allowed to +depend on any rule that is <code>testonly</code>.</p> +<p>Tests (<code>*_test</code> rules) and test suites (<a href="/reference/be/general.html#test_suite">test_suite</a> rules) -are <code>testonly</code> by default. -</p> - -<p> -This attribute is intended to mean that the target should not be -contained in binaries that are released to production. -</p> - -<p> -Because testonly is enforced at build time, not run time, and propagates +are <code>testonly</code> by default.</p> +<p>This attribute is intended to mean that the target should not be +contained in binaries that are released to production.</p> +<p>Because testonly is enforced at build time, not run time, and propagates virally through the dependency tree, it should be applied judiciously. For example, stubs and fakes that are useful for unit tests may also be useful for integration tests involving the same binaries that will be released to production, and therefore should probably not be marked testonly. Conversely, rules that are dangerous to even link in, perhaps because they unconditionally -override normal behavior, should definitely be marked testonly. -</p> -</td> - </tr> - <tr> - <td id="common.toolchains"><code>toolchains</code></td> - <td><p>List of <a href="/concepts/labels">labels</a>; - <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> - -<p> - The set of targets whose <a href="/reference/be/make-variables">Make variables</a> this target is - allowed to access. These targets are either instances of rules that provide - <code>TemplateVariableInfo</code> or special targets for toolchain types built into Bazel. These - include: - +override normal behavior, should definitely be marked testonly.</p></td> +</tr> +<tr> +<td id="common.toolchains"><code>toolchains</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; +<a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +<p>The set of targets whose <a href="/reference/be/make-variables">Make variables</a> this target is +allowed to access. These targets are either instances of rules that provide +<code>TemplateVariableInfo</code> or special targets for toolchain types built into Bazel. These +include:</p> <ul> - <li><code>@bazel_tools//tools/cpp:toolchain_type</code> - <li><code>@rules_java//toolchains:current_java_runtime</code> - </ul> - -<p> - Note that this is distinct from the concept of - <a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a> - that is used by rule implementations for platform-dependent configuration. You cannot use this - attribute to determine which specific <code>cc_toolchain</code> or <code>java_toolchain</code> a - target will use. -</p> -</td> - </tr> - <tr> - <td id="common.visibility"><code>visibility</code></td> - <td><p>List of <a href="/concepts/labels">labels</a>; - <a href="#configurable-attributes">nonconfigurable</a>; - default varies -</p> - -<p> - The <code>visibility</code> attribute controls whether the target can be - depended on by targets in other locations. See the documentation for - <a href="/concepts/visibility">visibility</a>. -</p> - -<p> - For targets declared directly in a BUILD file or in legacy macros called from - a BUILD file, the default value is the package's - <code><a href="/reference/be/functions.html#package.default_visibility">default_visibility</a></code> - if specified, or else <code>["//visibility:private"]</code>. For targets - declared in one or more symbolic macros, the default value is always just - <code>["//visibility:private"]</code> (which makes it useable only within the - package containing the macro's code). -</p> -</td> - </tr> - </tbody> - </table> - -<h2 id="common-attributes-tests">Attributes common to all test rules (*_test)</h2> - -<p>This section describes attributes that are common to all test rules.</p> +<li><code>@bazel_tools//tools/cpp:toolchain_type</code></li> +<li><code>@rules_java//toolchains:current_java_runtime</code></li> +</ul> +<p>Note that this is distinct from the concept of +<a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a> +that is used by rule implementations for platform-dependent configuration. You cannot use this +attribute to determine which specific <code>cc_toolchain</code> or <code>java_toolchain</code> a +target will use.</p></td> +</tr> +<tr> +<td id="common.visibility"><code>visibility</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; +<a href="#configurable-attributes">nonconfigurable</a>; +default varies</p> +<p>The <code>visibility</code> attribute controls whether the target can be +depended on by targets in other locations. See the documentation for +<a href="/concepts/visibility">visibility</a>.</p> +<p>For targets declared directly in a BUILD file or in legacy macros called from +a BUILD file, the default value is the package's +<a href="/reference/be/functions.html#package.default_visibility"><code>default_visibility</code></a> +if specified, or else <code>["//visibility:private"]</code>. For targets +declared in one or more symbolic macros, the default value is always just +<code>["//visibility:private"]</code> (which makes it useable only within the +package containing the macro's code).</p></td> +</tr> +</tbody> +</table> - <table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="test.args"><code>args</code></td> - <td><p>List of strings; subject to +## Attributes common to all test rules (\*\_test) + +This section describes attributes that are common to all test rules. + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th>Attribute</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="test.args"><code>args</code></td> +<td><p>List of strings; subject to <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and <a href="/reference/be/make-variables">"Make variable"</a> substitution, and <a href="#sh-tokenization">Bourne shell tokenization</a>; default is <code>[]</code></p> - <p>Command line arguments that Bazel passes to the target when it is -executed with <code>bazel test</code>. - -<p> -These arguments are passed before any <code>--test_arg</code> values -specified on the <code>bazel test</code> command line. -</p> -</td> - </tr> - <tr> - <td id="test.env"><code>env</code></td> - <td><p> - Dictionary of strings; values are subject to - <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and - <a href="/reference/be/make-variables">"Make variable"</a> substitution; default is <code>{}</code> -</p> - -<p> - Specifies additional environment variables to set when the test is executed by - <code>bazel test</code>. -</p> - -<p> - This attribute only applies to native rules, like <code>cc_test</code>, - <code>py_test</code>, and <code>sh_test</code>. It does not apply to - Starlark-defined test rules. For your own Starlark rules, you can add an "env" - attribute and use it to populate a - - <a href="/rules/lib/providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> - Provider. -</p> - <a href="/rules/lib/toplevel/testing#TestEnvironment">TestEnvironment</a> - - Provider. -</p> -</td> - </tr> - <tr> - <td id="test.env_inherit"><code>env_inherit</code></td> - <td><p>List of strings; default is <code>[]</code></p> - +executed with <code>bazel test</code>.</p> +<p>These arguments are passed before any <code>--test_arg</code> values +specified on the <code>bazel test</code> command line.</p></td> +</tr> +<tr> +<td id="test.env"><code>env</code></td> +<td><p>Dictionary of strings; values are subject to +<a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and +<a href="/reference/be/make-variables">"Make variable"</a> substitution; default is <code>{}</code></p> +<p>Specifies additional environment variables to set when the test is executed by +<code>bazel test</code>.</p> +<p>This attribute only applies to native rules, like <code>cc_test</code>, +<code>py_test</code>, and <code>sh_test</code>. It does not apply to +Starlark-defined test rules. For your own Starlark rules, you can add an "env" +attribute and use it to populate a +<a href="/rules/lib/providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> +Provider.</p> +<a href="/rules/lib/toplevel/testing#TestEnvironment">TestEnvironment</a> +Provider.</td> +</tr> +<tr> +<td id="test.env_inherit"><code>env_inherit</code></td> +<td><p>List of strings; default is <code>[]</code></p> <p>Specifies additional environment variables to inherit from the - external environment when the test is executed by <code>bazel test</code>. -</p> - -<p> - This attribute only applies to native rules, like <code>cc_test</code>, <code>py_test</code>, - and <code>sh_test</code>. It does not apply to Starlark-defined test rules. -</p> -</td> - </tr> - <tr> - <td id="test.size"><code>size</code></td> - <td><p>String <code>"enormous"</code>, <code>"large"</code>, <code>"medium"</code>, or - <code>"small"</code>; <a href="#configurable-attributes">nonconfigurable</a>; - default is <code>"medium"</code></p> - +external environment when the test is executed by <code>bazel test</code>.</p> +<p>This attribute only applies to native rules, like <code>cc_test</code>, <code>py_test</code>, +and <code>sh_test</code>. It does not apply to Starlark-defined test rules.</p></td> +</tr> +<tr> +<td id="test.size"><code>size</code></td> +<td><p>String <code>"enormous"</code>, <code>"large"</code>, <code>"medium"</code>, or +<code>"small"</code>; <a href="#configurable-attributes">nonconfigurable</a>; +default is <code>"medium"</code></p> <p>Specifies a test target's "heaviness": how much time/resources it needs to run.</p> - <p>Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or "enormous". Bazel uses the size to determine a default timeout, which can be overridden using the <code>timeout</code> attribute. The timeout is for all tests in the BUILD target, not for each individual test. When the test is run locally, the <code>size</code> is additionally used for scheduling purposes: Bazel tries to respect <code>--local_{ram,cpu}_resources</code> and not overwhelm the local machine by running lots of heavy tests at the same time.</p> - <p>Test sizes correspond to the following default timeouts and assumed peak local resource usages:</p> - <table style="width: 100%"> - <tr> - <th>Size</th> - <th>RAM (in MB)</th> - <th>CPU (in CPU cores)</th> - <th>Default timeout</th> - </tr> - <tr> - <td>small</td> - <td>20</td> - <td>1</td> - <td>short (1 minute)</td> - </tr> - <tr> - <td>medium</td> - <td>100</td> - <td>1</td> - <td>moderate (5 minutes)</td> - </tr> - <tr> - <td>large</td> - <td>300</td> - <td>1</td> - <td>long (15 minutes)</td> - </tr> - <tr> - <td>enormous</td> - <td>800</td> - <td>1</td> - <td>eternal (60 minutes)</td> - </tr> +<thead> +<tr> +<th>Size</th> +<th>RAM (in MB)</th> +<th>CPU (in CPU cores)</th> +<th>Default timeout</th> +</tr> +</thead> +<tbody> +<tr> +<td>small</td> +<td>20</td> +<td>1</td> +<td>short (1 minute)</td> +</tr> +<tr> +<td>medium</td> +<td>100</td> +<td>1</td> +<td>moderate (5 minutes)</td> +</tr> +<tr> +<td>large</td> +<td>300</td> +<td>1</td> +<td>long (15 minutes)</td> +</tr> +<tr> +<td>enormous</td> +<td>800</td> +<td>1</td> +<td>eternal (60 minutes)</td> +</tr> +</tbody> </table> - -<p> - The environment variable - <code><a href="/reference/test-encyclopedia#initial-conditions">TEST_SIZE</a></code> will be set to - the value of this attribute when spawning the test. -</p> - -</td> - </tr> - <tr> - <td id="test.timeout"><code>timeout</code></td> - <td><p>String <code>"short"</code>, <code>"moderate"</code>, <code>"long"</code>, or - <code>"eternal"</code>; <a href="#configurable-attributes">nonconfigurable</a>; default is derived - from the test's <code>size</code> attribute</code></p> - -<p> -How long the test is expected to run before returning. -</p> - -<p> -While a test's size attribute controls resource estimation, a test's -timeout may be set independently. If not explicitly specified, the +<p>The environment variable +<a href="/reference/test-encyclopedia#initial-conditions"><code>TEST_SIZE</code></a> will be set to +the value of this attribute when spawning the test.</p></td> +</tr> +<tr> +<td id="test.timeout"><code>timeout</code></td> +<td><p>String <code>"short"</code>, <code>"moderate"</code>, <code>"long"</code>, or +<code>"eternal"</code>; <a href="#configurable-attributes">nonconfigurable</a>; default is derived +from the test's <code>size</code> attribute</p> +<p>How long the test is expected to run before returning.</p> +<p>While a test's size attribute controls resource estimation, a test's +timeout may be set independently. If not explicitly specified, the timeout is based on the <a href="#test.size">test's size</a>. The test timeout can be overridden with the <code>--test_timeout</code> flag, e.g. for running under certain conditions which are known to be slow. Test timeout values -correspond to the following time periods: -</p> - +correspond to the following time periods:</p> <table style="width: 100%"> - <tr> - <th>Timeout Value</th> - <th>Time Period</th> - </tr> - <tr> - <td>short</td> - <td>1 minute</td> - </tr> - <tr> - <td>moderate</td> - <td>5 minutes</td> - </tr> - <tr> - <td>long</td> - <td>15 minutes</td> - </tr> - <tr> - <td>eternal</td> - <td>60 minutes</td> - </tr> +<thead> +<tr> +<th>Timeout Value</th> +<th>Time Period</th> +</tr> +</thead> +<tbody> +<tr> +<td>short</td> +<td>1 minute</td> +</tr> +<tr> +<td>moderate</td> +<td>5 minutes</td> +</tr> +<tr> +<td>long</td> +<td>15 minutes</td> +</tr> +<tr> +<td>eternal</td> +<td>60 minutes</td> +</tr> +</tbody> </table> - -<p> -For times other than the above, the test timeout can be overridden with the +<p>For times other than the above, the test timeout can be overridden with the <code>--test_timeout</code> bazel flag, e.g. for manually running under conditions which are known to be slow. The <code>--test_timeout</code> values are in seconds. For example <code>--test_timeout=120</code> will set the test -timeout to two minutes. -</p> - -<p> - The environment variable - <code><a href="/reference/test-encyclopedia#initial-conditions">TEST_TIMEOUT</a></code> will be set - to the test timeout (in seconds) when spawning the test. -</p> - -</td> - </tr> - <tr> - <td id="test.flaky"><code>flaky</code></td> - <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; - default is <code>False</code></p> - -<p> -Marks test as flaky. -</p> - -<p> -If set, executes the test up to three times, marking it as failed only if it +timeout to two minutes.</p> +<p>The environment variable +<a href="/reference/test-encyclopedia#initial-conditions"><code>TEST_TIMEOUT</code></a> will be set +to the test timeout (in seconds) when spawning the test.</p></td> +</tr> +<tr> +<td id="test.flaky"><code>flaky</code></td> +<td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; +default is <code>False</code></p> +<p>Marks test as flaky.</p> +<p>If set, executes the test up to three times, marking it as failed only if it fails each time. By default, this attribute is set to False and the test is executed only once. Note, that use of this attribute is generally discouraged - -tests should pass reliably when their assertions are upheld. -</p> -</td> - </tr> - <tr> - <td id="test.shard_count"><code>shard_count</code></td> - <td><p>Non-negative integer less than or equal to 50; default is <code>-1</code></p> - +tests should pass reliably when their assertions are upheld.</p></td> +</tr> +<tr> +<td id="test.shard_count"><code>shard_count</code></td> +<td><p>Non-negative integer less than or equal to 50; default is <code>-1</code></p> <p>Specifies the number of parallel shards to use to run the test.</p> - <p>If set, this value will override any heuristics used to determine the number of parallel shards with which to run the test. Note that for some test rules, this parameter may be required to enable sharding in the first place. Also see <code>--test_sharding_strategy</code>.</p> - -<p>If test sharding is enabled, the environment variable <code> -<a href="/reference/test-encyclopedia#initial-conditions">TEST_TOTAL_SHARDS</a> -</code> will be set to this value when spawning the test.</p> - +<p>If test sharding is enabled, the environment variable <code> </code><a href="/reference/test-encyclopedia#initial-conditions"><code>TEST_TOTAL_SHARDS</code></a><code> </code> will be set to this value when spawning the test.</p> <p>Sharding requires the test runner to support the test sharding protocol. If it does not, then it will most likely run every test in every shard, which is not what you want.</p> - <p>See <a href="/reference/test-encyclopedia#test-sharding">Test Sharding</a> -in the Test Encyclopedia for details on sharding.</p> -</td> - </tr> - <tr> - <td id="test.local"><code>local</code></td> - <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; - default is <code>False</code></p> - +in the Test Encyclopedia for details on sharding.</p></td> +</tr> +<tr> +<td id="test.local"><code>local</code></td> +<td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; +default is <code>False</code></p> <p>Forces the test to be run locally, without sandboxing.</p> - <p>Setting this to True is equivalent to providing "local" as a tag -(<code>tags=["local"]</code>).</p> -</td> - </tr> - </tbody> - </table> - -<h2 id="common-attributes-binaries">Attributes common to all binary rules (*_binary)</h2> - -<p>This section describes attributes that are common to all binary rules.</p> - - <table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="binary.args"><code>args</code></td> - <td><p> - List of strings; subject to - <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and - <a href="/reference/be/make-variables">"Make variable"</a> substitution, and - <a href="#sh-tokenization">Bourne shell tokenization</a>; - <a href="#configurable-attributes">nonconfigurable</a>; - default is <code>[]</code> -</p> +(<code>tags=["local"]</code>).</p></td> +</tr> +</tbody> +</table> -<p> -Command line arguments that Bazel will pass to the target when it is executed +## Attributes common to all binary rules (\*\_binary) + +This section describes attributes that are common to all binary rules. + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th>Attribute</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="binary.args"><code>args</code></td> +<td><p>List of strings; subject to +<a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and +<a href="/reference/be/make-variables">"Make variable"</a> substitution, and +<a href="#sh-tokenization">Bourne shell tokenization</a>; +<a href="#configurable-attributes">nonconfigurable</a>; +default is <code>[]</code></p> +<p>Command line arguments that Bazel will pass to the target when it is executed either by the <code>run</code> command or as a test. These arguments are passed before the ones that are specified on the <code>bazel run</code> or -<code>bazel test</code> command line. -</p> - -<p> -<em class="harmful">NOTE: The arguments are not passed when you run the target +<code>bazel test</code> command line.</p> +<p><em>NOTE: The arguments are not passed when you run the target outside of Bazel (for example, by manually executing the binary in -<code>bazel-bin/</code>).</em> -</p> -</td> - </tr> - <tr> - <td id="binary.env"><code>env</code></td> - <td><p>Dictionary of strings; values are subject to +<code>bazel-bin/</code>).</em></p></td> +</tr> +<tr> +<td id="binary.env"><code>env</code></td> +<td><p>Dictionary of strings; values are subject to <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and <a href="/reference/be/make-variables">"Make variable"</a> substitution; default is <code>{}</code></p> - <p>Specifies additional environment variables to set when the target is - executed by <code>bazel run</code>. -</p> - -<p> - This attribute only applies to native rules, like <code>cc_binary</code>, <code>py_binary</code>, - and <code>sh_binary</code>. It does not apply to Starlark-defined executable rules. For your own - Starlark rules, you can add an "env" attribute and use it to populate a - - <a href="/rules/lib/providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> - - Provider. -</p> - -<p> -<em class="harmful">NOTE: The environment variables are not set when you run the target +executed by <code>bazel run</code>.</p> +<p>This attribute only applies to native rules, like <code>cc_binary</code>, <code>py_binary</code>, +and <code>sh_binary</code>. It does not apply to Starlark-defined executable rules. For your own +Starlark rules, you can add an "env" attribute and use it to populate a +<a href="/rules/lib/providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> +Provider.</p> +<p><em>NOTE: The environment variables are not set when you run the target outside of Bazel (for example, by manually executing the binary in -<code>bazel-bin/</code>).</em> -</p> -</td> - </tr> - <tr> - <td id="binary.output_licenses"><code>output_licenses</code></td> - <td><p>List of strings; default is <code>[]</code></p> - -<p> -The licenses of the output files that this binary generates. - +<code>bazel-bin/</code>).</em></p></td> +</tr> +<tr> +<td id="binary.output_licenses"><code>output_licenses</code></td> +<td><p>List of strings; default is <code>[]</code></p> +<p>The licenses of the output files that this binary generates. This is part of a deprecated licensing API that Bazel no longer uses. Don't -use this. -</p> +use this.</p></td> +</tr> +</tbody> +</table> -</td> - </tr> - </tbody> - </table> +## Configurable attributes -<h2 id="configurable-attributes">Configurable attributes</h2> +Most attributes are "configurable", meaning that their values may change when +the target is built in different ways. Specifically, configurable attributes +may vary based on the flags passed to the Bazel command line, or what +downstream dependency is requesting the target. This can be used, for +instance, to customize the target for multiple platforms or compilation modes. -<p> - Most attributes are "configurable", meaning that their values may change when - the target is built in different ways. Specifically, configurable attributes - may vary based on the flags passed to the Bazel command line, or what - downstream dependency is requesting the target. This can be used, for - instance, to customize the target for multiple platforms or compilation modes. -</p> +The following example declares different sources for different target +architectures. Running `bazel build :multiplatform_lib --cpu x86` +will build the target using `x86_impl.cc`, while substituting +`--cpu arm` will instead cause it to use `arm_impl.cc`. -<p> - The following example declares different sources for different target - architectures. Running <code>bazel build :multiplatform_lib --cpu x86</code> - will build the target using <code>x86_impl.cc</code>, while substituting - <code>--cpu arm</code> will instead cause it to use <code>arm_impl.cc</code>. -</p> +``` code -<pre class="code"> cc_library( name = "multiplatform_lib", srcs = select({ @@ -1046,98 +729,73 @@ config_setting( name = "arm_mode", values = { "cpu": "arm" } ) -</pre> - -<p> - The <a href="/reference/be/functions.html#select"><code>select()</code></a> function - chooses among different alternative values for a configurable attribute based - on which <a href="/reference/be/general.html#config_setting"><code>config_setting</code></a> - or <a href="/reference/be/platforms-and-toolchains.html#constraint_value"><code>constraint_value</code></a> - criteria the target's configuration satisfies. -</p> - -<p> - Bazel evaluates configurable attributes after processing macros and before - processing rules (technically, between the - <a href="https://bazel.build/rules/concepts#evaluation-model"> - loading and analysis phases</a>). - Any processing before <code>select()</code> evaluation doesn't know which - branch the <code>select()</code> chooses. Macros, for example, can't change - their behavior based on the chosen branch, and <code>bazel query</code> can - only make conservative guesses about a target's configurable dependencies. See - <a href="https://bazel.build/docs/configurable-attributes#faq"> - this FAQ</a> - for more on using <code>select()</code> with rules and macros. -</p> - -<p> - Attributes marked <code>nonconfigurable</code> in their documentation cannot - use this feature. Usually an attribute is nonconfigurable because Bazel - internally needs to know its value before it can determine how to resolve a - <code>select()</code>. -</p> - -<p> - See <a href="https://bazel.build/docs/configurable-attributes"> - Configurable Build Attributes</a> for a detailed overview. -</p> +``` + +The [`select()`](/reference/be/functions.html#select) function +chooses among different alternative values for a configurable attribute based +on which [`config_setting`](/reference/be/general.html#config_setting) +or [`constraint_value`](/reference/be/platforms-and-toolchains.html#constraint_value) +criteria the target's configuration satisfies. + +Bazel evaluates configurable attributes after processing macros and before +processing rules (technically, between the +[loading and analysis phases](https://bazel.build/rules/concepts#evaluation-model)). +Any processing before `select()` evaluation doesn't know which +branch the `select()` chooses. Macros, for example, can't change +their behavior based on the chosen branch, and `bazel query` can +only make conservative guesses about a target's configurable dependencies. See +[this FAQ](https://bazel.build/docs/configurable-attributes#faq) +for more on using `select()` with rules and macros. + +Attributes marked `nonconfigurable` in their documentation cannot +use this feature. Usually an attribute is nonconfigurable because Bazel +internally needs to know its value before it can determine how to resolve a +`select()`. -<h2 id="implicit-outputs">Implicit output targets</h2> - -<p> - <i>Implicit outputs in C++ are deprecated. Please refrain from using it - in other languages where possible. We don't have a deprecation path yet - but they will eventually be deprecated too.</i> -</p> - -<p>When you define a build rule in a BUILD file, you are explicitly - declaring a new, named rule target in a package. Many build rule - functions also <i>implicitly</i> entail one or more output file - targets, whose contents and meaning are rule-specific. - - For example, when you explicitly declare a - <code>java_binary(name='foo', ...)</code> rule, you are also - <i>implicitly</i> declaring an output file - target <code>foo_deploy.jar</code> as a member of the same package. - (This particular target is a self-contained Java archive suitable - for deployment.) -</p> - -<p> - Implicit output targets are first-class members of the global - target graph. Just like other targets, they are built on demand, - either when specified in the top-level built command, or when they - are necessary prerequisites for other build targets. They can be - referenced as dependencies in BUILD files, and can be observed in - the output of analysis tools such as <code>bazel query</code>. -</p> - -<p> - For each kind of build rule, the rule's documentation contains a - special section detailing the names and contents of any implicit - outputs entailed by a declaration of that kind of rule. -</p> - -<p> - An important but somewhat subtle distinction between the - two namespaces used by the build system: - <a href="/concepts/labels">labels</a> identify <em>targets</em>, - which may be rules or files, and file targets may be divided into - either source (or input) file targets and derived (or output) file - targets. These are the things you can mention in BUILD files, - build from the command-line, or examine using <code>bazel query</code>; - this is the <em>target namespace</em>. Each file target corresponds - to one actual file on disk (the "file system namespace"); each rule - target may correspond to zero, one or more actual files on disk. - There may be files on disk that have no corresponding target; for - example, <code>.o</code> object files produced during C++ compilation - cannot be referenced from within BUILD files or from the command line. - In this way, the build tool may hide certain implementation details of - how it does its job. This is explained more fully in - the <a href="/concepts/build-ref">BUILD Concept Reference</a>. -</p> - -<!-- Generated footer --> - -</body> -</html> +See +[Configurable Build Attributes](https://bazel.build/docs/configurable-attributes) for a detailed overview. + +## Implicit output targets + +*Implicit outputs in C++ are deprecated. Please refrain from using it +in other languages where possible. We don't have a deprecation path yet +but they will eventually be deprecated too.* + +When you define a build rule in a BUILD file, you are explicitly +declaring a new, named rule target in a package. Many build rule +functions also *implicitly* entail one or more output file +targets, whose contents and meaning are rule-specific. +For example, when you explicitly declare a +`java_binary(name='foo', ...)` rule, you are also +*implicitly* declaring an output file +target `foo_deploy.jar` as a member of the same package. +(This particular target is a self-contained Java archive suitable +for deployment.) + +Implicit output targets are first-class members of the global +target graph. Just like other targets, they are built on demand, +either when specified in the top-level built command, or when they +are necessary prerequisites for other build targets. They can be +referenced as dependencies in BUILD files, and can be observed in +the output of analysis tools such as `bazel query`. + +For each kind of build rule, the rule's documentation contains a +special section detailing the names and contents of any implicit +outputs entailed by a declaration of that kind of rule. + +An important but somewhat subtle distinction between the +two namespaces used by the build system: +[labels](/concepts/labels) identify *targets*, +which may be rules or files, and file targets may be divided into +either source (or input) file targets and derived (or output) file +targets. These are the things you can mention in BUILD files, +build from the command-line, or examine using `bazel query`; +this is the *target namespace*. Each file target corresponds +to one actual file on disk (the "file system namespace"); each rule +target may correspond to zero, one or more actual files on disk. +There may be files on disk that have no corresponding target; for +example, `.o` object files produced during C++ compilation +cannot be referenced from within BUILD files or from the command line. +In this way, the build tool may hide certain implementation details of +how it does its job. This is explained more fully in +the [BUILD Concept Reference](/concepts/build-ref). diff --git a/reference/be/extra-actions.mdx b/reference/be/extra-actions.mdx index 099a7eb..e432ad5 100644 --- a/reference/be/extra-actions.mdx +++ b/reference/be/extra-actions.mdx @@ -2,323 +2,196 @@ title: 'extra-actions' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">Extra Actions Rules</h1> +# Extra Actions Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} - - - - -<h2>Rules</h2> +{% include "\_buttons.html" %} + +## Rules + +- [action_listener](#action_listener) +- [extra_action](#extra_action) + +## action_listener + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +action_listener(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, extra_actions, features, licenses, mnemonics, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) +``` + +**WARNING:** Extra actions are deprecated. Use +[aspects](https://bazel.build/rules/aspects) +instead. + +An `action_listener` rule doesn't produce any output itself. +Instead, it allows tool developers to insert +[`extra_action`](/reference/be/extra-actions.html#extra_action)s into the build system, +by providing a mapping from action to [`extra_action`](/reference/be/extra-actions.html#extra_action) +. + +This rule's arguments map action mnemonics to +[`extra_action`](/reference/be/extra-actions.html#extra_action) rules. + +By specifying the option +[`--experimental_action_listener=<label>`](/docs/user-manual#flag--experimental_action_listener), +the build will use the specified `action_listener` to insert +[`extra_action`](/reference/be/extra-actions.html#extra_action)s into the build graph. + +#### Example + + + action_listener( + name = "index_all_languages", + mnemonics = [ + "Javac", + "CppCompile", + "Python", + ], + extra_actions = [":indexer"], + ) + + action_listener( + name = "index_java", + mnemonics = ["Javac"], + extra_actions = [":indexer"], + ) + + extra_action( + name = "indexer", + tools = ["//my/tools:indexer"], + cmd = "$(location //my/tools:indexer)" + + "--extra_action_file=$(EXTRA_ACTION_FILE)", + ) + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="action_listener.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="action_listener.extra_actions"><code>extra_actions</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; required</p> +A list of <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a> targets +this <code>action_listener</code> should add to the build graph. +E.g. <code>[ "//my/tools:analyzer" ]</code>.</td> +</tr> +<tr> +<td id="action_listener.mnemonics"><code>mnemonics</code></td> +<td><p>List of strings; required</p> +A list of action mnemonics this <code>action_listener</code> should listen +for, e.g. <code>[ "Javac" ]</code>. +<p>Mnemonics are not a public interface. +There's no guarantee that the mnemonics and their actions don't change.</p></td> +</tr> +</tbody> +</table> + +## extra_action + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ExtraActionRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +extra_action(name, data, aspect_hints, cmd, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, out_templates, package_metadata, requires_action_output, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility) +``` + +**WARNING:** Extra actions are deprecated. Use +[aspects](https://bazel.build/rules/aspects) +instead. + +An `extra_action` rule doesn't produce any meaningful output +when specified as a regular build target. Instead, it allows tool developers +to insert additional actions into the build graph that shadow existing actions. + +See [`action_listener`](/reference/be/extra-actions.html#action_listener) for details +on how to enable `extra_action`s. + +The `extra_action`s run as a command-line. The command-line tool gets +access to a file containing a protocol buffer as \$(EXTRA_ACTION_FILE) +with detailed information on the original action it is shadowing. +It also has access to all the input files the original action has access to. +See `extra_actions_base.proto` +for details on the data stored inside the protocol buffer. Each proto file +contains an ExtraActionInfo message. + +Just like all other actions, extra actions are sandboxed, and should be designed to handle that. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="extra_action.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p> +You may refer to this rule by <code>label</code> in the <code>extra_actions</code> argument +of <a href="/reference/be/extra-actions.html#action_listener"><code> action_listener</code></a> rules.</td> +</tr> +<tr> +<td id="extra_action.cmd"><code>cmd</code></td> +<td><p>String; required</p> +The command to run. +<p>Like <a href="/reference/be/general.html#genrule.cmd">genrule cmd attribute</a> with the following +differences:</p> +<ol> +<li><p>No heuristic label expansion. Only labels using $(location ...) are expanded.</p></li> +<li><p>An additional pass is applied to the string to replace all +occurrences of the outputs created from the <code>out_templates</code> +attribute. All occurrences of <code>$(output </code><em><code>out_template</code></em><code>)</code> +are replaced with the path to the file denoted by <code>label</code>.</p> +<p>E.g. out_template <code>$(ACTION_ID).analysis</code> +can be matched with <code>$(output $(ACTION_ID).analysis)</code>.</p> +<p>In effect, this is the same substitution as <code>$(location)</code> +but with a different scope.</p></li> +</ol></td> +</tr> +<tr> +<td id="extra_action.out_templates"><code>out_templates</code></td> +<td><p>List of strings; default is <code>[]</code></p> +A list of templates for files generated by the <code>extra_action</code> command. +<p>The template can use the following variables:</p> <ul> - <li> - <a href="#action_listener"> - action_listener </a> - </li> - <li> - <a href="#extra_action"> - extra_action </a> - </li> -</ul> - - <h2 id="action_listener"> - action_listener - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">action_listener(<a href="#action_listener.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#action_listener.extra_actions">extra_actions</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#action_listener.mnemonics">mnemonics</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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> - <b>WARNING:</b> Extra actions are deprecated. Use - <a href="https://bazel.build/rules/aspects">aspects</a> - instead. -</p> - -<p> - An <code>action_listener</code> rule doesn't produce any output itself. - Instead, it allows tool developers to insert - <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a>s into the build system, - by providing a mapping from action to <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code> - </a>. -</p> - -<p> - This rule's arguments map action mnemonics to - <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a> rules. -</p> - -<p> - By specifying the option <a href="/docs/user-manual#flag--experimental_action_listener"> - <code>--experimental_action_listener=<label></code></a>, - the build will use the specified <code>action_listener</code> to insert - <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a>s into the build graph. -</p> - -<h4 id="action_listener_example">Example</h4> -<pre> -action_listener( - name = "index_all_languages", - mnemonics = [ - "Javac", - "CppCompile", - "Python", - ], - extra_actions = [":indexer"], -) - -action_listener( - name = "index_java", - mnemonics = ["Javac"], - extra_actions = [":indexer"], -) - -extra_action( - name = "indexer", - tools = ["//my/tools:indexer"], - cmd = "$(location //my/tools:indexer)" + - "--extra_action_file=$(EXTRA_ACTION_FILE)", -) -</pre> - - - - <h3 id="action_listener_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="action_listener.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="action_listener.extra_actions"> - <code>extra_actions</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; required</p> - A list of <code><a href="/reference/be/extra-actions.html#extra_action">extra_action</a></code> targets - this <code>action_listener</code> should add to the build graph. - E.g. <code>[ "//my/tools:analyzer" ]</code>. - - </td> - </tr> - <tr> - <td id="action_listener.mnemonics"> - <code>mnemonics</code> - </td> - <td> - <p>List of strings; required</p> - A list of action mnemonics this <code>action_listener</code> should listen - for, e.g. <code>[ "Javac" ]</code>. - <p> - Mnemonics are not a public interface. - There's no guarantee that the mnemonics and their actions don't change. - </p> - - </td> - </tr> - </tbody> - </table> - <h2 id="extra_action"> - extra_action - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ExtraActionRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">extra_action(<a href="#extra_action.name">name</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#extra_action.cmd">cmd</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#extra_action.out_templates">out_templates</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#extra_action.requires_action_output">requires_action_output</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.toolchains">toolchains</a>, <a href="#extra_action.tools">tools</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - -<p> - <b>WARNING:</b> Extra actions are deprecated. Use - <a href="https://bazel.build/rules/aspects">aspects</a> - instead. -</p> - -<p> - An <code>extra_action</code> rule doesn't produce any meaningful output - when specified as a regular build target. Instead, it allows tool developers - to insert additional actions into the build graph that shadow existing actions. -</p> - -<p> - See <a href="/reference/be/extra-actions.html#action_listener"><code>action_listener</code></a> for details - on how to enable <code>extra_action</code>s. -</p> - -<p> - The <code>extra_action</code>s run as a command-line. The command-line tool gets - access to a file containing a protocol buffer as $(EXTRA_ACTION_FILE) - with detailed information on the original action it is shadowing. - It also has access to all the input files the original action has access to. - See <tt>extra_actions_base.proto</tt> - for details on the data stored inside the protocol buffer. Each proto file - contains an ExtraActionInfo message. -</p> - -<p> - Just like all other actions, extra actions are sandboxed, and should be designed to handle that. -</p> - - - - <h3 id="extra_action_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="extra_action.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - You may refer to this rule by <code>label</code> in the <code>extra_actions</code> argument - of <a href="/reference/be/extra-actions.html#action_listener"><code> action_listener</code></a> rules. - - </td> - </tr> - <tr> - <td id="extra_action.cmd"> - <code>cmd</code> - </td> - <td> - <p>String; required</p> - The command to run. - <p> - Like <a href="/reference/be/general.html#genrule.cmd">genrule cmd attribute</a> with the following - differences: - </p> - <ol> - <li> - <p> - No heuristic label expansion. Only labels using $(location ...) are expanded. - </p> - </li> - <li> - <p> - An additional pass is applied to the string to replace all - occurrences of the outputs created from the <code>out_templates</code> - attribute. All occurrences of <code>$(output <i>out_template</i>)</code> - are replaced with the path to the file denoted by <code>label</code>. - </p> - <p> - E.g. out_template <code>$(ACTION_ID).analysis</code> - can be matched with <code>$(output $(ACTION_ID).analysis)</code>. - </p> - <p> - In effect, this is the same substitution as <code>$(location)</code> - but with a different scope. - </p> - </li> - </ol> - - </td> - </tr> - <tr> - <td id="extra_action.out_templates"> - <code>out_templates</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - A list of templates for files generated by the <code>extra_action</code> command. - <p> - The template can use the following variables: - <ul> - <li> - $(ACTION_ID), an id uniquely identifying this <code>extra_action</code>. - Used to generate a unique output file. - </li> - </ul> - </p> - - </td> - </tr> - <tr> - <td id="extra_action.requires_action_output"> - <code>requires_action_output</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Indicates this <code>extra_action</code> requires the output of the - original action to be present as input to this <code>extra_action</code>. - <p> - When true (default false), the extra_action can assume that the - original action outputs are available as part of its inputs. - </p> - - </td> - </tr> - <tr> - <td id="extra_action.tools"> - <code>tools</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of <code>tool</code> dependencies for this rule. - <p> - See the definition of <a href="/concepts/build-ref#deps">dependencies</a> for more - information. - </p> - <p> - The build system ensures these prerequisites are built before running the - <code>extra_action</code> command; they are built using the - <a href='/docs/user-manual#configurations'><code>exec</code>configuration</a>, - since they must run as a tool during the build itself. The path of an individual - <code>tools</code> target <code>//x:y</code> can be obtained using - <code>$(location //x:y)</code>. - </p> - <p> - All tools and their data dependencies are consolidated into a single tree - within which the command can use relative paths. The working directory will - be the root of that unified tree. - </p> - - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +<li>$(ACTION_ID), an id uniquely identifying this <code>extra_action</code>. +Used to generate a unique output file.</li> +</ul></td> +</tr> +<tr> +<td id="extra_action.requires_action_output"><code>requires_action_output</code></td> +<td><p>Boolean; default is <code>False</code></p> +Indicates this <code>extra_action</code> requires the output of the +original action to be present as input to this <code>extra_action</code>. +<p>When true (default false), the extra_action can assume that the +original action outputs are available as part of its inputs.</p></td> +</tr> +<tr> +<td id="extra_action.tools"><code>tools</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of <code>tool</code> dependencies for this rule. +<p>See the definition of <a href="/concepts/build-ref#deps">dependencies</a> for more +information.</p> +<p>The build system ensures these prerequisites are built before running the +<code>extra_action</code> command; they are built using the +<a href="/docs/user-manual#configurations"><code>exec</code>configuration</a>, +since they must run as a tool during the build itself. The path of an individual +<code>tools</code> target <code>//x:y</code> can be obtained using +<code>$(location //x:y)</code>.</p> +<p>All tools and their data dependencies are consolidated into a single tree +within which the command can use relative paths. The working directory will +be the root of that unified tree.</p></td> +</tr> +</tbody> +</table> diff --git a/reference/be/functions.mdx b/reference/be/functions.mdx index a982ea8..086fd42 100644 --- a/reference/be/functions.mdx +++ b/reference/be/functions.mdx @@ -2,280 +2,216 @@ title: 'functions' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> -<!-- - This document is synchronized with Bazel releases. - To edit, submit changes to the Bazel source code. ---> +# Functions -<!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip --> +{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm" %} +{% include "\_buttons.html" %} -<h1 class="page-title">Functions</h1> +## Contents -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm" %} -{% include "_buttons.html" %} - -<h2>Contents</h2> -<ul> - <li><a href="#package">package</a></li> - <li><a href="#package_group">package_group</a></li> - <li><a href="#exports_files">exports_files</a></li> - <li><a href="#glob">glob</a></li> - <li><a href="#select">select</a></li> - <li><a href="#subpackages">subpackages</a></li> -</ul> -<!-- ================================================================= - package() - ================================================================= ---> - -<h2 id="package">package</h2> - -<pre> -package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features) -</pre> -<p>This function declares metadata that applies to every rule in the -package. It is used at most once within a package (BUILD file).</p> - -<p>For the counterpart that declares metadata applying to every rule in the whole -<em>repository</em>, use the <code>repo()</code> function in the -<a href="/external/overview#repo.bazel"><code>REPO.bazel</code> file</a> at the root of your repo. -The <code>repo()</code> function takes exactly the same arguments as <code>package()</code>.</p> -<p>The package() function should be called right after all the load() statements at the top of the -file, before any rule.</p> - -<h3 id="package_args">Arguments</h3> +- [package](#package) +- [package_group](#package_group) +- [exports_files](#exports_files) +- [glob](#glob) +- [select](#select) +- [subpackages](#subpackages) + +## package + + + package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features) + +This function declares metadata that applies to every rule in the +package. It is used at most once within a package (BUILD file). + +For the counterpart that declares metadata applying to every rule in the whole +*repository*, use the `repo()` function in the +[`REPO.bazel` file](/external/overview#repo.bazel) at the root of your repo. +The `repo()` function takes exactly the same arguments as `package()`. + +The package() function should be called right after all the load() statements at the top of the +file, before any rule. + +### Arguments <table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="package.default_applicable_licenses"><code>default_applicable_licenses</code></td> - <td> - <p>Alias for <a href="#package.default_package_metadata"><code>default_package_metadata</code></a>. - </td> - </tr> - <tr> - <td id="package.default_visibility"><code>default_visibility</code></td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - <p>The default visibility of the top-level rule targets and symbolic - macros in this package — that is, the targets and symbolic macros - that are not themselves declared inside a symbolic macro. This attribute - is ignored if the target or macro specifies a <code>visibility</code> - value.</p> - <p>For detailed information about the syntax of this attribute, see the - documentation of <a href="/concepts/visibility"> - visibility</a>. The package default visibility does not apply to - <a href="#exports_files">exports_files</a>, which is public by default. - </p> - </td> - </tr> - <tr> - <td id="package.default_deprecation"><code>default_deprecation</code></td> - <td> - <p>String; default is <code>""</code></p> - <p>Sets the default <a href="common-definitions.html#common.deprecation"> - <code>deprecation</code></a> message for all rules in this package.</p> - </td> - </tr> - <tr> - <td id="package.default_package_metadata"><code>default_package_metadata</code></td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - <p>Sets a default list of metadata targets which apply to all other targets in the package. - These are typically targets related to OSS package and license declarations. - See <a href="https://github.com/bazelbuild/rules_license">rules_license</a> for examples.</p> - </td> - </tr> - <tr> - <td id="package.default_testonly"><code>default_testonly</code></td> - <td> - <p>Boolean; default is <code>False</code> except as noted</p> - <p>Sets the default <a href="common-definitions.html#common.testonly"> - <code>testonly</code></a> property for all rules in this package.</p> - <p>In packages under <code>javatests</code> the default value is <code>True</code>.</p> - </td> - </tr> - <tr> - <td id="package.features"><code>features</code></td> - <td> - <p>List strings; default is <code>[]</code></p> - <p>Sets various flags that affect the semantics of this BUILD file.</p> - <p>This feature is mainly used by the people working on the build system to - tag packages that need some kind of special handling. Do not use this unless - explicitly requested by someone working on the build system.</p> - - </td> - </tr> - - </tbody> +<thead> +<tr> +<th>Attribute</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="package.default_applicable_licenses"><code>default_applicable_licenses</code></td> +<td><p>Alias for <a href="#package.default_package_metadata"><code>default_package_metadata</code></a>.</p></td> +</tr> +<tr> +<td id="package.default_visibility"><code>default_visibility</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +<p>The default visibility of the top-level rule targets and symbolic +macros in this package — that is, the targets and symbolic macros +that are not themselves declared inside a symbolic macro. This attribute +is ignored if the target or macro specifies a <code>visibility</code> +value.</p> +<p>For detailed information about the syntax of this attribute, see the +documentation of +<a href="/concepts/visibility">visibility</a>. The package default visibility does not apply to +<a href="#exports_files">exports_files</a>, which is public by default.</p></td> +</tr> +<tr> +<td id="package.default_deprecation"><code>default_deprecation</code></td> +<td><p>String; default is <code>""</code></p> +<p>Sets the default +<a href="common-definitions.html#common.deprecation"><code>deprecation</code></a> message for all rules in this package.</p></td> +</tr> +<tr> +<td id="package.default_package_metadata"><code>default_package_metadata</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +<p>Sets a default list of metadata targets which apply to all other targets in the package. +These are typically targets related to OSS package and license declarations. +See <a href="https://github.com/bazelbuild/rules_license">rules_license</a> for examples.</p></td> +</tr> +<tr> +<td id="package.default_testonly"><code>default_testonly</code></td> +<td><p>Boolean; default is <code>False</code> except as noted</p> +<p>Sets the default +<a href="common-definitions.html#common.testonly"><code>testonly</code></a> property for all rules in this package.</p> +<p>In packages under <code>javatests</code> the default value is <code>True</code>.</p></td> +</tr> +<tr> +<td id="package.features"><code>features</code></td> +<td><p>List strings; default is <code>[]</code></p> +<p>Sets various flags that affect the semantics of this BUILD file.</p> +<p>This feature is mainly used by the people working on the build system to +tag packages that need some kind of special handling. Do not use this unless +explicitly requested by someone working on the build system.</p></td> +</tr> +</tbody> </table> -<h3 id="package_example">Examples</h3> +### Examples The declaration below declares that the rules in this package are visible only to members of package -group <code>//foo:target</code>. Individual visibility declarations +group `//foo:target`. Individual visibility declarations on a rule, if present, override this specification. -<pre class="code"> -package(default_visibility = ["//foo:target"]) -</pre> +``` code -<!-- ================================================================= - package_group() - ================================================================= ---> +package(default_visibility = ["//foo:target"]) +``` -<h2 id="package_group">package_group</h2> +## package_group -<pre>package_group(name, packages, includes)</pre> + package_group(name, packages, includes) -<p>This function defines a set of <a href="/concepts/build-ref#packages">packages</a> +This function defines a set of [packages](/concepts/build-ref#packages) and associates a label with the set. The label can be referenced in -<code>visibility</code> attributes.</p> +`visibility` attributes. -<p>Package groups are primarily used for visibility control. A publicly visible +Package groups are primarily used for visibility control. A publicly visible target can be referenced from every package in the source tree. A privately visible target can only be referenced within its own package (not subpackages). In between these extremes, a target may allow access to its own package plus any of the packages described by one or more package groups. For a more detailed explanation of the visibility system, see the -<a href="common-definitions.html#common.visibility">visibility</a> -attribute.</p> +[visibility](common-definitions.html#common.visibility) +attribute. -<p>A given package is considered to be in the group if it either matches the -<code>packages</code> attribute, or is already contained in one of the other -package groups mentioned in the <code>includes</code> attribute.</p> +A given package is considered to be in the group if it either matches the +`packages` attribute, or is already contained in one of the other +package groups mentioned in the `includes` attribute. -<p>Package groups are technically targets, but are not created by rules, and do -not themselves have any visibility protection.</p> +Package groups are technically targets, but are not created by rules, and do +not themselves have any visibility protection. -<h3 id="package_group_args">Arguments</h3> +### Arguments <table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="package_group.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - </td> - </tr> - <tr> - <td id="package_group.packages"><code>packages</code></td> - <td> - <p>List of strings; default is <code>[]</code></p> - <p>A list of zero or more package specifications.</p> - - <p>Each package specification string can have one of the following - forms:</p> - - <ol> - - <li>The full name of a package, without its repository, starting with a - double slash. For example, <code>//foo/bar</code> specifies the package - having that name and which lives in the same repository as the package - group. - - <li>As above, but with a trailing <code>/...</code>. For example, <code> - //foo/...</code> specifies the set of <code>//foo</code> and all its - subpackages. <code>//...</code> specifies all packages in the current - repository. - - <li>The strings <code>public</code> or <code>private</code>, which - respectively specify every package or no package. (This form requires - the flag <code>--incompatible_package_group_has_public_syntax</code> to - be set.) - - </ol> - - <p>In addition, the first two kinds of package specifications may also - be prefixed with <code>-</code> to indicate that they are negated.</p> - - <p>The package group contains any package that matches at least one of - its positive specifications and none of its negative specifications - For instance, the value <code>[//foo/..., -//foo/tests/...]</code> - includes all subpackages of <code>//foo</code> that are not also - subpackages of <code>//foo/tests</code>. (<code>//foo</code> itself is - included while </code>//foo/tests</code> itself is not.)</p> - - <p>Aside from public visibility, there is no way to directly specify - packages outside the current repository.</p> - - <p>If this attribute is missing, it is the same as setting it to an - empty list, which is also the same as setting it to a list containing - only <code>private</code>. - - <p><i>Note:</i> Prior to Bazel 6.0, the specification <code>//...</code> - had a legacy behavior of being the same as <code>public</code>. This - behavior is fixed when - <code>--incompatible_fix_package_group_reporoot_syntax</code> is - enabled, which is the default after Bazel 6.0.</p> - - <p><i>Note:</i> Prior to Bazel 6.0, when this attribute is serialized as - part of <code>bazel query --output=proto</code> (or - <code>--output=xml</code>), the leading slashes are omitted. For - instance, <code>//pkg/foo/...</code> will output as - <code>\"pkg/foo/...\"</code>. This behavior is fixed when - <code>--incompatible_package_group_includes_double_slash</code> is - enabled, which is the default after Bazel 6.0.</p> - </td> - </tr> - <tr> - <td id="package_group.includes"><code>includes</code></td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - <p>Other package groups that are included in this one.</p> - - <p>The labels in this attribute must refer to other package groups. - Packages in referenced package groups are taken to be part of this - package group. This is transitive — if package group - <code>a</code> includes package group <code>b</code>, and <code>b</code> - includes package group <code>c</code>, then every package in - <code>c</code> will also be a member of <code>a</code>.</p> - - <p>When used together with negated package specifications, note that the - set of packages for each group is first computed independently and the - results are then unioned together. This means that negated - specifications in one group have no effect on the specifications in - another group.</p> - </td> - </tr> - </tbody> +<thead> +<tr> +<th>Attribute</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="package_group.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="package_group.packages"><code>packages</code></td> +<td><p>List of strings; default is <code>[]</code></p> +<p>A list of zero or more package specifications.</p> +<p>Each package specification string can have one of the following +forms:</p> +<ol> +<li>The full name of a package, without its repository, starting with a +double slash. For example, <code>//foo/bar</code> specifies the package +having that name and which lives in the same repository as the package +group.</li> +<li>As above, but with a trailing <code>/...</code>. For example, <code> //foo/...</code> specifies the set of <code>//foo</code> and all its +subpackages. <code>//...</code> specifies all packages in the current +repository.</li> +<li>The strings <code>public</code> or <code>private</code>, which +respectively specify every package or no package. (This form requires +the flag <code>--incompatible_package_group_has_public_syntax</code> to +be set.)</li> +</ol> +<p>In addition, the first two kinds of package specifications may also +be prefixed with <code>-</code> to indicate that they are negated.</p> +<p>The package group contains any package that matches at least one of +its positive specifications and none of its negative specifications +For instance, the value <code>[//foo/..., -//foo/tests/...]</code> +includes all subpackages of <code>//foo</code> that are not also +subpackages of <code>//foo/tests</code>. (<code>//foo</code> itself is +included while //foo/tests itself is not.)</p> +<p>Aside from public visibility, there is no way to directly specify +packages outside the current repository.</p> +<p>If this attribute is missing, it is the same as setting it to an +empty list, which is also the same as setting it to a list containing +only <code>private</code>.</p> +<p><em>Note:</em> Prior to Bazel 6.0, the specification <code>//...</code> +had a legacy behavior of being the same as <code>public</code>. This +behavior is fixed when +<code>--incompatible_fix_package_group_reporoot_syntax</code> is +enabled, which is the default after Bazel 6.0.</p> +<p><em>Note:</em> Prior to Bazel 6.0, when this attribute is serialized as +part of <code>bazel query --output=proto</code> (or +<code>--output=xml</code>), the leading slashes are omitted. For +instance, <code>//pkg/foo/...</code> will output as +<code>\"pkg/foo/...\"</code>. This behavior is fixed when +<code>--incompatible_package_group_includes_double_slash</code> is +enabled, which is the default after Bazel 6.0.</p></td> +</tr> +<tr> +<td id="package_group.includes"><code>includes</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +<p>Other package groups that are included in this one.</p> +<p>The labels in this attribute must refer to other package groups. +Packages in referenced package groups are taken to be part of this +package group. This is transitive — if package group +<code>a</code> includes package group <code>b</code>, and <code>b</code> +includes package group <code>c</code>, then every package in +<code>c</code> will also be a member of <code>a</code>.</p> +<p>When used together with negated package specifications, note that the +set of packages for each group is first computed independently and the +results are then unioned together. This means that negated +specifications in one group have no effect on the specifications in +another group.</p></td> +</tr> +</tbody> </table> -<h3 id="package_group_example">Examples</h3> +### Examples -<p>The following <code>package_group</code> declaration specifies a -package group called "tropical" that contains tropical fruits.</p> +The following `package_group` declaration specifies a +package group called "tropical" that contains tropical fruits. + +``` code -<pre class="code"> package_group( name = "tropical", packages = [ @@ -284,12 +220,13 @@ package_group( "//fruits/papaya/...", ], ) -</pre> +``` + +The following declarations specify the package groups of a fictional +application: -<p>The following declarations specify the package groups of a fictional -application:</p> +``` code -<pre class="code"> package_group( name = "fooapp", includes = [ @@ -316,249 +253,192 @@ package_group( name = "controller", packages = ["//fooapp/algorithm"], ) -</pre> - -<!-- ================================================================= - exports_files([label, ...]) - ================================================================= - --> - -<h2 id="exports_files">exports_files</h2> - -<pre>exports_files([<i>label</i>, ...], visibility, licenses)</pre> - -<p> - <code>exports_files()</code> specifies a list of files belonging to - this package that are exported to other packages. -</p> - -<p> - The BUILD file for a package may only refer directly to source files belonging - to another package if they are explicitly exported with an - <code>exports_files()</code> statement. Read more about - <a href="/concepts/visibility#source-file-target-visibility">visibility of files</a>. -</p> - <p> - As a legacy behaviour, also files mentioned as input to a rule are exported - with the default visibility until the flag - <a href="https://github.com/bazelbuild/bazel/issues/10225"><code>--incompatible_no_implicit_file_export</code></a> - is flipped. However, this behavior should not be relied upon and actively - migrated away from. -</p> - -<h3 id="exports_files_args">Arguments</h3> - -<p> - The argument is a list of names of files within the current package. A - visibility declaration can also be specified; in this case, the files will be - visible to the targets specified. If no visibility is specified, the files - will be visible to every package, even if a package default visibility was - specified in the <code><a href="functions.html#package">package</a></code> - function. The <a href="common-definitions.html#common.licenses">licenses</a> - can also be specified. -</p> - -<h3 id="exports_files_example">Example</h3> - -<p> - The following example exports <code>golden.txt</code>, a - text file from the <code>test_data</code> package, so that other - packages may use it, for example, in the <code>data</code> attribute - of tests. -</p> - -<pre class="code"> +``` + +## exports_files + + exports_files([label, ...], visibility, licenses) + +`exports_files()` specifies a list of files belonging to +this package that are exported to other packages. + +The BUILD file for a package may only refer directly to source files belonging +to another package if they are explicitly exported with an +`exports_files()` statement. Read more about +[visibility of files](/concepts/visibility#source-file-target-visibility). + +As a legacy behaviour, also files mentioned as input to a rule are exported +with the default visibility until the flag +[`--incompatible_no_implicit_file_export`](https://github.com/bazelbuild/bazel/issues/10225) +is flipped. However, this behavior should not be relied upon and actively +migrated away from. + +### Arguments + +The argument is a list of names of files within the current package. A +visibility declaration can also be specified; in this case, the files will be +visible to the targets specified. If no visibility is specified, the files +will be visible to every package, even if a package default visibility was +specified in the [`package`](functions.html#package) +function. The [licenses](common-definitions.html#common.licenses) +can also be specified. + +### Example + +The following example exports `golden.txt`, a +text file from the `test_data` package, so that other +packages may use it, for example, in the `data` attribute +of tests. + +``` code + # from //test_data/BUILD exports_files(["golden.txt"]) -</pre> +``` -<!-- ================================================================= - glob() - ================================================================= - --> +## glob -<h2 id="glob">glob</h2> + glob(include, exclude=[], exclude_directories=1, allow_empty=True) -<pre>glob(include, exclude=[], exclude_directories=1, allow_empty=True)</pre> - -<p> Glob is a helper function that finds all files that match certain path patterns, and returns a new, mutable, sorted list of their paths. Glob only searches files in its own package, and looks only for source files (not generated files nor other targets). -</p> -<p> A source file's Label is included in the result if the file's package-relative -path matches any of the <code>include</code> patterns and none of the -<code>exclude</code> patterns. -</p> +path matches any of the `include` patterns and none of the +`exclude` patterns. -<p> -The <code>include</code> and <code>exclude</code> lists contain path patterns +The `include` and `exclude` lists contain path patterns that are relative to the current package. Every pattern may consist of one or more path segments. As usual with Unix paths, these segments are separated by -<code>/</code>. The segments in the pattern are matched against the segments of -the path. Segments may contain the <code>*</code> wildcard: this matches +`/`. The segments in the pattern are matched against the segments of +the path. Segments may contain the `*` wildcard: this matches any substring in the path segment (even the empty substring), excluding the -directory separator <code>/</code>. This wildcard can be used multiple times -within one path segment. Additionally, the <code>**</code> wildcard can match +directory separator `/`. This wildcard can be used multiple times +within one path segment. Additionally, the `**` wildcard can match zero or more complete path segments, but it must be declared as a standalone path segment. -</p> Examples: -<ul> -<li><code>foo/bar.txt</code> matches exactly the <code>foo/bar.txt</code> file -in this package (unless <code>foo/</code> is a subpackage)</li> -<li><code>foo/*.txt</code> matches every file in the <code>foo/</code> directory -if the file ends with <code>.txt</code> (unless <code>foo/</code> is a -subpackage)</li> -<li><code>foo/a*.htm*</code> matches every file in the <code>foo/</code> -directory that starts with <code>a</code>, then has an arbitrary string (could -be empty), then has <code>.htm</code>, and ends with another arbitrary string -(unless <code>foo/</code> is a subpackage); such as <code>foo/axx.htm</code> -and <code>foo/a.html</code> or <code>foo/axxx.html</code></li> -<li><code>foo/*</code> matches every file in the <code>foo/</code> directory, -(unless <code>foo/</code> is a subpackage); it does not match <code>foo</code> -directory itself even if <code>exclude_directories</code> is set to -</code>0</code></li> -<li><code>foo/**</code> matches every file in every non-subpackage subdirectory -under package's first level subdirectory <code>foo/</code>; if -<code>exclude_directories</code> is set to </code>0</code>, <code>foo</code> -directory itself also matches the pattern; in this case, <code>**</code> is -considered to match zero path segments</li> -<li><code>**/a.txt</code> matches <code>a.txt</code> files in this package's -directory plus non-subpackage subdirectories.</li> -<li><code>**/bar/**/*.txt</code> matches every <code>.txt</code> file in every -non-subpackage subdirectory of this package, if at least one directory on the -resulting path is called <code>bar</code>, such as -<code>xxx/bar/yyy/zzz/a.txt</code> or <code>bar/a.txt</code> (remember that -<code>**</code> also matches zero segments) or <code>bar/zzz/a.txt</code></li> -<li><code>**</code> matches every file in every non-subpackage subdirectory of -this package</li> -<li><code>foo**/a.txt</code> is an invalid pattern, because <code>**</code> must -stand on its own as a segment</li> -<li><code>foo/</code> is an invalid pattern, because the second segment defined -after <code>/</code> is an empty string</li> -</ul> - -<p> -If the <code>exclude_directories</code> argument is enabled (set to 1), files of + +- `foo/bar.txt` matches exactly the `foo/bar.txt` file + in this package (unless `foo/` is a subpackage) +- `foo/*.txt` matches every file in the `foo/` directory + if the file ends with `.txt` (unless `foo/` is a + subpackage) +- `foo/a*.htm*` matches every file in the `foo/` + directory that starts with `a`, then has an arbitrary string (could + be empty), then has `.htm`, and ends with another arbitrary string + (unless `foo/` is a subpackage); such as `foo/axx.htm` + and `foo/a.html` or `foo/axxx.html` +- `foo/*` matches every file in the `foo/` directory, + (unless `foo/` is a subpackage); it does not match `foo` + directory itself even if `exclude_directories` is set to + 0 +- `foo/**` matches every file in every non-subpackage subdirectory + under package's first level subdirectory `foo/`; if + `exclude_directories` is set to 0, `foo` + directory itself also matches the pattern; in this case, `**` is + considered to match zero path segments +- `**/a.txt` matches `a.txt` files in this package's + directory plus non-subpackage subdirectories. +- `**/bar/**/*.txt` matches every `.txt` file in every + non-subpackage subdirectory of this package, if at least one directory on the + resulting path is called `bar`, such as + `xxx/bar/yyy/zzz/a.txt` or `bar/a.txt` (remember that + `**` also matches zero segments) or `bar/zzz/a.txt` +- `**` matches every file in every non-subpackage subdirectory of + this package +- `foo**/a.txt` is an invalid pattern, because `**` must + stand on its own as a segment +- `foo/` is an invalid pattern, because the second segment defined + after `/` is an empty string + +If the `exclude_directories` argument is enabled (set to 1), files of type directory will be omitted from the results (default 1). -</p> -<p> -If the <code>allow_empty</code> argument is set to <code>False</code>, the -<code>glob</code> function will error-out if the result would otherwise be the + +If the `allow_empty` argument is set to `False`, the +`glob` function will error-out if the result would otherwise be the empty list. -</p> -<p> + There are several important limitations and caveats: -</p> -<ol> - <li> - <p> - Since <code>glob()</code> runs during BUILD file evaluation, - <code>glob()</code> matches files only in your source tree, never - generated files. If you are building a target that requires both +1. Since `glob()` runs during BUILD file evaluation, + `glob()` matches files only in your source tree, never + generated files. If you are building a target that requires both source and generated files, you must append an explicit list of generated - files to the glob. See the <a href="#glob_example">example</a> - below with <code>:mylib</code> and <code>:gen_java_srcs</code>. - </p> - </li> - - <li> - <p> - If a rule has the same name as a matched source file, the rule will - "shadow" the file. - </p> - <p> - To understand this, remember that <code>glob()</code> returns a list of - paths, so using <code>glob()</code> in other rules' attribute (e.g. - <code>srcs = glob(["*.cc"])</code>) has the same effect as listing the - matched paths explicitly. If for example <code>glob()</code> yields - <code>["Foo.java", "bar/Baz.java"]</code> but there's also a rule in the - package called "Foo.java" (which is allowed, though Bazel warns about it), - then the consumer of the <code>glob()</code> will use the "Foo.java" rule - (its outputs) instead of the "Foo.java" file. See - <a href="https://github.com/bazelbuild/bazel/issues/10395#issuecomment-583714657">GitHub - issue #10395</a> for more details. - </p> - </li> - - <li> - Globs may match files in subdirectories. And subdirectory names - may be wildcarded. However... - </li> - - <li> - <p> - Labels are not allowed to cross the package boundary and glob does + files to the glob. See the [example](#glob_example) + below with `:mylib` and `:gen_java_srcs`. + +2. If a rule has the same name as a matched source file, the rule will + "shadow" the file. + + To understand this, remember that `glob()` returns a list of + paths, so using `glob()` in other rules' attribute (e.g. + `srcs = glob(["*.cc"])`) has the same effect as listing the + matched paths explicitly. If for example `glob()` yields + `["Foo.java", "bar/Baz.java"]` but there's also a rule in the + package called "Foo.java" (which is allowed, though Bazel warns about it), + then the consumer of the `glob()` will use the "Foo.java" rule + (its outputs) instead of the "Foo.java" file. See + [GitHub + issue \#10395](https://github.com/bazelbuild/bazel/issues/10395#issuecomment-583714657) for more details. + +3. Globs may match files in subdirectories. And subdirectory names + may be wildcarded. However... + +4. Labels are not allowed to cross the package boundary and glob does not match files in subpackages. - </p> - <p> - For example, the glob expression <code>**/*.cc</code> in package - <code>x</code> does not include <code>x/y/z.cc</code> if - <code>x/y</code> exists as a package (either as - <code>x/y/BUILD</code>, or somewhere else on the package-path). This + For example, the glob expression `**/*.cc` in package + `x` does not include `x/y/z.cc` if + `x/y` exists as a package (either as + `x/y/BUILD`, or somewhere else on the package-path). This means that the result of the glob expression actually depends on the - existence of BUILD files — that is, the same glob expression would - include <code>x/y/z.cc</code> if there was no package called - <code>x/y</code> or it was marked as deleted using the - <a href="/docs/user-manual#flag--deleted_packages">--deleted_packages</a> + existence of BUILD files — that is, the same glob expression would + include `x/y/z.cc` if there was no package called + `x/y` or it was marked as deleted using the + [--deleted_packages](/docs/user-manual#flag--deleted_packages) flag. - </p> - - </li> - <li> - The restriction above applies to all glob expressions, +5. The restriction above applies to all glob expressions, no matter which wildcards they use. - </li> - <li> - A hidden file with filename starting with <code>.</code> is completely matched by - both the <code>**</code> and the <code>*</code> wildcards. If you want to match a hidden file - with a compound pattern, your pattern needs to begin with a <code>.</code>. For example, - <code>*</code> and <code>.*.txt</code> will match <code>.foo.txt</code>, but <code>*.txt</code> - will not. +6. A hidden file with filename starting with `.` is completely matched by + both the `**` and the `*` wildcards. If you want to match a hidden file + with a compound pattern, your pattern needs to begin with a `.`. For example, + `*` and `.*.txt` will match `.foo.txt`, but `*.txt` + will not. Hidden directories are also matched in the same manner. Hidden directories may include files that are not required as inputs, and can increase the number of unnecessarily globbed files and memory consumption. To exclude hidden directories, add them to the "exclude" list argument. - </li> - <li> - The "**" wildcard has one corner case: the pattern - <code>"**"</code> doesn't match the package's directory path. That is to - say, <code>glob(["**"], exclude_directories = False)</code> matches all files +7. The "\*\*" wildcard has one corner case: the pattern + `"**"` doesn't match the package's directory path. That is to + say, `glob(["**"], exclude_directories = False)` matches all files and directories transitively strictly under the current package's directory (but of course not going into directories of subpackages - see the previous note about that). - </li> -</ol> -<p> -In general, you should <b>try to provide an appropriate extension (e.g. *.html) -instead of using a bare '*'</b> for a glob pattern. The more explicit name +In general, you should **try to provide an appropriate extension (e.g. \*.html) +instead of using a bare '\*'** for a glob pattern. The more explicit name is both self documenting and ensures that you don't accidentally match backup files, or emacs/vi/... auto-save files. -</p> -<p> When writing build rules you can enumerate the elements of the glob. This enables generating individual rules for every input, for example. See the -<a href="#expanded_glob_example">expanded glob example</a> section below. -</p> +[expanded glob example](#expanded_glob_example) section below. + +### Glob Examples + +Create a Java library built from all java files in this directory, +and all files generated by the `:gen_java_srcs` rule. -<h3 id="glob_example">Glob Examples</h3> +``` code -<p> Create a Java library built from all java files in this directory, -and all files generated by the <code>:gen_java_srcs</code> rule.</p> -<pre class="code"> java_library( name = "mylib", srcs = glob(["*.java"]) + [":gen_java_srcs"], @@ -573,12 +453,14 @@ genrule( ], ... ) -</pre> +``` -<p>Include all txt files in directory testdata except experimental.txt. +Include all txt files in directory testdata except experimental.txt. Note that files in subdirectories of testdata will not be included. If -you want those files to be included, use a recursive glob (**).</p> -<pre class="code"> +you want those files to be included, use a recursive glob (\*\*). + +``` code + sh_test( name = "mytest", srcs = ["mytest.sh"], @@ -587,29 +469,31 @@ sh_test( exclude = ["testdata/experimental.txt"], ), ) -</pre> +``` -<h3 id="recursive_glob_example">Recursive Glob Examples</h3> +### Recursive Glob Examples +Make the test depend on all txt files in the testdata directory and any +of its subdirectories (and their subdirectories, and so on). +Subdirectories containing a BUILD file are ignored. (See limitations +and caveats above.) + +``` code -<p>Make the test depend on all txt files in the testdata directory and any - of its subdirectories (and their subdirectories, and so on). - Subdirectories containing a BUILD file are ignored. (See limitations - and caveats above.)</p> -<pre class="code"> sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob(["testdata/**/*.txt"]), ) -</pre> +``` -<p>Create a library built from all java files in this directory and all +Create a library built from all java files in this directory and all subdirectories except those whose path includes a directory named testing. -<b>This pattern should be avoided if possible, as it can reduce build -incrementality and therefore increase build times.</b> -</p> -<pre class="code"> +**This pattern should be avoided if possible, as it can reduce build +incrementality and therefore increase build times.** + +``` code + java_library( name = "mylib", srcs = glob( @@ -617,65 +501,55 @@ java_library( exclude = ["**/testing/**"], ), ) -</pre> +``` -<h3 id="expanded_glob_example">Expanded Glob Examples</h3> +### Expanded Glob Examples -<p> -Create an individual genrule for *_test.cc in the current directory +Create an individual genrule for \*\_test.cc in the current directory that counts the number of lines in the file. -</p> -<pre class="code"> +``` code + # Conveniently, the build language supports list comprehensions. [genrule( name = "count_lines_" + f[:-3], # strip ".cc" srcs = [f], outs = ["%s-linecount.txt" % f[:-3]], - cmd = "wc -l $< >$@", + cmd = "wc -l $< >$@", ) for f in glob(["*_test.cc"])] -</pre> +``` -<p> If the BUILD file above is in package //foo and the package contains three matching files, a_test.cc, b_test.cc and c_test.cc then running -<code>bazel query '//foo:all'</code> will list all rules that were generated: - -<pre> -$ bazel query '//foo:all' | sort -//foo:count_lines_a_test -//foo:count_lines_b_test -//foo:count_lines_c_test -</pre> - -<!-- ================================================================= - select() - ================================================================= ---> - -<h2 id="select">select</h2> - -<pre> -select( - {conditionA: valuesA, conditionB: valuesB, ...}, - no_match_error = "custom message" -) -</pre> +`bazel query '//foo:all'` will list all rules that were generated: + + + $ bazel query '//foo:all' | sort + //foo:count_lines_a_test + //foo:count_lines_b_test + //foo:count_lines_c_test + +## select -<p><code>select()</code> is the helper function that makes a rule attribute - <a href="common-definitions.html#configurable-attributes">configurable</a>. - It can replace the right-hand side of - <i>almost</i> - any attribute assignment so its value depends on command-line Bazel flags. - You can use this, for example, to define platform-specific dependencies or to - embed different resources depending on whether a rule is built in "developer" - vs. "release" mode. -</p> + select( + {conditionA: valuesA, conditionB: valuesB, ...}, + no_match_error = "custom message" + ) -<p>Basic use is as follows:</p> +`select()` is the helper function that makes a rule attribute +[configurable](common-definitions.html#configurable-attributes). +It can replace the right-hand side of +*almost* +any attribute assignment so its value depends on command-line Bazel flags. +You can use this, for example, to define platform-specific dependencies or to +embed different resources depending on whether a rule is built in "developer" +vs. "release" mode. + +Basic use is as follows: + +``` code -<pre class="code"> sh_binary( name = "mytarget", srcs = select({ @@ -684,77 +558,63 @@ sh_binary( "//conditions:default": ["mytarget_default.sh"] }) ) -</pre> - -<p>This makes the <code>srcs</code> attribute of - a <code>sh_binary</code> configurable by replacing its normal label - list assignment with a <code>select</code> call that maps - configuration conditions to matching values. Each condition is a label - reference to - a <code><a href="general.html#config_setting">config_setting</a></code> or - <code><a href="platforms-and-toolchains.html#constraint_value">constraint_value</a></code>, - which "matches" if the target's configuration matches an expected set of - values. The value of <code>mytarget#srcs</code> then becomes whichever - label list matches the current invocation. -</p> - -<p>Notes:</p> - -<ul> - <li>Exactly one condition is selected on any invocation. - </li> - <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 and constraint - values as A plus some additional flags or constraint values. This also - means that specialization resolution is not designed to create an ordering as - demonstrated in Example 2 below. - </li> - <li>If multiple conditions match and one is not a specialization of all the - others, Bazel fails with an error, unless all conditions resolve to the same value. - </li> - <li>The special pseudo-label <code>//conditions:default</code> is - considered to match if no other condition matches. If this condition - is left out, some other rule must match to avoid an error. - </li> - <li><code>select</code> can be embedded <i>inside</i> a larger - attribute assignment. So <code>srcs = ["common.sh"] - + select({ ":conditionA": ["myrule_a.sh"], ...})</code> and <code> - srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": - ["b.sh"]})</code> are valid expressions. - </li> - <li><code>select</code> works with most, but not all, attributes. Incompatible - attributes are marked <code>nonconfigurable</code> in their documentation. - -<!-- ================================================================= - subpackages() - ================================================================= - --> - -<h2 id="subpackages">subpackages</h2> - -<pre>subpackages(include, exclude=[], allow_empty=True)</pre> - -<p> - <code>subpackages()</code> is a helper function, similar to <code>glob()</code> - that lists subpackages instead of files and directories. It uses the same - path patterns as <code>glob()</code> and can match any subpackage that is a - direct descendant of the currently loading BUILD file. See <a - href="#glob">glob</a> for a detailed explanation and examples of include and - exclude patterns. -</p> - -<p> - The resulting list of subpackages returned is in sorted order and contains - paths relative to the current loading package that match the given patterns in - <code>include</code> and not those in <code>exclude</code>. - -<h3 id=subpackages_example">Example</h3> - -<p> - The following example lists all the direct subpackages for the package <code>foo/BUILD</code> - -<pre class="code"> +``` + +This makes the `srcs` attribute of +a `sh_binary` configurable by replacing its normal label +list assignment with a `select` call that maps +configuration conditions to matching values. Each condition is a label +reference to +a [`config_setting`](general.html#config_setting) or +[`constraint_value`](platforms-and-toolchains.html#constraint_value), +which "matches" if the target's configuration matches an expected set of +values. The value of `mytarget#srcs` then becomes whichever +label list matches the current invocation. + +Notes: + +Exactly one condition is selected on any invocation. + +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 and constraint +values as A plus some additional flags or constraint values. This also +means that specialization resolution is not designed to create an ordering as +demonstrated in Example 2 below. + +If multiple conditions match and one is not a specialization of all the +others, Bazel fails with an error, unless all conditions resolve to the same value. + +The special pseudo-label `//conditions:default` is +considered to match if no other condition matches. If this condition +is left out, some other rule must match to avoid an error. + +`select` can be embedded *inside* a larger +attribute assignment. So `srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...})` and ` srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]})` are valid expressions. + +`select` works with most, but not all, attributes. Incompatible +attributes are marked `nonconfigurable` in their documentation. + +## subpackages + + subpackages(include, exclude=[], allow_empty=True) + +`subpackages()` is a helper function, similar to `glob()` +that lists subpackages instead of files and directories. It uses the same +path patterns as `glob()` and can match any subpackage that is a +direct descendant of the currently loading BUILD file. See [glob](#glob) for a detailed explanation and examples of include and +exclude patterns. + +The resulting list of subpackages returned is in sorted order and contains +paths relative to the current loading package that match the given patterns in +`include` and not those in `exclude`. + +### Example + +The following example lists all the direct subpackages for the package `foo/BUILD` + +``` code + # The following BUILD files exist: # foo/BUILD # foo/bar/baz/BUILD @@ -797,14 +657,8 @@ subs6 = subpackages(include = ["sub/**"]) # In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it # is returned. But the subdirectories of 'foo/sub' will not be traversed # anymore. -</pre> - - <p> - In general it is preferred that instead of calling this function directly - that users use the 'subpackages' module of - <a href="https://github.com/bazelbuild/bazel-skylib">skylib</a>. - -<!-- Generated footer --> +``` -</body> -</html> +In general it is preferred that instead of calling this function directly +that users use the 'subpackages' module of +[skylib](https://github.com/bazelbuild/bazel-skylib). diff --git a/reference/be/general.mdx b/reference/be/general.mdx index 946c9b9..a510f80 100644 --- a/reference/be/general.mdx +++ b/reference/be/general.mdx @@ -2,111 +2,55 @@ title: 'general' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">General Rules</h1> +# General Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} +{% include "\_buttons.html" %} +## Rules +- [alias](#alias) +- [config_setting](#config_setting) +- [filegroup](#filegroup) +- [genquery](#genquery) +- [genrule](#genrule) +- [starlark_doc_extract](#starlark_doc_extract) +- [test_suite](#test_suite) +## alias -<h2>Rules</h2> -<ul> - <li> - <a href="#alias"> - alias </a> - </li> - <li> - <a href="#config_setting"> - config_setting </a> - </li> - <li> - <a href="#filegroup"> - filegroup </a> - </li> - <li> - <a href="#genquery"> - genquery </a> - </li> - <li> - <a href="#genrule"> - genrule </a> - </li> - <li> - <a href="#starlark_doc_extract"> - starlark_doc_extract </a> - </li> - <li> - <a href="#test_suite"> - test_suite </a> - </li> -</ul> +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/Alias.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +alias(name, actual, aspect_hints, compatible_with, deprecation, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) +``` + +The `alias` rule creates another name a rule can be referred to as. + +Aliasing only works for "regular" targets. In particular, `package_group` +and `test_suite` cannot be aliased. + +Aliasing may be of help in large repositories where renaming a target would require making +changes to lots of files. You can also use alias rule to store a +[select](/reference/be/functions.html#select) function call if you want to reuse that logic for +multiple targets. + +The alias rule has its own visibility declaration. In all other respects, it behaves +like the rule it references (e.g. testonly *on the alias* is ignored; the testonly-ness +of the referenced rule is used instead) with some minor exceptions: + +- Tests are not run if their alias is mentioned on the command line. To define an alias + that runs the referenced test, use a [`test_suite`](#test_suite) + rule with a single target in its [`tests`](#test_suite.tests) + attribute. +- When defining environment groups, the aliases to `environment` rules are not + supported. They are not supported in the `--target_environment` command line + option, either. + +#### Examples + +``` code - <h2 id="alias"> - alias - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/Alias.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">alias(<a href="#alias.name">name</a>, <a href="#alias.actual">actual</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.package_metadata">package_metadata</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> - The <code>alias</code> rule creates another name a rule can be referred to as. -</p> - -<p> - Aliasing only works for "regular" targets. In particular, <code>package_group</code> - and <code>test_suite</code> cannot be aliased. -</p> - -<p> - Aliasing may be of help in large repositories where renaming a target would require making - changes to lots of files. You can also use alias rule to store a - <a href="/reference/be/functions.html#select">select</a> function call if you want to reuse that logic for - multiple targets. -</p> - -<p> - The alias rule has its own visibility declaration. In all other respects, it behaves - like the rule it references (e.g. testonly <em>on the alias</em> is ignored; the testonly-ness - of the referenced rule is used instead) with some minor exceptions: - - <ul> - <li> - Tests are not run if their alias is mentioned on the command line. To define an alias - that runs the referenced test, use a <a href="#test_suite"><code>test_suite</code></a> - rule with a single target in its <a href="#test_suite.tests"><code>tests</code></a> - attribute. - </li> - <li> - When defining environment groups, the aliases to <code>environment</code> rules are not - supported. They are not supported in the <code>--target_environment</code> command line - option, either. - </li> - </ul> -</p> - -<h4 id="alias_example">Examples</h4> - -<pre class="code"> filegroup( name = "data", srcs = ["data.txt"], @@ -116,78 +60,63 @@ alias( name = "other", actual = ":data", ) -</pre> - - - - <h3 id="alias_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="alias.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="alias.actual"> - <code>actual</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - The target this alias refers to. It does not need to be a rule, it can also be an input - file. - - </td> - </tr> - </tbody> - </table> - <h2 id="config_setting"> - config_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/config/ConfigRuleClasses.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">config_setting(<a href="#config_setting.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#config_setting.constraint_values">constraint_values</a>, <a href="#config_setting.define_values">define_values</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#config_setting.flag_values">flag_values</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#config_setting.values">values</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - - <p> - Matches an expected configuration state (expressed as build flags or platform constraints) for - the purpose of triggering configurable attributes. See <a href="/reference/be/functions.html#select">select</a> for - how to consume this rule and <a href="/reference/be/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 build that sets <code>--compilation_mode=opt</code> or - <code>-c opt</code> (either explicitly at the command line or implicitly from .bazelrc files): - </p> - - <pre class="code"> +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="alias.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="alias.actual"><code>actual</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +The target this alias refers to. It does not need to be a rule, it can also be an input +file.</td> +</tr> +</tbody> +</table> + +## config_setting + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +config_setting(name, aspect_hints, constraint_values, define_values, deprecation, features, flag_values, licenses, package_metadata, tags, testonly, values, visibility) +``` + +Matches an expected configuration state (expressed as build flags or platform constraints) for +the purpose of triggering configurable attributes. See [select](/reference/be/functions.html#select) for +how to consume this rule and +[Configurable attributes](/reference/be/common-definitions#configurable-attributes) for an overview of the general feature. + +#### Examples + +The following matches any build that sets `--compilation_mode=opt` or +`-c opt` (either explicitly at the command line or implicitly from .bazelrc files): + +``` code + config_setting( name = "simple", values = {"compilation_mode": "opt"} ) - </pre> + +``` - <p>The following matches any build that targets ARM and applies the custom define - <code>FOO=bar</code> (for instance, <code>bazel build --cpu=arm --define FOO=bar ...</code>): - </p> +The following matches any build that targets ARM and applies the custom define +`FOO=bar` (for instance, `bazel build --cpu=arm --define FOO=bar ...`): + +``` code - <pre class="code"> config_setting( name = "two_conditions", values = { @@ -195,28 +124,30 @@ alias( "define": "FOO=bar" } ) - </pre> + +``` + +The following matches any build that sets +[user-defined flag](https://bazel.build/rules/config#user-defined-build-settings) +`--//custom_flags:foo=1` (either explicitly at the command line or implicitly from +.bazelrc files): - <p>The following matches any build that sets - <a href="https://bazel.build/rules/config#user-defined-build-settings">user-defined flag</a> - <code>--//custom_flags:foo=1</code> (either explicitly at the command line or implicitly from - .bazelrc files): - </p> +``` code - <pre class="code"> config_setting( name = "my_custom_flag_is_set", flag_values = { "//custom_flags:foo": "1" }, ) - </pre> + +``` + +The following matches any build that targets a platform with an x86_64 architecture and glibc +version 2.25, assuming the existence of a `constraint_value` with label +`//example:glibc_2_25`. Note that a platform still matches if it defines additional +constraint values beyond these two. - <p>The following matches any build that targets a platform with 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> +``` code - <pre class="code"> config_setting( name = "64bit_glibc_2_25", constraint_values = [ @@ -224,241 +155,175 @@ alias( "//example:glibc_2_25", ] ) - </pre> - - In all these cases, it's possible for the configuration to change within the build, for example if - a target needs to be built for a different platform than its dep. This means that even when a - <code>config_setting</code> doesn't match the top-level command-line flags, it may still match - some build targets. - - <h4 id="config_setting_notes">Notes</h4> - <ul> - <li>See <a href="/reference/be/functions.html#select">select</a> for what happens when multiple - <code>config_setting</code>s match the current configuration state. - </li> - - <li>For flags that support shorthand forms (e.g. <code>--compilation_mode</code> vs. - <code>-c</code>), <code>values</code> definitions must use the full form. These automatically - match invocations using either form. - </li> - - <li> - If a flag takes multiple values (like <code>--copt=-Da --copt=-Db</code> or a list-typed - <a href="https://bazel.build/rules/config#user-defined-build-settings"> - Starlark flag</a>), <code>values = { "flag": "a" }</code> matches if <code>"a"</code> is - present <i>anywhere</i> in the actual list. - - <p> - <code>values = { "myflag": "a,b" }</code> works the same way: this matches - <code>--myflag=a --myflag=b</code>, <code>--myflag=a --myflag=b --myflag=c</code>, - <code>--myflag=a,b</code>, and <code>--myflag=c,b,a</code>. Exact semantics vary between - flags. For example, <code>--copt</code> doesn't support multiple values <i>in the same - instance</i>: <code>--copt=a,b</code> produces <code>["a,b"]</code> while <code>--copt=a - --copt=b</code> produces <code>["a", "b"]</code> (so <code>values = { "copt": "a,b" }</code> - matches the former but not the latter). But <code>--ios_multi_cpus</code> (for Apple rules) - <i>does</i>: <code>-ios_multi_cpus=a,b</code> and <code>ios_multi_cpus=a --ios_multi_cpus=b - </code> both produce <code>["a", "b"]</code>. Check flag definitions and test your - conditions carefully to verify exact expectations. - </p> - </li> - - <li>If you need to define conditions that aren't modeled by built-in build flags, use - <a href="https://bazel.build/rules/config#user-defined-build-settings"> - Starlark-defined flags</a>. You can also use <code>--define</code>, but this offers weaker - support and is not recommended. See - <a href="/reference/be/common-definitions#configurable-attributes">here</a> for more discussion. - </li> - - <li>Avoid repeating identical <code>config_setting</code> definitions in different packages. - Instead, reference a common <code>config_setting</code> that defined in a canonical package. - </li> - - <li><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 <code>config_setting</code> but at least one must - be set for any given <code>config_setting</code>. - </li> - </ul> - - - <h3 id="config_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="config_setting.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="config_setting.constraint_values"> - <code>constraint_values</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> - 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://bazel.build/docs/configurable-attributes#platforms"> - Configurable Build Attributes</a> for details. - - <p>If two <code>config_setting</code>s match in the same <code>select</code> and one has - all the same flags and <code>constraint_setting</code>s as the other plus additional ones, - the one with more settings is chosen. This is known as "specialization". For example, - a <code>config_setting</code> matching <code>x86</code> and <code>Linux</code> specializes - a <code>config_setting</code> matching <code>x86</code>. - - <p>If two <code>config_setting</code>s match and both have <code>constraint_value</code>s - not present in the other, this is an error. - - </td> - </tr> - <tr> - <td id="config_setting.define_values"> - <code>define_values</code> - </td> - <td> - <p>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> - The same as <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> but - specifically for the <code>--define</code> flag. - - <p><code>--define</code> is special because its syntax (<code>--define KEY=VAL</code>) - means <code>KEY=VAL</code> is a <i>value</i> from a Bazel flag perspective. - </p> - - <p>That means: - - <pre class="code"> + +``` + +In all these cases, it's possible for the configuration to change within the build, for example if +a target needs to be built for a different platform than its dep. This means that even when a +`config_setting` doesn't match the top-level command-line flags, it may still match +some build targets. + +#### Notes + +- See [select](/reference/be/functions.html#select) for what happens when multiple + `config_setting`s match the current configuration state. + +- For flags that support shorthand forms (e.g. `--compilation_mode` vs. + `-c`), `values` definitions must use the full form. These automatically + match invocations using either form. + +- If a flag takes multiple values (like `--copt=-Da --copt=-Db` or a list-typed + [Starlark flag](https://bazel.build/rules/config#user-defined-build-settings)), `values = { "flag": "a" }` matches if `"a"` is + present *anywhere* in the actual list. + + `values = { "myflag": "a,b" }` works the same way: this matches + `--myflag=a --myflag=b`, `--myflag=a --myflag=b --myflag=c`, + `--myflag=a,b`, and `--myflag=c,b,a`. Exact semantics vary between + flags. For example, `--copt` doesn't support multiple values *in the same + instance*: `--copt=a,b` produces `["a,b"]` while `--copt=a --copt=b` produces `["a", "b"]` (so `values = { "copt": "a,b" }` + matches the former but not the latter). But `--ios_multi_cpus` (for Apple rules) + *does*: `-ios_multi_cpus=a,b` and `ios_multi_cpus=a --ios_multi_cpus=b ` both produce `["a", "b"]`. Check flag definitions and test your + conditions carefully to verify exact expectations. + +- If you need to define conditions that aren't modeled by built-in build flags, use + [Starlark-defined flags](https://bazel.build/rules/config#user-defined-build-settings). You can also use `--define`, but this offers weaker + support and is not recommended. See + [here](/reference/be/common-definitions#configurable-attributes) for more discussion. + +- Avoid repeating identical `config_setting` definitions in different packages. + Instead, reference a common `config_setting` that defined in a canonical package. + +- [`values`](general.html#config_setting.values), + [`define_values`](general.html#config_setting.define_values), and + [`constraint_values`](general.html#config_setting.constraint_values) + can be used in any combination in the same `config_setting` but at least one must + be set for any given `config_setting`. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="config_setting.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="config_setting.constraint_values"><code>constraint_values</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +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://bazel.build/docs/configurable-attributes#platforms">Configurable Build Attributes</a> for details. +<p>If two <code>config_setting</code>s match in the same <code>select</code> and one has +all the same flags and <code>constraint_setting</code>s as the other plus additional ones, +the one with more settings is chosen. This is known as "specialization". For example, +a <code>config_setting</code> matching <code>x86</code> and <code>Linux</code> specializes +a <code>config_setting</code> matching <code>x86</code>.</p> +<p>If two <code>config_setting</code>s match and both have <code>constraint_value</code>s +not present in the other, this is an error.</p></td> +</tr> +<tr> +<td id="config_setting.define_values"><code>define_values</code></td> +<td><p>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> +The same as <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> but +specifically for the <code>--define</code> flag. +<p><code>--define</code> is special because its syntax (<code>--define KEY=VAL</code>) +means <code>KEY=VAL</code> is a <em>value</em> from a Bazel flag perspective.</p> +<p>That means:</p> +<pre class="code"><code> config_setting( - name = "a_and_b", + name = "a_and_b", values = { - "define": "a=1", - "define": "b=2", + "define": "a=1", + "define": "b=2", }) - </pre> - - <p>doesn't work because the same key (<code>define</code>) appears twice in the - dictionary. This attribute solves that problem: - - <pre class="code"> + </code></pre> +<p>doesn't work because the same key (<code>define</code>) appears twice in the +dictionary. This attribute solves that problem:</p> +<pre class="code"><code> config_setting( - name = "a_and_b", + name = "a_and_b", define_values = { - "a": "1", - "b": "2", + "a": "1", + "b": "2", }) - </pre> - - <p>correctly matches <code>bazel build //foo --define a=1 --define b=2</code>. - - <p><code>--define</code> can still appear in - <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> with normal flag syntax, - and can be mixed freely with this attribute as long as dictionary keys remain distinct. - - </td> - </tr> - <tr> - <td id="config_setting.flag_values"> - <code>flag_values</code> - </td> - <td> - <p>Dictionary: <a href="/concepts/labels">label</a> -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> - The same as <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> but - for <a href="https://bazel.build/rules/config#user-defined-build-settings"> - user-defined build flags</a>. - - <p>This is a distinct attribute because user-defined flags are referenced as labels while - built-in flags are referenced as arbitrary strings. - - - </td> - </tr> - <tr> - <td id="config_setting.values"> - <code>values</code> - </td> - <td> - <p>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> - The set of configuration values that match this rule (expressed as build flags) - - <p>This rule inherits the configuration of the configured target that - references it in a <code>select</code> statement. It is considered to - "match" a Bazel invocation if, for every entry in the dictionary, its - configuration matches the entry's expected value. For example - <code>values = {"compilation_mode": "opt"}</code> matches the invocations - <code>bazel build --compilation_mode=opt ...</code> and - <code>bazel build -c opt ...</code> on target-configured rules. - </p> - - <p>For convenience's sake, configuration values are specified as build flags (without - the preceding <code>"--"</code>). But keep in mind that the two are not the same. This - is because targets can be built in multiple configurations within the same - build. For example, an exec configuration's "cpu" matches the value of - <code>--host_cpu</code>, not <code>--cpu</code>. So different instances of the - same <code>config_setting</code> may match the same invocation differently - depending on the configuration of the rule using them. - </p> - - <p>If a flag is not explicitly set at the command line, its default value is used. - If a key appears multiple times in the dictionary, only the last instance is used. - If a key references a flag that can be set multiple times on the command line (e.g. - <code>bazel build --copt=foo --copt=bar --copt=baz ...</code>), a match occurs if - <i>any</i> of those settings match. - <p> - - </td> - </tr> - </tbody> - </table> - <h2 id="filegroup"> - filegroup - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/filegroup/FilegroupRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">filegroup(<a href="#filegroup.name">name</a>, <a href="#filegroup.srcs">srcs</a>, <a href="#filegroup.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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#typical.licenses">licenses</a>, <a href="#filegroup.output_group">output_group</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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> - Use <code>filegroup</code> to gather the outputs of a set of targets under a single - label. -</p> - -<p> - <code>filegroup</code> is not a substitute for listing targets on the command line or - in an attribute of another rule, because targets have many properties other than their - outputs, which are not collected in the same way. However, it's still useful in quite - a few cases, for example, in the <code>srcs</code> attribute of a genrule, or - the <code>data</code> attribute of a *_binary rule. -</p> - -<p> - Using <code>filegroup</code> is encouraged instead of referencing directories directly. - Directly referencing directories is discouraged because the build system does not have - full knowledge of all files below the directory, so it may not rebuild when these files change. - When combined with <a href="/reference/be/functions.html#glob">glob</a>, <code>filegroup</code> can ensure that all - files are explicitly known to the build system. -</p> - -<h4 id="filegroup_example">Examples</h4> - -<p> - To create a <code>filegroup</code> consisting of two source files, do -</p> -<pre class="code"> + </code></pre> +<p>correctly matches <code>bazel build //foo --define a=1 --define b=2</code>.</p> +<p><code>--define</code> can still appear in +<a href="/reference/be/general.html#config_setting.values"><code>values</code></a> with normal flag syntax, +and can be mixed freely with this attribute as long as dictionary keys remain distinct.</p></td> +</tr> +<tr> +<td id="config_setting.flag_values"><code>flag_values</code></td> +<td><p>Dictionary: <a href="/concepts/labels">label</a> -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> +The same as <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> but +for +<a href="https://bazel.build/rules/config#user-defined-build-settings">user-defined build flags</a>. +<p>This is a distinct attribute because user-defined flags are referenced as labels while +built-in flags are referenced as arbitrary strings.</p></td> +</tr> +<tr> +<td id="config_setting.values"><code>values</code></td> +<td><p>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> +The set of configuration values that match this rule (expressed as build flags) +<p>This rule inherits the configuration of the configured target that +references it in a <code>select</code> statement. It is considered to +"match" a Bazel invocation if, for every entry in the dictionary, its +configuration matches the entry's expected value. For example +<code>values = {"compilation_mode": "opt"}</code> matches the invocations +<code>bazel build --compilation_mode=opt ...</code> and +<code>bazel build -c opt ...</code> on target-configured rules.</p> +<p>For convenience's sake, configuration values are specified as build flags (without +the preceding <code>"--"</code>). But keep in mind that the two are not the same. This +is because targets can be built in multiple configurations within the same +build. For example, an exec configuration's "cpu" matches the value of +<code>--host_cpu</code>, not <code>--cpu</code>. So different instances of the +same <code>config_setting</code> may match the same invocation differently +depending on the configuration of the rule using them.</p> +<p>If a flag is not explicitly set at the command line, its default value is used. +If a key appears multiple times in the dictionary, only the last instance is used. +If a key references a flag that can be set multiple times on the command line (e.g. +<code>bazel build --copt=foo --copt=bar --copt=baz ...</code>), a match occurs if +<em>any</em> of those settings match.</p></td> +</tr> +</tbody> +</table> + +## filegroup + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/filegroup/FilegroupRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +filegroup(name, srcs, data, aspect_hints, compatible_with, deprecation, features, licenses, output_group, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) +``` + +Use `filegroup` to gather the outputs of a set of targets under a single +label. + +`filegroup` is not a substitute for listing targets on the command line or +in an attribute of another rule, because targets have many properties other than their +outputs, which are not collected in the same way. However, it's still useful in quite +a few cases, for example, in the `srcs` attribute of a genrule, or +the `data` attribute of a \*\_binary rule. + +Using `filegroup` is encouraged instead of referencing directories directly. +Directly referencing directories is discouraged because the build system does not have +full knowledge of all files below the directory, so it may not rebuild when these files change. +When combined with [glob](/reference/be/functions.html#glob), `filegroup` can ensure that all +files are explicitly known to the build system. + +#### Examples + +To create a `filegroup` consisting of two source files, do + +``` code + filegroup( name = "mygroup", srcs = [ @@ -467,23 +332,25 @@ filegroup( "//a/binary:target", ], ) -</pre> -<p> - Or, use a <code>glob</code> to fully crawl a testdata directory: -</p> -<pre class="code"> +``` + +Or, use a `glob` to fully crawl a testdata directory: + +``` code + filegroup( name = "exported_testdata", srcs = glob([ "testdata/*.dat", - "testdata/logs/**/*.log", + "testdata/logs/**/*.log", ]), ) -</pre> -<p> - To make use of these definitions, reference the <code>filegroup</code> with a label from any rule: -</p> -<pre class="code"> +``` + +To make use of these definitions, reference the `filegroup` with a label from any rule: + +``` code + cc_library( name = "my_library", srcs = ["foo.cc"], @@ -492,924 +359,635 @@ cc_library( "//my_package:mygroup", ], ) -</pre> - - - - <h3 id="filegroup_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="filegroup.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="filegroup.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of targets that are members of the file group. - <p> - It is common to use the result of a <a href="/reference/be/functions.html#glob">glob</a> expression for - the value of the <code>srcs</code> attribute. - </p> - - </td> - </tr> - <tr> - <td id="filegroup.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this rule at runtime. - <p> - Targets named in the <code>data</code> attribute will be added to the - <code>runfiles</code> of this <code>filegroup</code> rule. When the - <code>filegroup</code> is referenced in the <code>data</code> attribute of - another rule its <code>runfiles</code> will be added to the <code>runfiles</code> - of the depending rule. See the <a href="/concepts/dependencies#data-dependencies">data dependencies</a> - section and <a href="/reference/be/common-definitions#common.data">general documentation of - <code>data</code></a> for more information about how to depend on and use data files. - </p> - - </td> - </tr> - <tr> - <td id="filegroup.output_group"> - <code>output_group</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The output group from which to gather artifacts from sources. If this attribute is - specified, artifacts from the specified output group of the dependencies will be exported - instead of the default output group. - <p>An "output group" is a category of output artifacts of a target, specified in that - rule's implementation. - </p> - - </td> - </tr> - </tbody> - </table> - <h2 id="genquery"> - genquery - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">genquery(<a href="#genquery.name">name</a>, <a href="common-definitions.html#typical.deps">deps</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#genquery.compressed_output">compressed_output</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#genquery.expression">expression</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#genquery.opts">opts</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#genquery.scope">scope</a>, <a href="#genquery.strict">strict</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> - <code>genquery()</code> runs a query specified in the - <a href="/reference/query">Bazel query language</a> and dumps the result - into a file. - </p> - <p> - In order to keep the build consistent, the query is allowed only to visit - the transitive closure of the targets specified in the <code>scope</code> - attribute. Queries violating this rule will fail during execution if - <code>strict</code> is unspecified or true (if <code>strict</code> is false, - the out of scope targets will simply be skipped with a warning). The - easiest way to make sure this does not happen is to mention the same labels - in the scope as in the query expression. - </p> - <p> - The only difference between the queries allowed here and on the command - line is that queries containing wildcard target specifications (e.g. - <code>//pkg:*</code> or <code>//pkg:all</code>) are not allowed here. - The reasons for this are two-fold: first, because <code>genquery</code> has - to specify a scope to prevent targets outside the transitive closure of the - query to influence its output; and, second, because <code>BUILD</code> files - do not support wildcard dependencies (e.g. <code>deps=["//a/..."]</code> - is not allowed). - </p> - <p> - The genquery's output is ordered lexicographically in order to enforce deterministic output, - with the exception of <code>--output=graph|minrank|maxrank</code> or when <code>somepath</code> - is used as the top-level function. - <p> - The name of the output file is the name of the rule. - </p> - -<h4 id="genquery_examples">Examples</h4> - <p> - This example writes the list of the labels in the transitive closure of the - specified target to a file. - </p> - -<pre class="code"> +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="filegroup.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="filegroup.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of targets that are members of the file group. +<p>It is common to use the result of a <a href="/reference/be/functions.html#glob">glob</a> expression for +the value of the <code>srcs</code> attribute.</p></td> +</tr> +<tr> +<td id="filegroup.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this rule at runtime. +<p>Targets named in the <code>data</code> attribute will be added to the +<code>runfiles</code> of this <code>filegroup</code> rule. When the +<code>filegroup</code> is referenced in the <code>data</code> attribute of +another rule its <code>runfiles</code> will be added to the <code>runfiles</code> +of the depending rule. See the <a href="/concepts/dependencies#data-dependencies">data dependencies</a> +section and <a href="/reference/be/common-definitions#common.data">general documentation of +<code>data</code></a> for more information about how to depend on and use data files.</p></td> +</tr> +<tr> +<td id="filegroup.output_group"><code>output_group</code></td> +<td><p>String; default is <code>""</code></p> +The output group from which to gather artifacts from sources. If this attribute is +specified, artifacts from the specified output group of the dependencies will be exported +instead of the default output group. +<p>An "output group" is a category of output artifacts of a target, specified in that +rule's implementation.</p></td> +</tr> +</tbody> +</table> + +## genquery + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +genquery(name, deps, data, aspect_hints, compatible_with, compressed_output, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, expression, features, licenses, opts, package_metadata, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility) +``` + +`genquery()` runs a query specified in the +[Bazel query language](/reference/query) and dumps the result +into a file. + +In order to keep the build consistent, the query is allowed only to visit +the transitive closure of the targets specified in the `scope` +attribute. Queries violating this rule will fail during execution if +`strict` is unspecified or true (if `strict` is false, +the out of scope targets will simply be skipped with a warning). The +easiest way to make sure this does not happen is to mention the same labels +in the scope as in the query expression. + +The only difference between the queries allowed here and on the command +line is that queries containing wildcard target specifications (e.g. +`//pkg:*` or `//pkg:all`) are not allowed here. +The reasons for this are two-fold: first, because `genquery` has +to specify a scope to prevent targets outside the transitive closure of the +query to influence its output; and, second, because `BUILD` files +do not support wildcard dependencies (e.g. `deps=["//a/..."]` +is not allowed). + +The genquery's output is ordered lexicographically in order to enforce deterministic output, +with the exception of `--output=graph|minrank|maxrank` or when `somepath` +is used as the top-level function. + +The name of the output file is the name of the rule. + +#### Examples + +This example writes the list of the labels in the transitive closure of the +specified target to a file. + +``` code + genquery( name = "kiwi-deps", expression = "deps(//kiwi:kiwi_lib)", scope = ["//kiwi:kiwi_lib"], ) -</pre> - - - - <h3 id="genquery_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="genquery.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="genquery.compressed_output"> - <code>compressed_output</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - If <code>True</code>, query output is written in GZIP file format. This setting can be used - to avoid spikes in Bazel's memory use when the query output is expected to be large. Bazel - already internally compresses query outputs greater than 2<sup>20</sup> bytes regardless of - the value of this setting, so setting this to <code>True</code> may not reduce retained - heap. However, it allows Bazel to skip <em>decompression</em> when writing the output file, - which can be memory-intensive. - - </td> - </tr> - <tr> - <td id="genquery.expression"> - <code>expression</code> - </td> - <td> - <p>String; required</p> - The query to be executed. In contrast to the command line and other places in BUILD files, - labels here are resolved relative to the root directory of the workspace. For example, the - label <code>:b</code> in this attribute in the file <code>a/BUILD</code> will refer to the - target <code>//:b</code>. - - </td> - </tr> - <tr> - <td id="genquery.opts"> - <code>opts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - The options that are passed to the query engine. These correspond to the command line - options that can be passed to <code>bazel query</code>. Some query options are not allowed - here: <code>--keep_going</code>, <code>--query_file</code>, <code>--universe_scope</code>, - <code>--order_results</code> and <code>--order_output</code>. Options not specified here - will have their default values just like on the command line of <code>bazel query</code>. - - </td> - </tr> - <tr> - <td id="genquery.scope"> - <code>scope</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; required</p> - The scope of the query. The query is not allowed to touch targets outside the transitive - closure of these targets. - - </td> - </tr> - <tr> - <td id="genquery.strict"> - <code>strict</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - If true, targets whose queries escape the transitive closure of their scopes will fail to - build. If false, Bazel will print a warning and skip whatever query path led it outside of - the scope, while completing the rest of the query. - - </td> - </tr> - </tbody> - </table> - <h2 id="genrule"> - genrule - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">genrule(<a href="#genrule.name">name</a>, <a href="#genrule.srcs">srcs</a>, <a href="#genrule.outs">outs</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#genrule.cmd">cmd</a>, <a href="#genrule.cmd_bash">cmd_bash</a>, <a href="#genrule.cmd_bat">cmd_bat</a>, <a href="#genrule.cmd_ps">cmd_ps</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#genrule.executable">executable</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#genrule.local">local</a>, <a href="#genrule.message">message</a>, <a href="#genrule.output_licenses">output_licenses</a>, <a href="#genrule.output_to_bindir">output_to_bindir</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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="#genrule.toolchains">toolchains</a>, <a href="#genrule.tools">tools</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - -<p>A <code>genrule</code> generates one or more files using a user-defined Bash command.</p> - -<p> - Genrules are generic build rules that you can use if there's no specific rule for the task. - For example, you could run a Bash one-liner. If however you need to compile C++ files, stick - to the existing <code>cc_*</code> rules, because all the heavy lifting has already been done - for you. -</p> -<p> - Note that genrule requires a shell to interpret the command argument. - It is also easy to reference arbitrary programs available on the PATH, however this makes the - command non-hermetic and may not be reproducible. - If you only need to run a single tool, consider using - <a href="https://github.com/bazelbuild/bazel-skylib/blob/main/docs/run_binary_doc.md">run_binary</a> - instead. -</p> -<p> - Like every other action, the action created by genrules should not assume anything about their - working directory; all Bazel guarantees is that their declared inputs will be available at the - path that <code>$(location)</code> returns for their label. For example, if the action is run in a - sandbox or remotely, the implementation of the sandbox or the remote execution will determine the - working directory. If run directly (using the <code>standalone</code> strategy), the working - directory will be the execution root, i.e. the result of <code>bazel info execution_root</code>. -</p> -<p> - Do not use a genrule for running tests. There are special dispensations for tests and test - results, including caching policies and environment variables. Tests generally need to be run - after the build is complete and on the target architecture, whereas genrules are executed during - the build and on the exec architecture (the two may be different). If you need a general purpose - testing rule, use <a href="/reference/be/shell.html#sh_test"><code>sh_test</code></a>. -</p> - -<h4>Cross-compilation Considerations</h4> - -<p> - <em>See <a href="/docs/user-manual#configurations">the user manual</a> for more info about - cross-compilation.</em> -</p> -<p> - While genrules run during a build, their outputs are often used after the build, for deployment or - testing. Consider the example of compiling C code for a microcontroller: the compiler accepts C - source files and generates code that runs on a microcontroller. The generated code obviously - cannot run on the CPU that was used for building it, but the C compiler (if compiled from source) - itself has to. -</p> -<p> - The build system uses the exec configuration to describe the machine(s) on which the build runs - and the target configuration to describe the machine(s) on which the output of the build is - supposed to run. It provides options to configure each of these and it segregates the - corresponding files into separate directories to avoid conflicts. -</p> -<p> - For genrules, the build system ensures that dependencies are built appropriately: - <code>srcs</code> are built (if necessary) for the <em>target</em> configuration, - <code>tools</code> are built for the <em>exec</em> configuration, and the output is considered to - be for the <em>target</em> configuration. It also provides <a href="/reference/be/make-variables"> - "Make" variables</a> that genrule commands can pass to the corresponding tools. -</p> -<p> - It is intentional that genrule defines no <code>deps</code> attribute: other built-in rules use - language-dependent meta information passed between the rules to automatically determine how to - handle dependent rules, but this level of automation is not possible for genrules. Genrules work - purely at the file and runfiles level. -</p> - -<h4>Special Cases</h4> - -<p> - <i>Exec-exec compilation</i>: in some cases, the build system needs to run genrules such that the - output can also be executed during the build. If for example a genrule builds some custom compiler - which is subsequently used by another genrule, the first one has to produce its output for the - exec configuration, because that's where the compiler will run in the other genrule. In this case, - the build system does the right thing automatically: it builds the <code>srcs</code> and - <code>outs</code> of the first genrule for the exec configuration instead of the target - configuration. See <a href="/docs/user-manual#configurations">the user manual</a> for more - info. -</p> -<p> - <i>JDK & C++ Tooling</i>: to use a tool from the JDK or the C++ compiler suite, the build system - provides a set of variables to use. See <a href="/reference/be/make-variables">"Make" variable</a> for - details. -</p> - -<h4>Genrule Environment</h4> - -<p> - The genrule command is executed by a Bash shell that is configured to fail when a command - or a pipeline fails, using <code>set -e -o pipefail</code>. -</p> -<p> - The build tool executes the Bash command in a sanitized process environment that - defines only core variables such as <code>PATH</code>, <code>PWD</code>, - <code>TMPDIR</code>, and a few others. - - To ensure that builds are reproducible, most variables defined in the user's shell - environment are not passed though to the genrule's command. However, Bazel (but not - Blaze) passes through the value of the user's <code>PATH</code> environment variable. - - Any change to the value of <code>PATH</code> will cause Bazel to re-execute the command - on the next build. - <!-- See https://github.com/bazelbuild/bazel/issues/1142 --> -</p> -<p> - A genrule command should not access the network except to connect processes that are - children of the command itself, though this is not currently enforced. -</p> -<p> - The build system automatically deletes any existing output files, but creates any necessary parent - directories before it runs a genrule. It also removes any output files in case of a failure. -</p> - -<h4>General Advice</h4> - -<ul> - <li>Do ensure that tools run by a genrule are deterministic and hermetic. They should not write - timestamps to their output, and they should use stable ordering for sets and maps, as well as - write only relative file paths to the output, no absolute paths. Not following this rule will - lead to unexpected build behavior (Bazel not rebuilding a genrule you thought it would) and - degrade cache performance.</li> - <li>Do use <code>$(location)</code> extensively, for outputs, tools and sources. Due to the - segregation of output files for different configurations, genrules cannot rely on hard-coded - and/or absolute paths.</li> - <li>Do write a common Starlark macro in case the same or very similar genrules are used in - multiple places. If the genrule is complex, consider implementing it in a script or as a - Starlark rule. This improves readability as well as testability.</li> - <li>Do make sure that the exit code correctly indicates success or failure of the genrule.</li> - <li>Do not write informational messages to stdout or stderr. While useful for debugging, this can - easily become noise; a successful genrule should be silent. On the other hand, a failing genrule - should emit good error messages.</li> - <li><code>$$</code> evaluates to a <code>$</code>, a literal dollar-sign, so in order to invoke a - shell command containing dollar-signs such as <code>ls $(dirname $x)</code>, one must escape it - thus: <code>ls $$(dirname $$x)</code>.</li> - <li>Avoid creating symlinks and directories. Bazel doesn't copy over the directory/symlink - structure created by genrules and its dependency checking of directories is unsound.</li> - <li>When referencing the genrule in other rules, you can use either the genrule's label or the - labels of individual output files. Sometimes the one approach is more readable, sometimes the - other: referencing outputs by name in a consuming rule's <code>srcs</code> will avoid - unintentionally picking up other outputs of the genrule, but can be tedious if the genrule - produces many outputs.</li> -</ul> - -<h4 id="genrule_examples">Examples</h4> +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="genquery.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="genquery.compressed_output"><code>compressed_output</code></td> +<td><p>Boolean; default is <code>False</code></p> +If <code>True</code>, query output is written in GZIP file format. This setting can be used +to avoid spikes in Bazel's memory use when the query output is expected to be large. Bazel +already internally compresses query outputs greater than 2<sup>20</sup> bytes regardless of +the value of this setting, so setting this to <code>True</code> may not reduce retained +heap. However, it allows Bazel to skip <em>decompression</em> when writing the output file, +which can be memory-intensive.</td> +</tr> +<tr> +<td id="genquery.expression"><code>expression</code></td> +<td><p>String; required</p> +The query to be executed. In contrast to the command line and other places in BUILD files, +labels here are resolved relative to the root directory of the workspace. For example, the +label <code>:b</code> in this attribute in the file <code>a/BUILD</code> will refer to the +target <code>//:b</code>.</td> +</tr> +<tr> +<td id="genquery.opts"><code>opts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +The options that are passed to the query engine. These correspond to the command line +options that can be passed to <code>bazel query</code>. Some query options are not allowed +here: <code>--keep_going</code>, <code>--query_file</code>, <code>--universe_scope</code>, +<code>--order_results</code> and <code>--order_output</code>. Options not specified here +will have their default values just like on the command line of <code>bazel query</code>.</td> +</tr> +<tr> +<td id="genquery.scope"><code>scope</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; required</p> +The scope of the query. The query is not allowed to touch targets outside the transitive +closure of these targets.</td> +</tr> +<tr> +<td id="genquery.strict"><code>strict</code></td> +<td><p>Boolean; default is <code>True</code></p> +If true, targets whose queries escape the transitive closure of their scopes will fail to +build. If false, Bazel will print a warning and skip whatever query path led it outside of +the scope, while completing the rest of the query.</td> +</tr> +</tbody> +</table> + +## genrule + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +genrule(name, srcs, outs, aspect_hints, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility) +``` + +A `genrule` generates one or more files using a user-defined Bash command. + +Genrules are generic build rules that you can use if there's no specific rule for the task. +For example, you could run a Bash one-liner. If however you need to compile C++ files, stick +to the existing `cc_*` rules, because all the heavy lifting has already been done +for you. + +Note that genrule requires a shell to interpret the command argument. +It is also easy to reference arbitrary programs available on the PATH, however this makes the +command non-hermetic and may not be reproducible. +If you only need to run a single tool, consider using +[run_binary](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/run_binary_doc.md) +instead. + +Like every other action, the action created by genrules should not assume anything about their +working directory; all Bazel guarantees is that their declared inputs will be available at the +path that `$(location)` returns for their label. For example, if the action is run in a +sandbox or remotely, the implementation of the sandbox or the remote execution will determine the +working directory. If run directly (using the `standalone` strategy), the working +directory will be the execution root, i.e. the result of `bazel info execution_root`. + +Do not use a genrule for running tests. There are special dispensations for tests and test +results, including caching policies and environment variables. Tests generally need to be run +after the build is complete and on the target architecture, whereas genrules are executed during +the build and on the exec architecture (the two may be different). If you need a general purpose +testing rule, use [`sh_test`](/reference/be/shell.html#sh_test). + +#### Cross-compilation Considerations + +*See [the user manual](/docs/user-manual#configurations) for more info about +cross-compilation.* + +While genrules run during a build, their outputs are often used after the build, for deployment or +testing. Consider the example of compiling C code for a microcontroller: the compiler accepts C +source files and generates code that runs on a microcontroller. The generated code obviously +cannot run on the CPU that was used for building it, but the C compiler (if compiled from source) +itself has to. + +The build system uses the exec configuration to describe the machine(s) on which the build runs +and the target configuration to describe the machine(s) on which the output of the build is +supposed to run. It provides options to configure each of these and it segregates the +corresponding files into separate directories to avoid conflicts. + +For genrules, the build system ensures that dependencies are built appropriately: +`srcs` are built (if necessary) for the *target* configuration, +`tools` are built for the *exec* configuration, and the output is considered to +be for the *target* configuration. It also provides +["Make" variables](/reference/be/make-variables) that genrule commands can pass to the corresponding tools. + +It is intentional that genrule defines no `deps` attribute: other built-in rules use +language-dependent meta information passed between the rules to automatically determine how to +handle dependent rules, but this level of automation is not possible for genrules. Genrules work +purely at the file and runfiles level. + +#### Special Cases + +*Exec-exec compilation*: in some cases, the build system needs to run genrules such that the +output can also be executed during the build. If for example a genrule builds some custom compiler +which is subsequently used by another genrule, the first one has to produce its output for the +exec configuration, because that's where the compiler will run in the other genrule. In this case, +the build system does the right thing automatically: it builds the `srcs` and +`outs` of the first genrule for the exec configuration instead of the target +configuration. See [the user manual](/docs/user-manual#configurations) for more +info. + +*JDK & C++ Tooling*: to use a tool from the JDK or the C++ compiler suite, the build system +provides a set of variables to use. See ["Make" variable](/reference/be/make-variables) for +details. + +#### Genrule Environment + +The genrule command is executed by a Bash shell that is configured to fail when a command +or a pipeline fails, using `set -e -o pipefail`. + +The build tool executes the Bash command in a sanitized process environment that +defines only core variables such as `PATH`, `PWD`, +`TMPDIR`, and a few others. +To ensure that builds are reproducible, most variables defined in the user's shell +environment are not passed though to the genrule's command. However, Bazel (but not +Blaze) passes through the value of the user's `PATH` environment variable. +Any change to the value of `PATH` will cause Bazel to re-execute the command +on the next build. + +A genrule command should not access the network except to connect processes that are +children of the command itself, though this is not currently enforced. + +The build system automatically deletes any existing output files, but creates any necessary parent +directories before it runs a genrule. It also removes any output files in case of a failure. + +#### General Advice + +- Do ensure that tools run by a genrule are deterministic and hermetic. They should not write + timestamps to their output, and they should use stable ordering for sets and maps, as well as + write only relative file paths to the output, no absolute paths. Not following this rule will + lead to unexpected build behavior (Bazel not rebuilding a genrule you thought it would) and + degrade cache performance. +- Do use `$(location)` extensively, for outputs, tools and sources. Due to the + segregation of output files for different configurations, genrules cannot rely on hard-coded + and/or absolute paths. +- Do write a common Starlark macro in case the same or very similar genrules are used in + multiple places. If the genrule is complex, consider implementing it in a script or as a + Starlark rule. This improves readability as well as testability. +- Do make sure that the exit code correctly indicates success or failure of the genrule. +- Do not write informational messages to stdout or stderr. While useful for debugging, this can + easily become noise; a successful genrule should be silent. On the other hand, a failing genrule + should emit good error messages. +- `$$` evaluates to a `$`, a literal dollar-sign, so in order to invoke a + shell command containing dollar-signs such as `ls $(dirname $x)`, one must escape it + thus: `ls $$(dirname $$x)`. +- Avoid creating symlinks and directories. Bazel doesn't copy over the directory/symlink + structure created by genrules and its dependency checking of directories is unsound. +- When referencing the genrule in other rules, you can use either the genrule's label or the + labels of individual output files. Sometimes the one approach is more readable, sometimes the + other: referencing outputs by name in a consuming rule's `srcs` will avoid + unintentionally picking up other outputs of the genrule, but can be tedious if the genrule + produces many outputs. + +#### Examples + +This example generates `foo.h`. There are no sources, because the command doesn't take +any input. The "binary" run by the command is a perl script in the same package as the genrule. + +``` code -<p> - This example generates <code>foo.h</code>. There are no sources, because the command doesn't take - any input. The "binary" run by the command is a perl script in the same package as the genrule. -</p> -<pre class="code"> genrule( name = "foo", srcs = [], outs = ["foo.h"], - cmd = "./$(location create_foo.pl) > \"$@\"", + cmd = "./$(location create_foo.pl) > \"$@\"", tools = ["create_foo.pl"], ) -</pre> - -<p> - The following example shows how to use a <a href="/reference/be/general.html#filegroup"><code>filegroup</code> - </a> and the outputs of another <code>genrule</code>. Note that using <code>$(SRCS)</code> instead - of explicit <code>$(location)</code> directives would also work; this example uses the latter for - sake of demonstration. -</p> -<pre class="code"> +``` + +The following example shows how to use a [`filegroup`](/reference/be/general.html#filegroup) +and the outputs of another `genrule`. Note that using `$(SRCS)` instead +of explicit `$(location)` directives would also work; this example uses the latter for +sake of demonstration. + +``` code + genrule( name = "concat_all_files", srcs = [ - "//some:files", # a filegroup with multiple files in it ==> $(location<b>s</b>) + "//some:files", # a filegroup with multiple files in it ==> $(locations) "//other:gen", # a genrule with a single output ==> $(location) ], outs = ["concatenated.txt"], cmd = "cat $(locations //some:files) $(location //other:gen) > $@", ) -</pre> - - - - <h3 id="genrule_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="genrule.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - <br/>You may refer to this rule by name in the - <code>srcs</code> or <code>deps</code> section of other <code>BUILD</code> - rules. If the rule generates source files, you should use the - <code>srcs</code> attribute. - - </td> - </tr> - <tr> - <td id="genrule.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of inputs for this rule, such as source files to process. - <p> - <em>This attributes is not suitable to list tools executed by the <code>cmd</code>; use - the <a href="/reference/be/general.html#genrule.tools"><code>tools</code></a> attribute for them instead. - </em> - </p> - <p> - The build system ensures these prerequisites are built before running the genrule - command; they are built using the same configuration as the original build request. The - names of the files of these prerequisites are available to the command as a - space-separated list in <code>$(SRCS)</code>; alternatively the path of an individual - <code>srcs</code> target <code>//x:y</code> can be obtained using <code>$(location - //x:y)</code>, or using <code>$<</code> provided it's the only entry in - <code>srcs</code>. - </p> - - </td> - </tr> - <tr> - <td id="genrule.outs"> - <code>outs</code> - </td> - <td> - <p>List of <a href="/concepts/build-ref#filename">filenames</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; required</p> - A list of files generated by this rule. - <p> - Output files must not cross package boundaries. - Output filenames are interpreted as relative to the package. - </p> - <p> - If the <code>executable</code> flag is set, <code>outs</code> must contain exactly one - label. - </p> - <p> - The genrule command is expected to create each output file at a predetermined location. - The location is available in <code>cmd</code> using <a - href="/reference/be/make-variables#predefined_genrule_variables">genrule-specific "Make" - variables</a> (<code>$@</code>, <code>$(OUTS)</code>, <code>$(@D)</code> or <code> - $(RULEDIR)</code>) or using <a href="/reference/be/make-variables#predefined_label_variables"> - <code>$(location)</code></a> substitution. - </p> - - </td> - </tr> - <tr> - <td id="genrule.cmd"> - <code>cmd</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The command to run. - Subject to <a href="/reference/be/make-variables#predefined_label_variables"><code>$(location) - </code></a> and <a href="/reference/be/make-variables">"Make" variable</a> substitution. - <ol> - <li> - First <a href="/reference/be/make-variables#predefined_label_variables"><code>$(location) - </code></a> substitution is applied, replacing all occurrences of <code>$(location <i> - label</i>)</code> and of <code>$(locations <i>label</i>)</code> (and similar - constructions using related variables <code>execpath</code>, <code>execpaths</code>, - <code>rootpath</code> and <code>rootpaths</code>). - </li> - <li> - Next, <a href="/reference/be/make-variables">"Make" variables</a> are expanded. Note that - predefined variables <code>$(JAVA)</code>, <code>$(JAVAC)</code> and - <code>$(JAVABASE)</code> expand under the <i>exec</i> configuration, so Java invocations - that run as part of a build step can correctly load shared libraries and other - dependencies. - </li> - <li> - Finally, the resulting command is executed using the Bash shell. If its exit code is - non-zero the command is considered to have failed. - </li> - </ol> - This is the fallback of <code>cmd_bash</code>, <code>cmd_ps</code> and <code>cmd_bat</code>, - if none of them are applicable. - </p> - <p> - If the command line length exceeds the platform limit (64K on Linux/macOS, 8K on Windows), - then genrule will write the command to a script and execute that script to work around. This - applies to all cmd attributes (<code>cmd</code>, <code>cmd_bash</code>, <code>cmd_ps</code>, - <code>cmd_bat</code>). - </p> - - </td> - </tr> - <tr> - <td id="genrule.cmd_bash"> - <code>cmd_bash</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The Bash command to run. - <p> This attribute has higher priority than <code>cmd</code>. The command is expanded and - runs in the exact same way as the <code>cmd</code> attribute. - </p> - - </td> - </tr> - <tr> - <td id="genrule.cmd_bat"> - <code>cmd_bat</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The Batch command to run on Windows. - <p> This attribute has higher priority than <code>cmd</code> and <code>cmd_bash</code>. - The command runs in the similar way as the <code>cmd</code> attribute, with the - following differences: - </p> - <ul> - <li> - This attribute only applies on Windows. - </li> - <li> - The command runs with <code>cmd.exe /c</code> with the following default arguments: - <ul> - <li> - <code>/S</code> - strip first and last quotes and execute everything else as is. - </li> - <li> - <code>/E:ON</code> - enable extended command set. - </li> - <li> - <code>/V:ON</code> - enable delayed variable expansion - </li> - <li> - <code>/D</code> - ignore AutoRun registry entries. - </li> - </ul> - </li> - <li> - After <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and - <a href="/reference/be/make-variables">"Make" variable</a> substitution, the paths will be - expanded to Windows style paths (with backslash). - </li> - </ul> - - </td> - </tr> - <tr> - <td id="genrule.cmd_ps"> - <code>cmd_ps</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The Powershell command to run on Windows. - <p> This attribute has higher priority than <code>cmd</code>, <code>cmd_bash</code> and - <code>cmd_bat</code>. The command runs in the similar way as the <code>cmd</code> - attribute, with the following differences: - </p> - <ul> - <li> - This attribute only applies on Windows. - </li> - <li> - The command runs with <code>powershell.exe /c</code>. - </li> - </ul> - <p> To make Powershell easier to use and less error-prone, we run the following - commands to set up the environment before executing Powershell command in genrule. - </p> - <ul> - <li> - <code>Set-ExecutionPolicy -Scope CurrentUser RemoteSigned</code> - allow running - unsigned scripts. - </li> - <li> - <code>$errorActionPreference='Stop'</code> - In case there are multiple commands - separated by <code>;</code>, the action exits immediately if a Powershell CmdLet fails, - but this does <strong>NOT</strong> work for external command. - </li> - <li> - <code>$PSDefaultParameterValues['*:Encoding'] = 'utf8'</code> - change the default - encoding from utf-16 to utf-8. - </li> - </ul> - - </td> - </tr> - <tr> - <td id="genrule.executable"> - <code>executable</code> - </td> - <td> - <p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> - Declare output to be executable. - <p> - Setting this flag to True means the output is an executable file and can be run using the - <code>run</code> command. The genrule must produce exactly one output in this case. - If this attribute is set, <code>run</code> will try executing the file regardless of - its content. - </p> - <p>Declaring data dependencies for the generated executable is not supported.</p> - - </td> - </tr> - <tr> - <td id="genrule.local"> - <code>local</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - <p> - If set to True, this option forces this <code>genrule</code> to run using the "local" - strategy, which means no remote execution, no sandboxing, no persistent workers. - </p> - <p> - This is equivalent to providing 'local' as a tag (<code>tags=["local"]</code>). - </p> - - </td> - </tr> - <tr> - <td id="genrule.message"> - <code>message</code> - </td> - <td> - <p>String; default is <code>""</code></p> - A progress message. - <p> - A progress message that will be printed as this build step is executed. By default, the - message is "Generating <i>output</i>" (or something equally bland) but you may provide a - more specific one. Use this attribute instead of <code>echo</code> or other print - statements in your <code>cmd</code> command, as this allows the build tool to control - whether such progress messages are printed or not. - </p> - - </td> - </tr> - <tr> - <td id="genrule.output_licenses"> - <code>output_licenses</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - See <a href="/reference/be/common-definitions#binary.output_licenses"><code>common attributes - </code></a> - - </td> - </tr> - <tr> - <td id="genrule.output_to_bindir"> - <code>output_to_bindir</code> - </td> - <td> - <p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> - <p> - If set to True, this option causes output files to be written into the <code>bin</code> - directory instead of the <code>genfiles</code> directory. - </p> - - </td> - </tr> - <tr> - <td id="genrule.toolchains"> - <code>toolchains</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> - <p> - The set of targets whose <a href="/reference/be/make-variables">Make variables</a> this genrule - is allowed to access, or the <a href="/docs/toolchains"><code>toolchain_type</code></a> - targets that this genrule will access. - </p> - - <p> - Toolchains accessed via <code>toolchain_type</code> must also provide a - <code>TemplateVariableInfo</code> provider, which the target can use to access toolchain - details. - </p> - - </td> - </tr> - <tr> - <td id="genrule.tools"> - <code>tools</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of <i>tool</i> dependencies for this rule. See the definition of - <a href="/concepts/build-ref#deps">dependencies</a> for more information. <br/> - <p> - The build system ensures these prerequisites are built before running the genrule command; - they are built using the <a href='/contribute/guide#configurations'><i>exec</i> - configuration</a>, since these tools are executed as part of the build. The path of an - individual <code>tools</code> target <code>//x:y</code> can be obtained using - <code>$(location //x:y)</code>. - </p> - <p> - Any <code>*_binary</code> or tool to be executed by <code>cmd</code> must appear in this - list, not in <code>srcs</code>, to ensure they are built in the correct configuration. - </p> - - </td> - </tr> - </tbody> - </table> - <h2 id="starlark_doc_extract"> - starlark_doc_extract - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/starlarkdocextract/StarlarkDocExtractRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">starlark_doc_extract(<a href="#starlark_doc_extract.name">name</a>, <a href="#starlark_doc_extract.deps">deps</a>, <a href="#starlark_doc_extract.src">src</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#starlark_doc_extract.allow_unused_doc_comments">allow_unused_doc_comments</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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.package_metadata">package_metadata</a>, <a href="#starlark_doc_extract.render_main_repo_name">render_main_repo_name</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#starlark_doc_extract.symbol_names">symbol_names</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><code>starlark_doc_extract()</code> extracts documentation for rules, functions (including -macros), aspects, and providers defined or re-exported in a given <code>.bzl</code> or -<code>.scl</code> file. The output of this rule is a <code>ModuleInfo</code> binary proto as defined +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="genrule.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p> +<br /> +You may refer to this rule by name in the +<code>srcs</code> or <code>deps</code> section of other <code>BUILD</code> +rules. If the rule generates source files, you should use the +<code>srcs</code> attribute.</td> +</tr> +<tr> +<td id="genrule.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of inputs for this rule, such as source files to process. +<p><em>This attributes is not suitable to list tools executed by the <code>cmd</code>; use +the <a href="/reference/be/general.html#genrule.tools"><code>tools</code></a> attribute for them instead.</em></p> +<p>The build system ensures these prerequisites are built before running the genrule +command; they are built using the same configuration as the original build request. The +names of the files of these prerequisites are available to the command as a +space-separated list in <code>$(SRCS)</code>; alternatively the path of an individual +<code>srcs</code> target <code>//x:y</code> can be obtained using <code>$(location //x:y)</code>, or using <code>$<</code> provided it's the only entry in +<code>srcs</code>.</p></td> +</tr> +<tr> +<td id="genrule.outs"><code>outs</code></td> +<td><p>List of <a href="/concepts/build-ref#filename">filenames</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; required</p> +A list of files generated by this rule. +<p>Output files must not cross package boundaries. +Output filenames are interpreted as relative to the package.</p> +<p>If the <code>executable</code> flag is set, <code>outs</code> must contain exactly one +label.</p> +<p>The genrule command is expected to create each output file at a predetermined location. +The location is available in <code>cmd</code> using <a href="/reference/be/make-variables#predefined_genrule_variables">genrule-specific "Make" +variables</a> (<code>$@</code>, <code>$(OUTS)</code>, <code>$(@D)</code> or <code> $(RULEDIR)</code>) or using +<a href="/reference/be/make-variables#predefined_label_variables"><code>$(location)</code></a> substitution.</p></td> +</tr> +<tr> +<td id="genrule.cmd"><code>cmd</code></td> +<td><p>String; default is <code>""</code></p> +The command to run. +Subject to <a href="/reference/be/make-variables#predefined_label_variables"><code>$(location) </code></a> and <a href="/reference/be/make-variables">"Make" variable</a> substitution. +<ol> +<li>First <a href="/reference/be/make-variables#predefined_label_variables"><code>$(location) </code></a> substitution is applied, replacing all occurrences of <code>$(location </code><em><code>label</code></em><code>)</code> and of <code>$(locations </code><em><code>label</code></em><code>)</code> (and similar +constructions using related variables <code>execpath</code>, <code>execpaths</code>, +<code>rootpath</code> and <code>rootpaths</code>).</li> +<li>Next, <a href="/reference/be/make-variables">"Make" variables</a> are expanded. Note that +predefined variables <code>$(JAVA)</code>, <code>$(JAVAC)</code> and +<code>$(JAVABASE)</code> expand under the <em>exec</em> configuration, so Java invocations +that run as part of a build step can correctly load shared libraries and other +dependencies.</li> +<li>Finally, the resulting command is executed using the Bash shell. If its exit code is +non-zero the command is considered to have failed.</li> +</ol> +This is the fallback of <code>cmd_bash</code>, <code>cmd_ps</code> and <code>cmd_bat</code>, +if none of them are applicable. +<p>If the command line length exceeds the platform limit (64K on Linux/macOS, 8K on Windows), +then genrule will write the command to a script and execute that script to work around. This +applies to all cmd attributes (<code>cmd</code>, <code>cmd_bash</code>, <code>cmd_ps</code>, +<code>cmd_bat</code>).</p></td> +</tr> +<tr> +<td id="genrule.cmd_bash"><code>cmd_bash</code></td> +<td><p>String; default is <code>""</code></p> +The Bash command to run. +<p>This attribute has higher priority than <code>cmd</code>. The command is expanded and +runs in the exact same way as the <code>cmd</code> attribute.</p></td> +</tr> +<tr> +<td id="genrule.cmd_bat"><code>cmd_bat</code></td> +<td><p>String; default is <code>""</code></p> +The Batch command to run on Windows. +<p>This attribute has higher priority than <code>cmd</code> and <code>cmd_bash</code>. +The command runs in the similar way as the <code>cmd</code> attribute, with the +following differences:</p> +<ul> +<li>This attribute only applies on Windows.</li> +<li>The command runs with <code>cmd.exe /c</code> with the following default arguments: +<ul> +<li><code>/S</code> - strip first and last quotes and execute everything else as is.</li> +<li><code>/E:ON</code> - enable extended command set.</li> +<li><code>/V:ON</code> - enable delayed variable expansion</li> +<li><code>/D</code> - ignore AutoRun registry entries.</li> +</ul></li> +<li>After <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and +<a href="/reference/be/make-variables">"Make" variable</a> substitution, the paths will be +expanded to Windows style paths (with backslash).</li> +</ul></td> +</tr> +<tr> +<td id="genrule.cmd_ps"><code>cmd_ps</code></td> +<td><p>String; default is <code>""</code></p> +The Powershell command to run on Windows. +<p>This attribute has higher priority than <code>cmd</code>, <code>cmd_bash</code> and +<code>cmd_bat</code>. The command runs in the similar way as the <code>cmd</code> +attribute, with the following differences:</p> +<ul> +<li>This attribute only applies on Windows.</li> +<li>The command runs with <code>powershell.exe /c</code>.</li> +</ul> +<p>To make Powershell easier to use and less error-prone, we run the following +commands to set up the environment before executing Powershell command in genrule.</p> +<ul> +<li><code>Set-ExecutionPolicy -Scope CurrentUser RemoteSigned</code> - allow running +unsigned scripts.</li> +<li><code>$errorActionPreference='Stop'</code> - In case there are multiple commands +separated by <code>;</code>, the action exits immediately if a Powershell CmdLet fails, +but this does <strong>NOT</strong> work for external command.</li> +<li><code>$PSDefaultParameterValues['*:Encoding'] = 'utf8'</code> - change the default +encoding from utf-16 to utf-8.</li> +</ul></td> +</tr> +<tr> +<td id="genrule.executable"><code>executable</code></td> +<td><p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> +Declare output to be executable. +<p>Setting this flag to True means the output is an executable file and can be run using the +<code>run</code> command. The genrule must produce exactly one output in this case. +If this attribute is set, <code>run</code> will try executing the file regardless of +its content.</p> +<p>Declaring data dependencies for the generated executable is not supported.</p></td> +</tr> +<tr> +<td id="genrule.local"><code>local</code></td> +<td><p>Boolean; default is <code>False</code></p> +<p>If set to True, this option forces this <code>genrule</code> to run using the "local" +strategy, which means no remote execution, no sandboxing, no persistent workers.</p> +<p>This is equivalent to providing 'local' as a tag (<code>tags=["local"]</code>).</p></td> +</tr> +<tr> +<td id="genrule.message"><code>message</code></td> +<td><p>String; default is <code>""</code></p> +A progress message. +<p>A progress message that will be printed as this build step is executed. By default, the +message is "Generating <em>output</em>" (or something equally bland) but you may provide a +more specific one. Use this attribute instead of <code>echo</code> or other print +statements in your <code>cmd</code> command, as this allows the build tool to control +whether such progress messages are printed or not.</p></td> +</tr> +<tr> +<td id="genrule.output_licenses"><code>output_licenses</code></td> +<td><p>List of strings; default is <code>[]</code></p> +See <a href="/reference/be/common-definitions#binary.output_licenses"><code>common attributes </code></a></td> +</tr> +<tr> +<td id="genrule.output_to_bindir"><code>output_to_bindir</code></td> +<td><p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> +<p>If set to True, this option causes output files to be written into the <code>bin</code> +directory instead of the <code>genfiles</code> directory.</p></td> +</tr> +<tr> +<td id="genrule.toolchains"><code>toolchains</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +<p>The set of targets whose <a href="/reference/be/make-variables">Make variables</a> this genrule +is allowed to access, or the <a href="/docs/toolchains"><code>toolchain_type</code></a> +targets that this genrule will access.</p> +<p>Toolchains accessed via <code>toolchain_type</code> must also provide a +<code>TemplateVariableInfo</code> provider, which the target can use to access toolchain +details.</p></td> +</tr> +<tr> +<td id="genrule.tools"><code>tools</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of <em>tool</em> dependencies for this rule. See the definition of +<a href="/concepts/build-ref#deps">dependencies</a> for more information.<br /> + <p>The build system ensures these prerequisites are built before running the genrule command; +they are built using the <a href="/contribute/guide#configurations"><em>exec</em> +configuration</a>, since these tools are executed as part of the build. The path of an +individual <code>tools</code> target <code>//x:y</code> can be obtained using +<code>$(location //x:y)</code>.</p> +<p>Any <code>*_binary</code> or tool to be executed by <code>cmd</code> must appear in this +list, not in <code>srcs</code>, to ensure they are built in the correct configuration.</p></td> +</tr> +</tbody> +</table> + +## starlark_doc_extract + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/starlarkdocextract/StarlarkDocExtractRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +starlark_doc_extract(name, deps, src, data, allow_unused_doc_comments, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility) +``` + +`starlark_doc_extract()` extracts documentation for rules, functions (including +macros), aspects, and providers defined or re-exported in a given `.bzl` or +`.scl` file. The output of this rule is a `ModuleInfo` binary proto as defined in -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto">stardoc_output.proto</a> +[stardoc_output.proto](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto) in the Bazel source tree. -<h4 id="starlark_doc_extract_implicit_outputs">Implicit output targets</h4> - <ul> - <li><code><var>name</var>.binaryproto</code> (the default output): A - <code>ModuleInfo</code> binary proto.</li> - <li><code><var>name</var>.textproto</code> (only built if explicitly requested): the text - proto version of <code><var>name</var>.binaryproto</code>.</li> - </ul> - - -<p>Warning: the output format of this rule is not guaranteed to be stable. It is intended mainly for -internal use by <a href="https://github.com/bazelbuild/stardoc">Stardoc</a>. - - - - <h3 id="starlark_doc_extract_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="starlark_doc_extract.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="starlark_doc_extract.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of targets wrapping the Starlark files which are <code>load()</code>-ed by - <code>src</code>. These targets <em>should</em> under normal usage be - <a href="https://github.com/bazelbuild/bazel-skylib/blob/main/bzl_library.bzl"><code>bzl_library</code></a> - targets, but the <code>starlark_doc_extract</code> rule does not enforce that, and accepts - any target which provides Starlark files in its <code>DefaultInfo</code>. - - <p>Note that the wrapped Starlark files must be files in the source tree; Bazel cannot - <code>load()</code> generated files. - - </td> - </tr> - <tr> - <td id="starlark_doc_extract.src"> - <code>src</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; required</p> - A Starlark file from which to extract documentation. - - <p>Note that this must be a file in the source tree; Bazel cannot <code>load()</code> - generated files. - - </td> - </tr> - <tr> - <td id="starlark_doc_extract.allow_unused_doc_comments"> - <code>allow_unused_doc_comments</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - If true, allow and silently ignore doc comments (comments starting with <code>#:</code>) - which are not attached to any global variable, or which are attached to a variable whose - value's documentation should be provided in a different way (for example, in a docstring for - a function, or via <code>rule(doc = ...)</code> for a rule). - - </td> - </tr> - <tr> - <td id="starlark_doc_extract.render_main_repo_name"> - <code>render_main_repo_name</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - If true, render labels in the main repository in emitted documentation with a repo component - (in other words, <code>//foo:bar.bzl</code> will be emitted as - <code>@main_repo_name//foo:bar.bzl</code>). - <p>The name to use for the main repository is obtained from <code>module(name = ...)</code> - in the main repository's <code>MODULE.bazel</code> file (if Bzlmod is enabled), or from - <code>workspace(name = ...)</code> in the main repository's <code>WORKSPACE</code> file. - <p>This attribute should be set to <code>False</code> when generating documentation for - Starlark files which are intended to be used only within the same repository, and to - <code>True</code> when generating documentation for Starlark files which are intended to be - used from other repositories. - - </td> - </tr> - <tr> - <td id="starlark_doc_extract.symbol_names"> - <code>symbol_names</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - An optional list of qualified names of exported functions, rules, providers, or aspects (or - structs in which they are nested) for which to extract documentation. Here, a <em>qualified - name</em> means the name under which an entity is made available to a user of the module, - including any structs in which the entity is nested for namespacing. - - <p><code>starlark_doc_extract</code> emits documentation for an entity if and only if - <ol> - <li> - each component of the entity's qualified name is public (in other words, the first - character of each component of the qualified name is alphabetic, not <code>"_"</code>); - <em>and</em> - </li> - <li> - <ol> - <li> - <em>either</em> the <code>symbol_names</code> list is empty (which is the default - case), <em>or</em> - </li> - <li> - the entity's qualified name, or the qualified name of a struct in which the entity - is nested, is in the <code>symbol_names</code> list. - </li> - </ol> - </li> - </ol> - - </td> - </tr> - </tbody> - </table> - <h2 id="test_suite"> - test_suite - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">test_suite(<a href="#test_suite.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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#typical.licenses">licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#test_suite.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="#test_suite.tests">tests</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - -<p> -A <code>test_suite</code> defines a set of tests that are considered "useful" to humans. This +#### Implicit output targets + +- `name``.binaryproto` (the default output): A + `ModuleInfo` binary proto. +- `name``.textproto` (only built if explicitly requested): the text + proto version of `name``.binaryproto`. + +Warning: the output format of this rule is not guaranteed to be stable. It is intended mainly for +internal use by [Stardoc](https://github.com/bazelbuild/stardoc). + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="starlark_doc_extract.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="starlark_doc_extract.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of targets wrapping the Starlark files which are <code>load()</code>-ed by +<code>src</code>. These targets <em>should</em> under normal usage be +<a href="https://github.com/bazelbuild/bazel-skylib/blob/main/bzl_library.bzl"><code>bzl_library</code></a> +targets, but the <code>starlark_doc_extract</code> rule does not enforce that, and accepts +any target which provides Starlark files in its <code>DefaultInfo</code>. +<p>Note that the wrapped Starlark files must be files in the source tree; Bazel cannot +<code>load()</code> generated files.</p></td> +</tr> +<tr> +<td id="starlark_doc_extract.src"><code>src</code></td> +<td><p><a href="/concepts/labels">Label</a>; required</p> +A Starlark file from which to extract documentation. +<p>Note that this must be a file in the source tree; Bazel cannot <code>load()</code> +generated files.</p></td> +</tr> +<tr> +<td id="starlark_doc_extract.allow_unused_doc_comments"><code>allow_unused_doc_comments</code></td> +<td><p>Boolean; default is <code>False</code></p> +If true, allow and silently ignore doc comments (comments starting with <code>#:</code>) +which are not attached to any global variable, or which are attached to a variable whose +value's documentation should be provided in a different way (for example, in a docstring for +a function, or via <code>rule(doc = ...)</code> for a rule).</td> +</tr> +<tr> +<td id="starlark_doc_extract.render_main_repo_name"><code>render_main_repo_name</code></td> +<td><p>Boolean; default is <code>False</code></p> +If true, render labels in the main repository in emitted documentation with a repo component +(in other words, <code>//foo:bar.bzl</code> will be emitted as +<code>@main_repo_name//foo:bar.bzl</code>). +<p>The name to use for the main repository is obtained from <code>module(name = ...)</code> +in the main repository's <code>MODULE.bazel</code> file (if Bzlmod is enabled), or from +<code>workspace(name = ...)</code> in the main repository's <code>WORKSPACE</code> file.</p> +<p>This attribute should be set to <code>False</code> when generating documentation for +Starlark files which are intended to be used only within the same repository, and to +<code>True</code> when generating documentation for Starlark files which are intended to be +used from other repositories.</p></td> +</tr> +<tr> +<td id="starlark_doc_extract.symbol_names"><code>symbol_names</code></td> +<td><p>List of strings; default is <code>[]</code></p> +An optional list of qualified names of exported functions, rules, providers, or aspects (or +structs in which they are nested) for which to extract documentation. Here, a <em>qualified +name</em> means the name under which an entity is made available to a user of the module, +including any structs in which the entity is nested for namespacing. +<p><code>starlark_doc_extract</code> emits documentation for an entity if and only if</p> +<ol> +<li>each component of the entity's qualified name is public (in other words, the first +character of each component of the qualified name is alphabetic, not <code>"_"</code>); +<em>and</em></li> +<li><ol> +<li><em>either</em> the <code>symbol_names</code> list is empty (which is the default +case), <em>or</em></li> +<li>the entity's qualified name, or the qualified name of a struct in which the entity +is nested, is in the <code>symbol_names</code> list.</li> +</ol></li> +</ol></td> +</tr> +</tbody> +</table> + +## test_suite + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +test_suite(name, aspect_hints, compatible_with, deprecation, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, tests, visibility) +``` + +A `test_suite` defines a set of tests that are considered "useful" to humans. This allows projects to define sets of tests, such as "tests you must run before checkin", "our -project's stress tests" or "all small tests." The <code>bazel test</code> command respects this sort -of organization: For an invocation like <code>bazel test //some/test:suite</code>, Bazel first -enumerates all test targets transitively included by the <code>//some/test:suite</code> target (we +project's stress tests" or "all small tests." The `bazel test` command respects this sort +of organization: For an invocation like `bazel test //some/test:suite`, Bazel first +enumerates all test targets transitively included by the `//some/test:suite` target (we call this "test_suite expansion"), then Bazel builds and tests those targets. -</p> -<h4 id="test_suite_examples">Examples</h4> +#### Examples + +A test suite to run all of the small tests in the current package. + +``` code -<p>A test suite to run all of the small tests in the current package.</p> -<pre class="code"> test_suite( name = "small_tests", tags = ["small"], ) -</pre> +``` + +A test suite that runs a specified set of tests: -<p>A test suite that runs a specified set of tests:</p> +``` code -<pre class="code"> test_suite( name = "smoke_tests", tests = [ @@ -1417,113 +995,76 @@ test_suite( "public_api_unittest", ], ) -</pre> +``` + +A test suite to run all tests in the current package which are not flaky. + +``` code -<p>A test suite to run all tests in the current package which are not flaky.</p> -<pre class="code"> test_suite( name = "non_flaky_test", tags = ["-flaky"], ) -</pre> - - - - <h3 id="test_suite_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="test_suite.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="test_suite.tags"> - <code>tags</code> - </td> - <td> - <p>List of strings; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> - List of text tags such as "small" or "database" or "-flaky". Tags may be any valid string. - <p> - Tags which begin with a "-" character are considered negative tags. The - preceding "-" character is not considered part of the tag, so a suite tag - of "-small" matches a test's "small" size. All other tags are considered - positive tags. - </p> - <p> - Optionally, to make positive tags more explicit, tags may also begin with the - "+" character, which will not be evaluated as part of the text of the tag. It - merely makes the positive and negative distinction easier to read. - </p> - <p> - Only test rules that match <b>all</b> of the positive tags and <b>none</b> of the negative - tags will be included in the test suite. Note that this does not mean that error checking - for dependencies on tests that are filtered out is skipped; the dependencies on skipped - tests still need to be legal (e.g. not blocked by visibility constraints). - </p> - <p> - The <code>manual</code> tag keyword is treated differently than the above by the - "test_suite expansion" performed by the <code>bazel test</code> command on invocations - involving wildcard - <a href="https://bazel.build/docs/build#specifying-build-targets">target patterns</a>. - There, <code>test_suite</code> targets tagged "manual" are filtered out (and thus not - expanded). This behavior is consistent with how <code>bazel build</code> and - <code>bazel test</code> handle wildcard target patterns in general. Note that this is - explicitly different from how <code>bazel query 'tests(E)'</code> behaves, as suites are - always expanded by the <code>tests</code> query function, regardless of the - <code>manual</code> tag. - </p> - <p> - Note that a test's <code>size</code> is considered a tag for the purpose of filtering. - </p> - <p> - If you need a <code>test_suite</code> that contains tests with mutually exclusive tags - (e.g. all small and medium tests), you'll have to create three <code>test_suite</code> - rules: one for all small tests, one for all medium tests, and one that includes the - previous two. - </p> - - </td> - </tr> - <tr> - <td id="test_suite.tests"> - <code>tests</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> - A list of test suites and test targets of any language. - <p> - Any <code>*_test</code> is accepted here, independent of the language. No - <code>*_binary</code> targets are accepted however, even if they happen to run a test. - Filtering by the specified <code>tags</code> is only done for tests listed directly in - this attribute. If this attribute contains <code>test_suite</code>s, the tests inside - those will not be filtered by this <code>test_suite</code> (they are considered to be - filtered already). - </p> - <p> - If the <code>tests</code> attribute is unspecified or empty, the rule will default to - including all test rules in the current BUILD file that are not tagged as - <code>manual</code>. These rules are still subject to <code>tag</code> filtering. - </p> - - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="test_suite.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="test_suite.tags"><code>tags</code></td> +<td><p>List of strings; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +List of text tags such as "small" or "database" or "-flaky". Tags may be any valid string. +<p>Tags which begin with a "-" character are considered negative tags. The +preceding "-" character is not considered part of the tag, so a suite tag +of "-small" matches a test's "small" size. All other tags are considered +positive tags.</p> +<p>Optionally, to make positive tags more explicit, tags may also begin with the +"+" character, which will not be evaluated as part of the text of the tag. It +merely makes the positive and negative distinction easier to read.</p> +<p>Only test rules that match <strong>all</strong> of the positive tags and <strong>none</strong> of the negative +tags will be included in the test suite. Note that this does not mean that error checking +for dependencies on tests that are filtered out is skipped; the dependencies on skipped +tests still need to be legal (e.g. not blocked by visibility constraints).</p> +<p>The <code>manual</code> tag keyword is treated differently than the above by the +"test_suite expansion" performed by the <code>bazel test</code> command on invocations +involving wildcard +<a href="https://bazel.build/docs/build#specifying-build-targets">target patterns</a>. +There, <code>test_suite</code> targets tagged "manual" are filtered out (and thus not +expanded). This behavior is consistent with how <code>bazel build</code> and +<code>bazel test</code> handle wildcard target patterns in general. Note that this is +explicitly different from how <code>bazel query 'tests(E)'</code> behaves, as suites are +always expanded by the <code>tests</code> query function, regardless of the +<code>manual</code> tag.</p> +<p>Note that a test's <code>size</code> is considered a tag for the purpose of filtering.</p> +<p>If you need a <code>test_suite</code> that contains tests with mutually exclusive tags +(e.g. all small and medium tests), you'll have to create three <code>test_suite</code> +rules: one for all small tests, one for all medium tests, and one that includes the +previous two.</p></td> +</tr> +<tr> +<td id="test_suite.tests"><code>tests</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +A list of test suites and test targets of any language. +<p>Any <code>*_test</code> is accepted here, independent of the language. No +<code>*_binary</code> targets are accepted however, even if they happen to run a test. +Filtering by the specified <code>tags</code> is only done for tests listed directly in +this attribute. If this attribute contains <code>test_suite</code>s, the tests inside +those will not be filtered by this <code>test_suite</code> (they are considered to be +filtered already).</p> +<p>If the <code>tests</code> attribute is unspecified or empty, the rule will default to +including all test rules in the current BUILD file that are not tagged as +<code>manual</code>. These rules are still subject to <code>tag</code> filtering.</p></td> +</tr> +</tbody> +</table> diff --git a/reference/be/java.mdx b/reference/be/java.mdx index 2c13db2..1f3d1a4 100644 --- a/reference/be/java.mdx +++ b/reference/be/java.mdx @@ -2,261 +2,171 @@ title: 'java' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">Java Rules</h1> +# Java Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} +{% include "\_buttons.html" %} +## Rules +- [java_binary](#java_binary) +- [java_import](#java_import) +- [java_library](#java_library) +- [java_test](#java_test) +- [java_package_configuration](#java_package_configuration) +- [java_plugin](#java_plugin) +- [java_runtime](#java_runtime) +- [java_single_jar](#java_single_jar) +- [java_toolchain](#java_toolchain) +## java_binary -<h2>Rules</h2> -<ul> - <li> - <a href="#java_binary"> - java_binary </a> - </li> - <li> - <a href="#java_import"> - java_import </a> - </li> - <li> - <a href="#java_library"> - java_library </a> - </li> - <li> - <a href="#java_test"> - java_test </a> - </li> - <li> - <a href="#java_package_configuration"> - java_package_configuration </a> - </li> - <li> - <a href="#java_plugin"> - java_plugin </a> - </li> - <li> - <a href="#java_runtime"> - java_runtime </a> - </li> - <li> - <a href="#java_single_jar"> - java_single_jar </a> - </li> - <li> - <a href="#java_toolchain"> - java_toolchain </a> - </li> -</ul> +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_binary.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <h2 id="java_binary"> - java_binary - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_binary.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_binary(<a href="#java_binary.name">name</a>, <a href="#java_binary.deps">deps</a>, <a href="#java_binary.srcs">srcs</a>, <a href="#java_binary.data">data</a>, <a href="#java_binary.resources">resources</a>, <a href="#java_binary.add_exports">add_exports</a>, <a href="#java_binary.add_opens">add_opens</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_binary.bootclasspath">bootclasspath</a>, <a href="#java_binary.classpath_resources">classpath_resources</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_binary.create_executable">create_executable</a>, <a href="#java_binary.deploy_env">deploy_env</a>, <a href="#java_binary.deploy_manifest_lines">deploy_manifest_lines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_binary.javacopts">javacopts</a>, <a href="#java_binary.jvm_flags">jvm_flags</a>, <a href="#java_binary.launcher">launcher</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_binary.main_class">main_class</a>, <a href="#java_binary.neverlink">neverlink</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_binary.plugins">plugins</a>, <a href="#java_binary.resource_strip_prefix">resource_strip_prefix</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_binary.runtime_deps">runtime_deps</a>, <a href="#java_binary.stamp">stamp</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.toolchains">toolchains</a>, <a href="#java_binary.use_launcher">use_launcher</a>, <a href="#java_binary.use_testrunner">use_testrunner</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> - Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. - The wrapper shell script uses a classpath that includes, among other things, a jar file for each - library on which the binary depends. When running the wrapper shell script, any nonempty - <code>JAVABIN</code> environment variable will take precedence over the version specified via - Bazel's <code>--java_runtime_version</code> flag. -</p> -<p> - The wrapper script accepts several unique flags. Refer to - <code>java_stub_template.txt</code> - for a list of configurable flags and environment variables accepted by the wrapper. -</p> - -<h4 id="java_binary_implicit_outputs">Implicit output targets</h4> -<ul> - <li><code><var>name</var>.jar</code>: A Java archive, containing the class files and other - resources corresponding to the binary's direct dependencies.</li> - <li><code><var>name</var>-src.jar</code>: An archive containing the sources ("source - jar").</li> - <li><code><var>name</var>_deploy.jar</code>: A Java archive suitable for deployment (only - built if explicitly requested). - <p> - Building the <code><<var>name</var>>_deploy.jar</code> target for your rule - creates a self-contained jar file with a manifest that allows it to be run with the - <code>java -jar</code> command or with the wrapper script's <code>--singlejar</code> - option. Using the wrapper script is preferred to <code>java -jar</code> because it - also passes the <a href="#java_binary-jvm_flags">JVM flags</a> and the options - to load native libraries. - </p> - <p> - The deploy jar contains all the classes that would be found by a classloader that - searched the classpath from the binary's wrapper script from beginning to end. It also - contains the native libraries needed for dependencies. These are automatically loaded - into the JVM at runtime. - </p> - <p>If your target specifies a <a href="#java_binary.launcher">launcher</a> - attribute, then instead of being a normal JAR file, the _deploy.jar will be a - native binary. This will contain the launcher plus any native (C++) dependencies of - your rule, all linked into a static binary. The actual jar file's bytes will be - appended to that native binary, creating a single binary blob containing both the - executable and the Java code. You can execute the resulting jar file directly - like you would execute any native binary.</p> - </li> - <li><code><var>name</var>_deploy-src.jar</code>: An archive containing the sources - collected from the transitive closure of the target. These will match the classes in the - <code>deploy.jar</code> except where jars have no matching source jar.</li> -</ul> +``` rule-signature +java_binary(name, deps, srcs, data, resources, add_exports, add_opens, args, aspect_hints, bootclasspath, classpath_resources, compatible_with, create_executable, deploy_env, deploy_manifest_lines, deprecation, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, javacopts, jvm_flags, launcher, licenses, main_class, neverlink, output_licenses, package_metadata, plugins, resource_strip_prefix, restricted_to, runtime_deps, stamp, tags, target_compatible_with, testonly, toolchains, use_launcher, use_testrunner, visibility) +``` + +Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. +The wrapper shell script uses a classpath that includes, among other things, a jar file for each +library on which the binary depends. When running the wrapper shell script, any nonempty +`JAVABIN` environment variable will take precedence over the version specified via +Bazel's `--java_runtime_version` flag. + +The wrapper script accepts several unique flags. Refer to +`java_stub_template.txt` +for a list of configurable flags and environment variables accepted by the wrapper. + +#### Implicit output targets + +- `name``.jar`: A Java archive, containing the class files and other + resources corresponding to the binary's direct dependencies. + +- `name``-src.jar`: An archive containing the sources ("source + jar"). + +- `name``_deploy.jar`: A Java archive suitable for deployment (only + built if explicitly requested). + + Building the `<``name``>_deploy.jar` target for your rule + creates a self-contained jar file with a manifest that allows it to be run with the + `java -jar` command or with the wrapper script's `--singlejar` + option. Using the wrapper script is preferred to `java -jar` because it + also passes the [JVM flags](#java_binary-jvm_flags) and the options + to load native libraries. + + The deploy jar contains all the classes that would be found by a classloader that + searched the classpath from the binary's wrapper script from beginning to end. It also + contains the native libraries needed for dependencies. These are automatically loaded + into the JVM at runtime. + + If your target specifies a [launcher](#java_binary.launcher) + attribute, then instead of being a normal JAR file, the \_deploy.jar will be a + native binary. This will contain the launcher plus any native (C++) dependencies of + your rule, all linked into a static binary. The actual jar file's bytes will be + appended to that native binary, creating a single binary blob containing both the + executable and the Java code. You can execute the resulting jar file directly + like you would execute any native binary. + +- `name``_deploy-src.jar`: An archive containing the sources + collected from the transitive closure of the target. These will match the classes in the + `deploy.jar` except where jars have no matching source jar. -<p> It is good practice to use the name of the source file that is the main entry point of the application (minus the extension). For example, if your entry point is called -<code>Main.java</code>, then your name could be <code>Main</code>. -</p> +`Main.java`, then your name could be `Main`. + +A `deps` attribute is not allowed in a `java_binary` rule without +[`srcs`](#java_binary-srcs); such a rule requires a +[`main_class`](#java_binary-main_class) provided by +[`runtime_deps`](#java_binary-runtime_deps). -<p> - A <code>deps</code> attribute is not allowed in a <code>java_binary</code> rule without - <a href="#java_binary-srcs"><code>srcs</code></a>; such a rule requires a - <a href="#java_binary-main_class"><code>main_class</code></a> provided by - <a href="#java_binary-runtime_deps"><code>runtime_deps</code></a>. -</p> +The following code snippet illustrates a common mistake: + +``` code -<p>The following code snippet illustrates a common mistake:</p> -<pre class="code"> -<code class="lang-starlark"> java_binary( name = "DontDoThis", srcs = [ - <var>...</var>, - <code class="deprecated">"GeneratedJavaFile.java"</code>, # a generated .java file + ..., + "GeneratedJavaFile.java", # a generated .java file ], - deps = [<code class="deprecated">":generating_rule",</code>], # rule that generates that file + deps = [":generating_rule",], # rule that generates that file ) -</code> -</pre> +``` + +Do this instead: + +``` code -<p>Do this instead:</p> -<pre class="code"> -<code class="lang-starlark"> java_binary( name = "DoThisInstead", srcs = [ - <var>...</var>, + ..., ":generating_rule", ], ) -</code> -</pre> - - <h3 id="java_binary_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="java_binary.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_binary.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries to be linked in to the target. +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_binary.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_binary.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries to be linked in to the target. See general comments about <code>deps</code> at <a href="common-definitions.html#typical-attributes">Typical attributes defined by -most build rules</a>. - </td> - </tr> - <tr> - <td id="java_binary.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of source files that are processed to create the target. +most build rules</a>.</td> +</tr> +<tr> +<td id="java_binary.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. -<p> -Source files of type <code>.java</code> are compiled. In case of generated +<p>Source files of type <code>.java</code> are compiled. In case of generated <code>.java</code> files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the <code>outs</code> of the generating rule. You should not list the generating rule in <code>deps</code> -because it is a no-op. -</p> -<p> -Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if -you need to generate a set of <code>.java</code> files with a genrule.) -</p> -<p> -Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates +because it is a no-op.</p> +<p>Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if +you need to generate a set of <code>.java</code> files with a genrule.)</p> +<p>Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates any of the files listed above, they will be used the same way as described for source -files. -</p> - -<p> -This argument is almost always required, except if a +files.</p> +<p>This argument is almost always required, except if a <a href="#java_binary.main_class"><code>main_class</code></a> attribute specifies a -class on the runtime classpath or you specify the <code>runtime_deps</code> argument. -</p> - </td> - </tr> - <tr> - <td id="java_binary.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this library at runtime. +class on the runtime classpath or you specify the <code>runtime_deps</code> argument.</p></td> +</tr> +<tr> +<td id="java_binary.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this library at runtime. See general comments about <code>data</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. - </td> - </tr> - <tr> - <td id="java_binary.resources"> - <code>resources</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of data files to include in a Java jar. - -<p> -Resources may be source files or generated files. -</p> - -<p> -If resources are specified, they will be bundled in the jar along with the usual +most build rules</a>.</td> +</tr> +<tr> +<td id="java_binary.resources"><code>resources</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of data files to include in a Java jar. +<p>Resources may be source files or generated files.</p> +<p>If resources are specified, they will be bundled in the jar along with the usual <code>.class</code> files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's <a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, @@ -265,155 +175,103 @@ found, Bazel then looks for the topmost directory named "java" or "javatests" (s example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, however, the <code>resource_strip_prefix</code> attribute can be used to specify a -specific alternative directory for resource files. - </td> - </tr> - <tr> - <td id="java_binary.add_exports"> - <code>add_exports</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-exports= flags. - </td> - </tr> - <tr> - <td id="java_binary.add_opens"> - <code>add_opens</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to reflectively access the given <code>module</code> or +specific alternative directory for resource files.</p></td> +</tr> +<tr> +<td id="java_binary.add_exports"><code>add_exports</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to access the given <code>module</code> or <code>package</code>. +<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> +</tr> +<tr> +<td id="java_binary.add_opens"><code>add_opens</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to reflectively access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-opens= flags. - </td> - </tr> - <tr> - <td id="java_binary.bootclasspath"> - <code>bootclasspath</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Restricted API, do not use! - </td> - </tr> - <tr> - <td id="java_binary.classpath_resources"> - <code>classpath_resources</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - <em class="harmful">DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)</em> -<p> -A list of resources that must be located at the root of the java tree. This attribute's +<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> +</tr> +<tr> +<td id="java_binary.bootclasspath"><code>bootclasspath</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Restricted API, do not use!</td> +</tr> +<tr> +<td id="java_binary.classpath_resources"><code>classpath_resources</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +<em>DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)</em> +<p>A list of resources that must be located at the root of the java tree. This attribute's only purpose is to support third-party libraries that require that their resources be found on the classpath as exactly <code>"myconfig.xml"</code>. It is only allowed on -binaries and not libraries, due to the danger of namespace conflicts. -</p> - </td> - </tr> - <tr> - <td id="java_binary.create_executable"> - <code>create_executable</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - Deprecated, use <code>java_single_jar</code> instead. - </td> - </tr> - <tr> - <td id="java_binary.deploy_env"> - <code>deploy_env</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of other <code>java_binary</code> targets which represent the deployment +binaries and not libraries, due to the danger of namespace conflicts.</p></td> +</tr> +<tr> +<td id="java_binary.create_executable"><code>create_executable</code></td> +<td><p>Boolean; default is <code>True</code></p> +Deprecated, use <code>java_single_jar</code> instead.</td> +</tr> +<tr> +<td id="java_binary.deploy_env"><code>deploy_env</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of other <code>java_binary</code> targets which represent the deployment environment for this binary. Set this attribute when building a plugin which will be loaded by another -<code>java_binary</code>.<br/> Setting this attribute excludes all dependencies from +<code>java_binary</code>.<br /> +Setting this attribute excludes all dependencies from the runtime classpath (and the deploy jar) of this binary that are shared between this -binary and the targets specified in <code>deploy_env</code>. - </td> - </tr> - <tr> - <td id="java_binary.deploy_manifest_lines"> - <code>deploy_manifest_lines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - A list of lines to add to the <code>META-INF/manifest.mf</code> file generated for the +binary and the targets specified in <code>deploy_env</code>.</td> +</tr> +<tr> +<td id="java_binary.deploy_manifest_lines"><code>deploy_manifest_lines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +A list of lines to add to the <code>META-INF/manifest.mf</code> file generated for the <code>*_deploy.jar</code> target. The contents of this attribute are <em>not</em> subject -to <a href="make-variables.html">"Make variable"</a> substitution. - </td> - </tr> - <tr> - <td id="java_binary.javacopts"> - <code>javacopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra compiler options for this binary. +to <a href="make-variables.html">"Make variable"</a> substitution.</td> +</tr> +<tr> +<td id="java_binary.javacopts"><code>javacopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra compiler options for this binary. Subject to <a href="make-variables.html">"Make variable"</a> substitution and <a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>These compiler options are passed to javac after the global compiler options.</p> - </td> - </tr> - <tr> - <td id="java_binary.jvm_flags"> - <code>jvm_flags</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - A list of flags to embed in the wrapper script generated for running this binary. +<p>These compiler options are passed to javac after the global compiler options.</p></td> +</tr> +<tr> +<td id="java_binary.jvm_flags"><code>jvm_flags</code></td> +<td><p>List of strings; default is <code>[]</code></p> +A list of flags to embed in the wrapper script generated for running this binary. Subject to <a href="/reference/be/make-variables#location">$(location)</a> and <a href="make-variables.html">"Make variable"</a> substitution, and <a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. - <p>The wrapper script for a Java binary includes a CLASSPATH definition (to find all the dependent jars) and invokes the right Java interpreter. The command line generated by the wrapper script includes the name of the main class followed by a <code>"$@"</code> so you can pass along other -arguments after the classname. However, arguments intended for parsing -by the JVM must be specified <i>before</i> the classname on the command -line. The contents of <code>jvm_flags</code> are added to the wrapper +arguments after the classname. However, arguments intended for parsing +by the JVM must be specified <em>before</em> the classname on the command +line. The contents of <code>jvm_flags</code> are added to the wrapper script before the classname is listed.</p> - <p>Note that this attribute has <em>no effect</em> on <code>*_deploy.jar</code> -outputs.</p> - </td> - </tr> - <tr> - <td id="java_binary.launcher"> - <code>launcher</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Specify a binary that will be used to run your Java program instead of the +outputs.</p></td> +</tr> +<tr> +<td id="java_binary.launcher"><code>launcher</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Specify a binary that will be used to run your Java program instead of the normal <code>bin/java</code> program included with the JDK. The target must be a <code>cc_binary</code>. Any <code>cc_binary</code> that implements the -<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html"> -Java Invocation API</a> can be specified as a value for this attribute. - +<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html">Java Invocation API</a> can be specified as a value for this attribute. <p>By default, Bazel will use the normal JDK launcher (bin/java or java.exe).</p> - -<p>The related <a href="/docs/user-manual#flag--java_launcher"><code> ---java_launcher</code></a> Bazel flag affects only those +<p>The related <a href="/docs/user-manual#flag--java_launcher"><code> --java_launcher</code></a> Bazel flag affects only those <code>java_binary</code> and <code>java_test</code> targets that have -<i>not</i> specified a <code>launcher</code> attribute.</p> - +<em>not</em> specified a <code>launcher</code> attribute.</p> <p>Note that your native (C++, SWIG, JNI) dependencies will be built differently depending on whether you are using the JDK launcher or another launcher:</p> - <ul> <li>If you are using the normal JDK launcher (the default), native dependencies are built as a shared library named <code>{name}_nativedeps.so</code>, where <code>{name}</code> is the <code>name</code> attribute of this java_binary rule. Unused code is <em>not</em> removed by the linker in this configuration.</li> - <li>If you are using any other launcher, native (C++) dependencies are statically linked into a binary named <code>{name}_nativedeps</code>, where <code>{name}</code> is the <code>name</code> attribute of this java_binary rule. In this case, @@ -421,170 +279,119 @@ the linker will remove any code it thinks is unused from the resulting binary, which means any C++ code accessed only via JNI may not be linked in unless that <code>cc_library</code> target specifies <code>alwayslink = True</code>.</li> </ul> - <p>When using any launcher other than the default JDK launcher, the format of the <code>*_deploy.jar</code> output changes. See the main -<a href="#java_binary">java_binary</a> docs for details.</p> - </td> - </tr> - <tr> - <td id="java_binary.main_class"> - <code>main_class</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Name of class with <code>main()</code> method to use as entry point. +<a href="#java_binary">java_binary</a> docs for details.</p></td> +</tr> +<tr> +<td id="java_binary.main_class"><code>main_class</code></td> +<td><p>String; default is <code>""</code></p> +Name of class with <code>main()</code> method to use as entry point. If a rule uses this option, it does not need a <code>srcs=[...]</code> list. Thus, with this attribute one can make an executable from a Java library that already contains one or more <code>main()</code> methods. -<p> -The value of this attribute is a class name, not a source file. The class must be +<p>The value of this attribute is a class name, not a source file. The class must be available at runtime: it may be compiled by this rule (from <code>srcs</code>) or provided by direct or transitive dependencies (through <code>runtime_deps</code> or <code>deps</code>). If the class is unavailable, the binary will fail at runtime; there -is no build-time check. -</p> - </td> - </tr> - <tr> - <td id="java_binary.neverlink"> - <code>neverlink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - - </td> - </tr> - <tr> - <td id="java_binary.plugins"> - <code>plugins</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Java compiler plugins to run at compile-time. +is no build-time check.</p></td> +</tr> +<tr> +<td id="java_binary.neverlink"><code>neverlink</code></td> +<td><p>Boolean; default is <code>False</code></p></td> +</tr> +<tr> +<td id="java_binary.plugins"><code>plugins</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Java compiler plugins to run at compile-time. Every <code>java_plugin</code> specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use -<code><a href="#java_library.exported_plugins">exported_plugins</a></code>. Resources -generated by the plugin will be included in the resulting jar of this rule. - </td> - </tr> - <tr> - <td id="java_binary.resource_strip_prefix"> - <code>resource_strip_prefix</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The path prefix to strip from Java resources. -<p> -If specified, this path prefix is stripped from every file in the <code>resources</code> +<a href="#java_library.exported_plugins"><code>exported_plugins</code></a>. Resources +generated by the plugin will be included in the resulting jar of this rule.</td> +</tr> +<tr> +<td id="java_binary.resource_strip_prefix"><code>resource_strip_prefix</code></td> +<td><p>String; default is <code>""</code></p> +The path prefix to strip from Java resources. +<p>If specified, this path prefix is stripped from every file in the <code>resources</code> attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at -<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>. -</p> - </td> - </tr> - <tr> - <td id="java_binary.runtime_deps"> - <code>runtime_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Libraries to make available to the final binary or test at runtime only. +<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.</p></td> +</tr> +<tr> +<td id="java_binary.runtime_deps"><code>runtime_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Libraries to make available to the final binary or test at runtime only. Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both -<code>runtime_deps</code> and <code>deps</code>. - </td> - </tr> - <tr> - <td id="java_binary.stamp"> - <code>stamp</code> - </td> - <td> - <p>Integer; default is <code>-1</code></p> - Whether to encode build information into the binary. Possible values: +<code>runtime_deps</code> and <code>deps</code>.</td> +</tr> +<tr> +<td id="java_binary.stamp"><code>stamp</code></td> +<td><p>Integer; default is <code>-1</code></p> +Whether to encode build information into the binary. Possible values: <ul> -<li> - <code>stamp = 1</code>: Always stamp the build information into the binary, even in - <a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This - setting should be avoided</b>, since it potentially kills remote caching for the - binary and any downstream actions that depend on it. -</li> -<li> - <code>stamp = 0</code>: Always replace build information by constant values. This - gives good build result caching. -</li> -<li> - <code>stamp = -1</code>: Embedding of build information is controlled by the - <a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag. -</li> +<li><code>stamp = 1</code>: Always stamp the build information into the binary, even in +<a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <strong>This +setting should be avoided</strong>, since it potentially kills remote caching for the +binary and any downstream actions that depend on it.</li> +<li><code>stamp = 0</code>: Always replace build information by constant values. This +gives good build result caching.</li> +<li><code>stamp = -1</code>: Embedding of build information is controlled by the +<a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.</li> </ul> -<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> - </td> - </tr> - <tr> - <td id="java_binary.use_launcher"> - <code>use_launcher</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - Whether the binary should use a custom launcher. - +<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p></td> +</tr> +<tr> +<td id="java_binary.use_launcher"><code>use_launcher</code></td> +<td><p>Boolean; default is <code>True</code></p> +Whether the binary should use a custom launcher. <p>If this attribute is set to false, the -<a href="/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related +<a href="/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related <a href="/docs/user-manual#flag--java_launcher"><code>--java_launcher</code></a> flag -will be ignored for this target. - </td> - </tr> - <tr> - <td id="java_binary.use_testrunner"> - <code>use_testrunner</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Use the test runner (by default +will be ignored for this target.</p></td> +</tr> +<tr> +<td id="java_binary.use_testrunner"><code>use_testrunner</code></td> +<td><p>Boolean; default is <code>False</code></p> +Use the test runner (by default <code>com.google.testing.junit.runner.BazelTestRunner</code>) class as the main entry point for a Java program, and provide the test class to the test runner as a value of <code>bazel.test_suite</code> -system property. - -<br/> +system property.<br /> You can use this to override the default behavior, which is to use test runner for <code>java_test</code> rules, -and not use it for <code>java_binary</code> rules. It is unlikely -you will want to do this. One use is for <code>AllTest</code> +and not use it for <code>java_binary</code> rules. It is unlikely +you will want to do this. One use is for <code>AllTest</code> rules that are invoked by another rule (to set up a database -before running the tests, for example). The <code>AllTest</code> +before running the tests, for example). The <code>AllTest</code> rule must be declared as a <code>java_binary</code>, but should still use the test runner as its main entry point. +The name of a test runner class can be overridden with <code>main_class</code> attribute.</td> +</tr> +</tbody> +</table> + +## java_import -The name of a test runner class can be overridden with <code>main_class</code> attribute. - </td> - </tr> - </tbody> - </table> - <h2 id="java_import"> - java_import - </h2> +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_import.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_import(name, deps, data, add_exports, add_opens, aspect_hints, compatible_with, constraints, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exports, features, jars, licenses, neverlink, package_metadata, proguard_specs, restricted_to, runtime_deps, srcjar, tags, target_compatible_with, testonly, toolchains, visibility) +``` - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_import.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +This rule allows the use of precompiled `.jar` files as +libraries for [`java_library`](#java_library) and +`java_binary` rules. - <pre class="rule-signature">java_import(<a href="#java_import.name">name</a>, <a href="#java_import.deps">deps</a>, <a href="#java_import.data">data</a>, <a href="#java_import.add_exports">add_exports</a>, <a href="#java_import.add_opens">add_opens</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_import.constraints">constraints</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#java_import.exports">exports</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#java_import.jars">jars</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_import.neverlink">neverlink</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_import.proguard_specs">proguard_specs</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_import.runtime_deps">runtime_deps</a>, <a href="#java_import.srcjar">srcjar</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +#### Examples - <p> - This rule allows the use of precompiled <code>.jar</code> files as - libraries for <code><a href="#java_library">java_library</a></code> and - <code>java_binary</code> rules. -</p> +``` code -<h4 id="java_import_examples">Examples</h4> -<pre class="code"> -<code class="lang-starlark"> java_import( name = "maven_model", jars = [ @@ -593,278 +400,179 @@ The name of a test runner class can be overridden with <code>main_class</code> a "maven_model/maven-model-builder-3.2.3.jar", ], ) -</code> -</pre> - - <h3 id="java_import_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="java_import.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_import.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries to be linked in to the target. -See <a href="/reference/be/java.html#java_library.deps">java_library.deps</a>. - </td> - </tr> - <tr> - <td id="java_import.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this rule at runtime. - </td> - </tr> - <tr> - <td id="java_import.add_exports"> - <code>add_exports</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-exports= flags. - </td> - </tr> - <tr> - <td id="java_import.add_opens"> - <code>add_opens</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to reflectively access the given <code>module</code> or +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_import.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_import.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries to be linked in to the target. +See <a href="/reference/be/java.html#java_library.deps">java_library.deps</a>.</td> +</tr> +<tr> +<td id="java_import.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this rule at runtime.</td> +</tr> +<tr> +<td id="java_import.add_exports"><code>add_exports</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to access the given <code>module</code> or <code>package</code>. +<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> +</tr> +<tr> +<td id="java_import.add_opens"><code>add_opens</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to reflectively access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-opens= flags. - </td> - </tr> - <tr> - <td id="java_import.constraints"> - <code>constraints</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra constraints imposed on this rule as a Java library. - </td> - </tr> - <tr> - <td id="java_import.exports"> - <code>exports</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Targets to make available to users of this rule. -See <a href="/reference/be/java.html#java_library.exports">java_library.exports</a>. - </td> - </tr> - <tr> - <td id="java_import.jars"> - <code>jars</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; required</p> - The list of JAR files provided to Java targets that depend on this target. - </td> - </tr> - <tr> - <td id="java_import.neverlink"> - <code>neverlink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Only use this library for compilation and not at runtime. +<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> +</tr> +<tr> +<td id="java_import.constraints"><code>constraints</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra constraints imposed on this rule as a Java library.</td> +</tr> +<tr> +<td id="java_import.exports"><code>exports</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Targets to make available to users of this rule. +See <a href="/reference/be/java.html#java_library.exports">java_library.exports</a>.</td> +</tr> +<tr> +<td id="java_import.jars"><code>jars</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; required</p> +The list of JAR files provided to Java targets that depend on this target.</td> +</tr> +<tr> +<td id="java_import.neverlink"><code>neverlink</code></td> +<td><p>Boolean; default is <code>False</code></p> +Only use this library for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of libraries like this are IDE APIs for IDE plug-ins or <code>tools.jar</code> for anything running on -a standard JDK. - </td> - </tr> - <tr> - <td id="java_import.proguard_specs"> - <code>proguard_specs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Files to be used as Proguard specification. +a standard JDK.</td> +</tr> +<tr> +<td id="java_import.proguard_specs"><code>proguard_specs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any <code>android_binary</code> target depending on this library. - The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in -<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges. - </td> - </tr> - <tr> - <td id="java_import.runtime_deps"> - <code>runtime_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Libraries to make available to the final binary or test at runtime only. -See <a href="/reference/be/java.html#java_library.runtime_deps">java_library.runtime_deps</a>. - </td> - </tr> - <tr> - <td id="java_import.srcjar"> - <code>srcjar</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - A JAR file that contains source code for the compiled JAR files. - </td> - </tr> - </tbody> - </table> - <h2 id="java_library"> - java_library - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_library(<a href="#java_library.name">name</a>, <a href="#java_library.deps">deps</a>, <a href="#java_library.srcs">srcs</a>, <a href="#java_library.data">data</a>, <a href="#java_library.resources">resources</a>, <a href="#java_library.add_exports">add_exports</a>, <a href="#java_library.add_opens">add_opens</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_library.bootclasspath">bootclasspath</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#java_library.exported_plugins">exported_plugins</a>, <a href="#java_library.exports">exports</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#java_library.javabuilder_jvm_flags">javabuilder_jvm_flags</a>, <a href="#java_library.javacopts">javacopts</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_library.neverlink">neverlink</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_library.plugins">plugins</a>, <a href="#java_library.proguard_specs">proguard_specs</a>, <a href="#java_library.resource_strip_prefix">resource_strip_prefix</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_library.runtime_deps">runtime_deps</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p>This rule compiles and links sources into a <code>.jar</code> file.</p> - -<h4>Implicit outputs</h4> -<ul> - <li><code>lib<var>name</var>.jar</code>: A Java archive containing the class files.</li> - <li><code>lib<var>name</var>-src.jar</code>: An archive containing the sources ("source - jar").</li> -</ul> +<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges.</td> +</tr> +<tr> +<td id="java_import.runtime_deps"><code>runtime_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Libraries to make available to the final binary or test at runtime only. +See <a href="/reference/be/java.html#java_library.runtime_deps">java_library.runtime_deps</a>.</td> +</tr> +<tr> +<td id="java_import.srcjar"><code>srcjar</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +A JAR file that contains source code for the compiled JAR files.</td> +</tr> +</tbody> +</table> + +## java_library + +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_library(name, deps, srcs, data, resources, add_exports, add_opens, aspect_hints, bootclasspath, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exported_plugins, exports, features, javabuilder_jvm_flags, javacopts, licenses, neverlink, package_metadata, plugins, proguard_specs, resource_strip_prefix, restricted_to, runtime_deps, tags, target_compatible_with, testonly, toolchains, visibility) +``` - <h3 id="java_library_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="java_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of libraries to link into this library. +This rule compiles and links sources into a `.jar` file. + +#### Implicit outputs + +- `lib``name``.jar`: A Java archive containing the class files. +- `lib``name``-src.jar`: An archive containing the sources ("source + jar"). + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of libraries to link into this library. See general comments about <code>deps</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by most build rules</a>. -<p> - The jars built by <code>java_library</code> rules listed in <code>deps</code> will be on - the compile-time classpath of this rule. Furthermore the transitive closure of their - <code>deps</code>, <code>runtime_deps</code> and <code>exports</code> will be on the - runtime classpath. -</p> -<p> - By contrast, targets in the <code>data</code> attribute are included in the runfiles but - on neither the compile-time nor runtime classpath. -</p> - </td> - </tr> - <tr> - <td id="java_library.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of source files that are processed to create the target. +<p>The jars built by <code>java_library</code> rules listed in <code>deps</code> will be on +the compile-time classpath of this rule. Furthermore the transitive closure of their +<code>deps</code>, <code>runtime_deps</code> and <code>exports</code> will be on the +runtime classpath.</p> +<p>By contrast, targets in the <code>data</code> attribute are included in the runfiles but +on neither the compile-time nor runtime classpath.</p></td> +</tr> +<tr> +<td id="java_library.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. -<p> -Source files of type <code>.java</code> are compiled. In case of generated +<p>Source files of type <code>.java</code> are compiled. In case of generated <code>.java</code> files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the <code>outs</code> of the generating rule. You should not list the generating rule in <code>deps</code> -because it is a no-op. -</p> -<p> -Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if -you need to generate a set of <code>.java</code> files with a genrule.) -</p> -<p> -Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates +because it is a no-op.</p> +<p>Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if +you need to generate a set of <code>.java</code> files with a genrule.)</p> +<p>Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates any of the files listed above, they will be used the same way as described for source -files. -</p> -<p> -Source files of type <code>.properties</code> are treated as resources. -</p> - +files.</p> +<p>Source files of type <code>.properties</code> are treated as resources.</p> <p>All other files are ignored, as long as there is at least one file of a file type described above. Otherwise an error is raised.</p> - -<p> -This argument is almost always required, except if you specify the <code>runtime_deps</code> argument. -</p> - </td> - </tr> - <tr> - <td id="java_library.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this library at runtime. +<p>This argument is almost always required, except if you specify the <code>runtime_deps</code> argument.</p></td> +</tr> +<tr> +<td id="java_library.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this library at runtime. See general comments about <code>data</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by most build rules</a>. -<p> - When building a <code>java_library</code>, Bazel doesn't put these files anywhere; if the - <code>data</code> files are generated files then Bazel generates them. When building a - test that depends on this <code>java_library</code> Bazel copies or links the - <code>data</code> files into the runfiles area. -</p> - </td> - </tr> - <tr> - <td id="java_library.resources"> - <code>resources</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of data files to include in a Java jar. -<p> -Resources may be source files or generated files. -</p> - -<p> -If resources are specified, they will be bundled in the jar along with the usual +<p>When building a <code>java_library</code>, Bazel doesn't put these files anywhere; if the +<code>data</code> files are generated files then Bazel generates them. When building a +test that depends on this <code>java_library</code> Bazel copies or links the +<code>data</code> files into the runfiles area.</p></td> +</tr> +<tr> +<td id="java_library.resources"><code>resources</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of data files to include in a Java jar. +<p>Resources may be source files or generated files.</p> +<p>If resources are specified, they will be bundled in the jar along with the usual <code>.class</code> files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's <a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, @@ -873,231 +581,156 @@ found, Bazel then looks for the topmost directory named "java" or "javatests" (s example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, however, the <code>resource_strip_prefix</code> attribute can be used to specify a -specific alternative directory for resource files. - </td> - </tr> - <tr> - <td id="java_library.add_exports"> - <code>add_exports</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-exports= flags. - </td> - </tr> - <tr> - <td id="java_library.add_opens"> - <code>add_opens</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to reflectively access the given <code>module</code> or +specific alternative directory for resource files.</p></td> +</tr> +<tr> +<td id="java_library.add_exports"><code>add_exports</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to access the given <code>module</code> or <code>package</code>. +<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> +</tr> +<tr> +<td id="java_library.add_opens"><code>add_opens</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to reflectively access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-opens= flags. - </td> - </tr> - <tr> - <td id="java_library.bootclasspath"> - <code>bootclasspath</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Restricted API, do not use! - </td> - </tr> - <tr> - <td id="java_library.exported_plugins"> - <code>exported_plugins</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of <code><a href="#/reference/be/java.html#java_plugin">java_plugin</a></code>s (e.g. annotation +<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> +</tr> +<tr> +<td id="java_library.bootclasspath"><code>bootclasspath</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Restricted API, do not use!</td> +</tr> +<tr> +<td id="java_library.exported_plugins"><code>exported_plugins</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of <a href="#/reference/be/java.html#java_plugin"><code>java_plugin</code></a>s (e.g. annotation processors) to export to libraries that directly depend on this library. -<p> - The specified list of <code>java_plugin</code>s will be applied to any library which - directly depends on this library, just as if that library had explicitly declared these - labels in <code><a href="/reference/be/java.html#java_library.plugins">plugins</a></code>. -</p> - </td> - </tr> - <tr> - <td id="java_library.exports"> - <code>exports</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Exported libraries. -<p> - Listing rules here will make them available to parent rules, as if the parents explicitly - depended on these rules. This is not true for regular (non-exported) <code>deps</code>. -</p> -<p> - Summary: a rule <i>X</i> can access the code in <i>Y</i> if there exists a dependency - path between them that begins with a <code>deps</code> edge followed by zero or more - <code>exports</code> edges. Let's see some examples to illustrate this. -</p> -<p> - Assume <i>A</i> depends on <i>B</i> and <i>B</i> depends on <i>C</i>. In this case - C is a <em>transitive</em> dependency of A, so changing C's sources and rebuilding A will - correctly rebuild everything. However A will not be able to use classes in C. To allow - that, either A has to declare C in its <code>deps</code>, or B can make it easier for A - (and anything that may depend on A) by declaring C in its (B's) <code>exports</code> - attribute. -</p> -<p> - The closure of exported libraries is available to all direct parent rules. Take a slightly - different example: A depends on B, B depends on C and D, and also exports C but not D. - Now A has access to C but not to D. Now, if C and D exported some libraries, C' and D' - respectively, A could only access C' but not D'. -</p> -<p> - Important: an exported rule is not a regular dependency. Sticking to the previous example, - if B exports C and wants to also use C, it has to also list it in its own - <code>deps</code>. -</p> - </td> - </tr> - <tr> - <td id="java_library.javabuilder_jvm_flags"> - <code>javabuilder_jvm_flags</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Restricted API, do not use! - </td> - </tr> - <tr> - <td id="java_library.javacopts"> - <code>javacopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra compiler options for this library. +<p>The specified list of <code>java_plugin</code>s will be applied to any library which +directly depends on this library, just as if that library had explicitly declared these +labels in <a href="/reference/be/java.html#java_library.plugins"><code>plugins</code></a>.</p></td> +</tr> +<tr> +<td id="java_library.exports"><code>exports</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Exported libraries. +<p>Listing rules here will make them available to parent rules, as if the parents explicitly +depended on these rules. This is not true for regular (non-exported) <code>deps</code>.</p> +<p>Summary: a rule <em>X</em> can access the code in <em>Y</em> if there exists a dependency +path between them that begins with a <code>deps</code> edge followed by zero or more +<code>exports</code> edges. Let's see some examples to illustrate this.</p> +<p>Assume <em>A</em> depends on <em>B</em> and <em>B</em> depends on <em>C</em>. In this case +C is a <em>transitive</em> dependency of A, so changing C's sources and rebuilding A will +correctly rebuild everything. However A will not be able to use classes in C. To allow +that, either A has to declare C in its <code>deps</code>, or B can make it easier for A +(and anything that may depend on A) by declaring C in its (B's) <code>exports</code> +attribute.</p> +<p>The closure of exported libraries is available to all direct parent rules. Take a slightly +different example: A depends on B, B depends on C and D, and also exports C but not D. +Now A has access to C but not to D. Now, if C and D exported some libraries, C' and D' +respectively, A could only access C' but not D'.</p> +<p>Important: an exported rule is not a regular dependency. Sticking to the previous example, +if B exports C and wants to also use C, it has to also list it in its own +<code>deps</code>.</p></td> +</tr> +<tr> +<td id="java_library.javabuilder_jvm_flags"><code>javabuilder_jvm_flags</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Restricted API, do not use!</td> +</tr> +<tr> +<td id="java_library.javacopts"><code>javacopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra compiler options for this library. Subject to <a href="make-variables.html">"Make variable"</a> substitution and <a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>These compiler options are passed to javac after the global compiler options.</p> - </td> - </tr> - <tr> - <td id="java_library.neverlink"> - <code>neverlink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Whether this library should only be used for compilation and not at runtime. +<p>These compiler options are passed to javac after the global compiler options.</p></td> +</tr> +<tr> +<td id="java_library.neverlink"><code>neverlink</code></td> +<td><p>Boolean; default is <code>False</code></p> +Whether this library should only be used for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of such libraries are the IDE APIs for IDE plug-ins or <code>tools.jar</code> for anything running on a standard JDK. -<p> - Note that <code>neverlink = True</code> does not prevent the compiler from inlining material - from this library into compilation targets that depend on it, as permitted by the Java - Language Specification (e.g., <code>static final</code> constants of <code>String</code> - or of primitive types). The preferred use case is therefore when the runtime library is - identical to the compilation library. -</p> -<p> - If the runtime library differs from the compilation library then you must ensure that it - differs only in places that the JLS forbids compilers to inline (and that must hold for - all future versions of the JLS). -</p> - </td> - </tr> - <tr> - <td id="java_library.plugins"> - <code>plugins</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Java compiler plugins to run at compile-time. +<p>Note that <code>neverlink = True</code> does not prevent the compiler from inlining material +from this library into compilation targets that depend on it, as permitted by the Java +Language Specification (e.g., <code>static final</code> constants of <code>String</code> +or of primitive types). The preferred use case is therefore when the runtime library is +identical to the compilation library.</p> +<p>If the runtime library differs from the compilation library then you must ensure that it +differs only in places that the JLS forbids compilers to inline (and that must hold for +all future versions of the JLS).</p></td> +</tr> +<tr> +<td id="java_library.plugins"><code>plugins</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Java compiler plugins to run at compile-time. Every <code>java_plugin</code> specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use -<code><a href="#java_library.exported_plugins">exported_plugins</a></code>. Resources -generated by the plugin will be included in the resulting jar of this rule. - </td> - </tr> - <tr> - <td id="java_library.proguard_specs"> - <code>proguard_specs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Files to be used as Proguard specification. +<a href="#java_library.exported_plugins"><code>exported_plugins</code></a>. Resources +generated by the plugin will be included in the resulting jar of this rule.</td> +</tr> +<tr> +<td id="java_library.proguard_specs"><code>proguard_specs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any <code>android_binary</code> target depending on this library. - The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in -<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges. - </td> - </tr> - <tr> - <td id="java_library.resource_strip_prefix"> - <code>resource_strip_prefix</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The path prefix to strip from Java resources. -<p> -If specified, this path prefix is stripped from every file in the <code>resources</code> +<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges.</td> +</tr> +<tr> +<td id="java_library.resource_strip_prefix"><code>resource_strip_prefix</code></td> +<td><p>String; default is <code>""</code></p> +The path prefix to strip from Java resources. +<p>If specified, this path prefix is stripped from every file in the <code>resources</code> attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at -<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>. -</p> - </td> - </tr> - <tr> - <td id="java_library.runtime_deps"> - <code>runtime_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Libraries to make available to the final binary or test at runtime only. +<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.</p></td> +</tr> +<tr> +<td id="java_library.runtime_deps"><code>runtime_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Libraries to make available to the final binary or test at runtime only. Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both -<code>runtime_deps</code> and <code>deps</code>. - </td> - </tr> - </tbody> - </table> - <h2 id="java_test"> - java_test - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_test.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_test(<a href="#java_test.name">name</a>, <a href="#java_test.deps">deps</a>, <a href="#java_test.srcs">srcs</a>, <a href="#java_test.data">data</a>, <a href="#java_test.resources">resources</a>, <a href="#java_test.add_exports">add_exports</a>, <a href="#java_test.add_opens">add_opens</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_test.bootclasspath">bootclasspath</a>, <a href="#java_test.classpath_resources">classpath_resources</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_test.create_executable">create_executable</a>, <a href="#java_test.deploy_manifest_lines">deploy_manifest_lines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#test.flaky">flaky</a>, <a href="#java_test.javacopts">javacopts</a>, <a href="#java_test.jvm_flags">jvm_flags</a>, <a href="#java_test.launcher">launcher</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#java_test.main_class">main_class</a>, <a href="#java_test.neverlink">neverlink</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_test.plugins">plugins</a>, <a href="#java_test.resource_strip_prefix">resource_strip_prefix</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_test.runtime_deps">runtime_deps</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#java_test.stamp">stamp</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="#java_test.test_class">test_class</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="#java_test.use_launcher">use_launcher</a>, <a href="#java_test.use_testrunner">use_testrunner</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> -A <code>java_test()</code> rule compiles a Java test. A test is a binary wrapper around your +<code>runtime_deps</code> and <code>deps</code>.</td> +</tr> +</tbody> +</table> + +## java_test + +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_test.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_test(name, deps, srcs, data, resources, add_exports, add_opens, args, aspect_hints, bootclasspath, classpath_resources, compatible_with, create_executable, deploy_manifest_lines, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, javacopts, jvm_flags, launcher, licenses, local, main_class, neverlink, package_metadata, plugins, resource_strip_prefix, restricted_to, runtime_deps, shard_count, size, stamp, tags, target_compatible_with, test_class, testonly, timeout, toolchains, use_launcher, use_testrunner, visibility) +``` + +A `java_test()` rule compiles a Java test. A test is a binary wrapper around your test code. The test runner's main method is invoked instead of the main class being compiled. -</p> -<h4 id="java_test_implicit_outputs">Implicit output targets</h4> -<ul> - <li><code><var>name</var>.jar</code>: A Java archive.</li> - <li><code><var>name</var>_deploy.jar</code>: A Java archive suitable - for deployment. (Only built if explicitly requested.) See the description of the - <code><var>name</var>_deploy.jar</code> output from - <a href="#java_binary">java_binary</a> for more details.</li> -</ul> +#### Implicit output targets -<p> -See the section on <code>java_binary()</code> arguments. This rule also -supports all <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">attributes common -to all test rules (*_test)</a>. -</p> +- `name``.jar`: A Java archive. +- `name``_deploy.jar`: A Java archive suitable + for deployment. (Only built if explicitly requested.) See the description of the + `name``_deploy.jar` output from + [java_binary](#java_binary) for more details. + +See the section on `java_binary()` arguments. This rule also +supports all [attributes common +to all test rules (\*\_test)](https://bazel.build/reference/be/common-definitions#common-attributes-tests). + +#### Examples + +``` code -<h4 id="java_test_examples">Examples</h4> -<pre class="code"> -<code class="lang-starlark"> java_library( name = "tests", @@ -1116,101 +749,65 @@ java_test( "//util/mysql", ], ) -</code> -</pre> - - <h3 id="java_test_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="java_test.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_test.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries to be linked in to the target. +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_test.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_test.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries to be linked in to the target. See general comments about <code>deps</code> at <a href="common-definitions.html#typical-attributes">Typical attributes defined by -most build rules</a>. - </td> - </tr> - <tr> - <td id="java_test.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of source files that are processed to create the target. +most build rules</a>.</td> +</tr> +<tr> +<td id="java_test.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. -<p> -Source files of type <code>.java</code> are compiled. In case of generated +<p>Source files of type <code>.java</code> are compiled. In case of generated <code>.java</code> files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the <code>outs</code> of the generating rule. You should not list the generating rule in <code>deps</code> -because it is a no-op. -</p> -<p> -Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if -you need to generate a set of <code>.java</code> files with a genrule.) -</p> -<p> -Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates +because it is a no-op.</p> +<p>Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if +you need to generate a set of <code>.java</code> files with a genrule.)</p> +<p>Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates any of the files listed above, they will be used the same way as described for source -files. -</p> - -<p> -This argument is almost always required, except if a +files.</p> +<p>This argument is almost always required, except if a <a href="#java_binary.main_class"><code>main_class</code></a> attribute specifies a -class on the runtime classpath or you specify the <code>runtime_deps</code> argument. -</p> - </td> - </tr> - <tr> - <td id="java_test.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this library at runtime. +class on the runtime classpath or you specify the <code>runtime_deps</code> argument.</p></td> +</tr> +<tr> +<td id="java_test.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this library at runtime. See general comments about <code>data</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. - </td> - </tr> - <tr> - <td id="java_test.resources"> - <code>resources</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of data files to include in a Java jar. - -<p> -Resources may be source files or generated files. -</p> - -<p> -If resources are specified, they will be bundled in the jar along with the usual +most build rules</a>.</td> +</tr> +<tr> +<td id="java_test.resources"><code>resources</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of data files to include in a Java jar. +<p>Resources may be source files or generated files.</p> +<p>If resources are specified, they will be bundled in the jar along with the usual <code>.class</code> files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's <a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, @@ -1219,141 +816,92 @@ found, Bazel then looks for the topmost directory named "java" or "javatests" (s example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, however, the <code>resource_strip_prefix</code> attribute can be used to specify a -specific alternative directory for resource files. - </td> - </tr> - <tr> - <td id="java_test.add_exports"> - <code>add_exports</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-exports= flags. - </td> - </tr> - <tr> - <td id="java_test.add_opens"> - <code>add_opens</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to reflectively access the given <code>module</code> or +specific alternative directory for resource files.</p></td> +</tr> +<tr> +<td id="java_test.add_exports"><code>add_exports</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to access the given <code>module</code> or <code>package</code>. +<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> +</tr> +<tr> +<td id="java_test.add_opens"><code>add_opens</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to reflectively access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-opens= flags. - </td> - </tr> - <tr> - <td id="java_test.bootclasspath"> - <code>bootclasspath</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Restricted API, do not use! - </td> - </tr> - <tr> - <td id="java_test.classpath_resources"> - <code>classpath_resources</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - <em class="harmful">DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)</em> -<p> -A list of resources that must be located at the root of the java tree. This attribute's +<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> +</tr> +<tr> +<td id="java_test.bootclasspath"><code>bootclasspath</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Restricted API, do not use!</td> +</tr> +<tr> +<td id="java_test.classpath_resources"><code>classpath_resources</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +<em>DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)</em> +<p>A list of resources that must be located at the root of the java tree. This attribute's only purpose is to support third-party libraries that require that their resources be found on the classpath as exactly <code>"myconfig.xml"</code>. It is only allowed on -binaries and not libraries, due to the danger of namespace conflicts. -</p> - </td> - </tr> - <tr> - <td id="java_test.create_executable"> - <code>create_executable</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - Deprecated, use <code>java_single_jar</code> instead. - </td> - </tr> - <tr> - <td id="java_test.deploy_manifest_lines"> - <code>deploy_manifest_lines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - A list of lines to add to the <code>META-INF/manifest.mf</code> file generated for the +binaries and not libraries, due to the danger of namespace conflicts.</p></td> +</tr> +<tr> +<td id="java_test.create_executable"><code>create_executable</code></td> +<td><p>Boolean; default is <code>True</code></p> +Deprecated, use <code>java_single_jar</code> instead.</td> +</tr> +<tr> +<td id="java_test.deploy_manifest_lines"><code>deploy_manifest_lines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +A list of lines to add to the <code>META-INF/manifest.mf</code> file generated for the <code>*_deploy.jar</code> target. The contents of this attribute are <em>not</em> subject -to <a href="make-variables.html">"Make variable"</a> substitution. - </td> - </tr> - <tr> - <td id="java_test.javacopts"> - <code>javacopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra compiler options for this binary. +to <a href="make-variables.html">"Make variable"</a> substitution.</td> +</tr> +<tr> +<td id="java_test.javacopts"><code>javacopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra compiler options for this binary. Subject to <a href="make-variables.html">"Make variable"</a> substitution and <a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>These compiler options are passed to javac after the global compiler options.</p> - </td> - </tr> - <tr> - <td id="java_test.jvm_flags"> - <code>jvm_flags</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - A list of flags to embed in the wrapper script generated for running this binary. +<p>These compiler options are passed to javac after the global compiler options.</p></td> +</tr> +<tr> +<td id="java_test.jvm_flags"><code>jvm_flags</code></td> +<td><p>List of strings; default is <code>[]</code></p> +A list of flags to embed in the wrapper script generated for running this binary. Subject to <a href="/reference/be/make-variables#location">$(location)</a> and <a href="make-variables.html">"Make variable"</a> substitution, and <a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. - <p>The wrapper script for a Java binary includes a CLASSPATH definition (to find all the dependent jars) and invokes the right Java interpreter. The command line generated by the wrapper script includes the name of the main class followed by a <code>"$@"</code> so you can pass along other -arguments after the classname. However, arguments intended for parsing -by the JVM must be specified <i>before</i> the classname on the command -line. The contents of <code>jvm_flags</code> are added to the wrapper +arguments after the classname. However, arguments intended for parsing +by the JVM must be specified <em>before</em> the classname on the command +line. The contents of <code>jvm_flags</code> are added to the wrapper script before the classname is listed.</p> - <p>Note that this attribute has <em>no effect</em> on <code>*_deploy.jar</code> -outputs.</p> - </td> - </tr> - <tr> - <td id="java_test.launcher"> - <code>launcher</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Specify a binary that will be used to run your Java program instead of the +outputs.</p></td> +</tr> +<tr> +<td id="java_test.launcher"><code>launcher</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Specify a binary that will be used to run your Java program instead of the normal <code>bin/java</code> program included with the JDK. The target must be a <code>cc_binary</code>. Any <code>cc_binary</code> that implements the -<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html"> -Java Invocation API</a> can be specified as a value for this attribute. - +<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html">Java Invocation API</a> can be specified as a value for this attribute. <p>By default, Bazel will use the normal JDK launcher (bin/java or java.exe).</p> - -<p>The related <a href="/docs/user-manual#flag--java_launcher"><code> ---java_launcher</code></a> Bazel flag affects only those +<p>The related <a href="/docs/user-manual#flag--java_launcher"><code> --java_launcher</code></a> Bazel flag affects only those <code>java_binary</code> and <code>java_test</code> targets that have -<i>not</i> specified a <code>launcher</code> attribute.</p> - +<em>not</em> specified a <code>launcher</code> attribute.</p> <p>Note that your native (C++, SWIG, JNI) dependencies will be built differently depending on whether you are using the JDK launcher or another launcher:</p> - <ul> <li>If you are using the normal JDK launcher (the default), native dependencies are built as a shared library named <code>{name}_nativedeps.so</code>, where <code>{name}</code> is the <code>name</code> attribute of this java_binary rule. Unused code is <em>not</em> removed by the linker in this configuration.</li> - <li>If you are using any other launcher, native (C++) dependencies are statically linked into a binary named <code>{name}_nativedeps</code>, where <code>{name}</code> is the <code>name</code> attribute of this java_binary rule. In this case, @@ -1361,208 +909,145 @@ the linker will remove any code it thinks is unused from the resulting binary, which means any C++ code accessed only via JNI may not be linked in unless that <code>cc_library</code> target specifies <code>alwayslink = True</code>.</li> </ul> - <p>When using any launcher other than the default JDK launcher, the format of the <code>*_deploy.jar</code> output changes. See the main -<a href="#java_binary">java_binary</a> docs for details.</p> - </td> - </tr> - <tr> - <td id="java_test.main_class"> - <code>main_class</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Name of class with <code>main()</code> method to use as entry point. +<a href="#java_binary">java_binary</a> docs for details.</p></td> +</tr> +<tr> +<td id="java_test.main_class"><code>main_class</code></td> +<td><p>String; default is <code>""</code></p> +Name of class with <code>main()</code> method to use as entry point. If a rule uses this option, it does not need a <code>srcs=[...]</code> list. Thus, with this attribute one can make an executable from a Java library that already contains one or more <code>main()</code> methods. -<p> -The value of this attribute is a class name, not a source file. The class must be +<p>The value of this attribute is a class name, not a source file. The class must be available at runtime: it may be compiled by this rule (from <code>srcs</code>) or provided by direct or transitive dependencies (through <code>runtime_deps</code> or <code>deps</code>). If the class is unavailable, the binary will fail at runtime; there -is no build-time check. -</p> - </td> - </tr> - <tr> - <td id="java_test.neverlink"> - <code>neverlink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - - </td> - </tr> - <tr> - <td id="java_test.plugins"> - <code>plugins</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Java compiler plugins to run at compile-time. +is no build-time check.</p></td> +</tr> +<tr> +<td id="java_test.neverlink"><code>neverlink</code></td> +<td><p>Boolean; default is <code>False</code></p></td> +</tr> +<tr> +<td id="java_test.plugins"><code>plugins</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Java compiler plugins to run at compile-time. Every <code>java_plugin</code> specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use -<code><a href="#java_library.exported_plugins">exported_plugins</a></code>. Resources -generated by the plugin will be included in the resulting jar of this rule. - </td> - </tr> - <tr> - <td id="java_test.resource_strip_prefix"> - <code>resource_strip_prefix</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The path prefix to strip from Java resources. -<p> -If specified, this path prefix is stripped from every file in the <code>resources</code> +<a href="#java_library.exported_plugins"><code>exported_plugins</code></a>. Resources +generated by the plugin will be included in the resulting jar of this rule.</td> +</tr> +<tr> +<td id="java_test.resource_strip_prefix"><code>resource_strip_prefix</code></td> +<td><p>String; default is <code>""</code></p> +The path prefix to strip from Java resources. +<p>If specified, this path prefix is stripped from every file in the <code>resources</code> attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at -<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>. -</p> - </td> - </tr> - <tr> - <td id="java_test.runtime_deps"> - <code>runtime_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Libraries to make available to the final binary or test at runtime only. +<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.</p></td> +</tr> +<tr> +<td id="java_test.runtime_deps"><code>runtime_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Libraries to make available to the final binary or test at runtime only. Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both -<code>runtime_deps</code> and <code>deps</code>. - </td> - </tr> - <tr> - <td id="java_test.stamp"> - <code>stamp</code> - </td> - <td> - <p>Integer; default is <code>0</code></p> - Whether to encode build information into the binary. Possible values: +<code>runtime_deps</code> and <code>deps</code>.</td> +</tr> +<tr> +<td id="java_test.stamp"><code>stamp</code></td> +<td><p>Integer; default is <code>0</code></p> +Whether to encode build information into the binary. Possible values: <ul> -<li> - <code>stamp = 1</code>: Always stamp the build information into the binary, even in - <a href="https://bazel.build/docs/user-manual#stamp"><code>--nostamp</code></a> builds. <b>This - setting should be avoided</b>, since it potentially kills remote caching for the - binary and any downstream actions that depend on it. -</li> -<li> - <code>stamp = 0</code>: Always replace build information by constant values. This - gives good build result caching. -</li> -<li> - <code>stamp = -1</code>: Embedding of build information is controlled by the - <a href="https://bazel.build/docs/user-manual#stamp"><code>--[no]stamp</code></a> flag. -</li> +<li><code>stamp = 1</code>: Always stamp the build information into the binary, even in +<a href="https://bazel.build/docs/user-manual#stamp"><code>--nostamp</code></a> builds. <strong>This +setting should be avoided</strong>, since it potentially kills remote caching for the +binary and any downstream actions that depend on it.</li> +<li><code>stamp = 0</code>: Always replace build information by constant values. This +gives good build result caching.</li> +<li><code>stamp = -1</code>: Embedding of build information is controlled by the +<a href="https://bazel.build/docs/user-manual#stamp"><code>--[no]stamp</code></a> flag.</li> </ul> -<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> - </td> - </tr> - <tr> - <td id="java_test.test_class"> - <code>test_class</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The Java class to be loaded by the test runner.<br/> -<p> - By default, if this argument is not defined then the legacy mode is used and the - test arguments are used instead. Set the <code>--nolegacy_bazel_java_test</code> flag - to not fallback on the first argument. -</p> -<p> - This attribute specifies the name of a Java class to be run by - this test. It is rare to need to set this. If this argument is omitted, - it will be inferred using the target's <code>name</code> and its - source-root-relative path. If the test is located outside a known - source root, Bazel will report an error if <code>test_class</code> - is unset. -</p> -<p> - For JUnit3, the test class needs to either be a subclass of - <code>junit.framework.TestCase</code> or it needs to have a public - static <code>suite()</code> method that returns a - <code>junit.framework.Test</code> (or a subclass of <code>Test</code>). -</p> -<p> - This attribute allows several <code>java_test</code> rules to - share the same <code>Test</code> - (<code>TestCase</code>, <code>TestSuite</code>, ...). Typically - additional information is passed to it - (e.g. via <code>jvm_flags=['-Dkey=value']</code>) so that its - behavior differs in each case, such as running a different - subset of the tests. This attribute also enables the use of - Java tests outside the <code>javatests</code> tree. -</p> - </td> - </tr> - <tr> - <td id="java_test.use_launcher"> - <code>use_launcher</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - Whether the binary should use a custom launcher. - +<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p></td> +</tr> +<tr> +<td id="java_test.test_class"><code>test_class</code></td> +<td><p>String; default is <code>""</code></p> +The Java class to be loaded by the test runner.<br /> + <p>By default, if this argument is not defined then the legacy mode is used and the +test arguments are used instead. Set the <code>--nolegacy_bazel_java_test</code> flag +to not fallback on the first argument.</p> +<p>This attribute specifies the name of a Java class to be run by +this test. It is rare to need to set this. If this argument is omitted, +it will be inferred using the target's <code>name</code> and its +source-root-relative path. If the test is located outside a known +source root, Bazel will report an error if <code>test_class</code> +is unset.</p> +<p>For JUnit3, the test class needs to either be a subclass of +<code>junit.framework.TestCase</code> or it needs to have a public +static <code>suite()</code> method that returns a +<code>junit.framework.Test</code> (or a subclass of <code>Test</code>).</p> +<p>This attribute allows several <code>java_test</code> rules to +share the same <code>Test</code> +(<code>TestCase</code>, <code>TestSuite</code>, ...). Typically +additional information is passed to it +(e.g. via <code>jvm_flags=['-Dkey=value']</code>) so that its +behavior differs in each case, such as running a different +subset of the tests. This attribute also enables the use of +Java tests outside the <code>javatests</code> tree.</p></td> +</tr> +<tr> +<td id="java_test.use_launcher"><code>use_launcher</code></td> +<td><p>Boolean; default is <code>True</code></p> +Whether the binary should use a custom launcher. <p>If this attribute is set to false, the -<a href="/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related +<a href="/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related <a href="/docs/user-manual#flag--java_launcher"><code>--java_launcher</code></a> flag -will be ignored for this target. - </td> - </tr> - <tr> - <td id="java_test.use_testrunner"> - <code>use_testrunner</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - Use the test runner (by default +will be ignored for this target.</p></td> +</tr> +<tr> +<td id="java_test.use_testrunner"><code>use_testrunner</code></td> +<td><p>Boolean; default is <code>True</code></p> +Use the test runner (by default <code>com.google.testing.junit.runner.BazelTestRunner</code>) class as the main entry point for a Java program, and provide the test class to the test runner as a value of <code>bazel.test_suite</code> -system property. - -<br/> +system property.<br /> You can use this to override the default behavior, which is to use test runner for <code>java_test</code> rules, -and not use it for <code>java_binary</code> rules. It is unlikely -you will want to do this. One use is for <code>AllTest</code> +and not use it for <code>java_binary</code> rules. It is unlikely +you will want to do this. One use is for <code>AllTest</code> rules that are invoked by another rule (to set up a database -before running the tests, for example). The <code>AllTest</code> +before running the tests, for example). The <code>AllTest</code> rule must be declared as a <code>java_binary</code>, but should still use the test runner as its main entry point. +The name of a test runner class can be overridden with <code>main_class</code> attribute.</td> +</tr> +</tbody> +</table> -The name of a test runner class can be overridden with <code>main_class</code> attribute. - </td> - </tr> - </tbody> - </table> - <h2 id="java_package_configuration"> - java_package_configuration - </h2> +## java_package_configuration - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_package_configuration.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_package_configuration.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <pre class="rule-signature">java_package_configuration(<a href="#java_package_configuration.name">name</a>, <a href="#java_package_configuration.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_package_configuration.javacopts">javacopts</a>, <a href="#java_package_configuration.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_package_configuration.packages">packages</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_package_configuration.system">system</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +``` rule-signature +java_package_configuration(name, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, javacopts, output_licenses, package_metadata, packages, restricted_to, system, tags, target_compatible_with, testonly, toolchains, visibility) +``` - <p> Configuration to apply to a set of packages. Configurations can be added to -<code><a href="/reference/be/java.html#java_toolchain.javacopts">java_toolchain.javacopts</a></code>s. -</p> +[`java_toolchain.javacopts`](/reference/be/java.html#java_toolchain.javacopts)s. + +#### Example: + +``` code -<h4 id="java_package_configuration_example">Example:</h4> -<pre class="code"> -<code class="lang-starlark"> java_package_configuration( name = "my_configuration", @@ -1585,217 +1070,142 @@ java_toolchain( ] ) -</code> -</pre> - - <h3 id="java_package_configuration_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="java_package_configuration.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_package_configuration.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this configuration at runtime. - </td> - </tr> - <tr> - <td id="java_package_configuration.javacopts"> - <code>javacopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Java compiler flags. - </td> - </tr> - <tr> - <td id="java_package_configuration.output_licenses"> - <code>output_licenses</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="java_package_configuration.packages"> - <code>packages</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The set of <code><a href="/reference/be/functions.html#package_group">package_group</a></code>s -the configuration should be applied to. - </td> - </tr> - <tr> - <td id="java_package_configuration.system"> - <code>system</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Corresponds to javac's --system flag. - </td> - </tr> - </tbody> - </table> - <h2 id="java_plugin"> - java_plugin - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_plugin.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_plugin(<a href="#java_plugin.name">name</a>, <a href="#java_plugin.deps">deps</a>, <a href="#java_plugin.srcs">srcs</a>, <a href="#java_plugin.data">data</a>, <a href="#java_plugin.resources">resources</a>, <a href="#java_plugin.add_exports">add_exports</a>, <a href="#java_plugin.add_opens">add_opens</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_plugin.bootclasspath">bootclasspath</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_plugin.generates_api">generates_api</a>, <a href="#java_plugin.javabuilder_jvm_flags">javabuilder_jvm_flags</a>, <a href="#java_plugin.javacopts">javacopts</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_plugin.neverlink">neverlink</a>, <a href="#java_plugin.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_plugin.plugins">plugins</a>, <a href="#java_plugin.processor_class">processor_class</a>, <a href="#java_plugin.proguard_specs">proguard_specs</a>, <a href="#java_plugin.resource_strip_prefix">resource_strip_prefix</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> - <code>java_plugin</code> defines plugins for the Java compiler run by Bazel. The - only supported kind of plugins are annotation processors. A <code>java_library</code> or - <code>java_binary</code> rule can run plugins by depending on them via the <code>plugins</code> - attribute. A <code>java_library</code> can also automatically export plugins to libraries that - directly depend on it using - <code><a href="#java_library-exported_plugins">exported_plugins</a></code>. -</p> - -<h4 id="java_plugin_implicit_outputs">Implicit output targets</h4> - <ul> - <li><code><var>libname</var>.jar</code>: A Java archive.</li> - </ul> - -<p>Arguments are a subset of (and with identical semantics to) those of -<a href="/reference/be/java.html#java_library">java_library()</a>, -except for the addition of the <code>processor_class</code> and -<code>generates_api</code> arguments.</p> - - <h3 id="java_plugin_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="java_plugin.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_plugin.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of libraries to link into this library. +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_package_configuration.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_package_configuration.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this configuration at runtime.</td> +</tr> +<tr> +<td id="java_package_configuration.javacopts"><code>javacopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Java compiler flags.</td> +</tr> +<tr> +<td id="java_package_configuration.output_licenses"><code>output_licenses</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="java_package_configuration.packages"><code>packages</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The set of <a href="/reference/be/functions.html#package_group"><code>package_group</code></a>s +the configuration should be applied to.</td> +</tr> +<tr> +<td id="java_package_configuration.system"><code>system</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Corresponds to javac's --system flag.</td> +</tr> +</tbody> +</table> + +## java_plugin + +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_plugin.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_plugin(name, deps, srcs, data, resources, add_exports, add_opens, aspect_hints, bootclasspath, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, generates_api, javabuilder_jvm_flags, javacopts, licenses, neverlink, output_licenses, package_metadata, plugins, processor_class, proguard_specs, resource_strip_prefix, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`java_plugin` defines plugins for the Java compiler run by Bazel. The +only supported kind of plugins are annotation processors. A `java_library` or +`java_binary` rule can run plugins by depending on them via the `plugins` +attribute. A `java_library` can also automatically export plugins to libraries that +directly depend on it using +[`exported_plugins`](#java_library-exported_plugins). + +#### Implicit output targets + +- `libname``.jar`: A Java archive. + +Arguments are a subset of (and with identical semantics to) those of +[java_library()](/reference/be/java.html#java_library), +except for the addition of the `processor_class` and +`generates_api` arguments. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_plugin.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_plugin.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of libraries to link into this library. See general comments about <code>deps</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by most build rules</a>. -<p> - The jars built by <code>java_library</code> rules listed in <code>deps</code> will be on - the compile-time classpath of this rule. Furthermore the transitive closure of their - <code>deps</code>, <code>runtime_deps</code> and <code>exports</code> will be on the - runtime classpath. -</p> -<p> - By contrast, targets in the <code>data</code> attribute are included in the runfiles but - on neither the compile-time nor runtime classpath. -</p> - </td> - </tr> - <tr> - <td id="java_plugin.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of source files that are processed to create the target. +<p>The jars built by <code>java_library</code> rules listed in <code>deps</code> will be on +the compile-time classpath of this rule. Furthermore the transitive closure of their +<code>deps</code>, <code>runtime_deps</code> and <code>exports</code> will be on the +runtime classpath.</p> +<p>By contrast, targets in the <code>data</code> attribute are included in the runfiles but +on neither the compile-time nor runtime classpath.</p></td> +</tr> +<tr> +<td id="java_plugin.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. -<p> -Source files of type <code>.java</code> are compiled. In case of generated +<p>Source files of type <code>.java</code> are compiled. In case of generated <code>.java</code> files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the <code>outs</code> of the generating rule. You should not list the generating rule in <code>deps</code> -because it is a no-op. -</p> -<p> -Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if -you need to generate a set of <code>.java</code> files with a genrule.) -</p> -<p> -Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates +because it is a no-op.</p> +<p>Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if +you need to generate a set of <code>.java</code> files with a genrule.)</p> +<p>Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates any of the files listed above, they will be used the same way as described for source -files. -</p> -<p> -Source files of type <code>.properties</code> are treated as resources. -</p> - +files.</p> +<p>Source files of type <code>.properties</code> are treated as resources.</p> <p>All other files are ignored, as long as there is at least one file of a file type described above. Otherwise an error is raised.</p> - -<p> -This argument is almost always required, except if you specify the <code>runtime_deps</code> argument. -</p> - </td> - </tr> - <tr> - <td id="java_plugin.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files needed by this library at runtime. +<p>This argument is almost always required, except if you specify the <code>runtime_deps</code> argument.</p></td> +</tr> +<tr> +<td id="java_plugin.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files needed by this library at runtime. See general comments about <code>data</code> at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by most build rules</a>. -<p> - When building a <code>java_library</code>, Bazel doesn't put these files anywhere; if the - <code>data</code> files are generated files then Bazel generates them. When building a - test that depends on this <code>java_library</code> Bazel copies or links the - <code>data</code> files into the runfiles area. -</p> - </td> - </tr> - <tr> - <td id="java_plugin.resources"> - <code>resources</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of data files to include in a Java jar. -<p> -Resources may be source files or generated files. -</p> - -<p> -If resources are specified, they will be bundled in the jar along with the usual +<p>When building a <code>java_library</code>, Bazel doesn't put these files anywhere; if the +<code>data</code> files are generated files then Bazel generates them. When building a +test that depends on this <code>java_library</code> Bazel copies or links the +<code>data</code> files into the runfiles area.</p></td> +</tr> +<tr> +<td id="java_plugin.resources"><code>resources</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of data files to include in a Java jar. +<p>Resources may be source files or generated files.</p> +<p>If resources are specified, they will be bundled in the jar along with the usual <code>.class</code> files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's <a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, @@ -1804,192 +1214,130 @@ found, Bazel then looks for the topmost directory named "java" or "javatests" (s example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, however, the <code>resource_strip_prefix</code> attribute can be used to specify a -specific alternative directory for resource files. - </td> - </tr> - <tr> - <td id="java_plugin.add_exports"> - <code>add_exports</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-exports= flags. - </td> - </tr> - <tr> - <td id="java_plugin.add_opens"> - <code>add_opens</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Allow this library to reflectively access the given <code>module</code> or +specific alternative directory for resource files.</p></td> +</tr> +<tr> +<td id="java_plugin.add_exports"><code>add_exports</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to access the given <code>module</code> or <code>package</code>. +<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> +</tr> +<tr> +<td id="java_plugin.add_opens"><code>add_opens</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Allow this library to reflectively access the given <code>module</code> or <code>package</code>. -<p> -This corresponds to the javac and JVM --add-opens= flags. - </td> - </tr> - <tr> - <td id="java_plugin.bootclasspath"> - <code>bootclasspath</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Restricted API, do not use! - </td> - </tr> - <tr> - <td id="java_plugin.generates_api"> - <code>generates_api</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - This attribute marks annotation processors that generate API code. +<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> +</tr> +<tr> +<td id="java_plugin.bootclasspath"><code>bootclasspath</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Restricted API, do not use!</td> +</tr> +<tr> +<td id="java_plugin.generates_api"><code>generates_api</code></td> +<td><p>Boolean; default is <code>False</code></p> +This attribute marks annotation processors that generate API code. <p>If a rule uses an API-generating annotation processor, other rules depending on it can refer to the generated code only if their compilation actions are scheduled after the generating rule. This attribute instructs Bazel to introduce scheduling constraints when ---java_header_compilation is enabled. -<p><em class="harmful">WARNING: This attribute affects build -performance, use it only if necessary.</em></p> - </td> - </tr> - <tr> - <td id="java_plugin.javabuilder_jvm_flags"> - <code>javabuilder_jvm_flags</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Restricted API, do not use! - </td> - </tr> - <tr> - <td id="java_plugin.javacopts"> - <code>javacopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra compiler options for this library. +--java_header_compilation is enabled.</p> +<p><em>WARNING: This attribute affects build +performance, use it only if necessary.</em></p></td> +</tr> +<tr> +<td id="java_plugin.javabuilder_jvm_flags"><code>javabuilder_jvm_flags</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Restricted API, do not use!</td> +</tr> +<tr> +<td id="java_plugin.javacopts"><code>javacopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra compiler options for this library. Subject to <a href="make-variables.html">"Make variable"</a> substitution and <a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>These compiler options are passed to javac after the global compiler options.</p> - </td> - </tr> - <tr> - <td id="java_plugin.neverlink"> - <code>neverlink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Whether this library should only be used for compilation and not at runtime. +<p>These compiler options are passed to javac after the global compiler options.</p></td> +</tr> +<tr> +<td id="java_plugin.neverlink"><code>neverlink</code></td> +<td><p>Boolean; default is <code>False</code></p> +Whether this library should only be used for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of such libraries are the IDE APIs for IDE plug-ins or <code>tools.jar</code> for anything running on a standard JDK. -<p> - Note that <code>neverlink = True</code> does not prevent the compiler from inlining material - from this library into compilation targets that depend on it, as permitted by the Java - Language Specification (e.g., <code>static final</code> constants of <code>String</code> - or of primitive types). The preferred use case is therefore when the runtime library is - identical to the compilation library. -</p> -<p> - If the runtime library differs from the compilation library then you must ensure that it - differs only in places that the JLS forbids compilers to inline (and that must hold for - all future versions of the JLS). -</p> - </td> - </tr> - <tr> - <td id="java_plugin.output_licenses"> - <code>output_licenses</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="java_plugin.plugins"> - <code>plugins</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Java compiler plugins to run at compile-time. +<p>Note that <code>neverlink = True</code> does not prevent the compiler from inlining material +from this library into compilation targets that depend on it, as permitted by the Java +Language Specification (e.g., <code>static final</code> constants of <code>String</code> +or of primitive types). The preferred use case is therefore when the runtime library is +identical to the compilation library.</p> +<p>If the runtime library differs from the compilation library then you must ensure that it +differs only in places that the JLS forbids compilers to inline (and that must hold for +all future versions of the JLS).</p></td> +</tr> +<tr> +<td id="java_plugin.output_licenses"><code>output_licenses</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="java_plugin.plugins"><code>plugins</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Java compiler plugins to run at compile-time. Every <code>java_plugin</code> specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use -<code><a href="#java_library.exported_plugins">exported_plugins</a></code>. Resources -generated by the plugin will be included in the resulting jar of this rule. - </td> - </tr> - <tr> - <td id="java_plugin.processor_class"> - <code>processor_class</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The processor class is the fully qualified type of the class that the Java compiler should +<a href="#java_library.exported_plugins"><code>exported_plugins</code></a>. Resources +generated by the plugin will be included in the resulting jar of this rule.</td> +</tr> +<tr> +<td id="java_plugin.processor_class"><code>processor_class</code></td> +<td><p>String; default is <code>""</code></p> +The processor class is the fully qualified type of the class that the Java compiler should use as entry point to the annotation processor. If not specified, this rule will not contribute an annotation processor to the Java compiler's annotation processing, but its runtime classpath will still be included on the compiler's annotation processor path. (This is primarily intended for use by <a href="https://errorprone.info/docs/plugins">Error Prone plugins</a>, which are loaded from the annotation processor path using -<a href="https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html"> -java.util.ServiceLoader</a>.) - </td> - </tr> - <tr> - <td id="java_plugin.proguard_specs"> - <code>proguard_specs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Files to be used as Proguard specification. +<a href="https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html">java.util.ServiceLoader</a>.)</td> +</tr> +<tr> +<td id="java_plugin.proguard_specs"><code>proguard_specs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any <code>android_binary</code> target depending on this library. - The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in -<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges. - </td> - </tr> - <tr> - <td id="java_plugin.resource_strip_prefix"> - <code>resource_strip_prefix</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The path prefix to strip from Java resources. -<p> -If specified, this path prefix is stripped from every file in the <code>resources</code> +<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges.</td> +</tr> +<tr> +<td id="java_plugin.resource_strip_prefix"><code>resource_strip_prefix</code></td> +<td><p>String; default is <code>""</code></p> +The path prefix to strip from Java resources. +<p>If specified, this path prefix is stripped from every file in the <code>resources</code> attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at -<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>. -</p> - </td> - </tr> - </tbody> - </table> - <h2 id="java_runtime"> - java_runtime - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_runtime.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_runtime(<a href="#java_runtime.name">name</a>, <a href="#java_runtime.srcs">srcs</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_runtime.default_cds">default_cds</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_runtime.hermetic_srcs">hermetic_srcs</a>, <a href="#java_runtime.hermetic_static_libs">hermetic_static_libs</a>, <a href="#java_runtime.java">java</a>, <a href="#java_runtime.java_home">java_home</a>, <a href="#java_runtime.lib_ct_sym">lib_ct_sym</a>, <a href="#java_runtime.lib_modules">lib_modules</a>, <a href="#java_runtime.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="#java_runtime.version">version</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> +<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.</p></td> +</tr> +</tbody> +</table> + +## java_runtime + +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_runtime.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_runtime(name, srcs, aspect_hints, compatible_with, default_cds, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hermetic_srcs, hermetic_static_libs, java, java_home, lib_ct_sym, lib_modules, output_licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, version, visibility) +``` + Specifies the configuration for a Java runtime. -</p> -<h4 id="java_runtime_example">Example:</h4> +#### Example: + +``` code + -<pre class="code"> -<code class="lang-starlark"> java_runtime( name = "jdk-9-ea+153", @@ -1997,273 +1345,184 @@ java_runtime( java_home = "jdk9-ea+153", ) -</code> -</pre> - - <h3 id="java_runtime_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="java_runtime.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_runtime.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - All files in the runtime. - </td> - </tr> - <tr> - <td id="java_runtime.default_cds"> - <code>default_cds</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Default CDS archive for hermetic <code>java_runtime</code>. When hermetic +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_runtime.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_runtime.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +All files in the runtime.</td> +</tr> +<tr> +<td id="java_runtime.default_cds"><code>default_cds</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Default CDS archive for hermetic <code>java_runtime</code>. When hermetic is enabled for a <code>java_binary</code> target the <code>java_runtime</code> -default CDS is packaged in the hermetic deploy JAR. - </td> - </tr> - <tr> - <td id="java_runtime.hermetic_srcs"> - <code>hermetic_srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Files in the runtime needed for hermetic deployments. - </td> - </tr> - <tr> - <td id="java_runtime.hermetic_static_libs"> - <code>hermetic_static_libs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The libraries that are statically linked with the launcher for hermetic deployments - </td> - </tr> - <tr> - <td id="java_runtime.java"> - <code>java</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - The path to the java executable. - </td> - </tr> - <tr> - <td id="java_runtime.java_home"> - <code>java_home</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The path to the root of the runtime. +default CDS is packaged in the hermetic deploy JAR.</td> +</tr> +<tr> +<td id="java_runtime.hermetic_srcs"><code>hermetic_srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Files in the runtime needed for hermetic deployments.</td> +</tr> +<tr> +<td id="java_runtime.hermetic_static_libs"><code>hermetic_static_libs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The libraries that are statically linked with the launcher for hermetic deployments</td> +</tr> +<tr> +<td id="java_runtime.java"><code>java</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +The path to the java executable.</td> +</tr> +<tr> +<td id="java_runtime.java_home"><code>java_home</code></td> +<td><p>String; default is <code>""</code></p> +The path to the root of the runtime. Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. If this path is absolute, the rule denotes a non-hermetic Java runtime with a well-known -path. In that case, the <code>srcs</code> and <code>java</code> attributes must be empty. - </td> - </tr> - <tr> - <td id="java_runtime.lib_ct_sym"> - <code>lib_ct_sym</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - The lib/ct.sym file needed for compilation with <code>--release</code>. If not specified and +path. In that case, the <code>srcs</code> and <code>java</code> attributes must be empty.</td> +</tr> +<tr> +<td id="java_runtime.lib_ct_sym"><code>lib_ct_sym</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +The lib/ct.sym file needed for compilation with <code>--release</code>. If not specified and there is exactly one file in <code>srcs</code> whose path ends with -<code>/lib/ct.sym</code>, that file is used. - </td> - </tr> - <tr> - <td id="java_runtime.lib_modules"> - <code>lib_modules</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - The lib/modules file needed for hermetic deployments. - </td> - </tr> - <tr> - <td id="java_runtime.output_licenses"> - <code>output_licenses</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="java_runtime.version"> - <code>version</code> - </td> - <td> - <p>Integer; default is <code>0</code></p> - The feature version of the Java runtime. I.e., the integer returned by -<code>Runtime.version().feature()</code>. - </td> - </tr> - </tbody> - </table> - <h2 id="java_single_jar"> - java_single_jar - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/java_single_jar.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_single_jar(<a href="#java_single_jar.name">name</a>, <a href="#java_single_jar.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#java_single_jar.compress">compress</a>, <a href="#java_single_jar.deploy_env">deploy_env</a>, <a href="#java_single_jar.deploy_manifest_lines">deploy_manifest_lines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#java_single_jar.exclude_build_data">exclude_build_data</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_single_jar.multi_release">multi_release</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - Collects Java dependencies and jar files into a single jar - -`java_single_jar` collects Java dependencies and jar files into a single jar. +<code>/lib/ct.sym</code>, that file is used.</td> +</tr> +<tr> +<td id="java_runtime.lib_modules"><code>lib_modules</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +The lib/modules file needed for hermetic deployments.</td> +</tr> +<tr> +<td id="java_runtime.output_licenses"><code>output_licenses</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="java_runtime.version"><code>version</code></td> +<td><p>Integer; default is <code>0</code></p> +The feature version of the Java runtime. I.e., the integer returned by +<code>Runtime.version().feature()</code>.</td> +</tr> +</tbody> +</table> + +## java_single_jar + +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/java_single_jar.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_single_jar(name, deps, aspect_hints, compatible_with, compress, deploy_env, deploy_manifest_lines, deprecation, exclude_build_data, exec_compatible_with, exec_group_compatible_with, exec_properties, features, multi_release, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Collects Java dependencies and jar files into a single jar +\`java_single_jar\` collects Java dependencies and jar files into a single jar. This is similar to java_binary with everything related to executables disabled, and provides an alternative to the java_binary "deploy jar hack". - -## Example - -```skylark +\## Example +\`\`\`skylark load("//tools/build_defs/java_single_jar:java_single_jar.bzl", "java_single_jar") - java_single_jar( - name = "my_single_jar", - deps = [ - "//java/com/google/foo", - "//java/com/google/bar", - ], +name = "my_single_jar", +deps = \[ +"//java/com/google/foo", +"//java/com/google/bar", +\], ) -``` - +\`\`\` Outputs: - {name}.jar: A single jar containing all of the inputs. - - <h3 id="java_single_jar_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="java_single_jar.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_single_jar.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The Java targets (including java_import and java_library) to collect +{name}.jar: A single jar containing all of the inputs. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_single_jar.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_single_jar.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The Java targets (including java_import and java_library) to collect transitive dependencies from. Runtime dependencies are collected via deps, exports, and runtime_deps. Resources are also collected. -Native cc_library or java_wrap_cc dependencies are not. - </td> - </tr> - <tr> - <td id="java_single_jar.compress"> - <code>compress</code> - </td> - <td> - <p>String; default is <code>"preserve"</code></p> - Whether to always deflate ("yes"), always store ("no"), or pass +Native cc_library or java_wrap_cc dependencies are not.</td> +</tr> +<tr> +<td id="java_single_jar.compress"><code>compress</code></td> +<td><p>String; default is <code>"preserve"</code></p> +Whether to always deflate ("yes"), always store ("no"), or pass through unmodified ("preserve"). The default is "preserve", and is the -most efficient option -- no extra work is done to inflate or deflate. - </td> - </tr> - <tr> - <td id="java_single_jar.deploy_env"> - <code>deploy_env</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - A list of `java_binary` or `java_single_jar` targets which represent +most efficient option -- no extra work is done to inflate or deflate.</td> +</tr> +<tr> +<td id="java_single_jar.deploy_env"><code>deploy_env</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +A list of `java_binary` or `java_single_jar` targets which represent the deployment environment for this binary. - Set this attribute when building a plugin which will be loaded by another `java_binary`. +`deploy_env` dependencies are excluded from the jar built by this rule.</td> +</tr> +<tr> +<td id="java_single_jar.deploy_manifest_lines"><code>deploy_manifest_lines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +A list of lines to add to the <code>META-INF/manifest.mf</code> file.</td> +</tr> +<tr> +<td id="java_single_jar.exclude_build_data"><code>exclude_build_data</code></td> +<td><p>Boolean; default is <code>True</code></p> +Whether to omit the build-data.properties file generated +by default.</td> +</tr> +<tr> +<td id="java_single_jar.multi_release"><code>multi_release</code></td> +<td><p>Boolean; default is <code>True</code></p> +Whether to enable Multi-Release output jars.</td> +</tr> +</tbody> +</table> + +## java_toolchain + +<a href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_toolchain.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_toolchain(name, android_lint_data, android_lint_jvm_opts, android_lint_opts, android_lint_package_configuration, android_lint_runner, aspect_hints, bootclasspath, compatible_javacopts, compatible_with, deprecation, deps_checker, exec_compatible_with, exec_group_compatible_with, exec_properties, features, forcibly_disable_header_compilation, genclass, header_compiler, header_compiler_builtin_processors, header_compiler_direct, ijar, jacocorunner, java_runtime, javabuilder, javabuilder_data, javabuilder_jvm_opts, javac_supports_multiplex_workers, javac_supports_worker_cancellation, javac_supports_worker_multiplex_sandboxing, javac_supports_workers, javacopts, jspecify_implicit_deps, jspecify_javacopts, jspecify_packages, jspecify_processor, jspecify_processor_class, jspecify_stubs, jvm_opts, licenses, misc, oneversion, oneversion_allowlist, oneversion_allowlist_for_tests, oneversion_whitelist, package_configuration, package_metadata, proguard_allowlister, reduced_classpath_incompatible_processors, restricted_to, singlejar, source_version, tags, target_compatible_with, target_version, testonly, timezone_data, toolchains, tools, turbine_data, turbine_jvm_opts, visibility, xlint) +``` -`deploy_env` dependencies are excluded from the jar built by this rule. - </td> - </tr> - <tr> - <td id="java_single_jar.deploy_manifest_lines"> - <code>deploy_manifest_lines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - A list of lines to add to the <code>META-INF/manifest.mf</code> file. - </td> - </tr> - <tr> - <td id="java_single_jar.exclude_build_data"> - <code>exclude_build_data</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - Whether to omit the build-data.properties file generated -by default. - </td> - </tr> - <tr> - <td id="java_single_jar.multi_release"> - <code>multi_release</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - Whether to enable Multi-Release output jars. - </td> - </tr> - </tbody> - </table> - <h2 id="java_toolchain"> - java_toolchain - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_toolchain.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_toolchain(<a href="#java_toolchain.name">name</a>, <a href="#java_toolchain.android_lint_data">android_lint_data</a>, <a href="#java_toolchain.android_lint_jvm_opts">android_lint_jvm_opts</a>, <a href="#java_toolchain.android_lint_opts">android_lint_opts</a>, <a href="#java_toolchain.android_lint_package_configuration">android_lint_package_configuration</a>, <a href="#java_toolchain.android_lint_runner">android_lint_runner</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#java_toolchain.bootclasspath">bootclasspath</a>, <a href="#java_toolchain.compatible_javacopts">compatible_javacopts</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#java_toolchain.deps_checker">deps_checker</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#java_toolchain.forcibly_disable_header_compilation">forcibly_disable_header_compilation</a>, <a href="#java_toolchain.genclass">genclass</a>, <a href="#java_toolchain.header_compiler">header_compiler</a>, <a href="#java_toolchain.header_compiler_builtin_processors">header_compiler_builtin_processors</a>, <a href="#java_toolchain.header_compiler_direct">header_compiler_direct</a>, <a href="#java_toolchain.ijar">ijar</a>, <a href="#java_toolchain.jacocorunner">jacocorunner</a>, <a href="#java_toolchain.java_runtime">java_runtime</a>, <a href="#java_toolchain.javabuilder">javabuilder</a>, <a href="#java_toolchain.javabuilder_data">javabuilder_data</a>, <a href="#java_toolchain.javabuilder_jvm_opts">javabuilder_jvm_opts</a>, <a href="#java_toolchain.javac_supports_multiplex_workers">javac_supports_multiplex_workers</a>, <a href="#java_toolchain.javac_supports_worker_cancellation">javac_supports_worker_cancellation</a>, <a href="#java_toolchain.javac_supports_worker_multiplex_sandboxing">javac_supports_worker_multiplex_sandboxing</a>, <a href="#java_toolchain.javac_supports_workers">javac_supports_workers</a>, <a href="#java_toolchain.javacopts">javacopts</a>, <a href="#java_toolchain.jspecify_implicit_deps">jspecify_implicit_deps</a>, <a href="#java_toolchain.jspecify_javacopts">jspecify_javacopts</a>, <a href="#java_toolchain.jspecify_packages">jspecify_packages</a>, <a href="#java_toolchain.jspecify_processor">jspecify_processor</a>, <a href="#java_toolchain.jspecify_processor_class">jspecify_processor_class</a>, <a href="#java_toolchain.jspecify_stubs">jspecify_stubs</a>, <a href="#java_toolchain.jvm_opts">jvm_opts</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#java_toolchain.misc">misc</a>, <a href="#java_toolchain.oneversion">oneversion</a>, <a href="#java_toolchain.oneversion_allowlist">oneversion_allowlist</a>, <a href="#java_toolchain.oneversion_allowlist_for_tests">oneversion_allowlist_for_tests</a>, <a href="#java_toolchain.oneversion_whitelist">oneversion_whitelist</a>, <a href="#java_toolchain.package_configuration">package_configuration</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#java_toolchain.proguard_allowlister">proguard_allowlister</a>, <a href="#java_toolchain.reduced_classpath_incompatible_processors">reduced_classpath_incompatible_processors</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#java_toolchain.singlejar">singlejar</a>, <a href="#java_toolchain.source_version">source_version</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="#java_toolchain.target_version">target_version</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#java_toolchain.timezone_data">timezone_data</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="#java_toolchain.tools">tools</a>, <a href="#java_toolchain.turbine_data">turbine_data</a>, <a href="#java_toolchain.turbine_jvm_opts">turbine_jvm_opts</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#java_toolchain.xlint">xlint</a>)</pre> - - <p> Specifies the configuration for the Java compiler. Which toolchain to be used can be changed through the --java_toolchain argument. Normally you should not write those kind of rules unless you want to tune your Java compiler. -</p> -<h4>Examples</h4> +#### Examples + +A simple example would be: + +``` code -<p>A simple example would be: -</p> -<pre class="code"> -<code class="lang-starlark"> java_toolchain( name = "toolchain", @@ -2274,467 +1533,266 @@ java_toolchain( javacopts = [ "-g" ], javabuilder = ":JavaBuilder_deploy.jar", ) -</code> -</pre> - - <h3 id="java_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="java_toolchain.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_toolchain.android_lint_data"> - <code>android_lint_data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Labels of tools available for label-expansion in android_lint_jvm_opts. - </td> - </tr> - <tr> - <td id="java_toolchain.android_lint_jvm_opts"> - <code>android_lint_jvm_opts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - The list of arguments for the JVM when invoking Android Lint. - </td> - </tr> - <tr> - <td id="java_toolchain.android_lint_opts"> - <code>android_lint_opts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - The list of Android Lint arguments. - </td> - </tr> - <tr> - <td id="java_toolchain.android_lint_package_configuration"> - <code>android_lint_package_configuration</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Android Lint Configuration that should be applied to the specified package groups. - </td> - </tr> - <tr> - <td id="java_toolchain.android_lint_runner"> - <code>android_lint_runner</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the Android Lint runner, if any. - </td> - </tr> - <tr> - <td id="java_toolchain.bootclasspath"> - <code>bootclasspath</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. - </td> - </tr> - <tr> - <td id="java_toolchain.compatible_javacopts"> - <code>compatible_javacopts</code> - </td> - <td> - <p>null; default is <code>{}</code></p> - Internal API, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.deps_checker"> - <code>deps_checker</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the ImportDepsChecker deploy jar. - </td> - </tr> - <tr> - <td id="java_toolchain.forcibly_disable_header_compilation"> - <code>forcibly_disable_header_compilation</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Overrides --java_header_compilation to disable header compilation on platforms that do not -support it, e.g. JDK 7 Bazel. - </td> - </tr> - <tr> - <td id="java_toolchain.genclass"> - <code>genclass</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the GenClass deploy jar. - </td> - </tr> - <tr> - <td id="java_toolchain.header_compiler"> - <code>header_compiler</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the header compiler. Required if --java_header_compilation is enabled. - </td> - </tr> - <tr> - <td id="java_toolchain.header_compiler_builtin_processors"> - <code>header_compiler_builtin_processors</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Internal API, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.header_compiler_direct"> - <code>header_compiler_direct</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Optional label of the header compiler to use for direct classpath actions that do not -include any API-generating annotation processors. +``` -<p>This tool does not support annotation processing. - </td> - </tr> - <tr> - <td id="java_toolchain.ijar"> - <code>ijar</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the ijar executable. - </td> - </tr> - <tr> - <td id="java_toolchain.jacocorunner"> - <code>jacocorunner</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the JacocoCoverageRunner deploy jar. - </td> - </tr> - <tr> - <td id="java_toolchain.java_runtime"> - <code>java_runtime</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - The java_runtime to use with this toolchain. It defaults to java_runtime -in execution configuration. - </td> - </tr> - <tr> - <td id="java_toolchain.javabuilder"> - <code>javabuilder</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the JavaBuilder deploy jar. - </td> - </tr> - <tr> - <td id="java_toolchain.javabuilder_data"> - <code>javabuilder_data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Labels of data available for label-expansion in javabuilder_jvm_opts. - </td> - </tr> - <tr> - <td id="java_toolchain.javabuilder_jvm_opts"> - <code>javabuilder_jvm_opts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - The list of arguments for the JVM when invoking JavaBuilder. - </td> - </tr> - <tr> - <td id="java_toolchain.javac_supports_multiplex_workers"> - <code>javac_supports_multiplex_workers</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - True if JavaBuilder supports running as a multiplex persistent worker, false if it doesn't. - </td> - </tr> - <tr> - <td id="java_toolchain.javac_supports_worker_cancellation"> - <code>javac_supports_worker_cancellation</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - True if JavaBuilder supports cancellation of persistent workers, false if it doesn't. - </td> - </tr> - <tr> - <td id="java_toolchain.javac_supports_worker_multiplex_sandboxing"> - <code>javac_supports_worker_multiplex_sandboxing</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - True if JavaBuilder supports running as a multiplex persistent worker with sandboxing, false if it doesn't. - </td> - </tr> - <tr> - <td id="java_toolchain.javac_supports_workers"> - <code>javac_supports_workers</code> - </td> - <td> - <p>Boolean; default is <code>True</code></p> - True if JavaBuilder supports running as a persistent worker, false if it doesn't. - </td> - </tr> - <tr> - <td id="java_toolchain.javacopts"> - <code>javacopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - The list of extra arguments for the Java compiler. Please refer to the Java compiler -documentation for the extensive list of possible Java compiler flags. - </td> - </tr> - <tr> - <td id="java_toolchain.jspecify_implicit_deps"> - <code>jspecify_implicit_deps</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Experimental, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.jspecify_javacopts"> - <code>jspecify_javacopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Experimental, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.jspecify_packages"> - <code>jspecify_packages</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Experimental, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.jspecify_processor"> - <code>jspecify_processor</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Experimental, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.jspecify_processor_class"> - <code>jspecify_processor_class</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Experimental, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.jspecify_stubs"> - <code>jspecify_stubs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Experimental, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.jvm_opts"> - <code>jvm_opts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - The list of arguments for the JVM when invoking the Java compiler. Please refer to the Java -virtual machine documentation for the extensive list of possible flags for this option. - </td> - </tr> - <tr> - <td id="java_toolchain.misc" class="deprecated"> - <code>misc</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Deprecated: use javacopts instead - </td> - </tr> - <tr> - <td id="java_toolchain.oneversion"> - <code>oneversion</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the one-version enforcement binary. - </td> - </tr> - <tr> - <td id="java_toolchain.oneversion_allowlist"> - <code>oneversion_allowlist</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the one-version allowlist. - </td> - </tr> - <tr> - <td id="java_toolchain.oneversion_allowlist_for_tests"> - <code>oneversion_allowlist_for_tests</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the one-version allowlist for tests. - </td> - </tr> - <tr> - <td id="java_toolchain.oneversion_whitelist" class="deprecated"> - <code>oneversion_whitelist</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Deprecated: use oneversion_allowlist instead - </td> - </tr> - <tr> - <td id="java_toolchain.package_configuration"> - <code>package_configuration</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Configuration that should be applied to the specified package groups. - </td> - </tr> - <tr> - <td id="java_toolchain.proguard_allowlister"> - <code>proguard_allowlister</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/jdk:proguard_whitelister"</code></p> - Label of the Proguard allowlister. - </td> - </tr> - <tr> - <td id="java_toolchain.reduced_classpath_incompatible_processors"> - <code>reduced_classpath_incompatible_processors</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Internal API, do not use! - </td> - </tr> - <tr> - <td id="java_toolchain.singlejar"> - <code>singlejar</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of the SingleJar deploy jar. - </td> - </tr> - <tr> - <td id="java_toolchain.source_version"> - <code>source_version</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The Java source version (e.g., '6' or '7'). It specifies which set of code structures -are allowed in the Java source code. - </td> - </tr> - <tr> - <td id="java_toolchain.target_version"> - <code>target_version</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The Java target version (e.g., '6' or '7'). It specifies for which Java runtime the class -should be build. - </td> - </tr> - <tr> - <td id="java_toolchain.timezone_data"> - <code>timezone_data</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Label of a resource jar containing timezone data. If set, the timezone data is added as an -implicitly runtime dependency of all java_binary rules. - </td> - </tr> - <tr> - <td id="java_toolchain.tools"> - <code>tools</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Labels of tools available for label-expansion in jvm_opts. - </td> - </tr> - <tr> - <td id="java_toolchain.turbine_data"> - <code>turbine_data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Labels of data available for label-expansion in turbine_jvm_opts. - </td> - </tr> - <tr> - <td id="java_toolchain.turbine_jvm_opts"> - <code>turbine_jvm_opts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - The list of arguments for the JVM when invoking turbine. - </td> - </tr> - <tr> - <td id="java_toolchain.xlint"> - <code>xlint</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - The list of warning to add or removes from default list. Precedes it with a dash to -removes it. Please see the Javac documentation on the -Xlint options for more information. - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_toolchain.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_toolchain.android_lint_data"><code>android_lint_data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Labels of tools available for label-expansion in android_lint_jvm_opts.</td> +</tr> +<tr> +<td id="java_toolchain.android_lint_jvm_opts"><code>android_lint_jvm_opts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +The list of arguments for the JVM when invoking Android Lint.</td> +</tr> +<tr> +<td id="java_toolchain.android_lint_opts"><code>android_lint_opts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +The list of Android Lint arguments.</td> +</tr> +<tr> +<td id="java_toolchain.android_lint_package_configuration"><code>android_lint_package_configuration</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Android Lint Configuration that should be applied to the specified package groups.</td> +</tr> +<tr> +<td id="java_toolchain.android_lint_runner"><code>android_lint_runner</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the Android Lint runner, if any.</td> +</tr> +<tr> +<td id="java_toolchain.bootclasspath"><code>bootclasspath</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag.</td> +</tr> +<tr> +<td id="java_toolchain.compatible_javacopts"><code>compatible_javacopts</code></td> +<td><p>null; default is <code>{}</code></p> +Internal API, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.deps_checker"><code>deps_checker</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the ImportDepsChecker deploy jar.</td> +</tr> +<tr> +<td id="java_toolchain.forcibly_disable_header_compilation"><code>forcibly_disable_header_compilation</code></td> +<td><p>Boolean; default is <code>False</code></p> +Overrides --java_header_compilation to disable header compilation on platforms that do not +support it, e.g. JDK 7 Bazel.</td> +</tr> +<tr> +<td id="java_toolchain.genclass"><code>genclass</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the GenClass deploy jar.</td> +</tr> +<tr> +<td id="java_toolchain.header_compiler"><code>header_compiler</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the header compiler. Required if --java_header_compilation is enabled.</td> +</tr> +<tr> +<td id="java_toolchain.header_compiler_builtin_processors"><code>header_compiler_builtin_processors</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Internal API, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.header_compiler_direct"><code>header_compiler_direct</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Optional label of the header compiler to use for direct classpath actions that do not +include any API-generating annotation processors. +<p>This tool does not support annotation processing.</p></td> +</tr> +<tr> +<td id="java_toolchain.ijar"><code>ijar</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the ijar executable.</td> +</tr> +<tr> +<td id="java_toolchain.jacocorunner"><code>jacocorunner</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the JacocoCoverageRunner deploy jar.</td> +</tr> +<tr> +<td id="java_toolchain.java_runtime"><code>java_runtime</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +The java_runtime to use with this toolchain. It defaults to java_runtime +in execution configuration.</td> +</tr> +<tr> +<td id="java_toolchain.javabuilder"><code>javabuilder</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the JavaBuilder deploy jar.</td> +</tr> +<tr> +<td id="java_toolchain.javabuilder_data"><code>javabuilder_data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Labels of data available for label-expansion in javabuilder_jvm_opts.</td> +</tr> +<tr> +<td id="java_toolchain.javabuilder_jvm_opts"><code>javabuilder_jvm_opts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +The list of arguments for the JVM when invoking JavaBuilder.</td> +</tr> +<tr> +<td id="java_toolchain.javac_supports_multiplex_workers"><code>javac_supports_multiplex_workers</code></td> +<td><p>Boolean; default is <code>True</code></p> +True if JavaBuilder supports running as a multiplex persistent worker, false if it doesn't.</td> +</tr> +<tr> +<td id="java_toolchain.javac_supports_worker_cancellation"><code>javac_supports_worker_cancellation</code></td> +<td><p>Boolean; default is <code>True</code></p> +True if JavaBuilder supports cancellation of persistent workers, false if it doesn't.</td> +</tr> +<tr> +<td id="java_toolchain.javac_supports_worker_multiplex_sandboxing"><code>javac_supports_worker_multiplex_sandboxing</code></td> +<td><p>Boolean; default is <code>False</code></p> +True if JavaBuilder supports running as a multiplex persistent worker with sandboxing, false if it doesn't.</td> +</tr> +<tr> +<td id="java_toolchain.javac_supports_workers"><code>javac_supports_workers</code></td> +<td><p>Boolean; default is <code>True</code></p> +True if JavaBuilder supports running as a persistent worker, false if it doesn't.</td> +</tr> +<tr> +<td id="java_toolchain.javacopts"><code>javacopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +The list of extra arguments for the Java compiler. Please refer to the Java compiler +documentation for the extensive list of possible Java compiler flags.</td> +</tr> +<tr> +<td id="java_toolchain.jspecify_implicit_deps"><code>jspecify_implicit_deps</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Experimental, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.jspecify_javacopts"><code>jspecify_javacopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Experimental, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.jspecify_packages"><code>jspecify_packages</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Experimental, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.jspecify_processor"><code>jspecify_processor</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Experimental, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.jspecify_processor_class"><code>jspecify_processor_class</code></td> +<td><p>String; default is <code>""</code></p> +Experimental, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.jspecify_stubs"><code>jspecify_stubs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Experimental, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.jvm_opts"><code>jvm_opts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +The list of arguments for the JVM when invoking the Java compiler. Please refer to the Java +virtual machine documentation for the extensive list of possible flags for this option.</td> +</tr> +<tr> +<td id="java_toolchain.misc" class="deprecated"><code>misc</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Deprecated: use javacopts instead</td> +</tr> +<tr> +<td id="java_toolchain.oneversion"><code>oneversion</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the one-version enforcement binary.</td> +</tr> +<tr> +<td id="java_toolchain.oneversion_allowlist"><code>oneversion_allowlist</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the one-version allowlist.</td> +</tr> +<tr> +<td id="java_toolchain.oneversion_allowlist_for_tests"><code>oneversion_allowlist_for_tests</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the one-version allowlist for tests.</td> +</tr> +<tr> +<td id="java_toolchain.oneversion_whitelist" class="deprecated"><code>oneversion_whitelist</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Deprecated: use oneversion_allowlist instead</td> +</tr> +<tr> +<td id="java_toolchain.package_configuration"><code>package_configuration</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Configuration that should be applied to the specified package groups.</td> +</tr> +<tr> +<td id="java_toolchain.proguard_allowlister"><code>proguard_allowlister</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/jdk:proguard_whitelister"</code></p> +Label of the Proguard allowlister.</td> +</tr> +<tr> +<td id="java_toolchain.reduced_classpath_incompatible_processors"><code>reduced_classpath_incompatible_processors</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Internal API, do not use!</td> +</tr> +<tr> +<td id="java_toolchain.singlejar"><code>singlejar</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of the SingleJar deploy jar.</td> +</tr> +<tr> +<td id="java_toolchain.source_version"><code>source_version</code></td> +<td><p>String; default is <code>""</code></p> +The Java source version (e.g., '6' or '7'). It specifies which set of code structures +are allowed in the Java source code.</td> +</tr> +<tr> +<td id="java_toolchain.target_version"><code>target_version</code></td> +<td><p>String; default is <code>""</code></p> +The Java target version (e.g., '6' or '7'). It specifies for which Java runtime the class +should be build.</td> +</tr> +<tr> +<td id="java_toolchain.timezone_data"><code>timezone_data</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Label of a resource jar containing timezone data. If set, the timezone data is added as an +implicitly runtime dependency of all java_binary rules.</td> +</tr> +<tr> +<td id="java_toolchain.tools"><code>tools</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Labels of tools available for label-expansion in jvm_opts.</td> +</tr> +<tr> +<td id="java_toolchain.turbine_data"><code>turbine_data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Labels of data available for label-expansion in turbine_jvm_opts.</td> +</tr> +<tr> +<td id="java_toolchain.turbine_jvm_opts"><code>turbine_jvm_opts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +The list of arguments for the JVM when invoking turbine.</td> +</tr> +<tr> +<td id="java_toolchain.xlint"><code>xlint</code></td> +<td><p>List of strings; default is <code>[]</code></p> +The list of warning to add or removes from default list. Precedes it with a dash to +removes it. Please see the Javac documentation on the -Xlint options for more information.</td> +</tr> +</tbody> +</table> diff --git a/reference/be/make-variables.mdx b/reference/be/make-variables.mdx index 51579c9..81f2d25 100644 --- a/reference/be/make-variables.mdx +++ b/reference/be/make-variables.mdx @@ -2,525 +2,348 @@ title: 'make-variables' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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 --> - -<!-- ============================================ - variables - ============================================ ---> -<h1 class="page-title" id="make-variables">Make Variables</h1> +# Make Variables {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm" %} -{% include "_buttons.html" %} - -<ul> - <li><a href="#use">Use</a></li> - <li><a href="#predefined_variables">Predefined variables</a></li> - <li><a href="#predefined_genrule_variables">Predefined genrule variables</a></li> - <li><a href="#predefined_label_variables">Predefined source/output path variables</a></li> - <li><a href="#custom_variables">Custom variables</a></li> -</ul> -<p> - "Make" variables are a special class of expandable string variables available - to attributes marked as <i>"Subject to 'Make variable' substitution"</i>. -</p> - -<p> - These can be used, for example, to inject specific toolchain paths into - user-constructed build actions. -</p> - -<p> - Bazel provides both <i>predefined</i> variables, which are available to all - targets, and <i>custom</i> variables, which are defined in dependency targets - and only available to targets that depend on them. -</p> - -<p> - The reason for the term "Make" is historical: the syntax and semantics of - these variables were originally intended to match <a - href="https://www.gnu.org/software/make/manual/html_node/Using-Variables.html">GNU - Make</a>. -</p> - -<h2 id="use">Use</h2> - -<p> - Attributes marked as <i>"Subject to 'Make variable' substitution"</i> can - reference the "Make" variable <code>FOO</code> as follows: -</p> - -<p> -<code>my_attr = "prefix $(FOO) suffix"</code> -</p> - -<p> - In other words, any substring matching <code>$(FOO)</code> gets expanded - to <code>FOO</code>'s value. If that value is <code>"bar"</code>, the final - string becomes: -</p> - -<p> -<code>my_attr = "prefix bar suffix"</code> -</p> - -<p> - If <code>FOO</code> doesn't correspond to a variable known to the consuming - target, Bazel fails with an error. -</p> - - -<p> - "Make" variables whose names are non-letter symbols, such as - <code>@</code>, can also be referenced using only a dollar sign, without - the parentheses. For example: -</p> - -<p> -<code>my_attr = "prefix $@ suffix"</code> -</p> - -<p> - To write <code>$</code> as a string literal (i.e. to prevent variable - expansion), write <code>$$</code>. -</p> - -<h2 id="predefined_variables">Predefined variables</h2> - -<p> - Predefined "Make" variables can be referenced by any attribute marked as - <i>"Subject to 'Make variable' substitution"</i> on any target. -</p> - -<p> - To see the list of these variables and their values for a given set of build - options, run -</p> - -<p><code>bazel info --show_make_env [build options]</code></p> - -<p> - and look at the top output lines with capital letters. -</p> - -<p><a href="https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-variables"> - See an example of predefined variables</a>.</p> - -<p><strong>Toolchain option variables</strong></p> - -<ul><!-- keep alphabetically sorted --> - <li><code>COMPILATION_MODE</code>: - <code>fastbuild</code>, <code>dbg</code>, or <code>opt</code>. (<a - href="https://bazel.build/docs/user-manual#flag--compilation_mode">more - details</a>) - </li> -</ul> - -<p><strong>Path variables</strong></p> - -<ul><!-- keep alphabetically sorted --> - <li> - <p> - <code>BINDIR</code>: The base of the generated binary tree for the target - architecture. - </p> - - <p> - Note that a different tree may be used for programs that run during the - build on the host architecture, to support cross-compiling. - </p> - - <p> - If you want to run a tool from within a <code>genrule</code>, the - recommended way to get its path is <code>$(<a - href="#predefined_label_variables">execpath</a> toolname)</code>, - where <i>toolname</i> must be listed in the <code>genrule</code>'s - <code><a - href="/reference/be/general.html#genrule.tools">tools</a></code> attribute. - </p> - </li> - - <li><code>GENDIR</code>: - The base of the generated code tree for the target architecture. - </li> -</ul> - -<p><strong>Machine architecture variables</strong></p> - -<ul><!-- keep alphabetically sorted --> - <li> <code>TARGET_CPU</code>: - The target architecture's CPU, e.g. <code>k8</code>. </li> -</ul> - -<h2 id="predefined_genrule_variables">Predefined genrule variables</h2> - -<p> - The following are specially available to <code>genrule</code>'s - <code><a href="/reference/be/general.html#genrule.cmd">cmd</a></code> attribute and are - generally important for making that attribute work. -</p> - -<p><a href="https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-genrule-variables"> - See an example of predefined genrule variables</a>.</p> - -<ul><!-- keep alphabetically sorted --> - <li><code>OUTS</code>: The <code>genrule</code>'s <code><a - href="/reference/be/general.html#genrule.outs">outs</a></code> list. If you have - only one output file, you can also use <code>$@</code>.</li> - <li> - <code>SRCS</code>: The <code>genrule</code>'s <code><a - href="/reference/be/general.html#genrule.srcs">srcs</a></code> list (or more - precisely: the path names of the files corresponding to labels in the - <code><a href="/reference/be/general.html#genrule.srcs">srcs</a></code> list). - If you have only one source file, you can also use <code>$<</code>. - </li> - - <li> - <code><</code>: <code>SRCS</code>, if it is a single file. Else triggers - a build error. - </li> - <li> - <code>@</code>: <code>OUTS</code>, if it is a single file. Else triggers a - build error. - </li> - <li> - <p> - <code>RULEDIR</code>: The output directory of the target, that is, the - directory corresponding to the name of the package containing the target - under the <code>genfiles</code> or <code>bin</code> tree. For - <code>//my/pkg:my_genrule</code> this always ends in <code>my/pkg</code>, - even if <code>//my/pkg:my_genrule</code>'s outputs are in subdirectories. - </p> - </li> - <li> - <p> - <code>@D</code>: The output directory. If - <a - href="/reference/be/general.html#genrule.outs">outs</a></code> has one entry, - this expands to the directory containing that file. If it has multiple - entries, this expands to the package's root directory in the - <code>genfiles</code> tree, <i>even if all output files are in the same - subdirectory</i>! - </p> - <p> - <b>Note:</b> Use <code>RULEDIR</code> over <code>@D</code> because - <code>RULEDIR</code> has simpler semantics and behaves the same way - regardless of the number of output files. - </p> - <p> - If the genrule needs to generate temporary intermediate files (perhaps as - a result of using some other tool like a compiler), it should attempt to - write them to <code>@D</code> (although <code>/tmp</code> will also - be writable) and remove them before finishing. - </p> - <p> - Especially avoid writing to directories containing inputs. They may be on - read-only filesystems. Even if not, doing so would trash the source tree. - </p> - </li> -</ul> - -<p> - <b>Note:</b> If the filenames corresponding to the input labels or the output - filenames contain spaces, <code>'</code>, or other special characters (or your - genrule is part of a Starlark macro which downstream users may invoke on such - files), then <code>$(SRCS)</code> and <code>$(OUTS)</code> are not suitable - for interpolation into a command line, as they do not have the semantics that - <code>"${@}"</code> would in Bash. -</p> -<p>One workaround is to convert to a Bash array, with - <pre><code>mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion' -$(SRC) -genrule_srcs_expansion -)</code></pre> -and then use <code>"$$\{SRCS[@]}"</code> in subsequent command lines in place -of <code>$(SRCS)</code>. A more robust option is to write a Starlark rule +{% include "\_buttons.html" %} + +- [Use](#use) +- [Predefined variables](#predefined_variables) +- [Predefined genrule variables](#predefined_genrule_variables) +- [Predefined source/output path variables](#predefined_label_variables) +- [Custom variables](#custom_variables) + +"Make" variables are a special class of expandable string variables available +to attributes marked as *"Subject to 'Make variable' substitution"*. + +These can be used, for example, to inject specific toolchain paths into +user-constructed build actions. + +Bazel provides both *predefined* variables, which are available to all +targets, and *custom* variables, which are defined in dependency targets +and only available to targets that depend on them. + +The reason for the term "Make" is historical: the syntax and semantics of +these variables were originally intended to match [GNU +Make](https://www.gnu.org/software/make/manual/html_node/Using-Variables.html). + +## Use + +Attributes marked as *"Subject to 'Make variable' substitution"* can +reference the "Make" variable `FOO` as follows: + +`my_attr = "prefix $(FOO) suffix"` + +In other words, any substring matching `$(FOO)` gets expanded +to `FOO`'s value. If that value is `"bar"`, the final +string becomes: + +`my_attr = "prefix bar suffix"` + +If `FOO` doesn't correspond to a variable known to the consuming +target, Bazel fails with an error. + +"Make" variables whose names are non-letter symbols, such as +`@`, can also be referenced using only a dollar sign, without +the parentheses. For example: + +`my_attr = "prefix $@ suffix"` + +To write `$` as a string literal (i.e. to prevent variable +expansion), write `$$`. + +## Predefined variables + +Predefined "Make" variables can be referenced by any attribute marked as +*"Subject to 'Make variable' substitution"* on any target. + +To see the list of these variables and their values for a given set of build +options, run + +`bazel info --show_make_env [build options]` + +and look at the top output lines with capital letters. + +[See an example of predefined variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-variables). + +**Toolchain option variables** + +- `COMPILATION_MODE`: + `fastbuild`, `dbg`, or `opt`. ([more + details](https://bazel.build/docs/user-manual#flag--compilation_mode)) + +**Path variables** + +- `BINDIR`: The base of the generated binary tree for the target + architecture. + + Note that a different tree may be used for programs that run during the + build on the host architecture, to support cross-compiling. + + If you want to run a tool from within a `genrule`, the + recommended way to get its path is `$(`[`execpath`](#predefined_label_variables)` toolname)`, + where *toolname* must be listed in the `genrule`'s + [`tools`](/reference/be/general.html#genrule.tools) attribute. + +- `GENDIR`: + The base of the generated code tree for the target architecture. + +**Machine architecture variables** + +- `TARGET_CPU`: + The target architecture's CPU, e.g. `k8`. + +## Predefined genrule variables + +The following are specially available to `genrule`'s +[`cmd`](/reference/be/general.html#genrule.cmd) attribute and are +generally important for making that attribute work. + +[See an example of predefined genrule variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-genrule-variables). + +- `OUTS`: The `genrule`'s [`outs`](/reference/be/general.html#genrule.outs) list. If you have + only one output file, you can also use `$@`. + +- `SRCS`: The `genrule`'s [`srcs`](/reference/be/general.html#genrule.srcs) list (or more + precisely: the path names of the files corresponding to labels in the + [`srcs`](/reference/be/general.html#genrule.srcs) list). + If you have only one source file, you can also use `$<`. + +- `<`: `SRCS`, if it is a single file. Else triggers + a build error. + +- `@`: `OUTS`, if it is a single file. Else triggers a + build error. + +- `RULEDIR`: The output directory of the target, that is, the + directory corresponding to the name of the package containing the target + under the `genfiles` or `bin` tree. For + `//my/pkg:my_genrule` this always ends in `my/pkg`, + even if `//my/pkg:my_genrule`'s outputs are in subdirectories. + +- `@D`: The output directory. If + [outs](/reference/be/general.html#genrule.outs) has one entry, + this expands to the directory containing that file. If it has multiple + entries, this expands to the package's root directory in the + `genfiles` tree, *even if all output files are in the same + subdirectory*! + + **Note:** Use `RULEDIR` over `@D` because + `RULEDIR` has simpler semantics and behaves the same way + regardless of the number of output files. + + If the genrule needs to generate temporary intermediate files (perhaps as + a result of using some other tool like a compiler), it should attempt to + write them to `@D` (although `/tmp` will also + be writable) and remove them before finishing. + + Especially avoid writing to directories containing inputs. They may be on + read-only filesystems. Even if not, doing so would trash the source tree. + +**Note:** If the filenames corresponding to the input labels or the output +filenames contain spaces, `'`, or other special characters (or your +genrule is part of a Starlark macro which downstream users may invoke on such +files), then `$(SRCS)` and `$(OUTS)` are not suitable +for interpolation into a command line, as they do not have the semantics that +`"${@}"` would in Bash. + +One workaround is to convert to a Bash array, with + + mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion' + $(SRC) + genrule_srcs_expansion + ) + +and then use `"$$\{SRCS[@]}"` in subsequent command lines in place +of `$(SRCS)`. A more robust option is to write a Starlark rule instead. -</p> - - -<h2 id="predefined_label_variables">Predefined source/output path variables</h2> -<p> - The predefined variables <code>execpath</code>, <code>execpaths</code>, - <code>rootpath</code>, <code>rootpaths</code>, <code>location</code>, and - <code>locations</code> take label parameters (e.g. <code>$(execpath - //foo:bar)</code>) and substitute the file paths denoted by that label. -</p> -<p> - - For source files, this is the path relative to your workspace root. - For files that are outputs of rules, this is the file's <i>output path</i> - (see the explanation of <i>output files</i> below). -</p> - -<p><a href="https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-path-variables"> - See an example of predefined path variables</a>.</p> - -<ul> - <li> - <p> - <code>execpath</code>: Denotes the path beneath the - - <a href="/docs/output_directories">execroot</a> - where Bazel runs build actions. - </p> - <p> - In the above example, Bazel runs all build actions in the directory linked - by the <code>bazel-myproject</code> symlink in your workspace root. The - source file <code>empty.source</code> is linked at the path - <code>bazel-myproject/testapp/empty.source</code>. So its exec path (which - is the subpath below the root) is <code>testapp/empty.source</code>. This - is the path build actions can use to find the file. - </p> - <p> - Output files are staged similarly, but are also prefixed with the subpath - <code>bazel-out/cpu-compilation_mode/bin</code> (or for the outputs of - tools: <code>bazel-out/cpu-opt-exec-hash/bin</code>). In the above example, - <code>//testapp:app</code> is a tool because it appears in - <code>show_app_output</code>'s <code><a - href="/reference/be/general.html#genrule.tools">tools</a></code> attribute. - So its output file <code>app</code> is written to - <code>bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app</code>. - The exec path is thus <code> - bazel-out/cpu-opt-exec-hash/bin/testapp/app</code>. This extra prefix - makes it possible to build the same target for, say, two different CPUs in - the same build without the results clobbering each other. - </p> - <p> - The label passed to this variable must represent exactly one file. For - labels representing source files, this is automatically true. For labels - representing rules, the rule must generate exactly one output. If this is - false or the label is malformed, the build fails with an error. - </p> - </li> - - <li> - <p> - <code>rootpath</code>: Denotes the path that a built binary can use to - find a dependency at runtime relative to the subdirectory of its runfiles - directory corresponding to the main repository. - <strong>Note:</strong> This only works if <a - href="/reference/command-line-reference#flag--enable_runfiles"> - <code>--enable_runfiles</code></a> is enabled, which is not the case on - Windows by default. Use <code>rlocationpath</code> instead for - cross-platform support. - <p> - This is similar to <code>execpath</code> but strips the configuration - prefixes described above. In the example from above this means both - <code>empty.source</code> and <code>app</code> use pure workspace-relative - paths: <code>testapp/empty.source</code> and <code>testapp/app</code>. - </p> - <p> - The <code>rootpath</code> of a file in an external repository - <code>repo</code> will start with <code>../repo/</code>, followed by the - repository-relative path. - </p> - <p> - This has the same "one output only" requirements as <code>execpath</code>. - </p> - </li> - - <li> - <p> - <code>rlocationpath</code>: The path a built binary can pass to the <code> - Rlocation</code> function of a runfiles library to find a dependency at - runtime, either in the runfiles directory (if available) or using the - runfiles manifest. - </p> - <p> - This is similar to <code>rootpath</code> in that it does not contain - configuration prefixes, but differs in that it always starts with the - name of the repository. In the example from above this means that <code> - empty.source</code> and <code>app</code> result in the following - paths: <code>myproject/testapp/empty.source</code> and <code> - myproject/testapp/app</code>. - </p> - <p> - The <code>rlocationpath</code> of a file in an external repository - <code>repo</code> will start with <code>repo/</code>, followed by the - repository-relative path. - </p> - <p> - Passing this path to a binary and resolving it to a file system path using - the runfiles libraries is the preferred approach to find dependencies at - runtime. Compared to <code>rootpath</code>, it has the advantage that it - works on all platforms and even if the runfiles directory is not - available. - </p> - <p> - This has the same "one output only" requirements as <code>execpath</code>. - </p> - </li> - - <li> - <code>location</code>: A synonym for either <code>execpath</code> or - <code>rootpath</code>, depending on the attribute being expanded. This is - legacy pre-Starlark behavior and not recommended unless you really know what - it does for a particular rule. See <a - href="https://github.com/bazelbuild/bazel/issues/2475#issuecomment-339318016">#2475</a> - for details. - </li> -</ul> - -<p> - <code>execpaths</code>, <code>rootpaths</code>, <code>rlocationpaths</code>, - and <code>locations</code> are the plural variations of <code>execpath</code>, - <code>rootpath</code>, <code>rlocationpath</code>, and<code>location</code>, - respectively. They support labels producing multiple outputs, in which case - each output is listed separated by a space. Zero-output rules and malformed - labels produce build errors. -</p> - -<p> - All referenced labels must appear in the consuming target's <code>srcs</code>, - output files, or <code>deps</code>. Otherwise the build fails. C++ targets can - also reference labels in <code><a - href="/reference/be/c-cpp.html#cc_binary.data">data</a></code>. -</p> - -<p> - Labels don't have to be in canonical form: <code>foo</code>, <code>:foo</code> - and <code>//somepkg:foo</code> are all fine. -</p> - -<h2 id="custom_variables">Custom variables</h2> - -<p> - Custom "Make" variables can be referenced by any attribute marked as - <i>"Subject to 'Make variable' substitution"</i>, but only on targets that - depend on other targets that <i>define</i> these variables. -</p> - -<p> - As best practice all variables should be custom unless there's a really good - reason to bake them into core Bazel. This saves Bazel from having to load - potentially expensive dependencies to supply variables consuming tarets may - not care about. -</p> - -<p><strong>C++ toolchain variables</strong></p> -<p> - The following are defined in C++ toolchain rules and available to any rule - that sets <code>toolchains = - ["@bazel_tools//tools/cpp:toolchain_type"]</code> - Some rules, like <code><a - href="/reference/be/java.html#java_binary">java_binary</a></code>, implicitly - include the C++ toolchain in their rule definition. They inherit these variables - automatically. -</p> - -<p> - The built-in C++ rules are much more sophisticated than "run the compiler on - it". In order to support compilation modes as diverse as *SAN, ThinLTO, - with/without modules, and carefully optimized binaries at the same time as - fast running tests on multiple platforms, the built-in rules go to great - lengths to ensure the correct inputs, outputs, and command-line flags are set - on each of potentially multiple internally generated actions. -</p> - -<p> - These variables are a fallback mechanism to be used by language experts in - rare cases. If you are tempted to use them, please <a - href="https://bazel.build/help">contact the Bazel devs</a> first. -</p> - -<ul><!-- keep alphabetically sorted --> - <li><code>ABI</code>: The C++ ABI version. </li> - - <li> <code>AR</code>: The "ar" command from crosstool. </li> - <li class="harmful"> <code>C_COMPILER</code>: - The C/C++ compiler identifier, e.g. <code>llvm</code>. - </li> - <li class="harmful"> - <p><code>CC</code>: The C and C++ compiler command.</p> - <p> - We strongly recommended always using <code>CC_FLAGS</code> in - combination with <code>CC</code>. Fail to do so at your own risk. - </p> - </li> - <li class="harmful"><code>CC_FLAGS</code>: A minimal set of flags for the C/C++ - compiler to be usable by genrules. In particular, this contains flags to - select the correct architecture if <code>CC</code> supports multiple - architectures. - </li> - - - <li> <code>DUMPBIN</code>: Microsoft COFF Binary File Dumper (dumpbin.exe) from - from Microsoft Visual Studio. </li> - - <li> <code>NM</code>: The "nm" command from crosstool. </li> - <li> <code>OBJCOPY</code>: The objcopy command from the same suite as the C/C++ - compiler. </li> - - <li> <code>STRIP</code>: The strip command from the same suite as the C/C++ - compiler.</li> -</ul> - -<p><strong>Java toolchain variables</strong></p> - -<p> - The following are defined in Java toolchain rules and available to any rule - that sets <code>toolchains = -["@rules_java//toolchains:current_java_runtime"]</code> (or - <code>"@rules_java//toolchains:current_host_java_runtime"</code> - for the host toolchain equivalent). -</p> - -<p> - Most of the tools in the JDK should not be used directly. The built-in Java - rules use much more sophisticated approaches to Java compilation and packaging - than upstream tools can express, such as interface Jars, header interface - Jars, and highly optimized Jar packaging and merging implementations. -</p> - -<p> - These variables are a fallback mechanism to be used by language experts in - rare cases. If you are tempted to use them, please <a - href="https://bazel.build/help">contact the Bazel devs</a> first. -</p> - -<ul><!-- keep alphabetically sorted --> - <li class="harmful"> <code>JAVA</code>: The "java" command (a Java virtual - machine). Avoid this, and use a <code><a - href="/reference/be/java.html#java_binary">java_binary</a></code> rule - instead where possible. May be a relative path. If you must change - directories before invoking <code>java</code>, you need to capture the - working directory before changing it. - </li> - - <li class="harmful"><code>JAVABASE</code>: The base directory containing the - Java utilities. May be a relative path. It will have a "bin" - subdirectory. - </li> -</ul> - -<p><strong>Starlark-defined variables</strong></p> - -<p> - Rule and <a href="/docs/toolchains">toolchain</a> writers can define - completely custom variables by returning a - <a href="/rules/lib/TemplateVariableInfo">TemplateVariableInfo</a> - provider. Any rules depending on these through the - <code>toolchains</code> attribute can then read their values: -</p> - -<p><a href="https://github.com/bazelbuild/examples/tree/main/make-variables#custom-starlark-defined-variables"> - See an example of Starlark-defined variables</a>.</p> - -<!-- Generated footer --> - - - -</body> -</html> + +## Predefined source/output path variables + +The predefined variables `execpath`, `execpaths`, +`rootpath`, `rootpaths`, `location`, and +`locations` take label parameters (e.g. `$(execpath //foo:bar)`) and substitute the file paths denoted by that label. + +For source files, this is the path relative to your workspace root. +For files that are outputs of rules, this is the file's *output path* +(see the explanation of *output files* below). + +[See an example of predefined path variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-path-variables). + +- `execpath`: Denotes the path beneath the + [execroot](/docs/output_directories) + where Bazel runs build actions. + + In the above example, Bazel runs all build actions in the directory linked + by the `bazel-myproject` symlink in your workspace root. The + source file `empty.source` is linked at the path + `bazel-myproject/testapp/empty.source`. So its exec path (which + is the subpath below the root) is `testapp/empty.source`. This + is the path build actions can use to find the file. + + Output files are staged similarly, but are also prefixed with the subpath + `bazel-out/cpu-compilation_mode/bin` (or for the outputs of + tools: `bazel-out/cpu-opt-exec-hash/bin`). In the above example, + `//testapp:app` is a tool because it appears in + `show_app_output`'s [`tools`](/reference/be/general.html#genrule.tools) attribute. + So its output file `app` is written to + `bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app`. + The exec path is thus ` bazel-out/cpu-opt-exec-hash/bin/testapp/app`. This extra prefix + makes it possible to build the same target for, say, two different CPUs in + the same build without the results clobbering each other. + + The label passed to this variable must represent exactly one file. For + labels representing source files, this is automatically true. For labels + representing rules, the rule must generate exactly one output. If this is + false or the label is malformed, the build fails with an error. + +- `rootpath`: Denotes the path that a built binary can use to + find a dependency at runtime relative to the subdirectory of its runfiles + directory corresponding to the main repository. + **Note:** This only works if + [`--enable_runfiles`](/reference/command-line-reference#flag--enable_runfiles) is enabled, which is not the case on + Windows by default. Use `rlocationpath` instead for + cross-platform support. + + This is similar to `execpath` but strips the configuration + prefixes described above. In the example from above this means both + `empty.source` and `app` use pure workspace-relative + paths: `testapp/empty.source` and `testapp/app`. + + The `rootpath` of a file in an external repository + `repo` will start with `../repo/`, followed by the + repository-relative path. + + This has the same "one output only" requirements as `execpath`. + +- `rlocationpath`: The path a built binary can pass to the ` Rlocation` function of a runfiles library to find a dependency at + runtime, either in the runfiles directory (if available) or using the + runfiles manifest. + + This is similar to `rootpath` in that it does not contain + configuration prefixes, but differs in that it always starts with the + name of the repository. In the example from above this means that ` empty.source` and `app` result in the following + paths: `myproject/testapp/empty.source` and ` myproject/testapp/app`. + + The `rlocationpath` of a file in an external repository + `repo` will start with `repo/`, followed by the + repository-relative path. + + Passing this path to a binary and resolving it to a file system path using + the runfiles libraries is the preferred approach to find dependencies at + runtime. Compared to `rootpath`, it has the advantage that it + works on all platforms and even if the runfiles directory is not + available. + + This has the same "one output only" requirements as `execpath`. + +- `location`: A synonym for either `execpath` or + `rootpath`, depending on the attribute being expanded. This is + legacy pre-Starlark behavior and not recommended unless you really know what + it does for a particular rule. See [\#2475](https://github.com/bazelbuild/bazel/issues/2475#issuecomment-339318016) + for details. + +`execpaths`, `rootpaths`, `rlocationpaths`, +and `locations` are the plural variations of `execpath`, +`rootpath`, `rlocationpath`, and`location`, +respectively. They support labels producing multiple outputs, in which case +each output is listed separated by a space. Zero-output rules and malformed +labels produce build errors. + +All referenced labels must appear in the consuming target's `srcs`, +output files, or `deps`. Otherwise the build fails. C++ targets can +also reference labels in [`data`](/reference/be/c-cpp.html#cc_binary.data). + +Labels don't have to be in canonical form: `foo`, `:foo` +and `//somepkg:foo` are all fine. + +## Custom variables + +Custom "Make" variables can be referenced by any attribute marked as +*"Subject to 'Make variable' substitution"*, but only on targets that +depend on other targets that *define* these variables. + +As best practice all variables should be custom unless there's a really good +reason to bake them into core Bazel. This saves Bazel from having to load +potentially expensive dependencies to supply variables consuming tarets may +not care about. + +**C++ toolchain variables** + +The following are defined in C++ toolchain rules and available to any rule +that sets `toolchains = ["@bazel_tools//tools/cpp:toolchain_type"]` +Some rules, like [`java_binary`](/reference/be/java.html#java_binary), implicitly +include the C++ toolchain in their rule definition. They inherit these variables +automatically. + +The built-in C++ rules are much more sophisticated than "run the compiler on +it". In order to support compilation modes as diverse as \*SAN, ThinLTO, +with/without modules, and carefully optimized binaries at the same time as +fast running tests on multiple platforms, the built-in rules go to great +lengths to ensure the correct inputs, outputs, and command-line flags are set +on each of potentially multiple internally generated actions. + +These variables are a fallback mechanism to be used by language experts in +rare cases. If you are tempted to use them, please [contact the Bazel devs](https://bazel.build/help) first. + +- `ABI`: The C++ ABI version. + +- `AR`: The "ar" command from crosstool. + +- `C_COMPILER`: + The C/C++ compiler identifier, e.g. `llvm`. + +- `CC`: The C and C++ compiler command. + + We strongly recommended always using `CC_FLAGS` in + combination with `CC`. Fail to do so at your own risk. + +- `CC_FLAGS`: A minimal set of flags for the C/C++ + compiler to be usable by genrules. In particular, this contains flags to + select the correct architecture if `CC` supports multiple + architectures. + +- `DUMPBIN`: Microsoft COFF Binary File Dumper (dumpbin.exe) from + from Microsoft Visual Studio. + +- `NM`: The "nm" command from crosstool. + +- `OBJCOPY`: The objcopy command from the same suite as the C/C++ + compiler. + +- `STRIP`: The strip command from the same suite as the C/C++ + compiler. + +**Java toolchain variables** + +The following are defined in Java toolchain rules and available to any rule +that sets `toolchains = ["@rules_java//toolchains:current_java_runtime"]` (or +`"@rules_java//toolchains:current_host_java_runtime"` +for the host toolchain equivalent). + +Most of the tools in the JDK should not be used directly. The built-in Java +rules use much more sophisticated approaches to Java compilation and packaging +than upstream tools can express, such as interface Jars, header interface +Jars, and highly optimized Jar packaging and merging implementations. + +These variables are a fallback mechanism to be used by language experts in +rare cases. If you are tempted to use them, please [contact the Bazel devs](https://bazel.build/help) first. + +- `JAVA`: The "java" command (a Java virtual + machine). Avoid this, and use a [`java_binary`](/reference/be/java.html#java_binary) rule + instead where possible. May be a relative path. If you must change + directories before invoking `java`, you need to capture the + working directory before changing it. +- `JAVABASE`: The base directory containing the + Java utilities. May be a relative path. It will have a "bin" + subdirectory. + +**Starlark-defined variables** + +Rule and [toolchain](/docs/toolchains) writers can define +completely custom variables by returning a +[TemplateVariableInfo](/rules/lib/TemplateVariableInfo) +provider. Any rules depending on these through the +`toolchains` attribute can then read their values: + +[See an example of Starlark-defined variables](https://github.com/bazelbuild/examples/tree/main/make-variables#custom-starlark-defined-variables). diff --git a/reference/be/objective-c.mdx b/reference/be/objective-c.mdx index e1f2160..72afbd3 100644 --- a/reference/be/objective-c.mdx +++ b/reference/be/objective-c.mdx @@ -2,264 +2,169 @@ title: 'objective-c' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">Objective-C Rules</h1> +# Objective-C Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} - +{% include "\_buttons.html" %} +## Rules +- [objc_import](#objc_import) +- [objc_library](#objc_library) -<h2>Rules</h2> -<ul> - <li> - <a href="#objc_import"> - objc_import </a> - </li> - <li> - <a href="#objc_library"> - objc_library </a> - </li> -</ul> +## objc_import - <h2 id="objc_import"> - objc_import - </h2> +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_import.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_import.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +``` rule-signature +objc_import(name, deps, hdrs, alwayslink, archives, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, includes, package_metadata, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) +``` - <pre class="rule-signature">objc_import(<a href="#objc_import.name">name</a>, <a href="#objc_import.deps">deps</a>, <a href="#objc_import.hdrs">hdrs</a>, <a href="#objc_import.alwayslink">alwayslink</a>, <a href="#objc_import.archives">archives</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#objc_import.includes">includes</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#objc_import.sdk_dylibs">sdk_dylibs</a>, <a href="#objc_import.sdk_frameworks">sdk_frameworks</a>, <a href="#objc_import.sdk_includes">sdk_includes</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="#objc_import.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#objc_import.weak_sdk_frameworks">weak_sdk_frameworks</a>)</pre> +This rule encapsulates an already-compiled static library in the form of an +`.a` file. It also allows exporting headers and resources using the same +attributes supported by `objc_library`. - <p>This rule encapsulates an already-compiled static library in the form of an -<code>.a</code> file. It also allows exporting headers and resources using the same -attributes supported by <code>objc_library</code>.</p> +### Arguments - <h3 id="objc_import_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="objc_import.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="objc_import.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of targets that this target depend on. - </td> - </tr> - <tr> - <td id="objc_import.hdrs"> - <code>hdrs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of C, C++, Objective-C, and Objective-C++ header files published +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="objc_import.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="objc_import.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of targets that this target depend on.</td> +</tr> +<tr> +<td id="objc_import.hdrs"><code>hdrs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of C, C++, Objective-C, and Objective-C++ header files published by this library to be included by sources in dependent rules. -<p> -These headers describe the public interface for the library and will be +<p>These headers describe the public interface for the library and will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library -should be listed in the srcs attribute instead. -<p> -These will be compiled separately from the source if modules are enabled. - </td> - </tr> - <tr> - <td id="objc_import.alwayslink"> - <code>alwayslink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - If 1, any bundle or binary that depends (directly or indirectly) on this +should be listed in the srcs attribute instead.</p> +<p>These will be compiled separately from the source if modules are enabled.</p></td> +</tr> +<tr> +<td id="objc_import.alwayslink"><code>alwayslink</code></td> +<td><p>Boolean; default is <code>False</code></p> +If 1, any bundle or binary that depends (directly or indirectly) on this library will link in all the object files for the files listed in <code>srcs</code> and <code>non_arc_srcs</code>, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback -provided by some service. - </td> - </tr> - <tr> - <td id="objc_import.archives"> - <code>archives</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; required</p> - The list of <code>.a</code> files provided to Objective-C targets that -depend on this target. - </td> - </tr> - <tr> - <td id="objc_import.includes"> - <code>includes</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of <code>#include/#import</code> search paths to add to this target +provided by some service.</td> +</tr> +<tr> +<td id="objc_import.archives"><code>archives</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; required</p> +The list of <code>.a</code> files provided to Objective-C targets that +depend on this target.</td> +</tr> +<tr> +<td id="objc_import.includes"><code>includes</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of <code>#include/#import</code> search paths to add to this target and all depending targets. - This is to support third party and open-sourced libraries that do not specify the entire workspace path in their <code>#import/#include</code> statements. -<p> -The paths are interpreted relative to the package directory, and the +<p>The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. <code>blaze-genfiles/pkg/includedir</code> and <code>blaze-out/pkg/includedir</code>) are included in addition to the -actual client root. -<p> -Unlike <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a>, these flags are added for this rule +actual client root.</p> +<p>Unlike <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a>, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-iquote" flags to <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead. - </td> - </tr> - <tr> - <td id="objc_import.sdk_dylibs"> - <code>sdk_dylibs</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Names of SDK .dylib libraries to link with. For instance, "libz" or +very careful, since this may have far-reaching effects. When in doubt, add +"-iquote" flags to <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead.</p></td> +</tr> +<tr> +<td id="objc_import.sdk_dylibs"><code>sdk_dylibs</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Names of SDK .dylib libraries to link with. For instance, "libz" or "libarchive". - "libc++" is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are -used. - </td> - </tr> - <tr> - <td id="objc_import.sdk_frameworks"> - <code>sdk_frameworks</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). - -<p> When linking a top level Apple binary, all SDK frameworks listed in that binary's -transitive dependency graph are linked. - </td> - </tr> - <tr> - <td id="objc_import.sdk_includes"> - <code>sdk_includes</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of <code>#include/#import</code> search paths to add to this target +used.</td> +</tr> +<tr> +<td id="objc_import.sdk_frameworks"><code>sdk_frameworks</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). +<p>When linking a top level Apple binary, all SDK frameworks listed in that binary's +transitive dependency graph are linked.</p></td> +</tr> +<tr> +<td id="objc_import.sdk_includes"><code>sdk_includes</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of <code>#include/#import</code> search paths to add to this target and all depending targets, where each path is relative to -<code>$(SDKROOT)/usr/include</code>. - </td> - </tr> - <tr> - <td id="objc_import.textual_hdrs"> - <code>textual_hdrs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of C, C++, Objective-C, and Objective-C++ files that are +<code>$(SDKROOT)/usr/include</code>.</td> +</tr> +<tr> +<td id="objc_import.textual_hdrs"><code>textual_hdrs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of C, C++, Objective-C, and Objective-C++ files that are included as headers by source files in this rule or by users of this library. Unlike hdrs, these will not be compiled separately from the -sources. - </td> - </tr> - <tr> - <td id="objc_import.weak_sdk_frameworks"> - <code>weak_sdk_frameworks</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Names of SDK frameworks to weakly link with. For instance, +sources.</td> +</tr> +<tr> +<td id="objc_import.weak_sdk_frameworks"><code>weak_sdk_frameworks</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Names of SDK frameworks to weakly link with. For instance, "MediaAccessibility". - In difference to regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause an error if they -are not present at runtime. - </td> - </tr> - </tbody> - </table> - <h2 id="objc_library"> - objc_library - </h2> +are not present at runtime.</td> +</tr> +</tbody> +</table> + +## objc_library - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <pre class="rule-signature">objc_library(<a href="#objc_library.name">name</a>, <a href="#objc_library.deps">deps</a>, <a href="#objc_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#objc_library.hdrs">hdrs</a>, <a href="#objc_library.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#objc_library.conlyopts">conlyopts</a>, <a href="#objc_library.copts">copts</a>, <a href="#objc_library.cxxopts">cxxopts</a>, <a href="#objc_library.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#objc_library.enable_modules">enable_modules</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#objc_library.implementation_deps">implementation_deps</a>, <a href="#objc_library.includes">includes</a>, <a href="#objc_library.linkopts">linkopts</a>, <a href="#objc_library.module_map">module_map</a>, <a href="#objc_library.module_name">module_name</a>, <a href="#objc_library.non_arc_srcs">non_arc_srcs</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#objc_library.pch">pch</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#objc_library.sdk_dylibs">sdk_dylibs</a>, <a href="#objc_library.sdk_frameworks">sdk_frameworks</a>, <a href="#objc_library.sdk_includes">sdk_includes</a>, <a href="#objc_library.stamp">stamp</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="#objc_library.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#objc_library.weak_sdk_frameworks">weak_sdk_frameworks</a>)</pre> +``` rule-signature +objc_library(name, deps, srcs, data, hdrs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, enable_modules, exec_compatible_with, exec_group_compatible_with, exec_properties, features, implementation_deps, includes, linkopts, module_map, module_name, non_arc_srcs, package_metadata, pch, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, stamp, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) +``` - <p>This rule produces a static library from the given Objective-C source files.</p> +This rule produces a static library from the given Objective-C source files. - <h3 id="objc_library_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="objc_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> +### Arguments - </td> - </tr> - <tr> - <td id="objc_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of targets that this target depend on. - </td> - </tr> - <tr> - <td id="objc_library.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of C, C++, Objective-C, and Objective-C++ source and header +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="objc_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="objc_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of targets that this target depend on.</td> +</tr> +<tr> +<td id="objc_library.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of C, C++, Objective-C, and Objective-C++ source and header files, and/or (`.s`, `.S`, or `.asm`) assembly source files, that are processed to create the library target. These are your checked-in files, plus any generated files. @@ -267,292 +172,194 @@ Source files are compiled into .o files with Clang. Header files may be included/imported by any source or header in the srcs attribute of this target, but not by headers in hdrs or any targets that depend on this rule. -Additionally, precompiled .o files may be given as srcs. Be careful to +Additionally, precompiled .o files may be given as srcs. Be careful to ensure consistency in the architecture of provided .o files and that of the -build to avoid missing symbol linker errors. - </td> - </tr> - <tr> - <td id="objc_library.hdrs"> - <code>hdrs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of C, C++, Objective-C, and Objective-C++ header files published +build to avoid missing symbol linker errors.</td> +</tr> +<tr> +<td id="objc_library.hdrs"><code>hdrs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of C, C++, Objective-C, and Objective-C++ header files published by this library to be included by sources in dependent rules. -<p> -These headers describe the public interface for the library and will be +<p>These headers describe the public interface for the library and will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library -should be listed in the srcs attribute instead. -<p> -These will be compiled separately from the source if modules are enabled. - </td> - </tr> - <tr> - <td id="objc_library.alwayslink"> - <code>alwayslink</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - If 1, any bundle or binary that depends (directly or indirectly) on this +should be listed in the srcs attribute instead.</p> +<p>These will be compiled separately from the source if modules are enabled.</p></td> +</tr> +<tr> +<td id="objc_library.alwayslink"><code>alwayslink</code></td> +<td><p>Boolean; default is <code>False</code></p> +If 1, any bundle or binary that depends (directly or indirectly) on this library will link in all the object files for the files listed in <code>srcs</code> and <code>non_arc_srcs</code>, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback -provided by some service. - </td> - </tr> - <tr> - <td id="objc_library.conlyopts"> - <code>conlyopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra flags to pass to the compiler for C files. +provided by some service.</td> +</tr> +<tr> +<td id="objc_library.conlyopts"><code>conlyopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra flags to pass to the compiler for C files. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. These flags will only apply to this target, and not those upon which it depends, or those which depend on it. -<p> -Note that for the generated Xcode project, directory paths specified using "-I" flags in +<p>Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and -added to the header search paths for the associated Xcode target. - </td> - </tr> - <tr> - <td id="objc_library.copts"> - <code>copts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra flags to pass to the compiler. +added to the header search paths for the associated Xcode target.</p></td> +</tr> +<tr> +<td id="objc_library.copts"><code>copts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra flags to pass to the compiler. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. These flags will only apply to this target, and not those upon which it depends, or those which depend on it. -<p> -Note that for the generated Xcode project, directory paths specified using "-I" flags in +<p>Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and -added to the header search paths for the associated Xcode target. - </td> - </tr> - <tr> - <td id="objc_library.cxxopts"> - <code>cxxopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra flags to pass to the compiler for Objective-C++ and C++ files. +added to the header search paths for the associated Xcode target.</p></td> +</tr> +<tr> +<td id="objc_library.cxxopts"><code>cxxopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra flags to pass to the compiler for Objective-C++ and C++ files. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and <a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. These flags will only apply to this target, and not those upon which it depends, or those which depend on it. -<p> -Note that for the generated Xcode project, directory paths specified using "-I" flags in +<p>Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and -added to the header search paths for the associated Xcode target. - </td> - </tr> - <tr> - <td id="objc_library.defines"> - <code>defines</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra <code>-D</code> flags to pass to the compiler. They should be in +added to the header search paths for the associated Xcode target.</p></td> +</tr> +<tr> +<td id="objc_library.defines"><code>defines</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra <code>-D</code> flags to pass to the compiler. They should be in the form <code>KEY=VALUE</code> or simply <code>KEY</code> and are passed not only to the compiler for this target (as <code>copts</code> are) but also to all <code>objc_</code> dependers of this target. Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. - </td> - </tr> - <tr> - <td id="objc_library.enable_modules"> - <code>enable_modules</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Enables clang module support (via -fmodules). +<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> +</tr> +<tr> +<td id="objc_library.enable_modules"><code>enable_modules</code></td> +<td><p>Boolean; default is <code>False</code></p> +Enables clang module support (via -fmodules). Setting this to 1 will allow you to @import system headers and other targets: @import UIKit; -@import path_to_package_target; - </td> - </tr> - <tr> - <td id="objc_library.implementation_deps"> - <code>implementation_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other libraries that the library target depends on. Unlike with +@import path_to_package_target;</td> +</tr> +<tr> +<td id="objc_library.implementation_deps"><code>implementation_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other libraries that the library target depends on. Unlike with <code>deps</code>, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with <code>implementation_deps</code> are still linked -in binary targets that depend on this library. - </td> - </tr> - <tr> - <td id="objc_library.includes"> - <code>includes</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of <code>#include/#import</code> search paths to add to this target +in binary targets that depend on this library.</td> +</tr> +<tr> +<td id="objc_library.includes"><code>includes</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of <code>#include/#import</code> search paths to add to this target and all depending targets. - This is to support third party and open-sourced libraries that do not specify the entire workspace path in their <code>#import/#include</code> statements. -<p> -The paths are interpreted relative to the package directory, and the +<p>The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. <code>blaze-genfiles/pkg/includedir</code> and <code>blaze-out/pkg/includedir</code>) are included in addition to the -actual client root. -<p> -Unlike <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a>, these flags are added for this rule +actual client root.</p> +<p>Unlike <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a>, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-iquote" flags to <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead. - </td> - </tr> - <tr> - <td id="objc_library.linkopts"> - <code>linkopts</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Extra flags to pass to the linker. - </td> - </tr> - <tr> - <td id="objc_library.module_map"> - <code>module_map</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - custom Clang module map for this target. Use of a custom module map is discouraged. Most +very careful, since this may have far-reaching effects. When in doubt, add +"-iquote" flags to <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead.</p></td> +</tr> +<tr> +<td id="objc_library.linkopts"><code>linkopts</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Extra flags to pass to the linker.</td> +</tr> +<tr> +<td id="objc_library.module_map"><code>module_map</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +custom Clang module map for this target. Use of a custom module map is discouraged. Most users should use module maps generated by Bazel. If specified, Bazel will not generate a module map for this target, but will pass the -provided module map to the compiler. - </td> - </tr> - <tr> - <td id="objc_library.module_name"> - <code>module_name</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Sets the module name for this target. By default the module name is the target path with -all special symbols replaced by _, e.g. //foo/baz:bar can be imported as foo_baz_bar. - </td> - </tr> - <tr> - <td id="objc_library.non_arc_srcs"> - <code>non_arc_srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of Objective-C files that are processed to create the +provided module map to the compiler.</td> +</tr> +<tr> +<td id="objc_library.module_name"><code>module_name</code></td> +<td><p>String; default is <code>""</code></p> +Sets the module name for this target. By default the module name is the target path with +all special symbols replaced by _, e.g. //foo/baz:bar can be imported as foo_baz_bar.</td> +</tr> +<tr> +<td id="objc_library.non_arc_srcs"><code>non_arc_srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of Objective-C files that are processed to create the library target that DO NOT use ARC. The files in this attribute are treated very similar to those in the -srcs attribute, but are compiled without ARC enabled. - </td> - </tr> - <tr> - <td id="objc_library.pch"> - <code>pch</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Header file to prepend to every source file being compiled (both arc +srcs attribute, but are compiled without ARC enabled.</td> +</tr> +<tr> +<td id="objc_library.pch"><code>pch</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Header file to prepend to every source file being compiled (both arc and non-arc). Use of pch files is actively discouraged in BUILD files, and this should be considered deprecated. Since pch files are not actually precompiled this is not a build-speed enhancement, and instead is just a global dependency. From a build efficiency point of view you are actually better including what you need directly -in your sources where you need it. - </td> - </tr> - <tr> - <td id="objc_library.sdk_dylibs"> - <code>sdk_dylibs</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Names of SDK .dylib libraries to link with. For instance, "libz" or +in your sources where you need it.</td> +</tr> +<tr> +<td id="objc_library.sdk_dylibs"><code>sdk_dylibs</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Names of SDK .dylib libraries to link with. For instance, "libz" or "libarchive". - "libc++" is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are -used. - </td> - </tr> - <tr> - <td id="objc_library.sdk_frameworks"> - <code>sdk_frameworks</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). - -<p> When linking a top level Apple binary, all SDK frameworks listed in that binary's -transitive dependency graph are linked. - </td> - </tr> - <tr> - <td id="objc_library.sdk_includes"> - <code>sdk_includes</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of <code>#include/#import</code> search paths to add to this target +used.</td> +</tr> +<tr> +<td id="objc_library.sdk_frameworks"><code>sdk_frameworks</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). +<p>When linking a top level Apple binary, all SDK frameworks listed in that binary's +transitive dependency graph are linked.</p></td> +</tr> +<tr> +<td id="objc_library.sdk_includes"><code>sdk_includes</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of <code>#include/#import</code> search paths to add to this target and all depending targets, where each path is relative to -<code>$(SDKROOT)/usr/include</code>. - </td> - </tr> - <tr> - <td id="objc_library.stamp"> - <code>stamp</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - - </td> - </tr> - <tr> - <td id="objc_library.textual_hdrs"> - <code>textual_hdrs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of C, C++, Objective-C, and Objective-C++ files that are +<code>$(SDKROOT)/usr/include</code>.</td> +</tr> +<tr> +<td id="objc_library.stamp"><code>stamp</code></td> +<td><p>Boolean; default is <code>False</code></p></td> +</tr> +<tr> +<td id="objc_library.textual_hdrs"><code>textual_hdrs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of C, C++, Objective-C, and Objective-C++ files that are included as headers by source files in this rule or by users of this library. Unlike hdrs, these will not be compiled separately from the -sources. - </td> - </tr> - <tr> - <td id="objc_library.weak_sdk_frameworks"> - <code>weak_sdk_frameworks</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Names of SDK frameworks to weakly link with. For instance, +sources.</td> +</tr> +<tr> +<td id="objc_library.weak_sdk_frameworks"><code>weak_sdk_frameworks</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Names of SDK frameworks to weakly link with. For instance, "MediaAccessibility". - In difference to regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause an error if they -are not present at runtime. - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +are not present at runtime.</td> +</tr> +</tbody> +</table> diff --git a/reference/be/overview.mdx b/reference/be/overview.mdx index 82d417a..e72f5b2 100644 --- a/reference/be/overview.mdx +++ b/reference/be/overview.mdx @@ -2,278 +2,193 @@ title: 'overview' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title">Bazel BUILD Encyclopedia of Functions</h1> +# Bazel BUILD Encyclopedia of Functions {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm" %} -{% include "_buttons.html" %} -<h2>Concepts and terminology</h2> - -<ul> - <li> - <a href="/reference/be/common-definitions">Common definitions</a> - <ul> - <li><a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a></li> - <li><a href="/reference/be/common-definitions#label-expansion">Label expansion</a></li> - <li><a href="/reference/be/common-definitions#typical-attributes">Typical attributes for most rules</a></li> - <li><a href="/reference/be/common-definitions#common-attributes">Common attributes for all rules</a></li> - <li><a href="/reference/be/common-definitions#common-attributes-tests">Common attributes for tests</a></li> - <li><a href="/reference/be/common-definitions#common-attributes-binaries">Common attributes for binaries</a></li> - <li><a href="/reference/be/common-definitions#configurable-attributes">Configurable attributes</a></li> - <li><a href="/reference/be/common-definitions#implicit-outputs">Implicit output targets</a></li> - </ul> - </li> - <li> - <a href="/reference/be/make-variables">"Make" variables</a> - <ul class="be-toc"> - <li><a href="/reference/be/make-variables#use">Use</a></li> - - </ul> - </li> -</ul> - -<h2>Functions</h2> - -<ul class="be-toc"> - <li><a href="/reference/be/functions.html#package">package</a></li> - <li><a href="/reference/be/functions.html#package_group">package_group</a></li> - - <li><a href="/reference/be/functions.html#exports_files">exports_files</a></li> - <li><a href="/reference/be/functions.html#glob">glob</a></li> - <li><a href="/reference/be/functions.html#select">select</a></li> - <li><a href="/rules/lib/globals/workspace#workspace">workspace</a></li> -</ul> - -<h2>Rules</h2> - -Native rules ship with the Bazel binary and do not require a <code>load</code> statement. +{% include "\_buttons.html" %} + +## Concepts and terminology + +- [Common definitions](/reference/be/common-definitions) + - [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization) + - [Label expansion](/reference/be/common-definitions#label-expansion) + - [Typical attributes for most rules](/reference/be/common-definitions#typical-attributes) + - [Common attributes for all rules](/reference/be/common-definitions#common-attributes) + - [Common attributes for tests](/reference/be/common-definitions#common-attributes-tests) + - [Common attributes for binaries](/reference/be/common-definitions#common-attributes-binaries) + - [Configurable attributes](/reference/be/common-definitions#configurable-attributes) + - [Implicit output targets](/reference/be/common-definitions#implicit-outputs) +- ["Make" variables](/reference/be/make-variables) + - [Use](/reference/be/make-variables#use) + +## Functions + +- [package](/reference/be/functions.html#package) +- [package_group](/reference/be/functions.html#package_group) +- [exports_files](/reference/be/functions.html#exports_files) +- [glob](/reference/be/functions.html#glob) +- [select](/reference/be/functions.html#select) +- [workspace](/rules/lib/globals/workspace#workspace) + +## Rules + +Native rules ship with the Bazel binary and do not require a `load` statement. Native rules are available globally in BUILD files. In .bzl files, you can find them in -the <code>native</code> module. - +the `native` module. For non-native Starlark rules that ship separately from Bazel, see the list of -<a href="/rules/rules#recommended-rules">recommended rules</a>. - -<h3>Language-specific native rules</h3> - - -<table class="table table-condensed table-striped" summary="Table of rules sorted by language"> - <thead> - <tr> - <th>Language</th> - <th>Flags</th> - <th>Binary rules</th> - <th>Library rules</th> - <th>Test rules</th> - <th>Other rules</th> - </tr> - </thead> - <tbody> - <tr> - <td class="lang">C / C++</td> - <td></td> - - <td> - <a href="c-cpp.html#cc_binary">cc_binary</a> - <br /> - </td> - <td> - <a href="c-cpp.html#cc_import">cc_import</a> - <br /> - <a href="c-cpp.html#cc_library">cc_library</a> - <br /> - <a href="c-cpp.html#cc_shared_library">cc_shared_library</a> - <br /> - <a href="c-cpp.html#cc_static_library">cc_static_library</a> - <br /> - </td> - <td> - <a href="c-cpp.html#cc_test">cc_test</a> - <br /> - </td> - <td> - <a href="c-cpp.html#cc_toolchain">cc_toolchain</a> - <br /> - <a href="c-cpp.html#fdo_prefetch_hints">fdo_prefetch_hints</a> - <br /> - <a href="c-cpp.html#fdo_profile">fdo_profile</a> - <br /> - <a href="c-cpp.html#memprof_profile">memprof_profile</a> - <br /> - <a href="c-cpp.html#propeller_optimize">propeller_optimize</a> - <br /> - </td> - </tr> - <tr> - <td class="lang">Java</td> - <td></td> - - <td> - <a href="java.html#java_binary">java_binary</a> - <br /> - </td> - <td> - <a href="java.html#java_import">java_import</a> - <br /> - <a href="java.html#java_library">java_library</a> - <br /> - </td> - <td> - <a href="java.html#java_test">java_test</a> - <br /> - </td> - <td> - <a href="java.html#java_package_configuration">java_package_configuration</a> - <br /> - <a href="java.html#java_plugin">java_plugin</a> - <br /> - <a href="java.html#java_runtime">java_runtime</a> - <br /> - <a href="java.html#java_single_jar">java_single_jar</a> - <br /> - <a href="java.html#java_toolchain">java_toolchain</a> - <br /> - </td> - </tr> - <tr> - <td class="lang">Objective-C</td> - <td></td> - - <td> - </td> - <td> - <a href="objective-c.html#objc_import">objc_import</a> - <br /> - <a href="objective-c.html#objc_library">objc_library</a> - <br /> - </td> - <td> - </td> - <td> - </td> - </tr> - <tr> - <td class="lang">Protocol Buffer</td> - <td></td> - - <td> - </td> - <td> - <a href="protocol-buffer.html#cc_proto_library">cc_proto_library</a> - <br /> - <a href="protocol-buffer.html#java_lite_proto_library">java_lite_proto_library</a> - <br /> - <a href="protocol-buffer.html#java_proto_library">java_proto_library</a> - <br /> - <a href="protocol-buffer.html#proto_library">proto_library</a> - <br /> - <a href="protocol-buffer.html#py_proto_library">py_proto_library</a> - <br /> - </td> - <td> - </td> - <td> - <a href="protocol-buffer.html#proto_lang_toolchain">proto_lang_toolchain</a> - <br /> - <a href="protocol-buffer.html#proto_toolchain">proto_toolchain</a> - <br /> - </td> - </tr> - <tr> - <td class="lang">Python</td> - <td></td> - - <td> - <a href="python.html#py_binary">py_binary</a> - <br /> - </td> - <td> - <a href="python.html#py_library">py_library</a> - <br /> - </td> - <td> - <a href="python.html#py_test">py_test</a> - <br /> - </td> - <td> - <a href="python.html#py_runtime">py_runtime</a> - <br /> - </td> - </tr> - <tr> - <td class="lang">Shell</td> - <td></td> - - <td> - <a href="shell.html#sh_binary">sh_binary</a> - <br /> - </td> - <td> - <a href="shell.html#sh_library">sh_library</a> - <br /> - </td> - <td> - <a href="shell.html#sh_test">sh_test</a> - <br /> - </td> - <td> - </td> - </tr> - </tbody> - +[recommended rules](/rules/rules#recommended-rules). + +### Language-specific native rules + +<table class="table table-condensed table-striped" style="width:100%;" data-summary="Table of rules sorted by language"> +<colgroup> +<col style="width: 16%" /> +<col style="width: 16%" /> +<col style="width: 16%" /> +<col style="width: 16%" /> +<col style="width: 16%" /> +<col style="width: 16%" /> +</colgroup> +<thead> +<tr> +<th>Language</th> +<th>Flags</th> +<th>Binary rules</th> +<th>Library rules</th> +<th>Test rules</th> +<th>Other rules</th> +</tr> +</thead> +<tbody> +<tr> +<td class="lang">C / C++</td> +<td></td> +<td><a href="c-cpp.html#cc_binary">cc_binary</a><br /> +</td> +<td><a href="c-cpp.html#cc_import">cc_import</a><br /> +<a href="c-cpp.html#cc_library">cc_library</a><br /> +<a href="c-cpp.html#cc_shared_library">cc_shared_library</a><br /> +<a href="c-cpp.html#cc_static_library">cc_static_library</a><br /> +</td> +<td><a href="c-cpp.html#cc_test">cc_test</a><br /> +</td> +<td><a href="c-cpp.html#cc_toolchain">cc_toolchain</a><br /> +<a href="c-cpp.html#fdo_prefetch_hints">fdo_prefetch_hints</a><br /> +<a href="c-cpp.html#fdo_profile">fdo_profile</a><br /> +<a href="c-cpp.html#memprof_profile">memprof_profile</a><br /> +<a href="c-cpp.html#propeller_optimize">propeller_optimize</a><br /> +</td> +</tr> +<tr> +<td class="lang">Java</td> +<td></td> +<td><a href="java.html#java_binary">java_binary</a><br /> +</td> +<td><a href="java.html#java_import">java_import</a><br /> +<a href="java.html#java_library">java_library</a><br /> +</td> +<td><a href="java.html#java_test">java_test</a><br /> +</td> +<td><a href="java.html#java_package_configuration">java_package_configuration</a><br /> +<a href="java.html#java_plugin">java_plugin</a><br /> +<a href="java.html#java_runtime">java_runtime</a><br /> +<a href="java.html#java_single_jar">java_single_jar</a><br /> +<a href="java.html#java_toolchain">java_toolchain</a><br /> +</td> +</tr> +<tr> +<td class="lang">Objective-C</td> +<td></td> +<td></td> +<td><a href="objective-c.html#objc_import">objc_import</a><br /> +<a href="objective-c.html#objc_library">objc_library</a><br /> +</td> +<td></td> +<td></td> +</tr> +<tr> +<td class="lang">Protocol Buffer</td> +<td></td> +<td></td> +<td><a href="protocol-buffer.html#cc_proto_library">cc_proto_library</a><br /> +<a href="protocol-buffer.html#java_lite_proto_library">java_lite_proto_library</a><br /> +<a href="protocol-buffer.html#java_proto_library">java_proto_library</a><br /> +<a href="protocol-buffer.html#proto_library">proto_library</a><br /> +<a href="protocol-buffer.html#py_proto_library">py_proto_library</a><br /> +</td> +<td></td> +<td><a href="protocol-buffer.html#proto_lang_toolchain">proto_lang_toolchain</a><br /> +<a href="protocol-buffer.html#proto_toolchain">proto_toolchain</a><br /> +</td> +</tr> +<tr> +<td class="lang">Python</td> +<td></td> +<td><a href="python.html#py_binary">py_binary</a><br /> +</td> +<td><a href="python.html#py_library">py_library</a><br /> +</td> +<td><a href="python.html#py_test">py_test</a><br /> +</td> +<td><a href="python.html#py_runtime">py_runtime</a><br /> +</td> +</tr> +<tr> +<td class="lang">Shell</td> +<td></td> +<td><a href="shell.html#sh_binary">sh_binary</a><br /> +</td> +<td><a href="shell.html#sh_library">sh_library</a><br /> +</td> +<td><a href="shell.html#sh_test">sh_test</a><br /> +</td> +<td></td> +</tr> +</tbody> </table> -<h3>Language-agnostic native rules</h3> - -<table class="table table-condensed table-striped" summary="Table of rules not specific to a programming language"> - <thead> - <tr> - <th>Family</th> - <th>Rules</th> - </tr> - </thead> - <tbody> - <tr> - <td class="lang">Extra Actions</td> - <td> - <ul class="hlist"> - <li> <a href="extra-actions.html#action_listener">action_listener</a> - <li> <a href="extra-actions.html#extra_action">extra_action</a> - </ul> - </td> - </tr> - <tr> - <td class="lang">General</td> - <td> - <ul class="hlist"> - <li> <a href="general.html#alias">alias</a> - <li> <a href="general.html#config_setting">config_setting</a> - <li> <a href="general.html#filegroup">filegroup</a> - <li> <a href="general.html#genquery">genquery</a> - <li> <a href="general.html#genrule">genrule</a> - <li> <a href="general.html#starlark_doc_extract">starlark_doc_extract</a> - <li> <a href="general.html#test_suite">test_suite</a> - </ul> - </td> - </tr> - <tr> - <td class="lang">Platforms and Toolchains</td> - <td> - <ul class="hlist"> - <li> <a href="platforms-and-toolchains.html#constraint_setting">constraint_setting</a> - <li> <a href="platforms-and-toolchains.html#constraint_value">constraint_value</a> - <li> <a href="platforms-and-toolchains.html#platform">platform</a> - <li> <a href="platforms-and-toolchains.html#toolchain">toolchain</a> - <li> <a href="platforms-and-toolchains.html#toolchain_type">toolchain_type</a> - </ul> - </td> - </tr> - </tbody> +### Language-agnostic native rules + +<table class="table table-condensed table-striped" data-summary="Table of rules not specific to a programming language"> +<colgroup> +<col style="width: 50%" /> +<col style="width: 50%" /> +</colgroup> +<thead> +<tr> +<th>Family</th> +<th>Rules</th> +</tr> +</thead> +<tbody> +<tr> +<td class="lang">Extra Actions</td> +<td><ul> +<li><a href="extra-actions.html#action_listener">action_listener</a></li> +<li><a href="extra-actions.html#extra_action">extra_action</a></li> +</ul></td> +</tr> +<tr> +<td class="lang">General</td> +<td><ul> +<li><a href="general.html#alias">alias</a></li> +<li><a href="general.html#config_setting">config_setting</a></li> +<li><a href="general.html#filegroup">filegroup</a></li> +<li><a href="general.html#genquery">genquery</a></li> +<li><a href="general.html#genrule">genrule</a></li> +<li><a href="general.html#starlark_doc_extract">starlark_doc_extract</a></li> +<li><a href="general.html#test_suite">test_suite</a></li> +</ul></td> +</tr> +<tr> +<td class="lang">Platforms and Toolchains</td> +<td><ul> +<li><a href="platforms-and-toolchains.html#constraint_setting">constraint_setting</a></li> +<li><a href="platforms-and-toolchains.html#constraint_value">constraint_value</a></li> +<li><a href="platforms-and-toolchains.html#platform">platform</a></li> +<li><a href="platforms-and-toolchains.html#toolchain">toolchain</a></li> +<li><a href="platforms-and-toolchains.html#toolchain_type">toolchain_type</a></li> +</ul></td> +</tr> +</tbody> </table> -</body> -</html> diff --git a/reference/be/platforms-and-toolchains.mdx b/reference/be/platforms-and-toolchains.mdx index 23ecc85..4aae3b8 100644 --- a/reference/be/platforms-and-toolchains.mdx +++ b/reference/be/platforms-and-toolchains.mdx @@ -2,214 +2,143 @@ title: 'platforms-and-toolchains' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">Platforms and Toolchains Rules</h1> +# Platforms and Toolchains Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} +{% 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="/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="common-definitions.html#common.aspect_hints">aspect_hints</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.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. +The user should be familiar with the concepts explained [here](/extending/platforms). -For more details, see the -<a href="https://bazel.build/docs/platforms">Platforms</a> page. +## Rules -<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. +- [constraint_setting](#constraint_setting) +- [constraint_value](#constraint_value) +- [platform](#platform) +- [toolchain](#toolchain) +- [toolchain_type](#toolchain_type) +## constraint_setting +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintSettingRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <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="/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="/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> - </table> - <h2 id="constraint_value"> - constraint_value - </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/ConstraintValueRule.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_value(<a href="#constraint_value.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.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> +``` rule-signature +constraint_setting(name, aspect_hints, default_constraint_value, deprecation, features, licenses, tags, testonly, visibility) +``` +This rule is used to introduce a new constraint type for which a platform may specify a value. +For instance, you might define a `constraint_setting` named "glibc_version" to represent +the capability for platforms to have different versions of the glibc library installed. +For more details, see the +[Platforms](https://bazel.build/docs/platforms) page. -This rule introduces a new value for a given constraint type. +Each `constraint_setting` has an extensible set of associated +`constraint_value`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 `@platforms//cpu:cpu` can be extended with a custom value in order to +define a platform targeting an obscure cpu architecture. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="constraint_setting.name"><code>name</code></td> +<td><p><a href="/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="/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.</p></td> +</tr> +</tbody> +</table> + +## constraint_value + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintValueRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +constraint_value(name, aspect_hints, constraint_setting, deprecation, features, licenses, tags, testonly, visibility) +``` +This rule introduces a new value for a given constraint type. For more details, see the -<a href="https://bazel.build/docs/platforms">Platforms</a> page. +[Platforms](https://bazel.build/docs/platforms) page. + +#### Example -<h4 id="constraint_value_examples">Example</h4> -<p>The following creates a new possible value for the predefined <code>constraint_value</code> +The following creates a new possible value for the predefined `constraint_value` representing cpu architecture. -<pre class="code"> + +``` 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="/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="/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> - </table> - <h2 id="platform"> - platform - </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/PlatformRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">platform(<a href="#platform.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#platform.constraint_values">constraint_values</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#platform.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#platform.flags">flags</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#platform.missing_toolchain_error">missing_toolchain_error</a>, <a href="#platform.parents">parents</a>, <a href="#platform.remote_execution_properties">remote_execution_properties</a>, <a href="#platform.required_settings">required_settings</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 +``` + +Platforms can then declare that they have the `mips` architecture as an alternative to +`x86_64`, `arm`, and so on. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="constraint_value.name"><code>name</code></td> +<td><p><a href="/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="/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> +</table> + +## platform + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +platform(name, aspect_hints, constraint_values, deprecation, exec_properties, features, flags, licenses, missing_toolchain_error, parents, remote_execution_properties, required_settings, tags, testonly, visibility) +``` + +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 [Platforms](/extending/platforms) page. + +#### Example -For more details, see the <a href="/extending/platforms">Platforms</a> page. +This defines a platform that describes any environment running Linux on ARM. +``` code -<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 = [ @@ -217,23 +146,21 @@ platform( "@platforms//cpu:arm", ], ) -</pre> +``` + +### Platform Flags -<h3 id="platform_flags">Platform Flags</h3> -<p> - Platforms may use the <code>flags</code> attribute to specify a list of flags that will be added - to the configuration whenever the platform is used as the target platform (i.e., as the value of - the <code>--platforms</code> flag). -</p> +Platforms may use the `flags` attribute to specify a list of flags that will be added +to the configuration whenever the platform is used as the target platform (i.e., as the value of +the `--platforms` flag). -<p> - Flags set from the platform effectively have the highest precedence and overwrite any previous - value for that flag, from the command line, rc file, or transition. -</p> +Flags set from the platform effectively have the highest precedence and overwrite any previous +value for that flag, from the command line, rc file, or transition. -<h4 id="platform_flags_examples">Example</h4> +#### Example + +``` code -<pre class="code"> platform( name = "foo", flags = [ @@ -242,33 +169,27 @@ platform( "--no//package:other_bool_flag", ], ) -</pre> - -<p> - This defines a platform named <code>foo</code>. When this is the target platform (either because - the user specified <code>--platforms//:foo</code>, because a transition set the - <code>//command_line_option:platforms</code> flag to <code>["//:foo"]</code>, or because - <code>//:foo</code> was used as an execution platform), then the given flags will be set in the - configuration. -</p> - -<h4 id=platform_flags_repeated>Platforms and Repeatable Flags</h4> - -<p> - Some flags will accumulate values when they are repeated, such as <code>--features</code>, - <code>--copt</code>, any Starlark flag created as <code>config.string(repeatable = True)</code>. - These flags are not compatible with setting the flags from the platform: instead, all previous - values will be removed and overwritten with the values from the platform. -</p> - -<p> - As an example, given the following platform, the invocation <code>build --platforms=//:repeat_demo - --features feature_a --features feature_b</code> will end up with the value of the - <code>--feature</code> flag being <code>["feature_c", "feature_d"]</code>, removing the features - set on the command line. -</p> - -<pre class="code"> +``` + +This defines a platform named `foo`. When this is the target platform (either because +the user specified `--platforms//:foo`, because a transition set the +`//command_line_option:platforms` flag to `["//:foo"]`, or because +`//:foo` was used as an execution platform), then the given flags will be set in the +configuration. + +#### Platforms and Repeatable Flags + +Some flags will accumulate values when they are repeated, such as `--features`, +`--copt`, any Starlark flag created as `config.string(repeatable = True)`. +These flags are not compatible with setting the flags from the platform: instead, all previous +values will be removed and overwritten with the values from the platform. + +As an example, given the following platform, the invocation `build --platforms=//:repeat_demo --features feature_a --features feature_b` will end up with the value of the +`--feature` flag being `["feature_c", "feature_d"]`, removing the features +set on the command line. + +``` code + platform( name = "repeat_demo", flags = [ @@ -276,71 +197,53 @@ platform( "--features=feature_d", ], ) -</pre> - -<p> - For this reason, it is discouraged to use repeatable flags in the <code>flags</code> attribute. -</p> - -<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"> +``` + +For this reason, it is discouraged to use repeatable flags in the `flags` attribute. + +### Platform Inheritance + +Platforms may use the `parents` attribute to specify another platform that they will +inherit constraint values from. Although the `parents` attribute takes a list, no +more than a single value is currently supported, and specifying multiple parents is an error. + +When checking for the value of a constraint setting in a platform, first the values directly set +(via the `constraint_values` 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. + +Platforms inherit the `exec_properties` attribute from the parent platform. +The dictionary entries in `exec_properties` of the parent and child platforms +will be combined. +If the same key appears in both the parent's and the child's `exec_properties`, +the child's value will be used. If the child platform specifies an empty string as a value, the +corresponding property will be unset. + +Platforms can also inherit the (deprecated) `remote_execution_properties` attribute +from the parent platform. Note: new code should use `exec_properties` 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 `remote_execution_platform` is as follows when there +is a parent platform: + +1. If `remote_execution_property` is not set on the child platform, the parent's + `remote_execution_properties` will be used. +2. If `remote_execution_property` is set on the child platform, and contains the + literal string {PARENT_REMOTE_EXECUTION_PROPERTIES}, that macro will be + replaced with the contents of the parent's `remote_execution_property` attribute. +3. If `remote_execution_property` is set on the child platform, and does not contain + the macro, the child's `remote_execution_property` will be used unchanged. + +*Since `remote_execution_properties` is deprecated and will be phased out, mixing +`remote_execution_properties` and `exec_properties` in the same +inheritance chain is not allowed.* +Prefer to use `exec_properties` over the deprecated +`remote_execution_properties`. + +#### Example: Constraint Values + +``` code + platform( name = "parent", constraint_values = [ @@ -359,25 +262,19 @@ 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"> +``` + +In this example, the child platforms have the following properties: + +- `child_a` has the constraint values `@platforms//os:linux` (inherited + from the parent) and `@platforms//cpu:x86_64` (set directly on the platform). +- `child_b` inherits all constraint values from the parent, and doesn't set any of + its own. + +#### Example: Execution properties + +``` code + platform( name = "parent", exec_properties = { @@ -410,300 +307,194 @@ platform( "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="/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="/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.flags"> - <code>flags</code> - </td> - <td> - <p>List of strings; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> - A list of flags that will be enabled when this platform is used as the target platform in - a configuration. Only flags that are part of the configuration can be set, such as those - that can be used in transitions, or the <code>--define</code> flag. - - </td> - </tr> - <tr> - <td id="platform.missing_toolchain_error"> - <code>missing_toolchain_error</code> - </td> - <td> - <p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>"For more information on platforms or toolchains see https://bazel.build/concepts/platforms-intro."</code></p> - A custom error message that is displayed when a mandatory toolchain requirement cannot be satisfied for this target platform. Intended to point to relevant documentation users can read to understand why their toolchains are misconfigured. - - Not inherited from parent platforms. - - </td> - </tr> - <tr> - <td id="platform.parents"> - <code>parents</code> - </td> - <td> - <p>List of <a href="/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> - <tr> - <td id="platform.required_settings"> - <code>required_settings</code> - </td> - <td> - <p>List of <a href="/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 platform to be used as an execution platform during toolchain resolution. - - Required settings are not inherited from parent platforms. - - </td> - </tr> - </tbody> - </table> - <h2 id="toolchain"> - toolchain - </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/ToolchainRule.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">toolchain(<a href="#toolchain.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#toolchain.exec_compatible_with">exec_compatible_with</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.package_metadata">package_metadata</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="#toolchain.use_target_platform_constraints">use_target_platform_constraints</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 +``` + +In this example, the child platforms have the following properties: + +- `child_a` inherits the "exec_properties" of the parent and does not set its own. +- `child_b` inherits the parent's `exec_properties` and overrides the + value of `k1`. Its `exec_properties` will be: + `{ "k1": "child", "k2": "v2" }`. +- `child_c` inherits the parent's `exec_properties` and unsets + `k1`. Its `exec_properties` will be: + `{ "k2": "v2" }`. +- `child_d` inherits the parent's `exec_properties` and adds a new + property. Its `exec_properties` will be: + `{ "k1": "v1", "k2": "v2", "k3": "v3" }`. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="platform.name"><code>name</code></td> +<td><p><a href="/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="/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>.</p></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.flags"><code>flags</code></td> +<td><p>List of strings; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> +A list of flags that will be enabled when this platform is used as the target platform in +a configuration. Only flags that are part of the configuration can be set, such as those +that can be used in transitions, or the <code>--define</code> flag.</td> +</tr> +<tr> +<td id="platform.missing_toolchain_error"><code>missing_toolchain_error</code></td> +<td><p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>"For more information on platforms or toolchains see https://bazel.build/concepts/platforms-intro."</code></p> +A custom error message that is displayed when a mandatory toolchain requirement cannot be satisfied for this target platform. Intended to point to relevant documentation users can read to understand why their toolchains are misconfigured. +Not inherited from parent platforms.</td> +</tr> +<tr> +<td id="platform.parents"><code>parents</code></td> +<td><p>List of <a href="/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> +<tr> +<td id="platform.required_settings"><code>required_settings</code></td> +<td><p>List of <a href="/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 platform to be used as an execution platform during toolchain resolution. +Required settings are not inherited from parent platforms.</td> +</tr> +</tbody> +</table> + +## toolchain + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ToolchainRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +toolchain(name, aspect_hints, deprecation, exec_compatible_with, features, licenses, package_metadata, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, use_target_platform_constraints, visibility) +``` + +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/docs/toolchains">Toolchains</a> page for more +[Toolchains](https://bazel.build/docs/toolchains) page for more details. +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="toolchain.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</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>List of <a href="/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="/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="/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="/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="/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> +<tr> +<td id="toolchain.use_target_platform_constraints"><code>use_target_platform_constraints</code></td> +<td><p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> +If <code>True</code>, this toolchain behaves as if its <code>exec_compatible_with</code> and +<code>target_compatible_with</code> constraints are set to those of the current target +platform. <code>exec_compatible_with</code> and <code>target_compatible_with</code> must not +be set in that case.</td> +</tr> +</tbody> +</table> + +## toolchain_type + +<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/ToolchainType.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +toolchain_type(name, aspect_hints, compatible_with, deprecation, features, no_match_error, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) +``` + +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. + +See the [Toolchains](/docs/toolchains) page for more details. + +#### Example + +This defines a toolchain type for a custom rule. + +``` code - - <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><a href="/concepts/labels#target-names">Name</a>; required</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>List of <a href="/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="/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="/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="/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="/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> - <tr> - <td id="toolchain.use_target_platform_constraints"> - <code>use_target_platform_constraints</code> - </td> - <td> - <p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> - If <code>True</code>, this toolchain behaves as if its <code>exec_compatible_with</code> and - <code>target_compatible_with</code> constraints are set to those of the current target - platform. <code>exec_compatible_with</code> and <code>target_compatible_with</code> must not - be set in that case. - - </td> - </tr> - </tbody> - </table> - <h2 id="toolchain_type"> - toolchain_type - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/ToolchainType.java" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">toolchain_type(<a href="#toolchain_type.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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="#toolchain_type.no_match_error">no_match_error</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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="/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> +``` + +This can be used in a bzl file. + +``` code -<p> - This can be used in a bzl file. -</p> -<pre class="code"> bar_binary = rule( implementation = _bar_binary_impl, attrs = { @@ -713,43 +504,26 @@ bar_binary = rule( }, 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><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="toolchain_type.no_match_error"> - <code>no_match_error</code> - </td> - <td> - <p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>""</code></p> - A custom error message to display when no matching toolchain is found for this type. - - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="toolchain_type.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="toolchain_type.no_match_error"><code>no_match_error</code></td> +<td><p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>""</code></p> +A custom error message to display when no matching toolchain is found for this type.</td> +</tr> +</tbody> +</table> diff --git a/reference/be/protocol-buffer.mdx b/reference/be/protocol-buffer.mdx index 7129166..e195cb8 100644 --- a/reference/be/protocol-buffer.mdx +++ b/reference/be/protocol-buffer.mdx @@ -2,159 +2,91 @@ title: 'protocol-buffer' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">Protocol Buffer Rules</h1> +# Protocol Buffer Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} +{% include "\_buttons.html" %} +## Rules +- [cc_proto_library](#cc_proto_library) +- [java_lite_proto_library](#java_lite_proto_library) +- [java_proto_library](#java_proto_library) +- [proto_library](#proto_library) +- [py_proto_library](#py_proto_library) +- [proto_lang_toolchain](#proto_lang_toolchain) +- [proto_toolchain](#proto_toolchain) +## cc_proto_library + +<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_cc_proto_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +cc_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`cc_proto_library` generates C++ code from `.proto` files. + +`deps` must point to [`proto_library `](protocol-buffer.html#proto_library) rules. -<h2>Rules</h2> -<ul> - <li> - <a href="#cc_proto_library"> - cc_proto_library </a> - </li> - <li> - <a href="#java_lite_proto_library"> - java_lite_proto_library </a> - </li> - <li> - <a href="#java_proto_library"> - java_proto_library </a> - </li> - <li> - <a href="#proto_library"> - proto_library </a> - </li> - <li> - <a href="#py_proto_library"> - py_proto_library </a> - </li> - <li> - <a href="#proto_lang_toolchain"> - proto_lang_toolchain </a> - </li> - <li> - <a href="#proto_toolchain"> - proto_toolchain </a> - </li> -</ul> - - <h2 id="cc_proto_library"> - cc_proto_library - </h2> - - <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_cc_proto_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">cc_proto_library(<a href="#cc_proto_library.name">name</a>, <a href="#cc_proto_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> -<code>cc_proto_library</code> generates C++ code from <code>.proto</code> files. -</p> - -<p> -<code>deps</code> must point to <a href="protocol-buffer.html#proto_library"><code>proto_library -</code></a> rules. -</p> - -<p> Example: -</p> -<pre> -<code class="lang-starlark"> -cc_library( - name = "lib", - deps = [":foo_cc_proto"], -) -cc_proto_library( - name = "foo_cc_proto", - deps = [":foo_proto"], -) -proto_library( - name = "foo_proto", -) -</code> -</pre> - - <h3 id="cc_proto_library_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="cc_proto_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="cc_proto_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> -rules to generate C++ code for. - </td> - </tr> - </tbody> - </table> - <h2 id="java_lite_proto_library"> - java_lite_proto_library - </h2> - - <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/java_lite_proto_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_lite_proto_library(<a href="#java_lite_proto_library.name">name</a>, <a href="#java_lite_proto_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> -<code>java_lite_proto_library</code> generates Java code from <code>.proto</code> files. -</p> - -<p> -<code>deps</code> must point to <a href="protocol-buffer.html#proto_library"><code>proto_library -</code></a> rules. -</p> - -<p> + cc_library( + name = "lib", + deps = [":foo_cc_proto"], + ) + + cc_proto_library( + name = "foo_cc_proto", + deps = [":foo_proto"], + ) + + proto_library( + name = "foo_proto", + ) + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="cc_proto_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="cc_proto_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> +rules to generate C++ code for.</td> +</tr> +</tbody> +</table> + +## java_lite_proto_library + +<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/java_lite_proto_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_lite_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`java_lite_proto_library` generates Java code from `.proto` files. + +`deps` must point to [`proto_library `](protocol-buffer.html#proto_library) rules. + Example: -</p> -<pre class="code"> -<code class="lang-starlark"> +``` code + + java_library( name = "lib", runtime_deps = [":foo"], @@ -168,66 +100,48 @@ java_lite_proto_library( proto_library( name = "bar", ) -</code> -</pre> - - <h3 id="java_lite_proto_library_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="java_lite_proto_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_lite_proto_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> -rules to generate Java code for. - </td> - </tr> - </tbody> - </table> - <h2 id="java_proto_library"> - java_proto_library - </h2> - - <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_java_proto_library_rule.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">java_proto_library(<a href="#java_proto_library.name">name</a>, <a href="#java_proto_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> -<code>java_proto_library</code> generates Java code from <code>.proto</code> files. -</p> - -<p> -<code>deps</code> must point to <a href="protocol-buffer.html#proto_library"><code>proto_library -</code></a> rules. -</p> - -<p> +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_lite_proto_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_lite_proto_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> +rules to generate Java code for.</td> +</tr> +</tbody> +</table> + +## java_proto_library + +<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_java_proto_library_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +java_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`java_proto_library` generates Java code from `.proto` files. + +`deps` must point to [`proto_library `](protocol-buffer.html#proto_library) rules. + Example: -</p> -<pre class="code"> -<code class="lang-starlark"> +``` code + + java_library( name = "lib", runtime_deps = [":foo_java_proto"], @@ -241,530 +155,364 @@ java_proto_library( proto_library( name = "foo_proto", ) -</code> -</pre> - - <h3 id="java_proto_library_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="java_proto_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="java_proto_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> -rules to generate Java code for. - </td> - </tr> - </tbody> - </table> - <h2 id="proto_library"> - proto_library - </h2> - - <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_library_rule.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">proto_library(<a href="#proto_library.name">name</a>, <a href="#proto_library.deps">deps</a>, <a href="#proto_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#proto_library.allow_exports">allow_exports</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#proto_library.exports">exports</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#proto_library.import_prefix">import_prefix</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#proto_library.option_deps">option_deps</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#proto_library.strip_import_prefix">strip_import_prefix</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p>Use <code>proto_library</code> to define libraries of protocol buffers which -may be used from multiple languages. A <code>proto_library</code> may be listed -in the <code>deps</code> clause of supported rules, such as -<code>java_proto_library</code>. - -<p>When compiled on the command-line, a <code>proto_library</code> creates a file -named <code>foo-descriptor-set.proto.bin</code>, which is the descriptor set for +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="java_proto_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="java_proto_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> +rules to generate Java code for.</td> +</tr> +</tbody> +</table> + +## proto_library + +<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_library_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +proto_library(name, deps, srcs, data, allow_exports, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exports, features, import_prefix, licenses, option_deps, package_metadata, restricted_to, strip_import_prefix, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Use `proto_library` to define libraries of protocol buffers which +may be used from multiple languages. A `proto_library` may be listed +in the `deps` clause of supported rules, such as +`java_proto_library`. + +When compiled on the command-line, a `proto_library` creates a file +named `foo-descriptor-set.proto.bin`, which is the descriptor set for the messages the rule srcs. The file is a serialized -<code>FileDescriptorSet</code>, which is described in -<a href="https://developers.google.com/protocol-buffers/docs/techniques#self-description"> -https://developers.google.com/protocol-buffers/docs/techniques#self-description</a>. +`FileDescriptorSet`, which is described in +<https://developers.google.com/protocol-buffers/docs/techniques#self-description>. -<p>It only contains information about the <code>.proto</code> files directly -mentioned by a <code>proto_library</code> rule; the collection of transitive +It only contains information about the `.proto` files directly +mentioned by a `proto_library` rule; the collection of transitive descriptor sets is available through the -<code>[ProtoInfo].transitive_descriptor_sets</code> Starlark provider. -See documentation in <code>proto_info.bzl</code>. +`[ProtoInfo].transitive_descriptor_sets` Starlark provider. +See documentation in `proto_info.bzl`. -<p>Recommended code organization: -<ul> -<li>One <code>proto_library</code> rule per <code>.proto</code> file. -<li>A file named <code>foo.proto</code> will be in a rule named <code>foo_proto</code>, +Recommended code organization: + +- One `proto_library` rule per `.proto` file. +- A file named `foo.proto` will be in a rule named `foo_proto`, which is located in the same package. -<li>A <code>[language]_proto_library</code> that wraps a <code>proto_library</code> - named <code>foo_proto</code> should be called <code>foo_[language]_proto</code>, +- A `[language]_proto_library` that wraps a `proto_library` + named `foo_proto` should be called `foo_[language]_proto`, and be located in the same package. -</ul> - - <h3 id="proto_library_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="proto_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="proto_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other <code>proto_library</code> rules that the target depends upon. + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="proto_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="proto_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other <code>proto_library</code> rules that the target depends upon. A <code>proto_library</code> may only depend on other <code>proto_library</code> -targets. It may not depend on language-specific libraries. - </td> - </tr> - <tr> - <td id="proto_library.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of <code>.proto</code> and <code>.protodevel</code> files that are +targets. It may not depend on language-specific libraries.</td> +</tr> +<tr> +<td id="proto_library.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of <code>.proto</code> and <code>.protodevel</code> files that are processed to create the target. This is usually a non empty list. One usecase -where <code>srcs</code> can be empty is an <i>alias-library</i>. This is a +where <code>srcs</code> can be empty is an <em>alias-library</em>. This is a proto_library rule having one or more other proto_library in <code>deps</code>. -This pattern can be used to e.g. export a public api under a persistent name. - </td> - </tr> - <tr> - <td id="proto_library.allow_exports"> - <code>allow_exports</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - An optional allowlist that prevents proto library to be reexported or used in -lang_proto_library that is not in one of the listed packages. - </td> - </tr> - <tr> - <td id="proto_library.exports"> - <code>exports</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - List of proto_library targets that can be referenced via "import public" in the +This pattern can be used to e.g. export a public api under a persistent name.</td> +</tr> +<tr> +<td id="proto_library.allow_exports"><code>allow_exports</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +An optional allowlist that prevents proto library to be reexported or used in +lang_proto_library that is not in one of the listed packages.</td> +</tr> +<tr> +<td id="proto_library.exports"><code>exports</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +List of proto_library targets that can be referenced via "import public" in the proto source. It's an error if you use "import public" but do not list the corresponding library in the exports attribute. Note that you have list the library both in deps and exports since not all -lang_proto_library implementations have been changed yet. - </td> - </tr> - <tr> - <td id="proto_library.import_prefix"> - <code>import_prefix</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The prefix to add to the paths of the .proto files in this rule. - +lang_proto_library implementations have been changed yet.</td> +</tr> +<tr> +<td id="proto_library.import_prefix"><code>import_prefix</code></td> +<td><p>String; default is <code>""</code></p> +The prefix to add to the paths of the .proto files in this rule. <p>When set, the .proto source files in the <code>srcs</code> attribute of this rule are -accessible at is the value of this attribute prepended to their repository-relative path. - +accessible at is the value of this attribute prepended to their repository-relative path.</p> <p>The prefix in the <code>strip_import_prefix</code> attribute is removed before this -prefix is added. - </td> - </tr> - <tr> - <td id="proto_library.option_deps"> - <code>option_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of other <code>proto_library</code> rules that the target depends upon for options only. +prefix is added.</p></td> +</tr> +<tr> +<td id="proto_library.option_deps"><code>option_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of other <code>proto_library</code> rules that the target depends upon for options only. A <code>proto_library</code> may only depend on other <code>proto_library</code> -targets. It may not depend on language-specific libraries. - </td> - </tr> - <tr> - <td id="proto_library.strip_import_prefix"> - <code>strip_import_prefix</code> - </td> - <td> - <p>String; default is <code>"/"</code></p> - The prefix to strip from the paths of the .proto files in this rule. - +targets. It may not depend on language-specific libraries.</td> +</tr> +<tr> +<td id="proto_library.strip_import_prefix"><code>strip_import_prefix</code></td> +<td><p>String; default is <code>"/"</code></p> +The prefix to strip from the paths of the .proto files in this rule. <p>When set, .proto source files in the <code>srcs</code> attribute of this rule are -accessible at their path with this prefix cut off. - +accessible at their path with this prefix cut off.</p> <p>If it's a relative path (not starting with a slash), it's taken as a package-relative -one. If it's an absolute one, it's understood as a repository-relative path. - +one. If it's an absolute one, it's understood as a repository-relative path.</p> <p>The prefix in the <code>import_prefix</code> attribute is added after this prefix is -stripped. - </td> - </tr> - </tbody> - </table> - <h2 id="py_proto_library"> - py_proto_library - </h2> +stripped.</p></td> +</tr> +</tbody> +</table> - <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/py_proto_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +## py_proto_library - <pre class="rule-signature">py_proto_library(<a href="#py_proto_library.name">name</a>, <a href="#py_proto_library.deps">deps</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/py_proto_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - Use `py_proto_library` to generate Python libraries from `.proto` files. - - The convention is to name the `py_proto_library` rule `foo_py_pb2`, - when it is wrapping `proto_library` rule `foo_proto`. - - `deps` must point to a `proto_library` rule. - - Example: +``` rule-signature +py_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` -```starlark +Use \`py_proto_library\` to generate Python libraries from \`.proto\` files. +The convention is to name the \`py_proto_library\` rule \`foo_py_pb2\`, +when it is wrapping \`proto_library\` rule \`foo_proto\`. +\`deps\` must point to a \`proto_library\` rule. +Example: +\`\`\`starlark py_library( - name = "lib", - deps = [":foo_py_pb2"], +name = "lib", +deps = \[":foo_py_pb2"\], ) - py_proto_library( - name = "foo_py_pb2", - deps = [":foo_proto"], +name = "foo_py_pb2", +deps = \[":foo_proto"\], ) - proto_library( - name = "foo_proto", - srcs = ["foo.proto"], +name = "foo_proto", +srcs = \["foo.proto"\], ) -``` - - <h3 id="py_proto_library_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="py_proto_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="py_proto_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of `proto_library` rules to generate Python libraries for. - +\`\`\` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="py_proto_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="py_proto_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of `proto_library` rules to generate Python libraries for. Usually this is just the one target: the proto library of interest. -It can be any target providing `ProtoInfo`. - </td> - </tr> - </tbody> - </table> - <h2 id="proto_lang_toolchain"> - proto_lang_toolchain - </h2> +It can be any target providing `ProtoInfo`.</td> +</tr> +</tbody> +</table> + +## proto_lang_toolchain - <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_lang_toolchain_rule.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_lang_toolchain_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - <pre class="rule-signature">proto_lang_toolchain(<a href="#proto_lang_toolchain.name">name</a>, <a href="#proto_lang_toolchain.allowlist_different_package">allowlist_different_package</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#proto_lang_toolchain.blacklisted_protos">blacklisted_protos</a>, <a href="#proto_lang_toolchain.command_line">command_line</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#proto_lang_toolchain.denylisted_protos">denylisted_protos</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#proto_lang_toolchain.mnemonic">mnemonic</a>, <a href="#proto_lang_toolchain.output_files">output_files</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#proto_lang_toolchain.plugin">plugin</a>, <a href="#proto_lang_toolchain.plugin_format_flag">plugin_format_flag</a>, <a href="#proto_lang_toolchain.progress_message">progress_message</a>, <a href="#proto_lang_toolchain.protoc_minimal_do_not_use">protoc_minimal_do_not_use</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#proto_lang_toolchain.runtime">runtime</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="#proto_lang_toolchain.toolchain_type">toolchain_type</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +``` rule-signature +proto_lang_toolchain(name, allowlist_different_package, aspect_hints, blacklisted_protos, command_line, compatible_with, denylisted_protos, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, mnemonic, output_files, package_metadata, plugin, plugin_format_flag, progress_message, protoc_minimal_do_not_use, restricted_to, runtime, tags, target_compatible_with, testonly, toolchain_type, toolchains, visibility) +``` - <p>If using Bazel, please load the rule from <a href="https://github.com/bazelbuild/rules_proto"> -https://github.com/bazelbuild/rules_proto</a>. +If using Bazel, please load the rule from +<https://github.com/bazelbuild/rules_proto>. -<p>Specifies how a LANG_proto_library rule (e.g., <code>java_proto_library</code>) should invoke the +Specifies how a LANG_proto_library rule (e.g., `java_proto_library`) should invoke the proto-compiler. Some LANG_proto_library rules allow specifying which toolchain to use using command-line flags; consult their documentation. -<p>Normally you should not write those kind of rules unless you want to +Normally you should not write those kind of rules unless you want to tune your Java compiler. -<p>There's no compiler. The proto-compiler is taken from the proto_library rule we attach to. It is +There's no compiler. The proto-compiler is taken from the proto_library rule we attach to. It is passed as a command-line flag to Blaze. Several features require a proto-compiler to be invoked on the proto_library rule itself. It's beneficial to enforce the compiler that LANG_proto_library uses is the same as the one -<code>proto_library</code> does. +`proto_library` does. + +#### Examples -<h4>Examples</h4> +A simple example would be: + +``` lang-starlark -<p>A simple example would be: -<pre><code class="lang-starlark"> proto_lang_toolchain( name = "javalite_toolchain", command_line = "--javalite_out=shared,immutable:$(OUT)", plugin = ":javalite_plugin", runtime = ":protobuf_lite", ) -</code></pre> - - <h3 id="proto_lang_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="proto_lang_toolchain.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.allowlist_different_package"> - <code>allowlist_different_package</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.blacklisted_protos"> - <code>blacklisted_protos</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Deprecated. Alias for <code>denylisted_protos</code>. Will be removed in a future release. - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.command_line"> - <code>command_line</code> - </td> - <td> - <p>String; required</p> - This value will be passed to proto-compiler to generate the code. Only include the parts +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="proto_lang_toolchain.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="proto_lang_toolchain.allowlist_different_package"><code>allowlist_different_package</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> +</tr> +<tr> +<td id="proto_lang_toolchain.blacklisted_protos"><code>blacklisted_protos</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Deprecated. Alias for <code>denylisted_protos</code>. Will be removed in a future release.</td> +</tr> +<tr> +<td id="proto_lang_toolchain.command_line"><code>command_line</code></td> +<td><p>String; required</p> +This value will be passed to proto-compiler to generate the code. Only include the parts specific to this code-generator/plugin (e.g., do not include -I parameters) <ul> - <li><code>$(OUT)</code> is LANG_proto_library-specific. The rules are expected to define - how they interpret this variable. For Java, for example, $(OUT) will be replaced with - the src-jar filename to create.</li> -</ul> - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.denylisted_protos"> - <code>denylisted_protos</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - No code will be generated for files in the <code>srcs</code> attribute of +<li><code>$(OUT)</code> is LANG_proto_library-specific. The rules are expected to define +how they interpret this variable. For Java, for example, $(OUT) will be replaced with +the src-jar filename to create.</li> +</ul></td> +</tr> +<tr> +<td id="proto_lang_toolchain.denylisted_protos"><code>denylisted_protos</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +No code will be generated for files in the <code>srcs</code> attribute of <code>denylisted_protos</code>. This is used for .proto files that are already linked into proto runtimes, such as -<code>any.proto</code>. - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.mnemonic"> - <code>mnemonic</code> - </td> - <td> - <p>String; default is <code>"GenProto"</code></p> - This value will be set as the mnemonic on protoc action. - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.output_files"> - <code>output_files</code> - </td> - <td> - <p>String; default is <code>"legacy"</code></p> - Controls how <code>$(OUT)</code> in <code>command_line</code> is formatted, either by +<code>any.proto</code>.</td> +</tr> +<tr> +<td id="proto_lang_toolchain.mnemonic"><code>mnemonic</code></td> +<td><p>String; default is <code>"GenProto"</code></p> +This value will be set as the mnemonic on protoc action.</td> +</tr> +<tr> +<td id="proto_lang_toolchain.output_files"><code>output_files</code></td> +<td><p>String; default is <code>"legacy"</code></p> +Controls how <code>$(OUT)</code> in <code>command_line</code> is formatted, either by a path to a single file or output directory in case of multiple files. -Possible values are: "single", "multiple". - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.plugin"> - <code>plugin</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - If provided, will be made available to the action that calls the proto-compiler, and will be +Possible values are: "single", "multiple".</td> +</tr> +<tr> +<td id="proto_lang_toolchain.plugin"><code>plugin</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +If provided, will be made available to the action that calls the proto-compiler, and will be passed to the proto-compiler: -<code>--plugin=protoc-gen-PLUGIN=<executable>.</code> - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.plugin_format_flag"> - <code>plugin_format_flag</code> - </td> - <td> - <p>String; default is <code>""</code></p> - If provided, this value will be passed to proto-compiler to use the plugin. +<code>--plugin=protoc-gen-PLUGIN=<executable>.</code></td> +</tr> +<tr> +<td id="proto_lang_toolchain.plugin_format_flag"><code>plugin_format_flag</code></td> +<td><p>String; default is <code>""</code></p> +If provided, this value will be passed to proto-compiler to use the plugin. The value must contain a single %s which is replaced with plugin executable. -<code>--plugin=protoc-gen-PLUGIN=<executable>.</code> - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.progress_message"> - <code>progress_message</code> - </td> - <td> - <p>String; default is <code>"Generating proto_library %{label}"</code></p> - This value will be set as the progress message on protoc action. - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.protoc_minimal_do_not_use"> - <code>protoc_minimal_do_not_use</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.runtime"> - <code>runtime</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - A language-specific library that the generated code is compiled against. +<code>--plugin=protoc-gen-PLUGIN=<executable>.</code></td> +</tr> +<tr> +<td id="proto_lang_toolchain.progress_message"><code>progress_message</code></td> +<td><p>String; default is <code>"Generating proto_library %{label}"</code></p> +This value will be set as the progress message on protoc action.</td> +</tr> +<tr> +<td id="proto_lang_toolchain.protoc_minimal_do_not_use"><code>protoc_minimal_do_not_use</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> +</tr> +<tr> +<td id="proto_lang_toolchain.runtime"><code>runtime</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +A language-specific library that the generated code is compiled against. The exact behavior is LANG_proto_library-specific. -Java, for example, should compile against the runtime. - </td> - </tr> - <tr> - <td id="proto_lang_toolchain.toolchain_type"> - <code>toolchain_type</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - - </td> - </tr> - </tbody> - </table> - <h2 id="proto_toolchain"> - proto_toolchain - </h2> - - <a class="button button-with-icon" href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_toolchain_rule.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">proto_toolchain(<a href="#proto_toolchain.name">name</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#proto_toolchain.command_line">command_line</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#proto_toolchain.mnemonic">mnemonic</a>, <a href="#proto_toolchain.output_files">output_files</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#proto_toolchain.progress_message">progress_message</a>, <a href="#proto_toolchain.proto_compiler">proto_compiler</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - - - <h3 id="proto_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="proto_toolchain.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="proto_toolchain.command_line"> - <code>command_line</code> - </td> - <td> - <p>String; default is <code>"--descriptor_set_out=%s"</code></p> - - </td> - </tr> - <tr> - <td id="proto_toolchain.mnemonic"> - <code>mnemonic</code> - </td> - <td> - <p>String; default is <code>"GenProtoDescriptorSet"</code></p> - - </td> - </tr> - <tr> - <td id="proto_toolchain.output_files"> - <code>output_files</code> - </td> - <td> - <p>String; default is <code>"single"</code></p> - - </td> - </tr> - <tr> - <td id="proto_toolchain.progress_message"> - <code>progress_message</code> - </td> - <td> - <p>String; default is <code>"Generating Descriptor Set proto_library %{label}"</code></p> - - </td> - </tr> - <tr> - <td id="proto_toolchain.proto_compiler"> - <code>proto_compiler</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +Java, for example, should compile against the runtime.</td> +</tr> +<tr> +<td id="proto_lang_toolchain.toolchain_type"><code>toolchain_type</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> +</tr> +</tbody> +</table> + +## proto_toolchain + +<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_toolchain_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +proto_toolchain(name, aspect_hints, command_line, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, mnemonic, output_files, package_metadata, progress_message, proto_compiler, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="proto_toolchain.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="proto_toolchain.command_line"><code>command_line</code></td> +<td><p>String; default is <code>"--descriptor_set_out=%s"</code></p></td> +</tr> +<tr> +<td id="proto_toolchain.mnemonic"><code>mnemonic</code></td> +<td><p>String; default is <code>"GenProtoDescriptorSet"</code></p></td> +</tr> +<tr> +<td id="proto_toolchain.output_files"><code>output_files</code></td> +<td><p>String; default is <code>"single"</code></p></td> +</tr> +<tr> +<td id="proto_toolchain.progress_message"><code>progress_message</code></td> +<td><p>String; default is <code>"Generating Descriptor Set proto_library %{label}"</code></p></td> +</tr> +<tr> +<td id="proto_toolchain.proto_compiler"><code>proto_compiler</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> +</tr> +</tbody> +</table> diff --git a/reference/be/python.mdx b/reference/be/python.mdx index 08c4174..44fd237 100644 --- a/reference/be/python.mdx +++ b/reference/be/python.mdx @@ -2,543 +2,349 @@ title: 'python' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">Python Rules</h1> +# Python Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} - - - - -<h2>Rules</h2> -<ul> - <li> - <a href="#py_binary"> - py_binary </a> - </li> - <li> - <a href="#py_library"> - py_library </a> - </li> - <li> - <a href="#py_test"> - py_test </a> - </li> - <li> - <a href="#py_runtime"> - py_runtime </a> - </li> -</ul> +{% include "\_buttons.html" %} - <h2 id="py_binary"> - py_binary - </h2> +## Rules - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_binary_rule.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +- [py_binary](#py_binary) +- [py_library](#py_library) +- [py_test](#py_test) +- [py_runtime](#py_runtime) - <pre class="rule-signature">py_binary(<a href="#py_binary.name">name</a>, <a href="#py_binary.deps">deps</a>, <a href="#py_binary.srcs">srcs</a>, <a href="#py_binary.data">data</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#py_binary.distribs">distribs</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#py_binary.imports">imports</a>, <a href="#py_binary.interpreter_args">interpreter_args</a>, <a href="#py_binary.legacy_create_init">legacy_create_init</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#py_binary.main">main</a>, <a href="#py_binary.main_module">main_module</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#py_binary.precompile">precompile</a>, <a href="#py_binary.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_binary.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_binary.precompile_source_retention">precompile_source_retention</a>, <a href="#py_binary.pyc_collection">pyc_collection</a>, <a href="#py_binary.pyi_deps">pyi_deps</a>, <a href="#py_binary.pyi_srcs">pyi_srcs</a>, <a href="#py_binary.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_binary.srcs_version">srcs_version</a>, <a href="#py_binary.stamp">stamp</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +## py_binary +<a href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_binary_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +``` rule-signature +py_binary(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, distribs, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, imports, interpreter_args, legacy_create_init, licenses, main, main_module, output_licenses, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, pyi_deps, pyi_srcs, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility) +``` - <h3 id="py_binary_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="py_binary.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="py_binary.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - List of additional libraries to be linked in to the target. +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="py_binary.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="py_binary.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py_library` rules. - Targets that only provide data files used at runtime belong in the `data` attribute. - :::{note} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. - * {obj}`PyInfo.site_packages_symlinks` uses topological ordering. - See {obj}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. -::: - </td> - </tr> - <tr> - <td id="py_binary.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of Python source files that are processed to create the target. This -includes all your checked-in code and may include generated source files. The +:::</td> +</tr> +<tr> +<td id="py_binary.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary -files that may be needed at run time belong in `data`. - </td> - </tr> - <tr> - <td id="py_binary.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files need by this library at runtime. See comments about +files that may be needed at run time belong in `data`.</td> +</tr> +<tr> +<td id="py_binary.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). - There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. -This is because Python has a concept of runtime resources. - </td> - </tr> - <tr> - <td id="py_binary.distribs"> - <code>distribs</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="py_binary.imports"> - <code>imports</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of import directories to be added to the PYTHONPATH. - +This is because Python has a concept of runtime resources.</td> +</tr> +<tr> +<td id="py_binary.distribs"><code>distribs</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="py_binary.imports"><code>imports</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, - Absolute paths (paths that start with `/`) and paths that references a path -above the execution root are not allowed and will result in an error. - </td> - </tr> - <tr> - <td id="py_binary.interpreter_args"> - <code>interpreter_args</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Arguments that are only applicable to the interpreter. - +above the execution root are not allowed and will result in an error.</td> +</tr> +<tr> +<td id="py_binary.interpreter_args"><code>interpreter_args</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Arguments that are only applicable to the interpreter. The args an interpreter supports are specific to the interpreter. For CPython, see https://docs.python.org/3/using/cmdline.html. - :::{note} Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise. ::: - :::{seealso} The {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable ::: - :::{versionadded} 1.3.0 -::: - </td> - </tr> - <tr> - <td id="py_binary.legacy_create_init"> - <code>legacy_create_init</code> - </td> - <td> - <p>Integer; default is <code>-1</code></p> - Whether to implicitly create empty `__init__.py` files in the runfiles tree. +:::</td> +</tr> +<tr> +<td id="py_binary.legacy_create_init"><code>legacy_create_init</code></td> +<td><p>Integer; default is <code>-1</code></p> +Whether to implicitly create empty `__init__.py` files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default, `-1` (auto), means true unless `--incompatible_default_to_explicit_init_py` is used. If false, the user is responsible for creating (possibly empty) `__init__.py` files and adding them to -the `srcs` of Python targets as required. - </td> - </tr> - <tr> - <td id="py_binary.main"> - <code>main</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Optional; the name of the source file that is the main entry point of the +the `srcs` of Python targets as required.</td> +</tr> +<tr> +<td id="py_binary.main"><code>main</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Optional; the name of the source file that is the main entry point of the application. This file must also be listed in `srcs`. If left unspecified, `name`, with `.py` appended, is used instead. If `name` does not match any filename in `srcs`, `main` must be specified. - -This is mutually exclusive with {obj}`main_module`. - </td> - </tr> - <tr> - <td id="py_binary.main_module"> - <code>main_module</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Module name to execute as the main program. - +This is mutually exclusive with {obj}`main_module`.</td> +</tr> +<tr> +<td id="py_binary.main_module"><code>main_module</code></td> +<td><p>String; default is <code>""</code></p> +Module name to execute as the main program. When set, `srcs` is not required, and it is assumed the module is provided by a dependency. - See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more information about running modules as the main program. - This is mutually exclusive with {obj}`main`. - :::{versionadded} 1.3.0 -::: - </td> - </tr> - <tr> - <td id="py_binary.precompile"> - <code>precompile</code> - </td> - <td> - <p>String; default is <code>"inherit"</code></p> - Whether py source files **for this target** should be precompiled. - +:::</td> +</tr> +<tr> +<td id="py_binary.precompile"><code>precompile</code></td> +<td><p>String; default is <code>"inherit"</code></p> +Whether py source files **for this target** should be precompiled. Values: - * `inherit`: Allow the downstream binary decide if precompiled files are used. * `enabled`: Compile Python source files at build time. * `disabled`: Don't compile Python source files at build time. - :::{seealso} - * The {flag}`--precompile` flag, which can override this attribute in some cases - and will affect all targets when building. +and will affect all targets when building. * The {obj}`pyc_collection` attribute for transitively enabling precompiling on - a per-target basis. +a per-target basis. * The [Precompiling](precompiling) docs for a guide about using precompiling. -::: - </td> - </tr> - <tr> - <td id="py_binary.precompile_invalidation_mode"> - <code>precompile_invalidation_mode</code> - </td> - <td> - <p>String; default is <code>"auto"</code></p> - How precompiled files should be verified to be up-to-date with their associated +:::</td> +</tr> +<tr> +<td id="py_binary.precompile_invalidation_mode"><code>precompile_invalidation_mode</code></td> +<td><p>String; default is <code>"auto"</code></p> +How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: * `auto`: The effective value will be automatically determined by other build - settings. +settings. * `checked_hash`: Use the pyc file if the hash of the source file matches the hash - recorded in the pyc file. This is most useful when working with code that - you may modify. +recorded in the pyc file. This is most useful when working with code that +you may modify. * `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against - the source file. This is most useful when the code won't be modified. - +the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see -https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode - </td> - </tr> - <tr> - <td id="py_binary.precompile_optimize_level"> - <code>precompile_optimize_level</code> - </td> - <td> - <p>Integer; default is <code>0</code></p> - The optimization level for precompiled files. - +https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode</td> +</tr> +<tr> +<td id="py_binary.precompile_optimize_level"><code>precompile_optimize_level</code></td> +<td><p>Integer; default is <code>0</code></p> +The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile - NOTE: The value `-1` means "current interpreter", which will be the interpreter used _at build time when pycs are generated_, not the interpreter used at -runtime when the code actually runs. - </td> - </tr> - <tr> - <td id="py_binary.precompile_source_retention"> - <code>precompile_source_retention</code> - </td> - <td> - <p>String; default is <code>"inherit"</code></p> - Determines, when a source file is compiled, if the source file is kept +runtime when the code actually runs.</td> +</tr> +<tr> +<td id="py_binary.precompile_source_retention"><code>precompile_source_retention</code></td> +<td><p>String; default is <code>"inherit"</code></p> +Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: - * `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. * `keep_source`: Include the original Python source. -* `omit_source`: Don't include the original py source. - </td> - </tr> - <tr> - <td id="py_binary.pyc_collection"> - <code>pyc_collection</code> - </td> - <td> - <p>String; default is <code>"inherit"</code></p> - Determines whether pyc files from dependencies should be manually included. - +* `omit_source`: Don't include the original py source.</td> +</tr> +<tr> +<td id="py_binary.pyc_collection"><code>pyc_collection</code></td> +<td><p>String; default is <code>"inherit"</code></p> +Determines whether pyc files from dependencies should be manually included. Valid values are: * `inherit`: Inherit the value from {flag}`--precompile`. * `include_pyc`: Add implicitly generated pyc files from dependencies. i.e. - pyc files for targets that specify {attr}`precompile="inherit"`. +pyc files for targets that specify {attr}`precompile="inherit"`. * `disabled`: Don't add implicitly generated pyc files. Note that - pyc files may still come from dependencies that enable precompiling at the - target level. - </td> - </tr> - <tr> - <td id="py_binary.pyi_deps"> - <code>pyi_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Dependencies providing type definitions the library needs. - +pyc files may still come from dependencies that enable precompiling at the +target level.</td> +</tr> +<tr> +<td id="py_binary.pyi_deps"><code>pyi_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). - :::{versionadded} 1.1.0 -::: - </td> - </tr> - <tr> - <td id="py_binary.pyi_srcs"> - <code>pyi_srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Type definition files for the library. - +:::</td> +</tr> +<tr> +<td id="py_binary.pyi_srcs"><code>pyi_srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). - :::{versionadded} 1.1.0 -::: - </td> - </tr> - <tr> - <td id="py_binary.python_version"> - <code>python_version</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The Python version this target should use. - +:::</td> +</tr> +<tr> +<td id="py_binary.python_version"><code>python_version</code></td> +<td><p>String; default is <code>""</code></p> +The Python version this target should use. The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or unspecified, the incoming configuration's {obj}`--python_version` flag is inherited. For backwards compatibility, the values `PY2` and `PY3` are accepted, but treated as an empty/unspecified value. - :::{note} In order for the requested version to be used, there must be a toolchain configured to match the Python version. If there isn't, then it may be silently ignored, or an error may occur, depending on the toolchain configuration. ::: - :::{versionchanged} 1.1.0 - This attribute was changed from only accepting `PY2` and `PY3` values to accepting arbitrary Python versions. -::: - </td> - </tr> - <tr> - <td id="py_binary.srcs_version"> - <code>srcs_version</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Defunct, unused, does nothing. - </td> - </tr> - <tr> - <td id="py_binary.stamp"> - <code>stamp</code> - </td> - <td> - <p>Integer; default is <code>-1</code></p> - Whether to encode build information into the binary. Possible values: - +:::</td> +</tr> +<tr> +<td id="py_binary.srcs_version"><code>srcs_version</code></td> +<td><p>String; default is <code>""</code></p> +Defunct, unused, does nothing.</td> +</tr> +<tr> +<td id="py_binary.stamp"><code>stamp</code></td> +<td><p>Integer; default is <code>-1</code></p> +Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in - `--nostamp` builds. **This setting should be avoided**, since it potentially kills - remote caching for the binary and any downstream actions that depend on it. +`--nostamp` builds. **This setting should be avoided**, since it potentially kills +remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives - good build result caching. +good build result caching. * `stamp = -1`: Embedding of build information is controlled by the - `--[no]stamp` flag. - +`--[no]stamp` flag. Stamped binaries are not rebuilt unless their dependencies change. - WARNING: Stamping can harm build performance by reducing cache hits and should -be avoided if possible. - </td> - </tr> - </tbody> - </table> - <h2 id="py_library"> - py_library - </h2> +be avoided if possible.</td> +</tr> +</tbody> +</table> - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_library_rule.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +## py_library - <pre class="rule-signature">py_library(<a href="#py_library.name">name</a>, <a href="#py_library.deps">deps</a>, <a href="#py_library.srcs">srcs</a>, <a href="#py_library.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#py_library.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#py_library.experimental_venvs_site_packages">experimental_venvs_site_packages</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#py_library.imports">imports</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#py_library.precompile">precompile</a>, <a href="#py_library.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_library.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_library.precompile_source_retention">precompile_source_retention</a>, <a href="#py_library.pyi_deps">pyi_deps</a>, <a href="#py_library.pyi_srcs">pyi_srcs</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_library.srcs_version">srcs_version</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> +<a href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_library_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - A library of Python code that can be depended upon. +``` rule-signature +py_library(name, deps, srcs, data, aspect_hints, compatible_with, deprecation, distribs, exec_compatible_with, exec_group_compatible_with, exec_properties, experimental_venvs_site_packages, features, imports, licenses, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyi_deps, pyi_srcs, restricted_to, srcs_version, tags, target_compatible_with, testonly, toolchains, visibility) +``` +A library of Python code that can be depended upon. Default outputs: -* The input Python sources -* The precompiled artifacts from the sources. - +\* The input Python sources +\* The precompiled artifacts from the sources. NOTE: Precompilation affects which of the default outputs are included in the resulting runfiles. See the precompile-related attributes and flags for more information. - :::{versionchanged} 0.37.0 Source files are no longer added to the runfiles directly. ::: - <h3 id="py_library_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="py_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="py_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - List of additional libraries to be linked in to the target. +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="py_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="py_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py_library` rules. - Targets that only provide data files used at runtime belong in the `data` attribute. - :::{note} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. - * {obj}`PyInfo.site_packages_symlinks` uses topological ordering. - See {obj}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. -::: - </td> - </tr> - <tr> - <td id="py_library.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of Python source files that are processed to create the target. This -includes all your checked-in code and may include generated source files. The +:::</td> +</tr> +<tr> +<td id="py_library.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary -files that may be needed at run time belong in `data`. - </td> - </tr> - <tr> - <td id="py_library.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files need by this library at runtime. See comments about +files that may be needed at run time belong in `data`.</td> +</tr> +<tr> +<td id="py_library.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). - There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. -This is because Python has a concept of runtime resources. - </td> - </tr> - <tr> - <td id="py_library.distribs"> - <code>distribs</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="py_library.experimental_venvs_site_packages"> - <code>experimental_venvs_site_packages</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - **INTERNAL ATTRIBUTE. SHOULD ONLY BE SET BY rules_python-INTERNAL CODE.** - +This is because Python has a concept of runtime resources.</td> +</tr> +<tr> +<td id="py_library.distribs"><code>distribs</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="py_library.experimental_venvs_site_packages"><code>experimental_venvs_site_packages</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +**INTERNAL ATTRIBUTE. SHOULD ONLY BE SET BY rules_python-INTERNAL CODE.** :::{include} /_includes/experimental_api.md ::: - A flag that decides whether the library should treat its sources as a site-packages layout. - When the flag is `yes`, then the `srcs` files are treated as a site-packages layout that is relative to the `imports` attribute. The `imports` attribute can have only a single element. It is a repo-relative runfiles path. - For example, in the `my/pkg/BUILD.bazel` file, given `srcs=["site-packages/foo/bar.py"]`, specifying `imports=["my/pkg/site-packages"]` means `foo/bar.py` is the file path under the binary's venv site-packages directory that should be made available (i.e. `import foo.bar` will work). - `__init__.py` files are treated specially to provide basic support for [implicit namespace packages]( https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages). @@ -547,798 +353,533 @@ presence or absense. Stated another way: [pkgutil-style namespace packages]( https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages) won't be understood as namespace packages; they'll be seen as regular packages. This will likely lead to conflicts with other targets that contribute to the namespace. - :::{tip} This attributes populates {obj}`PyInfo.site_packages_symlinks`, which is a topologically ordered depset. This means dependencies closer and earlier to a consumer have precedence. See {obj}`PyInfo.site_packages_symlinks` for more information. ::: - :::{versionadded} 1.4.0 -::: - </td> - </tr> - <tr> - <td id="py_library.imports"> - <code>imports</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of import directories to be added to the PYTHONPATH. - +:::</td> +</tr> +<tr> +<td id="py_library.imports"><code>imports</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, - Absolute paths (paths that start with `/`) and paths that references a path -above the execution root are not allowed and will result in an error. - </td> - </tr> - <tr> - <td id="py_library.precompile"> - <code>precompile</code> - </td> - <td> - <p>String; default is <code>"inherit"</code></p> - Whether py source files **for this target** should be precompiled. - +above the execution root are not allowed and will result in an error.</td> +</tr> +<tr> +<td id="py_library.precompile"><code>precompile</code></td> +<td><p>String; default is <code>"inherit"</code></p> +Whether py source files **for this target** should be precompiled. Values: - * `inherit`: Allow the downstream binary decide if precompiled files are used. * `enabled`: Compile Python source files at build time. * `disabled`: Don't compile Python source files at build time. - :::{seealso} - * The {flag}`--precompile` flag, which can override this attribute in some cases - and will affect all targets when building. +and will affect all targets when building. * The {obj}`pyc_collection` attribute for transitively enabling precompiling on - a per-target basis. +a per-target basis. * The [Precompiling](precompiling) docs for a guide about using precompiling. -::: - </td> - </tr> - <tr> - <td id="py_library.precompile_invalidation_mode"> - <code>precompile_invalidation_mode</code> - </td> - <td> - <p>String; default is <code>"auto"</code></p> - How precompiled files should be verified to be up-to-date with their associated +:::</td> +</tr> +<tr> +<td id="py_library.precompile_invalidation_mode"><code>precompile_invalidation_mode</code></td> +<td><p>String; default is <code>"auto"</code></p> +How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: * `auto`: The effective value will be automatically determined by other build - settings. +settings. * `checked_hash`: Use the pyc file if the hash of the source file matches the hash - recorded in the pyc file. This is most useful when working with code that - you may modify. +recorded in the pyc file. This is most useful when working with code that +you may modify. * `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against - the source file. This is most useful when the code won't be modified. - +the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see -https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode - </td> - </tr> - <tr> - <td id="py_library.precompile_optimize_level"> - <code>precompile_optimize_level</code> - </td> - <td> - <p>Integer; default is <code>0</code></p> - The optimization level for precompiled files. - +https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode</td> +</tr> +<tr> +<td id="py_library.precompile_optimize_level"><code>precompile_optimize_level</code></td> +<td><p>Integer; default is <code>0</code></p> +The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile - NOTE: The value `-1` means "current interpreter", which will be the interpreter used _at build time when pycs are generated_, not the interpreter used at -runtime when the code actually runs. - </td> - </tr> - <tr> - <td id="py_library.precompile_source_retention"> - <code>precompile_source_retention</code> - </td> - <td> - <p>String; default is <code>"inherit"</code></p> - Determines, when a source file is compiled, if the source file is kept +runtime when the code actually runs.</td> +</tr> +<tr> +<td id="py_library.precompile_source_retention"><code>precompile_source_retention</code></td> +<td><p>String; default is <code>"inherit"</code></p> +Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: - * `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. * `keep_source`: Include the original Python source. -* `omit_source`: Don't include the original py source. - </td> - </tr> - <tr> - <td id="py_library.pyi_deps"> - <code>pyi_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Dependencies providing type definitions the library needs. - +* `omit_source`: Don't include the original py source.</td> +</tr> +<tr> +<td id="py_library.pyi_deps"><code>pyi_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). - :::{versionadded} 1.1.0 -::: - </td> - </tr> - <tr> - <td id="py_library.pyi_srcs"> - <code>pyi_srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Type definition files for the library. - +:::</td> +</tr> +<tr> +<td id="py_library.pyi_srcs"><code>pyi_srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). - :::{versionadded} 1.1.0 -::: - </td> - </tr> - <tr> - <td id="py_library.srcs_version"> - <code>srcs_version</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Defunct, unused, does nothing. - </td> - </tr> - </tbody> - </table> - <h2 id="py_test"> - py_test - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_test_rule.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">py_test(<a href="#py_test.name">name</a>, <a href="#py_test.deps">deps</a>, <a href="#py_test.srcs">srcs</a>, <a href="#py_test.data">data</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#py_test.distribs">distribs</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#test.flaky">flaky</a>, <a href="#py_test.imports">imports</a>, <a href="#py_test.interpreter_args">interpreter_args</a>, <a href="#py_test.legacy_create_init">legacy_create_init</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#py_test.main">main</a>, <a href="#py_test.main_module">main_module</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#py_test.precompile">precompile</a>, <a href="#py_test.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_test.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_test.precompile_source_retention">precompile_source_retention</a>, <a href="#py_test.pyc_collection">pyc_collection</a>, <a href="#py_test.pyi_deps">pyi_deps</a>, <a href="#py_test.pyi_srcs">pyi_srcs</a>, <a href="#py_test.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#py_test.srcs_version">srcs_version</a>, <a href="#py_test.stamp">stamp</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#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - - - <h3 id="py_test_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="py_test.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> +:::</td> +</tr> +<tr> +<td id="py_library.srcs_version"><code>srcs_version</code></td> +<td><p>String; default is <code>""</code></p> +Defunct, unused, does nothing.</td> +</tr> +</tbody> +</table> + +## py_test + +<a href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_test_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +py_test(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, imports, interpreter_args, legacy_create_init, licenses, local, main, main_module, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, pyi_deps, pyi_srcs, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility) +``` - </td> - </tr> - <tr> - <td id="py_test.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - List of additional libraries to be linked in to the target. +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="py_test.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="py_test.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py_library` rules. - Targets that only provide data files used at runtime belong in the `data` attribute. - :::{note} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. - * {obj}`PyInfo.site_packages_symlinks` uses topological ordering. - See {obj}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. -::: - </td> - </tr> - <tr> - <td id="py_test.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of Python source files that are processed to create the target. This -includes all your checked-in code and may include generated source files. The +:::</td> +</tr> +<tr> +<td id="py_test.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary -files that may be needed at run time belong in `data`. - </td> - </tr> - <tr> - <td id="py_test.data"> - <code>data</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of files need by this library at runtime. See comments about +files that may be needed at run time belong in `data`.</td> +</tr> +<tr> +<td id="py_test.data"><code>data</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). - There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. -This is because Python has a concept of runtime resources. - </td> - </tr> - <tr> - <td id="py_test.distribs"> - <code>distribs</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="py_test.imports"> - <code>imports</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - List of import directories to be added to the PYTHONPATH. - +This is because Python has a concept of runtime resources.</td> +</tr> +<tr> +<td id="py_test.distribs"><code>distribs</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="py_test.imports"><code>imports</code></td> +<td><p>List of strings; default is <code>[]</code></p> +List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, - Absolute paths (paths that start with `/`) and paths that references a path -above the execution root are not allowed and will result in an error. - </td> - </tr> - <tr> - <td id="py_test.interpreter_args"> - <code>interpreter_args</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - Arguments that are only applicable to the interpreter. - +above the execution root are not allowed and will result in an error.</td> +</tr> +<tr> +<td id="py_test.interpreter_args"><code>interpreter_args</code></td> +<td><p>List of strings; default is <code>[]</code></p> +Arguments that are only applicable to the interpreter. The args an interpreter supports are specific to the interpreter. For CPython, see https://docs.python.org/3/using/cmdline.html. - :::{note} Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise. ::: - :::{seealso} The {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable ::: - :::{versionadded} 1.3.0 -::: - </td> - </tr> - <tr> - <td id="py_test.legacy_create_init"> - <code>legacy_create_init</code> - </td> - <td> - <p>Integer; default is <code>-1</code></p> - Whether to implicitly create empty `__init__.py` files in the runfiles tree. +:::</td> +</tr> +<tr> +<td id="py_test.legacy_create_init"><code>legacy_create_init</code></td> +<td><p>Integer; default is <code>-1</code></p> +Whether to implicitly create empty `__init__.py` files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default, `-1` (auto), means true unless `--incompatible_default_to_explicit_init_py` is used. If false, the user is responsible for creating (possibly empty) `__init__.py` files and adding them to -the `srcs` of Python targets as required. - </td> - </tr> - <tr> - <td id="py_test.main"> - <code>main</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - Optional; the name of the source file that is the main entry point of the +the `srcs` of Python targets as required.</td> +</tr> +<tr> +<td id="py_test.main"><code>main</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +Optional; the name of the source file that is the main entry point of the application. This file must also be listed in `srcs`. If left unspecified, `name`, with `.py` appended, is used instead. If `name` does not match any filename in `srcs`, `main` must be specified. - -This is mutually exclusive with {obj}`main_module`. - </td> - </tr> - <tr> - <td id="py_test.main_module"> - <code>main_module</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Module name to execute as the main program. - +This is mutually exclusive with {obj}`main_module`.</td> +</tr> +<tr> +<td id="py_test.main_module"><code>main_module</code></td> +<td><p>String; default is <code>""</code></p> +Module name to execute as the main program. When set, `srcs` is not required, and it is assumed the module is provided by a dependency. - See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more information about running modules as the main program. - This is mutually exclusive with {obj}`main`. - :::{versionadded} 1.3.0 -::: - </td> - </tr> - <tr> - <td id="py_test.precompile"> - <code>precompile</code> - </td> - <td> - <p>String; default is <code>"inherit"</code></p> - Whether py source files **for this target** should be precompiled. - +:::</td> +</tr> +<tr> +<td id="py_test.precompile"><code>precompile</code></td> +<td><p>String; default is <code>"inherit"</code></p> +Whether py source files **for this target** should be precompiled. Values: - * `inherit`: Allow the downstream binary decide if precompiled files are used. * `enabled`: Compile Python source files at build time. * `disabled`: Don't compile Python source files at build time. - :::{seealso} - * The {flag}`--precompile` flag, which can override this attribute in some cases - and will affect all targets when building. +and will affect all targets when building. * The {obj}`pyc_collection` attribute for transitively enabling precompiling on - a per-target basis. +a per-target basis. * The [Precompiling](precompiling) docs for a guide about using precompiling. -::: - </td> - </tr> - <tr> - <td id="py_test.precompile_invalidation_mode"> - <code>precompile_invalidation_mode</code> - </td> - <td> - <p>String; default is <code>"auto"</code></p> - How precompiled files should be verified to be up-to-date with their associated +:::</td> +</tr> +<tr> +<td id="py_test.precompile_invalidation_mode"><code>precompile_invalidation_mode</code></td> +<td><p>String; default is <code>"auto"</code></p> +How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: * `auto`: The effective value will be automatically determined by other build - settings. +settings. * `checked_hash`: Use the pyc file if the hash of the source file matches the hash - recorded in the pyc file. This is most useful when working with code that - you may modify. +recorded in the pyc file. This is most useful when working with code that +you may modify. * `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against - the source file. This is most useful when the code won't be modified. - +the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see -https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode - </td> - </tr> - <tr> - <td id="py_test.precompile_optimize_level"> - <code>precompile_optimize_level</code> - </td> - <td> - <p>Integer; default is <code>0</code></p> - The optimization level for precompiled files. - +https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode</td> +</tr> +<tr> +<td id="py_test.precompile_optimize_level"><code>precompile_optimize_level</code></td> +<td><p>Integer; default is <code>0</code></p> +The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile - NOTE: The value `-1` means "current interpreter", which will be the interpreter used _at build time when pycs are generated_, not the interpreter used at -runtime when the code actually runs. - </td> - </tr> - <tr> - <td id="py_test.precompile_source_retention"> - <code>precompile_source_retention</code> - </td> - <td> - <p>String; default is <code>"inherit"</code></p> - Determines, when a source file is compiled, if the source file is kept +runtime when the code actually runs.</td> +</tr> +<tr> +<td id="py_test.precompile_source_retention"><code>precompile_source_retention</code></td> +<td><p>String; default is <code>"inherit"</code></p> +Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: - * `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. * `keep_source`: Include the original Python source. -* `omit_source`: Don't include the original py source. - </td> - </tr> - <tr> - <td id="py_test.pyc_collection"> - <code>pyc_collection</code> - </td> - <td> - <p>String; default is <code>"inherit"</code></p> - Determines whether pyc files from dependencies should be manually included. - +* `omit_source`: Don't include the original py source.</td> +</tr> +<tr> +<td id="py_test.pyc_collection"><code>pyc_collection</code></td> +<td><p>String; default is <code>"inherit"</code></p> +Determines whether pyc files from dependencies should be manually included. Valid values are: * `inherit`: Inherit the value from {flag}`--precompile`. * `include_pyc`: Add implicitly generated pyc files from dependencies. i.e. - pyc files for targets that specify {attr}`precompile="inherit"`. +pyc files for targets that specify {attr}`precompile="inherit"`. * `disabled`: Don't add implicitly generated pyc files. Note that - pyc files may still come from dependencies that enable precompiling at the - target level. - </td> - </tr> - <tr> - <td id="py_test.pyi_deps"> - <code>pyi_deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Dependencies providing type definitions the library needs. - +pyc files may still come from dependencies that enable precompiling at the +target level.</td> +</tr> +<tr> +<td id="py_test.pyi_deps"><code>pyi_deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). - :::{versionadded} 1.1.0 -::: - </td> - </tr> - <tr> - <td id="py_test.pyi_srcs"> - <code>pyi_srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - Type definition files for the library. - +:::</td> +</tr> +<tr> +<td id="py_test.pyi_srcs"><code>pyi_srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). - :::{versionadded} 1.1.0 -::: - </td> - </tr> - <tr> - <td id="py_test.python_version"> - <code>python_version</code> - </td> - <td> - <p>String; default is <code>""</code></p> - The Python version this target should use. - +:::</td> +</tr> +<tr> +<td id="py_test.python_version"><code>python_version</code></td> +<td><p>String; default is <code>""</code></p> +The Python version this target should use. The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or unspecified, the incoming configuration's {obj}`--python_version` flag is inherited. For backwards compatibility, the values `PY2` and `PY3` are accepted, but treated as an empty/unspecified value. - :::{note} In order for the requested version to be used, there must be a toolchain configured to match the Python version. If there isn't, then it may be silently ignored, or an error may occur, depending on the toolchain configuration. ::: - :::{versionchanged} 1.1.0 - This attribute was changed from only accepting `PY2` and `PY3` values to accepting arbitrary Python versions. -::: - </td> - </tr> - <tr> - <td id="py_test.srcs_version"> - <code>srcs_version</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Defunct, unused, does nothing. - </td> - </tr> - <tr> - <td id="py_test.stamp"> - <code>stamp</code> - </td> - <td> - <p>Integer; default is <code>0</code></p> - Whether to encode build information into the binary. Possible values: - +:::</td> +</tr> +<tr> +<td id="py_test.srcs_version"><code>srcs_version</code></td> +<td><p>String; default is <code>""</code></p> +Defunct, unused, does nothing.</td> +</tr> +<tr> +<td id="py_test.stamp"><code>stamp</code></td> +<td><p>Integer; default is <code>0</code></p> +Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in - `--nostamp` builds. **This setting should be avoided**, since it potentially kills - remote caching for the binary and any downstream actions that depend on it. +`--nostamp` builds. **This setting should be avoided**, since it potentially kills +remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives - good build result caching. +good build result caching. * `stamp = -1`: Embedding of build information is controlled by the - `--[no]stamp` flag. - +`--[no]stamp` flag. Stamped binaries are not rebuilt unless their dependencies change. - WARNING: Stamping can harm build performance by reducing cache hits and should -be avoided if possible. - </td> - </tr> - </tbody> - </table> - <h2 id="py_runtime"> - py_runtime - </h2> +be avoided if possible.</td> +</tr> +</tbody> +</table> - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_runtime_rule.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> +## py_runtime - <pre class="rule-signature">py_runtime(<a href="#py_runtime.name">name</a>, <a href="#py_runtime.abi_flags">abi_flags</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</a>, <a href="#py_runtime.bootstrap_template">bootstrap_template</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#py_runtime.coverage_tool">coverage_tool</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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="#py_runtime.files">files</a>, <a href="#py_runtime.implementation_name">implementation_name</a>, <a href="#py_runtime.interpreter">interpreter</a>, <a href="#py_runtime.interpreter_path">interpreter_path</a>, <a href="#py_runtime.interpreter_version_info">interpreter_version_info</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="#py_runtime.pyc_tag">pyc_tag</a>, <a href="#py_runtime.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_runtime.site_init_template">site_init_template</a>, <a href="#py_runtime.stage2_bootstrap_template">stage2_bootstrap_template</a>, <a href="#py_runtime.stub_shebang">stub_shebang</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#py_runtime.zip_main_template">zip_main_template</a>)</pre> +<a href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_runtime_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - Represents a Python runtime used to execute Python code. +``` rule-signature +py_runtime(name, abi_flags, aspect_hints, bootstrap_template, compatible_with, coverage_tool, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, files, implementation_name, interpreter, interpreter_path, interpreter_version_info, package_metadata, pyc_tag, python_version, restricted_to, site_init_template, stage2_bootstrap_template, stub_shebang, tags, target_compatible_with, testonly, toolchains, visibility, zip_main_template) +``` -A `py_runtime` target can represent either a *platform runtime* or an *in-build -runtime*. A platform runtime accesses a system-installed interpreter at a known +Represents a Python runtime used to execute Python code. +A \`py_runtime\` target can represent either a \*platform runtime\* or an \*in-build +runtime\*. A platform runtime accesses a system-installed interpreter at a known path, whereas an in-build runtime points to an executable target that acts as the interpreter. In both cases, an "interpreter" means any executable binary or wrapper script that is capable of running a Python script passed on the command line, following the same conventions as the standard CPython interpreter. - A platform runtime is by its nature non-hermetic. It imposes a requirement on the target platform to have an interpreter located at a specific path. An in-build runtime may or may not be hermetic, depending on whether it points to a checked-in interpreter or a wrapper script that accesses the system interpreter. - Example - -``` +\`\`\` load("@rules_python//python:py_runtime.bzl", "py_runtime") - py_runtime( - name = "python-2.7.12", - files = glob(["python-2.7.12/**"]), - interpreter = "python-2.7.12/bin/python", +name = "python-2.7.12", +files = glob(\["python-2.7.12/\*\*"\]), +interpreter = "python-2.7.12/bin/python", ) - py_runtime( - name = "python-3.6.0", - interpreter_path = "/opt/pyenv/versions/3.6.0/bin/python", +name = "python-3.6.0", +interpreter_path = "/opt/pyenv/versions/3.6.0/bin/python", ) -``` - - <h3 id="py_runtime_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="py_runtime.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="py_runtime.abi_flags"> - <code>abi_flags</code> - </td> - <td> - <p>String; default is <code>"<AUTO>"</code></p> - The runtime's ABI flags, i.e. `sys.abiflags`. - -If not set, then it will be set based on flags. - </td> - </tr> - <tr> - <td id="py_runtime.bootstrap_template"> - <code>bootstrap_template</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:bootstrap_template"</code></p> - The bootstrap script template file to use. Should have %python_binary%, +\`\`\` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="py_runtime.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="py_runtime.abi_flags"><code>abi_flags</code></td> +<td><p>String; default is <code>""</code></p> +The runtime's ABI flags, i.e. `sys.abiflags`. +If not set, then it will be set based on flags.</td> +</tr> +<tr> +<td id="py_runtime.bootstrap_template"><code>bootstrap_template</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:bootstrap_template"</code></p> +The bootstrap script template file to use. Should have %python_binary%, %workspace_name%, %main%, and %imports%. - This template, after expansion, becomes the executable file used to start the process, so it is responsible for initial bootstrapping actions such as finding the Python interpreter, runfiles, and constructing an environment to run the intended Python application. - While this attribute is currently optional, it will become required when the Python rules are moved out of Bazel itself. - The exact variable names expanded is an unstable API and is subject to change. The API will become more stable when the Python rules are moved out of Bazel itself. - -See @bazel_tools//tools/python:python_bootstrap_template.txt for more variables. - </td> - </tr> - <tr> - <td id="py_runtime.coverage_tool"> - <code>coverage_tool</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - This is a target to use for collecting code coverage information from +See @bazel_tools//tools/python:python_bootstrap_template.txt for more variables.</td> +</tr> +<tr> +<td id="py_runtime.coverage_tool"><code>coverage_tool</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +This is a target to use for collecting code coverage information from {rule}`py_binary` and {rule}`py_test` targets. - If set, the target must either produce a single file or be an executable target. The path to the single file, or the executable if the target is executable, -determines the entry point for the python coverage tool. The target and its +determines the entry point for the python coverage tool. The target and its runfiles will be added to the runfiles when coverage is enabled. - The entry point for the tool must be loadable by a Python interpreter (e.g. a -`.py` or `.pyc` file). It must accept the command line arguments +`.py` or `.pyc` file). It must accept the command line arguments of [`coverage.py`](https://coverage.readthedocs.io), at least including -the `run` and `lcov` subcommands. - </td> - </tr> - <tr> - <td id="py_runtime.files"> - <code>files</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - For an in-build runtime, this is the set of files comprising this runtime. +the `run` and `lcov` subcommands.</td> +</tr> +<tr> +<td id="py_runtime.files"><code>files</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +For an in-build runtime, this is the set of files comprising this runtime. These files will be added to the runfiles of Python binaries that use this -runtime. For a platform runtime this attribute must not be set. - </td> - </tr> - <tr> - <td id="py_runtime.implementation_name"> - <code>implementation_name</code> - </td> - <td> - <p>String; default is <code>"cpython"</code></p> - The Python implementation name (`sys.implementation.name`) - </td> - </tr> - <tr> - <td id="py_runtime.interpreter"> - <code>interpreter</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> - For an in-build runtime, this is the target to invoke as the interpreter. It +runtime. For a platform runtime this attribute must not be set.</td> +</tr> +<tr> +<td id="py_runtime.implementation_name"><code>implementation_name</code></td> +<td><p>String; default is <code>"cpython"</code></p> +The Python implementation name (`sys.implementation.name`)</td> +</tr> +<tr> +<td id="py_runtime.interpreter"><code>interpreter</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> +For an in-build runtime, this is the target to invoke as the interpreter. It can be either of: - * A single file, which will be the interpreter binary. It's assumed such - interpreters are either self-contained single-file executables or any - supporting files are specified in `files`. +interpreters are either self-contained single-file executables or any +supporting files are specified in `files`. * An executable target. The target's executable will be the interpreter binary. - Any other default outputs (`target.files`) and plain files runfiles - (`runfiles.files`) will be automatically included as if specified in the - `files` attribute. - - NOTE: the runfiles of the target may not yet be properly respected/propagated - to consumers of the toolchain/interpreter, see - bazel-contrib/rules_python/issues/1612 - +Any other default outputs (`target.files`) and plain files runfiles +(`runfiles.files`) will be automatically included as if specified in the +`files` attribute. +NOTE: the runfiles of the target may not yet be properly respected/propagated +to consumers of the toolchain/interpreter, see +bazel-contrib/rules_python/issues/1612 For a platform runtime (i.e. `interpreter_path` being set) this attribute must -not be set. - </td> - </tr> - <tr> - <td id="py_runtime.interpreter_path"> - <code>interpreter_path</code> - </td> - <td> - <p>String; default is <code>""</code></p> - For a platform runtime, this is the absolute path of a Python interpreter on -the target platform. For an in-build runtime this attribute must not be set. - </td> - </tr> - <tr> - <td id="py_runtime.interpreter_version_info"> - <code>interpreter_version_info</code> - </td> - <td> - <p>Dictionary: String -> String; default is <code>{}</code></p> - Version information about the interpreter this runtime provides. - +not be set.</td> +</tr> +<tr> +<td id="py_runtime.interpreter_path"><code>interpreter_path</code></td> +<td><p>String; default is <code>""</code></p> +For a platform runtime, this is the absolute path of a Python interpreter on +the target platform. For an in-build runtime this attribute must not be set.</td> +</tr> +<tr> +<td id="py_runtime.interpreter_version_info"><code>interpreter_version_info</code></td> +<td><p>Dictionary: String -> String; default is <code>{}</code></p> +Version information about the interpreter this runtime provides. If not specified, uses {obj}`--python_version` - The supported keys match the names for `sys.version_info`. While the input values are strings, most are converted to ints. The supported keys are: - * major: int, the major version number - * minor: int, the minor version number - * micro: optional int, the micro version number - * releaselevel: optional str, the release level - * serial: optional int, the serial number of the release - +* major: int, the major version number +* minor: int, the minor version number +* micro: optional int, the micro version number +* releaselevel: optional str, the release level +* serial: optional int, the serial number of the release :::{versionchanged} 0.36.0 {obj}`--python_version` determines the default value. -::: - </td> - </tr> - <tr> - <td id="py_runtime.pyc_tag"> - <code>pyc_tag</code> - </td> - <td> - <p>String; default is <code>""</code></p> - Optional string; the tag portion of a pyc filename, e.g. the `cpython-39` infix +:::</td> +</tr> +<tr> +<td id="py_runtime.pyc_tag"><code>pyc_tag</code></td> +<td><p>String; default is <code>""</code></p> +Optional string; the tag portion of a pyc filename, e.g. the `cpython-39` infix of `foo.cpython-39.pyc`. See PEP 3147. If not specified, it will be computed from `implementation_name` and `interpreter_version_info`. If no pyc_tag is -available, then only source-less pyc generation will function correctly. - </td> - </tr> - <tr> - <td id="py_runtime.python_version"> - <code>python_version</code> - </td> - <td> - <p>String; default is <code>"PY3"</code></p> - Whether this runtime is for Python major version 2 or 3. Valid values are `"PY2"` +available, then only source-less pyc generation will function correctly.</td> +</tr> +<tr> +<td id="py_runtime.python_version"><code>python_version</code></td> +<td><p>String; default is <code>"PY3"</code></p> +Whether this runtime is for Python major version 2 or 3. Valid values are `"PY2"` and `"PY3"`. - The default value is controlled by the `--incompatible_py3_is_default` flag. However, in the future this attribute will be mandatory and have no default -value. - </td> - </tr> - <tr> - <td id="py_runtime.site_init_template"> - <code>site_init_template</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:site_init_template"</code></p> - The template to use for the binary-specific site-init hook run by the +value.</td> +</tr> +<tr> +<td id="py_runtime.site_init_template"><code>site_init_template</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:site_init_template"</code></p> +The template to use for the binary-specific site-init hook run by the interpreter at startup. - :::{versionadded} 0.41.0 -::: - </td> - </tr> - <tr> - <td id="py_runtime.stage2_bootstrap_template"> - <code>stage2_bootstrap_template</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:stage2_bootstrap_template"</code></p> - The template to use when two stage bootstrapping is enabled - +:::</td> +</tr> +<tr> +<td id="py_runtime.stage2_bootstrap_template"><code>stage2_bootstrap_template</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:stage2_bootstrap_template"</code></p> +The template to use when two stage bootstrapping is enabled :::{seealso} {obj}`PyRuntimeInfo.stage2_bootstrap_template` and {obj}`--bootstrap_impl` -::: - </td> - </tr> - <tr> - <td id="py_runtime.stub_shebang"> - <code>stub_shebang</code> - </td> - <td> - <p>String; default is <code>"#!/usr/bin/env python3"</code></p> - "Shebang" expression prepended to the bootstrapping Python stub script +:::</td> +</tr> +<tr> +<td id="py_runtime.stub_shebang"><code>stub_shebang</code></td> +<td><p>String; default is <code>"#!/usr/bin/env python3"</code></p> +"Shebang" expression prepended to the bootstrapping Python stub script used when executing {rule}`py_binary` targets. - See https://github.com/bazelbuild/bazel/issues/8685 for motivation. - -Does not apply to Windows. - </td> - </tr> - <tr> - <td id="py_runtime.zip_main_template"> - <code>zip_main_template</code> - </td> - <td> - <p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:zip_main_template"</code></p> - The template to use for a zip's top-level `__main__.py` file. - +Does not apply to Windows.</td> +</tr> +<tr> +<td id="py_runtime.zip_main_template"><code>zip_main_template</code></td> +<td><p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:zip_main_template"</code></p> +The template to use for a zip's top-level `__main__.py` file. This becomes the entry point executed when `python foo.zip` is run. - :::{seealso} The {obj}`PyRuntimeInfo.zip_main_template` field. -::: - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +:::</td> +</tr> +</tbody> +</table> diff --git a/reference/be/shell.mdx b/reference/be/shell.mdx index 50f85c5..0f096dd 100644 --- a/reference/be/shell.mdx +++ b/reference/be/shell.mdx @@ -2,186 +2,124 @@ title: 'shell' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_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">Shell Rules</h1> +# Shell Rules {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "_buttons.html" %} - - - - -<h2>Rules</h2> -<ul> - <li> - <a href="#sh_binary"> - sh_binary </a> - </li> - <li> - <a href="#sh_library"> - sh_library </a> - </li> - <li> - <a href="#sh_test"> - sh_test </a> - </li> -</ul> - - <h2 id="sh_binary"> - sh_binary - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_binary.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">sh_binary(<a href="#sh_binary.name">name</a>, <a href="#sh_binary.deps">deps</a>, <a href="#sh_binary.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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#binary.env">env</a>, <a href="#sh_binary.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="#sh_binary.use_bash_launcher">use_bash_launcher</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> - The <code>sh_binary</code> rule is used to declare executable shell scripts. - (<code>sh_binary</code> is a misnomer: its outputs aren't necessarily binaries.) This rule ensures - that all dependencies are built, and appear in the <code>runfiles</code> area at execution time. - We recommend that you name your <code>sh_binary()</code> rules after the name of the script minus - the extension (e.g. <code>.sh</code>); the rule name and the file name must be distinct. - <code>sh_binary</code> respects shebangs, so any available interpreter may be used (eg. - <code>#!/bin/zsh</code>) -</p> -<h4 id="sh_binary_examples">Example</h4> -<p>For a simple shell script with no dependencies and some data files: -</p> -<pre class="code"> +{% include "\_buttons.html" %} + +## Rules + +- [sh_binary](#sh_binary) +- [sh_library](#sh_library) +- [sh_test](#sh_test) + +## sh_binary + +<a href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_binary.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +sh_binary(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, output_licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, use_bash_launcher, visibility) +``` + +The `sh_binary` rule is used to declare executable shell scripts. +(`sh_binary` is a misnomer: its outputs aren't necessarily binaries.) This rule ensures +that all dependencies are built, and appear in the `runfiles` area at execution time. +We recommend that you name your `sh_binary()` rules after the name of the script minus +the extension (e.g. `.sh`); the rule name and the file name must be distinct. +`sh_binary` respects shebangs, so any available interpreter may be used (eg. +`#!/bin/zsh`) + +#### Example + +For a simple shell script with no dependencies and some data files: + +``` code + sh_binary( name = "foo", srcs = ["foo.sh"], data = glob(["datafiles/*.txt"]), ) -</pre> - - <h3 id="sh_binary_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="sh_binary.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="sh_binary.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of "library" targets to be aggregated into this target. +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="sh_binary.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="sh_binary.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of "library" targets to be aggregated into this target. See general comments about <code>deps</code> at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by most build rules</a>. -<p> - This attribute should be used to list other <code>sh_library</code> rules that provide - interpreted program source code depended on by the code in <code>srcs</code>. The files - provided by these rules will be present among the <code>runfiles</code> of this target. -</p> - </td> - </tr> - <tr> - <td id="sh_binary.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The file containing the shell script. -<p> - This attribute must be a singleton list, whose element is the shell script. - This script must be executable, and may be a source file or a generated file. - All other files required at runtime (whether scripts or data) belong in the - <code>data</code> attribute. -</p> - </td> - </tr> - <tr> - <td id="sh_binary.env_inherit"> - <code>env_inherit</code> - </td> - <td> - <p>List of strings; default is <code>[]</code></p> - - </td> - </tr> - <tr> - <td id="sh_binary.use_bash_launcher"> - <code>use_bash_launcher</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Use a bash launcher initializing the runfiles library - </td> - </tr> - </tbody> - </table> - <h2 id="sh_library"> - sh_library - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_library.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">sh_library(<a href="#sh_library.name">name</a>, <a href="#sh_library.deps">deps</a>, <a href="#sh_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#common.package_metadata">package_metadata</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.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p> - The main use for this rule is to aggregate together a logical - "library" consisting of related scripts—programs in an - interpreted language that does not require compilation or linking, - such as the Bourne shell—and any data those programs need at - run-time. Such "libraries" can then be used from - the <code>data</code> attribute of one or - more <code>sh_binary</code> rules. -</p> - -<p> - You can use the <a href="/reference/be/general.html#filegroup"><code>filegroup</code></a> rule to aggregate data - files. -</p> - -<p> - In interpreted programming languages, there's not always a clear - distinction between "code" and "data": after all, the program is - just "data" from the interpreter's point of view. For this reason - this rule has three attributes which are all essentially equivalent: - <code>srcs</code>, <code>deps</code> and <code>data</code>. - The current implementation does not distinguish between the elements of these lists. - All three attributes accept rules, source files and generated files. - It is however good practice to use the attributes for their usual purpose (as with other rules). -</p> - -<h4 id="sh_library_examples">Examples</h4> - -<pre class="code"> +<p>This attribute should be used to list other <code>sh_library</code> rules that provide +interpreted program source code depended on by the code in <code>srcs</code>. The files +provided by these rules will be present among the <code>runfiles</code> of this target.</p></td> +</tr> +<tr> +<td id="sh_binary.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The file containing the shell script. +<p>This attribute must be a singleton list, whose element is the shell script. +This script must be executable, and may be a source file or a generated file. +All other files required at runtime (whether scripts or data) belong in the +<code>data</code> attribute.</p></td> +</tr> +<tr> +<td id="sh_binary.env_inherit"><code>env_inherit</code></td> +<td><p>List of strings; default is <code>[]</code></p></td> +</tr> +<tr> +<td id="sh_binary.use_bash_launcher"><code>use_bash_launcher</code></td> +<td><p>Boolean; default is <code>False</code></p> +Use a bash launcher initializing the runfiles library</td> +</tr> +</tbody> +</table> + +## sh_library + +<a href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +sh_library(name, deps, srcs, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +The main use for this rule is to aggregate together a logical +"library" consisting of related scripts—programs in an +interpreted language that does not require compilation or linking, +such as the Bourne shell—and any data those programs need at +run-time. Such "libraries" can then be used from +the `data` attribute of one or +more `sh_binary` rules. + +You can use the [`filegroup`](/reference/be/general.html#filegroup) rule to aggregate data +files. + +In interpreted programming languages, there's not always a clear +distinction between "code" and "data": after all, the program is +just "data" from the interpreter's point of view. For this reason +this rule has three attributes which are all essentially equivalent: +`srcs`, `deps` and `data`. +The current implementation does not distinguish between the elements of these lists. +All three attributes accept rules, source files and generated files. +It is however good practice to use the attributes for their usual purpose (as with other rules). + +#### Examples + +``` code + sh_library( name = "foo", data = [ @@ -189,79 +127,61 @@ sh_library( ":deploy_foo", # another sh_binary with srcs ], ) -</pre> - - <h3 id="sh_library_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="sh_library.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="sh_library.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of "library" targets to be aggregated into this target. +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="sh_library.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="sh_library.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of "library" targets to be aggregated into this target. See general comments about <code>deps</code> at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by most build rules</a>. -<p> - This attribute should be used to list other <code>sh_library</code> rules that provide - interpreted program source code depended on by the code in <code>srcs</code>. The files - provided by these rules will be present among the <code>runfiles</code> of this target. -</p> - </td> - </tr> - <tr> - <td id="sh_library.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of input files. -<p> - This attribute should be used to list shell script source files that belong to - this library. Scripts can load other scripts using the shell's <code>source</code> - or <code>.</code> command. -</p> - </td> - </tr> - </tbody> - </table> - <h2 id="sh_test"> - sh_test - </h2> - - <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_test.bzl" target="_blank"> - View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> - </a> - - <pre class="rule-signature">sh_test(<a href="#sh_test.name">name</a>, <a href="#sh_test.deps">deps</a>, <a href="#sh_test.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.aspect_hints">aspect_hints</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#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_group_compatible_with">exec_group_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#test.flaky">flaky</a>, <a href="common-definitions.html#test.local">local</a>, <a href="common-definitions.html#common.package_metadata">package_metadata</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</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#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="#sh_test.use_bash_launcher">use_bash_launcher</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> - - <p>A <code>sh_test()</code> rule creates a test written as a Bourne shell script.</p> - -<p>See the <a href="/reference/be/common-definitions#common-attributes-tests"> -attributes common to all test rules (*_test)</a>.</p> - -<h4 id="sh_test_examples">Examples</h4> - -<pre class="code"> +<p>This attribute should be used to list other <code>sh_library</code> rules that provide +interpreted program source code depended on by the code in <code>srcs</code>. The files +provided by these rules will be present among the <code>runfiles</code> of this target.</p></td> +</tr> +<tr> +<td id="sh_library.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of input files. +<p>This attribute should be used to list shell script source files that belong to +this library. Scripts can load other scripts using the shell's <code>source</code> +or <code>.</code> command.</p></td> +</tr> +</tbody> +</table> + +## sh_test + +<a href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_test.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> + +``` rule-signature +sh_test(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, local, package_metadata, restricted_to, shard_count, size, tags, target_compatible_with, testonly, timeout, toolchains, use_bash_launcher, visibility) +``` + +A `sh_test()` rule creates a test written as a Bourne shell script. + +See the +[attributes common to all test rules (\*\_test)](/reference/be/common-definitions#common-attributes-tests). + +#### Examples + +``` code + sh_test( name = "foo_integration_test", size = "small", @@ -269,73 +189,46 @@ sh_test( deps = [":foo_sh_lib"], data = glob(["testdata/*.txt"]), ) -</pre> - - <h3 id="sh_test_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="sh_test.name"><code>name</code></td> - <td> - <p><a href="/concepts/labels#target-names">Name</a>; required</p> - <p>A unique name for this target.</p> - - </td> - </tr> - <tr> - <td id="sh_test.deps"> - <code>deps</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The list of "library" targets to be aggregated into this target. +``` + +### Arguments + +<table class="table table-condensed table-bordered table-params"> +<thead> +<tr> +<th colspan="2">Attributes</th> +</tr> +</thead> +<tbody> +<tr> +<td id="sh_test.name"><code>name</code></td> +<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> +<p>A unique name for this target.</p></td> +</tr> +<tr> +<td id="sh_test.deps"><code>deps</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The list of "library" targets to be aggregated into this target. See general comments about <code>deps</code> at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by most build rules</a>. -<p> - This attribute should be used to list other <code>sh_library</code> rules that provide - interpreted program source code depended on by the code in <code>srcs</code>. The files - provided by these rules will be present among the <code>runfiles</code> of this target. -</p> - </td> - </tr> - <tr> - <td id="sh_test.srcs"> - <code>srcs</code> - </td> - <td> - <p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> - The file containing the shell script. -<p> - This attribute must be a singleton list, whose element is the shell script. - This script must be executable, and may be a source file or a generated file. - All other files required at runtime (whether scripts or data) belong in the - <code>data</code> attribute. -</p> - </td> - </tr> - <tr> - <td id="sh_test.use_bash_launcher"> - <code>use_bash_launcher</code> - </td> - <td> - <p>Boolean; default is <code>False</code></p> - Use a bash launcher initializing the runfiles library - </td> - </tr> - </tbody> - </table> - -<!-- Generated footer --> - -</body> -</html> +<p>This attribute should be used to list other <code>sh_library</code> rules that provide +interpreted program source code depended on by the code in <code>srcs</code>. The files +provided by these rules will be present among the <code>runfiles</code> of this target.</p></td> +</tr> +<tr> +<td id="sh_test.srcs"><code>srcs</code></td> +<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> +The file containing the shell script. +<p>This attribute must be a singleton list, whose element is the shell script. +This script must be executable, and may be a source file or a generated file. +All other files required at runtime (whether scripts or data) belong in the +<code>data</code> attribute.</p></td> +</tr> +<tr> +<td id="sh_test.use_bash_launcher"><code>use_bash_launcher</code></td> +<td><p>Boolean; default is <code>False</code></p> +Use a bash launcher initializing the runfiles library</td> +</tr> +</tbody> +</table> diff --git a/reference/command-line-reference.mdx b/reference/command-line-reference.mdx index cf6021e..9aff8c2 100644 --- a/reference/command-line-reference.mdx +++ b/reference/command-line-reference.mdx @@ -1,12297 +1,11871 @@ --- -title: 'Command-Line Reference' +title: 'command-line-reference' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title">Command-Line Reference</h1> +# Command-Line Reference {% dynamic setvar source_file "site/command-line-reference-prefix.html" %} -{% include "_buttons.html" %} +{% include "\_buttons.html" %} + -<pre> -bazel [<startup options>] <command> [<args>] -</pre> + bazel [<startup options>] <command> [<args>] or -<pre> -bazel [<startup options>] <command> [<args>] -- [<target patterns>] -</pre> -See the <a href="/docs/build#specifying-build-targets">User's Guide</a> for the + bazel [<startup options>] <command> [<args>] -- [<target patterns>] + +See the [User's Guide](/docs/build#specifying-build-targets) for the target patterns syntax. -<h2>Option Syntax</h2> +## Option Syntax -<p> Options can be passed to Bazel in different ways. Options that require a value can be passed with either an equals sign or a space: -<pre> ---<option>=<value> ---<option> <value> -</pre> + + + --<option>=<value> + --<option> <value> + Some options have a single character short form; in that case, the short form has to be passed with a single dash and a space. -<pre> --<short_form> <value> -</pre> -</p> -<p> + + -<short_form> <value> + Boolean options can be enabled as follows: -<pre> ---<option> ---<option>=[true|yes|1] -</pre> + + + --<option> + --<option>=[true|yes|1] and disabled as follows: -<pre> ---no<option> ---<option>=[false|no|0] -</pre> -</p> -<p> + + --no<option> + --<option>=[false|no|0] + Tristate options are usually set to automatic by default, and can be force-enabled as follows: -<pre> ---<option>=[true|yes|1] -</pre> + + + --<option>=[true|yes|1] + or force-disabled as follows: -<pre> ---no<option> ---<option>=[false|no|0] -</pre> -</p> -<h2>Commands</h2> -<table> -<tr> - <td><a href="#aquery"><code>aquery</code></a></td> - <td>Analyzes the given targets and queries the action graph.</td> -</tr> -<tr> - <td><a href="#build"><code>build</code></a></td> - <td>Builds the specified targets.</td> -</tr> -<tr> - <td><a href="#canonicalize-flags"><code>canonicalize-flags</code></a></td> - <td>Canonicalizes a list of bazel options.</td> -</tr> -<tr> - <td><a href="#clean"><code>clean</code></a></td> - <td>Removes output files and optionally stops the server.</td> -</tr> -<tr> - <td><a href="#coverage"><code>coverage</code></a></td> - <td>Generates code coverage report for specified test targets.</td> -</tr> -<tr> - <td><a href="#cquery"><code>cquery</code></a></td> - <td>Loads, analyzes, and queries the specified targets w/ configurations.</td> -</tr> -<tr> - <td><a href="#dump"><code>dump</code></a></td> - <td>Dumps the internal state of the bazel server process.</td> -</tr> -<tr> - <td><a href="#fetch"><code>fetch</code></a></td> - <td>Fetches external repositories that are prerequisites to the targets.</td> -</tr> -<tr> - <td><a href="#help"><code>help</code></a></td> - <td>Prints help for commands, or the index.</td> -</tr> -<tr> - <td><a href="#info"><code>info</code></a></td> - <td>Displays runtime info about the bazel server.</td> -</tr> -<tr> - <td><a href="#license"><code>license</code></a></td> - <td>Prints the license of this software.</td> -</tr> -<tr> - <td><a href="#mobile-install"><code>mobile-install</code></a></td> - <td>Installs targets to mobile devices.</td> -</tr> -<tr> - <td><a href="#mod"><code>mod</code></a></td> - <td>Queries the Bzlmod external dependency graph</td> -</tr> -<tr> - <td><a href="#print_action"><code>print_action</code></a></td> - <td>Prints the command line args for compiling a file.</td> -</tr> -<tr> - <td><a href="#query"><code>query</code></a></td> - <td>Executes a dependency graph query.</td> -</tr> -<tr> - <td><a href="#run"><code>run</code></a></td> - <td>Runs the specified target.</td> -</tr> -<tr> - <td><a href="#shutdown"><code>shutdown</code></a></td> - <td>Stops the bazel server.</td> -</tr> -<tr> - <td><a href="#test"><code>test</code></a></td> - <td>Builds and runs the specified test targets.</td> -</tr> -<tr> - <td><a href="#vendor"><code>vendor</code></a></td> - <td>Fetches external repositories into a folder specified by the flag --vendor_dir.</td> -</tr> -<tr> - <td><a href="#version"><code>version</code></a></td> - <td>Prints version information for bazel.</td> -</tr> -</table> - -<h2>Startup Options</h2> -<dl>Options that appear before the command and are parsed by the client: -<dt id="startup_options-flag--autodetect_server_javabase"><code id="autodetect_server_javabase"><a href="#startup_options-flag--autodetect_server_javabase">--[no]autodetect_server_javabase</a></code> default: "true"</dt> -<dd> -<p>When --noautodetect_server_javabase is passed, Bazel does not fall back to the local JDK for running the bazel server and instead exits.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="startup_options-flag--batch"><code id="batch"><a href="#startup_options-flag--batch">--[no]batch</a></code> default: "false"</dt> -<dd> -<p>If set, Bazel will be run as just a client process without a server, instead of in the standard client/server mode. This is deprecated and will be removed, please prefer shutting down the server explicitly if you wish to avoid lingering servers.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> -</p></dd> -<dt id="startup_options-flag--batch_cpu_scheduling"><code id="batch_cpu_scheduling"><a href="#startup_options-flag--batch_cpu_scheduling">--[no]batch_cpu_scheduling</a></code> default: "false"</dt> -<dd> -<p>Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched_setscheduler'. If false, then Bazel does not perform a system call.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="startup_options-flag--bazelrc"><code id="bazelrc"><a href="#startup_options-flag--bazelrc">--bazelrc</a>=<path></code> multiple uses are accumulated</dt> -<dd> -<p>The location of the user .bazelrc file containing default values of Bazel options. /dev/null indicates that all further <code>--bazelrc</code>s will be ignored, which is useful to disable the search for a user rc file, e.g. in release builds. + + + --no<option> + --<option>=[false|no|0] + +## Commands + +| | | +|----|----| +| [`aquery`](#aquery) | Analyzes the given targets and queries the action graph. | +| [`build`](#build) | Builds the specified targets. | +| [`canonicalize-flags`](#canonicalize-flags) | Canonicalizes a list of bazel options. | +| [`clean`](#clean) | Removes output files and optionally stops the server. | +| [`coverage`](#coverage) | Generates code coverage report for specified test targets. | +| [`cquery`](#cquery) | Loads, analyzes, and queries the specified targets w/ configurations. | +| [`dump`](#dump) | Dumps the internal state of the bazel server process. | +| [`fetch`](#fetch) | Fetches external repositories that are prerequisites to the targets. | +| [`help`](#help) | Prints help for commands, or the index. | +| [`info`](#info) | Displays runtime info about the bazel server. | +| [`license`](#license) | Prints the license of this software. | +| [`mobile-install`](#mobile-install) | Installs targets to mobile devices. | +| [`mod`](#mod) | Queries the Bzlmod external dependency graph | +| [`print_action`](#print_action) | Prints the command line args for compiling a file. | +| [`query`](#query) | Executes a dependency graph query. | +| [`run`](#run) | Runs the specified target. | +| [`shutdown`](#shutdown) | Stops the bazel server. | +| [`test`](#test) | Builds and runs the specified test targets. | +| [`vendor`](#vendor) | Fetches external repositories into a folder specified by the flag --vendor_dir. | +| [`version`](#version) | Prints version information for bazel. | + +## Startup Options + +[`--[no]autodetect_server_javabase`](#startup_options-flag--autodetect_server_javabase) default: "true" +When --noautodetect_server_javabase is passed, Bazel does not fall back to the local JDK for running the bazel server and instead exits. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]batch`](#startup_options-flag--batch) default: "false" +If set, Bazel will be run as just a client process without a server, instead of in the standard client/server mode. This is deprecated and will be removed, please prefer shutting down the server explicitly if you wish to avoid lingering servers. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`deprecated`](#metadata_tag_DEPRECATED) + +[`--[no]batch_cpu_scheduling`](#startup_options-flag--batch_cpu_scheduling) default: "false" +Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched_setscheduler'. If false, then Bazel does not perform a system call. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--bazelrc`](#startup_options-flag--bazelrc)`=<path>` multiple uses are accumulated +The location of the user .bazelrc file containing default values of Bazel options. /dev/null indicates that all further `--bazelrc`s will be ignored, which is useful to disable the search for a user rc file, e.g. in release builds. This option can also be specified multiple times. -E.g. with <code>--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc</code>,</p> -<ol> -<li>x.rc and y.rc are read.</li> -<li>z.rc is ignored due to the prior /dev/null. -If unspecified, Bazel uses the first .bazelrc file it finds in the following two locations: the workspace directory, then the user's home directory. -Note: command line options will always supersede any option in bazelrc.</li> -</ol> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="startup_options-flag--block_for_lock"><code id="block_for_lock"><a href="#startup_options-flag--block_for_lock">--[no]block_for_lock</a></code> default: "true"</dt> -<dd> -<p>When --noblock_for_lock is passed, Bazel does not wait for a running command to complete, but instead exits immediately.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="startup_options-flag--client_debug"><code id="client_debug"><a href="#startup_options-flag--client_debug">--[no]client_debug</a></code> default: "false"</dt> -<dd> -<p>If true, log debug information from the client to stderr. Changing this option will not cause the server to restart.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="startup_options-flag--connect_timeout_secs"><code id="connect_timeout_secs"><a href="#startup_options-flag--connect_timeout_secs">--connect_timeout_secs</a>=<an integer></code> default: "30"</dt> -<dd> -<p>The amount of time the client waits for each attempt to connect to the server</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="startup_options-flag--digest_function"><code id="digest_function"><a href="#startup_options-flag--digest_function">--digest_function</a>=<hash function></code> default: see description</dt> -<dd> -<p>The hash function to use when computing file digests.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="startup_options-flag--experimental_cgroup_parent"><code id="experimental_cgroup_parent"><a href="#startup_options-flag--experimental_cgroup_parent">--experimental_cgroup_parent</a>=<path></code> default: see description</dt> -<dd> -<p>The cgroup where to start the bazel server as an absolute path. The server process will be started in the specified cgroup for each supported controller. For example, if the value of this flag is /build/bazel and the cpu and memory controllers are mounted respectively on /sys/fs/cgroup/cpu and /sys/fs/cgroup/memory, the server will be started in the cgroups /sys/fs/cgroup/cpu/build/bazel and /sys/fs/cgroup/memory/build/bazel.It is not an error if the specified cgroup is not writable for one or more of the controllers. This options does not have any effect on platforms that do not support cgroups.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="startup_options-flag--experimental_run_in_user_cgroup"><code id="experimental_run_in_user_cgroup"><a href="#startup_options-flag--experimental_run_in_user_cgroup">--[no]experimental_run_in_user_cgroup</a></code> default: "false"</dt> -<dd> -<p>If true, the Bazel server will be run with systemd-run, and the user will own the cgroup. This flag only takes effect on Linux.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="startup_options-flag--failure_detail_out"><code id="failure_detail_out"><a href="#startup_options-flag--failure_detail_out">--failure_detail_out</a>=<path></code> default: see description</dt> -<dd> -<p>If set, specifies a location to write a failure_detail protobuf message if the server experiences a failure and cannot report it via gRPC, as normal. Otherwise, the location will be ${OUTPUT_BASE}/failure_detail.rawproto.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="startup_options-flag--home_rc"><code id="home_rc"><a href="#startup_options-flag--home_rc">--[no]home_rc</a></code> default: "true"</dt> -<dd> -<p>Whether or not to look for the home bazelrc file at $HOME/.bazelrc</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="startup_options-flag--idle_server_tasks"><code id="idle_server_tasks"><a href="#startup_options-flag--idle_server_tasks">--[no]idle_server_tasks</a></code> default: "true"</dt> -<dd> -<p>Run System.gc() when the server is idle</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="startup_options-flag--ignore_all_rc_files"><code id="ignore_all_rc_files"><a href="#startup_options-flag--ignore_all_rc_files">--[no]ignore_all_rc_files</a></code> default: "false"</dt> -<dd> -<p>Disables all rc files, regardless of the values of other rc-modifying flags, even if these flags come later in the list of startup options.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="startup_options-flag--io_nice_level"><code id="io_nice_level"><a href="#startup_options-flag--io_nice_level">--io_nice_level</a>={-1,0,1,2,3,4,5,6,7}</code> default: "-1"</dt> -<dd> -<p>Only on Linux; set a level from 0-7 for best-effort IO scheduling using the sys_ioprio_set system call. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. If set to a negative value, then Bazel does not perform a system call.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="startup_options-flag--local_startup_timeout_secs"><code id="local_startup_timeout_secs"><a href="#startup_options-flag--local_startup_timeout_secs">--local_startup_timeout_secs</a>=<an integer></code> default: "120"</dt> -<dd> -<p>The maximum amount of time the client waits to connect to the server</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="startup_options-flag--macos_qos_class"><code id="macos_qos_class"><a href="#startup_options-flag--macos_qos_class">--macos_qos_class</a>=<a string></code> default: "default"</dt> -<dd> -<p>Sets the QoS service class of the bazel server when running on macOS. This flag has no effect on all other platforms but is supported to ensure rc files can be shared among them without changes. Possible values are: user-interactive, user-initiated, default, utility, and background.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="startup_options-flag--max_idle_secs"><code id="max_idle_secs"><a href="#startup_options-flag--max_idle_secs">--max_idle_secs</a>=<integer></code> default: "10800"</dt> -<dd> -<p>The number of seconds the build server will wait idling before shutting down. Zero means that the server will never shutdown. This is only read on server-startup, changing this option will not cause the server to restart.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="startup_options-flag--output_base"><code id="output_base"><a href="#startup_options-flag--output_base">--output_base</a>=<path></code> default: see description</dt> -<dd> -<p>If set, specifies the output location to which all build output will be written. Otherwise, the location will be ${OUTPUT_ROOT}/<em>blaze</em>${USER}/${MD5_OF_WORKSPACE_ROOT}. Note: If you specify a different option from one to the next Bazel invocation for this value, you'll likely start up a new, additional Bazel server. Bazel starts exactly one server per specified output base. Typically there is one output base per workspace - however, with this option you may have multiple output bases per workspace and thereby run multiple builds for the same client on the same machine concurrently. See 'bazel help shutdown' on how to shutdown a Bazel server.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="startup_options-flag--output_user_root"><code id="output_user_root"><a href="#startup_options-flag--output_user_root">--output_user_root</a>=<path></code> default: see description</dt> -<dd> -<p>The user-specific directory beneath which all build outputs are written; by default, this is a function of $USER, but by specifying a constant, build outputs can be shared between collaborating users.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="startup_options-flag--preemptible"><code id="preemptible"><a href="#startup_options-flag--preemptible">--[no]preemptible</a></code> default: "false"</dt> -<dd> -<p>If true, the command can be preempted if another command is started.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="startup_options-flag--quiet"><code id="quiet"><a href="#startup_options-flag--quiet">--[no]quiet</a></code> default: "false"</dt> -<dd> -<p>If true, no informational messages are emitted on the console, only errors. Changing this option will not cause the server to restart.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="startup_options-flag--server_jvm_out"><code id="server_jvm_out"><a href="#startup_options-flag--server_jvm_out">--server_jvm_out</a>=<path></code> default: see description</dt> -<dd> -<p>The location to write the server's JVM's output. If unset then defaults to a location in output_base.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="startup_options-flag--shutdown_on_low_sys_mem"><code id="shutdown_on_low_sys_mem"><a href="#startup_options-flag--shutdown_on_low_sys_mem">--[no]shutdown_on_low_sys_mem</a></code> default: "false"</dt> -<dd> -<p>If max_idle_secs is set and the build server has been idle for a while, shut down the server when the system is low on free RAM. Linux and MacOS only.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="startup_options-flag--system_rc"><code id="system_rc"><a href="#startup_options-flag--system_rc">--[no]system_rc</a></code> default: "true"</dt> -<dd> -<p>Whether or not to look for the system-wide bazelrc.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="startup_options-flag--unlimit_coredumps"><code id="unlimit_coredumps"><a href="#startup_options-flag--unlimit_coredumps">--[no]unlimit_coredumps</a></code> default: "false"</dt> -<dd> -<p>Raises the soft coredump limit to the hard limit to make coredumps of the server (including the JVM) and the client possible under common conditions. Stick this flag in your bazelrc once and forget about it so that you get coredumps when you actually encounter a condition that triggers them.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="startup_options-flag--windows_enable_symlinks"><code id="windows_enable_symlinks"><a href="#startup_options-flag--windows_enable_symlinks">--[no]windows_enable_symlinks</a></code> default: "false"</dt> -<dd> -<p>If true, real symbolic links will be created on Windows instead of file copying. Requires Windows developer mode to be enabled and Windows 10 version 1703 or greater.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="startup_options-flag--workspace_rc"><code id="workspace_rc"><a href="#startup_options-flag--workspace_rc">--[no]workspace_rc</a></code> default: "true"</dt> -<dd> -<p>Whether or not to look for the workspace bazelrc file at $workspace/.bazelrc</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="startup_options-flag--host_jvm_args"><code id="host_jvm_args"><a href="#startup_options-flag--host_jvm_args">--host_jvm_args</a>=<jvm_arg></code> multiple uses are accumulated</dt> -<dd> -<p>Flags to pass to the JVM executing Blaze.</p> -</dd> -<dt id="startup_options-flag--host_jvm_debug"><code id="host_jvm_debug"><a href="#startup_options-flag--host_jvm_debug">--host_jvm_debug</a></code></dt> -<dd> -<p>Convenience option to add some additional JVM startup flags, which cause the JVM to wait during startup until you connect from a JDWP-compliant debugger (like Eclipse) to port 5005.</p> -<p>Expands to: -<br/>  <code><a href="#flag--host_jvm_args">--host_jvm_args=-agentlib:jdwp=transport=dt_socket,server=y,address=5005</a></code> -</p></dd> -<dt id="startup_options-flag--server_javabase"><code id="server_javabase"><a href="#startup_options-flag--server_javabase">--server_javabase</a>=<jvm path></code> default: ""</dt> -<dd> -<p>Path to the JVM used to execute Bazel itself.</p> -</dd> -</dl> - -<h2><a name="common_options">Options Common to all Commands</a></h2> -<dl>Options that appear before the command and are parsed by the client: -<dt id="common_options-flag--distdir"><code id="distdir"><a href="#common_options-flag--distdir">--distdir</a>=<a path></code> multiple uses are accumulated</dt> -<dd> -<p>Additional places to search for archives before accessing the network to download them.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--experimental_repository_cache_hardlinks"><code id="experimental_repository_cache_hardlinks"><a href="#common_options-flag--experimental_repository_cache_hardlinks">--[no]experimental_repository_cache_hardlinks</a></code> default: "false"</dt> -<dd> -<p>If set, the repository cache will hardlink the file in case of a cache hit, rather than copying. This is intended to save disk space.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--experimental_repository_downloader_retries"><code id="experimental_repository_downloader_retries"><a href="#common_options-flag--experimental_repository_downloader_retries">--experimental_repository_downloader_retries</a>=<an integer></code> default: "5"</dt> -<dd> -<p>The maximum number of attempts to retry a download error. If set to 0, retries are disabled.</p> -<p>Tags: -<a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_scale_timeouts"><code id="experimental_scale_timeouts"><a href="#common_options-flag--experimental_scale_timeouts">--experimental_scale_timeouts</a>=<a double></code> default: "1.0"</dt> -<dd> -<p>Scale all timeouts in Starlark repository rules by this factor. In this way, external repositories can be made working on machines that are slower than the rule author expected, without changing the source code</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--http_connector_attempts"><code id="http_connector_attempts"><a href="#common_options-flag--http_connector_attempts">--http_connector_attempts</a>=<an integer></code> default: "8"</dt> -<dd> -<p>The maximum number of attempts for http downloads.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--http_connector_retry_max_timeout"><code id="http_connector_retry_max_timeout"><a href="#common_options-flag--http_connector_retry_max_timeout">--http_connector_retry_max_timeout</a>=<An immutable length of time.></code> default: "0s"</dt> -<dd> -<p>The maximum timeout for http download retries. With a value of 0, no timeout maximum is defined.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--http_max_parallel_downloads"><code id="http_max_parallel_downloads"><a href="#common_options-flag--http_max_parallel_downloads">--http_max_parallel_downloads</a>=<an integer></code> default: "8"</dt> -<dd> -<p>The maximum number parallel http downloads.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--http_timeout_scaling"><code id="http_timeout_scaling"><a href="#common_options-flag--http_timeout_scaling">--http_timeout_scaling</a>=<a double></code> default: "1.0"</dt> -<dd> -<p>Scale all timeouts related to http downloads by the given factor</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--repo_contents_cache"><code id="repo_contents_cache"><a href="#common_options-flag--repo_contents_cache">--repo_contents_cache</a>=<a path></code> default: see description</dt> -<dd> -<p>Specifies the location of the repo contents cache, which contains fetched repo directories shareable across workspaces. An empty string as argument requests the repo contents cache to be disabled, otherwise the default of '<--repository_cache>/contents' is used. Note that this means setting '--repository_cache=' would by default disable the repo contents cache as well, unless '--repo_contents_cache=<some_path>' is also set.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--repo_contents_cache_gc_idle_delay"><code id="repo_contents_cache_gc_idle_delay"><a href="#common_options-flag--repo_contents_cache_gc_idle_delay">--repo_contents_cache_gc_idle_delay</a>=<An immutable length of time.></code> default: "5m"</dt> -<dd> -<p>Specifies the amount of time the server must remain idle before garbage collection happens -to the repo contents cache.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--repo_contents_cache_gc_max_age"><code id="repo_contents_cache_gc_max_age"><a href="#common_options-flag--repo_contents_cache_gc_max_age">--repo_contents_cache_gc_max_age</a>=<An immutable length of time.></code> default: "14d"</dt> -<dd> -<p>Specifies the amount of time an entry in the repo contents cache can stay unused before it's garbage collected. If set to zero, only duplicate entries will be garbage collected.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--repository_cache"><code id="repository_cache"><a href="#common_options-flag--repository_cache">--repository_cache</a>=<a path></code> default: see description</dt> -<dd> -<p>Specifies the cache location of the downloaded values obtained during the fetching of external repositories. An empty string as argument requests the cache to be disabled, otherwise the default of '<--output_user_root>/cache/repos/v1' is used</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--repository_disable_download"><code id="repository_disable_download"><a href="#common_options-flag--repository_disable_download">--[no]repository_disable_download</a></code> default: "false"</dt> -<dd> -<p>If set, downloading using ctx.download{,_and_extract} is not allowed during repository fetching. Note that network access is not completely disabled; ctx.execute could still run an arbitrary executable that accesses the Internet.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -</dl> -<dl>Options that control build execution: -<dt id="common_options-flag--experimental_ui_max_stdouterr_bytes"><code id="experimental_ui_max_stdouterr_bytes"><a href="#common_options-flag--experimental_ui_max_stdouterr_bytes">--experimental_ui_max_stdouterr_bytes</a>=<an integer in (-1)-1073741819 range></code> default: "1048576"</dt> -<dd> -<p>The maximum size of the stdout / stderr files that will be printed to the console. -1 implies no limit.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="common_options-flag--gc_churning_threshold"><code id="gc_churning_threshold"><a href="#common_options-flag--gc_churning_threshold">--gc_churning_threshold</a>=<an integer in 0-100 range></code> default: "100"</dt> -<dd> -<p>At any point after an invocation has been running for at least one minute, if Blaze has spent at least this percentage of the invocation's wall time doing full GCs, Blaze will give up and fail with an OOM. A value of 100 effectively means to never give up for this reason.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--gc_churning_threshold_if_multiple_top_level_targets"><code id="gc_churning_threshold_if_multiple_top_level_targets"><a href="#common_options-flag--gc_churning_threshold_if_multiple_top_level_targets">--gc_churning_threshold_if_multiple_top_level_targets</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>If set to a value in [0, 100] and this is a command that takes top-level targets (e.g. build but not query) and there are multiple such top-level targets, overrides --gc_churning_threshold. Useful to configure more aggressive OOMing behavior (i.e. a lower value than --gc_churning_threshold) when they are multiple top-level targets so that the invoker of Bazel can split and retry while still having less aggressive behavior when there is a single top-level target.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--gc_thrashing_threshold"><code id="gc_thrashing_threshold"><a href="#common_options-flag--gc_thrashing_threshold">--gc_thrashing_threshold</a>=<an integer in 0-100 range></code> default: "100"</dt> -<dd> -<p>The percent of tenured space occupied (0-100) above which GcThrashingDetector considers memory pressure events against its limits (--gc_thrashing_limits). If set to 100, GcThrashingDetector is disabled.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="common_options-flag--incompatible_enable_proto_toolchain_resolution"><code id="incompatible_enable_proto_toolchain_resolution"><a href="#common_options-flag--incompatible_enable_proto_toolchain_resolution">--[no]incompatible_enable_proto_toolchain_resolution</a></code> default: "false"</dt> -<dd> -<p>If true, proto lang rules define toolchains from protobuf repository.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="common_options-flag--bep_maximum_open_remote_upload_files"><code id="bep_maximum_open_remote_upload_files"><a href="#common_options-flag--bep_maximum_open_remote_upload_files">--bep_maximum_open_remote_upload_files</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>Maximum number of open files allowed during BEP artifact upload.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--remote_download_all"><code id="remote_download_all"><a href="#common_options-flag--remote_download_all">--remote_download_all</a></code></dt> -<dd> -<p>Downloads all remote outputs to the local machine. This flag is an alias for --remote_download_outputs=all.</p> -<p>Expands to: -<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=all</a></code> -</p><p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--remote_download_minimal"><code id="remote_download_minimal"><a href="#common_options-flag--remote_download_minimal">--remote_download_minimal</a></code></dt> -<dd> -<p>Does not download any remote build outputs to the local machine. This flag is an alias for --remote_download_outputs=minimal.</p> -<p>Expands to: -<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=minimal</a></code> -</p><p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--remote_download_outputs"><code id="remote_download_outputs"><a href="#common_options-flag--remote_download_outputs">--remote_download_outputs</a>=<all, minimal or toplevel></code> default: "toplevel"</dt> -<dd> -<p>If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--remote_download_symlink_template"><code id="remote_download_symlink_template"><a href="#common_options-flag--remote_download_symlink_template">--remote_download_symlink_template</a>=<a string></code> default: ""</dt> -<dd> -<p>Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--remote_download_toplevel"><code id="remote_download_toplevel"><a href="#common_options-flag--remote_download_toplevel">--remote_download_toplevel</a></code></dt> -<dd> -<p>Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote_download_outputs=toplevel.</p> -<p>Expands to: -<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=toplevel</a></code> -</p><p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--repo_env"><code id="repo_env"><a href="#common_options-flag--repo_env">--repo_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional environment variables to be available only for repository rules. Note that repository rules see the full environment anyway, but in this way variables can be set via command-line flags and <code>.bazelrc</code> entries. The special syntax <code>=NAME</code> can be used to explicitly unset a variable.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="common_options-flag--allow_experimental_loads"><code id="allow_experimental_loads"><a href="#common_options-flag--allow_experimental_loads">--[no]allow_experimental_loads</a></code> default: "false"</dt> -<dd> -<p>If enabled, issue only a warning instead of an error for loads of experimental .bzls.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="common_options-flag--check_bzl_visibility"><code id="check_bzl_visibility"><a href="#common_options-flag--check_bzl_visibility">--[no]check_bzl_visibility</a></code> default: "true"</dt> -<dd> -<p>If disabled, .bzl load visibility errors are demoted to warnings.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_enforce_starlark_utf8"><code id="incompatible_enforce_starlark_utf8"><a href="#common_options-flag--incompatible_enforce_starlark_utf8">--[no]incompatible_enforce_starlark_utf8</a></code> default: "warning"</dt> -<dd> -<p>If enabled (or set to 'error'), fail if Starlark files are not UTF-8 encoded. If set to 'warning', emit a warning instead. If set to 'off', Bazel assumes that Starlark files are UTF-8 encoded but does not verify this assumption. Note that Starlark files which are not UTF-8 encoded can cause Bazel to behave inconsistently.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="common_options-flag--experimental_bzl_visibility"><code id="experimental_bzl_visibility"><a href="#common_options-flag--experimental_bzl_visibility">--[no]experimental_bzl_visibility</a></code> default: "true"</dt> -<dd> -<p>If enabled, adds a <code>visibility()</code> function that .bzl files may call during top-level evaluation to set their visibility for the purpose of load() statements.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_cc_shared_library"><code id="experimental_cc_shared_library"><a href="#common_options-flag--experimental_cc_shared_library">--[no]experimental_cc_shared_library</a></code> default: "false"</dt> -<dd> -<p>If set to true, rule attributes and Starlark API methods needed for the rule cc_shared_library will be available</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_disable_external_package"><code id="experimental_disable_external_package"><a href="#common_options-flag--experimental_disable_external_package">--[no]experimental_disable_external_package</a></code> default: "false"</dt> -<dd> -<p>If set to true, the auto-generated //external package will not be available anymore. Bazel will still be unable to parse the file 'external/BUILD', but globs reaching into external/ from the unnamed package will work.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_dormant_deps"><code id="experimental_dormant_deps"><a href="#common_options-flag--experimental_dormant_deps">--[no]experimental_dormant_deps</a></code> default: "false"</dt> -<dd> -<p>If set to true, attr.label(materializer=), attr(for_dependency_resolution=), attr.dormant_label(), attr.dormant_label_list() and rule(for_dependency_resolution=) are allowed.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_enable_android_migration_apis"><code id="experimental_enable_android_migration_apis"><a href="#common_options-flag--experimental_enable_android_migration_apis">--[no]experimental_enable_android_migration_apis</a></code> default: "false"</dt> -<dd> -<p>If set to true, enables the APIs required to support the Android Starlark migration.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="common_options-flag--experimental_enable_first_class_macros"><code id="experimental_enable_first_class_macros"><a href="#common_options-flag--experimental_enable_first_class_macros">--[no]experimental_enable_first_class_macros</a></code> default: "true"</dt> -<dd> -<p>If set to true, enables the <code>macro()</code> construct for defining symbolic macros.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="common_options-flag--experimental_enable_scl_dialect"><code id="experimental_enable_scl_dialect"><a href="#common_options-flag--experimental_enable_scl_dialect">--[no]experimental_enable_scl_dialect</a></code> default: "true"</dt> -<dd> -<p>If set to true, .scl files may be used in load() statements.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="common_options-flag--experimental_enable_starlark_set"><code id="experimental_enable_starlark_set"><a href="#common_options-flag--experimental_enable_starlark_set">--[no]experimental_enable_starlark_set</a></code> default: "true"</dt> -<dd> -<p>If true, enable the set data type and set() constructor in Starlark.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_google_legacy_api"><code id="experimental_google_legacy_api"><a href="#common_options-flag--experimental_google_legacy_api">--[no]experimental_google_legacy_api</a></code> default: "false"</dt> -<dd> -<p>If set to true, exposes a number of experimental pieces of Starlark build API pertaining to Google legacy code.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_isolated_extension_usages"><code id="experimental_isolated_extension_usages"><a href="#common_options-flag--experimental_isolated_extension_usages">--[no]experimental_isolated_extension_usages</a></code> default: "false"</dt> -<dd> -<p>If true, enables the <code>isolate</code> parameter in the <a href="https://bazel.build/rules/lib/globals/module#use_extension"><code>use_extension</code></a> function.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--experimental_platforms_api"><code id="experimental_platforms_api"><a href="#common_options-flag--experimental_platforms_api">--[no]experimental_platforms_api</a></code> default: "false"</dt> -<dd> -<p>If set to true, enables a number of platform-related Starlark APIs useful for debugging.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_repo_remote_exec"><code id="experimental_repo_remote_exec"><a href="#common_options-flag--experimental_repo_remote_exec">--[no]experimental_repo_remote_exec</a></code> default: "false"</dt> -<dd> -<p>If set to true, repository_rule gains some remote execution capabilities.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_repository_ctx_execute_wasm"><code id="experimental_repository_ctx_execute_wasm"><a href="#common_options-flag--experimental_repository_ctx_execute_wasm">--[no]experimental_repository_ctx_execute_wasm</a></code> default: "false"</dt> -<dd> -<p>If true enables the repository_ctx <code>load_wasm</code> and <code>execute_wasm</code> methods.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_sibling_repository_layout"><code id="experimental_sibling_repository_layout"><a href="#common_options-flag--experimental_sibling_repository_layout">--[no]experimental_sibling_repository_layout</a></code> default: "false"</dt> -<dd> -<p>If set to true, non-main repositories are planted as symlinks to the main repository in the execution root. That is, all repositories are direct children of the $output_base/execution_root directory. This has the side effect of freeing up $output_base/execution_root/<strong>main</strong>/external for the real top-level 'external' directory.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_single_package_toolchain_binding"><code id="experimental_single_package_toolchain_binding"><a href="#common_options-flag--experimental_single_package_toolchain_binding">--[no]experimental_single_package_toolchain_binding</a></code> default: "false"</dt> -<dd> -<p>If enabled, the register_toolchain function may not include target patterns which may refer to more than one package.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--experimental_starlark_types"><code id="experimental_starlark_types"><a href="#common_options-flag--experimental_starlark_types">--[no]experimental_starlark_types</a></code> default: "false"</dt> -<dd> -<p>Enables type annotations and type checking. Locations where the annotations are allowed is further controlled by <code>--experimental_starlark_types_allowed_paths</code>.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_starlark_types_allowed_paths"><code id="experimental_starlark_types_allowed_paths"><a href="#common_options-flag--experimental_starlark_types_allowed_paths">--experimental_starlark_types_allowed_paths</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>List of canonical Label prefixes under which Starlark type annotations are allowed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_allow_tags_propagation"><code id="incompatible_allow_tags_propagation"><a href="#common_options-flag--incompatible_allow_tags_propagation">--[no]incompatible_allow_tags_propagation</a></code> default: "true"</dt> -<dd> -<p>If set to true, tags will be propagated from a target to the actions' execution requirements; otherwise tags are not propagated. See https://github.com/bazelbuild/bazel/issues/8830 for details.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_always_check_depset_elements"><code id="incompatible_always_check_depset_elements"><a href="#common_options-flag--incompatible_always_check_depset_elements">--[no]incompatible_always_check_depset_elements</a></code> default: "true"</dt> -<dd> -<p>Check the validity of elements added to depsets, in all constructors. Elements must be immutable, but historically the depset(direct=...) constructor forgot to check. Use tuples instead of lists in depset elements. See https://github.com/bazelbuild/bazel/issues/10313 for details.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_autoload_externally"><code id="incompatible_autoload_externally"><a href="#common_options-flag--incompatible_autoload_externally">--incompatible_autoload_externally</a>=<comma-separated set of options></code> default: "+@rules_cc"</dt> -<dd> -<p>A comma-separated list of rules (or other symbols) that were previously part of Bazel and which are now to be retrieved from their respective external repositories. This flag is intended to be used to facilitate migration of rules out of Bazel. See also https://github.com/bazelbuild/bazel/issues/23043. -A symbol that is autoloaded within a file behaves as if its built-into-Bazel definition were replaced by its canonical new definition in an external repository. For a BUILD file, this essentially means implicitly adding a load() statement. For a .bzl file, it's either a load() statement or a change to a field of the <code>native</code> object, depending on whether the autoloaded symbol is a rule. +E.g. with `--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc`, + +1. x.rc and y.rc are read. +2. z.rc is ignored due to the prior /dev/null. + If unspecified, Bazel uses the first .bazelrc file it finds in the following two locations: the workspace directory, then the user's home directory. + Note: command line options will always supersede any option in bazelrc. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--[no]block_for_lock`](#startup_options-flag--block_for_lock) default: "true" +When --noblock_for_lock is passed, Bazel does not wait for a running command to complete, but instead exits immediately. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]client_debug`](#startup_options-flag--client_debug) default: "false" +If true, log debug information from the client to stderr. Changing this option will not cause the server to restart. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--connect_timeout_secs`](#startup_options-flag--connect_timeout_secs)`=<an integer>` default: "30" +The amount of time the client waits for each attempt to connect to the server + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--digest_function`](#startup_options-flag--digest_function)`=<hash function>` default: see description +The hash function to use when computing file digests. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--experimental_cgroup_parent`](#startup_options-flag--experimental_cgroup_parent)`=<path>` default: see description +The cgroup where to start the bazel server as an absolute path. The server process will be started in the specified cgroup for each supported controller. For example, if the value of this flag is /build/bazel and the cpu and memory controllers are mounted respectively on /sys/fs/cgroup/cpu and /sys/fs/cgroup/memory, the server will be started in the cgroups /sys/fs/cgroup/cpu/build/bazel and /sys/fs/cgroup/memory/build/bazel.It is not an error if the specified cgroup is not writable for one or more of the controllers. This options does not have any effect on platforms that do not support cgroups. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_run_in_user_cgroup`](#startup_options-flag--experimental_run_in_user_cgroup) default: "false" +If true, the Bazel server will be run with systemd-run, and the user will own the cgroup. This flag only takes effect on Linux. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) + +[`--failure_detail_out`](#startup_options-flag--failure_detail_out)`=<path>` default: see description +If set, specifies a location to write a failure_detail protobuf message if the server experiences a failure and cannot report it via gRPC, as normal. Otherwise, the location will be \${OUTPUT_BASE}/failure_detail.rawproto. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]home_rc`](#startup_options-flag--home_rc) default: "true" +Whether or not to look for the home bazelrc file at \$HOME/.bazelrc + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--[no]idle_server_tasks`](#startup_options-flag--idle_server_tasks) default: "true" +Run System.gc() when the server is idle + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]ignore_all_rc_files`](#startup_options-flag--ignore_all_rc_files) default: "false" +Disables all rc files, regardless of the values of other rc-modifying flags, even if these flags come later in the list of startup options. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--io_nice_level`](#startup_options-flag--io_nice_level)`={-1,0,1,2,3,4,5,6,7}` default: "-1" +Only on Linux; set a level from 0-7 for best-effort IO scheduling using the sys_ioprio_set system call. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. If set to a negative value, then Bazel does not perform a system call. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--local_startup_timeout_secs`](#startup_options-flag--local_startup_timeout_secs)`=<an integer>` default: "120" +The maximum amount of time the client waits to connect to the server + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--macos_qos_class`](#startup_options-flag--macos_qos_class)`=<a string>` default: "default" +Sets the QoS service class of the bazel server when running on macOS. This flag has no effect on all other platforms but is supported to ensure rc files can be shared among them without changes. Possible values are: user-interactive, user-initiated, default, utility, and background. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--max_idle_secs`](#startup_options-flag--max_idle_secs)`=<integer>` default: "10800" +The number of seconds the build server will wait idling before shutting down. Zero means that the server will never shutdown. This is only read on server-startup, changing this option will not cause the server to restart. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--output_base`](#startup_options-flag--output_base)`=<path>` default: see description +If set, specifies the output location to which all build output will be written. Otherwise, the location will be \${OUTPUT_ROOT}/*blaze*\${USER}/\${MD5_OF_WORKSPACE_ROOT}. Note: If you specify a different option from one to the next Bazel invocation for this value, you'll likely start up a new, additional Bazel server. Bazel starts exactly one server per specified output base. Typically there is one output base per workspace - however, with this option you may have multiple output bases per workspace and thereby run multiple builds for the same client on the same machine concurrently. See 'bazel help shutdown' on how to shutdown a Bazel server. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--output_user_root`](#startup_options-flag--output_user_root)`=<path>` default: see description +The user-specific directory beneath which all build outputs are written; by default, this is a function of \$USER, but by specifying a constant, build outputs can be shared between collaborating users. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]preemptible`](#startup_options-flag--preemptible) default: "false" +If true, the command can be preempted if another command is started. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]quiet`](#startup_options-flag--quiet) default: "false" +If true, no informational messages are emitted on the console, only errors. Changing this option will not cause the server to restart. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--server_jvm_out`](#startup_options-flag--server_jvm_out)`=<path>` default: see description +The location to write the server's JVM's output. If unset then defaults to a location in output_base. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]shutdown_on_low_sys_mem`](#startup_options-flag--shutdown_on_low_sys_mem) default: "false" +If max_idle_secs is set and the build server has been idle for a while, shut down the server when the system is low on free RAM. Linux and MacOS only. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]system_rc`](#startup_options-flag--system_rc) default: "true" +Whether or not to look for the system-wide bazelrc. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--[no]unlimit_coredumps`](#startup_options-flag--unlimit_coredumps) default: "false" +Raises the soft coredump limit to the hard limit to make coredumps of the server (including the JVM) and the client possible under common conditions. Stick this flag in your bazelrc once and forget about it so that you get coredumps when you actually encounter a condition that triggers them. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--[no]windows_enable_symlinks`](#startup_options-flag--windows_enable_symlinks) default: "false" +If true, real symbolic links will be created on Windows instead of file copying. Requires Windows developer mode to be enabled and Windows 10 version 1703 or greater. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--[no]workspace_rc`](#startup_options-flag--workspace_rc) default: "true" +Whether or not to look for the workspace bazelrc file at \$workspace/.bazelrc + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--host_jvm_args`](#startup_options-flag--host_jvm_args)`=<jvm_arg>` multiple uses are accumulated +Flags to pass to the JVM executing Blaze. + +[`--host_jvm_debug`](#startup_options-flag--host_jvm_debug) +Convenience option to add some additional JVM startup flags, which cause the JVM to wait during startup until you connect from a JDWP-compliant debugger (like Eclipse) to port 5005. + +Expands to: +  [`--host_jvm_args=-agentlib:jdwp=transport=dt_socket,server=y,address=5005`](#flag--host_jvm_args) + +[`--server_javabase`](#startup_options-flag--server_javabase)`=<jvm path>` default: "" +Path to the JVM used to execute Bazel itself. + +## <span id="common_options">Options Common to all Commands</span> + +[`--distdir`](#common_options-flag--distdir)`=<a path>` multiple uses are accumulated +Additional places to search for archives before accessing the network to download them. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--[no]experimental_repository_cache_hardlinks`](#common_options-flag--experimental_repository_cache_hardlinks) default: "false" +If set, the repository cache will hardlink the file in case of a cache hit, rather than copying. This is intended to save disk space. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--experimental_repository_downloader_retries`](#common_options-flag--experimental_repository_downloader_retries)`=<an integer>` default: "5" +The maximum number of attempts to retry a download error. If set to 0, retries are disabled. + +Tags: +[`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_scale_timeouts`](#common_options-flag--experimental_scale_timeouts)`=<a double>` default: "1.0" +Scale all timeouts in Starlark repository rules by this factor. In this way, external repositories can be made working on machines that are slower than the rule author expected, without changing the source code + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--http_connector_attempts`](#common_options-flag--http_connector_attempts)`=<an integer>` default: "8" +The maximum number of attempts for http downloads. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--http_connector_retry_max_timeout`](#common_options-flag--http_connector_retry_max_timeout)`=<An immutable length of time.>` default: "0s" +The maximum timeout for http download retries. With a value of 0, no timeout maximum is defined. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--http_max_parallel_downloads`](#common_options-flag--http_max_parallel_downloads)`=<an integer>` default: "8" +The maximum number parallel http downloads. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--http_timeout_scaling`](#common_options-flag--http_timeout_scaling)`=<a double>` default: "1.0" +Scale all timeouts related to http downloads by the given factor + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--repo_contents_cache`](#common_options-flag--repo_contents_cache)`=<a path>` default: see description +Specifies the location of the repo contents cache, which contains fetched repo directories shareable across workspaces. An empty string as argument requests the repo contents cache to be disabled, otherwise the default of '\<--repository_cache\>/contents' is used. Note that this means setting '--repository_cache=' would by default disable the repo contents cache as well, unless '--repo_contents_cache=\<some_path\>' is also set. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--repo_contents_cache_gc_idle_delay`](#common_options-flag--repo_contents_cache_gc_idle_delay)`=<An immutable length of time.>` default: "5m" +Specifies the amount of time the server must remain idle before garbage collection happens +to the repo contents cache. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--repo_contents_cache_gc_max_age`](#common_options-flag--repo_contents_cache_gc_max_age)`=<An immutable length of time.>` default: "14d" +Specifies the amount of time an entry in the repo contents cache can stay unused before it's garbage collected. If set to zero, only duplicate entries will be garbage collected. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--repository_cache`](#common_options-flag--repository_cache)`=<a path>` default: see description +Specifies the cache location of the downloaded values obtained during the fetching of external repositories. An empty string as argument requests the cache to be disabled, otherwise the default of '\<--output_user_root\>/cache/repos/v1' is used + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--[no]repository_disable_download`](#common_options-flag--repository_disable_download) default: "false" +If set, downloading using ctx.download{,\_and_extract} is not allowed during repository fetching. Note that network access is not completely disabled; ctx.execute could still run an arbitrary executable that accesses the Internet. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +<!-- --> + +[`--experimental_ui_max_stdouterr_bytes`](#common_options-flag--experimental_ui_max_stdouterr_bytes)`=<an integer in (-1)-1073741819 range>` default: "1048576" +The maximum size of the stdout / stderr files that will be printed to the console. -1 implies no limit. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--gc_churning_threshold`](#common_options-flag--gc_churning_threshold)`=<an integer in 0-100 range>` default: "100" +At any point after an invocation has been running for at least one minute, if Blaze has spent at least this percentage of the invocation's wall time doing full GCs, Blaze will give up and fail with an OOM. A value of 100 effectively means to never give up for this reason. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--gc_churning_threshold_if_multiple_top_level_targets`](#common_options-flag--gc_churning_threshold_if_multiple_top_level_targets)`=<an integer>` default: "-1" +If set to a value in \[0, 100\] and this is a command that takes top-level targets (e.g. build but not query) and there are multiple such top-level targets, overrides --gc_churning_threshold. Useful to configure more aggressive OOMing behavior (i.e. a lower value than --gc_churning_threshold) when they are multiple top-level targets so that the invoker of Bazel can split and retry while still having less aggressive behavior when there is a single top-level target. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--gc_thrashing_threshold`](#common_options-flag--gc_thrashing_threshold)`=<an integer in 0-100 range>` default: "100" +The percent of tenured space occupied (0-100) above which GcThrashingDetector considers memory pressure events against its limits (--gc_thrashing_limits). If set to 100, GcThrashingDetector is disabled. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +<!-- --> + +[`--[no]incompatible_enable_proto_toolchain_resolution`](#common_options-flag--incompatible_enable_proto_toolchain_resolution) default: "false" +If true, proto lang rules define toolchains from protobuf repository. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--bep_maximum_open_remote_upload_files`](#common_options-flag--bep_maximum_open_remote_upload_files)`=<an integer>` default: "-1" +Maximum number of open files allowed during BEP artifact upload. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_all`](#common_options-flag--remote_download_all) +Downloads all remote outputs to the local machine. This flag is an alias for --remote_download_outputs=all. + +Expands to: +  [`--remote_download_outputs=all`](#flag--remote_download_outputs) + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_minimal`](#common_options-flag--remote_download_minimal) +Does not download any remote build outputs to the local machine. This flag is an alias for --remote_download_outputs=minimal. + +Expands to: +  [`--remote_download_outputs=minimal`](#flag--remote_download_outputs) + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_outputs`](#common_options-flag--remote_download_outputs)`=<all, minimal or toplevel>` default: "toplevel" +If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_symlink_template`](#common_options-flag--remote_download_symlink_template)`=<a string>` default: "" +Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_toplevel`](#common_options-flag--remote_download_toplevel) +Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote_download_outputs=toplevel. + +Expands to: +  [`--remote_download_outputs=toplevel`](#flag--remote_download_outputs) + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--repo_env`](#common_options-flag--repo_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies additional environment variables to be available only for repository rules. Note that repository rules see the full environment anyway, but in this way variables can be set via command-line flags and \<code\>.bazelrc\</code\> entries. The special syntax \<code\>=NAME\</code\> can be used to explicitly unset a variable. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +<!-- --> + +[`--[no]allow_experimental_loads`](#common_options-flag--allow_experimental_loads) default: "false" +If enabled, issue only a warning instead of an error for loads of experimental .bzls. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]check_bzl_visibility`](#common_options-flag--check_bzl_visibility) default: "true" +If disabled, .bzl load visibility errors are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]incompatible_enforce_starlark_utf8`](#common_options-flag--incompatible_enforce_starlark_utf8) default: "warning" +If enabled (or set to 'error'), fail if Starlark files are not UTF-8 encoded. If set to 'warning', emit a warning instead. If set to 'off', Bazel assumes that Starlark files are UTF-8 encoded but does not verify this assumption. Note that Starlark files which are not UTF-8 encoded can cause Bazel to behave inconsistently. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]experimental_bzl_visibility`](#common_options-flag--experimental_bzl_visibility) default: "true" +If enabled, adds a `visibility()` function that .bzl files may call during top-level evaluation to set their visibility for the purpose of load() statements. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_cc_shared_library`](#common_options-flag--experimental_cc_shared_library) default: "false" +If set to true, rule attributes and Starlark API methods needed for the rule cc_shared_library will be available + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_disable_external_package`](#common_options-flag--experimental_disable_external_package) default: "false" +If set to true, the auto-generated //external package will not be available anymore. Bazel will still be unable to parse the file 'external/BUILD', but globs reaching into external/ from the unnamed package will work. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_dormant_deps`](#common_options-flag--experimental_dormant_deps) default: "false" +If set to true, attr.label(materializer=), attr(for_dependency_resolution=), attr.dormant_label(), attr.dormant_label_list() and rule(for_dependency_resolution=) are allowed. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_enable_android_migration_apis`](#common_options-flag--experimental_enable_android_migration_apis) default: "false" +If set to true, enables the APIs required to support the Android Starlark migration. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_enable_first_class_macros`](#common_options-flag--experimental_enable_first_class_macros) default: "true" +If set to true, enables the `macro()` construct for defining symbolic macros. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_enable_scl_dialect`](#common_options-flag--experimental_enable_scl_dialect) default: "true" +If set to true, .scl files may be used in load() statements. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_enable_starlark_set`](#common_options-flag--experimental_enable_starlark_set) default: "true" +If true, enable the set data type and set() constructor in Starlark. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_google_legacy_api`](#common_options-flag--experimental_google_legacy_api) default: "false" +If set to true, exposes a number of experimental pieces of Starlark build API pertaining to Google legacy code. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_isolated_extension_usages`](#common_options-flag--experimental_isolated_extension_usages) default: "false" +If true, enables the \<code\>isolate\</code\> parameter in the \<a href="https://bazel.build/rules/lib/globals/module#use_extension"\>\<code\>use_extension\</code\>\</a\> function. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]experimental_platforms_api`](#common_options-flag--experimental_platforms_api) default: "false" +If set to true, enables a number of platform-related Starlark APIs useful for debugging. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_repo_remote_exec`](#common_options-flag--experimental_repo_remote_exec) default: "false" +If set to true, repository_rule gains some remote execution capabilities. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_repository_ctx_execute_wasm`](#common_options-flag--experimental_repository_ctx_execute_wasm) default: "false" +If true enables the repository_ctx `load_wasm` and `execute_wasm` methods. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_sibling_repository_layout`](#common_options-flag--experimental_sibling_repository_layout) default: "false" +If set to true, non-main repositories are planted as symlinks to the main repository in the execution root. That is, all repositories are direct children of the \$output_base/execution_root directory. This has the side effect of freeing up \$output_base/execution_root/**main**/external for the real top-level 'external' directory. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_single_package_toolchain_binding`](#common_options-flag--experimental_single_package_toolchain_binding) default: "false" +If enabled, the register_toolchain function may not include target patterns which may refer to more than one package. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]experimental_starlark_types`](#common_options-flag--experimental_starlark_types) default: "false" +Enables type annotations and type checking. Locations where the annotations are allowed is further controlled by `--experimental_starlark_types_allowed_paths`. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_starlark_types_allowed_paths`](#common_options-flag--experimental_starlark_types_allowed_paths)`=<comma-separated list of options>` default: "" +List of canonical Label prefixes under which Starlark type annotations are allowed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_allow_tags_propagation`](#common_options-flag--incompatible_allow_tags_propagation) default: "true" +If set to true, tags will be propagated from a target to the actions' execution requirements; otherwise tags are not propagated. See https://github.com/bazelbuild/bazel/issues/8830 for details. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_always_check_depset_elements`](#common_options-flag--incompatible_always_check_depset_elements) default: "true" +Check the validity of elements added to depsets, in all constructors. Elements must be immutable, but historically the depset(direct=...) constructor forgot to check. Use tuples instead of lists in depset elements. See https://github.com/bazelbuild/bazel/issues/10313 for details. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_autoload_externally`](#common_options-flag--incompatible_autoload_externally)`=<comma-separated set of options>` default: "+@rules_cc" +A comma-separated list of rules (or other symbols) that were previously part of Bazel and which are now to be retrieved from their respective external repositories. This flag is intended to be used to facilitate migration of rules out of Bazel. See also https://github.com/bazelbuild/bazel/issues/23043. +A symbol that is autoloaded within a file behaves as if its built-into-Bazel definition were replaced by its canonical new definition in an external repository. For a BUILD file, this essentially means implicitly adding a load() statement. For a .bzl file, it's either a load() statement or a change to a field of the `native` object, depending on whether the autoloaded symbol is a rule. Bazel maintains a hardcoded list of all symbols that may be autoloaded; only those symbols may appear in this flag. For each symbol, Bazel knows the new definition location in an external repository, as well as a set of special-cased repositories that must not autoload it to avoid creating cycles. -A list item of "+foo" in this flag causes symbol foo to be autoloaded, except in foo's exempt repositories, within which the Bazel-defined version of foo is still available. -A list item of "foo" triggers autoloading as above, but the Bazel-defined version of foo is not made available to the excluded repositories. This ensures that foo's external repository does not depend on the old Bazel implementation of foo -A list item of "-foo" does not trigger any autoloading, but makes the Bazel-defined version of foo inaccessible throughout the workspace. This is used to validate that the workspace is ready for foo's definition to be deleted from Bazel. -If a symbol is not named in this flag then it continues to work as normal -- no autoloading is done, nor is the Bazel-defined version suppressed. For configuration see https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/packages/AutoloadSymbols.java As a shortcut also whole repository may be used, for example +@rules_python will autoload all Python rules.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_disable_autoloads_in_main_repo"><code id="incompatible_disable_autoloads_in_main_repo"><a href="#common_options-flag--incompatible_disable_autoloads_in_main_repo">--[no]incompatible_disable_autoloads_in_main_repo</a></code> default: "true"</dt> -<dd> -<p>Controls if the autoloads (set by --incompatible_autoload_externally) are enabled in themain repository. When enabled the rules (or other symbols) that were previously part of Bazel need to have load statements. Use buildifier to add them.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_disable_objc_library_transition"><code id="incompatible_disable_objc_library_transition"><a href="#common_options-flag--incompatible_disable_objc_library_transition">--[no]incompatible_disable_objc_library_transition</a></code> default: "true"</dt> -<dd> -<p>Disable objc_library's custom transition and inherit from the top level target instead (No-op in Bazel)</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_disable_starlark_host_transitions"><code id="incompatible_disable_starlark_host_transitions"><a href="#common_options-flag--incompatible_disable_starlark_host_transitions">--[no]incompatible_disable_starlark_host_transitions</a></code> default: "false"</dt> -<dd> -<p>If set to true, rule attributes cannot set 'cfg = "host"'. Rules should set 'cfg = "exec"' instead.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_disable_target_default_provider_fields"><code id="incompatible_disable_target_default_provider_fields"><a href="#common_options-flag--incompatible_disable_target_default_provider_fields">--[no]incompatible_disable_target_default_provider_fields</a></code> default: "false"</dt> -<dd> -<p>If set to true, disable the ability to utilize the default provider via field syntax. Use provider-key syntax instead. For example, instead of using <code>ctx.attr.dep.files</code> to access <code>files</code>, utilize `ctx.attr.dep[DefaultInfo].files See https://github.com/bazelbuild/bazel/issues/9014 for details.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_disable_transitions_on"><code id="incompatible_disable_transitions_on"><a href="#common_options-flag--incompatible_disable_transitions_on">--incompatible_disable_transitions_on</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>A comma-separated list of flags that cannot be used in transitions inputs or outputs.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_disallow_ctx_resolve_tools"><code id="incompatible_disallow_ctx_resolve_tools"><a href="#common_options-flag--incompatible_disallow_ctx_resolve_tools">--[no]incompatible_disallow_ctx_resolve_tools</a></code> default: "true"</dt> -<dd> -<p>If set to true, calling the deprecated ctx.resolve_tools API always fails. Uses of this API should be replaced by an executable or tools argument to ctx.actions.run or ctx.actions.run_shell.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_disallow_empty_glob"><code id="incompatible_disallow_empty_glob"><a href="#common_options-flag--incompatible_disallow_empty_glob">--[no]incompatible_disallow_empty_glob</a></code> default: "true"</dt> -<dd> -<p>If set to true, the default value of the <code>allow_empty</code> argument of glob() is False.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_enable_deprecated_label_apis"><code id="incompatible_enable_deprecated_label_apis"><a href="#common_options-flag--incompatible_enable_deprecated_label_apis">--[no]incompatible_enable_deprecated_label_apis</a></code> default: "true"</dt> -<dd> -<p>If enabled, certain deprecated APIs (native.repository_name, Label.workspace_name, Label.relative) can be used.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_fail_on_unknown_attributes"><code id="incompatible_fail_on_unknown_attributes"><a href="#common_options-flag--incompatible_fail_on_unknown_attributes">--[no]incompatible_fail_on_unknown_attributes</a></code> default: "true"</dt> -<dd> -<p>If enabled, targets that have unknown attributes set to None fail.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_fix_package_group_reporoot_syntax"><code id="incompatible_fix_package_group_reporoot_syntax"><a href="#common_options-flag--incompatible_fix_package_group_reporoot_syntax">--[no]incompatible_fix_package_group_reporoot_syntax</a></code> default: "true"</dt> -<dd> -<p>In package_group's <code>packages</code> attribute, changes the meaning of the value "//..." to refer to all packages in the current repository instead of all packages in any repository. You can use the special value "public" in place of "//..." to obtain the old behavior. This flag requires that --incompatible_package_group_has_public_syntax also be enabled.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_locations_prefers_executable"><code id="incompatible_locations_prefers_executable"><a href="#common_options-flag--incompatible_locations_prefers_executable">--[no]incompatible_locations_prefers_executable</a></code> default: "true"</dt> -<dd> -<p>Whether a target that provides an executable expands to the executable rather than the files in <code>DefaultInfo.files</code> under $(locations ...) expansion if the number of files is not 1.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_no_attr_license"><code id="incompatible_no_attr_license"><a href="#common_options-flag--incompatible_no_attr_license">--[no]incompatible_no_attr_license</a></code> default: "true"</dt> -<dd> -<p>If set to true, disables the function <code>attr.license</code>.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_no_implicit_file_export"><code id="incompatible_no_implicit_file_export"><a href="#common_options-flag--incompatible_no_implicit_file_export">--[no]incompatible_no_implicit_file_export</a></code> default: "false"</dt> -<dd> -<p>If set, (used) source files are package private unless exported explicitly. See https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_no_implicit_watch_label"><code id="incompatible_no_implicit_watch_label"><a href="#common_options-flag--incompatible_no_implicit_watch_label">--[no]incompatible_no_implicit_watch_label</a></code> default: "true"</dt> -<dd> -<p>If true, then methods on <code>repository_ctx</code> that are passed a Label will no longer automatically watch the file under that label for changes even if <code>watch = "no"</code>, and <code>repository_ctx.path</code> no longer causes the returned path to be watched. Use <code>repository_ctx.watch</code> instead.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_no_rule_outputs_param"><code id="incompatible_no_rule_outputs_param"><a href="#common_options-flag--incompatible_no_rule_outputs_param">--[no]incompatible_no_rule_outputs_param</a></code> default: "false"</dt> -<dd> -<p>If set to true, disables the <code>outputs</code> parameter of the <code>rule()</code> Starlark function.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_package_group_has_public_syntax"><code id="incompatible_package_group_has_public_syntax"><a href="#common_options-flag--incompatible_package_group_has_public_syntax">--[no]incompatible_package_group_has_public_syntax</a></code> default: "true"</dt> -<dd> -<p>In package_group's <code>packages</code> attribute, allows writing "public" or "private" to refer to all packages or no packages respectively.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_resolve_select_keys_eagerly"><code id="incompatible_resolve_select_keys_eagerly"><a href="#common_options-flag--incompatible_resolve_select_keys_eagerly">--[no]incompatible_resolve_select_keys_eagerly</a></code> default: "false"</dt> -<dd> -<p>If enabled, string keys in dicts passed to select() in .bzl files are immediately resolved to Labels relative to the file instead of being interpreted relative to the BUILD file they are ultimately loaded from.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_run_shell_command_string"><code id="incompatible_run_shell_command_string"><a href="#common_options-flag--incompatible_run_shell_command_string">--[no]incompatible_run_shell_command_string</a></code> default: "true"</dt> -<dd> -<p>If set to true, the command parameter of actions.run_shell will only accept string</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_simplify_unconditional_selects_in_rule_attrs"><code id="incompatible_simplify_unconditional_selects_in_rule_attrs"><a href="#common_options-flag--incompatible_simplify_unconditional_selects_in_rule_attrs">--[no]incompatible_simplify_unconditional_selects_in_rule_attrs</a></code> default: "true"</dt> -<dd> -<p>If true, simplify configurable rule attributes which contain only unconditional selects; for example, if ["a"] + select("//conditions:default", ["b"]) is assigned to a rule attribute, it is stored as ["a", "b"]. This option does not affect attributes of symbolic macros or attribute default values.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_stop_exporting_build_file_path"><code id="incompatible_stop_exporting_build_file_path"><a href="#common_options-flag--incompatible_stop_exporting_build_file_path">--[no]incompatible_stop_exporting_build_file_path</a></code> default: "false"</dt> -<dd> -<p>If set to true, deprecated ctx.build_file_path will not be available. ctx.label.package + '/BUILD' can be used instead.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_stop_exporting_language_modules"><code id="incompatible_stop_exporting_language_modules"><a href="#common_options-flag--incompatible_stop_exporting_language_modules">--[no]incompatible_stop_exporting_language_modules</a></code> default: "false"</dt> -<dd> -<p>If enabled, certain language-specific modules (such as <code>cc_common</code>) are unavailable in user .bzl files and may only be called from their respective rules repositories.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_unambiguous_label_stringification"><code id="incompatible_unambiguous_label_stringification"><a href="#common_options-flag--incompatible_unambiguous_label_stringification">--[no]incompatible_unambiguous_label_stringification</a></code> default: "true"</dt> -<dd> -<p>When true, Bazel will stringify the label @//foo:bar to @//foo:bar, instead of //foo:bar. This only affects the behavior of str(), the % operator, and so on; the behavior of repr() is unchanged. See https://github.com/bazelbuild/bazel/issues/15916 for more information.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_use_cc_configure_from_rules_cc"><code id="incompatible_use_cc_configure_from_rules_cc"><a href="#common_options-flag--incompatible_use_cc_configure_from_rules_cc">--[no]incompatible_use_cc_configure_from_rules_cc</a></code> default: "false"</dt> -<dd> -<p>When true, Bazel will no longer allow using cc_configure from @bazel_tools. Please see https://github.com/bazelbuild/bazel/issues/10134 for details and migration instructions.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--max_computation_steps"><code id="max_computation_steps"><a href="#common_options-flag--max_computation_steps">--max_computation_steps</a>=<a long integer></code> default: "0"</dt> -<dd> -<p>The maximum number of Starlark computation steps that may be executed by a BUILD file (zero means no limit).</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="common_options-flag--nested_set_depth_limit"><code id="nested_set_depth_limit"><a href="#common_options-flag--nested_set_depth_limit">--nested_set_depth_limit</a>=<an integer></code> default: "3500"</dt> -<dd> -<p>The maximum depth of the graph internal to a depset (also known as NestedSet), above which the depset() constructor will fail.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--repositories_without_autoloads"><code id="repositories_without_autoloads"><a href="#common_options-flag--repositories_without_autoloads">--repositories_without_autoloads</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>A list of additional repositories (beyond the hardcoded ones Bazel knows about) where autoloads are not to be added. This should typically contain repositories that are transitively depended on by a repository that may be loaded automatically (and which can therefore potentially create a cycle).</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options relating to Bzlmod output and semantics: -<dt id="common_options-flag--allow_yanked_versions"><code id="allow_yanked_versions"><a href="#common_options-flag--allow_yanked_versions">--allow_yanked_versions</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Specified the module versions in the form of <code>&lt;module1&gt;@&lt;version1&gt;,&lt;module2&gt;@&lt;version2&gt;</code> that will be allowed in the resolved dependency graph even if they are declared yanked in the registry where they come from (if they are not coming from a NonRegistryOverride). Otherwise, yanked versions will cause the resolution to fail. You can also define allowed yanked version with the <code>BZLMOD_ALLOW_YANKED_VERSIONS</code> environment variable. You can disable this check by using the keyword 'all' (not recommended).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--check_bazel_compatibility"><code id="check_bazel_compatibility"><a href="#common_options-flag--check_bazel_compatibility">--check_bazel_compatibility</a>=<error, warning or off></code> default: "error"</dt> -<dd> -<p>Check bazel version compatibility of Bazel modules. Valid values are <code>error</code> to escalate it to a resolution failure, <code>off</code> to disable the check, or <code>warning</code> to print a warning when mismatch detected.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--check_direct_dependencies"><code id="check_direct_dependencies"><a href="#common_options-flag--check_direct_dependencies">--check_direct_dependencies</a>=<off, warning or error></code> default: "warning"</dt> -<dd> -<p>Check if the direct <code>bazel_dep</code> dependencies declared in the root module are the same versions you get in the resolved dependency graph. Valid values are <code>off</code> to disable the check, <code>warning</code> to print a warning when mismatch detected or <code>error</code> to escalate it to a resolution failure.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--ignore_dev_dependency"><code id="ignore_dev_dependency"><a href="#common_options-flag--ignore_dev_dependency">--[no]ignore_dev_dependency</a></code> default: "false"</dt> -<dd> -<p>If true, Bazel ignores <code>bazel_dep</code> and <code>use_extension</code> declared as <code>dev_dependency</code> in the MODULE.bazel of the root module. Note that, those dev dependencies are always ignored in the MODULE.bazel if it's not the root module regardless of the value of this flag.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--lockfile_mode"><code id="lockfile_mode"><a href="#common_options-flag--lockfile_mode">--lockfile_mode</a>=<off, update, refresh or error></code> default: "update"</dt> -<dd> -<p>Specifies how and whether or not to use the lockfile. Valid values are <code>update</code> to use the lockfile and update it if there are changes, <code>refresh</code> to additionally refresh mutable information (yanked versions and previously missing modules) from remote registries from time to time, <code>error</code> to use the lockfile but throw an error if it's not up-to-date, or <code>off</code> to neither read from or write to the lockfile.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--module_mirrors"><code id="module_mirrors"><a href="#common_options-flag--module_mirrors">--module_mirrors</a>=<comma-separated list of options></code> default: see description</dt> -<dd> -<p>A comma-separated list of URLs under which the source URLs of Bazel modules can be found, +A list item of "+foo" in this flag causes symbol foo to be autoloaded, except in foo's exempt repositories, within which the Bazel-defined version of foo is still available. +A list item of "foo" triggers autoloading as above, but the Bazel-defined version of foo is not made available to the excluded repositories. This ensures that foo's external repository does not depend on the old Bazel implementation of foo +A list item of "-foo" does not trigger any autoloading, but makes the Bazel-defined version of foo inaccessible throughout the workspace. This is used to validate that the workspace is ready for foo's definition to be deleted from Bazel. +If a symbol is not named in this flag then it continues to work as normal -- no autoloading is done, nor is the Bazel-defined version suppressed. For configuration see https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/packages/AutoloadSymbols.java As a shortcut also whole repository may be used, for example +@rules_python will autoload all Python rules. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_autoloads_in_main_repo`](#common_options-flag--incompatible_disable_autoloads_in_main_repo) default: "true" +Controls if the autoloads (set by --incompatible_autoload_externally) are enabled in themain repository. When enabled the rules (or other symbols) that were previously part of Bazel need to have load statements. Use buildifier to add them. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_objc_library_transition`](#common_options-flag--incompatible_disable_objc_library_transition) default: "true" +Disable objc_library's custom transition and inherit from the top level target instead (No-op in Bazel) + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_starlark_host_transitions`](#common_options-flag--incompatible_disable_starlark_host_transitions) default: "false" +If set to true, rule attributes cannot set 'cfg = "host"'. Rules should set 'cfg = "exec"' instead. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_target_default_provider_fields`](#common_options-flag--incompatible_disable_target_default_provider_fields) default: "false" +If set to true, disable the ability to utilize the default provider via field syntax. Use provider-key syntax instead. For example, instead of using `ctx.attr.dep.files` to access `files`, utilize \`ctx.attr.dep\[DefaultInfo\].files See https://github.com/bazelbuild/bazel/issues/9014 for details. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_disable_transitions_on`](#common_options-flag--incompatible_disable_transitions_on)`=<comma-separated set of options>` default: "" +A comma-separated list of flags that cannot be used in transitions inputs or outputs. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_disallow_ctx_resolve_tools`](#common_options-flag--incompatible_disallow_ctx_resolve_tools) default: "true" +If set to true, calling the deprecated ctx.resolve_tools API always fails. Uses of this API should be replaced by an executable or tools argument to ctx.actions.run or ctx.actions.run_shell. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disallow_empty_glob`](#common_options-flag--incompatible_disallow_empty_glob) default: "true" +If set to true, the default value of the `allow_empty` argument of glob() is False. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enable_deprecated_label_apis`](#common_options-flag--incompatible_enable_deprecated_label_apis) default: "true" +If enabled, certain deprecated APIs (native.repository_name, Label.workspace_name, Label.relative) can be used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]incompatible_fail_on_unknown_attributes`](#common_options-flag--incompatible_fail_on_unknown_attributes) default: "true" +If enabled, targets that have unknown attributes set to None fail. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_fix_package_group_reporoot_syntax`](#common_options-flag--incompatible_fix_package_group_reporoot_syntax) default: "true" +In package_group's `packages` attribute, changes the meaning of the value "//..." to refer to all packages in the current repository instead of all packages in any repository. You can use the special value "public" in place of "//..." to obtain the old behavior. This flag requires that --incompatible_package_group_has_public_syntax also be enabled. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_locations_prefers_executable`](#common_options-flag--incompatible_locations_prefers_executable) default: "true" +Whether a target that provides an executable expands to the executable rather than the files in \<code\>DefaultInfo.files\</code\> under \$(locations ...) expansion if the number of files is not 1. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_no_attr_license`](#common_options-flag--incompatible_no_attr_license) default: "true" +If set to true, disables the function `attr.license`. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_no_implicit_file_export`](#common_options-flag--incompatible_no_implicit_file_export) default: "false" +If set, (used) source files are package private unless exported explicitly. See https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_no_implicit_watch_label`](#common_options-flag--incompatible_no_implicit_watch_label) default: "true" +If true, then methods on \<code\>repository_ctx\</code\> that are passed a Label will no longer automatically watch the file under that label for changes even if \<code\>watch = "no"\</code\>, and \<code\>repository_ctx.path\</code\> no longer causes the returned path to be watched. Use \<code\>repository_ctx.watch\</code\> instead. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_no_rule_outputs_param`](#common_options-flag--incompatible_no_rule_outputs_param) default: "false" +If set to true, disables the `outputs` parameter of the `rule()` Starlark function. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_package_group_has_public_syntax`](#common_options-flag--incompatible_package_group_has_public_syntax) default: "true" +In package_group's `packages` attribute, allows writing "public" or "private" to refer to all packages or no packages respectively. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_resolve_select_keys_eagerly`](#common_options-flag--incompatible_resolve_select_keys_eagerly) default: "false" +If enabled, string keys in dicts passed to select() in .bzl files are immediately resolved to Labels relative to the file instead of being interpreted relative to the BUILD file they are ultimately loaded from. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_run_shell_command_string`](#common_options-flag--incompatible_run_shell_command_string) default: "true" +If set to true, the command parameter of actions.run_shell will only accept string + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_simplify_unconditional_selects_in_rule_attrs`](#common_options-flag--incompatible_simplify_unconditional_selects_in_rule_attrs) default: "true" +If true, simplify configurable rule attributes which contain only unconditional selects; for example, if \["a"\] + select("//conditions:default", \["b"\]) is assigned to a rule attribute, it is stored as \["a", "b"\]. This option does not affect attributes of symbolic macros or attribute default values. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_stop_exporting_build_file_path`](#common_options-flag--incompatible_stop_exporting_build_file_path) default: "false" +If set to true, deprecated ctx.build_file_path will not be available. ctx.label.package + '/BUILD' can be used instead. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_stop_exporting_language_modules`](#common_options-flag--incompatible_stop_exporting_language_modules) default: "false" +If enabled, certain language-specific modules (such as `cc_common`) are unavailable in user .bzl files and may only be called from their respective rules repositories. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_unambiguous_label_stringification`](#common_options-flag--incompatible_unambiguous_label_stringification) default: "true" +When true, Bazel will stringify the label @//foo:bar to @//foo:bar, instead of //foo:bar. This only affects the behavior of str(), the % operator, and so on; the behavior of repr() is unchanged. See https://github.com/bazelbuild/bazel/issues/15916 for more information. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_use_cc_configure_from_rules_cc`](#common_options-flag--incompatible_use_cc_configure_from_rules_cc) default: "false" +When true, Bazel will no longer allow using cc_configure from @bazel_tools. Please see https://github.com/bazelbuild/bazel/issues/10134 for details and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--max_computation_steps`](#common_options-flag--max_computation_steps)`=<a long integer>` default: "0" +The maximum number of Starlark computation steps that may be executed by a BUILD file (zero means no limit). + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--nested_set_depth_limit`](#common_options-flag--nested_set_depth_limit)`=<an integer>` default: "3500" +The maximum depth of the graph internal to a depset (also known as NestedSet), above which the depset() constructor will fail. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--repositories_without_autoloads`](#common_options-flag--repositories_without_autoloads)`=<comma-separated set of options>` default: "" +A list of additional repositories (beyond the hardcoded ones Bazel knows about) where autoloads are not to be added. This should typically contain repositories that are transitively depended on by a repository that may be loaded automatically (and which can therefore potentially create a cycle). + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--allow_yanked_versions`](#common_options-flag--allow_yanked_versions)`=<a string>` multiple uses are accumulated +Specified the module versions in the form of `<module1>@<version1>,<module2>@<version2>` that will be allowed in the resolved dependency graph even if they are declared yanked in the registry where they come from (if they are not coming from a NonRegistryOverride). Otherwise, yanked versions will cause the resolution to fail. You can also define allowed yanked version with the `BZLMOD_ALLOW_YANKED_VERSIONS` environment variable. You can disable this check by using the keyword 'all' (not recommended). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--check_bazel_compatibility`](#common_options-flag--check_bazel_compatibility)`=<error, warning or off>` default: "error" +Check bazel version compatibility of Bazel modules. Valid values are `error` to escalate it to a resolution failure, `off` to disable the check, or `warning` to print a warning when mismatch detected. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--check_direct_dependencies`](#common_options-flag--check_direct_dependencies)`=<off, warning or error>` default: "warning" +Check if the direct `bazel_dep` dependencies declared in the root module are the same versions you get in the resolved dependency graph. Valid values are `off` to disable the check, `warning` to print a warning when mismatch detected or `error` to escalate it to a resolution failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]ignore_dev_dependency`](#common_options-flag--ignore_dev_dependency) default: "false" +If true, Bazel ignores `bazel_dep` and `use_extension` declared as `dev_dependency` in the MODULE.bazel of the root module. Note that, those dev dependencies are always ignored in the MODULE.bazel if it's not the root module regardless of the value of this flag. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--lockfile_mode`](#common_options-flag--lockfile_mode)`=<off, update, refresh or error>` default: "update" +Specifies how and whether or not to use the lockfile. Valid values are `update` to use the lockfile and update it if there are changes, `refresh` to additionally refresh mutable information (yanked versions and previously missing modules) from remote registries from time to time, `error` to use the lockfile but throw an error if it's not up-to-date, or `off` to neither read from or write to the lockfile. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--module_mirrors`](#common_options-flag--module_mirrors)`=<comma-separated list of options>` default: see description +A comma-separated list of URLs under which the source URLs of Bazel modules can be found, in addition to and taking precedence over any registry-provided mirror URLs. Set this to an empty value to disable the use of any mirrors not specified by the registries. The default set of mirrors may change over time, but all downloads from mirrors are verified -by hashes stored in the registry (and thus pinned by the lockfile).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="common_options-flag--override_module"><code id="override_module"><a href="#common_options-flag--override_module">--override_module</a>=<an equals-separated mapping of module name to path></code> multiple uses are accumulated</dt> -<dd> -<p>Override a module with a local path in the form of <module name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of <code>bazel info workspace</code>. If the given path is empty, then remove any previous overrides.</p> -</dd> -<dt id="common_options-flag--registry"><code id="registry"><a href="#common_options-flag--registry">--registry</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the registries to use to locate Bazel module dependencies. The order is important: modules will be looked up in earlier registries first, and only fall back to later registries when they're missing from the earlier ones.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="common_options-flag--vendor_dir"><code id="vendor_dir"><a href="#common_options-flag--vendor_dir">--vendor_dir</a>=<a path></code> default: see description</dt> -<dd> -<p>Specifies the directory that should hold the external repositories in vendor mode, whether for the purpose of fetching them into it or using them while building. The path can be specified as either an absolute path or a path relative to the workspace directory.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> -<dl>Options that trigger optimizations of the build time: -<dt id="common_options-flag--gc_thrashing_limits"><code id="gc_thrashing_limits"><a href="#common_options-flag--gc_thrashing_limits">--gc_thrashing_limits</a>=<comma separated pairs of <period>:<count>></code> default: "1s:2,20s:3,1m:5"</dt> -<dd> -<p>Limits which, if reached, cause GcThrashingDetector to crash Bazel with an OOM. Each limit is specified as <period>:<count> where period is a duration and count is a positive integer. If more than --gc_thrashing_threshold percent of tenured space (old gen heap) remains occupied after <count> consecutive full GCs within <period>, an OOM is triggered. Multiple limits can be specified separated by commas.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--heuristically_drop_nodes"><code id="heuristically_drop_nodes"><a href="#common_options-flag--heuristically_drop_nodes">--[no]heuristically_drop_nodes</a></code> default: "false"</dt> -<dd> -<p>If true, Blaze will remove FileState and DirectoryListingState nodes after related File and DirectoryListing node is done to save memory. We expect that it is less likely that these nodes will be needed again. If so, the program will re-evaluate them.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_do_not_split_linking_cmdline"><code id="incompatible_do_not_split_linking_cmdline"><a href="#common_options-flag--incompatible_do_not_split_linking_cmdline">--[no]incompatible_do_not_split_linking_cmdline</a></code> default: "true"</dt> -<dd> -<p>When true, Bazel no longer modifies command line flags used for linking, and also doesn't selectively decide which flags go to the param file and which don't. See https://github.com/bazelbuild/bazel/issues/7670 for details.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--keep_state_after_build"><code id="keep_state_after_build"><a href="#common_options-flag--keep_state_after_build">--[no]keep_state_after_build</a></code> default: "true"</dt> -<dd> -<p>If false, Blaze will discard the inmemory state from this build when the build finishes. Subsequent builds will not have any incrementality with respect to this one.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="common_options-flag--skyframe_high_water_mark_full_gc_drops_per_invocation"><code id="skyframe_high_water_mark_full_gc_drops_per_invocation"><a href="#common_options-flag--skyframe_high_water_mark_full_gc_drops_per_invocation">--skyframe_high_water_mark_full_gc_drops_per_invocation</a>=<an integer, >= 0></code> default: "10"</dt> -<dd> -<p>Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe_high_water_mark_threshold, when a full GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that full GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a full GC event occurs and that retained heap percentage threshold is exceeded.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--skyframe_high_water_mark_minor_gc_drops_per_invocation"><code id="skyframe_high_water_mark_minor_gc_drops_per_invocation"><a href="#common_options-flag--skyframe_high_water_mark_minor_gc_drops_per_invocation">--skyframe_high_water_mark_minor_gc_drops_per_invocation</a>=<an integer, >= 0></code> default: "10"</dt> -<dd> -<p>Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe_high_water_mark_threshold, when a minor GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that minor GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a minor GC event occurs and that retained heap percentage threshold is exceeded.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--skyframe_high_water_mark_threshold"><code id="skyframe_high_water_mark_threshold"><a href="#common_options-flag--skyframe_high_water_mark_threshold">--skyframe_high_water_mark_threshold</a>=<an integer></code> default: "85"</dt> -<dd> -<p>Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage is at least this threshold, it will drop unnecessary temporary Skyframe state. Tweaking this may let you mitigate wall time impact of GC thrashing, when the GC thrashing is (i) caused by the memory usage of this temporary state and (ii) more costly than reconstituting the state when it is needed.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--track_incremental_state"><code id="track_incremental_state"><a href="#common_options-flag--track_incremental_state">--[no]track_incremental_state</a></code> default: "true"</dt> -<dd> -<p>If false, Blaze will not persist data that allows for invalidation and re-evaluation on incremental builds in order to save memory on this build. Subsequent builds will not have any incrementality with respect to this one. Usually you will want to specify --batch when setting this to false.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="common_options-flag--announce_rc"><code id="announce_rc"><a href="#common_options-flag--announce_rc">--[no]announce_rc</a></code> default: "false"</dt> -<dd> -<p>Whether to announce rc options.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--attempt_to_print_relative_paths"><code id="attempt_to_print_relative_paths"><a href="#common_options-flag--attempt_to_print_relative_paths">--[no]attempt_to_print_relative_paths</a></code> default: "false"</dt> -<dd> -<p>When printing the location part of messages, attempt to use a path relative to the workspace directory or one of the directories specified by --package_path.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="common_options-flag--bes_backend"><code id="bes_backend"><a href="#common_options-flag--bes_backend">--bes_backend</a>=<a string></code> default: ""</dt> -<dd> -<p>Specifies the build event service (BES) backend endpoint in the form [SCHEME://]HOST[:PORT]. The default is to disable BES uploads. Supported schemes are grpc and grpcs (grpc with TLS enabled). If no scheme is provided, Bazel assumes grpcs.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_check_preceding_lifecycle_events"><code id="bes_check_preceding_lifecycle_events"><a href="#common_options-flag--bes_check_preceding_lifecycle_events">--[no]bes_check_preceding_lifecycle_events</a></code> default: "false"</dt> -<dd> -<p>Sets the field check_preceding_lifecycle_events_present on PublishBuildToolEventStreamRequest which tells BES to check whether it previously received InvocationAttemptStarted and BuildEnqueued events matching the current tool event.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_header"><code id="bes_header"><a href="#common_options-flag--bes_header">--bes_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header in NAME=VALUE form that will be included in BES requests. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_instance_name"><code id="bes_instance_name"><a href="#common_options-flag--bes_instance_name">--bes_instance_name</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies the instance name under which the BES will persist uploaded BEP. Defaults to null.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_keywords"><code id="bes_keywords"><a href="#common_options-flag--bes_keywords">--bes_keywords</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies a list of notification keywords to be added the default set of keywords published to BES ("command_name=<command_name> ", "protocol_name=BEP"). Defaults to none.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_lifecycle_events"><code id="bes_lifecycle_events"><a href="#common_options-flag--bes_lifecycle_events">--[no]bes_lifecycle_events</a></code> default: "true"</dt> -<dd> -<p>Specifies whether to publish BES lifecycle events. (defaults to 'true').</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_oom_finish_upload_timeout"><code id="bes_oom_finish_upload_timeout"><a href="#common_options-flag--bes_oom_finish_upload_timeout">--bes_oom_finish_upload_timeout</a>=<An immutable length of time.></code> default: "10m"</dt> -<dd> -<p>Specifies how long bazel should wait for the BES/BEP upload to complete while OOMing. This flag ensures termination when the JVM is severely GC thrashing and cannot make progress on any user thread.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--bes_outerr_buffer_size"><code id="bes_outerr_buffer_size"><a href="#common_options-flag--bes_outerr_buffer_size">--bes_outerr_buffer_size</a>=<an integer></code> default: "10240"</dt> -<dd> -<p>Specifies the maximal size of stdout or stderr to be buffered in BEP, before it is reported as a progress event. Individual writes are still reported in a single event, even if larger than the specified value up to --bes_outerr_chunk_size.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_outerr_chunk_size"><code id="bes_outerr_chunk_size"><a href="#common_options-flag--bes_outerr_chunk_size">--bes_outerr_chunk_size</a>=<an integer></code> default: "1048576"</dt> -<dd> -<p>Specifies the maximal size of stdout or stderr to be sent to BEP in a single message.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_proxy"><code id="bes_proxy"><a href="#common_options-flag--bes_proxy">--bes_proxy</a>=<a string></code> default: see description</dt> -<dd> -<p>Connect to the Build Event Service through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket).</p> -</dd> -<dt id="common_options-flag--bes_results_url"><code id="bes_results_url"><a href="#common_options-flag--bes_results_url">--bes_results_url</a>=<a string></code> default: ""</dt> -<dd> -<p>Specifies the base URL where a user can view the information streamed to the BES backend. Bazel will output the URL appended by the invocation id to the terminal.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="common_options-flag--bes_system_keywords"><code id="bes_system_keywords"><a href="#common_options-flag--bes_system_keywords">--bes_system_keywords</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies a list of notification keywords to be included directly, without the "user_keyword=" prefix included for keywords supplied via --bes_keywords. Intended for Build service operators that set --bes_lifecycle_events=false and include keywords when calling PublishLifecycleEvent. Build service operators using this flag should prevent users from overriding the flag value.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_timeout"><code id="bes_timeout"><a href="#common_options-flag--bes_timeout">--bes_timeout</a>=<An immutable length of time.></code> default: "0s"</dt> -<dd> -<p>Specifies how long bazel should wait for the BES/BEP upload to complete after the build and tests have finished. A valid timeout is a natural number followed by a unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The default value is '0' which means that there is no timeout.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--bes_upload_mode"><code id="bes_upload_mode"><a href="#common_options-flag--bes_upload_mode">--bes_upload_mode</a>=<wait_for_upload_complete, nowait_for_upload_complete or fully_async></code> default: "wait_for_upload_complete"</dt> -<dd> -<p>Specifies whether the Build Event Service upload should block the build completion or should end the invocation immediately and finish the upload in the background.</p> -<ul> -<li><code>wait_for_upload_complete</code>: blocks at the end of the current invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend.</li> -<li><code>nowait_for_upload_complete</code>: blocks at the beginning of the next invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend.</li> -<li><code>fully_async</code>: blocks at the beginning of the next invocation until all events are uploaded but does not wait for acknowledgements. Events may be lost in case of (transient) failures and backends may report streams as incomplete in this mode. There is no guarantee that <code>FinishInvocationAttempt</code> or <code>FinishBuild</code> lifecycle events are sent.</li> -</ul> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="common_options-flag--build_event_binary_file"><code id="build_event_binary_file"><a href="#common_options-flag--build_event_binary_file">--build_event_binary_file</a>=<a string></code> default: ""</dt> -<dd> -<p>If non-empty, write a varint delimited binary representation of representation of the build event protocol to that file. This option implies --bes_upload_mode=wait_for_upload_complete.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--build_event_binary_file_path_conversion"><code id="build_event_binary_file_path_conversion"><a href="#common_options-flag--build_event_binary_file_path_conversion">--[no]build_event_binary_file_path_conversion</a></code> default: "true"</dt> -<dd> -<p>Convert paths in the binary file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--build_event_binary_file_upload_mode"><code id="build_event_binary_file_upload_mode"><a href="#common_options-flag--build_event_binary_file_upload_mode">--build_event_binary_file_upload_mode</a>=<wait_for_upload_complete, nowait_for_upload_complete or fully_async></code> default: "wait_for_upload_complete"</dt> -<dd> -<p>Specifies whether the Build Event Service upload for --build_event_binary_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="common_options-flag--build_event_json_file"><code id="build_event_json_file"><a href="#common_options-flag--build_event_json_file">--build_event_json_file</a>=<a string></code> default: ""</dt> -<dd> -<p>If non-empty, write a JSON serialisation of the build event protocol to that file. This option implies --bes_upload_mode=wait_for_upload_complete.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--build_event_json_file_path_conversion"><code id="build_event_json_file_path_conversion"><a href="#common_options-flag--build_event_json_file_path_conversion">--[no]build_event_json_file_path_conversion</a></code> default: "true"</dt> -<dd> -<p>Convert paths in the json file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--build_event_json_file_upload_mode"><code id="build_event_json_file_upload_mode"><a href="#common_options-flag--build_event_json_file_upload_mode">--build_event_json_file_upload_mode</a>=<wait_for_upload_complete, nowait_for_upload_complete or fully_async></code> default: "wait_for_upload_complete"</dt> -<dd> -<p>Specifies whether the Build Event Service upload for --build_event_json_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="common_options-flag--build_event_max_named_set_of_file_entries"><code id="build_event_max_named_set_of_file_entries"><a href="#common_options-flag--build_event_max_named_set_of_file_entries">--build_event_max_named_set_of_file_entries</a>=<an integer></code> default: "5000"</dt> -<dd> -<p>The maximum number of entries for a single named_set_of_files event; values smaller than 2 are ignored and no event splitting is performed. This is intended for limiting the maximum event size in the build event protocol, although it does not directly control event size. The total event size is a function of the structure of the set as well as the file and uri lengths, which may in turn depend on the hash function.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--build_event_publish_all_actions"><code id="build_event_publish_all_actions"><a href="#common_options-flag--build_event_publish_all_actions">--[no]build_event_publish_all_actions</a></code> default: "false"</dt> -<dd> -<p>Whether all actions should be published.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--build_event_text_file"><code id="build_event_text_file"><a href="#common_options-flag--build_event_text_file">--build_event_text_file</a>=<a string></code> default: ""</dt> -<dd> -<p>If non-empty, write a textual representation of the build event protocol to that file</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--build_event_text_file_path_conversion"><code id="build_event_text_file_path_conversion"><a href="#common_options-flag--build_event_text_file_path_conversion">--[no]build_event_text_file_path_conversion</a></code> default: "true"</dt> -<dd> -<p>Convert paths in the text file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--build_event_text_file_upload_mode"><code id="build_event_text_file_upload_mode"><a href="#common_options-flag--build_event_text_file_upload_mode">--build_event_text_file_upload_mode</a>=<wait_for_upload_complete, nowait_for_upload_complete or fully_async></code> default: "wait_for_upload_complete"</dt> -<dd> -<p>Specifies whether the Build Event Service upload for --build_event_text_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="common_options-flag--build_event_upload_max_retries"><code id="build_event_upload_max_retries"><a href="#common_options-flag--build_event_upload_max_retries">--build_event_upload_max_retries</a>=<an integer></code> default: "4"</dt> -<dd> -<p>The maximum number of times Bazel should retry uploading a build event.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--experimental_bep_target_summary"><code id="experimental_bep_target_summary"><a href="#common_options-flag--experimental_bep_target_summary">--[no]experimental_bep_target_summary</a></code> default: "false"</dt> -<dd> -<p>Whether to publish TargetSummary events.</p> -</dd> -<dt id="common_options-flag--experimental_build_event_expand_filesets"><code id="experimental_build_event_expand_filesets"><a href="#common_options-flag--experimental_build_event_expand_filesets">--[no]experimental_build_event_expand_filesets</a></code> default: "false"</dt> -<dd> -<p>If true, expand Filesets in the BEP when presenting output files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--experimental_build_event_output_group_mode"><code id="experimental_build_event_output_group_mode"><a href="#common_options-flag--experimental_build_event_output_group_mode">--experimental_build_event_output_group_mode</a>=<an output group name followed by an OutputGroupFileMode, e.g. default=both></code> multiple uses are accumulated</dt> -<dd> -<p>Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED_SET_OF_FILES_ONLY', 'INLINE_ONLY', or 'BOTH'. The default value is 'NAMED_SET_OF_FILES_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental_build_event_output_group_mode=baseline.lcov=both</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--experimental_build_event_upload_retry_minimum_delay"><code id="experimental_build_event_upload_retry_minimum_delay"><a href="#common_options-flag--experimental_build_event_upload_retry_minimum_delay">--experimental_build_event_upload_retry_minimum_delay</a>=<An immutable length of time.></code> default: "1s"</dt> -<dd> -<p>Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6)</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--experimental_build_event_upload_strategy"><code id="experimental_build_event_upload_strategy"><a href="#common_options-flag--experimental_build_event_upload_strategy">--experimental_build_event_upload_strategy</a>=<a string></code> default: see description</dt> -<dd> -<p>Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--experimental_collect_load_average_in_profiler"><code id="experimental_collect_load_average_in_profiler"><a href="#common_options-flag--experimental_collect_load_average_in_profiler">--[no]experimental_collect_load_average_in_profiler</a></code> default: "true"</dt> -<dd> -<p>If enabled, the profiler collects the system's overall load average.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_collect_pressure_stall_indicators"><code id="experimental_collect_pressure_stall_indicators"><a href="#common_options-flag--experimental_collect_pressure_stall_indicators">--[no]experimental_collect_pressure_stall_indicators</a></code> default: "false"</dt> -<dd> -<p>If enabled, the profiler collects the Linux PSI data.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_collect_resource_estimation"><code id="experimental_collect_resource_estimation"><a href="#common_options-flag--experimental_collect_resource_estimation">--[no]experimental_collect_resource_estimation</a></code> default: "false"</dt> -<dd> -<p>If enabled, the profiler collects CPU and memory usage estimation for local actions.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_collect_skyframe_counts_in_profiler"><code id="experimental_collect_skyframe_counts_in_profiler"><a href="#common_options-flag--experimental_collect_skyframe_counts_in_profiler">--[no]experimental_collect_skyframe_counts_in_profiler</a></code> default: "false"</dt> -<dd> -<p>If enabled, the profiler collects SkyFunction counts in the Skyframe graph over time for key function types, like configured targets and action executions. May have a performance hit as this visits the ENTIRE Skyframe graph at every profiling time unit. Do not use this flag with performance-critical measurements.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_collect_system_network_usage"><code id="experimental_collect_system_network_usage"><a href="#common_options-flag--experimental_collect_system_network_usage">--[no]experimental_collect_system_network_usage</a></code> default: "true"</dt> -<dd> -<p>If enabled, the profiler collects the system's network usage.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_collect_worker_data_in_profiler"><code id="experimental_collect_worker_data_in_profiler"><a href="#common_options-flag--experimental_collect_worker_data_in_profiler">--[no]experimental_collect_worker_data_in_profiler</a></code> default: "true"</dt> -<dd> -<p>If enabled, the profiler collects worker's aggregated resource data.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_command_profile"><code id="experimental_command_profile"><a href="#common_options-flag--experimental_command_profile">--experimental_command_profile</a>=<cpu, wall, alloc or lock></code> default: see description</dt> -<dd> -<p>Records a Java Flight Recorder profile for the duration of the command. One of the supported profiling event types (cpu, wall, alloc or lock) must be given as an argument. The profile is written to a file named after the event type under the output base directory. The syntax and semantics of this flag might change in the future to support additional profile types or output formats; use at your own risk.</p> -</dd> -<dt id="common_options-flag--experimental_profile_additional_tasks"><code id="experimental_profile_additional_tasks"><a href="#common_options-flag--experimental_profile_additional_tasks">--experimental_profile_additional_tasks</a>=<phase, action, discover_inputs, action_check, action_lock, action_update, action_complete, action_rewinding, bzlmod, info, create_package, remote_execution, local_execution, scanner, local_parse, upload_time, remote_process_time, remote_queue, remote_setup, fetch, local_process_time, vfs_stat, vfs_dir, vfs_readlink, vfs_md5, vfs_xattr, vfs_delete, vfs_open, vfs_read, vfs_write, vfs_glob, vfs_vmfs_stat, vfs_vmfs_dir, vfs_vmfs_read, wait, thread_name, thread_sort_index, skyframe_eval, skyfunction, critical_path, critical_path_component, handle_gc_notification, local_action_counts, starlark_parser, starlark_user_fn, starlark_builtin_fn, starlark_user_compiled_fn, starlark_repository_fn, action_fs_staging, remote_cache_check, remote_download, remote_network, filesystem_traversal, worker_execution, worker_setup, worker_borrow, worker_working, worker_copying_outputs, credential_helper, conflict_check, dynamic_lock, repository_fetch, repository_vendor, repo_cache_gc_wait, spawn_log, rpc, skycache, wasm_load, wasm_exec or unknown></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional profile tasks to be included in the profile.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_profile_include_primary_output"><code id="experimental_profile_include_primary_output"><a href="#common_options-flag--experimental_profile_include_primary_output">--[no]experimental_profile_include_primary_output</a></code> default: "false"</dt> -<dd> -<p>Includes the extra "out" attribute in action events that contains the exec path to the action's primary output.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_profile_include_target_configuration"><code id="experimental_profile_include_target_configuration"><a href="#common_options-flag--experimental_profile_include_target_configuration">--[no]experimental_profile_include_target_configuration</a></code> default: "false"</dt> -<dd> -<p>Includes target configuration hash in action events' JSON profile data.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_profile_include_target_label"><code id="experimental_profile_include_target_label"><a href="#common_options-flag--experimental_profile_include_target_label">--[no]experimental_profile_include_target_label</a></code> default: "false"</dt> -<dd> -<p>Includes target label in action events' JSON profile data.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_record_metrics_for_all_mnemonics"><code id="experimental_record_metrics_for_all_mnemonics"><a href="#common_options-flag--experimental_record_metrics_for_all_mnemonics">--[no]experimental_record_metrics_for_all_mnemonics</a></code> default: "false"</dt> -<dd> -<p>Controls the output of BEP ActionSummary and BuildGraphMetrics, limiting the number of mnemonics in ActionData and number of entries reported in BuildGraphMetrics.AspectCount/RuleClassCount. By default the number of types is limited to the top 20, by number of executed actions for ActionData, and instances for RuleClass and Asepcts. Setting this option will write statistics for all mnemonics, rule classes and aspects.</p> -</dd> -<dt id="common_options-flag--experimental_record_skyframe_metrics"><code id="experimental_record_skyframe_metrics"><a href="#common_options-flag--experimental_record_skyframe_metrics">--[no]experimental_record_skyframe_metrics</a></code> default: "false"</dt> -<dd> -<p>Controls the output of BEP BuildGraphMetrics, including expensiveto compute skyframe metrics about Skykeys, RuleClasses and Aspects.With this flag set to false BuildGraphMetrics.rule_count and aspectfields will not be populated in the BEP.</p> -</dd> -<dt id="common_options-flag--experimental_run_bep_event_include_residue"><code id="experimental_run_bep_event_include_residue"><a href="#common_options-flag--experimental_run_bep_event_include_residue">--[no]experimental_run_bep_event_include_residue</a></code> default: "false"</dt> -<dd> -<p>Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--experimental_stream_log_file_uploads"><code id="experimental_stream_log_file_uploads"><a href="#common_options-flag--experimental_stream_log_file_uploads">--[no]experimental_stream_log_file_uploads</a></code> default: "false"</dt> -<dd> -<p>Stream log file uploads directly to the remote storage rather than writing them to disk.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--experimental_workspace_rules_log_file"><code id="experimental_workspace_rules_log_file"><a href="#common_options-flag--experimental_workspace_rules_log_file">--experimental_workspace_rules_log_file</a>=<a path></code> default: see description</dt> -<dd> -<p>Log certain Workspace Rules events into this file as delimited WorkspaceEvent protos.</p> -</dd> -<dt id="common_options-flag--generate_json_trace_profile"><code id="generate_json_trace_profile"><a href="#common_options-flag--generate_json_trace_profile">--[no]generate_json_trace_profile</a></code> default: "auto"</dt> -<dd> -<p>If enabled, Bazel profiles the build and writes a JSON-format profile into a file in the output base. View profile by loading into chrome://tracing. By default Bazel writes the profile for all build-like commands and query.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--heap_dump_on_oom"><code id="heap_dump_on_oom"><a href="#common_options-flag--heap_dump_on_oom">--[no]heap_dump_on_oom</a></code> default: "false"</dt> -<dd> -<p>Whether to manually output a heap dump if an OOM is thrown (including manual OOMs due to reaching --gc_thrashing_limits). The dump will be written to <output_base>/<invocation_id>.heapdump.hprof. This option effectively replaces -XX:+HeapDumpOnOutOfMemoryError, which has no effect for manual OOMs.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--jvm_heap_histogram_internal_object_pattern"><code id="jvm_heap_histogram_internal_object_pattern"><a href="#common_options-flag--jvm_heap_histogram_internal_object_pattern">--jvm_heap_histogram_internal_object_pattern</a>=<a valid Java regular expression></code> default: "jdk\.internal\.vm\.Filler.+"</dt> -<dd> -<p>Regex for overriding the matching logic for JDK21+ JVM heap memory collection. We are relying on volatile internal G1 GC implemenation details to get a clean memory metric, this option allows us to adapt to changes in that internal implementation without having to wait for a binary release. Passed to JDK Matcher.find()</p> -</dd> -<dt id="common_options-flag--legacy_important_outputs"><code id="legacy_important_outputs"><a href="#common_options-flag--legacy_important_outputs">--[no]legacy_important_outputs</a></code> default: "false"</dt> -<dd> -<p>Use this to suppress generation of the legacy important_outputs field in the TargetComplete event. important_outputs are required for Bazel to ResultStore/BTX integration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--logging"><code id="logging"><a href="#common_options-flag--logging">--logging</a>=<0 <= an integer <= 6></code> default: "3"</dt> -<dd> -<p>The logging level.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--memory_profile"><code id="memory_profile"><a href="#common_options-flag--memory_profile">--memory_profile</a>=<a path></code> default: see description</dt> -<dd> -<p>If set, write memory usage data to the specified file at phase ends and stable heap to master log at end of build.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--memory_profile_stable_heap_parameters"><code id="memory_profile_stable_heap_parameters"><a href="#common_options-flag--memory_profile_stable_heap_parameters">--memory_profile_stable_heap_parameters</a>=<integers, separated by a comma expected in pairs></code> default: "1,0"</dt> -<dd> -<p>Tune memory profile's computation of stable heap at end of build. Should be and even number of integers separated by commas. In each pair the first integer is the number of GCs to perform. The second integer in each pair is the number of seconds to wait between GCs. Ex: 2,4,4,0 would 2 GCs with a 4sec pause, followed by 4 GCs with zero second pause</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--profile"><code id="profile"><a href="#common_options-flag--profile">--profile</a>=<a path></code> default: see description</dt> -<dd> -<p>If set, profile Bazel and write data to the specified file. See https://bazel.build/advanced/performance/json-trace-profile for more information.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--profiles_to_retain"><code id="profiles_to_retain"><a href="#common_options-flag--profiles_to_retain">--profiles_to_retain</a>=<an integer></code> default: "5"</dt> -<dd> -<p>Number of profiles to retain in the output base. If there are more than this number of profiles in the output base, the oldest are deleted until the total is under the limit.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--record_full_profiler_data"><code id="record_full_profiler_data"><a href="#common_options-flag--record_full_profiler_data">--[no]record_full_profiler_data</a></code> default: "false"</dt> -<dd> -<p>By default, Bazel profiler will record only aggregated data for fast but numerous events (such as statting the file). If this option is enabled, profiler will record each event - resulting in more precise profiling data but LARGE performance hit. Option only has effect if --profile used as well.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--redirect_local_instrumentation_output_writes"><code id="redirect_local_instrumentation_output_writes"><a href="#common_options-flag--redirect_local_instrumentation_output_writes">--[no]redirect_local_instrumentation_output_writes</a></code> default: "false"</dt> -<dd> -<p>If true and supported, instrumentation output is redirected to be written locally on a different machine than where bazel is running on.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--remote_print_execution_messages"><code id="remote_print_execution_messages"><a href="#common_options-flag--remote_print_execution_messages">--remote_print_execution_messages</a>=<failure, success or all></code> default: "failure"</dt> -<dd> -<p>Choose when to print remote execution messages. Valid values are <code>failure</code>, to print only on failures, <code>success</code> to print only on successes and <code>all</code> to print always.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="common_options-flag--slim_profile"><code id="slim_profile"><a href="#common_options-flag--slim_profile">--[no]slim_profile</a></code> default: "true"</dt> -<dd> -<p>Slims down the size of the JSON profile by merging events if the profile gets too large.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--starlark_cpu_profile"><code id="starlark_cpu_profile"><a href="#common_options-flag--starlark_cpu_profile">--starlark_cpu_profile</a>=<a string></code> default: ""</dt> -<dd> -<p>Writes into the specified file a pprof profile of CPU usage by all Starlark threads.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--tool_tag"><code id="tool_tag"><a href="#common_options-flag--tool_tag">--tool_tag</a>=<a string></code> default: ""</dt> -<dd> -<p>A tool name to attribute this Bazel invocation to.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--ui_event_filters"><code id="ui_event_filters"><a href="#common_options-flag--ui_event_filters">--ui_event_filters</a>=<Convert list of comma separated event kind to list of filters></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies which events to show in the UI. It is possible to add or remove events to the default ones using leading +/-, or override the default set completely with direct assignment. The set of supported event kinds include INFO, DEBUG, ERROR and more.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="common_options-flag--write_command_log"><code id="write_command_log"><a href="#common_options-flag--write_command_log">--[no]write_command_log</a></code> default: "false"</dt> -<dd> -<p>Whether or not to write the command.log file</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -</dl> -<dl>Remote caching and execution options: -<dt id="common_options-flag--downloader_config"><code id="downloader_config"><a href="#common_options-flag--downloader_config">--downloader_config</a>=<a path></code> default: see description</dt> -<dd> -<p>Specify a file to configure the remote downloader with. This file consists of lines, each of which starts with a directive (<code>allow</code>, <code>block</code> or <code>rewrite</code>) followed by either a host name (for <code>allow</code> and <code>block</code>) or two patterns, one to match against, and one to use as a substitute URL, with back-references starting from <code>$1</code>. It is possible for multiple <code>rewrite</code> directives for the same URL to be given, and in this case multiple URLs will be returned.</p> -</dd> -<dt id="common_options-flag--experimental_circuit_breaker_strategy"><code id="experimental_circuit_breaker_strategy"><a href="#common_options-flag--experimental_circuit_breaker_strategy">--experimental_circuit_breaker_strategy</a>=<failure></code> default: see description</dt> -<dd> -<p>Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="common_options-flag--experimental_remote_cache_compression_threshold"><code id="experimental_remote_cache_compression_threshold"><a href="#common_options-flag--experimental_remote_cache_compression_threshold">--experimental_remote_cache_compression_threshold</a>=<an integer></code> default: "100"</dt> -<dd> -<p>The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote_cache_compression is set.</p> -</dd> -<dt id="common_options-flag--experimental_remote_cache_lease_extension"><code id="experimental_remote_cache_lease_extension"><a href="#common_options-flag--experimental_remote_cache_lease_extension">--[no]experimental_remote_cache_lease_extension</a></code> default: "false"</dt> -<dd> -<p>If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending <code>FindMissingBlobs</code> calls periodically to remote cache. The frequency is based on the value of <code>--experimental_remote_cache_ttl</code>.</p> -</dd> -<dt id="common_options-flag--experimental_remote_cache_ttl"><code id="experimental_remote_cache_ttl"><a href="#common_options-flag--experimental_remote_cache_ttl">--experimental_remote_cache_ttl</a>=<An immutable length of time.></code> default: "3h"</dt> -<dd> -<p>The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="common_options-flag--experimental_remote_capture_corrupted_outputs"><code id="experimental_remote_capture_corrupted_outputs"><a href="#common_options-flag--experimental_remote_capture_corrupted_outputs">--experimental_remote_capture_corrupted_outputs</a>=<a path></code> default: see description</dt> -<dd> -<p>A path to a directory where the corrupted outputs will be captured to.</p> -</dd> -<dt id="common_options-flag--experimental_remote_discard_merkle_trees"><code id="experimental_remote_discard_merkle_trees"><a href="#common_options-flag--experimental_remote_discard_merkle_trees">--[no]experimental_remote_discard_merkle_trees</a></code> default: "true"</dt> -<dd> -<p>If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries.</p> -</dd> -<dt id="common_options-flag--experimental_remote_downloader"><code id="experimental_remote_downloader"><a href="#common_options-flag--experimental_remote_downloader">--experimental_remote_downloader</a>=<a string></code> default: see description</dt> -<dd> -<p>A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote_asset.proto</p> -</dd> -<dt id="common_options-flag--experimental_remote_downloader_local_fallback"><code id="experimental_remote_downloader_local_fallback"><a href="#common_options-flag--experimental_remote_downloader_local_fallback">--[no]experimental_remote_downloader_local_fallback</a></code> default: "false"</dt> -<dd> -<p>Whether to fall back to the local downloader if remote downloader fails.</p> -</dd> -<dt id="common_options-flag--experimental_remote_downloader_propagate_credentials"><code id="experimental_remote_downloader_propagate_credentials"><a href="#common_options-flag--experimental_remote_downloader_propagate_credentials">--[no]experimental_remote_downloader_propagate_credentials</a></code> default: "false"</dt> -<dd> -<p>Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new <code>http_header_url:&lt;url-index&gt;:&lt;header-key&gt;</code> qualifier where the <code>&lt;url-index&gt;</code> is a 0-based position of the URL inside the FetchBlobRequest's <code>uris</code> field. The URL-specific headers should take precedence over the global headers.</p> -</dd> -<dt id="common_options-flag--experimental_remote_execution_keepalive"><code id="experimental_remote_execution_keepalive"><a href="#common_options-flag--experimental_remote_execution_keepalive">--[no]experimental_remote_execution_keepalive</a></code> default: "false"</dt> -<dd> -<p>Whether to use keepalive for remote execution calls.</p> -</dd> -<dt id="common_options-flag--experimental_remote_failure_rate_threshold"><code id="experimental_remote_failure_rate_threshold"><a href="#common_options-flag--experimental_remote_failure_rate_threshold">--experimental_remote_failure_rate_threshold</a>=<an integer in 0-100 range></code> default: "10"</dt> -<dd> -<p>Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="common_options-flag--experimental_remote_failure_window_interval"><code id="experimental_remote_failure_window_interval"><a href="#common_options-flag--experimental_remote_failure_window_interval">--experimental_remote_failure_window_interval</a>=<An immutable length of time.></code> default: "60s"</dt> -<dd> -<p>The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="common_options-flag--experimental_remote_mark_tool_inputs"><code id="experimental_remote_mark_tool_inputs"><a href="#common_options-flag--experimental_remote_mark_tool_inputs">--[no]experimental_remote_mark_tool_inputs</a></code> default: "false"</dt> -<dd> -<p>If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers.</p> -</dd> -<dt id="common_options-flag--experimental_remote_merkle_tree_cache"><code id="experimental_remote_merkle_tree_cache"><a href="#common_options-flag--experimental_remote_merkle_tree_cache">--[no]experimental_remote_merkle_tree_cache</a></code> default: "false"</dt> -<dd> -<p>If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental_remote_merkle_tree_cache_size.</p> -</dd> -<dt id="common_options-flag--experimental_remote_merkle_tree_cache_size"><code id="experimental_remote_merkle_tree_cache_size"><a href="#common_options-flag--experimental_remote_merkle_tree_cache_size">--experimental_remote_merkle_tree_cache_size</a>=<a long integer></code> default: "1000"</dt> -<dd> -<p>The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000.</p> -</dd> -<dt id="common_options-flag--experimental_remote_output_service"><code id="experimental_remote_output_service"><a href="#common_options-flag--experimental_remote_output_service">--experimental_remote_output_service</a>=<a string></code> default: see description</dt> -<dd> -<p>HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS.</p> -</dd> -<dt id="common_options-flag--experimental_remote_output_service_output_path_prefix"><code id="experimental_remote_output_service_output_path_prefix"><a href="#common_options-flag--experimental_remote_output_service_output_path_prefix">--experimental_remote_output_service_output_path_prefix</a>=<a string></code> default: ""</dt> -<dd> -<p>The path under which the contents of output directories managed by the --experimental_remote_output_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service.</p> -</dd> -<dt id="common_options-flag--experimental_remote_require_cached"><code id="experimental_remote_require_cached"><a href="#common_options-flag--experimental_remote_require_cached">--[no]experimental_remote_require_cached</a></code> default: "false"</dt> -<dd> -<p>If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache.</p> -</dd> -<dt id="common_options-flag--experimental_remote_scrubbing_config"><code id="experimental_remote_scrubbing_config"><a href="#common_options-flag--experimental_remote_scrubbing_config">--experimental_remote_scrubbing_config</a>=<Converts to a Scrubber></code> default: see description</dt> -<dd> -<p>Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote_scrubbing.proto).</p> -<p>This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds.</p> -<p>Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead.</p> -<p>Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions.</p> -<p>In order to successfully use this feature, you likely want to set a custom --host_platform together with --experimental_platform_in_output_dir (to normalize output prefixes) and --incompatible_strict_action_env (to normalize environment variables).</p> -</dd> -<dt id="common_options-flag--guard_against_concurrent_changes"><code id="guard_against_concurrent_changes"><a href="#common_options-flag--guard_against_concurrent_changes">--[no]guard_against_concurrent_changes</a></code> default: "lite"</dt> -<dd> -<p>Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="common_options-flag--remote_accept_cached"><code id="remote_accept_cached"><a href="#common_options-flag--remote_accept_cached">--[no]remote_accept_cached</a></code> default: "true"</dt> -<dd> -<p>Whether to accept remotely cached action results.</p> -</dd> -<dt id="common_options-flag--remote_build_event_upload"><code id="remote_build_event_upload"><a href="#common_options-flag--remote_build_event_upload">--remote_build_event_upload</a>=<all or minimal></code> default: "minimal"</dt> -<dd> -<p>If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. -If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. -Default to 'minimal'.</p> -</dd> -<dt id="common_options-flag--remote_bytestream_uri_prefix"><code id="remote_bytestream_uri_prefix"><a href="#common_options-flag--remote_bytestream_uri_prefix">--remote_bytestream_uri_prefix</a>=<a string></code> default: see description</dt> -<dd> -<p>The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote_executor and --remote_instance_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "${hostname}/${instance_name}".</p> -</dd> -<dt id="common_options-flag--remote_cache"><code id="remote_cache"><a href="#common_options-flag--remote_cache">--remote_cache</a>=<a string></code> default: see description</dt> -<dd> -<p>A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching</p> -</dd> -<dt id="common_options-flag--remote_cache_async"><code id="remote_cache_async"><a href="#common_options-flag--remote_cache_async">--[no]remote_cache_async</a></code> default: "true"</dt> -<dd> -<p>If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set.</p> -</dd> -<dt id="common_options-flag--remote_cache_compression"><code id="remote_cache_compression"><a href="#common_options-flag--remote_cache_compression">--[no]remote_cache_compression</a></code> default: "false"</dt> -<dd> -<p>If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental_remote_cache_compression_threshold.</p> -</dd> -<dt id="common_options-flag--remote_cache_header"><code id="remote_cache_header"><a href="#common_options-flag--remote_cache_header">--remote_cache_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header that will be included in cache requests: --remote_cache_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -</dd> -<dt id="common_options-flag--remote_default_exec_properties"><code id="remote_default_exec_properties"><a href="#common_options-flag--remote_default_exec_properties">--remote_default_exec_properties</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec_properties.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--remote_default_platform_properties"><code id="remote_default_platform_properties"><a href="#common_options-flag--remote_default_platform_properties">--remote_default_platform_properties</a>=<a string></code> default: ""</dt> -<dd> -<p>Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote_execution_properties. This value will also be used if the host platform is selected as the execution platform for remote execution.</p> -</dd> -<dt id="common_options-flag--remote_download_regex"><code id="remote_download_regex"><a href="#common_options-flag--remote_download_regex">--remote_download_regex</a>=<a valid Java regular expression></code> multiple uses are accumulated</dt> -<dd> -<p>Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote_download_outputs. Multiple patterns may be specified by repeating this flag.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="common_options-flag--remote_downloader_header"><code id="remote_downloader_header"><a href="#common_options-flag--remote_downloader_header">--remote_downloader_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header that will be included in remote downloader requests: --remote_downloader_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -</dd> -<dt id="common_options-flag--remote_exec_header"><code id="remote_exec_header"><a href="#common_options-flag--remote_exec_header">--remote_exec_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header that will be included in execution requests: --remote_exec_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -</dd> -<dt id="common_options-flag--remote_execution_priority"><code id="remote_execution_priority"><a href="#common_options-flag--remote_execution_priority">--remote_execution_priority</a>=<an integer></code> default: "0"</dt> -<dd> -<p>The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent.</p> -</dd> -<dt id="common_options-flag--remote_executor"><code id="remote_executor"><a href="#common_options-flag--remote_executor">--remote_executor</a>=<a string></code> default: see description</dt> -<dd> -<p>HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS.</p> -</dd> -<dt id="common_options-flag--remote_grpc_log"><code id="remote_grpc_log"><a href="#common_options-flag--remote_grpc_log">--remote_grpc_log</a>=<a path></code> default: see description</dt> -<dd> -<p>If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream).</p> -</dd> -<dt id="common_options-flag--remote_header"><code id="remote_header"><a href="#common_options-flag--remote_header">--remote_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header that will be included in requests: --remote_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -</dd> -<dt id="common_options-flag--remote_instance_name"><code id="remote_instance_name"><a href="#common_options-flag--remote_instance_name">--remote_instance_name</a>=<a string></code> default: ""</dt> -<dd> -<p>Value to pass as instance_name in the remote execution API.</p> -</dd> -<dt id="common_options-flag--remote_local_fallback"><code id="remote_local_fallback"><a href="#common_options-flag--remote_local_fallback">--[no]remote_local_fallback</a></code> default: "false"</dt> -<dd> -<p>Whether to fall back to standalone local execution strategy if remote execution fails.</p> -</dd> -<dt id="common_options-flag--remote_local_fallback_strategy"><code id="remote_local_fallback_strategy"><a href="#common_options-flag--remote_local_fallback_strategy">--remote_local_fallback_strategy</a>=<a string></code> default: "local"</dt> -<dd> -<p>Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details.</p> -</dd> -<dt id="common_options-flag--remote_max_connections"><code id="remote_max_connections"><a href="#common_options-flag--remote_max_connections">--remote_max_connections</a>=<an integer></code> default: "100"</dt> -<dd> -<p>Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. -For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote_max_connections concurrent requests. -For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around <code>--remote_max_connections * 100</code> concurrent requests.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--remote_proxy"><code id="remote_proxy"><a href="#common_options-flag--remote_proxy">--remote_proxy</a>=<a string></code> default: see description</dt> -<dd> -<p>Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket).</p> -</dd> -<dt id="common_options-flag--remote_result_cache_priority"><code id="remote_result_cache_priority"><a href="#common_options-flag--remote_result_cache_priority">--remote_result_cache_priority</a>=<an integer></code> default: "0"</dt> -<dd> -<p>The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent.</p> -</dd> -<dt id="common_options-flag--remote_retries"><code id="remote_retries"><a href="#common_options-flag--remote_retries">--remote_retries</a>=<an integer></code> default: "5"</dt> -<dd> -<p>The maximum number of attempts to retry a transient error. If set to 0, retries are disabled.</p> -</dd> -<dt id="common_options-flag--remote_retry_max_delay"><code id="remote_retry_max_delay"><a href="#common_options-flag--remote_retry_max_delay">--remote_retry_max_delay</a>=<An immutable length of time.></code> default: "5s"</dt> -<dd> -<p>The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> -</dd> -<dt id="common_options-flag--remote_timeout"><code id="remote_timeout"><a href="#common_options-flag--remote_timeout">--remote_timeout</a>=<An immutable length of time.></code> default: "60s"</dt> -<dd> -<p>The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> -</dd> -<dt id="common_options-flag--remote_upload_local_results"><code id="remote_upload_local_results"><a href="#common_options-flag--remote_upload_local_results">--[no]remote_upload_local_results</a></code> default: "true"</dt> -<dd> -<p>Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so.</p> -</dd> -<dt id="common_options-flag--remote_verify_downloads"><code id="remote_verify_downloads"><a href="#common_options-flag--remote_verify_downloads">--[no]remote_verify_downloads</a></code> default: "true"</dt> -<dd> -<p>If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value.</p> -</dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="common_options-flag--build_metadata"><code id="build_metadata"><a href="#common_options-flag--build_metadata">--build_metadata</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Custom key-value string pairs to supply in a build event.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="common_options-flag--color"><code id="color"><a href="#common_options-flag--color">--color</a>=<yes, no or auto></code> default: "auto"</dt> -<dd> -<p>Use terminal controls to colorize output.</p> -</dd> -<dt id="common_options-flag--config"><code id="config"><a href="#common_options-flag--config">--config</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Selects additional config sections from the rc files; for every <command>, it also pulls in the options from <command>:<config> if such a section exists; if this section doesn't exist in any .rc file, Blaze fails with an error. The config sections and flag combinations they are equivalent to are located in the tools/*.blazerc config files.</p> -</dd> -<dt id="common_options-flag--credential_helper"><code id="credential_helper"><a href="#common_options-flag--credential_helper">--credential_helper</a>=<Path to a credential helper. It may be absolute, relative to the PATH environment variable, or %workspace%-relative. The path be optionally prefixed by a scope followed by an '='. The scope is a domain name, optionally with a single leading '*' wildcard component. A helper applies to URIs matching its scope, with more specific scopes preferred. If a helper has no scope, it applies to every URI.></code> multiple uses are accumulated</dt> -<dd> -<p>Configures a credential helper conforming to the <a href="https://github.com/EngFlow/credential-helper-spec">Credential Helper Specification</a> to use for retrieving authorization credentials for repository fetching, remote caching and execution, and the build event service.</p> -<p>Credentials supplied by a helper take precedence over credentials supplied by <code>--google_default_credentials</code>, <code>--google_credentials</code>, a <code>.netrc</code> file, or the auth parameter to <code>repository_ctx.download()</code> and <code>repository_ctx.download_and_extract()</code>.</p> -<p>May be specified multiple times to set up multiple helpers.</p> -<p>See https://blog.engflow.com/2023/10/09/configuring-bazels-credential-helper/ for instructions.</p> -</dd> -<dt id="common_options-flag--credential_helper_cache_duration"><code id="credential_helper_cache_duration"><a href="#common_options-flag--credential_helper_cache_duration">--credential_helper_cache_duration</a>=<An immutable length of time.></code> default: "30m"</dt> -<dd> -<p>How long to cache credentials for if the credential helper doesn't return an expiration time. Changing the value of this flag clears the cache.</p> -</dd> -<dt id="common_options-flag--credential_helper_timeout"><code id="credential_helper_timeout"><a href="#common_options-flag--credential_helper_timeout">--credential_helper_timeout</a>=<An immutable length of time.></code> default: "10s"</dt> -<dd> -<p>Configures the timeout for a credential helper.</p> -<p>Credential helpers failing to respond within this timeout will fail the invocation.</p> -</dd> -<dt id="common_options-flag--curses"><code id="curses"><a href="#common_options-flag--curses">--curses</a>=<yes, no or auto></code> default: "auto"</dt> -<dd> -<p>Use terminal cursor controls to minimize scrolling output.</p> -</dd> -<dt id="common_options-flag--disk_cache"><code id="disk_cache"><a href="#common_options-flag--disk_cache">--disk_cache</a>=<a path></code> default: see description</dt> -<dd> -<p>A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created.</p> -</dd> -<dt id="common_options-flag--enable_platform_specific_config"><code id="enable_platform_specific_config"><a href="#common_options-flag--enable_platform_specific_config">--[no]enable_platform_specific_config</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel picks up host-OS-specific config lines from bazelrc files. For example, if the host OS is Linux and you run bazel build, Bazel picks up lines starting with build:linux. Supported OS identifiers are linux, macos, windows, freebsd, and openbsd. Enabling this flag is equivalent to using --config=linux on Linux, --config=windows on Windows, etc.</p> -</dd> -<dt id="common_options-flag--experimental_action_cache_gc_idle_delay"><code id="experimental_action_cache_gc_idle_delay"><a href="#common_options-flag--experimental_action_cache_gc_idle_delay">--experimental_action_cache_gc_idle_delay</a>=<An immutable length of time.></code> default: "5m"</dt> -<dd> -<p>How long the server must remain idle before a garbage collection of the action cache is attempted. Ineffectual unless --experimental_action_cache_gc_max_age is nonzero.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--experimental_action_cache_gc_max_age"><code id="experimental_action_cache_gc_max_age"><a href="#common_options-flag--experimental_action_cache_gc_max_age">--experimental_action_cache_gc_max_age</a>=<An immutable length of time.></code> default: "0"</dt> -<dd> -<p>If set to a nonzero value, the action cache will be periodically garbage collected to remove entries older than this age. Garbage collection occurs in the background once the server has become idle, as determined by the --experimental_action_cache_gc_idle_delay and --experimental_action_cache_gc_threshold flags.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--experimental_action_cache_gc_threshold"><code id="experimental_action_cache_gc_threshold"><a href="#common_options-flag--experimental_action_cache_gc_threshold">--experimental_action_cache_gc_threshold</a>=<an integer in 0-100 range></code> default: "10"</dt> -<dd> -<p>The percentage of stale action cache entries required for garbage collection to be triggered. Ineffectual unless --experimental_action_cache_gc_max_age is nonzero.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--experimental_disk_cache_gc_idle_delay"><code id="experimental_disk_cache_gc_idle_delay"><a href="#common_options-flag--experimental_disk_cache_gc_idle_delay">--experimental_disk_cache_gc_idle_delay</a>=<An immutable length of time.></code> default: "5m"</dt> -<dd> -<p>How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental_disk_cache_gc_max_size and/or --experimental_disk_cache_gc_max_age.</p> -</dd> -<dt id="common_options-flag--experimental_disk_cache_gc_max_age"><code id="experimental_disk_cache_gc_max_age"><a href="#common_options-flag--experimental_disk_cache_gc_max_age">--experimental_disk_cache_gc_max_age</a>=<An immutable length of time.></code> default: "0"</dt> -<dd> -<p>If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental_disk_cache_gc_max_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag.</p> -</dd> -<dt id="common_options-flag--experimental_disk_cache_gc_max_size"><code id="experimental_disk_cache_gc_max_size"><a href="#common_options-flag--experimental_disk_cache_gc_max_size">--experimental_disk_cache_gc_max_size</a>=<a size in bytes, optionally followed by a K, M, G or T multiplier></code> default: "0"</dt> -<dd> -<p>If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental_disk_cache_gc_max_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag.</p> -</dd> -<dt id="common_options-flag--experimental_enable_thread_dump"><code id="experimental_enable_thread_dump"><a href="#common_options-flag--experimental_enable_thread_dump">--[no]experimental_enable_thread_dump</a></code> default: "false"</dt> -<dd> -<p>Whether to enable thread dumps. If true, Bazel will dump the state of all threads (including virtual threads) to a file every --experimental_thread_dump_interval, or after action execution being inactive for --experimental_thread_dump_action_execution_inactivity_duration. The dumps will be written to the <output_base>/server/thread_dumps/ directory.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_install_base_gc_max_age"><code id="experimental_install_base_gc_max_age"><a href="#common_options-flag--experimental_install_base_gc_max_age">--experimental_install_base_gc_max_age</a>=<An immutable length of time.></code> default: "30d"</dt> -<dd> -<p>How long an install base must go unused before it's eligible for garbage collection. If nonzero, the server will attempt to garbage collect other install bases when idle.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="common_options-flag--experimental_rule_extension_api"><code id="experimental_rule_extension_api"><a href="#common_options-flag--experimental_rule_extension_api">--[no]experimental_rule_extension_api</a></code> default: "true"</dt> -<dd> -<p>Enable experimental rule extension API and subrule APIs</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="common_options-flag--experimental_thread_dump_action_execution_inactivity_duration"><code id="experimental_thread_dump_action_execution_inactivity_duration"><a href="#common_options-flag--experimental_thread_dump_action_execution_inactivity_duration">--experimental_thread_dump_action_execution_inactivity_duration</a>=<An immutable length of time.></code> default: "0"</dt> -<dd> -<p>Dump the threads when action execution being inactive for this duration. If zero, no thread dumps are written for action execution being inactive.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_thread_dump_interval"><code id="experimental_thread_dump_interval"><a href="#common_options-flag--experimental_thread_dump_interval">--experimental_thread_dump_interval</a>=<An immutable length of time.></code> default: "0"</dt> -<dd> -<p>How often to dump the threads periodically. If zero, no thread dumps are written periodically.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="common_options-flag--experimental_windows_watchfs"><code id="experimental_windows_watchfs"><a href="#common_options-flag--experimental_windows_watchfs">--[no]experimental_windows_watchfs</a></code> default: "false"</dt> -<dd> -<p>If true, experimental Windows support for --watchfs is enabled. Otherwise --watchfsis a non-op on Windows. Make sure to also enable --watchfs.</p> -</dd> -<dt id="common_options-flag--google_auth_scopes"><code id="google_auth_scopes"><a href="#common_options-flag--google_auth_scopes">--google_auth_scopes</a>=<comma-separated list of options></code> default: "https://www.googleapis.com/auth/cloud-platform"</dt> -<dd> -<p>A comma-separated list of Google Cloud authentication scopes.</p> -</dd> -<dt id="common_options-flag--google_credentials"><code id="google_credentials"><a href="#common_options-flag--google_credentials">--google_credentials</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies the file to get authentication credentials from. See https://cloud.google.com/docs/authentication for details.</p> -</dd> -<dt id="common_options-flag--google_default_credentials"><code id="google_default_credentials"><a href="#common_options-flag--google_default_credentials">--[no]google_default_credentials</a></code> default: "false"</dt> -<dd> -<p>Whether to use 'Google Application Default Credentials' for authentication. See https://cloud.google.com/docs/authentication for details. Disabled by default.</p> -</dd> -<dt id="common_options-flag--grpc_keepalive_time"><code id="grpc_keepalive_time"><a href="#common_options-flag--grpc_keepalive_time">--grpc_keepalive_time</a>=<An immutable length of time.></code> default: see description</dt> -<dd> -<p>Configures keep-alive pings for outgoing gRPC connections. If this is set, then Bazel sends pings after this much time of no read operations on the connection, but only if there is at least one pending gRPC call. Times are treated as second granularity; it is an error to set a value less than one second. By default, keep-alive pings are disabled. You should coordinate with the service owner before enabling this setting. For example to set a value of 30 seconds to this flag, it should be done as this --grpc_keepalive_time=30s</p> -</dd> -<dt id="common_options-flag--grpc_keepalive_timeout"><code id="grpc_keepalive_timeout"><a href="#common_options-flag--grpc_keepalive_timeout">--grpc_keepalive_timeout</a>=<An immutable length of time.></code> default: "20s"</dt> -<dd> -<p>Configures a keep-alive timeout for outgoing gRPC connections. If keep-alive pings are enabled with --grpc_keepalive_time, then Bazel times out a connection if it does not receive a ping reply after this much time. Times are treated as second granularity; it is an error to set a value less than one second. If keep-alive pings are disabled, then this setting is ignored.</p> -</dd> -<dt id="common_options-flag--incompatible_disable_non_executable_java_binary"><code id="incompatible_disable_non_executable_java_binary"><a href="#common_options-flag--incompatible_disable_non_executable_java_binary">--[no]incompatible_disable_non_executable_java_binary</a></code> default: "false"</dt> -<dd> -<p>If true, java_binary is always executable. create_executable attribute is removed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--incompatible_repo_env_ignores_action_env"><code id="incompatible_repo_env_ignores_action_env"><a href="#common_options-flag--incompatible_repo_env_ignores_action_env">--[no]incompatible_repo_env_ignores_action_env</a></code> default: "true"</dt> -<dd> -<p>If true, <code>--action_env=NAME=VALUE</code> will no longer affect repository rule and module extension environments.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="common_options-flag--inject_repository"><code id="inject_repository"><a href="#common_options-flag--inject_repository">--inject_repository</a>=<an equals-separated mapping of repository name to path></code> multiple uses are accumulated</dt> -<dd> -<p>Adds a new repository with a local path in the form of <repository name>=<path>. This only takes effect with --enable_bzlmod and is equivalent to adding a corresponding <code>local_repository</code> to the root module's MODULE.bazel file via <code>use_repo_rule</code>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%', it is relative to the workspace root, which is the output of <code>bazel info workspace</code>. If the given path is empty, then remove any previous injections.</p> -</dd> -<dt id="common_options-flag--invocation_id"><code id="invocation_id"><a href="#common_options-flag--invocation_id">--invocation_id</a>=<a UUID></code> default: ""</dt> -<dd> -<p>Unique identifier, in UUID format, for the command being run. If explicitly specified uniqueness must be ensured by the caller. The UUID is printed to stderr, the BEP and remote execution protocol.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="common_options-flag--override_repository"><code id="override_repository"><a href="#common_options-flag--override_repository">--override_repository</a>=<an equals-separated mapping of repository name to path></code> multiple uses are accumulated</dt> -<dd> -<p>Override a repository with a local path in the form of <repository name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of <code>bazel info workspace</code>. If the given path is empty, then remove any previous overrides.</p> -</dd> -<dt id="common_options-flag--progress_in_terminal_title"><code id="progress_in_terminal_title"><a href="#common_options-flag--progress_in_terminal_title">--[no]progress_in_terminal_title</a></code> default: "false"</dt> -<dd> -<p>Show the command progress in the terminal title. Useful to see what bazel is doing when having multiple terminal tabs.</p> -</dd> -<dt id="common_options-flag--show_progress"><code id="show_progress"><a href="#common_options-flag--show_progress">--[no]show_progress</a></code> default: "true"</dt> -<dd> -<p>Display progress messages during a build.</p> -</dd> -<dt id="common_options-flag--show_progress_rate_limit"><code id="show_progress_rate_limit"><a href="#common_options-flag--show_progress_rate_limit">--show_progress_rate_limit</a>=<a double></code> default: "0.2"</dt> -<dd> -<p>Minimum number of seconds between progress messages in the output.</p> -</dd> -<dt id="common_options-flag--show_timestamps"><code id="show_timestamps"><a href="#common_options-flag--show_timestamps">--[no]show_timestamps</a></code> default: "false"</dt> -<dd> -<p>Include timestamps in messages</p> -</dd> -<dt id="common_options-flag--tls_certificate"><code id="tls_certificate"><a href="#common_options-flag--tls_certificate">--tls_certificate</a>=<a string></code> default: see description</dt> -<dd> -<p>Specify a path to a TLS certificate that is trusted to sign server certificates.</p> -</dd> -<dt id="common_options-flag--tls_client_certificate"><code id="tls_client_certificate"><a href="#common_options-flag--tls_client_certificate">--tls_client_certificate</a>=<a string></code> default: see description</dt> -<dd> -<p>Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication.</p> -</dd> -<dt id="common_options-flag--tls_client_key"><code id="tls_client_key"><a href="#common_options-flag--tls_client_key">--tls_client_key</a>=<a string></code> default: see description</dt> -<dd> -<p>Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication.</p> -</dd> -<dt id="common_options-flag--ui_actions_shown"><code id="ui_actions_shown"><a href="#common_options-flag--ui_actions_shown">--ui_actions_shown</a>=<an integer></code> default: "8"</dt> -<dd> -<p>Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="common_options-flag--watchfs"><code id="watchfs"><a href="#common_options-flag--watchfs">--[no]watchfs</a></code> default: "false"</dt> -<dd> -<p>On Linux/macOS: If true, bazel tries to use the operating system's file watch service for local changes instead of scanning every file for a change. On Windows: this flag currently is a non-op but can be enabled in conjunction with --experimental_windows_watchfs. On any OS: The behavior is undefined if your workspace is on a network file system, and files are edited on a remote machine.</p> -</dd> -</dl> - -<h2><a name="aquery">Aquery Options</a></h2> -<p>Inherits all options from <a href="#build">build</a>.</p> - -<dl>Options relating to query output and semantics: -<dt id="aquery-flag--aspect_deps"><code id="aspect_deps"><a href="#aquery-flag--aspect_deps">--aspect_deps</a>=<off, conservative or precise></code> default: "conservative"</dt> -<dd> -<p>How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="aquery-flag--consistent_labels"><code id="consistent_labels"><a href="#aquery-flag--consistent_labels">--[no]consistent_labels</a></code> default: "false"</dt> -<dd> -<p>If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--experimental_explicit_aspects"><code id="experimental_explicit_aspects"><a href="#aquery-flag--experimental_explicit_aspects">--[no]experimental_explicit_aspects</a></code> default: "false"</dt> -<dd> -<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--graph:factored"><code id="graph:factored"><a href="#aquery-flag--graph:factored">--[no]graph:factored</a></code> default: "true"</dt> -<dd> -<p>If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--graph:node_limit"><code id="graph:node_limit"><a href="#aquery-flag--graph:node_limit">--graph:node_limit</a>=<an integer></code> default: "512"</dt> -<dd> -<p>The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--implicit_deps"><code id="implicit_deps"><a href="#aquery-flag--implicit_deps">--[no]implicit_deps</a></code> default: "true"</dt> -<dd> -<p>If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="aquery-flag--include_artifacts"><code id="include_artifacts"><a href="#aquery-flag--include_artifacts">--[no]include_artifacts</a></code> default: "true"</dt> -<dd> -<p>Includes names of the action inputs and outputs in the output (potentially large).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--include_aspects"><code id="include_aspects"><a href="#aquery-flag--include_aspects">--[no]include_aspects</a></code> default: "true"</dt> -<dd> -<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--include_commandline"><code id="include_commandline"><a href="#aquery-flag--include_commandline">--[no]include_commandline</a></code> default: "true"</dt> -<dd> -<p>Includes the content of the action command lines in the output (potentially large).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--include_file_write_contents"><code id="include_file_write_contents"><a href="#aquery-flag--include_file_write_contents">--[no]include_file_write_contents</a></code> default: "false"</dt> -<dd> -<p>Include the file contents for the FileWrite, SourceSymlinkManifest, and RepoMappingManifest actions (potentially large).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--include_param_files"><code id="include_param_files"><a href="#aquery-flag--include_param_files">--[no]include_param_files</a></code> default: "false"</dt> -<dd> -<p>Include the content of the param files used in the command (potentially large). Note: Enabling this flag will automatically enable the --include_commandline flag.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--include_pruned_inputs"><code id="include_pruned_inputs"><a href="#aquery-flag--include_pruned_inputs">--[no]include_pruned_inputs</a></code> default: "true"</dt> -<dd> -<p>Includes action inputs that were pruned during action execution. Only affects actions that discover inputs and have been executed in a previous invocation. Only takes effect if --include_artifacts is also set.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--incompatible_package_group_includes_double_slash"><code id="incompatible_package_group_includes_double_slash"><a href="#aquery-flag--incompatible_package_group_includes_double_slash">--[no]incompatible_package_group_includes_double_slash</a></code> default: "true"</dt> -<dd> -<p>If enabled, when outputting package_group's <code>packages</code> attribute, the leading <code>//</code> will not be omitted.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="aquery-flag--infer_universe_scope"><code id="infer_universe_scope"><a href="#aquery-flag--infer_universe_scope">--[no]infer_universe_scope</a></code> default: "false"</dt> -<dd> -<p>If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.<code>allrdeps</code>) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to <code>query</code> (i.e. not <code>cquery</code>).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="aquery-flag--line_terminator_null"><code id="line_terminator_null"><a href="#aquery-flag--line_terminator_null">--[no]line_terminator_null</a></code> default: "false"</dt> -<dd> -<p>Whether each format is terminated with \0 instead of newline.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--nodep_deps"><code id="nodep_deps"><a href="#aquery-flag--nodep_deps">--[no]nodep_deps</a></code> default: "true"</dt> -<dd> -<p>If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of <code>info build-language</code> to learn about all the "nodep" attributes in the build language.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="aquery-flag--output"><code id="output"><a href="#aquery-flag--output">--output</a>=<a string></code> default: "text"</dt> -<dd> -<p>The format in which the aquery results should be printed. Allowed values for aquery are: text, textproto, proto, streamed_proto, jsonproto.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--output_file"><code id="output_file"><a href="#aquery-flag--output_file">--output_file</a>=<a string></code> default: ""</dt> -<dd> -<p>When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query &gt; file</code>.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:default_values"><code id="proto:default_values"><a href="#aquery-flag--proto:default_values">--[no]proto:default_values</a></code> default: "true"</dt> -<dd> -<p>If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:definition_stack"><code id="proto:definition_stack"><a href="#aquery-flag--proto:definition_stack">--[no]proto:definition_stack</a></code> default: "false"</dt> -<dd> -<p>Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:flatten_selects"><code id="proto:flatten_selects"><a href="#aquery-flag--proto:flatten_selects">--[no]proto:flatten_selects</a></code> default: "true"</dt> -<dd> -<p>If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="aquery-flag--proto:include_attribute_source_aspects"><code id="proto:include_attribute_source_aspects"><a href="#aquery-flag--proto:include_attribute_source_aspects">--[no]proto:include_attribute_source_aspects</a></code> default: "false"</dt> -<dd> -<p>Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:include_starlark_rule_env"><code id="proto:include_starlark_rule_env"><a href="#aquery-flag--proto:include_starlark_rule_env">--[no]proto:include_starlark_rule_env</a></code> default: "true"</dt> -<dd> -<p>Use the starlark environment in the value of the generated $internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:include_synthetic_attribute_hash"><code id="proto:include_synthetic_attribute_hash"><a href="#aquery-flag--proto:include_synthetic_attribute_hash">--[no]proto:include_synthetic_attribute_hash</a></code> default: "false"</dt> -<dd> -<p>Whether or not to calculate and populate the $internal_attr_hash attribute.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:instantiation_stack"><code id="proto:instantiation_stack"><a href="#aquery-flag--proto:instantiation_stack">--[no]proto:instantiation_stack</a></code> default: "false"</dt> -<dd> -<p>Populate the instantiation call stack of each rule. Note that this requires the stack to be present</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:locations"><code id="proto:locations"><a href="#aquery-flag--proto:locations">--[no]proto:locations</a></code> default: "true"</dt> -<dd> -<p>Whether to output location information in proto output at all.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:output_rule_attrs"><code id="proto:output_rule_attrs"><a href="#aquery-flag--proto:output_rule_attrs">--proto:output_rule_attrs</a>=<comma-separated list of options></code> default: "all"</dt> -<dd> -<p>Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:rule_classes"><code id="proto:rule_classes"><a href="#aquery-flag--proto:rule_classes">--[no]proto:rule_classes</a></code> default: "false"</dt> -<dd> -<p>Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--proto:rule_inputs_and_outputs"><code id="proto:rule_inputs_and_outputs"><a href="#aquery-flag--proto:rule_inputs_and_outputs">--[no]proto:rule_inputs_and_outputs</a></code> default: "true"</dt> -<dd> -<p>Whether or not to populate the rule_input and rule_output fields.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--query_file"><code id="query_file"><a href="#aquery-flag--query_file">--query_file</a>=<a string></code> default: ""</dt> -<dd> -<p>If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="aquery-flag--relative_locations"><code id="relative_locations"><a href="#aquery-flag--relative_locations">--[no]relative_locations</a></code> default: "false"</dt> -<dd> -<p>If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--skyframe_state"><code id="skyframe_state"><a href="#aquery-flag--skyframe_state">--[no]skyframe_state</a></code> default: "false"</dt> -<dd> -<p>Without performing extra analysis, dump the current Action Graph from Skyframe. Note: Specifying a target with --skyframe_state is currently not supported. This flag is only available with --output=proto or --output=textproto.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="aquery-flag--tool_deps"><code id="tool_deps"><a href="#aquery-flag--tool_deps">--[no]tool_deps</a></code> default: "true"</dt> -<dd> -<p>Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. -Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="aquery-flag--universe_scope"><code id="universe_scope"><a href="#aquery-flag--universe_scope">--universe_scope</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. -For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> - -<dl>Options that control build execution: -<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> -<dd> -<p>Enable persistent aar extractor by using workers.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> -<dd> -<p>Whether to make source manifest actions remotable</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> -<dd> -<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> -<dd> -<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> -<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> -<p>Examples: -'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> -<dd> -<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> -<dd> -<p>If true, use the target platform for running tests rather than the test exec group.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The Android target compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> -<dd> -<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The C++ compiler to use for compiling the target.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> -<dd> -<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> -<dd> -<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> -<dd> -<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> -<dd> -<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> -<dd> -<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>No-op flag. Will be removed in a future release.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> -<dd> -<p>The label of a platform rule that describes the host system.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> -<dd> -<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> -<dd> -<p>Whether to emit a strip action as part of objc linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> -<dd> -<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> -<dd> -<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> -<dd> -<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> -<dd> -<p>The minimum OS version which your compilation targets.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> -<dd> -<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>The labels of the platform rules describing the target platforms for the current command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> -<dd> -<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> -<dd> -<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> -<dd> -<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> -<dd> -<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> -<dl>Options that control the output of the command: -<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> -<dd> -<p>Whether to generate debug symbol(.dSYM) file(s).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> -<dd> -<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> -<dd> -<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> -<dd> -<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> -<dd> -<p>Sets the suffixes of header files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> -<dd> -<p>Sets the suffixes of source files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> -<dd> -<p>Run extra actions for alternative Java api versions in a proto_library.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> -<dd> -<p>Save the state of enabled and requested feautres as an output of compilation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> -<dd> -<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> -<dd> -<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> -<dd> -<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>List of flags for which the use in select() is disabled.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> -<dd> -<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> -<dd> -<p>Specifies whether to generate a linkmap file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> -<dd> -<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case -the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -<br> -Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>Allowed values for the --cpu flag.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> -<dd> -<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> -<dd> -<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> -<dd> -<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> -<dd> -<p>Build python executable zip; on on Windows, off on other platforms</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> -<dd> -<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> -<dd> -<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> -<dd> -<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for FDO will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> -<dd> -<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> -<dd> -<p>Compress Java resources in APKs</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> -<dd> -<p>use rex tool to rewrite dex files</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will also generate collect coverage information for generated files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> -<dd> -<p>Uses these strings as objc fastbuild compiler options.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> -<dd> -<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> -<dd> -<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> -<dd> -<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> -<dd> -<p>py_binary targets include their label even when stamping is disabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> -<dd> -<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> -<dd> -<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use cache prefetch hints.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The fdo_profile representing the profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> -<dd> -<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> -<dd> -<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>The host CPU.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to linker when linking tools in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> -<dd> -<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> -<dd> -<p>If true, the genfiles directory is folded into the bin directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> -<dd> -<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> -<dd> -<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> -<dd> -<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> -</p></dd> -<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use memprof profile.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> -<dd> -<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> -<dd> -<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> -<dd> -<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> -<dd> -<p>If true, native libraries that contain identical functionality will be shared among different targets</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> -<dd> -<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> -<dd> -<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> -<dd> -<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> -<dd> -<p>Whether to desugar Java 8 bytecode before dexing.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> -<dd> -<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> -<dd> -<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> -<dd> -<p>Whether to double-check correct desugaring at Android binary level.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> -<dd> -<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> -<dd> -<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> -<dd> -<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> -<dd> -<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> -<dd> -<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> -<dd> -<p>No-op. Kept here for backwards compatibility.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> -<dd> -<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> -<dd> -<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> -<dd> -<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Options that affect the signing outputs of a build: -<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> -<dd> -<p>Implementation to use to sign APKs</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> -<dd> -<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> -<dd> -<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> -<dd> -<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> -<dd> -<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> -<dd> -<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that govern the behavior of the test environment or test runner: -<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> -<dd> -<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> -<dd> -<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> -<dd> -<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> -<dd> -<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> -</dd> -<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> -<dd> -<p>Use dex2oat in parallel to possibly speed up android_test.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> -<dd> -<p>Enable checking for memory leaks in ios_test targets.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> -<dd> -<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> -</dd> -<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> -<dd> -<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> -</dd> -<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, undeclared test outputs will be archived in a zip file.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -</dl> -<dl>Options that trigger optimizations of the build time: -<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> -<dd> -<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> -<dd> -<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> -<dd> -<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> -<dd> -<p>Does most of the work for dexing separately for each Jar file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> -<dd> -<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> -<dd> -<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> -<dd> -<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> -<dd> -<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> -<dd> -<p>If enabled, visibility errors include additional diagnostic information.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> -<dd> -<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> -<dd> -<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> -<dd> -<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> -</dd> -<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> -<dd> -<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> -<dd> -<p>If true, coverage for clang will generate an LCOV report.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> -<dd> -<p>Enables reduced classpaths for Java compilations.</p> -</dd> -<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> -<dd> -<p>Whether to validate java_* sources.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> -<dd> -<p>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.</p> -</dd> -<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher used by tools that are executed during a build.</p> -</dd> -<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac when building tools that are executed during a build.</p> -</dd> -<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> -<dd> -<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> -<dd> -<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the J2ObjC tool.</p> -</dd> -<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> -<dd> -<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> -<p>Expands to: -<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> -<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> -<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> -<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> -<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> -</p></dd> -<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> -<dd> -<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> -</dd> -<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> -<dd> -<p>Compile ijars directly from source.</p> -</dd> -<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version</p> -</dd> -<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> -</dd> -<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> -<dd> -<p>The Java runtime version</p> -</dd> -<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac.</p> -</dd> -<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> -</dd> -<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to do dexing without sharding.</p> -</dd> -<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Plugins to use in the build. Currently works with java_plugin.</p> -</dd> -<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> -</dd> -<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> -<dd> -<p>The label of the proto-compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> -<dd> -<p>Whether to pass profile_path to the proto compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the protobuf compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> -<dd> -<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> -</dd> -<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> -<dd> -<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> -</dd> -<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> -</dd> -<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>This option is deprecated and has no effect.</p> -</dd> -<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> -<dd> -<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> -</dd> -<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> -<dd> -<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> -</dd> -<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version used to execute the tools that are needed during a build</p> -</dd> -<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> -<dd> -<p>The Java runtime version used to execute tools during the build</p> -</dd> -<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> -<dd> -<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> -</dd> -</dl> - -<h2><a name="build">Build Options</a></h2> -<dl>Options that control build execution: -<dt id="build-flag--allow_one_action_on_resource_unavailable"><code id="allow_one_action_on_resource_unavailable"><a href="#build-flag--allow_one_action_on_resource_unavailable">--[no]allow_one_action_on_resource_unavailable</a></code> default: "true"</dt> -<dd> -<p>If set, allow at least one action to run even if the resource is not enough or unavailable.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--check_up_to_date"><code id="check_up_to_date"><a href="#build-flag--check_up_to_date">--[no]check_up_to_date</a></code> default: "false"</dt> -<dd> -<p>Don't perform the build, just check if it is up-to-date. If all targets are up-to-date, the build completes successfully. If any step needs to be executed an error is reported and the build fails.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--dynamic_local_execution_delay"><code id="dynamic_local_execution_delay"><a href="#build-flag--dynamic_local_execution_delay">--dynamic_local_execution_delay</a>=<an integer></code> default: "1000"</dt> -<dd> -<p>How many milliseconds should local execution be delayed, if remote execution was faster during a build at least once?</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--dynamic_local_strategy"><code id="dynamic_local_strategy"><a href="#build-flag--dynamic_local_strategy">--dynamic_local_strategy</a>=<a '[name=]value1[,..,valueN]' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>The local strategies, in order, to use for the given mnemonic - the first applicable strategy is used. For example, <code>worker,sandboxed</code> runs actions that support persistent workers using the worker strategy, and all others using the sandboxed strategy. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is <code>worker,sandboxed</code>, or<code>worker,sandboxed,standalone</code> if <code>experimental_local_lockfree_output</code> is set. Takes [mnemonic=]local_strategy[,local_strategy,...]</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--dynamic_remote_strategy"><code id="dynamic_remote_strategy"><a href="#build-flag--dynamic_remote_strategy">--dynamic_remote_strategy</a>=<a '[name=]value1[,..,valueN]' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>The remote strategies, in order, to use for the given mnemonic - the first applicable strategy is used. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is <code>remote</code>, so this flag usually does not need to be set explicitly. Takes [mnemonic=]remote_strategy[,remote_strategy,...]</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_async_execution"><code id="experimental_async_execution"><a href="#build-flag--experimental_async_execution">--[no]experimental_async_execution</a></code> default: "false"</dt> -<dd> -<p>If set to true, Bazel is allowed to run action in a virtual thread. The number of actions in flight is still capped with --jobs.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="build-flag--experimental_async_execution_max_concurrent_actions"><code id="experimental_async_execution_max_concurrent_actions"><a href="#build-flag--experimental_async_execution_max_concurrent_actions">--experimental_async_execution_max_concurrent_actions</a>=<an integer></code> default: "5000"</dt> -<dd> -<p>The number of maximum concurrent actions to run with async execution. If the value is less than --jobs, it is clamped to --jobs.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_docker_image"><code id="experimental_docker_image"><a href="#build-flag--experimental_docker_image">--experimental_docker_image</a>=<a string></code> default: ""</dt> -<dd> -<p>Specify a Docker image name (e.g. "ubuntu:latest") that should be used to execute a sandboxed action when using the docker strategy and the action itself doesn't already have a container-image attribute in its remote_execution_properties in the platform description. The value of this flag is passed verbatim to 'docker run', so it supports the same syntax and mechanisms as Docker itself.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_docker_use_customized_images"><code id="experimental_docker_use_customized_images"><a href="#build-flag--experimental_docker_use_customized_images">--[no]experimental_docker_use_customized_images</a></code> default: "true"</dt> -<dd> -<p>If enabled, injects the uid and gid of the current user into the Docker image before using it. This is required if your build / tests depend on the user having a name and home directory inside the container. This is on by default, but you can disable it in case the automatic image customization feature doesn't work in your case or you know that you don't need it.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_dynamic_exclude_tools"><code id="experimental_dynamic_exclude_tools"><a href="#build-flag--experimental_dynamic_exclude_tools">--[no]experimental_dynamic_exclude_tools</a></code> default: "true"</dt> -<dd> -<p>When set, targets that are build "for tool" are not subject to dynamic execution. Such targets are extremely unlikely to be built incrementally and thus not worth spending local cycles on.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_dynamic_local_load_factor"><code id="experimental_dynamic_local_load_factor"><a href="#build-flag--experimental_dynamic_local_load_factor">--experimental_dynamic_local_load_factor</a>=<a double></code> default: "0"</dt> -<dd> -<p>Controls how much load from dynamic execution to put on the local machine. This flag adjusts how many actions in dynamic execution we will schedule concurrently. It is based on the number of CPUs Blaze thinks is available, which can be controlled with the --local_resources=cpu= flag. -If this flag is 0, all actions are scheduled locally immediately. If > 0, the amount of actions scheduled locally is limited by the number of CPUs available. If < 1, the load factor is used to reduce the number of locally scheduled actions when the number of actions waiting to schedule is high. This lessens the load on the local machine in the clean build case, where the local machine does not contribute much.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_dynamic_slow_remote_time"><code id="experimental_dynamic_slow_remote_time"><a href="#build-flag--experimental_dynamic_slow_remote_time">--experimental_dynamic_slow_remote_time</a>=<An immutable length of time.></code> default: "0"</dt> -<dd> -<p>If >0, the time a dynamically run action must run remote-only before we prioritize its local execution to avoid remote timeouts. This may hide some problems on the remote execution system. Do not turn this on without monitoring of remote execution issues.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_enable_docker_sandbox"><code id="experimental_enable_docker_sandbox"><a href="#build-flag--experimental_enable_docker_sandbox">--[no]experimental_enable_docker_sandbox</a></code> default: "false"</dt> -<dd> -<p>Enable Docker-based sandboxing. This option has no effect if Docker is not installed.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_inmemory_sandbox_stashes"><code id="experimental_inmemory_sandbox_stashes"><a href="#build-flag--experimental_inmemory_sandbox_stashes">--[no]experimental_inmemory_sandbox_stashes</a></code> default: "false"</dt> -<dd> -<p>If set to true, the contents of stashed sandboxes for reuse_sandbox_directories will be tracked in memory. This reduces the amount of I/O needed during reuse. Depending on the build this flag may improve wall time. Depending on the build as well this flag may use a significant amount of additional memory.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_sandbox_async_tree_delete_idle_threads"><code id="experimental_sandbox_async_tree_delete_idle_threads"><a href="#build-flag--experimental_sandbox_async_tree_delete_idle_threads">--experimental_sandbox_async_tree_delete_idle_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "4"</dt> -<dd> -<p>If 0, sandboxes are deleted as soon as actions finish, blocking action completion. If greater than 0, sandboxes are deleted asynchronously in the background without blocking action completion. Asynchronous deletion uses a single thread while a command is running, but ramps up to as many threads as the value of this flag once the server becomes idle. Set to <code>auto</code> to use as many threads as the number of CPUs. A server shutdown blocks on any pending asynchronous deletions.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_sandbox_enforce_resources_regexp"><code id="experimental_sandbox_enforce_resources_regexp"><a href="#build-flag--experimental_sandbox_enforce_resources_regexp">--experimental_sandbox_enforce_resources_regexp</a>=<a valid Java regular expression></code> default: ""</dt> -<dd> -<p>If true, actions whose mnemonic matches the input regex will have their resources request enforced as limits, overriding the value of --experimental_sandbox_limits, if the resource type supports it. For example a test that declares cpu:3 and resources:memory:10, will run with at most 3 cpus and 10 megabytes of memory.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_sandbox_limits"><code id="experimental_sandbox_limits"><a href="#build-flag--experimental_sandbox_limits">--experimental_sandbox_limits</a>=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> multiple uses are accumulated</dt> -<dd> -<p>If > 0, each Linux sandbox will be limited to the given amount for the specified resource. Requires --incompatible_use_new_cgroup_implementation and overrides --experimental_sandbox_memory_limit_mb. Requires cgroups v1 or v2 and permissions for the users to the cgroups dir.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_sandbox_memory_limit_mb"><code id="experimental_sandbox_memory_limit_mb"><a href="#build-flag--experimental_sandbox_memory_limit_mb">--experimental_sandbox_memory_limit_mb</a>=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.></code> default: "0"</dt> -<dd> -<p>If > 0, each Linux sandbox will be limited to the given amount of memory (in MB). Requires cgroups v1 or v2 and permissions for the users to the cgroups dir.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_shrink_worker_pool"><code id="experimental_shrink_worker_pool"><a href="#build-flag--experimental_shrink_worker_pool">--[no]experimental_shrink_worker_pool</a></code> default: "false"</dt> -<dd> -<p>If enabled, could shrink worker pool if worker memory pressure is high. This flag works only when flag experimental_total_worker_memory_limit_mb is enabled.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_total_worker_memory_limit_mb"><code id="experimental_total_worker_memory_limit_mb"><a href="#build-flag--experimental_total_worker_memory_limit_mb">--experimental_total_worker_memory_limit_mb</a>=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.></code> default: "0"</dt> -<dd> -<p>If this limit is greater than zero idle workers might be killed if the total memory usage of all workers exceed the limit.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_use_hermetic_linux_sandbox"><code id="experimental_use_hermetic_linux_sandbox"><a href="#build-flag--experimental_use_hermetic_linux_sandbox">--[no]experimental_use_hermetic_linux_sandbox</a></code> default: "false"</dt> -<dd> -<p>If set to true, do not mount root, only mount whats provided with sandbox_add_mount_pair. Input files will be hardlinked to the sandbox instead of symlinked to from the sandbox. If action input files are located on a filesystem different from the sandbox, then the input files will be copied instead.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_use_windows_sandbox"><code id="experimental_use_windows_sandbox"><a href="#build-flag--experimental_use_windows_sandbox">--[no]experimental_use_windows_sandbox</a></code> default: "false"</dt> -<dd> -<p>Use Windows sandbox to run actions. If "yes", the binary provided by --experimental_windows_sandbox_path must be valid and correspond to a supported version of sandboxfs. If "auto", the binary may be missing or not compatible.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_windows_sandbox_path"><code id="experimental_windows_sandbox_path"><a href="#build-flag--experimental_windows_sandbox_path">--experimental_windows_sandbox_path</a>=<a string></code> default: "BazelSandbox.exe"</dt> -<dd> -<p>Path to the Windows sandbox binary to use when --experimental_use_windows_sandbox is true. If a bare name, use the first binary of that name found in the PATH.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_worker_allowlist"><code id="experimental_worker_allowlist"><a href="#build-flag--experimental_worker_allowlist">--experimental_worker_allowlist</a>=<comma-separated set of options></code> default: see description</dt> -<dd> -<p>If non-empty, only allow using persistent workers with the given worker key mnemonic.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_worker_cancellation"><code id="experimental_worker_cancellation"><a href="#build-flag--experimental_worker_cancellation">--[no]experimental_worker_cancellation</a></code> default: "false"</dt> -<dd> -<p>If enabled, Bazel may send cancellation requests to workers that support them.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_worker_memory_limit_mb"><code id="experimental_worker_memory_limit_mb"><a href="#build-flag--experimental_worker_memory_limit_mb">--experimental_worker_memory_limit_mb</a>=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.></code> default: "0"</dt> -<dd> -<p>If this limit is greater than zero, workers might be killed if the memory usage of the worker exceeds the limit. If not used together with dynamic execution and <code>--experimental_dynamic_ignore_local_signals=9</code>, this may crash your build.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_worker_metrics_poll_interval"><code id="experimental_worker_metrics_poll_interval"><a href="#build-flag--experimental_worker_metrics_poll_interval">--experimental_worker_metrics_poll_interval</a>=<An immutable length of time.></code> default: "5s"</dt> -<dd> -<p>The interval between collecting worker metrics and possibly attempting evictions. Cannot effectively be less than 1s for performance reasons.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_worker_multiplex_sandboxing"><code id="experimental_worker_multiplex_sandboxing"><a href="#build-flag--experimental_worker_multiplex_sandboxing">--[no]experimental_worker_multiplex_sandboxing</a></code> default: "false"</dt> -<dd> -<p>If enabled, multiplex workers with a 'supports-multiplex-sandboxing' execution requirement will run in a sandboxed environment, using a separate sandbox directory per work request. Multiplex workers with the execution requirement are always sandboxed when running under the dynamic execution strategy, irrespective of this flag.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_worker_sandbox_hardening"><code id="experimental_worker_sandbox_hardening"><a href="#build-flag--experimental_worker_sandbox_hardening">--[no]experimental_worker_sandbox_hardening</a></code> default: "false"</dt> -<dd> -<p>If enabled, workers are run in a hardened sandbox, if the implementation allows it. If hardening is enabled then tmp directories are distinct for different workers.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_worker_sandbox_inmemory_tracking"><code id="experimental_worker_sandbox_inmemory_tracking"><a href="#build-flag--experimental_worker_sandbox_inmemory_tracking">--experimental_worker_sandbox_inmemory_tracking</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>A worker key mnemonic for which the contents of the sandbox directory are tracked in memory. This may improve build performance at the cost of additional memory usage. Only affects sandboxed workers. May be specified multiple times for different mnemonics.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_worker_strict_flagfiles"><code id="experimental_worker_strict_flagfiles"><a href="#build-flag--experimental_worker_strict_flagfiles">--[no]experimental_worker_strict_flagfiles</a></code> default: "false"</dt> -<dd> -<p>If enabled, actions arguments for workers that do not follow the worker specification will cause an error. Worker arguments must have exactly one @flagfile argument as the last of its list of arguments.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--genrule_strategy"><code id="genrule_strategy"><a href="#build-flag--genrule_strategy">--genrule_strategy</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>Specify how to execute genrules. This flag will be phased out. Instead, use --spawn_strategy=<value> to control all actions or --strategy=Genrule=<value> to control genrules only.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--incompatible_use_new_cgroup_implementation"><code id="incompatible_use_new_cgroup_implementation"><a href="#build-flag--incompatible_use_new_cgroup_implementation">--[no]incompatible_use_new_cgroup_implementation</a></code> default: "true"</dt> -<dd> -<p>If true, use the new implementation for cgroups. The old implementation only supports the memory controller and ignores the value of --experimental_sandbox_limits.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--internal_spawn_scheduler"><code id="internal_spawn_scheduler"><a href="#build-flag--internal_spawn_scheduler">--[no]internal_spawn_scheduler</a></code> default: "true"</dt> -<dd> -<p>Placeholder option so that we can tell in Blaze whether the spawn scheduler was enabled.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--jobs"><code id="jobs"><a href="#build-flag--jobs">--jobs</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> [<code>-j</code>] default: "auto"</dt> -<dd> -<p>The number of concurrent jobs to run. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". Values must be between 1 and 5000. Values above 2500 may cause memory issues. "auto" calculates a reasonable default based on host resources.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--keep_going"><code id="keep_going"><a href="#build-flag--keep_going">--[no]keep_going</a></code> [<code>-k</code>] default: "false"</dt> -<dd> -<p>Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="build-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#build-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> -<dd> -<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="build-flag--reuse_sandbox_directories"><code id="reuse_sandbox_directories"><a href="#build-flag--reuse_sandbox_directories">--[no]reuse_sandbox_directories</a></code> default: "true"</dt> -<dd> -<p>If set to true, directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_base"><code id="sandbox_base"><a href="#build-flag--sandbox_base">--sandbox_base</a>=<a string></code> default: ""</dt> -<dd> -<p>Lets the sandbox create its sandbox directories underneath this path. Specify a path on tmpfs (like /run/shm) to possibly improve performance a lot when your build / tests have many input files. Note: You need enough RAM and free space on the tmpfs to hold output and intermediate files generated by running actions.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_enable_loopback_device"><code id="sandbox_enable_loopback_device"><a href="#build-flag--sandbox_enable_loopback_device">--[no]sandbox_enable_loopback_device</a></code> default: "true"</dt> -<dd> -<p>If true, a loopback device will be set up in the linux-sandbox network namespace for local actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_explicit_pseudoterminal"><code id="sandbox_explicit_pseudoterminal"><a href="#build-flag--sandbox_explicit_pseudoterminal">--[no]sandbox_explicit_pseudoterminal</a></code> default: "false"</dt> -<dd> -<p>Explicitly enable the creation of pseudoterminals for sandboxed actions. Some linux distributions require setting the group id of the process to 'tty' inside the sandbox in order for pseudoterminals to function. If this is causing issues, this flag can be disabled to enable other groups to be used.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_tmpfs_path"><code id="sandbox_tmpfs_path"><a href="#build-flag--sandbox_tmpfs_path">--sandbox_tmpfs_path</a>=<an absolute path></code> multiple uses are accumulated</dt> -<dd> -<p>For sandboxed actions, mount an empty, writable directory at this absolute path (if supported by the sandboxing implementation, ignored otherwise).</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--skip_incompatible_explicit_targets"><code id="skip_incompatible_explicit_targets"><a href="#build-flag--skip_incompatible_explicit_targets">--[no]skip_incompatible_explicit_targets</a></code> default: "false"</dt> -<dd> -<p>Skip incompatible targets that are explicitly listed on the command line. By default, building such targets results in an error but they are silently skipped when this option is enabled. See: https://bazel.build/extending/platforms#skipping-incompatible-targets</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="build-flag--spawn_strategy"><code id="spawn_strategy"><a href="#build-flag--spawn_strategy">--spawn_strategy</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>Specify how spawn actions are executed by default. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". See https://blog.bazel.build/2019/06/19/list-strategy.html for details.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--strategy"><code id="strategy"><a href="#build-flag--strategy">--strategy</a>=<a '[name=]value1[,..,valueN]' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify how to distribute compilation of other spawn actions. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". This flag overrides the values set by --spawn_strategy (and --genrule_strategy if used with mnemonic Genrule). See https://blog.bazel.build/2019/06/19/list-strategy.html for details.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--strategy_regexp"><code id="strategy_regexp"><a href="#build-flag--strategy_regexp">--strategy_regexp</a>=<a '<RegexFilter>=value[,value]' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Override which spawn strategy should be used to execute spawn actions that have descriptions matching a certain regex_filter. See --per_file_copt for details onregex_filter matching. The last regex_filter that matches the description is used. This option overrides other flags for specifying strategy. Example: --strategy_regexp=//foo.<em>.cc,-//foo/bar=local means to run actions using local strategy if their descriptions match //foo.</em>.cc but not //foo/bar. Example: --strategy_regexp='Compiling.*/bar=local --strategy_regexp=Compiling=sandboxed will run 'Compiling //foo/bar/baz' with the 'local' strategy, but reversing the order would run it with 'sandboxed'.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--worker_extra_flag"><code id="worker_extra_flag"><a href="#build-flag--worker_extra_flag">--worker_extra_flag</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Extra command-flags that will be passed to worker processes in addition to --persistent_worker, keyed by mnemonic (e.g. --worker_extra_flag=Javac=--debug.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--worker_max_instances"><code id="worker_max_instances"><a href="#build-flag--worker_max_instances">--worker_max_instances</a>=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> multiple uses are accumulated</dt> -<dd> -<p>How many instances of each kind of persistent worker may be launched if you use the 'worker' strategy. May be specified as [name=value] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--worker_max_multiplex_instances"><code id="worker_max_multiplex_instances"><a href="#build-flag--worker_max_multiplex_instances">--worker_max_multiplex_instances</a>=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> multiple uses are accumulated</dt> -<dd> -<p>How many WorkRequests a multiplex worker process may receive in parallel if you use the 'worker' strategy with --worker_multiplex. May be specified as [name=value] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--worker_multiplex"><code id="worker_multiplex"><a href="#build-flag--worker_multiplex">--[no]worker_multiplex</a></code> default: "true"</dt> -<dd> -<p>If enabled, workers will use multiplexing if they support it.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--worker_quit_after_build"><code id="worker_quit_after_build"><a href="#build-flag--worker_quit_after_build">--[no]worker_quit_after_build</a></code> default: "false"</dt> -<dd> -<p>If enabled, all workers quit after a build is done.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--worker_sandboxing"><code id="worker_sandboxing"><a href="#build-flag--worker_sandboxing">--[no]worker_sandboxing</a></code> default: "false"</dt> -<dd> -<p>If enabled, singleplex workers will run in a sandboxed environment. Singleplex workers are always sandboxed when running under the dynamic execution strategy, irrespective of this flag.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--worker_verbose"><code id="worker_verbose"><a href="#build-flag--worker_verbose">--[no]worker_verbose</a></code> default: "false"</dt> -<dd> -<p>If enabled, prints verbose messages when workers are started, shutdown, ...</p> -</dd> -</dl> -<dl>Options that control the output of the command: -<dt id="build-flag--build"><code id="build"><a href="#build-flag--build">--[no]build</a></code> default: "true"</dt> -<dd> -<p>Execute the build; this is the usual behaviour. Specifying --nobuild causes the build to stop before executing the build actions, returning zero iff the package loading and analysis phases completed successfully; this mode is useful for testing those phases.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--experimental_use_validation_aspect"><code id="experimental_use_validation_aspect"><a href="#build-flag--experimental_use_validation_aspect">--[no]experimental_use_validation_aspect</a></code> default: "false"</dt> -<dd> -<p>Whether to run validation actions using aspect (for parallelism with tests).</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--output_groups"><code id="output_groups"><a href="#build-flag--output_groups">--output_groups</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>A list of comma-separated output group names, each of which optionally prefixed by a + or a -. A group prefixed by + is added to the default set of output groups, while a group prefixed by - is removed from the default set. If at least one group is not prefixed, the default set of output groups is omitted. For example, --output_groups=+foo,+bar builds the union of the default set, foo, and bar, while --output_groups=foo,bar overrides the default set such that only foo and bar are built.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--run_validations"><code id="run_validations"><a href="#build-flag--run_validations">--[no]run_validations</a></code> default: "true"</dt> -<dd> -<p>Whether to run validation actions as part of the build. See https://bazel.build/extending/rules#validation_actions</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--serialized_frontier_profile"><code id="serialized_frontier_profile"><a href="#build-flag--serialized_frontier_profile">--serialized_frontier_profile</a>=<a string></code> default: ""</dt> -<dd> -<p>Dump a profile of serialized frontier bytes. Specifies the output path.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="build-flag--aspects"><code id="aspects"><a href="#build-flag--aspects">--aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of aspects to be applied to top-level targets. In the list, if aspect some_aspect specifies required aspect providers via required_aspect_providers, some_aspect will run after every aspect that was mentioned before it in the aspects list whose advertised providers satisfy some_aspect required aspect providers. Moreover, some_aspect will run after all its required aspects specified by requires attribute. some_aspect will then have access to the values of those aspects' providers. <bzl-file-label>%<aspect_name>, for example '//tools:my_def.bzl%my_aspect', where 'my_aspect' is a top-level value from a file tools/my_def.bzl</p> -</dd> -<dt id="build-flag--bep_maximum_open_remote_upload_files"><code id="bep_maximum_open_remote_upload_files"><a href="#build-flag--bep_maximum_open_remote_upload_files">--bep_maximum_open_remote_upload_files</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>Maximum number of open files allowed during BEP artifact upload.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--experimental_convenience_symlinks"><code id="experimental_convenience_symlinks"><a href="#build-flag--experimental_convenience_symlinks">--[no]experimental_convenience_symlinks</a></code> default: "normal"</dt> -<dd> -<p>This flag controls how the convenience symlinks (the symlinks that appear in the workspace after the build) will be managed. Possible values: -normal (default): Each kind of convenience symlink will be created or deleted, as determined by the build. -clean: All symlinks will be unconditionally deleted. -ignore: Symlinks will not be created or cleaned up. -log_only: Generate log messages as if 'normal' were passed, but don't actually perform any filesystem operations (useful for tools). -Note that only symlinks whose names are generated by the current value of --symlink_prefix can be affected; if the prefix changes, any pre-existing symlinks will be left alone.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--experimental_convenience_symlinks_bep_event"><code id="experimental_convenience_symlinks_bep_event"><a href="#build-flag--experimental_convenience_symlinks_bep_event">--[no]experimental_convenience_symlinks_bep_event</a></code> default: "true"</dt> -<dd> -<p>This flag controls whether or not we will post the build eventConvenienceSymlinksIdentified to the BuildEventProtocol. If the value is true, the BuildEventProtocol will have an entry for convenienceSymlinksIdentified, listing all of the convenience symlinks created in your workspace. If false, then the convenienceSymlinksIdentified entry in the BuildEventProtocol will be empty.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--remote_download_all"><code id="remote_download_all"><a href="#build-flag--remote_download_all">--remote_download_all</a></code></dt> -<dd> -<p>Downloads all remote outputs to the local machine. This flag is an alias for --remote_download_outputs=all.</p> -<p>Expands to: -<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=all</a></code> -</p><p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--remote_download_minimal"><code id="remote_download_minimal"><a href="#build-flag--remote_download_minimal">--remote_download_minimal</a></code></dt> -<dd> -<p>Does not download any remote build outputs to the local machine. This flag is an alias for --remote_download_outputs=minimal.</p> -<p>Expands to: -<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=minimal</a></code> -</p><p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--remote_download_outputs"><code id="remote_download_outputs"><a href="#build-flag--remote_download_outputs">--remote_download_outputs</a>=<all, minimal or toplevel></code> default: "toplevel"</dt> -<dd> -<p>If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--remote_download_symlink_template"><code id="remote_download_symlink_template"><a href="#build-flag--remote_download_symlink_template">--remote_download_symlink_template</a>=<a string></code> default: ""</dt> -<dd> -<p>Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--remote_download_toplevel"><code id="remote_download_toplevel"><a href="#build-flag--remote_download_toplevel">--remote_download_toplevel</a></code></dt> -<dd> -<p>Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote_download_outputs=toplevel.</p> -<p>Expands to: -<br/>  <code><a href="#flag--remote_download_outputs">--remote_download_outputs=toplevel</a></code> -</p><p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--symlink_prefix"><code id="symlink_prefix"><a href="#build-flag--symlink_prefix">--symlink_prefix</a>=<a string></code> default: see description</dt> -<dd> -<p>The prefix that is prepended to any of the convenience symlinks that are created after a build. If omitted, the default value is the name of the build tool followed by a hyphen. If '/' is passed, then no symlinks are created and no warning is emitted. Warning: the special functionality for '/' will be deprecated soon; use --experimental_convenience_symlinks=ignore instead.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="build-flag--experimental_docker_privileged"><code id="experimental_docker_privileged"><a href="#build-flag--experimental_docker_privileged">--[no]experimental_docker_privileged</a></code> default: "false"</dt> -<dd> -<p>If enabled, Bazel will pass the --privileged flag to 'docker run' when running actions. This might be required by your build, but it might also result in reduced hermeticity.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_sandboxfs_map_symlink_targets"><code id="experimental_sandboxfs_map_symlink_targets"><a href="#build-flag--experimental_sandboxfs_map_symlink_targets">--[no]experimental_sandboxfs_map_symlink_targets</a></code> default: "false"</dt> -<dd> -<p>No-op</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_add_mount_pair"><code id="sandbox_add_mount_pair"><a href="#build-flag--sandbox_add_mount_pair">--sandbox_add_mount_pair</a>=<a single path or a 'source:target' pair></code> multiple uses are accumulated</dt> -<dd> -<p>Add additional path pair to mount in sandbox.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_block_path"><code id="sandbox_block_path"><a href="#build-flag--sandbox_block_path">--sandbox_block_path</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>For sandboxed actions, disallow access to this path.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_default_allow_network"><code id="sandbox_default_allow_network"><a href="#build-flag--sandbox_default_allow_network">--[no]sandbox_default_allow_network</a></code> default: "true"</dt> -<dd> -<p>Allow network access by default for actions; this may not work with all sandboxing implementations.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_fake_hostname"><code id="sandbox_fake_hostname"><a href="#build-flag--sandbox_fake_hostname">--[no]sandbox_fake_hostname</a></code> default: "false"</dt> -<dd> -<p>Change the current hostname to 'localhost' for sandboxed actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_fake_username"><code id="sandbox_fake_username"><a href="#build-flag--sandbox_fake_username">--[no]sandbox_fake_username</a></code> default: "false"</dt> -<dd> -<p>Change the current username to 'nobody' for sandboxed actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--sandbox_writable_path"><code id="sandbox_writable_path"><a href="#build-flag--sandbox_writable_path">--sandbox_writable_path</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>For sandboxed actions, make an existing directory writable in the sandbox (if supported by the sandboxing implementation, ignored otherwise).</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="build-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#build-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> -<dd> -<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="build-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#build-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> -<dd> -<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that govern the behavior of the test environment or test runner: -<dt id="build-flag--check_tests_up_to_date"><code id="check_tests_up_to_date"><a href="#build-flag--check_tests_up_to_date">--[no]check_tests_up_to_date</a></code> default: "false"</dt> -<dd> -<p>Don't run tests, just check if they are up-to-date. If all tests results are up-to-date, the testing completes successfully. If any test needs to be built or executed, an error is reported and the testing fails. This option implies --check_up_to_date behavior.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--flaky_test_attempts"><code id="flaky_test_attempts"><a href="#build-flag--flaky_test_attempts">--flaky_test_attempts</a>=<a positive integer, the string "default", or test_regex@attempts. This flag may be passed more than once></code> multiple uses are accumulated</dt> -<dd> -<p>Each test will be retried up to the specified number of times in case of any test failure. Tests that required more than one attempt to pass are marked as 'FLAKY' in the test summary. Normally the value specified is just an integer or the string 'default'. If an integer, then all tests will be run up to N times. If 'default', then only a single test attempt will be made for regular tests and three for tests marked explicitly as flaky by their rule (flaky=1 attribute). Alternate syntax: regex_filter@flaky_test_attempts. Where flaky_test_attempts is as above and regex_filter stands for a list of include and exclude regular expression patterns (Also see --runs_per_test). Example: --flaky_test_attempts=//foo/.<em>,-//foo/bar/.</em>@3 deflakes all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, behavior is as if 'default' above.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--local_test_jobs"><code id="local_test_jobs"><a href="#build-flag--local_test_jobs">--local_test_jobs</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> -<dd> -<p>The max number of local test jobs to run concurrently. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". 0 means local resources will limit the number of local test jobs to run concurrently instead. Setting this greater than the value for --jobs is ineffectual.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--test_keep_going"><code id="test_keep_going"><a href="#build-flag--test_keep_going">--[no]test_keep_going</a></code> default: "true"</dt> -<dd> -<p>When disabled, any non-passing test will cause the entire build to stop. By default all tests are run, even if some do not pass.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--test_strategy"><code id="test_strategy"><a href="#build-flag--test_strategy">--test_strategy</a>=<a string></code> default: ""</dt> -<dd> -<p>Specifies which strategy to use when running tests.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--test_tmpdir"><code id="test_tmpdir"><a href="#build-flag--test_tmpdir">--test_tmpdir</a>=<a path></code> default: see description</dt> -<dd> -<p>Specifies the base temporary directory for 'bazel test' to use.</p> -</dd> -</dl> -<dl>Options that trigger optimizations of the build time: -<dt id="build-flag--cache_computed_file_digests"><code id="cache_computed_file_digests"><a href="#build-flag--cache_computed_file_digests">--cache_computed_file_digests</a>=<a long integer></code> default: "50000"</dt> -<dd> -<p>If greater than 0, configures Bazel to cache file digests in memory based on their metadata instead of recomputing the digests from disk every time they are needed. Setting this to 0 ensures correctness because not all file changes can be noted from file metadata. When not 0, the number indicates the size of the cache as the number of file digests to be cached.</p> -</dd> -<dt id="build-flag--experimental_active_directories"><code id="experimental_active_directories"><a href="#build-flag--experimental_active_directories">--experimental_active_directories</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>Active directories for Skyfocus and remote analysis caching. Specify as comma-separated workspace root-relative paths. This is a stateful flag. Defining one persists it for subsequent invocations, until it is redefined with a new set.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--experimental_cpu_load_scheduling"><code id="experimental_cpu_load_scheduling"><a href="#build-flag--experimental_cpu_load_scheduling">--[no]experimental_cpu_load_scheduling</a></code> default: "false"</dt> -<dd> -<p>Enables the experimental local execution scheduling based on CPU load, not estimation of actions one by one. Experimental scheduling have showed the large benefit on a large local builds on a powerful machines with the large number of cores. Reccommended to use with --local_resources=cpu=HOST_CPUS</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_dynamic_ignore_local_signals"><code id="experimental_dynamic_ignore_local_signals"><a href="#build-flag--experimental_dynamic_ignore_local_signals">--experimental_dynamic_ignore_local_signals</a>=<a comma-separated list of signal numbers></code> default: see description</dt> -<dd> -<p>Takes a list of OS signal numbers. If a local branch of dynamic execution gets killed with any of these signals, the remote branch will be allowed to finish instead. For persistent workers, this only affects signals that kill the worker process.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_enable_skyfocus"><code id="experimental_enable_skyfocus"><a href="#build-flag--experimental_enable_skyfocus">--[no]experimental_enable_skyfocus</a></code> default: "false"</dt> -<dd> -<p>If true, enable the use of --experimental_active_directories to reduce Bazel's memory footprint for incremental builds. This feature is known as Skyfocus.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--local_cpu_resources"><code id="local_cpu_resources"><a href="#build-flag--local_cpu_resources">--local_cpu_resources</a>=<an integer, or "HOST_CPUS", optionally followed by [-|*]<float>.></code> default: "HOST_CPUS"</dt> -<dd> -<p>Explicitly set the total number of local CPU cores available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST_CPUS", optionally followed by [-|<em>]<float> (eg. HOST_CPUS</em>.5 to use half the available CPU cores). By default, ("HOST_CPUS"), Bazel will query system configuration to estimate the number of CPU cores available.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--local_extra_resources"><code id="local_extra_resources"><a href="#build-flag--local_extra_resources">--local_extra_resources</a>=<a named float, 'name=value'></code> multiple uses are accumulated</dt> -<dd> -<p>Set the number of extra resources available to Bazel. Takes in a string-float pair. Can be used multiple times to specify multiple types of extra resources. Bazel will limit concurrently running actions based on the available extra resources and the extra resources required. Tests can declare the amount of extra resources they need by using a tag of the "resources:<resoucename>:<amount>" format. Available CPU, RAM and resources cannot be set with this flag.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--local_ram_resources"><code id="local_ram_resources"><a href="#build-flag--local_ram_resources">--local_ram_resources</a>=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.></code> default: "HOST_RAM*.67"</dt> -<dd> -<p>Explicitly set the total amount of local host RAM (in MB) available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST_RAM", optionally followed by [-|<em>]<float> (eg. HOST_RAM</em>.5 to use half the available RAM). By default, ("HOST_RAM*.67"), Bazel will query system configuration to estimate the amount of RAM available and will use 67% of it.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--local_resources"><code id="local_resources"><a href="#build-flag--local_resources">--local_resources</a>=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> multiple uses are accumulated</dt> -<dd> -<p>Set the number of resources available to Bazel. Takes in an assignment to a float or HOST_RAM/HOST_CPUS, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.5 to use half the available RAM). Can be used multiple times to specify multiple types of resources. Bazel will limit concurrently running actions based on the available resources and the resources required. Tests can declare the amount of resources they need by using a tag of the "resources:<resource name>:<amount>" format. Overrides resources specified by --local_{cpu|ram|extra}_resources.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="build-flag--build_event_upload_max_retries"><code id="build_event_upload_max_retries"><a href="#build-flag--build_event_upload_max_retries">--build_event_upload_max_retries</a>=<an integer></code> default: "4"</dt> -<dd> -<p>The maximum number of times Bazel should retry uploading a build event.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="build-flag--debug_spawn_scheduler"><code id="debug_spawn_scheduler"><a href="#build-flag--debug_spawn_scheduler">--[no]debug_spawn_scheduler</a></code> default: "false"</dt> -<dd> -</dd> -<dt id="build-flag--experimental_bep_target_summary"><code id="experimental_bep_target_summary"><a href="#build-flag--experimental_bep_target_summary">--[no]experimental_bep_target_summary</a></code> default: "false"</dt> -<dd> -<p>Whether to publish TargetSummary events.</p> -</dd> -<dt id="build-flag--experimental_build_event_expand_filesets"><code id="experimental_build_event_expand_filesets"><a href="#build-flag--experimental_build_event_expand_filesets">--[no]experimental_build_event_expand_filesets</a></code> default: "false"</dt> -<dd> -<p>If true, expand Filesets in the BEP when presenting output files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--experimental_build_event_output_group_mode"><code id="experimental_build_event_output_group_mode"><a href="#build-flag--experimental_build_event_output_group_mode">--experimental_build_event_output_group_mode</a>=<an output group name followed by an OutputGroupFileMode, e.g. default=both></code> multiple uses are accumulated</dt> -<dd> -<p>Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED_SET_OF_FILES_ONLY', 'INLINE_ONLY', or 'BOTH'. The default value is 'NAMED_SET_OF_FILES_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental_build_event_output_group_mode=baseline.lcov=both</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--experimental_build_event_upload_retry_minimum_delay"><code id="experimental_build_event_upload_retry_minimum_delay"><a href="#build-flag--experimental_build_event_upload_retry_minimum_delay">--experimental_build_event_upload_retry_minimum_delay</a>=<An immutable length of time.></code> default: "1s"</dt> -<dd> -<p>Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6)</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="build-flag--experimental_build_event_upload_strategy"><code id="experimental_build_event_upload_strategy"><a href="#build-flag--experimental_build_event_upload_strategy">--experimental_build_event_upload_strategy</a>=<a string></code> default: see description</dt> -<dd> -<p>Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--experimental_docker_verbose"><code id="experimental_docker_verbose"><a href="#build-flag--experimental_docker_verbose">--[no]experimental_docker_verbose</a></code> default: "false"</dt> -<dd> -<p>If enabled, Bazel will print more verbose messages about the Docker sandbox strategy.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_frontier_violation_check"><code id="experimental_frontier_violation_check"><a href="#build-flag--experimental_frontier_violation_check">--experimental_frontier_violation_check</a>=<strict, warn or disabled_for_testing></code> default: "strict"</dt> -<dd> -<p>Strategies to handle potential incorrectness from changes beyond the frontier (i.e. outside the active directories)</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="build-flag--experimental_frontier_violation_verbose"><code id="experimental_frontier_violation_verbose"><a href="#build-flag--experimental_frontier_violation_verbose">--[no]experimental_frontier_violation_verbose</a></code> default: "false"</dt> -<dd> -<p>If true, Bazel will print instructions for fixing Skycache violations</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--experimental_materialize_param_files_directly"><code id="experimental_materialize_param_files_directly"><a href="#build-flag--experimental_materialize_param_files_directly">--[no]experimental_materialize_param_files_directly</a></code> default: "false"</dt> -<dd> -<p>If materializing param files, do so with direct writes to disk.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_run_bep_event_include_residue"><code id="experimental_run_bep_event_include_residue"><a href="#build-flag--experimental_run_bep_event_include_residue">--[no]experimental_run_bep_event_include_residue</a></code> default: "false"</dt> -<dd> -<p>Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--experimental_skyfocus_dump_keys"><code id="experimental_skyfocus_dump_keys"><a href="#build-flag--experimental_skyfocus_dump_keys">--experimental_skyfocus_dump_keys</a>=<none, count or verbose></code> default: "none"</dt> -<dd> -<p>For debugging Skyfocus. Dump the focused SkyKeys (roots, leafs, focused deps, focused rdeps).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--experimental_skyfocus_dump_post_gc_stats"><code id="experimental_skyfocus_dump_post_gc_stats"><a href="#build-flag--experimental_skyfocus_dump_post_gc_stats">--[no]experimental_skyfocus_dump_post_gc_stats</a></code> default: "false"</dt> -<dd> -<p>For debugging Skyfocus. If enabled, trigger manual GC before/after focusing to report heap sizes reductions. This will increase the Skyfocus latency.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--experimental_stream_log_file_uploads"><code id="experimental_stream_log_file_uploads"><a href="#build-flag--experimental_stream_log_file_uploads">--[no]experimental_stream_log_file_uploads</a></code> default: "false"</dt> -<dd> -<p>Stream log file uploads directly to the remote storage rather than writing them to disk.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--explain"><code id="explain"><a href="#build-flag--explain">--explain</a>=<a path></code> default: see description</dt> -<dd> -<p>Causes the build system to explain each executed step of the build. The explanation is written to the specified log file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--ignore_unsupported_sandboxing"><code id="ignore_unsupported_sandboxing"><a href="#build-flag--ignore_unsupported_sandboxing">--[no]ignore_unsupported_sandboxing</a></code> default: "false"</dt> -<dd> -<p>Do not print a warning when sandboxed execution is not supported on this system.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--legacy_important_outputs"><code id="legacy_important_outputs"><a href="#build-flag--legacy_important_outputs">--[no]legacy_important_outputs</a></code> default: "false"</dt> -<dd> -<p>Use this to suppress generation of the legacy important_outputs field in the TargetComplete event. important_outputs are required for Bazel to ResultStore/BTX integration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--materialize_param_files"><code id="materialize_param_files"><a href="#build-flag--materialize_param_files">--[no]materialize_param_files</a></code> default: "false"</dt> -<dd> -<p>Writes intermediate parameter files to output tree even when using remote action execution or caching. Useful when debugging actions. This is implied by --subcommands and --verbose_failures.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--max_config_changes_to_show"><code id="max_config_changes_to_show"><a href="#build-flag--max_config_changes_to_show">--max_config_changes_to_show</a>=<an integer></code> default: "3"</dt> -<dd> -<p>When discarding the analysis cache due to a change in the build options, displays up to the given number of changed option names. If the number given is -1, all changed options will be displayed.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--max_test_output_bytes"><code id="max_test_output_bytes"><a href="#build-flag--max_test_output_bytes">--max_test_output_bytes</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>Specifies maximum per-test-log size that can be emitted when --test_output is 'errors' or 'all'. Useful for avoiding overwhelming the output with excessively noisy test output. The test header is included in the log size. Negative values imply no limit. Output is all or nothing.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--output_filter"><code id="output_filter"><a href="#build-flag--output_filter">--output_filter</a>=<a valid Java regular expression></code> default: see description</dt> -<dd> -<p>Only shows warnings and action outputs for rules with a name matching the provided regular expression.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--progress_report_interval"><code id="progress_report_interval"><a href="#build-flag--progress_report_interval">--progress_report_interval</a>=<an integer in 0-3600 range></code> default: "0"</dt> -<dd> -<p>The number of seconds to wait between reports on still running jobs. The default value 0 means the first report will be printed after 10 seconds, then 30 seconds and after that progress is reported once every minute. When --curses is enabled, progress is reported every second.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--remote_analysis_json_log"><code id="remote_analysis_json_log"><a href="#build-flag--remote_analysis_json_log">--remote_analysis_json_log</a>=<a string></code> default: see description</dt> -<dd> -<p>If set, a JSON file is written to this location that contains a detailed log of the behavior of remote analysis caching. It's interpreted as a path relative to the current working directory.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="build-flag--remote_print_execution_messages"><code id="remote_print_execution_messages"><a href="#build-flag--remote_print_execution_messages">--remote_print_execution_messages</a>=<failure, success or all></code> default: "failure"</dt> -<dd> -<p>Choose when to print remote execution messages. Valid values are <code>failure</code>, to print only on failures, <code>success</code> to print only on successes and <code>all</code> to print always.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--sandbox_debug"><code id="sandbox_debug"><a href="#build-flag--sandbox_debug">--[no]sandbox_debug</a></code> default: "false"</dt> -<dd> -<p>Enables debugging features for the sandboxing feature. This includes two things: first, the sandbox root contents are left untouched after a build; and second, prints extra debugging information on execution. This can help developers of Bazel or Starlark rules with debugging failures due to missing input files, etc.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--show_result"><code id="show_result"><a href="#build-flag--show_result">--show_result</a>=<an integer></code> default: "1"</dt> -<dd> -<p>Show the results of the build. For each target, state whether or not it was brought up-to-date, and if so, a list of output files that were built. The printed files are convenient strings for copy+pasting to the shell, to execute them. -This option requires an integer argument, which is the threshold number of targets above which result information is not printed. Thus zero causes suppression of the message and MAX_INT causes printing of the result to occur always. The default is one. -If nothing was built for a target its results may be omitted to keep the output under the threshold.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--subcommands"><code id="subcommands"><a href="#build-flag--subcommands">--[no]subcommands</a></code> [<code>-s</code>] default: "false"</dt> -<dd> -<p>Display the subcommands executed during a build. Related flags: --execution_log_json_file, --execution_log_binary_file (for logging subcommands to a file in a tool-friendly format).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--test_output"><code id="test_output"><a href="#build-flag--test_output">--test_output</a>=<summary, errors, all or streamed></code> default: "summary"</dt> -<dd> -<p>Specifies desired output mode. Valid values are 'summary' to output only test status summary, 'errors' to also print test logs for failed tests, 'all' to print logs for all tests and 'streamed' to output logs for all tests in real time (this will force tests to be executed locally one at a time regardless of --test_strategy value).</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--test_summary"><code id="test_summary"><a href="#build-flag--test_summary">--test_summary</a>=<short, terse, detailed, none or testcase></code> default: "short"</dt> -<dd> -<p>Specifies the desired format of the test summary. Valid values are 'short' to print information only about tests executed, 'terse', to print information only about unsuccessful tests that were run, 'detailed' to print detailed information about failed test cases, 'testcase' to print summary in test case resolution, do not print detailed information about failed test cases and 'none' to omit the summary.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="build-flag--verbose_failures"><code id="verbose_failures"><a href="#build-flag--verbose_failures">--[no]verbose_failures</a></code> default: "false"</dt> -<dd> -<p>If a command fails, print out the full command line.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="build-flag--aspects_parameters"><code id="aspects_parameters"><a href="#build-flag--aspects_parameters">--aspects_parameters</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the values of the command-line aspects parameters. Each parameter value is specified via <param_name>=<param_value>, for example 'my_param=my_val' where 'my_param' is a parameter of some aspect in --aspects list or required by an aspect in the list. This option can be used multiple times. However, it is not allowed to assign values to the same parameter more than once.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="build-flag--target_pattern_file"><code id="target_pattern_file"><a href="#build-flag--target_pattern_file">--target_pattern_file</a>=<a string></code> default: ""</dt> -<dd> -<p>If set, build will read patterns from the file named here, rather than on the command line. It is an error to specify a file here as well as command-line patterns.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Remote caching and execution options: -<dt id="build-flag--experimental_circuit_breaker_strategy"><code id="experimental_circuit_breaker_strategy"><a href="#build-flag--experimental_circuit_breaker_strategy">--experimental_circuit_breaker_strategy</a>=<failure></code> default: see description</dt> -<dd> -<p>Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_remote_cache_compression_threshold"><code id="experimental_remote_cache_compression_threshold"><a href="#build-flag--experimental_remote_cache_compression_threshold">--experimental_remote_cache_compression_threshold</a>=<an integer></code> default: "100"</dt> -<dd> -<p>The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote_cache_compression is set.</p> -</dd> -<dt id="build-flag--experimental_remote_cache_eviction_retries"><code id="experimental_remote_cache_eviction_retries"><a href="#build-flag--experimental_remote_cache_eviction_retries">--experimental_remote_cache_eviction_retries</a>=<an integer></code> default: "5"</dt> -<dd> -<p>The maximum number of attempts to retry if the build encountered a transient remote cache error that would otherwise fail the build. Applies for example when artifacts are evicted from the remote cache, or in certain cache failure conditions. A new invocation id will be generated for each attempt.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_remote_cache_lease_extension"><code id="experimental_remote_cache_lease_extension"><a href="#build-flag--experimental_remote_cache_lease_extension">--[no]experimental_remote_cache_lease_extension</a></code> default: "false"</dt> -<dd> -<p>If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending <code>FindMissingBlobs</code> calls periodically to remote cache. The frequency is based on the value of <code>--experimental_remote_cache_ttl</code>.</p> -</dd> -<dt id="build-flag--experimental_remote_cache_ttl"><code id="experimental_remote_cache_ttl"><a href="#build-flag--experimental_remote_cache_ttl">--experimental_remote_cache_ttl</a>=<An immutable length of time.></code> default: "3h"</dt> -<dd> -<p>The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_remote_capture_corrupted_outputs"><code id="experimental_remote_capture_corrupted_outputs"><a href="#build-flag--experimental_remote_capture_corrupted_outputs">--experimental_remote_capture_corrupted_outputs</a>=<a path></code> default: see description</dt> -<dd> -<p>A path to a directory where the corrupted outputs will be captured to.</p> -</dd> -<dt id="build-flag--experimental_remote_discard_merkle_trees"><code id="experimental_remote_discard_merkle_trees"><a href="#build-flag--experimental_remote_discard_merkle_trees">--[no]experimental_remote_discard_merkle_trees</a></code> default: "true"</dt> -<dd> -<p>If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries.</p> -</dd> -<dt id="build-flag--experimental_remote_downloader"><code id="experimental_remote_downloader"><a href="#build-flag--experimental_remote_downloader">--experimental_remote_downloader</a>=<a string></code> default: see description</dt> -<dd> -<p>A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote_asset.proto</p> -</dd> -<dt id="build-flag--experimental_remote_downloader_local_fallback"><code id="experimental_remote_downloader_local_fallback"><a href="#build-flag--experimental_remote_downloader_local_fallback">--[no]experimental_remote_downloader_local_fallback</a></code> default: "false"</dt> -<dd> -<p>Whether to fall back to the local downloader if remote downloader fails.</p> -</dd> -<dt id="build-flag--experimental_remote_downloader_propagate_credentials"><code id="experimental_remote_downloader_propagate_credentials"><a href="#build-flag--experimental_remote_downloader_propagate_credentials">--[no]experimental_remote_downloader_propagate_credentials</a></code> default: "false"</dt> -<dd> -<p>Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new <code>http_header_url:&lt;url-index&gt;:&lt;header-key&gt;</code> qualifier where the <code>&lt;url-index&gt;</code> is a 0-based position of the URL inside the FetchBlobRequest's <code>uris</code> field. The URL-specific headers should take precedence over the global headers.</p> -</dd> -<dt id="build-flag--experimental_remote_execution_keepalive"><code id="experimental_remote_execution_keepalive"><a href="#build-flag--experimental_remote_execution_keepalive">--[no]experimental_remote_execution_keepalive</a></code> default: "false"</dt> -<dd> -<p>Whether to use keepalive for remote execution calls.</p> -</dd> -<dt id="build-flag--experimental_remote_failure_rate_threshold"><code id="experimental_remote_failure_rate_threshold"><a href="#build-flag--experimental_remote_failure_rate_threshold">--experimental_remote_failure_rate_threshold</a>=<an integer in 0-100 range></code> default: "10"</dt> -<dd> -<p>Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_remote_failure_window_interval"><code id="experimental_remote_failure_window_interval"><a href="#build-flag--experimental_remote_failure_window_interval">--experimental_remote_failure_window_interval</a>=<An immutable length of time.></code> default: "60s"</dt> -<dd> -<p>The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--experimental_remote_mark_tool_inputs"><code id="experimental_remote_mark_tool_inputs"><a href="#build-flag--experimental_remote_mark_tool_inputs">--[no]experimental_remote_mark_tool_inputs</a></code> default: "false"</dt> -<dd> -<p>If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers.</p> -</dd> -<dt id="build-flag--experimental_remote_merkle_tree_cache"><code id="experimental_remote_merkle_tree_cache"><a href="#build-flag--experimental_remote_merkle_tree_cache">--[no]experimental_remote_merkle_tree_cache</a></code> default: "false"</dt> -<dd> -<p>If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental_remote_merkle_tree_cache_size.</p> -</dd> -<dt id="build-flag--experimental_remote_merkle_tree_cache_size"><code id="experimental_remote_merkle_tree_cache_size"><a href="#build-flag--experimental_remote_merkle_tree_cache_size">--experimental_remote_merkle_tree_cache_size</a>=<a long integer></code> default: "1000"</dt> -<dd> -<p>The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000.</p> -</dd> -<dt id="build-flag--experimental_remote_output_service"><code id="experimental_remote_output_service"><a href="#build-flag--experimental_remote_output_service">--experimental_remote_output_service</a>=<a string></code> default: see description</dt> -<dd> -<p>HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS.</p> -</dd> -<dt id="build-flag--experimental_remote_output_service_output_path_prefix"><code id="experimental_remote_output_service_output_path_prefix"><a href="#build-flag--experimental_remote_output_service_output_path_prefix">--experimental_remote_output_service_output_path_prefix</a>=<a string></code> default: ""</dt> -<dd> -<p>The path under which the contents of output directories managed by the --experimental_remote_output_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service.</p> -</dd> -<dt id="build-flag--experimental_remote_require_cached"><code id="experimental_remote_require_cached"><a href="#build-flag--experimental_remote_require_cached">--[no]experimental_remote_require_cached</a></code> default: "false"</dt> -<dd> -<p>If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache.</p> -</dd> -<dt id="build-flag--experimental_remote_scrubbing_config"><code id="experimental_remote_scrubbing_config"><a href="#build-flag--experimental_remote_scrubbing_config">--experimental_remote_scrubbing_config</a>=<Converts to a Scrubber></code> default: see description</dt> -<dd> -<p>Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote_scrubbing.proto).</p> -<p>This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds.</p> -<p>Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead.</p> -<p>Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions.</p> -<p>In order to successfully use this feature, you likely want to set a custom --host_platform together with --experimental_platform_in_output_dir (to normalize output prefixes) and --incompatible_strict_action_env (to normalize environment variables).</p> -</dd> -<dt id="build-flag--guard_against_concurrent_changes"><code id="guard_against_concurrent_changes"><a href="#build-flag--guard_against_concurrent_changes">--[no]guard_against_concurrent_changes</a></code> default: "lite"</dt> -<dd> -<p>Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="build-flag--remote_accept_cached"><code id="remote_accept_cached"><a href="#build-flag--remote_accept_cached">--[no]remote_accept_cached</a></code> default: "true"</dt> -<dd> -<p>Whether to accept remotely cached action results.</p> -</dd> -<dt id="build-flag--remote_build_event_upload"><code id="remote_build_event_upload"><a href="#build-flag--remote_build_event_upload">--remote_build_event_upload</a>=<all or minimal></code> default: "minimal"</dt> -<dd> -<p>If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. +by hashes stored in the registry (and thus pinned by the lockfile). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--override_module`](#common_options-flag--override_module)`=<an equals-separated mapping of module name to path>` multiple uses are accumulated +Override a module with a local path in the form of \<module name\>=\<path\>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. + +[`--registry`](#common_options-flag--registry)`=<a string>` multiple uses are accumulated +Specifies the registries to use to locate Bazel module dependencies. The order is important: modules will be looked up in earlier registries first, and only fall back to later registries when they're missing from the earlier ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--vendor_dir`](#common_options-flag--vendor_dir)`=<a path>` default: see description +Specifies the directory that should hold the external repositories in vendor mode, whether for the purpose of fetching them into it or using them while building. The path can be specified as either an absolute path or a path relative to the workspace directory. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--gc_thrashing_limits`](#common_options-flag--gc_thrashing_limits)`=<comma separated pairs of <period>:<count>>` default: "1s:2,20s:3,1m:5" +Limits which, if reached, cause GcThrashingDetector to crash Bazel with an OOM. Each limit is specified as \<period\>:\<count\> where period is a duration and count is a positive integer. If more than --gc_thrashing_threshold percent of tenured space (old gen heap) remains occupied after \<count\> consecutive full GCs within \<period\>, an OOM is triggered. Multiple limits can be specified separated by commas. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]heuristically_drop_nodes`](#common_options-flag--heuristically_drop_nodes) default: "false" +If true, Blaze will remove FileState and DirectoryListingState nodes after related File and DirectoryListing node is done to save memory. We expect that it is less likely that these nodes will be needed again. If so, the program will re-evaluate them. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]incompatible_do_not_split_linking_cmdline`](#common_options-flag--incompatible_do_not_split_linking_cmdline) default: "true" +When true, Bazel no longer modifies command line flags used for linking, and also doesn't selectively decide which flags go to the param file and which don't. See https://github.com/bazelbuild/bazel/issues/7670 for details. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]keep_state_after_build`](#common_options-flag--keep_state_after_build) default: "true" +If false, Blaze will discard the inmemory state from this build when the build finishes. Subsequent builds will not have any incrementality with respect to this one. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--skyframe_high_water_mark_full_gc_drops_per_invocation`](#common_options-flag--skyframe_high_water_mark_full_gc_drops_per_invocation)`=<an integer, >= 0>` default: "10" +Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe_high_water_mark_threshold, when a full GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that full GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a full GC event occurs and that retained heap percentage threshold is exceeded. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--skyframe_high_water_mark_minor_gc_drops_per_invocation`](#common_options-flag--skyframe_high_water_mark_minor_gc_drops_per_invocation)`=<an integer, >= 0>` default: "10" +Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe_high_water_mark_threshold, when a minor GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that minor GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a minor GC event occurs and that retained heap percentage threshold is exceeded. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--skyframe_high_water_mark_threshold`](#common_options-flag--skyframe_high_water_mark_threshold)`=<an integer>` default: "85" +Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage is at least this threshold, it will drop unnecessary temporary Skyframe state. Tweaking this may let you mitigate wall time impact of GC thrashing, when the GC thrashing is (i) caused by the memory usage of this temporary state and (ii) more costly than reconstituting the state when it is needed. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]track_incremental_state`](#common_options-flag--track_incremental_state) default: "true" +If false, Blaze will not persist data that allows for invalidation and re-evaluation on incremental builds in order to save memory on this build. Subsequent builds will not have any incrementality with respect to this one. Usually you will want to specify --batch when setting this to false. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +<!-- --> + +[`--[no]announce_rc`](#common_options-flag--announce_rc) default: "false" +Whether to announce rc options. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]attempt_to_print_relative_paths`](#common_options-flag--attempt_to_print_relative_paths) default: "false" +When printing the location part of messages, attempt to use a path relative to the workspace directory or one of the directories specified by --package_path. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--bes_backend`](#common_options-flag--bes_backend)`=<a string>` default: "" +Specifies the build event service (BES) backend endpoint in the form \[SCHEME://\]HOST\[:PORT\]. The default is to disable BES uploads. Supported schemes are grpc and grpcs (grpc with TLS enabled). If no scheme is provided, Bazel assumes grpcs. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]bes_check_preceding_lifecycle_events`](#common_options-flag--bes_check_preceding_lifecycle_events) default: "false" +Sets the field check_preceding_lifecycle_events_present on PublishBuildToolEventStreamRequest which tells BES to check whether it previously received InvocationAttemptStarted and BuildEnqueued events matching the current tool event. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--bes_header`](#common_options-flag--bes_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header in NAME=VALUE form that will be included in BES requests. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--bes_instance_name`](#common_options-flag--bes_instance_name)`=<a string>` default: see description +Specifies the instance name under which the BES will persist uploaded BEP. Defaults to null. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--bes_keywords`](#common_options-flag--bes_keywords)`=<comma-separated list of options>` multiple uses are accumulated +Specifies a list of notification keywords to be added the default set of keywords published to BES ("command_name=\<command_name\> ", "protocol_name=BEP"). Defaults to none. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]bes_lifecycle_events`](#common_options-flag--bes_lifecycle_events) default: "true" +Specifies whether to publish BES lifecycle events. (defaults to 'true'). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--bes_oom_finish_upload_timeout`](#common_options-flag--bes_oom_finish_upload_timeout)`=<An immutable length of time.>` default: "10m" +Specifies how long bazel should wait for the BES/BEP upload to complete while OOMing. This flag ensures termination when the JVM is severely GC thrashing and cannot make progress on any user thread. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--bes_outerr_buffer_size`](#common_options-flag--bes_outerr_buffer_size)`=<an integer>` default: "10240" +Specifies the maximal size of stdout or stderr to be buffered in BEP, before it is reported as a progress event. Individual writes are still reported in a single event, even if larger than the specified value up to --bes_outerr_chunk_size. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--bes_outerr_chunk_size`](#common_options-flag--bes_outerr_chunk_size)`=<an integer>` default: "1048576" +Specifies the maximal size of stdout or stderr to be sent to BEP in a single message. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--bes_proxy`](#common_options-flag--bes_proxy)`=<a string>` default: see description +Connect to the Build Event Service through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). + +[`--bes_results_url`](#common_options-flag--bes_results_url)`=<a string>` default: "" +Specifies the base URL where a user can view the information streamed to the BES backend. Bazel will output the URL appended by the invocation id to the terminal. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--bes_system_keywords`](#common_options-flag--bes_system_keywords)`=<comma-separated list of options>` multiple uses are accumulated +Specifies a list of notification keywords to be included directly, without the "user_keyword=" prefix included for keywords supplied via --bes_keywords. Intended for Build service operators that set --bes_lifecycle_events=false and include keywords when calling PublishLifecycleEvent. Build service operators using this flag should prevent users from overriding the flag value. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--bes_timeout`](#common_options-flag--bes_timeout)`=<An immutable length of time.>` default: "0s" +Specifies how long bazel should wait for the BES/BEP upload to complete after the build and tests have finished. A valid timeout is a natural number followed by a unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The default value is '0' which means that there is no timeout. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--bes_upload_mode`](#common_options-flag--bes_upload_mode)`=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait_for_upload_complete" +Specifies whether the Build Event Service upload should block the build completion or should end the invocation immediately and finish the upload in the background. + +- `wait_for_upload_complete`: blocks at the end of the current invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. +- `nowait_for_upload_complete`: blocks at the beginning of the next invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. +- `fully_async`: blocks at the beginning of the next invocation until all events are uploaded but does not wait for acknowledgements. Events may be lost in case of (transient) failures and backends may report streams as incomplete in this mode. There is no guarantee that `FinishInvocationAttempt` or `FinishBuild` lifecycle events are sent. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--build_event_binary_file`](#common_options-flag--build_event_binary_file)`=<a string>` default: "" +If non-empty, write a varint delimited binary representation of representation of the build event protocol to that file. This option implies --bes_upload_mode=wait_for_upload_complete. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_event_binary_file_path_conversion`](#common_options-flag--build_event_binary_file_path_conversion) default: "true" +Convert paths in the binary file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--build_event_binary_file_upload_mode`](#common_options-flag--build_event_binary_file_upload_mode)`=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait_for_upload_complete" +Specifies whether the Build Event Service upload for --build_event_binary_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--build_event_json_file`](#common_options-flag--build_event_json_file)`=<a string>` default: "" +If non-empty, write a JSON serialisation of the build event protocol to that file. This option implies --bes_upload_mode=wait_for_upload_complete. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_event_json_file_path_conversion`](#common_options-flag--build_event_json_file_path_conversion) default: "true" +Convert paths in the json file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--build_event_json_file_upload_mode`](#common_options-flag--build_event_json_file_upload_mode)`=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait_for_upload_complete" +Specifies whether the Build Event Service upload for --build_event_json_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--build_event_max_named_set_of_file_entries`](#common_options-flag--build_event_max_named_set_of_file_entries)`=<an integer>` default: "5000" +The maximum number of entries for a single named_set_of_files event; values smaller than 2 are ignored and no event splitting is performed. This is intended for limiting the maximum event size in the build event protocol, although it does not directly control event size. The total event size is a function of the structure of the set as well as the file and uri lengths, which may in turn depend on the hash function. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_event_publish_all_actions`](#common_options-flag--build_event_publish_all_actions) default: "false" +Whether all actions should be published. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--build_event_text_file`](#common_options-flag--build_event_text_file)`=<a string>` default: "" +If non-empty, write a textual representation of the build event protocol to that file + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_event_text_file_path_conversion`](#common_options-flag--build_event_text_file_path_conversion) default: "true" +Convert paths in the text file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--build_event_text_file_upload_mode`](#common_options-flag--build_event_text_file_upload_mode)`=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait_for_upload_complete" +Specifies whether the Build Event Service upload for --build_event_text_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--build_event_upload_max_retries`](#common_options-flag--build_event_upload_max_retries)`=<an integer>` default: "4" +The maximum number of times Bazel should retry uploading a build event. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--[no]experimental_bep_target_summary`](#common_options-flag--experimental_bep_target_summary) default: "false" +Whether to publish TargetSummary events. + +[`--[no]experimental_build_event_expand_filesets`](#common_options-flag--experimental_build_event_expand_filesets) default: "false" +If true, expand Filesets in the BEP when presenting output files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--experimental_build_event_output_group_mode`](#common_options-flag--experimental_build_event_output_group_mode)`=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated +Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED_SET_OF_FILES_ONLY', 'INLINE_ONLY', or 'BOTH'. The default value is 'NAMED_SET_OF_FILES_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental_build_event_output_group_mode=baseline.lcov=both + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--experimental_build_event_upload_retry_minimum_delay`](#common_options-flag--experimental_build_event_upload_retry_minimum_delay)`=<An immutable length of time.>` default: "1s" +Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--experimental_build_event_upload_strategy`](#common_options-flag--experimental_build_event_upload_strategy)`=<a string>` default: see description +Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_collect_load_average_in_profiler`](#common_options-flag--experimental_collect_load_average_in_profiler) default: "true" +If enabled, the profiler collects the system's overall load average. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_collect_pressure_stall_indicators`](#common_options-flag--experimental_collect_pressure_stall_indicators) default: "false" +If enabled, the profiler collects the Linux PSI data. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_collect_resource_estimation`](#common_options-flag--experimental_collect_resource_estimation) default: "false" +If enabled, the profiler collects CPU and memory usage estimation for local actions. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_collect_skyframe_counts_in_profiler`](#common_options-flag--experimental_collect_skyframe_counts_in_profiler) default: "false" +If enabled, the profiler collects SkyFunction counts in the Skyframe graph over time for key function types, like configured targets and action executions. May have a performance hit as this visits the ENTIRE Skyframe graph at every profiling time unit. Do not use this flag with performance-critical measurements. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_collect_system_network_usage`](#common_options-flag--experimental_collect_system_network_usage) default: "true" +If enabled, the profiler collects the system's network usage. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_collect_worker_data_in_profiler`](#common_options-flag--experimental_collect_worker_data_in_profiler) default: "true" +If enabled, the profiler collects worker's aggregated resource data. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--experimental_command_profile`](#common_options-flag--experimental_command_profile)`=<cpu, wall, alloc or lock>` default: see description +Records a Java Flight Recorder profile for the duration of the command. One of the supported profiling event types (cpu, wall, alloc or lock) must be given as an argument. The profile is written to a file named after the event type under the output base directory. The syntax and semantics of this flag might change in the future to support additional profile types or output formats; use at your own risk. + +[`--experimental_profile_additional_tasks`](#common_options-flag--experimental_profile_additional_tasks)`=<phase, action, discover_inputs, action_check, action_lock, action_update, action_complete, action_rewinding, bzlmod, info, create_package, remote_execution, local_execution, scanner, local_parse, upload_time, remote_process_time, remote_queue, remote_setup, fetch, local_process_time, vfs_stat, vfs_dir, vfs_readlink, vfs_md5, vfs_xattr, vfs_delete, vfs_open, vfs_read, vfs_write, vfs_glob, vfs_vmfs_stat, vfs_vmfs_dir, vfs_vmfs_read, wait, thread_name, thread_sort_index, skyframe_eval, skyfunction, critical_path, critical_path_component, handle_gc_notification, local_action_counts, starlark_parser, starlark_user_fn, starlark_builtin_fn, starlark_user_compiled_fn, starlark_repository_fn, action_fs_staging, remote_cache_check, remote_download, remote_network, filesystem_traversal, worker_execution, worker_setup, worker_borrow, worker_working, worker_copying_outputs, credential_helper, conflict_check, dynamic_lock, repository_fetch, repository_vendor, repo_cache_gc_wait, spawn_log, rpc, skycache, wasm_load, wasm_exec or unknown>` multiple uses are accumulated +Specifies additional profile tasks to be included in the profile. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_profile_include_primary_output`](#common_options-flag--experimental_profile_include_primary_output) default: "false" +Includes the extra "out" attribute in action events that contains the exec path to the action's primary output. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_profile_include_target_configuration`](#common_options-flag--experimental_profile_include_target_configuration) default: "false" +Includes target configuration hash in action events' JSON profile data. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_profile_include_target_label`](#common_options-flag--experimental_profile_include_target_label) default: "false" +Includes target label in action events' JSON profile data. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_record_metrics_for_all_mnemonics`](#common_options-flag--experimental_record_metrics_for_all_mnemonics) default: "false" +Controls the output of BEP ActionSummary and BuildGraphMetrics, limiting the number of mnemonics in ActionData and number of entries reported in BuildGraphMetrics.AspectCount/RuleClassCount. By default the number of types is limited to the top 20, by number of executed actions for ActionData, and instances for RuleClass and Asepcts. Setting this option will write statistics for all mnemonics, rule classes and aspects. + +[`--[no]experimental_record_skyframe_metrics`](#common_options-flag--experimental_record_skyframe_metrics) default: "false" +Controls the output of BEP BuildGraphMetrics, including expensiveto compute skyframe metrics about Skykeys, RuleClasses and Aspects.With this flag set to false BuildGraphMetrics.rule_count and aspectfields will not be populated in the BEP. + +[`--[no]experimental_run_bep_event_include_residue`](#common_options-flag--experimental_run_bep_event_include_residue) default: "false" +Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_stream_log_file_uploads`](#common_options-flag--experimental_stream_log_file_uploads) default: "false" +Stream log file uploads directly to the remote storage rather than writing them to disk. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--experimental_workspace_rules_log_file`](#common_options-flag--experimental_workspace_rules_log_file)`=<a path>` default: see description +Log certain Workspace Rules events into this file as delimited WorkspaceEvent protos. + +[`--[no]generate_json_trace_profile`](#common_options-flag--generate_json_trace_profile) default: "auto" +If enabled, Bazel profiles the build and writes a JSON-format profile into a file in the output base. View profile by loading into chrome://tracing. By default Bazel writes the profile for all build-like commands and query. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]heap_dump_on_oom`](#common_options-flag--heap_dump_on_oom) default: "false" +Whether to manually output a heap dump if an OOM is thrown (including manual OOMs due to reaching --gc_thrashing_limits). The dump will be written to \<output_base\>/\<invocation_id\>.heapdump.hprof. This option effectively replaces -XX:+HeapDumpOnOutOfMemoryError, which has no effect for manual OOMs. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--jvm_heap_histogram_internal_object_pattern`](#common_options-flag--jvm_heap_histogram_internal_object_pattern)`=<a valid Java regular expression>` default: "jdk\\internal\\vm\\Filler.+" +Regex for overriding the matching logic for JDK21+ JVM heap memory collection. We are relying on volatile internal G1 GC implemenation details to get a clean memory metric, this option allows us to adapt to changes in that internal implementation without having to wait for a binary release. Passed to JDK Matcher.find() + +[`--[no]legacy_important_outputs`](#common_options-flag--legacy_important_outputs) default: "false" +Use this to suppress generation of the legacy important_outputs field in the TargetComplete event. important_outputs are required for Bazel to ResultStore/BTX integration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--logging`](#common_options-flag--logging)`=<0 <= an integer <= 6>` default: "3" +The logging level. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--memory_profile`](#common_options-flag--memory_profile)`=<a path>` default: see description +If set, write memory usage data to the specified file at phase ends and stable heap to master log at end of build. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--memory_profile_stable_heap_parameters`](#common_options-flag--memory_profile_stable_heap_parameters)`=<integers, separated by a comma expected in pairs>` default: "1,0" +Tune memory profile's computation of stable heap at end of build. Should be and even number of integers separated by commas. In each pair the first integer is the number of GCs to perform. The second integer in each pair is the number of seconds to wait between GCs. Ex: 2,4,4,0 would 2 GCs with a 4sec pause, followed by 4 GCs with zero second pause + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--profile`](#common_options-flag--profile)`=<a path>` default: see description +If set, profile Bazel and write data to the specified file. See https://bazel.build/advanced/performance/json-trace-profile for more information. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--profiles_to_retain`](#common_options-flag--profiles_to_retain)`=<an integer>` default: "5" +Number of profiles to retain in the output base. If there are more than this number of profiles in the output base, the oldest are deleted until the total is under the limit. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]record_full_profiler_data`](#common_options-flag--record_full_profiler_data) default: "false" +By default, Bazel profiler will record only aggregated data for fast but numerous events (such as statting the file). If this option is enabled, profiler will record each event - resulting in more precise profiling data but LARGE performance hit. Option only has effect if --profile used as well. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]redirect_local_instrumentation_output_writes`](#common_options-flag--redirect_local_instrumentation_output_writes) default: "false" +If true and supported, instrumentation output is redirected to be written locally on a different machine than where bazel is running on. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--remote_print_execution_messages`](#common_options-flag--remote_print_execution_messages)`=<failure, success or all>` default: "failure" +Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]slim_profile`](#common_options-flag--slim_profile) default: "true" +Slims down the size of the JSON profile by merging events if the profile gets too large. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--starlark_cpu_profile`](#common_options-flag--starlark_cpu_profile)`=<a string>` default: "" +Writes into the specified file a pprof profile of CPU usage by all Starlark threads. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--tool_tag`](#common_options-flag--tool_tag)`=<a string>` default: "" +A tool name to attribute this Bazel invocation to. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--ui_event_filters`](#common_options-flag--ui_event_filters)`=<Convert list of comma separated event kind to list of filters>` multiple uses are accumulated +Specifies which events to show in the UI. It is possible to add or remove events to the default ones using leading +/-, or override the default set completely with direct assignment. The set of supported event kinds include INFO, DEBUG, ERROR and more. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]write_command_log`](#common_options-flag--write_command_log) default: "false" +Whether or not to write the command.log file + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +<!-- --> + +[`--downloader_config`](#common_options-flag--downloader_config)`=<a path>` default: see description +Specify a file to configure the remote downloader with. This file consists of lines, each of which starts with a directive (`allow`, `block` or `rewrite`) followed by either a host name (for `allow` and `block`) or two patterns, one to match against, and one to use as a substitute URL, with back-references starting from `$1`. It is possible for multiple `rewrite` directives for the same URL to be given, and in this case multiple URLs will be returned. + +[`--experimental_circuit_breaker_strategy`](#common_options-flag--experimental_circuit_breaker_strategy)`=<failure>` default: see description +Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_remote_cache_compression_threshold`](#common_options-flag--experimental_remote_cache_compression_threshold)`=<an integer>` default: "100" +The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote_cache_compression is set. + +[`--[no]experimental_remote_cache_lease_extension`](#common_options-flag--experimental_remote_cache_lease_extension) default: "false" +If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. + +[`--experimental_remote_cache_ttl`](#common_options-flag--experimental_remote_cache_ttl)`=<An immutable length of time.>` default: "3h" +The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_remote_capture_corrupted_outputs`](#common_options-flag--experimental_remote_capture_corrupted_outputs)`=<a path>` default: see description +A path to a directory where the corrupted outputs will be captured to. + +[`--[no]experimental_remote_discard_merkle_trees`](#common_options-flag--experimental_remote_discard_merkle_trees) default: "true" +If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. + +[`--experimental_remote_downloader`](#common_options-flag--experimental_remote_downloader)`=<a string>` default: see description +A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote_asset.proto + +[`--[no]experimental_remote_downloader_local_fallback`](#common_options-flag--experimental_remote_downloader_local_fallback) default: "false" +Whether to fall back to the local downloader if remote downloader fails. + +[`--[no]experimental_remote_downloader_propagate_credentials`](#common_options-flag--experimental_remote_downloader_propagate_credentials) default: "false" +Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. + +[`--[no]experimental_remote_execution_keepalive`](#common_options-flag--experimental_remote_execution_keepalive) default: "false" +Whether to use keepalive for remote execution calls. + +[`--experimental_remote_failure_rate_threshold`](#common_options-flag--experimental_remote_failure_rate_threshold)`=<an integer in 0-100 range>` default: "10" +Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_remote_failure_window_interval`](#common_options-flag--experimental_remote_failure_window_interval)`=<An immutable length of time.>` default: "60s" +The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_remote_mark_tool_inputs`](#common_options-flag--experimental_remote_mark_tool_inputs) default: "false" +If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. + +[`--[no]experimental_remote_merkle_tree_cache`](#common_options-flag--experimental_remote_merkle_tree_cache) default: "false" +If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental_remote_merkle_tree_cache_size. + +[`--experimental_remote_merkle_tree_cache_size`](#common_options-flag--experimental_remote_merkle_tree_cache_size)`=<a long integer>` default: "1000" +The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. + +[`--experimental_remote_output_service`](#common_options-flag--experimental_remote_output_service)`=<a string>` default: see description +HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. + +[`--experimental_remote_output_service_output_path_prefix`](#common_options-flag--experimental_remote_output_service_output_path_prefix)`=<a string>` default: "" +The path under which the contents of output directories managed by the --experimental_remote_output_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. + +[`--[no]experimental_remote_require_cached`](#common_options-flag--experimental_remote_require_cached) default: "false" +If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. + +[`--experimental_remote_scrubbing_config`](#common_options-flag--experimental_remote_scrubbing_config)`=<Converts to a Scrubber>` default: see description +Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote_scrubbing.proto). + +This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. + +Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. + +Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. + +In order to successfully use this feature, you likely want to set a custom --host_platform together with --experimental_platform_in_output_dir (to normalize output prefixes) and --incompatible_strict_action_env (to normalize environment variables). + +[`--[no]guard_against_concurrent_changes`](#common_options-flag--guard_against_concurrent_changes) default: "lite" +Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]remote_accept_cached`](#common_options-flag--remote_accept_cached) default: "true" +Whether to accept remotely cached action results. + +[`--remote_build_event_upload`](#common_options-flag--remote_build_event_upload)`=<all or minimal>` default: "minimal" +If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. -Default to 'minimal'.</p> -</dd> -<dt id="build-flag--remote_bytestream_uri_prefix"><code id="remote_bytestream_uri_prefix"><a href="#build-flag--remote_bytestream_uri_prefix">--remote_bytestream_uri_prefix</a>=<a string></code> default: see description</dt> -<dd> -<p>The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote_executor and --remote_instance_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "${hostname}/${instance_name}".</p> -</dd> -<dt id="build-flag--remote_cache"><code id="remote_cache"><a href="#build-flag--remote_cache">--remote_cache</a>=<a string></code> default: see description</dt> -<dd> -<p>A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching</p> -</dd> -<dt id="build-flag--remote_cache_async"><code id="remote_cache_async"><a href="#build-flag--remote_cache_async">--[no]remote_cache_async</a></code> default: "true"</dt> -<dd> -<p>If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set.</p> -</dd> -<dt id="build-flag--remote_cache_compression"><code id="remote_cache_compression"><a href="#build-flag--remote_cache_compression">--[no]remote_cache_compression</a></code> default: "false"</dt> -<dd> -<p>If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental_remote_cache_compression_threshold.</p> -</dd> -<dt id="build-flag--remote_cache_header"><code id="remote_cache_header"><a href="#build-flag--remote_cache_header">--remote_cache_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header that will be included in cache requests: --remote_cache_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -</dd> -<dt id="build-flag--remote_default_exec_properties"><code id="remote_default_exec_properties"><a href="#build-flag--remote_default_exec_properties">--remote_default_exec_properties</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec_properties.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--remote_default_platform_properties"><code id="remote_default_platform_properties"><a href="#build-flag--remote_default_platform_properties">--remote_default_platform_properties</a>=<a string></code> default: ""</dt> -<dd> -<p>Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote_execution_properties. This value will also be used if the host platform is selected as the execution platform for remote execution.</p> -</dd> -<dt id="build-flag--remote_download_regex"><code id="remote_download_regex"><a href="#build-flag--remote_download_regex">--remote_download_regex</a>=<a valid Java regular expression></code> multiple uses are accumulated</dt> -<dd> -<p>Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote_download_outputs. Multiple patterns may be specified by repeating this flag.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="build-flag--remote_downloader_header"><code id="remote_downloader_header"><a href="#build-flag--remote_downloader_header">--remote_downloader_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header that will be included in remote downloader requests: --remote_downloader_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -</dd> -<dt id="build-flag--remote_exec_header"><code id="remote_exec_header"><a href="#build-flag--remote_exec_header">--remote_exec_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header that will be included in execution requests: --remote_exec_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -</dd> -<dt id="build-flag--remote_execution_priority"><code id="remote_execution_priority"><a href="#build-flag--remote_execution_priority">--remote_execution_priority</a>=<an integer></code> default: "0"</dt> -<dd> -<p>The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent.</p> -</dd> -<dt id="build-flag--remote_executor"><code id="remote_executor"><a href="#build-flag--remote_executor">--remote_executor</a>=<a string></code> default: see description</dt> -<dd> -<p>HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS.</p> -</dd> -<dt id="build-flag--remote_grpc_log"><code id="remote_grpc_log"><a href="#build-flag--remote_grpc_log">--remote_grpc_log</a>=<a path></code> default: see description</dt> -<dd> -<p>If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream).</p> -</dd> -<dt id="build-flag--remote_header"><code id="remote_header"><a href="#build-flag--remote_header">--remote_header</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Specify a header that will be included in requests: --remote_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list.</p> -</dd> -<dt id="build-flag--remote_instance_name"><code id="remote_instance_name"><a href="#build-flag--remote_instance_name">--remote_instance_name</a>=<a string></code> default: ""</dt> -<dd> -<p>Value to pass as instance_name in the remote execution API.</p> -</dd> -<dt id="build-flag--remote_local_fallback"><code id="remote_local_fallback"><a href="#build-flag--remote_local_fallback">--[no]remote_local_fallback</a></code> default: "false"</dt> -<dd> -<p>Whether to fall back to standalone local execution strategy if remote execution fails.</p> -</dd> -<dt id="build-flag--remote_local_fallback_strategy"><code id="remote_local_fallback_strategy"><a href="#build-flag--remote_local_fallback_strategy">--remote_local_fallback_strategy</a>=<a string></code> default: "local"</dt> -<dd> -<p>Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details.</p> -</dd> -<dt id="build-flag--remote_max_connections"><code id="remote_max_connections"><a href="#build-flag--remote_max_connections">--remote_max_connections</a>=<an integer></code> default: "100"</dt> -<dd> -<p>Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. +Default to 'minimal'. + +[`--remote_bytestream_uri_prefix`](#common_options-flag--remote_bytestream_uri_prefix)`=<a string>` default: see description +The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote_executor and --remote_instance_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "\${hostname}/\${instance_name}". + +[`--remote_cache`](#common_options-flag--remote_cache)`=<a string>` default: see description +A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching + +[`--[no]remote_cache_async`](#common_options-flag--remote_cache_async) default: "true" +If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. + +[`--[no]remote_cache_compression`](#common_options-flag--remote_cache_compression) default: "false" +If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental_remote_cache_compression_threshold. + +[`--remote_cache_header`](#common_options-flag--remote_cache_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header that will be included in cache requests: --remote_cache_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +[`--remote_default_exec_properties`](#common_options-flag--remote_default_exec_properties)`=<a 'name=value' assignment>` multiple uses are accumulated +Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec_properties. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_default_platform_properties`](#common_options-flag--remote_default_platform_properties)`=<a string>` default: "" +Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote_execution_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. + +[`--remote_download_regex`](#common_options-flag--remote_download_regex)`=<a valid Java regular expression>` multiple uses are accumulated +Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote_download_outputs. Multiple patterns may be specified by repeating this flag. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_downloader_header`](#common_options-flag--remote_downloader_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header that will be included in remote downloader requests: --remote_downloader_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +[`--remote_exec_header`](#common_options-flag--remote_exec_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header that will be included in execution requests: --remote_exec_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +[`--remote_execution_priority`](#common_options-flag--remote_execution_priority)`=<an integer>` default: "0" +The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. + +[`--remote_executor`](#common_options-flag--remote_executor)`=<a string>` default: see description +HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. + +[`--remote_grpc_log`](#common_options-flag--remote_grpc_log)`=<a path>` default: see description +If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). + +[`--remote_header`](#common_options-flag--remote_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header that will be included in requests: --remote_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +[`--remote_instance_name`](#common_options-flag--remote_instance_name)`=<a string>` default: "" +Value to pass as instance_name in the remote execution API. + +[`--[no]remote_local_fallback`](#common_options-flag--remote_local_fallback) default: "false" +Whether to fall back to standalone local execution strategy if remote execution fails. + +[`--remote_local_fallback_strategy`](#common_options-flag--remote_local_fallback_strategy)`=<a string>` default: "local" +Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. + +[`--remote_max_connections`](#common_options-flag--remote_max_connections)`=<an integer>` default: "100" +Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote_max_connections concurrent requests. -For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around <code>--remote_max_connections * 100</code> concurrent requests.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="build-flag--remote_proxy"><code id="remote_proxy"><a href="#build-flag--remote_proxy">--remote_proxy</a>=<a string></code> default: see description</dt> -<dd> -<p>Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket).</p> -</dd> -<dt id="build-flag--remote_result_cache_priority"><code id="remote_result_cache_priority"><a href="#build-flag--remote_result_cache_priority">--remote_result_cache_priority</a>=<an integer></code> default: "0"</dt> -<dd> -<p>The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent.</p> -</dd> -<dt id="build-flag--remote_retries"><code id="remote_retries"><a href="#build-flag--remote_retries">--remote_retries</a>=<an integer></code> default: "5"</dt> -<dd> -<p>The maximum number of attempts to retry a transient error. If set to 0, retries are disabled.</p> -</dd> -<dt id="build-flag--remote_retry_max_delay"><code id="remote_retry_max_delay"><a href="#build-flag--remote_retry_max_delay">--remote_retry_max_delay</a>=<An immutable length of time.></code> default: "5s"</dt> -<dd> -<p>The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> -</dd> -<dt id="build-flag--remote_timeout"><code id="remote_timeout"><a href="#build-flag--remote_timeout">--remote_timeout</a>=<An immutable length of time.></code> default: "60s"</dt> -<dd> -<p>The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds.</p> -</dd> -<dt id="build-flag--remote_upload_local_results"><code id="remote_upload_local_results"><a href="#build-flag--remote_upload_local_results">--[no]remote_upload_local_results</a></code> default: "true"</dt> -<dd> -<p>Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so.</p> -</dd> -<dt id="build-flag--remote_verify_downloads"><code id="remote_verify_downloads"><a href="#build-flag--remote_verify_downloads">--[no]remote_verify_downloads</a></code> default: "true"</dt> -<dd> -<p>If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value.</p> -</dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="build-flag--allow_analysis_cache_discard"><code id="allow_analysis_cache_discard"><a href="#build-flag--allow_analysis_cache_discard">--[no]allow_analysis_cache_discard</a></code> default: "true"</dt> -<dd> -<p>If discarding the analysis cache due to a change in the build system, setting this option to false will cause bazel to exit, rather than continuing with the build. This option has no effect when 'discard_analysis_cache' is also set.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="build-flag--auto_output_filter"><code id="auto_output_filter"><a href="#build-flag--auto_output_filter">--auto_output_filter</a>=<none, all, packages or subpackages></code> default: "none"</dt> -<dd> -<p>If --output_filter is not specified, then the value for this option is used create a filter automatically. Allowed values are 'none' (filter nothing / show everything), 'all' (filter everything / show nothing), 'packages' (include output from rules in packages mentioned on the Blaze command line), and 'subpackages' (like 'packages', but also include subpackages). For the 'packages' and 'subpackages' values //java/foo and //javatests/foo are treated as one package)'.</p> -</dd> -<dt id="build-flag--build_manual_tests"><code id="build_manual_tests"><a href="#build-flag--build_manual_tests">--[no]build_manual_tests</a></code> default: "false"</dt> -<dd> -<p>Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from processing. This option forces them to be built (but not executed).</p> -</dd> -<dt id="build-flag--build_tag_filters"><code id="build_tag_filters"><a href="#build-flag--build_tag_filters">--build_tag_filters</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>Specifies a comma-separated list of tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those targets will be built that contain at least one included tag and do not contain any excluded tags. This option does not affect the set of tests executed with the 'test' command; those are be governed by the test filtering options, for example '--test_tag_filters'</p> -</dd> -<dt id="build-flag--build_tests_only"><code id="build_tests_only"><a href="#build-flag--build_tests_only">--[no]build_tests_only</a></code> default: "false"</dt> -<dd> -<p>If specified, only *_test and test_suite rules will be built and other targets specified on the command line will be ignored. By default everything that was requested will be built.</p> -</dd> -<dt id="build-flag--combined_report"><code id="combined_report"><a href="#build-flag--combined_report">--combined_report</a>=<none or lcov></code> default: "lcov"</dt> -<dd> -<p>Specifies desired cumulative coverage report type. At this point only LCOV is supported.</p> -</dd> -<dt id="build-flag--compile_one_dependency"><code id="compile_one_dependency"><a href="#build-flag--compile_one_dependency">--[no]compile_one_dependency</a></code> default: "false"</dt> -<dd> -<p>Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single target that depends on the source file to detect errors as early as possible in the edit/build/test cycle. This argument affects the way all non-flag arguments are interpreted; instead of being targets to build they are source filenames. For each source filename an arbitrary target that depends on it will be built.</p> -</dd> -<dt id="build-flag--deleted_packages"><code id="deleted_packages"><a href="#build-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> -<dd> -<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> -</dd> -<dt id="build-flag--discard_analysis_cache"><code id="discard_analysis_cache"><a href="#build-flag--discard_analysis_cache">--[no]discard_analysis_cache</a></code> default: "false"</dt> -<dd> -<p>Discard the analysis cache immediately after the analysis phase completes. Reduces memory usage by ~10%, but makes further incremental builds slower.</p> -</dd> -<dt id="build-flag--disk_cache"><code id="disk_cache"><a href="#build-flag--disk_cache">--disk_cache</a>=<a path></code> default: see description</dt> -<dd> -<p>A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created.</p> -</dd> -<dt id="build-flag--embed_label"><code id="embed_label"><a href="#build-flag--embed_label">--embed_label</a>=<a one-line string></code> default: ""</dt> -<dd> -<p>Embed source control revision or release label in binary</p> -</dd> -<dt id="build-flag--execution_log_binary_file"><code id="execution_log_binary_file"><a href="#build-flag--execution_log_binary_file">--execution_log_binary_file</a>=<a path></code> default: see description</dt> -<dd> -<p>Log the executed spawns into this file as length-delimited SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution_log_compact_file, which is significantly smaller and cheaper to produce. Related flags: --execution_log_compact_file (compact format; mutually exclusive), --execution_log_json_file (text JSON format; mutually exclusive), --execution_log_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output).</p> -</dd> -<dt id="build-flag--execution_log_compact_file"><code id="execution_log_compact_file"><a href="#build-flag--execution_log_compact_file">--execution_log_compact_file</a>=<a path></code> default: see description</dt> -<dd> -<p>Log the executed spawns into this file as length-delimited ExecLogEntry protos, according to src/main/protobuf/spawn.proto. The entire file is zstd compressed. Related flags: --execution_log_binary_file (binary protobuf format; mutually exclusive), --execution_log_json_file (text JSON format; mutually exclusive), --subcommands (for displaying subcommands in terminal output).</p> -</dd> -<dt id="build-flag--execution_log_json_file"><code id="execution_log_json_file"><a href="#build-flag--execution_log_json_file">--execution_log_json_file</a>=<a path></code> default: see description</dt> -<dd> -<p>Log the executed spawns into this file as newline-delimited JSON representations of SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution_log_compact_file, which is significantly smaller and cheaper to produce. Related flags: --execution_log_compact_file (compact format; mutually exclusive), --execution_log_binary_file (binary protobuf format; mutually exclusive), --execution_log_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output).</p> -</dd> -<dt id="build-flag--execution_log_sort"><code id="execution_log_sort"><a href="#build-flag--execution_log_sort">--[no]execution_log_sort</a></code> default: "true"</dt> -<dd> -<p>Whether to sort the execution log, making it easier to compare logs across invocations. Set to false to avoid potentially significant CPU and memory usage at the end of the invocation, at the cost of producing the log in nondeterministic execution order. Only applies to the binary and JSON formats; the compact format is never sorted.</p> -</dd> -<dt id="build-flag--expand_test_suites"><code id="expand_test_suites"><a href="#build-flag--expand_test_suites">--[no]expand_test_suites</a></code> default: "true"</dt> -<dd> -<p>Expand test_suite targets into their constituent tests before analysis. When this flag is turned on (the default), negative target patterns will apply to the tests belonging to the test suite, otherwise they will not. Turning off this flag is useful when top-level aspects are applied at command line: then they can analyze test_suite targets.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="build-flag--experimental_disk_cache_gc_idle_delay"><code id="experimental_disk_cache_gc_idle_delay"><a href="#build-flag--experimental_disk_cache_gc_idle_delay">--experimental_disk_cache_gc_idle_delay</a>=<An immutable length of time.></code> default: "5m"</dt> -<dd> -<p>How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental_disk_cache_gc_max_size and/or --experimental_disk_cache_gc_max_age.</p> -</dd> -<dt id="build-flag--experimental_disk_cache_gc_max_age"><code id="experimental_disk_cache_gc_max_age"><a href="#build-flag--experimental_disk_cache_gc_max_age">--experimental_disk_cache_gc_max_age</a>=<An immutable length of time.></code> default: "0"</dt> -<dd> -<p>If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental_disk_cache_gc_max_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag.</p> -</dd> -<dt id="build-flag--experimental_disk_cache_gc_max_size"><code id="experimental_disk_cache_gc_max_size"><a href="#build-flag--experimental_disk_cache_gc_max_size">--experimental_disk_cache_gc_max_size</a>=<a size in bytes, optionally followed by a K, M, G or T multiplier></code> default: "0"</dt> -<dd> -<p>If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental_disk_cache_gc_max_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag.</p> -</dd> -<dt id="build-flag--experimental_extra_action_filter"><code id="experimental_extra_action_filter"><a href="#build-flag--experimental_extra_action_filter">--experimental_extra_action_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: ""</dt> -<dd> -<p>Deprecated in favor of aspects. Filters set of targets to schedule extra_actions for.</p> -</dd> -<dt id="build-flag--experimental_extra_action_top_level_only"><code id="experimental_extra_action_top_level_only"><a href="#build-flag--experimental_extra_action_top_level_only">--[no]experimental_extra_action_top_level_only</a></code> default: "false"</dt> -<dd> -<p>Deprecated in favor of aspects. Only schedules extra_actions for top level targets.</p> -</dd> -<dt id="build-flag--experimental_spawn_scheduler"><code id="experimental_spawn_scheduler"><a href="#build-flag--experimental_spawn_scheduler">--experimental_spawn_scheduler</a></code></dt> -<dd> -<p>Enable dynamic execution by running actions locally and remotely in parallel. Bazel spawns each action locally and remotely and picks the one that completes first. If an action supports workers, the local action will be run in the persistent worker mode. To enable dynamic execution for an individual action mnemonic, use the <code>--internal_spawn_scheduler</code> and <code>--strategy=&lt;mnemonic&gt;=dynamic</code> flags instead.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_spawn_scheduler">--internal_spawn_scheduler</a></code> -<br/>  <code><a href="#flag--spawn_strategy">--spawn_strategy=dynamic</a></code> -</p></dd> -<dt id="build-flag--fetch"><code id="fetch"><a href="#build-flag--fetch">--[no]fetch</a></code> default: "true"</dt> -<dd> -<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> -</dd> -<dt id="build-flag--local_termination_grace_seconds"><code id="local_termination_grace_seconds"><a href="#build-flag--local_termination_grace_seconds">--local_termination_grace_seconds</a>=<an integer></code> default: "15"</dt> -<dd> -<p>Time to wait between terminating a local process due to timeout and forcefully shutting it down.</p> -</dd> -<dt id="build-flag--package_path"><code id="package_path"><a href="#build-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> -<dd> -<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> -</dd> -<dt id="build-flag--show_loading_progress"><code id="show_loading_progress"><a href="#build-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> -<dd> -<p>If enabled, causes Bazel to print "Loading package:" messages.</p> -</dd> -<dt id="build-flag--test_lang_filters"><code id="test_lang_filters"><a href="#build-flag--test_lang_filters">--test_lang_filters</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>Specifies a comma-separated list of test languages. Each language can be optionally preceded with '-' to specify excluded languages. Only those test targets will be found that are written in the specified languages. The name used for each language should be the same as the language prefix in the *_test rule, e.g. one of 'cc', 'java', 'py', etc. This option affects --build_tests_only behavior and the test command.</p> -</dd> -<dt id="build-flag--test_size_filters"><code id="test_size_filters"><a href="#build-flag--test_size_filters">--test_size_filters</a>=<comma-separated list of values: small, medium, large, or enormous></code> default: ""</dt> -<dd> -<p>Specifies a comma-separated list of test sizes. Each size can be optionally preceded with '-' to specify excluded sizes. Only those test targets will be found that contain at least one included size and do not contain any excluded sizes. This option affects --build_tests_only behavior and the test command.</p> -</dd> -<dt id="build-flag--test_tag_filters"><code id="test_tag_filters"><a href="#build-flag--test_tag_filters">--test_tag_filters</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>Specifies a comma-separated list of test tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those test targets will be found that contain at least one included tag and do not contain any excluded tags. This option affects --build_tests_only behavior and the test command.</p> -</dd> -<dt id="build-flag--test_timeout_filters"><code id="test_timeout_filters"><a href="#build-flag--test_timeout_filters">--test_timeout_filters</a>=<comma-separated list of values: short, moderate, long, or eternal></code> default: ""</dt> -<dd> -<p>Specifies a comma-separated list of test timeouts. Each timeout can be optionally preceded with '-' to specify excluded timeouts. Only those test targets will be found that contain at least one included timeout and do not contain any excluded timeouts. This option affects --build_tests_only behavior and the test command.</p> -</dd> -<dt id="build-flag--workspace_status_command"><code id="workspace_status_command"><a href="#build-flag--workspace_status_command">--workspace_status_command</a>=<path></code> default: ""</dt> -<dd> -<p>A command invoked at the beginning of the build to provide status information about the workspace in the form of key/value pairs. See the User's Manual for the full specification. Also see tools/buildstamp/get_workspace_status for an example.</p> -</dd> -</dl> - -<dl>Options that control build execution: -<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> -<dd> -<p>Enable persistent aar extractor by using workers.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> -<dd> -<p>Whether to make source manifest actions remotable</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> -<dd> -<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> -<dd> -<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> -<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> -<p>Examples: -'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> -<dd> -<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> -<dd> -<p>If true, use the target platform for running tests rather than the test exec group.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The Android target compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> -<dd> -<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The C++ compiler to use for compiling the target.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> -<dd> -<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> -<dd> -<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> -<dd> -<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> -<dd> -<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> -<dd> -<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>No-op flag. Will be removed in a future release.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> -<dd> -<p>The label of a platform rule that describes the host system.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> -<dd> -<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> -<dd> -<p>Whether to emit a strip action as part of objc linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> -<dd> -<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> -<dd> -<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> -<dd> -<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> -<dd> -<p>The minimum OS version which your compilation targets.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> -<dd> -<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>The labels of the platform rules describing the target platforms for the current command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> -<dd> -<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> -<dd> -<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> -<dd> -<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> -<dd> -<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> -<dl>Options that control the output of the command: -<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> -<dd> -<p>Whether to generate debug symbol(.dSYM) file(s).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> -<dd> -<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> -<dd> -<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> -<dd> -<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> -<dd> -<p>Sets the suffixes of header files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> -<dd> -<p>Sets the suffixes of source files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> -<dd> -<p>Run extra actions for alternative Java api versions in a proto_library.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> -<dd> -<p>Save the state of enabled and requested feautres as an output of compilation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> -<dd> -<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> -<dd> -<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> -<dd> -<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>List of flags for which the use in select() is disabled.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> -<dd> -<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> -<dd> -<p>Specifies whether to generate a linkmap file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> -<dd> -<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case -the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -<br> -Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>Allowed values for the --cpu flag.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> -<dd> -<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> -<dd> -<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> -<dd> -<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> -<dd> -<p>Build python executable zip; on on Windows, off on other platforms</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> -<dd> -<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> -<dd> -<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> -<dd> -<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for FDO will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> -<dd> -<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> -<dd> -<p>Compress Java resources in APKs</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> -<dd> -<p>use rex tool to rewrite dex files</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will also generate collect coverage information for generated files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> -<dd> -<p>Uses these strings as objc fastbuild compiler options.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> -<dd> -<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> -<dd> -<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> -<dd> -<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> -<dd> -<p>py_binary targets include their label even when stamping is disabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> -<dd> -<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> -<dd> -<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use cache prefetch hints.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The fdo_profile representing the profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> -<dd> -<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> -<dd> -<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>The host CPU.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to linker when linking tools in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> -<dd> -<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> -<dd> -<p>If true, the genfiles directory is folded into the bin directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> -<dd> -<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> -<dd> -<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> -<dd> -<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> -</p></dd> -<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use memprof profile.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> -<dd> -<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> -<dd> -<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> -<dd> -<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> -<dd> -<p>If true, native libraries that contain identical functionality will be shared among different targets</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> -<dd> -<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> -<dd> -<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> -<dd> -<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> -<dd> -<p>Whether to desugar Java 8 bytecode before dexing.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> -<dd> -<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> -<dd> -<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> -<dd> -<p>Whether to double-check correct desugaring at Android binary level.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> -<dd> -<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> -<dd> -<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> -<dd> -<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> -<dd> -<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> -<dd> -<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> -<dd> -<p>No-op. Kept here for backwards compatibility.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> -<dd> -<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> -<dd> -<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> -<dd> -<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Options that affect the signing outputs of a build: -<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> -<dd> -<p>Implementation to use to sign APKs</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> -<dd> -<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> -<dd> -<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> -<dd> -<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> -<dd> -<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> -<dd> -<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that govern the behavior of the test environment or test runner: -<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> -<dd> -<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> -<dd> -<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> -<dd> -<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> -<dd> -<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> -</dd> -<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> -<dd> -<p>Use dex2oat in parallel to possibly speed up android_test.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> -<dd> -<p>Enable checking for memory leaks in ios_test targets.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> -<dd> -<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> -</dd> -<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> -<dd> -<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> -</dd> -<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, undeclared test outputs will be archived in a zip file.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -</dl> -<dl>Options that trigger optimizations of the build time: -<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> -<dd> -<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> -<dd> -<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> -<dd> -<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> -<dd> -<p>Does most of the work for dexing separately for each Jar file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> -<dd> -<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> -<dd> -<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> -<dd> -<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> -<dd> -<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> -<dd> -<p>If enabled, visibility errors include additional diagnostic information.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> -<dd> -<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> -<dd> -<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> -<dd> -<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> -</dd> -<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> -<dd> -<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> -<dd> -<p>If true, coverage for clang will generate an LCOV report.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> -<dd> -<p>Enables reduced classpaths for Java compilations.</p> -</dd> -<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> -<dd> -<p>Whether to validate java_* sources.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> -<dd> -<p>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.</p> -</dd> -<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher used by tools that are executed during a build.</p> -</dd> -<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac when building tools that are executed during a build.</p> -</dd> -<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> -<dd> -<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> -<dd> -<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the J2ObjC tool.</p> -</dd> -<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> -<dd> -<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> -<p>Expands to: -<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> -<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> -<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> -<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> -<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> -</p></dd> -<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> -<dd> -<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> -</dd> -<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> -<dd> -<p>Compile ijars directly from source.</p> -</dd> -<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version</p> -</dd> -<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> -</dd> -<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> -<dd> -<p>The Java runtime version</p> -</dd> -<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac.</p> -</dd> -<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> -</dd> -<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to do dexing without sharding.</p> -</dd> -<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Plugins to use in the build. Currently works with java_plugin.</p> -</dd> -<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> -</dd> -<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> -<dd> -<p>The label of the proto-compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> -<dd> -<p>Whether to pass profile_path to the proto compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the protobuf compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> -<dd> -<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> -</dd> -<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> -<dd> -<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> -</dd> -<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> -</dd> -<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>This option is deprecated and has no effect.</p> -</dd> -<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> -<dd> -<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> -</dd> -<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> -<dd> -<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> -</dd> -<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version used to execute the tools that are needed during a build</p> -</dd> -<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> -<dd> -<p>The Java runtime version used to execute tools during the build</p> -</dd> -<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> -<dd> -<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> -</dd> -</dl> - -<h2><a name="canonicalize-flags">Canonicalize-flags Options</a></h2> -<p>Inherits all options from <a href="#build">build</a>.</p> - -<dl>Options that control the output of the command: -<dt id="canonicalize-flags-flag--canonicalize_policy"><code id="canonicalize_policy"><a href="#canonicalize-flags-flag--canonicalize_policy">--[no]canonicalize_policy</a></code> default: "false"</dt> -<dd> -<p>Output the canonical policy, after expansion and filtering. To keep the output clean, the canonicalized command arguments will NOT be shown when this option is set to true. Note that the command specified by --for_command affects the filtered policy, and if none is specified, the default command is 'build'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="canonicalize-flags-flag--experimental_include_default_values"><code id="experimental_include_default_values"><a href="#canonicalize-flags-flag--experimental_include_default_values">--[no]experimental_include_default_values</a></code> default: "true"</dt> -<dd> -<p>Whether Starlark options set to their default values are included in the output.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="canonicalize-flags-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#canonicalize-flags-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> -<dd> -<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="canonicalize-flags-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#canonicalize-flags-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> -<dd> -<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="canonicalize-flags-flag--for_command"><code id="for_command"><a href="#canonicalize-flags-flag--for_command">--for_command</a>=<a string></code> default: "build"</dt> -<dd> -<p>The command for which the options should be canonicalized.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="canonicalize-flags-flag--invocation_policy"><code id="invocation_policy"><a href="#canonicalize-flags-flag--invocation_policy">--invocation_policy</a>=<a string></code> default: ""</dt> -<dd> -<p>Applies an invocation policy to the options to be canonicalized.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="canonicalize-flags-flag--deleted_packages"><code id="deleted_packages"><a href="#canonicalize-flags-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> -<dd> -<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> -</dd> -<dt id="canonicalize-flags-flag--fetch"><code id="fetch"><a href="#canonicalize-flags-flag--fetch">--[no]fetch</a></code> default: "true"</dt> -<dd> -<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> -</dd> -<dt id="canonicalize-flags-flag--package_path"><code id="package_path"><a href="#canonicalize-flags-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> -<dd> -<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> -</dd> -<dt id="canonicalize-flags-flag--show_loading_progress"><code id="show_loading_progress"><a href="#canonicalize-flags-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> -<dd> -<p>If enabled, causes Bazel to print "Loading package:" messages.</p> -</dd> -</dl> - -<h2><a name="clean">Clean Options</a></h2> -<p>Inherits all options from <a href="#build">build</a>.</p> - -<dl>Options that control the output of the command: -<dt id="clean-flag--async"><code id="async"><a href="#clean-flag--async">--[no]async</a></code> default: "false"</dt> -<dd> -<p>If true, output cleaning is asynchronous. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="clean-flag--expunge"><code id="expunge"><a href="#clean-flag--expunge">--[no]expunge</a></code> default: "false"</dt> -<dd> -<p>If true, clean removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running.</p> -<p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -<dt id="clean-flag--expunge_async"><code id="expunge_async"><a href="#clean-flag--expunge_async">--expunge_async</a></code></dt> -<dd> -<p>If specified, clean asynchronously removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background.</p> -<p>Expands to: -<br/>  <code><a href="#flag--expunge">--expunge</a></code> -<br/>  <code><a href="#flag--async">--async</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a> -</p></dd> -</dl> - -<h2><a name="config">Config Options</a></h2> -<h2><a name="coverage">Coverage Options</a></h2> -<p>Inherits all options from <a href="#test">test</a>.</p> - - -<h2><a name="cquery">Cquery Options</a></h2> -<p>Inherits all options from <a href="#test">test</a>.</p> - -<dl>Options relating to query output and semantics: -<dt id="cquery-flag--aspect_deps"><code id="aspect_deps"><a href="#cquery-flag--aspect_deps">--aspect_deps</a>=<off, conservative or precise></code> default: "conservative"</dt> -<dd> -<p>How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="cquery-flag--consistent_labels"><code id="consistent_labels"><a href="#cquery-flag--consistent_labels">--[no]consistent_labels</a></code> default: "false"</dt> -<dd> -<p>If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--experimental_explicit_aspects"><code id="experimental_explicit_aspects"><a href="#cquery-flag--experimental_explicit_aspects">--[no]experimental_explicit_aspects</a></code> default: "false"</dt> -<dd> -<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--graph:factored"><code id="graph:factored"><a href="#cquery-flag--graph:factored">--[no]graph:factored</a></code> default: "true"</dt> -<dd> -<p>If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--graph:node_limit"><code id="graph:node_limit"><a href="#cquery-flag--graph:node_limit">--graph:node_limit</a>=<an integer></code> default: "512"</dt> -<dd> -<p>The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--implicit_deps"><code id="implicit_deps"><a href="#cquery-flag--implicit_deps">--[no]implicit_deps</a></code> default: "true"</dt> -<dd> -<p>If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="cquery-flag--include_aspects"><code id="include_aspects"><a href="#cquery-flag--include_aspects">--[no]include_aspects</a></code> default: "true"</dt> -<dd> -<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--incompatible_package_group_includes_double_slash"><code id="incompatible_package_group_includes_double_slash"><a href="#cquery-flag--incompatible_package_group_includes_double_slash">--[no]incompatible_package_group_includes_double_slash</a></code> default: "true"</dt> -<dd> -<p>If enabled, when outputting package_group's <code>packages</code> attribute, the leading <code>//</code> will not be omitted.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="cquery-flag--infer_universe_scope"><code id="infer_universe_scope"><a href="#cquery-flag--infer_universe_scope">--[no]infer_universe_scope</a></code> default: "false"</dt> -<dd> -<p>If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.<code>allrdeps</code>) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to <code>query</code> (i.e. not <code>cquery</code>).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="cquery-flag--line_terminator_null"><code id="line_terminator_null"><a href="#cquery-flag--line_terminator_null">--[no]line_terminator_null</a></code> default: "false"</dt> -<dd> -<p>Whether each format is terminated with \0 instead of newline.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--nodep_deps"><code id="nodep_deps"><a href="#cquery-flag--nodep_deps">--[no]nodep_deps</a></code> default: "true"</dt> -<dd> -<p>If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of <code>info build-language</code> to learn about all the "nodep" attributes in the build language.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="cquery-flag--output"><code id="output"><a href="#cquery-flag--output">--output</a>=<a string></code> default: "label"</dt> -<dd> -<p>The format in which the cquery results should be printed. Allowed values for cquery are: label, label_kind, textproto, transitions, proto, streamed_proto, jsonproto. If you select 'transitions', you also have to specify the --transitions=(lite|full) option.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--output_file"><code id="output_file"><a href="#cquery-flag--output_file">--output_file</a>=<a string></code> default: ""</dt> -<dd> -<p>When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query &gt; file</code>.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:default_values"><code id="proto:default_values"><a href="#cquery-flag--proto:default_values">--[no]proto:default_values</a></code> default: "true"</dt> -<dd> -<p>If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:definition_stack"><code id="proto:definition_stack"><a href="#cquery-flag--proto:definition_stack">--[no]proto:definition_stack</a></code> default: "false"</dt> -<dd> -<p>Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:flatten_selects"><code id="proto:flatten_selects"><a href="#cquery-flag--proto:flatten_selects">--[no]proto:flatten_selects</a></code> default: "true"</dt> -<dd> -<p>If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="cquery-flag--proto:include_attribute_source_aspects"><code id="proto:include_attribute_source_aspects"><a href="#cquery-flag--proto:include_attribute_source_aspects">--[no]proto:include_attribute_source_aspects</a></code> default: "false"</dt> -<dd> -<p>Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:include_configurations"><code id="proto:include_configurations"><a href="#cquery-flag--proto:include_configurations">--[no]proto:include_configurations</a></code> default: "true"</dt> -<dd> -<p>if enabled, proto output will include information about configurations. When disabled,cquery proto output format resembles query output format.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="cquery-flag--proto:include_starlark_rule_env"><code id="proto:include_starlark_rule_env"><a href="#cquery-flag--proto:include_starlark_rule_env">--[no]proto:include_starlark_rule_env</a></code> default: "true"</dt> -<dd> -<p>Use the starlark environment in the value of the generated $internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:include_synthetic_attribute_hash"><code id="proto:include_synthetic_attribute_hash"><a href="#cquery-flag--proto:include_synthetic_attribute_hash">--[no]proto:include_synthetic_attribute_hash</a></code> default: "false"</dt> -<dd> -<p>Whether or not to calculate and populate the $internal_attr_hash attribute.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:instantiation_stack"><code id="proto:instantiation_stack"><a href="#cquery-flag--proto:instantiation_stack">--[no]proto:instantiation_stack</a></code> default: "false"</dt> -<dd> -<p>Populate the instantiation call stack of each rule. Note that this requires the stack to be present</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:locations"><code id="proto:locations"><a href="#cquery-flag--proto:locations">--[no]proto:locations</a></code> default: "true"</dt> -<dd> -<p>Whether to output location information in proto output at all.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:output_rule_attrs"><code id="proto:output_rule_attrs"><a href="#cquery-flag--proto:output_rule_attrs">--proto:output_rule_attrs</a>=<comma-separated list of options></code> default: "all"</dt> -<dd> -<p>Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:rule_classes"><code id="proto:rule_classes"><a href="#cquery-flag--proto:rule_classes">--[no]proto:rule_classes</a></code> default: "false"</dt> -<dd> -<p>Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--proto:rule_inputs_and_outputs"><code id="proto:rule_inputs_and_outputs"><a href="#cquery-flag--proto:rule_inputs_and_outputs">--[no]proto:rule_inputs_and_outputs</a></code> default: "true"</dt> -<dd> -<p>Whether or not to populate the rule_input and rule_output fields.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--query_file"><code id="query_file"><a href="#cquery-flag--query_file">--query_file</a>=<a string></code> default: ""</dt> -<dd> -<p>If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="cquery-flag--relative_locations"><code id="relative_locations"><a href="#cquery-flag--relative_locations">--[no]relative_locations</a></code> default: "false"</dt> -<dd> -<p>If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--show_config_fragments"><code id="show_config_fragments"><a href="#cquery-flag--show_config_fragments">--show_config_fragments</a>=<off, direct or transitive></code> default: "off"</dt> -<dd> -<p>Shows the configuration fragments required by a rule and its transitive dependencies. This can be useful for evaluating how much a configured target graph can be trimmed.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="cquery-flag--starlark:expr"><code id="starlark:expr"><a href="#cquery-flag--starlark:expr">--starlark:expr</a>=<a string></code> default: ""</dt> -<dd> -<p>A Starlark expression to format each configured target in cquery's --output=starlark mode. The configured target is bound to 'target'. If neither --starlark:expr nor --starlark:file is specified, this option will default to 'str(target.label)'. It is an error to specify both --starlark:expr and --starlark:file.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--starlark:file"><code id="starlark:file"><a href="#cquery-flag--starlark:file">--starlark:file</a>=<a string></code> default: ""</dt> -<dd> -<p>The name of a file that defines a Starlark function called 'format', of one argument, that is applied to each configured target to format it as a string. It is an error to specify both --starlark:expr and --starlark:file. See help for --output=starlark for additional detail.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="cquery-flag--tool_deps"><code id="tool_deps"><a href="#cquery-flag--tool_deps">--[no]tool_deps</a></code> default: "true"</dt> -<dd> -<p>Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. -Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="cquery-flag--transitions"><code id="transitions"><a href="#cquery-flag--transitions">--transitions</a>=<full, lite or none></code> default: "none"</dt> -<dd> -<p>The format in which cquery will print transition information.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="cquery-flag--universe_scope"><code id="universe_scope"><a href="#cquery-flag--universe_scope">--universe_scope</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. -For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> - -<dl>Options that control build execution: -<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> -<dd> -<p>Enable persistent aar extractor by using workers.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> -<dd> -<p>Whether to make source manifest actions remotable</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> -<dd> -<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> -<dd> -<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> -<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> -<p>Examples: -'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> -<dd> -<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> -<dd> -<p>If true, use the target platform for running tests rather than the test exec group.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The Android target compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> -<dd> -<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The C++ compiler to use for compiling the target.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> -<dd> -<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> -<dd> -<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> -<dd> -<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> -<dd> -<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> -<dd> -<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>No-op flag. Will be removed in a future release.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> -<dd> -<p>The label of a platform rule that describes the host system.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> -<dd> -<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> -<dd> -<p>Whether to emit a strip action as part of objc linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> -<dd> -<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> -<dd> -<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> -<dd> -<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> -<dd> -<p>The minimum OS version which your compilation targets.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> -<dd> -<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>The labels of the platform rules describing the target platforms for the current command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> -<dd> -<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> -<dd> -<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> -<dd> -<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> -<dd> -<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> -<dl>Options that control the output of the command: -<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> -<dd> -<p>Whether to generate debug symbol(.dSYM) file(s).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> -<dd> -<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> -<dd> -<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> -<dd> -<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> -<dd> -<p>Sets the suffixes of header files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> -<dd> -<p>Sets the suffixes of source files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> -<dd> -<p>Run extra actions for alternative Java api versions in a proto_library.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> -<dd> -<p>Save the state of enabled and requested feautres as an output of compilation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> -<dd> -<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> -<dd> -<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> -<dd> -<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>List of flags for which the use in select() is disabled.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> -<dd> -<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> -<dd> -<p>Specifies whether to generate a linkmap file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> -<dd> -<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case -the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -<br> -Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>Allowed values for the --cpu flag.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> -<dd> -<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> -<dd> -<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> -<dd> -<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> -<dd> -<p>Build python executable zip; on on Windows, off on other platforms</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> -<dd> -<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> -<dd> -<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> -<dd> -<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for FDO will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> -<dd> -<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> -<dd> -<p>Compress Java resources in APKs</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> -<dd> -<p>use rex tool to rewrite dex files</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will also generate collect coverage information for generated files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> -<dd> -<p>Uses these strings as objc fastbuild compiler options.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> -<dd> -<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> -<dd> -<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> -<dd> -<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> -<dd> -<p>py_binary targets include their label even when stamping is disabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> -<dd> -<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> -<dd> -<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use cache prefetch hints.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The fdo_profile representing the profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> -<dd> -<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> -<dd> -<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>The host CPU.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to linker when linking tools in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> -<dd> -<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> -<dd> -<p>If true, the genfiles directory is folded into the bin directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> -<dd> -<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> -<dd> -<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> -<dd> -<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> -</p></dd> -<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use memprof profile.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> -<dd> -<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> -<dd> -<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> -<dd> -<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> -<dd> -<p>If true, native libraries that contain identical functionality will be shared among different targets</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> -<dd> -<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> -<dd> -<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> -<dd> -<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> -<dd> -<p>Whether to desugar Java 8 bytecode before dexing.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> -<dd> -<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> -<dd> -<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> -<dd> -<p>Whether to double-check correct desugaring at Android binary level.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> -<dd> -<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> -<dd> -<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> -<dd> -<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> -<dd> -<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> -<dd> -<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> -<dd> -<p>No-op. Kept here for backwards compatibility.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> -<dd> -<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> -<dd> -<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> -<dd> -<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Options that affect the signing outputs of a build: -<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> -<dd> -<p>Implementation to use to sign APKs</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> -<dd> -<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> -<dd> -<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> -<dd> -<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> -<dd> -<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> -<dd> -<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that govern the behavior of the test environment or test runner: -<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> -<dd> -<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> -<dd> -<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> -<dd> -<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> -<dd> -<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> -</dd> -<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> -<dd> -<p>Use dex2oat in parallel to possibly speed up android_test.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> -<dd> -<p>Enable checking for memory leaks in ios_test targets.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> -<dd> -<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> -</dd> -<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> -<dd> -<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> -</dd> -<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, undeclared test outputs will be archived in a zip file.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -</dl> -<dl>Options that trigger optimizations of the build time: -<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> -<dd> -<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> -<dd> -<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> -<dd> -<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> -<dd> -<p>Does most of the work for dexing separately for each Jar file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> -<dd> -<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> -<dd> -<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> -<dd> -<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> -<dd> -<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> -<dd> -<p>If enabled, visibility errors include additional diagnostic information.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> -<dd> -<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> -<dd> -<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> -<dd> -<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> -</dd> -<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> -<dd> -<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> -<dd> -<p>If true, coverage for clang will generate an LCOV report.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> -<dd> -<p>Enables reduced classpaths for Java compilations.</p> -</dd> -<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> -<dd> -<p>Whether to validate java_* sources.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> -<dd> -<p>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.</p> -</dd> -<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher used by tools that are executed during a build.</p> -</dd> -<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac when building tools that are executed during a build.</p> -</dd> -<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> -<dd> -<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> -<dd> -<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the J2ObjC tool.</p> -</dd> -<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> -<dd> -<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> -<p>Expands to: -<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> -<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> -<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> -<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> -<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> -</p></dd> -<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> -<dd> -<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> -</dd> -<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> -<dd> -<p>Compile ijars directly from source.</p> -</dd> -<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version</p> -</dd> -<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> -</dd> -<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> -<dd> -<p>The Java runtime version</p> -</dd> -<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac.</p> -</dd> -<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> -</dd> -<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to do dexing without sharding.</p> -</dd> -<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Plugins to use in the build. Currently works with java_plugin.</p> -</dd> -<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> -</dd> -<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> -<dd> -<p>The label of the proto-compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> -<dd> -<p>Whether to pass profile_path to the proto compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the protobuf compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> -<dd> -<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> -</dd> -<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> -<dd> -<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> -</dd> -<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> -</dd> -<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>This option is deprecated and has no effect.</p> -</dd> -<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> -<dd> -<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> -</dd> -<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> -<dd> -<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> -</dd> -<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version used to execute the tools that are needed during a build</p> -</dd> -<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> -<dd> -<p>The Java runtime version used to execute tools during the build</p> -</dd> -<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> -<dd> -<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> -</dd> -</dl> - -<h2><a name="dump">Dump Options</a></h2> -<dl>Options that control the output of the command: -<dt id="dump-flag--action_cache"><code id="action_cache"><a href="#dump-flag--action_cache">--[no]action_cache</a></code> default: "false"</dt> -<dd> -<p>Dump action cache content.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="dump-flag--memory"><code id="memory"><a href="#dump-flag--memory">--memory</a>=<memory mode></code> default: see description</dt> -<dd> -<p>Dump the memory use of the given Skyframe node.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="dump-flag--packages"><code id="packages"><a href="#dump-flag--packages">--[no]packages</a></code> default: "false"</dt> -<dd> -<p>Dump package cache content.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="dump-flag--rule_classes"><code id="rule_classes"><a href="#dump-flag--rule_classes">--[no]rule_classes</a></code> default: "false"</dt> -<dd> -<p>Dump rule classes.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="dump-flag--rules"><code id="rules"><a href="#dump-flag--rules">--[no]rules</a></code> default: "false"</dt> -<dd> -<p>Dump rules, including counts and memory usage (if memory is tracked).</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="dump-flag--skyframe"><code id="skyframe"><a href="#dump-flag--skyframe">--skyframe</a>=<off, summary, count, value, deps, rdeps, function_graph, active_directories or active_directories_frontier_deps></code> default: "off"</dt> -<dd> -<p>Dump the Skyframe graph.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="dump-flag--skykey_filter"><code id="skykey_filter"><a href="#dump-flag--skykey_filter">--skykey_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: ".*"</dt> -<dd> -<p>Regex filter of SkyKey names to output. Only used with --skyframe=deps, rdeps, function_graph.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -<dt id="dump-flag--skylark_memory"><code id="skylark_memory"><a href="#dump-flag--skylark_memory">--skylark_memory</a>=<a string></code> default: see description</dt> -<dd> -<p>Dumps a pprof-compatible memory profile to the specified path. To learn more please see https://github.com/google/pprof.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -</dl> - -<h2><a name="fetch">Fetch Options</a></h2> -<p>Inherits all options from <a href="#test">test</a>.</p> - -<dl>Options that control build execution: -<dt id="fetch-flag--all"><code id="all"><a href="#fetch-flag--all">--[no]all</a></code> default: "false"</dt> -<dd> -<p>Fetches all external repositories necessary for building any target or repository. This is the default if no other flags and arguments are provided. Only works when --enable_bzlmod is on.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="fetch-flag--keep_going"><code id="keep_going"><a href="#fetch-flag--keep_going">--[no]keep_going</a></code> [<code>-k</code>] default: "false"</dt> -<dd> -<p>Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="fetch-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#fetch-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> -<dd> -<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="fetch-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#fetch-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> -<dd> -<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="fetch-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#fetch-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> -<dd> -<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options relating to Bzlmod output and semantics: -<dt id="fetch-flag--configure"><code id="configure"><a href="#fetch-flag--configure">--[no]configure</a></code> default: "false"</dt> -<dd> -<p>Only fetches repositories marked as 'configure' for system-configuration purpose. Only works when --enable_bzlmod is on.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="fetch-flag--force"><code id="force"><a href="#fetch-flag--force">--[no]force</a></code> default: "false"</dt> -<dd> -<p>Ignore existing repository if any and force fetch the repository again. Only works when --enable_bzlmod is on.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="fetch-flag--repo"><code id="repo"><a href="#fetch-flag--repo">--repo</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Only fetches the specified repository, which can be either {@apparent_repo_name} or {@@canonical_repo_name}. Only works when --enable_bzlmod is on.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="fetch-flag--deleted_packages"><code id="deleted_packages"><a href="#fetch-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> -<dd> -<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> -</dd> -<dt id="fetch-flag--fetch"><code id="fetch"><a href="#fetch-flag--fetch">--[no]fetch</a></code> default: "true"</dt> -<dd> -<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> -</dd> -<dt id="fetch-flag--package_path"><code id="package_path"><a href="#fetch-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> -<dd> -<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> -</dd> -<dt id="fetch-flag--show_loading_progress"><code id="show_loading_progress"><a href="#fetch-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> -<dd> -<p>If enabled, causes Bazel to print "Loading package:" messages.</p> -</dd> -</dl> - -<dl>Options that control build execution: -<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> -<dd> -<p>Enable persistent aar extractor by using workers.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> -<dd> -<p>Whether to make source manifest actions remotable</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> -<dd> -<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> -<dd> -<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> -<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> -<p>Examples: -'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> -<dd> -<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> -<dd> -<p>If true, use the target platform for running tests rather than the test exec group.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The Android target compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> -<dd> -<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The C++ compiler to use for compiling the target.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> -<dd> -<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> -<dd> -<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> -<dd> -<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> -<dd> -<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> -<dd> -<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>No-op flag. Will be removed in a future release.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> -<dd> -<p>The label of a platform rule that describes the host system.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> -<dd> -<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> -<dd> -<p>Whether to emit a strip action as part of objc linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> -<dd> -<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> -<dd> -<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> -<dd> -<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> -<dd> -<p>The minimum OS version which your compilation targets.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> -<dd> -<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>The labels of the platform rules describing the target platforms for the current command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> -<dd> -<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> -<dd> -<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> -<dd> -<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> -<dd> -<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> -<dl>Options that control the output of the command: -<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> -<dd> -<p>Whether to generate debug symbol(.dSYM) file(s).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> -<dd> -<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> -<dd> -<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> -<dd> -<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> -<dd> -<p>Sets the suffixes of header files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> -<dd> -<p>Sets the suffixes of source files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> -<dd> -<p>Run extra actions for alternative Java api versions in a proto_library.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> -<dd> -<p>Save the state of enabled and requested feautres as an output of compilation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> -<dd> -<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> -<dd> -<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> -<dd> -<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>List of flags for which the use in select() is disabled.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> -<dd> -<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> -<dd> -<p>Specifies whether to generate a linkmap file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> -<dd> -<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case -the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -<br> -Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>Allowed values for the --cpu flag.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> -<dd> -<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> -<dd> -<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> -<dd> -<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> -<dd> -<p>Build python executable zip; on on Windows, off on other platforms</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> -<dd> -<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> -<dd> -<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> -<dd> -<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for FDO will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> -<dd> -<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> -<dd> -<p>Compress Java resources in APKs</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> -<dd> -<p>use rex tool to rewrite dex files</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will also generate collect coverage information for generated files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> -<dd> -<p>Uses these strings as objc fastbuild compiler options.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> -<dd> -<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> -<dd> -<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> -<dd> -<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> -<dd> -<p>py_binary targets include their label even when stamping is disabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> -<dd> -<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> -<dd> -<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use cache prefetch hints.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The fdo_profile representing the profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> -<dd> -<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> -<dd> -<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>The host CPU.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to linker when linking tools in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> -<dd> -<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> -<dd> -<p>If true, the genfiles directory is folded into the bin directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> -<dd> -<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> -<dd> -<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> -<dd> -<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> -</p></dd> -<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use memprof profile.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> -<dd> -<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> -<dd> -<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> -<dd> -<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> -<dd> -<p>If true, native libraries that contain identical functionality will be shared among different targets</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> -<dd> -<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> -<dd> -<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> -<dd> -<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> -<dd> -<p>Whether to desugar Java 8 bytecode before dexing.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> -<dd> -<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> -<dd> -<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> -<dd> -<p>Whether to double-check correct desugaring at Android binary level.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> -<dd> -<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> -<dd> -<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> -<dd> -<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> -<dd> -<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> -<dd> -<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> -<dd> -<p>No-op. Kept here for backwards compatibility.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> -<dd> -<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> -<dd> -<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> -<dd> -<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Options that affect the signing outputs of a build: -<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> -<dd> -<p>Implementation to use to sign APKs</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> -<dd> -<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> -<dd> -<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> -<dd> -<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> -<dd> -<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> -<dd> -<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that govern the behavior of the test environment or test runner: -<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> -<dd> -<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> -<dd> -<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> -<dd> -<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> -<dd> -<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> -</dd> -<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> -<dd> -<p>Use dex2oat in parallel to possibly speed up android_test.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> -<dd> -<p>Enable checking for memory leaks in ios_test targets.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> -<dd> -<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> -</dd> -<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> -<dd> -<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> -</dd> -<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, undeclared test outputs will be archived in a zip file.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -</dl> -<dl>Options that trigger optimizations of the build time: -<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> -<dd> -<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> -<dd> -<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> -<dd> -<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> -<dd> -<p>Does most of the work for dexing separately for each Jar file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> -<dd> -<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> -<dd> -<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> -<dd> -<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> -<dd> -<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> -<dd> -<p>If enabled, visibility errors include additional diagnostic information.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> -<dd> -<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> -<dd> -<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> -<dd> -<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> -</dd> -<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> -<dd> -<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> -<dd> -<p>If true, coverage for clang will generate an LCOV report.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> -<dd> -<p>Enables reduced classpaths for Java compilations.</p> -</dd> -<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> -<dd> -<p>Whether to validate java_* sources.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> -<dd> -<p>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.</p> -</dd> -<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher used by tools that are executed during a build.</p> -</dd> -<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac when building tools that are executed during a build.</p> -</dd> -<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> -<dd> -<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> -<dd> -<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the J2ObjC tool.</p> -</dd> -<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> -<dd> -<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> -<p>Expands to: -<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> -<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> -<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> -<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> -<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> -</p></dd> -<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> -<dd> -<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> -</dd> -<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> -<dd> -<p>Compile ijars directly from source.</p> -</dd> -<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version</p> -</dd> -<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> -</dd> -<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> -<dd> -<p>The Java runtime version</p> -</dd> -<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac.</p> -</dd> -<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> -</dd> -<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to do dexing without sharding.</p> -</dd> -<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Plugins to use in the build. Currently works with java_plugin.</p> -</dd> -<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> -</dd> -<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> -<dd> -<p>The label of the proto-compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> -<dd> -<p>Whether to pass profile_path to the proto compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the protobuf compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> -<dd> -<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> -</dd> -<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> -<dd> -<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> -</dd> -<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> -</dd> -<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>This option is deprecated and has no effect.</p> -</dd> -<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> -<dd> -<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> -</dd> -<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> -<dd> -<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> -</dd> -<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version used to execute the tools that are needed during a build</p> -</dd> -<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> -<dd> -<p>The Java runtime version used to execute tools during the build</p> -</dd> -<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> -<dd> -<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> -</dd> -</dl> - -<h2><a name="help">Help Options</a></h2> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="help-flag--help_verbosity"><code id="help_verbosity"><a href="#help-flag--help_verbosity">--help_verbosity</a>=<long, medium or short></code> default: "medium"</dt> -<dd> -<p>Select the verbosity of the help command.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="help-flag--long"><code id="long"><a href="#help-flag--long">--long</a></code> [<code>-l</code>]</dt> -<dd> -<p>Show full description of each option, instead of just its name.</p> -<p>Expands to: -<br/>  <code><a href="#flag--help_verbosity">--help_verbosity=long</a></code> -</p><p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="help-flag--short"><code id="short"><a href="#help-flag--short">--short</a></code></dt> -<dd> -<p>Show only the names of the options, not their types or meanings.</p> -<p>Expands to: -<br/>  <code><a href="#flag--help_verbosity">--help_verbosity=short</a></code> -</p><p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -</dl> - -<h2><a name="info">Info Options</a></h2> -<p>Inherits all options from <a href="#build">build</a>.</p> - -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="info-flag--info_output_type"><code id="info_output_type"><a href="#info-flag--info_output_type">--info_output_type</a>=<stdout or response_proto></code> default: "stdout"</dt> -<dd> -<p>If stdout, results are directly printed to the console. If response_proto, the info command results are packed in response extensions.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="info-flag--show_make_env"><code id="show_make_env"><a href="#info-flag--show_make_env">--[no]show_make_env</a></code> default: "false"</dt> -<dd> -<p>Include the "Make" environment in the output.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -</dl> - -<h2><a name="license">License Options</a></h2> - -<h2><a name="mobile-install">Mobile-install Options</a></h2> -<p>Inherits all options from <a href="#build">build</a>.</p> - -<dl>Options that control build execution: -<dt id="mobile-install-flag--mode"><code id="mode"><a href="#mobile-install-flag--mode">--mode</a>=<classic, classic_internal_test_do_not_use or skylark></code> default: "skylark"</dt> -<dd> -<p>Deprecated no-effect flag. Only skylark mode is still supported.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="mobile-install-flag--adb"><code id="adb"><a href="#mobile-install-flag--adb">--adb</a>=<a string></code> default: ""</dt> -<dd> -<p>adb binary to use for the 'mobile-install' command. If unspecified, the one in the Android SDK specified by the --android_sdk_channel command line option (or the default SDK if --android_sdk_channel is not specified) is used.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Options that control the output of the command: -<dt id="mobile-install-flag--incremental"><code id="incremental"><a href="#mobile-install-flag--incremental">--[no]incremental</a></code> default: "false"</dt> -<dd> -<p>Whether to do an incremental install. If true, try to avoid unnecessary additional work by reading the state of the device the code is to be installed on and using that information to avoid unnecessary work. If false (the default), always do a full install.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="mobile-install-flag--split_apks"><code id="split_apks"><a href="#mobile-install-flag--split_apks">--[no]split_apks</a></code> default: "false"</dt> -<dd> -<p>Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="mobile-install-flag--adb_arg"><code id="adb_arg"><a href="#mobile-install-flag--adb_arg">--adb_arg</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Extra arguments to pass to adb. Usually used to designate a device to install to.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="mobile-install-flag--debug_app"><code id="debug_app"><a href="#mobile-install-flag--debug_app">--debug_app</a></code></dt> -<dd> -<p>Whether to wait for the debugger before starting the app.</p> -<p>Expands to: -<br/>  <code><a href="#flag--start">--start=DEBUG</a></code> -</p><p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="mobile-install-flag--device"><code id="device"><a href="#mobile-install-flag--device">--device</a>=<a string></code> default: ""</dt> -<dd> -<p>The adb device serial number. If not specified, the first device will be used.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="mobile-install-flag--start"><code id="start"><a href="#mobile-install-flag--start">--start</a>=<no, cold, warm or debug></code> default: "NO"</dt> -<dd> -<p>How the app should be started after installing it. Set to WARM to preserve and restore application state on incremental installs.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="mobile-install-flag--start_app"><code id="start_app"><a href="#mobile-install-flag--start_app">--start_app</a></code></dt> -<dd> -<p>Whether to start the app after installing it.</p> -<p>Expands to: -<br/>  <code><a href="#flag--start">--start=COLD</a></code> -</p><p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="mobile-install-flag--incremental_install_verbosity"><code id="incremental_install_verbosity"><a href="#mobile-install-flag--incremental_install_verbosity">--incremental_install_verbosity</a>=<a string></code> default: ""</dt> -<dd> -<p>The verbosity for incremental install. Set to 1 for debug logging.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></a> -</p></dd> -</dl> - -<h2><a name="mod">Mod Options</a></h2> -<dl>Options that control build execution: -<dt id="mod-flag--experimental_remotable_source_manifests"><code id="experimental_remotable_source_manifests"><a href="#mod-flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> -<dd> -<p>Whether to make source manifest actions remotable</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--experimental_strict_fileset_output"><code id="experimental_strict_fileset_output"><a href="#mod-flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--incompatible_modify_execution_info_additive"><code id="incompatible_modify_execution_info_additive"><a href="#mod-flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> -<dd> -<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="mod-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#mod-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> -<dd> -<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="mod-flag--modify_execution_info"><code id="modify_execution_info"><a href="#mod-flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> -<dd> -<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> -<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> -<p>Examples: -'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="mod-flag--use_target_platform_for_tests"><code id="use_target_platform_for_tests"><a href="#mod-flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> -<dd> -<p>If true, use the target platform for running tests rather than the test exec group.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="mod-flag--incompatible_bazel_test_exec_run_under"><code id="incompatible_bazel_test_exec_run_under"><a href="#mod-flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> -<dd> -<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that control the output of the command: -<dt id="mod-flag--build_runfile_links"><code id="build_runfile_links"><a href="#mod-flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> -<dd> -<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--build_runfile_manifests"><code id="build_runfile_manifests"><a href="#mod-flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> -<dd> -<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--incompatible_always_include_files_in_data"><code id="incompatible_always_include_files_in_data"><a href="#mod-flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> -<dd> -<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="mod-flag--incompatible_compact_repo_mapping_manifest"><code id="incompatible_compact_repo_mapping_manifest"><a href="#mod-flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> -<dd> -<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="mod-flag--incompatible_disable_select_on"><code id="incompatible_disable_select_on"><a href="#mod-flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>List of flags for which the use in select() is disabled.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="mod-flag--incompatible_filegroup_runfiles_for_data"><code id="incompatible_filegroup_runfiles_for_data"><a href="#mod-flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> -<dd> -<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="mod-flag--action_env"><code id="action_env"><a href="#mod-flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case -the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -<br> -Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="mod-flag--allowed_cpu_values"><code id="allowed_cpu_values"><a href="#mod-flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>Allowed values for the --cpu flag.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--collect_code_coverage"><code id="collect_code_coverage"><a href="#mod-flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--compilation_mode"><code id="compilation_mode"><a href="#mod-flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> -<dd> -<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="mod-flag--cpu"><code id="cpu"><a href="#mod-flag--cpu">--cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--define"><code id="define"><a href="#mod-flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--enable_runfiles"><code id="enable_runfiles"><a href="#mod-flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> -<dd> -<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--exec_aspects"><code id="exec_aspects"><a href="#mod-flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="mod-flag--experimental_action_listener"><code id="experimental_action_listener"><a href="#mod-flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--experimental_collect_code_coverage_for_generated_files"><code id="experimental_collect_code_coverage_for_generated_files"><a href="#mod-flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will also generate collect coverage information for generated files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--experimental_output_paths"><code id="experimental_output_paths"><a href="#mod-flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> -<dd> -<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="mod-flag--experimental_override_platform_cpu_name"><code id="experimental_override_platform_cpu_name"><a href="#mod-flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--experimental_platform_in_output_dir"><code id="experimental_platform_in_output_dir"><a href="#mod-flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> -<dd> -<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code id="experimental_use_platforms_in_output_dir_legacy_heuristic"><a href="#mod-flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> -<dd> -<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--features"><code id="features"><a href="#mod-flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--host_action_env"><code id="host_action_env"><a href="#mod-flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="mod-flag--host_compilation_mode"><code id="host_compilation_mode"><a href="#mod-flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> -<dd> -<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="mod-flag--host_cpu"><code id="host_cpu"><a href="#mod-flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>The host CPU.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--host_features"><code id="host_features"><a href="#mod-flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--incompatible_auto_exec_groups"><code id="incompatible_auto_exec_groups"><a href="#mod-flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> -<dd> -<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="mod-flag--incompatible_merge_genfiles_directory"><code id="incompatible_merge_genfiles_directory"><a href="#mod-flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> -<dd> -<p>If true, the genfiles directory is folded into the bin directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="mod-flag--incompatible_target_cpu_from_platform"><code id="incompatible_target_cpu_from_platform"><a href="#mod-flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> -<dd> -<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="mod-flag--instrument_test_targets"><code id="instrument_test_targets"><a href="#mod-flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> -<dd> -<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--instrumentation_filter"><code id="instrumentation_filter"><a href="#mod-flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> -<dd> -<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="mod-flag--platform_suffix"><code id="platform_suffix"><a href="#mod-flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="mod-flag--run_under"><code id="run_under"><a href="#mod-flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> -<dd> -<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="mod-flag--stamp"><code id="stamp"><a href="#mod-flag--stamp">--[no]stamp</a></code> default: "false"</dt> -<dd> -<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="mod-flag--check_visibility"><code id="check_visibility"><a href="#mod-flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> -<dd> -<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="mod-flag--enforce_constraints"><code id="enforce_constraints"><a href="#mod-flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> -<dd> -<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="mod-flag--experimental_enforce_transitive_visibility"><code id="experimental_enforce_transitive_visibility"><a href="#mod-flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> -<dd> -<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--incompatible_check_testonly_for_output_files"><code id="incompatible_check_testonly_for_output_files"><a href="#mod-flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> -<dd> -<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="mod-flag--strict_filesets"><code id="strict_filesets"><a href="#mod-flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="mod-flag--target_environment"><code id="target_environment"><a href="#mod-flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="mod-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#mod-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> -<dd> -<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="mod-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#mod-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> -<dd> -<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that govern the behavior of the test environment or test runner: -<dt id="mod-flag--allow_analysis_failures"><code id="allow_analysis_failures"><a href="#mod-flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> -<dd> -<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="mod-flag--analysis_testing_deps_limit"><code id="analysis_testing_deps_limit"><a href="#mod-flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> -<dd> -<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> -<dl>Options relating to the output and semantics of the `mod` subcommand: -<dt id="mod-flag--base_module"><code id="base_module"><a href="#mod-flag--base_module">--base_module</a>=<"<root>" for the root module; <module>@<version> for a specific version of a module; <module> for all versions of a module; @<name> for a repo with the given apparent name; or @@<name> for a repo with the given canonical name></code> default: "<root>"</dt> -<dd> -<p>Specify a module relative to which the specified target repos will be interpreted.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--charset"><code id="charset"><a href="#mod-flag--charset">--charset</a>=<utf8 or ascii></code> default: "utf8"</dt> -<dd> -<p>Chooses the character set to use for the tree. Only affects text output. Valid values are "utf8" or "ascii". Default is "utf8"</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--cycles"><code id="cycles"><a href="#mod-flag--cycles">--[no]cycles</a></code> default: "true"</dt> -<dd> -<p>Points out dependency cycles inside the displayed tree.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--depth"><code id="depth"><a href="#mod-flag--depth">--depth</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>Maximum display depth of the dependency tree. A depth of 1 displays the direct dependencies, for example. For tree, path and all_paths it defaults to Integer.MAX_VALUE, while for deps and explain it defaults to 1 (only displays direct deps of the root besides the target leaves and their parents).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--extension_filter"><code id="extension_filter"><a href="#mod-flag--extension_filter">--extension_filter</a>=<a comma-separated list of <extension>s></code> default: see description</dt> -<dd> -<p>Only display the usages of these module extensions and the repos generated by them if their respective flags are set. If set, the result graph will only include paths that contain modules using the specified extensions. An empty list disables the filter, effectively specifying all possible extensions.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--extension_info"><code id="extension_info"><a href="#mod-flag--extension_info">--extension_info</a>=<hidden, usages, repos or all></code> default: "hidden"</dt> -<dd> -<p>Specify how much detail about extension usages to include in the query result. "Usages" will only show the extensions names, "repos" will also include repos imported with use_repo, and "all" will also show the other repositories generated by extensions.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--extension_usages"><code id="extension_usages"><a href="#mod-flag--extension_usages">--extension_usages</a>=<a comma-separated list of <module>s></code> default: ""</dt> -<dd> -<p>Specify modules whose extension usages will be displayed in the show_extension query.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--from"><code id="from"><a href="#mod-flag--from">--from</a>=<a comma-separated list of <module>s></code> default: "<root>"</dt> -<dd> -<p>The module(s) starting from which the dependency graph query will be displayed. Check each query’s description for the exact semantics. Defaults to <root>.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--include_builtin"><code id="include_builtin"><a href="#mod-flag--include_builtin">--[no]include_builtin</a></code> default: "false"</dt> -<dd> -<p>Include built-in modules in the dependency graph. Disabled by default because it is quite noisy.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--include_unused"><code id="include_unused"><a href="#mod-flag--include_unused">--[no]include_unused</a></code> default: "false"</dt> -<dd> -<p>The queries will also take into account and display the unused modules, which are not present in the module resolution graph after selection (due to the Minimal-Version Selection or override rules). This can have different effects for each of the query types i.e. include new paths in the all_paths command, or extra dependants in the explain command.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--output"><code id="output"><a href="#mod-flag--output">--output</a>=<text, json or graph></code> default: "text"</dt> -<dd> -<p>The format in which the query results should be printed. Allowed values for query are: text, json, graph</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="mod-flag--verbose"><code id="verbose"><a href="#mod-flag--verbose">--[no]verbose</a></code> default: "false"</dt> -<dd> -<p>The queries will also display the reason why modules were resolved to their current version (if changed). Defaults to true only for the explain query.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="mod-flag--verbose_visibility_errors"><code id="verbose_visibility_errors"><a href="#mod-flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> -<dd> -<p>If enabled, visibility errors include additional diagnostic information.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="mod-flag--flag_alias"><code id="flag_alias"><a href="#mod-flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> -<dd> -<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="mod-flag--deleted_packages"><code id="deleted_packages"><a href="#mod-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> -<dd> -<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> -</dd> -<dt id="mod-flag--fetch"><code id="fetch"><a href="#mod-flag--fetch">--[no]fetch</a></code> default: "true"</dt> -<dd> -<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> -</dd> -<dt id="mod-flag--package_path"><code id="package_path"><a href="#mod-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> -<dd> -<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> -</dd> -<dt id="mod-flag--show_loading_progress"><code id="show_loading_progress"><a href="#mod-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> -<dd> -<p>If enabled, causes Bazel to print "Loading package:" messages.</p> -</dd> -</dl> - -<h2><a name="print_action">Print_action Options</a></h2> -<p>Inherits all options from <a href="#build">build</a>.</p> - -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="print_action-flag--print_action_mnemonics"><code id="print_action_mnemonics"><a href="#print_action-flag--print_action_mnemonics">--print_action_mnemonics</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Lists which mnemonics to filter print_action data by, no filtering takes place when left empty.</p> -</dd> -</dl> - -<h2><a name="query">Query Options</a></h2> -<dl>Options that control build execution: -<dt id="query-flag--experimental_remotable_source_manifests"><code id="experimental_remotable_source_manifests"><a href="#query-flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> -<dd> -<p>Whether to make source manifest actions remotable</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--experimental_strict_fileset_output"><code id="experimental_strict_fileset_output"><a href="#query-flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--incompatible_modify_execution_info_additive"><code id="incompatible_modify_execution_info_additive"><a href="#query-flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> -<dd> -<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--keep_going"><code id="keep_going"><a href="#query-flag--keep_going">--[no]keep_going</a></code> [<code>-k</code>] default: "false"</dt> -<dd> -<p>Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="query-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#query-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> -<dd> -<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -<dt id="query-flag--modify_execution_info"><code id="modify_execution_info"><a href="#query-flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> -<dd> -<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> -<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> -<p>Examples: -'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="query-flag--use_target_platform_for_tests"><code id="use_target_platform_for_tests"><a href="#query-flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> -<dd> -<p>If true, use the target platform for running tests rather than the test exec group.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="query-flag--incompatible_bazel_test_exec_run_under"><code id="incompatible_bazel_test_exec_run_under"><a href="#query-flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> -<dd> -<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that control the output of the command: -<dt id="query-flag--build_runfile_links"><code id="build_runfile_links"><a href="#query-flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> -<dd> -<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--build_runfile_manifests"><code id="build_runfile_manifests"><a href="#query-flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> -<dd> -<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--incompatible_always_include_files_in_data"><code id="incompatible_always_include_files_in_data"><a href="#query-flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> -<dd> -<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--incompatible_compact_repo_mapping_manifest"><code id="incompatible_compact_repo_mapping_manifest"><a href="#query-flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> -<dd> -<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--incompatible_disable_select_on"><code id="incompatible_disable_select_on"><a href="#query-flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>List of flags for which the use in select() is disabled.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="query-flag--incompatible_filegroup_runfiles_for_data"><code id="incompatible_filegroup_runfiles_for_data"><a href="#query-flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> -<dd> -<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="query-flag--action_env"><code id="action_env"><a href="#query-flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case -the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -<br> -Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="query-flag--allowed_cpu_values"><code id="allowed_cpu_values"><a href="#query-flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>Allowed values for the --cpu flag.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--collect_code_coverage"><code id="collect_code_coverage"><a href="#query-flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--compilation_mode"><code id="compilation_mode"><a href="#query-flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> -<dd> -<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="query-flag--cpu"><code id="cpu"><a href="#query-flag--cpu">--cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--define"><code id="define"><a href="#query-flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--enable_runfiles"><code id="enable_runfiles"><a href="#query-flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> -<dd> -<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--exec_aspects"><code id="exec_aspects"><a href="#query-flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="query-flag--experimental_action_listener"><code id="experimental_action_listener"><a href="#query-flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--experimental_collect_code_coverage_for_generated_files"><code id="experimental_collect_code_coverage_for_generated_files"><a href="#query-flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will also generate collect coverage information for generated files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--experimental_output_paths"><code id="experimental_output_paths"><a href="#query-flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> -<dd> -<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="query-flag--experimental_override_platform_cpu_name"><code id="experimental_override_platform_cpu_name"><a href="#query-flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--experimental_platform_in_output_dir"><code id="experimental_platform_in_output_dir"><a href="#query-flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> -<dd> -<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code id="experimental_use_platforms_in_output_dir_legacy_heuristic"><a href="#query-flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> -<dd> -<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--features"><code id="features"><a href="#query-flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--host_action_env"><code id="host_action_env"><a href="#query-flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="query-flag--host_compilation_mode"><code id="host_compilation_mode"><a href="#query-flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> -<dd> -<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="query-flag--host_cpu"><code id="host_cpu"><a href="#query-flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>The host CPU.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--host_features"><code id="host_features"><a href="#query-flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--incompatible_auto_exec_groups"><code id="incompatible_auto_exec_groups"><a href="#query-flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> -<dd> -<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--incompatible_merge_genfiles_directory"><code id="incompatible_merge_genfiles_directory"><a href="#query-flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> -<dd> -<p>If true, the genfiles directory is folded into the bin directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--incompatible_target_cpu_from_platform"><code id="incompatible_target_cpu_from_platform"><a href="#query-flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> -<dd> -<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--instrument_test_targets"><code id="instrument_test_targets"><a href="#query-flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> -<dd> -<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--instrumentation_filter"><code id="instrumentation_filter"><a href="#query-flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> -<dd> -<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="query-flag--platform_suffix"><code id="platform_suffix"><a href="#query-flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="query-flag--run_under"><code id="run_under"><a href="#query-flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> -<dd> -<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="query-flag--stamp"><code id="stamp"><a href="#query-flag--stamp">--[no]stamp</a></code> default: "false"</dt> -<dd> -<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="query-flag--check_visibility"><code id="check_visibility"><a href="#query-flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> -<dd> -<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="query-flag--enforce_constraints"><code id="enforce_constraints"><a href="#query-flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> -<dd> -<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="query-flag--experimental_enforce_transitive_visibility"><code id="experimental_enforce_transitive_visibility"><a href="#query-flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> -<dd> -<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--incompatible_check_testonly_for_output_files"><code id="incompatible_check_testonly_for_output_files"><a href="#query-flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> -<dd> -<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--strict_filesets"><code id="strict_filesets"><a href="#query-flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="query-flag--target_environment"><code id="target_environment"><a href="#query-flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="query-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#query-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> -<dd> -<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#query-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> -<dd> -<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that govern the behavior of the test environment or test runner: -<dt id="query-flag--allow_analysis_failures"><code id="allow_analysis_failures"><a href="#query-flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> -<dd> -<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="query-flag--analysis_testing_deps_limit"><code id="analysis_testing_deps_limit"><a href="#query-flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> -<dd> -<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> -<dl>Options relating to query output and semantics: -<dt id="query-flag--aspect_deps"><code id="aspect_deps"><a href="#query-flag--aspect_deps">--aspect_deps</a>=<off, conservative or precise></code> default: "conservative"</dt> -<dd> -<p>How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="query-flag--consistent_labels"><code id="consistent_labels"><a href="#query-flag--consistent_labels">--[no]consistent_labels</a></code> default: "false"</dt> -<dd> -<p>If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--experimental_explicit_aspects"><code id="experimental_explicit_aspects"><a href="#query-flag--experimental_explicit_aspects">--[no]experimental_explicit_aspects</a></code> default: "false"</dt> -<dd> -<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--experimental_graphless_query"><code id="experimental_graphless_query"><a href="#query-flag--experimental_graphless_query">--[no]experimental_graphless_query</a></code> default: "auto"</dt> -<dd> -<p>If true, uses a Query implementation that does not make a copy of the graph. The new implementation only supports --order_output=no, as well as only a subset of output formatters.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="query-flag--graph:conditional_edges_limit"><code id="graph:conditional_edges_limit"><a href="#query-flag--graph:conditional_edges_limit">--graph:conditional_edges_limit</a>=<an integer></code> default: "4"</dt> -<dd> -<p>The maximum number of condition labels to show. -1 means no truncation and 0 means no annotation. This option is only applicable to --output=graph.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--graph:factored"><code id="graph:factored"><a href="#query-flag--graph:factored">--[no]graph:factored</a></code> default: "true"</dt> -<dd> -<p>If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--graph:node_limit"><code id="graph:node_limit"><a href="#query-flag--graph:node_limit">--graph:node_limit</a>=<an integer></code> default: "512"</dt> -<dd> -<p>The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--implicit_deps"><code id="implicit_deps"><a href="#query-flag--implicit_deps">--[no]implicit_deps</a></code> default: "true"</dt> -<dd> -<p>If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="query-flag--include_aspects"><code id="include_aspects"><a href="#query-flag--include_aspects">--[no]include_aspects</a></code> default: "true"</dt> -<dd> -<p>aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--incompatible_lexicographical_output"><code id="incompatible_lexicographical_output"><a href="#query-flag--incompatible_lexicographical_output">--[no]incompatible_lexicographical_output</a></code> default: "true"</dt> -<dd> -<p>If this option is set, sorts --order_output=auto output in lexicographical order.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--incompatible_package_group_includes_double_slash"><code id="incompatible_package_group_includes_double_slash"><a href="#query-flag--incompatible_package_group_includes_double_slash">--[no]incompatible_package_group_includes_double_slash</a></code> default: "true"</dt> -<dd> -<p>If enabled, when outputting package_group's <code>packages</code> attribute, the leading <code>//</code> will not be omitted.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="query-flag--infer_universe_scope"><code id="infer_universe_scope"><a href="#query-flag--infer_universe_scope">--[no]infer_universe_scope</a></code> default: "false"</dt> -<dd> -<p>If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.<code>allrdeps</code>) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to <code>query</code> (i.e. not <code>cquery</code>).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="query-flag--line_terminator_null"><code id="line_terminator_null"><a href="#query-flag--line_terminator_null">--[no]line_terminator_null</a></code> default: "false"</dt> -<dd> -<p>Whether each format is terminated with \0 instead of newline.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--nodep_deps"><code id="nodep_deps"><a href="#query-flag--nodep_deps">--[no]nodep_deps</a></code> default: "true"</dt> -<dd> -<p>If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of <code>info build-language</code> to learn about all the "nodep" attributes in the build language.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="query-flag--noorder_results"><code id="noorder_results"><a href="#query-flag--noorder_results">--noorder_results</a></code></dt> -<dd> -<p>Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph.</p> -<p>Expands to: -<br/>  <code><a href="#flag--order_output">--order_output=no</a></code> -</p><p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--null"><code id="null"><a href="#query-flag--null">--null</a></code></dt> -<dd> -<p>Whether each format is terminated with \0 instead of newline.</p> -<p>Expands to: -<br/>  <code><a href="#flag--line_terminator_null">--line_terminator_null=true</a></code> -</p><p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--order_output"><code id="order_output"><a href="#query-flag--order_output">--order_output</a>=<no, deps, auto or full></code> default: "auto"</dt> -<dd> -<p>Output the results unordered (no), dependency-ordered (deps), or fully ordered (full). The default is 'auto', meaning that results are output either dependency-ordered or fully ordered, depending on the output formatter (dependency-ordered for proto, minrank, maxrank, and graph, fully ordered for all others). When output is fully ordered, nodes are printed in a fully deterministic (total) order. First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a post-order depth-first search in which outgoing edges to unvisited nodes are traversed in alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order in which they were visited.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--order_results"><code id="order_results"><a href="#query-flag--order_results">--order_results</a></code></dt> -<dd> -<p>Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph.</p> -<p>Expands to: -<br/>  <code><a href="#flag--order_output">--order_output=auto</a></code> -</p><p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--output"><code id="output"><a href="#query-flag--output">--output</a>=<a string></code> default: "label"</dt> -<dd> -<p>The format in which the query results should be printed. Allowed values for query are: build, graph, streamed_jsonproto, label, label_kind, location, maxrank, minrank, package, proto, streamed_proto, xml.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--output_file"><code id="output_file"><a href="#query-flag--output_file">--output_file</a>=<a string></code> default: ""</dt> -<dd> -<p>When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query &gt; file</code>.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:default_values"><code id="proto:default_values"><a href="#query-flag--proto:default_values">--[no]proto:default_values</a></code> default: "true"</dt> -<dd> -<p>If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:definition_stack"><code id="proto:definition_stack"><a href="#query-flag--proto:definition_stack">--[no]proto:definition_stack</a></code> default: "false"</dt> -<dd> -<p>Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:flatten_selects"><code id="proto:flatten_selects"><a href="#query-flag--proto:flatten_selects">--[no]proto:flatten_selects</a></code> default: "true"</dt> -<dd> -<p>If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="query-flag--proto:include_attribute_source_aspects"><code id="proto:include_attribute_source_aspects"><a href="#query-flag--proto:include_attribute_source_aspects">--[no]proto:include_attribute_source_aspects</a></code> default: "false"</dt> -<dd> -<p>Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not).</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:include_starlark_rule_env"><code id="proto:include_starlark_rule_env"><a href="#query-flag--proto:include_starlark_rule_env">--[no]proto:include_starlark_rule_env</a></code> default: "true"</dt> -<dd> -<p>Use the starlark environment in the value of the generated $internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:include_synthetic_attribute_hash"><code id="proto:include_synthetic_attribute_hash"><a href="#query-flag--proto:include_synthetic_attribute_hash">--[no]proto:include_synthetic_attribute_hash</a></code> default: "false"</dt> -<dd> -<p>Whether or not to calculate and populate the $internal_attr_hash attribute.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:instantiation_stack"><code id="proto:instantiation_stack"><a href="#query-flag--proto:instantiation_stack">--[no]proto:instantiation_stack</a></code> default: "false"</dt> -<dd> -<p>Populate the instantiation call stack of each rule. Note that this requires the stack to be present</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:locations"><code id="proto:locations"><a href="#query-flag--proto:locations">--[no]proto:locations</a></code> default: "true"</dt> -<dd> -<p>Whether to output location information in proto output at all.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:output_rule_attrs"><code id="proto:output_rule_attrs"><a href="#query-flag--proto:output_rule_attrs">--proto:output_rule_attrs</a>=<comma-separated list of options></code> default: "all"</dt> -<dd> -<p>Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:rule_classes"><code id="proto:rule_classes"><a href="#query-flag--proto:rule_classes">--[no]proto:rule_classes</a></code> default: "false"</dt> -<dd> -<p>Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--proto:rule_inputs_and_outputs"><code id="proto:rule_inputs_and_outputs"><a href="#query-flag--proto:rule_inputs_and_outputs">--[no]proto:rule_inputs_and_outputs</a></code> default: "true"</dt> -<dd> -<p>Whether or not to populate the rule_input and rule_output fields.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--query_file"><code id="query_file"><a href="#query-flag--query_file">--query_file</a>=<a string></code> default: ""</dt> -<dd> -<p>If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="query-flag--relative_locations"><code id="relative_locations"><a href="#query-flag--relative_locations">--[no]relative_locations</a></code> default: "false"</dt> -<dd> -<p>If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--strict_test_suite"><code id="strict_test_suite"><a href="#query-flag--strict_test_suite">--[no]strict_test_suite</a></code> default: "false"</dt> -<dd> -<p>If true, the tests() expression gives an error if it encounters a test_suite containing non-test targets.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="query-flag--tool_deps"><code id="tool_deps"><a href="#query-flag--tool_deps">--[no]tool_deps</a></code> default: "true"</dt> -<dd> -<p>Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. -Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="query-flag--universe_scope"><code id="universe_scope"><a href="#query-flag--universe_scope">--universe_scope</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. -For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="query-flag--xml:default_values"><code id="xml:default_values"><a href="#query-flag--xml:default_values">--[no]xml:default_values</a></code> default: "false"</dt> -<dd> -<p>If true, rule attributes whose value is not explicitly specified in the BUILD file are printed; otherwise they are omitted.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="query-flag--xml:line_numbers"><code id="xml:line_numbers"><a href="#query-flag--xml:line_numbers">--[no]xml:line_numbers</a></code> default: "true"</dt> -<dd> -<p>If true, XML output contains line numbers. Disabling this option may make diffs easier to read. This option is only applicable to --output=xml.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="query-flag--verbose_visibility_errors"><code id="verbose_visibility_errors"><a href="#query-flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> -<dd> -<p>If enabled, visibility errors include additional diagnostic information.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="query-flag--flag_alias"><code id="flag_alias"><a href="#query-flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> -<dd> -<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="query-flag--deleted_packages"><code id="deleted_packages"><a href="#query-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> -<dd> -<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> -</dd> -<dt id="query-flag--fetch"><code id="fetch"><a href="#query-flag--fetch">--[no]fetch</a></code> default: "true"</dt> -<dd> -<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> -</dd> -<dt id="query-flag--package_path"><code id="package_path"><a href="#query-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> -<dd> -<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> -</dd> -<dt id="query-flag--show_loading_progress"><code id="show_loading_progress"><a href="#query-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> -<dd> -<p>If enabled, causes Bazel to print "Loading package:" messages.</p> -</dd> -</dl> - -<h2><a name="run">Run Options</a></h2> -<p>Inherits all options from <a href="#build">build</a>.</p> - -<dl>Options that appear before the command and are parsed by the client: -<dt id="run-flag--portable_paths"><code id="portable_paths"><a href="#run-flag--portable_paths">--[no]portable_paths</a></code> default: "false"</dt> -<dd> -<p>If true, includes paths to replace in ExecRequest to make the resulting paths portable.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="run-flag--run"><code id="run"><a href="#run-flag--run">--[no]run</a></code> default: "true"</dt> -<dd> -<p>If false, skip running the command line constructed for the built target. Note that this flag is ignored for all --script_path builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="run-flag--run_env"><code id="run_env"><a href="#run-flag--run_env">--run_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to the target to run. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. Note that the executed target will generally see the full environment of the host except for those variables that have been explicitly unset.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="run-flag--script_path"><code id="script_path"><a href="#run-flag--script_path">--script_path</a>=<a path></code> default: see description</dt> -<dd> -<p>If set, write a shell script to the given file which invokes the target. If this option is set, the target is not run from bazel. Use 'bazel run --script_path=foo //foo && ./foo' to invoke target '//foo' This differs from 'bazel run //foo' in that the bazel lock is released and the executable is connected to the terminal's stdin.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> - -<h2><a name="shutdown">Shutdown Options</a></h2> -<dl>Options that control the output of the command: -<dt id="shutdown-flag--iff_heap_size_greater_than"><code id="iff_heap_size_greater_than"><a href="#shutdown-flag--iff_heap_size_greater_than">--iff_heap_size_greater_than</a>=<an integer></code> default: "0"</dt> -<dd> -<p>Iff non-zero, then shutdown will only shut down the server if the total memory (in MB) consumed by the JVM exceeds this value.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -</dl> - -<h2><a name="test">Test Options</a></h2> -<p>Inherits all options from <a href="#build">build</a>.</p> - -<dl>Options that affect the verbosity, format or location of logging: -<dt id="test-flag--print_relative_test_log_paths"><code id="print_relative_test_log_paths"><a href="#test-flag--print_relative_test_log_paths">--[no]print_relative_test_log_paths</a></code> default: "false"</dt> -<dd> -<p>If true, when printing the path to a test log, use relative path that makes use of the 'testlogs' convenience symlink. N.B. - A subsequent 'build'/'test'/etc invocation with a different configuration can cause the target of this symlink to change, making the path printed previously no longer useful.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="test-flag--test_verbose_timeout_warnings"><code id="test_verbose_timeout_warnings"><a href="#test-flag--test_verbose_timeout_warnings">--[no]test_verbose_timeout_warnings</a></code> default: "false"</dt> -<dd> -<p>If true, print additional warnings when the actual test execution time does not match the timeout defined by the test (whether implied or explicit).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="test-flag--verbose_test_summary"><code id="verbose_test_summary"><a href="#test-flag--verbose_test_summary">--[no]verbose_test_summary</a></code> default: "true"</dt> -<dd> -<p>If true, print additional information (timing, number of failed runs, etc) in the test summary.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> - -<h2><a name="vendor">Vendor Options</a></h2> -<p>Inherits all options from <a href="#test">test</a>.</p> - -<dl>Options that control build execution: -<dt id="vendor-flag--keep_going"><code id="keep_going"><a href="#vendor-flag--keep_going">--[no]keep_going</a></code> [<code>-k</code>] default: "false"</dt> -<dd> -<p>Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="vendor-flag--loading_phase_threads"><code id="loading_phase_threads"><a href="#vendor-flag--loading_phase_threads">--loading_phase_threads</a>=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5"></code> default: "auto"</dt> -<dd> -<p>Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|<em>]<float>) eg. "auto", "HOST_CPUS</em>.5". "auto" sets a reasonable default based on host resources. Must be at least 1.</p> -<p>Tags: -<a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="vendor-flag--incompatible_config_setting_private_default_visibility"><code id="incompatible_config_setting_private_default_visibility"><a href="#vendor-flag--incompatible_config_setting_private_default_visibility">--[no]incompatible_config_setting_private_default_visibility</a></code> default: "false"</dt> -<dd> -<p>If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="vendor-flag--incompatible_enforce_config_setting_visibility"><code id="incompatible_enforce_config_setting_visibility"><a href="#vendor-flag--incompatible_enforce_config_setting_visibility">--[no]incompatible_enforce_config_setting_visibility</a></code> default: "true"</dt> -<dd> -<p>If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options relating to Bzlmod output and semantics: -<dt id="vendor-flag--repo"><code id="repo"><a href="#vendor-flag--repo">--repo</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Only vendors the specified repository, which can be either <code>@apparent_repo_name</code> or <code>@@canonical_repo_name</code>. This option can be set multiple times</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="vendor-flag--deleted_packages"><code id="deleted_packages"><a href="#vendor-flag--deleted_packages">--deleted_packages</a>=<comma-separated list of package names></code> multiple uses are accumulated</dt> -<dd> -<p>A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem.</p> -</dd> -<dt id="vendor-flag--fetch"><code id="fetch"><a href="#vendor-flag--fetch">--[no]fetch</a></code> default: "true"</dt> -<dd> -<p>Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure.</p> -</dd> -<dt id="vendor-flag--package_path"><code id="package_path"><a href="#vendor-flag--package_path">--package_path</a>=<colon-separated list of options></code> default: "%workspace%"</dt> -<dd> -<p>A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'.</p> -</dd> -<dt id="vendor-flag--show_loading_progress"><code id="show_loading_progress"><a href="#vendor-flag--show_loading_progress">--[no]show_loading_progress</a></code> default: "true"</dt> -<dd> -<p>If enabled, causes Bazel to print "Loading package:" messages.</p> -</dd> -</dl> - -<dl>Options that control build execution: -<dt id="flag--experimental_persistent_aar_extractor"><code><a href="#flag--experimental_persistent_aar_extractor">--[no]experimental_persistent_aar_extractor</a></code> default: "false"</dt> -<dd> -<p>Enable persistent aar extractor by using workers.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_remotable_source_manifests"><code><a href="#flag--experimental_remotable_source_manifests">--[no]experimental_remotable_source_manifests</a></code> default: "false"</dt> -<dd> -<p>Whether to make source manifest actions remotable</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_split_coverage_postprocessing"><code><a href="#flag--experimental_split_coverage_postprocessing">--[no]experimental_split_coverage_postprocessing</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel will run coverage postprocessing for test in a new spawn.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_strict_fileset_output"><code><a href="#flag--experimental_strict_fileset_output">--[no]experimental_strict_fileset_output</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incompatible_modify_execution_info_additive"><code><a href="#flag--incompatible_modify_execution_info_additive">--[no]incompatible_modify_execution_info_additive</a></code> default: "true"</dt> -<dd> -<p>When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--modify_execution_info"><code><a href="#flag--modify_execution_info">--modify_execution_info</a>=<regex=[+-]key,regex=[+-]key,...></code> multiple uses are accumulated</dt> -<dd> -<p>Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic.</p> -<p>Syntax: "regex=[+-]key,regex=[+-]key,...".</p> -<p>Examples: -'.<em>=+x,.</em>=-y,.<em>=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).</em>=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--persistent_android_dex_desugar"><code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_android_dex_desugar">--internal_persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Desugar=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=DexBuilder=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_android_resource_processor"><code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_busybox_tools">--internal_persistent_busybox_tools</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AaptPackage=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceParser=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceValidator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceCompiler=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=RClassGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceLink=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAapt2=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidAssetMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidCompiledResourceMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AndroidManifestMerger=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=Aapt2Optimize=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=AARGenerator=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=ProcessDatabinding=worker</a></code> -<br/>  <code><a href="#flag--strategy">--strategy=GenerateDataBindingBaseClasses=worker</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_dex_desugar"><code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android dex and desugar actions by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_dex_desugar">--persistent_android_dex_desugar</a></code> -<br/>  <code><a href="#flag--internal_persistent_multiplex_android_dex_desugar">--internal_persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_resource_processor"><code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code></dt> -<dd> -<p>Enable persistent multiplexed Android resource processor by using workers.</p> -<p>Expands to: -<br/>  <code><a href="#flag--persistent_android_resource_processor">--persistent_android_resource_processor</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AaptPackage=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=RClassGenerator=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAapt2=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=ManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers</a></code> -<br/>  <code><a href="#flag--modify_execution_info">--modify_execution_info=AARGenerator=+supports-multiplex-workers</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--persistent_multiplex_android_tools"><code><a href="#flag--persistent_multiplex_android_tools">--persistent_multiplex_android_tools</a></code></dt> -<dd> -<p>Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing).</p> -<p>Expands to: -<br/>  <code><a href="#flag--internal_persistent_multiplex_busybox_tools">--internal_persistent_multiplex_busybox_tools</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_resource_processor">--persistent_multiplex_android_resource_processor</a></code> -<br/>  <code><a href="#flag--persistent_multiplex_android_dex_desugar">--persistent_multiplex_android_dex_desugar</a></code> -</p><p>Tags: -<a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--use_target_platform_for_tests"><code><a href="#flag--use_target_platform_for_tests">--[no]use_target_platform_for_tests</a></code> default: "false"</dt> -<dd> -<p>If true, use the target platform for running tests rather than the test exec group.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> -<dl>Options that configure the toolchain used for action execution: -<dt id="flag--android_compiler"><code><a href="#flag--android_compiler">--android_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The Android target compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_manifest_merger"><code><a href="#flag--android_manifest_merger">--android_manifest_merger</a>=<legacy, android or force_android></code> default: "android"</dt> -<dd> -<p>Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--android_platforms"><code><a href="#flag--android_platforms">--android_platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--cc_output_directory_tag"><code><a href="#flag--cc_output_directory_tag">--cc_output_directory_tag</a>=<a string></code> default: ""</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compiler"><code><a href="#flag--compiler">--compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>The C++ compiler to use for compiling the target.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--coverage_output_generator"><code><a href="#flag--coverage_output_generator">--coverage_output_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:lcov_merger"</dt> -<dd> -<p>Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_report_generator"><code><a href="#flag--coverage_report_generator">--coverage_report_generator</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_report_generator"</dt> -<dd> -<p>Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--coverage_support"><code><a href="#flag--coverage_support">--coverage_support</a>=<a build target label></code> default: "@bazel_tools//tools/test:coverage_support"</dt> -<dd> -<p>Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--custom_malloc"><code><a href="#flag--custom_malloc">--custom_malloc</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--experimental_include_xcode_execution_requirements"><code><a href="#flag--experimental_include_xcode_execution_requirements">--[no]experimental_include_xcode_execution_requirements</a></code> default: "false"</dt> -<dd> -<p>If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_prefer_mutual_xcode"><code><a href="#flag--experimental_prefer_mutual_xcode">--[no]experimental_prefer_mutual_xcode</a></code> default: "true"</dt> -<dd> -<p>If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--extra_execution_platforms"><code><a href="#flag--extra_execution_platforms">--extra_execution_platforms</a>=<comma-separated list of options></code> default: ""</dt> -<dd> -<p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--extra_toolchains"><code><a href="#flag--extra_toolchains">--extra_toolchains</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains().</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--grte_top"><code><a href="#flag--grte_top">--grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_compiler"><code><a href="#flag--host_compiler">--host_compiler</a>=<a string></code> default: see description</dt> -<dd> -<p>No-op flag. Will be removed in a future release.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--host_grte_top"><code><a href="#flag--host_grte_top">--host_grte_top</a>=<a label></code> default: see description</dt> -<dd> -<p>If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_platform"><code><a href="#flag--host_platform">--host_platform</a>=<a build target label></code> default: "@bazel_tools//tools:host_platform"</dt> -<dd> -<p>The label of a platform rule that describes the host system.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--incompatible_bazel_test_exec_run_under"><code><a href="#flag--incompatible_bazel_test_exec_run_under">--[no]incompatible_bazel_test_exec_run_under</a></code> default: "true"</dt> -<dd> -<p>If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run_under=//foo" in the target configuration.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_builtin_objc_strip_action"><code><a href="#flag--incompatible_builtin_objc_strip_action">--[no]incompatible_builtin_objc_strip_action</a></code> default: "true"</dt> -<dd> -<p>Whether to emit a strip action as part of objc linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_dont_enable_host_nonhost_crosstool_features"><code><a href="#flag--incompatible_dont_enable_host_nonhost_crosstool_features">--[no]incompatible_dont_enable_host_nonhost_crosstool_features</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_enable_apple_toolchain_resolution"><code><a href="#flag--incompatible_enable_apple_toolchain_resolution">--[no]incompatible_enable_apple_toolchain_resolution</a></code> default: "false"</dt> -<dd> -<p>Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native)</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_remove_legacy_whole_archive"><code><a href="#flag--incompatible_remove_legacy_whole_archive">--[no]incompatible_remove_legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions).</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strip_executable_safely"><code><a href="#flag--incompatible_strip_executable_safely">--[no]incompatible_strip_executable_safely</a></code> default: "false"</dt> -<dd> -<p>If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--interface_shared_objects"><code><a href="#flag--interface_shared_objects">--[no]interface_shared_objects</a></code> default: "true"</dt> -<dd> -<p>Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_sdk_version"><code><a href="#flag--ios_sdk_version">--ios_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--macos_sdk_version"><code><a href="#flag--macos_sdk_version">--macos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--minimum_os_version"><code><a href="#flag--minimum_os_version">--minimum_os_version</a>=<a string></code> default: see description</dt> -<dd> -<p>The minimum OS version which your compilation targets.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_mappings"><code><a href="#flag--platform_mappings">--platform_mappings</a>=<a main workspace-relative path></code> default: ""</dt> -<dd> -<p>The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--platforms"><code><a href="#flag--platforms">--platforms</a>=<a build target label></code> default: ""</dt> -<dd> -<p>The labels of the platform rules describing the target platforms for the current command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_path"><code><a href="#flag--python_path">--python_path</a>=<a string></code> default: see description</dt> -<dd> -<p>The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_sdk_version"><code><a href="#flag--tvos_sdk_version">--tvos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--use_platforms_in_apple_crosstool_transition"><code><a href="#flag--use_platforms_in_apple_crosstool_transition">--[no]use_platforms_in_apple_crosstool_transition</a></code> default: "false"</dt> -<dd> -<p>Makes apple_crosstool_transition fall back to using the value of <code>--platforms</code> flag instead of legacy <code>--cpu</code> when needed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_sdk_version"><code><a href="#flag--watchos_sdk_version">--watchos_sdk_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version"><code><a href="#flag--xcode_version">--xcode_version</a>=<a string></code> default: see description</dt> -<dd> -<p>If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xcode_version_config"><code><a href="#flag--xcode_version_config">--xcode_version_config</a>=<a build target label></code> default: "@bazel_tools//tools/cpp:host_xcodes"</dt> -<dd> -<p>The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -</dl> -<dl>Options that control the output of the command: -<dt id="flag--apple_generate_dsym"><code><a href="#flag--apple_generate_dsym">--[no]apple_generate_dsym</a></code> default: "false"</dt> -<dd> -<p>Whether to generate debug symbol(.dSYM) file(s).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--build_runfile_links"><code><a href="#flag--build_runfile_links">--[no]build_runfile_links</a></code> default: "true"</dt> -<dd> -<p>If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_runfile_manifests"><code><a href="#flag--build_runfile_manifests">--[no]build_runfile_manifests</a></code> default: "true"</dt> -<dd> -<p>If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--build_test_dwp"><code><a href="#flag--build_test_dwp">--[no]build_test_dwp</a></code> default: "false"</dt> -<dd> -<p>If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cc_proto_library_header_suffixes"><code><a href="#flag--cc_proto_library_header_suffixes">--cc_proto_library_header_suffixes</a>=<comma-separated set of options></code> default: ".pb.h"</dt> -<dd> -<p>Sets the suffixes of header files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--cc_proto_library_source_suffixes"><code><a href="#flag--cc_proto_library_source_suffixes">--cc_proto_library_source_suffixes</a>=<comma-separated set of options></code> default: ".pb.cc"</dt> -<dd> -<p>Sets the suffixes of source files that a cc_proto_library creates.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_proto_descriptor_sets_include_source_info"><code><a href="#flag--experimental_proto_descriptor_sets_include_source_info">--[no]experimental_proto_descriptor_sets_include_source_info</a></code> default: "false"</dt> -<dd> -<p>Run extra actions for alternative Java api versions in a proto_library.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_save_feature_state"><code><a href="#flag--experimental_save_feature_state">--[no]experimental_save_feature_state</a></code> default: "false"</dt> -<dd> -<p>Save the state of enabled and requested feautres as an output of compilation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fission"><code><a href="#flag--fission">--fission</a>=<a set of compilation modes></code> default: "no"</dt> -<dd> -<p>Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_always_include_files_in_data"><code><a href="#flag--incompatible_always_include_files_in_data">--[no]incompatible_always_include_files_in_data</a></code> default: "true"</dt> -<dd> -<p>If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_compact_repo_mapping_manifest"><code><a href="#flag--incompatible_compact_repo_mapping_manifest">--[no]incompatible_compact_repo_mapping_manifest</a></code> default: "false"</dt> -<dd> -<p>If enabled, the <binary>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_select_on"><code><a href="#flag--incompatible_disable_select_on">--incompatible_disable_select_on</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>List of flags for which the use in select() is disabled.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_filegroup_runfiles_for_data"><code><a href="#flag--incompatible_filegroup_runfiles_for_data">--[no]incompatible_filegroup_runfiles_for_data</a></code> default: "true"</dt> -<dd> -<p>If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--objc_generate_linkmap"><code><a href="#flag--objc_generate_linkmap">--[no]objc_generate_linkmap</a></code> default: "false"</dt> -<dd> -<p>Specifies whether to generate a linkmap file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--save_temps"><code><a href="#flag--save_temps">--[no]save_temps</a></code> default: "false"</dt> -<dd> -<p>If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++).</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="flag--action_env"><code><a href="#flag--action_env">--action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case -the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -<br> -Note that unless <code>--incompatible_repo_env_ignores_action_env</code> is true, all <code>name=value</code> pairs will be available to repository rules.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--allowed_cpu_values"><code><a href="#flag--allowed_cpu_values">--allowed_cpu_values</a>=<comma-separated set of options></code> default: ""</dt> -<dd> -<p>Allowed values for the --cpu flag.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--android_databinding_use_androidx"><code><a href="#flag--android_databinding_use_androidx">--[no]android_databinding_use_androidx</a></code> default: "true"</dt> -<dd> -<p>Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_databinding_use_v3_4_args"><code><a href="#flag--android_databinding_use_v3_4_args">--[no]android_databinding_use_v3_4_args</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2 with 3.4.0 argument. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--android_dynamic_mode"><code><a href="#flag--android_dynamic_mode">--android_dynamic_mode</a>=<off, default or fully></code> default: "off"</dt> -<dd> -<p>Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--android_manifest_merger_order"><code><a href="#flag--android_manifest_merger_order">--android_manifest_merger_order</a>=<alphabetical, alphabetical_by_configuration or dependency></code> default: "alphabetical"</dt> -<dd> -<p>Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--android_resource_shrinking"><code><a href="#flag--android_resource_shrinking">--[no]android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--build_python_zip"><code><a href="#flag--build_python_zip">--[no]build_python_zip</a></code> default: "auto"</dt> -<dd> -<p>Build python executable zip; on on Windows, off on other platforms</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--catalyst_cpus"><code><a href="#flag--catalyst_cpus">--catalyst_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple Catalyst binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--collect_code_coverage"><code><a href="#flag--collect_code_coverage">--[no]collect_code_coverage</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--compilation_mode"><code><a href="#flag--compilation_mode">--compilation_mode</a>=<fastbuild, dbg or opt></code> [<code>-c</code>] default: "fastbuild"</dt> -<dd> -<p>Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--conlyopt"><code><a href="#flag--conlyopt">--conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--copt"><code><a href="#flag--copt">--copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cpu"><code><a href="#flag--cpu">--cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_absolute_path"><code><a href="#flag--cs_fdo_absolute_path">--cs_fdo_absolute_path</a>=<a string></code> default: see description</dt> -<dd> -<p>Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_instrument"><code><a href="#flag--cs_fdo_instrument">--cs_fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cs_fdo_profile"><code><a href="#flag--cs_fdo_profile">--cs_fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The cs_fdo_profile representing the context sensitive profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--cxxopt"><code><a href="#flag--cxxopt">--cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when compiling C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--define"><code><a href="#flag--define">--define</a>=<a 'name=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--dynamic_mode"><code><a href="#flag--dynamic_mode">--dynamic_mode</a>=<off, default or fully></code> default: "default"</dt> -<dd> -<p>Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_propeller_optimize_absolute_paths"><code><a href="#flag--enable_propeller_optimize_absolute_paths">--[no]enable_propeller_optimize_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for propeller optimize will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_remaining_fdo_absolute_paths"><code><a href="#flag--enable_remaining_fdo_absolute_paths">--[no]enable_remaining_fdo_absolute_paths</a></code> default: "true"</dt> -<dd> -<p>If set, any use of absolute paths for FDO will raise an error.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--enable_runfiles"><code><a href="#flag--enable_runfiles">--[no]enable_runfiles</a></code> default: "auto"</dt> -<dd> -<p>Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--exec_aspects"><code><a href="#flag--exec_aspects">--exec_aspects</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_action_listener"><code><a href="#flag--experimental_action_listener">--experimental_action_listener</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions.</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_compress_java_resources"><code><a href="#flag--experimental_android_compress_java_resources">--[no]experimental_android_compress_java_resources</a></code> default: "false"</dt> -<dd> -<p>Compress Java resources in APKs</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_databinding_v2"><code><a href="#flag--experimental_android_databinding_v2">--[no]experimental_android_databinding_v2</a></code> default: "true"</dt> -<dd> -<p>Use android databinding v2. This flag is a no-op.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_resource_shrinking"><code><a href="#flag--experimental_android_resource_shrinking">--[no]experimental_android_resource_shrinking</a></code> default: "false"</dt> -<dd> -<p>Enables resource shrinking for android_binary APKs that use ProGuard.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_android_rewrite_dexes_with_rex"><code><a href="#flag--experimental_android_rewrite_dexes_with_rex">--[no]experimental_android_rewrite_dexes_with_rex</a></code> default: "false"</dt> -<dd> -<p>use rex tool to rewrite dex files</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_collect_code_coverage_for_generated_files"><code><a href="#flag--experimental_collect_code_coverage_for_generated_files">--[no]experimental_collect_code_coverage_for_generated_files</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will also generate collect coverage information for generated files.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_objc_fastbuild_options"><code><a href="#flag--experimental_objc_fastbuild_options">--experimental_objc_fastbuild_options</a>=<comma-separated list of options></code> default: "-O0,-DDEBUG=1"</dt> -<dd> -<p>Uses these strings as objc fastbuild compiler options.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--experimental_omitfp"><code><a href="#flag--experimental_omitfp">--[no]experimental_omitfp</a></code> default: "false"</dt> -<dd> -<p>If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_output_paths"><code><a href="#flag--experimental_output_paths">--experimental_output_paths</a>=<off or strip></code> default: "off"</dt> -<dd> -<p>Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--experimental_override_platform_cpu_name"><code><a href="#flag--experimental_override_platform_cpu_name">--experimental_override_platform_cpu_name</a>=<a 'label=value' assignment></code> multiple uses are accumulated</dt> -<dd> -<p>Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_platform_in_output_dir"><code><a href="#flag--experimental_platform_in_output_dir">--[no]experimental_platform_in_output_dir</a></code> default: "false"</dt> -<dd> -<p>If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_py_binaries_include_label"><code><a href="#flag--experimental_py_binaries_include_label">--[no]experimental_py_binaries_include_label</a></code> default: "false"</dt> -<dd> -<p>py_binary targets include their label even when stamping is disabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_llvm_covmap"><code><a href="#flag--experimental_use_llvm_covmap">--[no]experimental_use_llvm_covmap</a></code> default: "false"</dt> -<dd> -<p>If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_use_platforms_in_output_dir_legacy_heuristic"><code><a href="#flag--experimental_use_platforms_in_output_dir_legacy_heuristic">--[no]experimental_use_platforms_in_output_dir_legacy_heuristic</a></code> default: "true"</dt> -<dd> -<p>Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--fdo_instrument"><code><a href="#flag--fdo_instrument">--fdo_instrument</a>=<a string></code> default: see description</dt> -<dd> -<p>Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_optimize"><code><a href="#flag--fdo_optimize">--fdo_optimize</a>=<a string></code> default: see description</dt> -<dd> -<p>Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. <code>//foo/bar:file.afdo</code> - you may need to add an <code>exports_files</code> directive to the corresponding package) and labels pointing to <code>fdo_profile</code> targets. This flag will be superseded by the <code>fdo_profile</code> rule.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_prefetch_hints"><code><a href="#flag--fdo_prefetch_hints">--fdo_prefetch_hints</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use cache prefetch hints.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--fdo_profile"><code><a href="#flag--fdo_profile">--fdo_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The fdo_profile representing the profile to be used for optimization.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--features"><code><a href="#flag--features">--features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host_features</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--force_pic"><code><a href="#flag--force_pic">--[no]force_pic</a></code> default: "false"</dt> -<dd> -<p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie").</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_action_env"><code><a href="#flag--host_action_env">--host_action_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_compilation_mode"><code><a href="#flag--host_compilation_mode">--host_compilation_mode</a>=<fastbuild, dbg or opt></code> default: "opt"</dt> -<dd> -<p>Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--host_conlyopt"><code><a href="#flag--host_conlyopt">--host_conlyopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_copt"><code><a href="#flag--host_copt">--host_copt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the C compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cpu"><code><a href="#flag--host_cpu">--host_cpu</a>=<a string></code> default: ""</dt> -<dd> -<p>The host CPU.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_cxxopt"><code><a href="#flag--host_cxxopt">--host_cxxopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to C++ compiler for tools built in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_features"><code><a href="#flag--host_features">--host_features</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_linkopt"><code><a href="#flag--host_linkopt">--host_linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to linker when linking tools in the exec configurations.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--host_macos_minimum_os"><code><a href="#flag--host_macos_minimum_os">--host_macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--host_per_file_copt"><code><a href="#flag--host_per_file_copt">--host_per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--incompatible_auto_exec_groups"><code><a href="#flag--incompatible_auto_exec_groups">--[no]incompatible_auto_exec_groups</a></code> default: "false"</dt> -<dd> -<p>When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify <code>toolchain</code> parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_merge_genfiles_directory"><code><a href="#flag--incompatible_merge_genfiles_directory">--[no]incompatible_merge_genfiles_directory</a></code> default: "true"</dt> -<dd> -<p>If true, the genfiles directory is folded into the bin directory.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_target_cpu_from_platform"><code><a href="#flag--incompatible_target_cpu_from_platform">--[no]incompatible_target_cpu_from_platform</a></code> default: "true"</dt> -<dd> -<p>If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET_CPU) make variable.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--instrument_test_targets"><code><a href="#flag--instrument_test_targets">--[no]instrument_test_targets</a></code> default: "false"</dt> -<dd> -<p>When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--instrumentation_filter"><code><a href="#flag--instrumentation_filter">--instrumentation_filter</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-/javatests[/:],-/test/java[/:]"</dt> -<dd> -<p>When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ios_minimum_os"><code><a href="#flag--ios_minimum_os">--ios_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--ios_multi_cpus"><code><a href="#flag--ios_multi_cpus">--ios_multi_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--legacy_whole_archive"><code><a href="#flag--legacy_whole_archive">--[no]legacy_whole_archive</a></code> default: "true"</dt> -<dd> -<p>Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_DEPRECATED"><code>deprecated</code></a> -</p></dd> -<dt id="flag--linkopt"><code><a href="#flag--linkopt">--linkopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to gcc when linking.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltobackendopt"><code><a href="#flag--ltobackendopt">--ltobackendopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO backend step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--ltoindexopt"><code><a href="#flag--ltoindexopt">--ltoindexopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional option to pass to the LTO indexing step (under --features=thin_lto).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--macos_cpus"><code><a href="#flag--macos_cpus">--macos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple macOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--macos_minimum_os"><code><a href="#flag--macos_minimum_os">--macos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--memprof_profile"><code><a href="#flag--memprof_profile">--memprof_profile</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use memprof profile.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--objc_debug_with_GLIBCXX"><code><a href="#flag--objc_debug_with_GLIBCXX">--[no]objc_debug_with_GLIBCXX</a></code> default: "false"</dt> -<dd> -<p>If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objc_enable_binary_stripping"><code><a href="#flag--objc_enable_binary_stripping">--[no]objc_enable_binary_stripping</a></code> default: "false"</dt> -<dd> -<p>Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--objccopt"><code><a href="#flag--objccopt">--objccopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to gcc when compiling Objective-C/C++ source files.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--per_file_copt"><code><a href="#flag--per_file_copt">--per_file_copt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--per_file_ltobackendopt"><code><a href="#flag--per_file_ltobackendopt">--per_file_ltobackendopt</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--platform_suffix"><code><a href="#flag--platform_suffix">--platform_suffix</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a suffix to be added to the configuration directory.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--propeller_optimize"><code><a href="#flag--propeller_optimize">--propeller_optimize</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_cc_profile"><code><a href="#flag--propeller_optimize_absolute_cc_profile">--propeller_optimize_absolute_cc_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of cc_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--propeller_optimize_absolute_ld_profile"><code><a href="#flag--propeller_optimize_absolute_ld_profile">--propeller_optimize_absolute_ld_profile</a>=<a string></code> default: see description</dt> -<dd> -<p>Absolute path name of ld_profile file for Propeller Optimized builds.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--run_under"><code><a href="#flag--run_under">--run_under</a>=<a prefix in front of command></code> default: see description</dt> -<dd> -<p>Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--share_native_deps"><code><a href="#flag--share_native_deps">--[no]share_native_deps</a></code> default: "true"</dt> -<dd> -<p>If true, native libraries that contain identical functionality will be shared among different targets</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stamp"><code><a href="#flag--stamp">--[no]stamp</a></code> default: "false"</dt> -<dd> -<p>Stamp binaries with the date, username, hostname, workspace information, etc.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--strip"><code><a href="#flag--strip">--strip</a>=<always, sometimes or never></code> default: "sometimes"</dt> -<dd> -<p>Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--stripopt"><code><a href="#flag--stripopt">--stripopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to strip when generating a '<name>.stripped' binary.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--tvos_cpus"><code><a href="#flag--tvos_cpus">--tvos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple tvOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--tvos_minimum_os"><code><a href="#flag--tvos_minimum_os">--tvos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--visionos_cpus"><code><a href="#flag--visionos_cpus">--visionos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple visionOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_cpus"><code><a href="#flag--watchos_cpus">--watchos_cpus</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Comma-separated list of architectures for which to build Apple watchOS binaries.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--watchos_minimum_os"><code><a href="#flag--watchos_minimum_os">--watchos_minimum_os</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'.</p> -<p>Tags: -<a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--xbinary_fdo"><code><a href="#flag--xbinary_fdo">--xbinary_fdo</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -</dl> -<dl>Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<dt id="flag--check_visibility"><code><a href="#flag--check_visibility">--[no]check_visibility</a></code> default: "true"</dt> -<dd> -<p>If disabled, visibility errors in target dependencies are demoted to warnings.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--desugar_for_android"><code><a href="#flag--desugar_for_android">--[no]desugar_for_android</a></code> default: "true"</dt> -<dd> -<p>Whether to desugar Java 8 bytecode before dexing.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--desugar_java8_libs"><code><a href="#flag--desugar_java8_libs">--[no]desugar_java8_libs</a></code> default: "false"</dt> -<dd> -<p>Whether to include supported Java 8 libraries in apps for legacy devices.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--enforce_constraints"><code><a href="#flag--enforce_constraints">--[no]enforce_constraints</a></code> default: "true"</dt> -<dd> -<p>Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a> -</p></dd> -<dt id="flag--experimental_check_desugar_deps"><code><a href="#flag--experimental_check_desugar_deps">--[no]experimental_check_desugar_deps</a></code> default: "true"</dt> -<dd> -<p>Whether to double-check correct desugaring at Android binary level.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_enforce_transitive_visibility"><code><a href="#flag--experimental_enforce_transitive_visibility">--[no]experimental_enforce_transitive_visibility</a></code> default: "false"</dt> -<dd> -<p>If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_one_version_enforcement"><code><a href="#flag--experimental_one_version_enforcement">--experimental_one_version_enforcement</a>=<off, warning or error></code> default: "OFF"</dt> -<dd> -<p>When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--experimental_strict_java_deps"><code><a href="#flag--experimental_strict_java_deps">--experimental_strict_java_deps</a>=<off, warn, error, strict or default></code> default: "default"</dt> -<dd> -<p>If true, checks that a Java target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--incompatible_check_testonly_for_output_files"><code><a href="#flag--incompatible_check_testonly_for_output_files">--[no]incompatible_check_testonly_for_output_files</a></code> default: "false"</dt> -<dd> -<p>If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_android_rules"><code><a href="#flag--incompatible_disable_native_android_rules">--[no]incompatible_disable_native_android_rules</a></code> default: "false"</dt> -<dd> -<p>If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_disable_native_apple_binary_rule"><code><a href="#flag--incompatible_disable_native_apple_binary_rule">--[no]incompatible_disable_native_apple_binary_rule</a></code> default: "false"</dt> -<dd> -<p>No-op. Kept here for backwards compatibility.</p> -<p>Tags: -<a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--one_version_enforcement_on_java_tests"><code><a href="#flag--one_version_enforcement_on_java_tests">--[no]one_version_enforcement_on_java_tests</a></code> default: "true"</dt> -<dd> -<p>When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--python_native_rules_allowlist"><code><a href="#flag--python_native_rules_allowlist">--python_native_rules_allowlist</a>=<a build target label></code> default: see description</dt> -<dd> -<p>An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--strict_filesets"><code><a href="#flag--strict_filesets">--[no]strict_filesets</a></code> default: "false"</dt> -<dd> -<p>If this option is enabled, filesets crossing package boundaries are reported as errors.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--strict_proto_deps"><code><a href="#flag--strict_proto_deps">--strict_proto_deps</a>=<off, warn, error, strict or default></code> default: "error"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_public_imports"><code><a href="#flag--strict_public_imports">--strict_public_imports</a>=<off, warn, error, strict or default></code> default: "off"</dt> -<dd> -<p>Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--strict_system_includes"><code><a href="#flag--strict_system_includes">--[no]strict_system_includes</a></code> default: "false"</dt> -<dd> -<p>If true, headers found through system include paths (-isystem) are also required to be declared.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></a> -</p></dd> -<dt id="flag--target_environment"><code><a href="#flag--target_environment">--target_environment</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -</dl> -<dl>Options that affect the signing outputs of a build: -<dt id="flag--apk_signing_method"><code><a href="#flag--apk_signing_method">--apk_signing_method</a>=<v1, v2, v1_v2 or v4></code> default: "v1_v2"</dt> -<dd> -<p>Implementation to use to sign APKs</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--device_debug_entitlements"><code><a href="#flag--device_debug_entitlements">--[no]device_debug_entitlements</a></code> default: "true"</dt> -<dd> -<p>If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a> -</p></dd> -<dt id="flag--ios_signing_cert_name"><code><a href="#flag--ios_signing_cert_name">--ios_signing_cert_name</a>=<a string></code> default: see description</dt> -<dd> -<p>Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES).</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -</dl> -<dl>This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<dt id="flag--incompatible_disallow_sdk_frameworks_attributes"><code><a href="#flag--incompatible_disallow_sdk_frameworks_attributes">--[no]incompatible_disallow_sdk_frameworks_attributes</a></code> default: "false"</dt> -<dd> -<p>If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_objc_alwayslink_by_default"><code><a href="#flag--incompatible_objc_alwayslink_by_default">--[no]incompatible_objc_alwayslink_by_default</a></code> default: "false"</dt> -<dd> -<p>If true, make the default value true for alwayslink attributes in objc_library and objc_import.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_python_disallow_native_rules"><code><a href="#flag--incompatible_python_disallow_native_rules">--[no]incompatible_python_disallow_native_rules</a></code> default: "false"</dt> -<dd> -<p>When true, an error occurs when using the builtin py_* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Options that govern the behavior of the test environment or test runner: -<dt id="flag--allow_analysis_failures"><code><a href="#flag--allow_analysis_failures">--[no]allow_analysis_failures</a></code> default: "false"</dt> -<dd> -<p>If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--analysis_testing_deps_limit"><code><a href="#flag--analysis_testing_deps_limit">--analysis_testing_deps_limit</a>=<an integer></code> default: "2000"</dt> -<dd> -<p>Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--break_build_on_parallel_dex2oat_failure"><code><a href="#flag--break_build_on_parallel_dex2oat_failure">--[no]break_build_on_parallel_dex2oat_failure</a></code> default: "false"</dt> -<dd> -<p>If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--default_test_resources"><code><a href="#flag--default_test_resources">--default_test_resources</a>=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100></code> multiple uses are accumulated</dt> -<dd> -<p>Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by [-|<em>]<float> (eg. memory=HOST_RAM</em>.1,HOST_RAM*.2,HOST_RAM*.3,HOST_RAM*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags.</p> -</dd> -<dt id="flag--experimental_android_use_parallel_dex2oat"><code><a href="#flag--experimental_android_use_parallel_dex2oat">--[no]experimental_android_use_parallel_dex2oat</a></code> default: "false"</dt> -<dd> -<p>Use dex2oat in parallel to possibly speed up android_test.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--ios_memleaks"><code><a href="#flag--ios_memleaks">--[no]ios_memleaks</a></code> default: "false"</dt> -<dd> -<p>Enable checking for memory leaks in ios_test targets.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a> -</p></dd> -<dt id="flag--ios_simulator_device"><code><a href="#flag--ios_simulator_device">--ios_simulator_device</a>=<a string></code> default: see description</dt> -<dd> -<p>The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--ios_simulator_version"><code><a href="#flag--ios_simulator_version">--ios_simulator_version</a>=<a dotted version (for example '2.3' or '3.3alpha2.4')></code> default: see description</dt> -<dd> -<p>The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--runs_per_test"><code><a href="#flag--runs_per_test">--runs_per_test</a>=<a positive integer or test_regex@runs. This flag may be passed more than once></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.<em>,-//foo/bar/.</em>@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once.</p> -</dd> -<dt id="flag--test_env"><code><a href="#flag--test_env">--test_env</a>=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -<dt id="flag--test_timeout"><code><a href="#flag--test_timeout">--test_timeout</a>=<a single integer or comma-separated list of 4 integers></code> default: "-1"</dt> -<dd> -<p>Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category.</p> -</dd> -<dt id="flag--zip_undeclared_test_outputs"><code><a href="#flag--zip_undeclared_test_outputs">--[no]zip_undeclared_test_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, undeclared test outputs will be archived in a zip file.</p> -<p>Tags: -<a href="#effect_tag_TEST_RUNNER"><code>test_runner</code></a> -</p></dd> -</dl> -<dl>Options that trigger optimizations of the build time: -<dt id="flag--experimental_filter_library_jar_with_program_jar"><code><a href="#flag--experimental_filter_library_jar_with_program_jar">--[no]experimental_filter_library_jar_with_program_jar</a></code> default: "false"</dt> -<dd> -<p>Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar.</p> -<p>Tags: -<a href="#effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_dotd_files"><code><a href="#flag--experimental_inmemory_dotd_files">--[no]experimental_inmemory_dotd_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_inmemory_jdeps_files"><code><a href="#flag--experimental_inmemory_jdeps_files">--[no]experimental_inmemory_jdeps_files</a></code> default: "true"</dt> -<dd> -<p>If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_retain_test_configuration_across_testonly"><code><a href="#flag--experimental_retain_test_configuration_across_testonly">--[no]experimental_retain_test_configuration_across_testonly</a></code> default: "false"</dt> -<dd> -<p>When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_unsupported_and_brittle_include_scanning"><code><a href="#flag--experimental_unsupported_and_brittle_include_scanning">--[no]experimental_unsupported_and_brittle_include_scanning</a></code> default: "false"</dt> -<dd> -<p>Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a>, <a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--incremental_dexing"><code><a href="#flag--incremental_dexing">--[no]incremental_dexing</a></code> default: "true"</dt> -<dd> -<p>Does most of the work for dexing separately for each Jar file.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -<dt id="flag--objc_use_dotd_pruning"><code><a href="#flag--objc_use_dotd_pruning">--[no]objc_use_dotd_pruning</a></code> default: "true"</dt> -<dd> -<p>If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--process_headers_in_dependencies"><code><a href="#flag--process_headers_in_dependencies">--[no]process_headers_in_dependencies</a></code> default: "false"</dt> -<dd> -<p>When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain).</p> -<p>Tags: -<a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -<dt id="flag--trim_test_configuration"><code><a href="#flag--trim_test_configuration">--[no]trim_test_configuration</a></code> default: "true"</dt> -<dd> -<p>When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></a> -</p></dd> -</dl> -<dl>Options that affect the verbosity, format or location of logging: -<dt id="flag--toolchain_resolution_debug"><code><a href="#flag--toolchain_resolution_debug">--toolchain_resolution_debug</a>=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths></code> default: "-.*"</dt> -<dd> -<p>Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution.</p> -<p>Tags: -<a href="#effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></a> -</p></dd> -<dt id="flag--verbose_visibility_errors"><code><a href="#flag--verbose_visibility_errors">--[no]verbose_visibility_errors</a></code> default: "false"</dt> -<dd> -<p>If enabled, visibility errors include additional diagnostic information.</p> -<p>Tags: -<a href="#effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -</dl> -<dl>Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<dt id="flag--flag_alias"><code><a href="#flag--flag_alias">--flag_alias</a>=<a 'name=value' flag alias></code> multiple uses are accumulated</dt> -<dd> -<p>Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument.</p> -<p>Tags: -<a href="#effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></a>, <a href="#metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></a> -</p></dd> -<dt id="flag--incompatible_default_to_explicit_init_py"><code><a href="#flag--incompatible_default_to_explicit_init_py">--[no]incompatible_default_to_explicit_init_py</a></code> default: "false"</dt> -<dd> -<p>This flag changes the default behavior so that <strong>init</strong>.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -</dl> -<dl>Miscellaneous options, not otherwise categorized.: -<dt id="flag--cache_test_results"><code><a href="#flag--cache_test_results">--[no]cache_test_results</a></code> [<code>-t</code>] default: "auto"</dt> -<dd> -<p>If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results.</p> -</dd> -<dt id="flag--experimental_cancel_concurrent_tests"><code><a href="#flag--experimental_cancel_concurrent_tests">--[no]experimental_cancel_concurrent_tests</a></code> default: "never"</dt> -<dd> -<p>If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_fetch_all_coverage_outputs"><code><a href="#flag--experimental_fetch_all_coverage_outputs">--[no]experimental_fetch_all_coverage_outputs</a></code> default: "false"</dt> -<dd> -<p>If true, then Bazel fetches the entire coverage data directory for each test during a coverage run.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_generate_llvm_lcov"><code><a href="#flag--experimental_generate_llvm_lcov">--[no]experimental_generate_llvm_lcov</a></code> default: "false"</dt> -<dd> -<p>If true, coverage for clang will generate an LCOV report.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--experimental_java_classpath"><code><a href="#flag--experimental_java_classpath">--experimental_java_classpath</a>=<off, javabuilder, bazel or bazel_no_fallback></code> default: "bazel"</dt> -<dd> -<p>Enables reduced classpaths for Java compilations.</p> -</dd> -<dt id="flag--experimental_run_android_lint_on_java_rules"><code><a href="#flag--experimental_run_android_lint_on_java_rules">--[no]experimental_run_android_lint_on_java_rules</a></code> default: "false"</dt> -<dd> -<p>Whether to validate java_* sources.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#metadata_tag_EXPERIMENTAL"><code>experimental</code></a> -</p></dd> -<dt id="flag--explicit_java_test_deps"><code><a href="#flag--explicit_java_test_deps">--[no]explicit_java_test_deps</a></code> default: "false"</dt> -<dd> -<p>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.</p> -</dd> -<dt id="flag--host_java_launcher"><code><a href="#flag--host_java_launcher">--host_java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher used by tools that are executed during a build.</p> -</dd> -<dt id="flag--host_javacopt"><code><a href="#flag--host_javacopt">--host_javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac when building tools that are executed during a build.</p> -</dd> -<dt id="flag--host_jvmopt"><code><a href="#flag--host_jvmopt">--host_jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--incompatible_check_sharding_support"><code><a href="#flag--incompatible_check_sharding_support">--[no]incompatible_check_sharding_support</a></code> default: "true"</dt> -<dd> -<p>If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard.</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_exclusive_test_sandboxed"><code><a href="#flag--incompatible_exclusive_test_sandboxed">--[no]incompatible_exclusive_test_sandboxed</a></code> default: "true"</dt> -<dd> -<p>If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally</p> -<p>Tags: -<a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--incompatible_strict_action_env"><code><a href="#flag--incompatible_strict_action_env">--[no]incompatible_strict_action_env</a></code> default: "false"</dt> -<dd> -<p>If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a>, <a href="#metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></a> -</p></dd> -<dt id="flag--j2objc_translation_flags"><code><a href="#flag--j2objc_translation_flags">--j2objc_translation_flags</a>=<comma-separated list of options></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the J2ObjC tool.</p> -</dd> -<dt id="flag--java_debug"><code><a href="#flag--java_debug">--java_debug</a></code></dt> -<dd> -<p>Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed.</p> -<p>Expands to: -<br/>  <code><a href="#flag--test_arg">--test_arg=--wrapper_script_flag=--debug</a></code> -<br/>  <code><a href="#flag--test_output">--test_output=streamed</a></code> -<br/>  <code><a href="#flag--test_strategy">--test_strategy=exclusive</a></code> -<br/>  <code><a href="#flag--test_timeout">--test_timeout=9999</a></code> -<br/>  <code><a href="#flag--nocache_test_results">--nocache_test_results</a></code> -</p></dd> -<dt id="flag--java_deps"><code><a href="#flag--java_deps">--[no]java_deps</a></code> default: "true"</dt> -<dd> -<p>Generate dependency information (for now, compile-time classpath) per Java target.</p> -</dd> -<dt id="flag--java_header_compilation"><code><a href="#flag--java_header_compilation">--[no]java_header_compilation</a></code> default: "true"</dt> -<dd> -<p>Compile ijars directly from source.</p> -</dd> -<dt id="flag--java_language_version"><code><a href="#flag--java_language_version">--java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version</p> -</dd> -<dt id="flag--java_launcher"><code><a href="#flag--java_launcher">--java_launcher</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag.</p> -</dd> -<dt id="flag--java_runtime_version"><code><a href="#flag--java_runtime_version">--java_runtime_version</a>=<a string></code> default: "local_jdk"</dt> -<dd> -<p>The Java runtime version</p> -</dd> -<dt id="flag--javacopt"><code><a href="#flag--javacopt">--javacopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to javac.</p> -</dd> -<dt id="flag--jvmopt"><code><a href="#flag--jvmopt">--jvmopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target.</p> -</dd> -<dt id="flag--legacy_main_dex_list_generator"><code><a href="#flag--legacy_main_dex_list_generator">--legacy_main_dex_list_generator</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex.</p> -</dd> -<dt id="flag--optimizing_dexer"><code><a href="#flag--optimizing_dexer">--optimizing_dexer</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies a binary to use to do dexing without sharding.</p> -</dd> -<dt id="flag--plugin"><code><a href="#flag--plugin">--plugin</a>=<a build target label></code> multiple uses are accumulated</dt> -<dd> -<p>Plugins to use in the build. Currently works with java_plugin.</p> -</dd> -<dt id="flag--proguard_top"><code><a href="#flag--proguard_top">--proguard_top</a>=<a build target label></code> default: see description</dt> -<dd> -<p>Specifies which version of ProGuard to use for code removal when building a Java binary.</p> -</dd> -<dt id="flag--proto_compiler"><code><a href="#flag--proto_compiler">--proto_compiler</a>=<a build target label></code> default: "@bazel_tools//tools/proto:protoc"</dt> -<dd> -<p>The label of the proto-compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile"><code><a href="#flag--proto_profile">--[no]proto_profile</a></code> default: "true"</dt> -<dd> -<p>Whether to pass profile_path to the proto compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_profile_path"><code><a href="#flag--proto_profile_path">--proto_profile_path</a>=<a build target label></code> default: see description</dt> -<dd> -<p>The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_cc"><code><a href="#flag--proto_toolchain_for_cc">--proto_toolchain_for_cc</a>=<a build target label></code> default: "@bazel_tools//tools/proto:cc_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile C++ protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_j2objc"><code><a href="#flag--proto_toolchain_for_j2objc">--proto_toolchain_for_j2objc</a>=<a build target label></code> default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile j2objc protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_java"><code><a href="#flag--proto_toolchain_for_java">--proto_toolchain_for_java</a>=<a build target label></code> default: "@bazel_tools//tools/proto:java_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile Java protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--proto_toolchain_for_javalite"><code><a href="#flag--proto_toolchain_for_javalite">--proto_toolchain_for_javalite</a>=<a build target label></code> default: "@bazel_tools//tools/proto:javalite_toolchain"</dt> -<dd> -<p>Label of proto_lang_toolchain() which describes how to compile JavaLite protos</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--protocopt"><code><a href="#flag--protocopt">--protocopt</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Additional options to pass to the protobuf compiler.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a> -</p></dd> -<dt id="flag--runs_per_test_detects_flakes"><code><a href="#flag--runs_per_test_detects_flakes">--[no]runs_per_test_detects_flakes</a></code> default: "false"</dt> -<dd> -<p>If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status.</p> -</dd> -<dt id="flag--shell_executable"><code><a href="#flag--shell_executable">--shell_executable</a>=<a path></code> default: see description</dt> -<dd> -<p>Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries.</p> -<p>Tags: -<a href="#effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></a> -</p></dd> -<dt id="flag--test_arg"><code><a href="#flag--test_arg">--test_arg</a>=<a string></code> multiple uses are accumulated</dt> -<dd> -<p>Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command.</p> -</dd> -<dt id="flag--test_filter"><code><a href="#flag--test_filter">--test_filter</a>=<a string></code> default: see description</dt> -<dd> -<p>Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built.</p> -</dd> -<dt id="flag--test_result_expiration"><code><a href="#flag--test_result_expiration">--test_result_expiration</a>=<an integer></code> default: "-1"</dt> -<dd> -<p>This option is deprecated and has no effect.</p> -</dd> -<dt id="flag--test_runner_fail_fast"><code><a href="#flag--test_runner_fail_fast">--[no]test_runner_fail_fast</a></code> default: "false"</dt> -<dd> -<p>Forwards fail fast option to the test runner. The test runner should stop execution upon first failure.</p> -</dd> -<dt id="flag--test_sharding_strategy"><code><a href="#flag--test_sharding_strategy">--test_sharding_strategy</a>=<explicit, disabled or forced=k where k is the number of shards to enforce></code> default: "explicit"</dt> -<dd> -<p>Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute.</p> -</dd> -<dt id="flag--tool_java_language_version"><code><a href="#flag--tool_java_language_version">--tool_java_language_version</a>=<a string></code> default: ""</dt> -<dd> -<p>The Java language version used to execute the tools that are needed during a build</p> -</dd> -<dt id="flag--tool_java_runtime_version"><code><a href="#flag--tool_java_runtime_version">--tool_java_runtime_version</a>=<a string></code> default: "remotejdk_11"</dt> -<dd> -<p>The Java runtime version used to execute tools during the build</p> -</dd> -<dt id="flag--use_ijars"><code><a href="#flag--use_ijars">--[no]use_ijars</a></code> default: "true"</dt> -<dd> -<p>If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different.</p> -</dd> -</dl> - -<h2><a name="version">Version Options</a></h2> -<dl>Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<dt id="version-flag--gnu_format"><code id="gnu_format"><a href="#version-flag--gnu_format">--[no]gnu_format</a></code> default: "false"</dt> -<dd> -<p>If set, write the version to stdout using the conventions described in the GNU standards.</p> -<p>Tags: -<a href="#effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></a>, <a href="#effect_tag_EXECUTION"><code>execution</code></a> -</p></dd> -</dl> - -<h3>Option Effect Tags</h3> -<table> -<tr> -<td id="effect_tag_UNKNOWN"><code>unknown</code></td> -<td>This option has unknown, or undocumented, effect.</td> -</tr> -<tr> -<td id="effect_tag_NO_OP"><code>no_op</code></td> -<td>This option has literally no effect.</td> -</tr> -<tr> -<td id="effect_tag_LOSES_INCREMENTAL_STATE"><code>loses_incremental_state</code></td> -<td>Changing the value of this option can cause significant loss of incremental state, which slows builds. State could be lost due to a server restart or to invalidation of a large part of the dependency graph.</td> -</tr> -<tr> -<td id="effect_tag_CHANGES_INPUTS"><code>changes_inputs</code></td> -<td>This option actively changes the inputs that bazel considers for the build, such as filesystem restrictions, repository versions, or other options.</td> -</tr> -<tr> -<td id="effect_tag_AFFECTS_OUTPUTS"><code>affects_outputs</code></td> -<td>This option affects bazel's outputs. This tag is intentionally broad, can include transitive affects, and does not specify the type of output it affects.</td> -</tr> -<tr> -<td id="effect_tag_BUILD_FILE_SEMANTICS"><code>build_file_semantics</code></td> -<td>This option affects the semantics of BUILD or .bzl files.</td> -</tr> -<tr> -<td id="effect_tag_BAZEL_INTERNAL_CONFIGURATION"><code>bazel_internal_configuration</code></td> -<td>This option affects settings of bazel-internal machinery. This tag does not, on its own, mean that build artifacts are affected.</td> -</tr> -<tr> -<td id="effect_tag_LOADING_AND_ANALYSIS"><code>loading_and_analysis</code></td> -<td>This option affects the loading and analysis of dependencies, and the building of the dependency graph.</td> -</tr> -<tr> -<td id="effect_tag_EXECUTION"><code>execution</code></td> -<td>This option affects the execution phase, such as sandboxing or remote execution related options.</td> -</tr> -<tr> -<td id="effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS"><code>host_machine_resource_optimizations</code></td> -<td>This option triggers an optimization that may be machine specific and is not guaranteed to work on all machines. The optimization could include a tradeoff with other aspects of performance, such as memory or cpu cost.</td> -</tr> -<tr> -<td id="effect_tag_EAGERNESS_TO_EXIT"><code>eagerness_to_exit</code></td> -<td>This option changes how eagerly bazel will exit from a failure, where a choice between continuing despite the failure and ending the invocation exists.</td> -</tr> -<tr> -<td id="effect_tag_BAZEL_MONITORING"><code>bazel_monitoring</code></td> -<td>This option is used to monitor bazel's behavior and performance.</td> -</tr> -<tr> -<td id="effect_tag_TERMINAL_OUTPUT"><code>terminal_output</code></td> -<td>This option affects bazel's terminal output.</td> -</tr> -<tr> -<td id="effect_tag_ACTION_COMMAND_LINES"><code>action_command_lines</code></td> -<td>This option changes the command line arguments of one or more build actions.</td> -</tr> -<tr> -<td id="effect_tag_TEST_RUNNER"><code>test_runner</code></td> -<td>This option changes the testrunner environment of the build.</td> -</tr> -</table> -<h3>Option Metadata Tags</h3> -<table> -<tr> -<td id="metadata_tag_EXPERIMENTAL"><code>experimental</code></td> -<td>This option triggers an experimental feature with no guarantees of functionality.</td> -</tr> -<tr> -<td id="metadata_tag_INCOMPATIBLE_CHANGE"><code>incompatible_change</code></td> -<td>This option triggers a breaking change. Use this option to test your migration readiness or get early access to the new feature</td> -</tr> -<tr> -<td id="metadata_tag_DEPRECATED"><code>deprecated</code></td> -<td>This option is deprecated. It might be that the feature it affects is deprecated, or that another method of supplying the information is preferred.</td> -</tr> -<tr> -<td id="metadata_tag_NON_CONFIGURABLE"><code>non_configurable</code></td> -<td>This option cannot be changed in a transition or be used in a select() statement.</td> -</tr> -</table> - -<br/><br/><br/><br/> -</body> -</html> +For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--remote_proxy`](#common_options-flag--remote_proxy)`=<a string>` default: see description +Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). + +[`--remote_result_cache_priority`](#common_options-flag--remote_result_cache_priority)`=<an integer>` default: "0" +The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. + +[`--remote_retries`](#common_options-flag--remote_retries)`=<an integer>` default: "5" +The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. + +[`--remote_retry_max_delay`](#common_options-flag--remote_retry_max_delay)`=<An immutable length of time.>` default: "5s" +The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +[`--remote_timeout`](#common_options-flag--remote_timeout)`=<An immutable length of time.>` default: "60s" +The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +[`--[no]remote_upload_local_results`](#common_options-flag--remote_upload_local_results) default: "true" +Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. + +[`--[no]remote_verify_downloads`](#common_options-flag--remote_verify_downloads) default: "true" +If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. + +<!-- --> + +[`--build_metadata`](#common_options-flag--build_metadata)`=<a 'name=value' assignment>` multiple uses are accumulated +Custom key-value string pairs to supply in a build event. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--color`](#common_options-flag--color)`=<yes, no or auto>` default: "auto" +Use terminal controls to colorize output. + +[`--config`](#common_options-flag--config)`=<a string>` multiple uses are accumulated +Selects additional config sections from the rc files; for every \<command\>, it also pulls in the options from \<command\>:\<config\> if such a section exists; if this section doesn't exist in any .rc file, Blaze fails with an error. The config sections and flag combinations they are equivalent to are located in the tools/\*.blazerc config files. + +[`--credential_helper`](#common_options-flag--credential_helper)`=<Path to a credential helper. It may be absolute, relative to the PATH environment variable, or %workspace%-relative. The path be optionally prefixed by a scope followed by an '='. The scope is a domain name, optionally with a single leading '*' wildcard component. A helper applies to URIs matching its scope, with more specific scopes preferred. If a helper has no scope, it applies to every URI.>` multiple uses are accumulated +Configures a credential helper conforming to the \<a href="https://github.com/EngFlow/credential-helper-spec"\>Credential Helper Specification\</a\> to use for retrieving authorization credentials for repository fetching, remote caching and execution, and the build event service. + +Credentials supplied by a helper take precedence over credentials supplied by `--google_default_credentials`, `--google_credentials`, a `.netrc` file, or the auth parameter to `repository_ctx.download()` and `repository_ctx.download_and_extract()`. + +May be specified multiple times to set up multiple helpers. + +See https://blog.engflow.com/2023/10/09/configuring-bazels-credential-helper/ for instructions. + +[`--credential_helper_cache_duration`](#common_options-flag--credential_helper_cache_duration)`=<An immutable length of time.>` default: "30m" +How long to cache credentials for if the credential helper doesn't return an expiration time. Changing the value of this flag clears the cache. + +[`--credential_helper_timeout`](#common_options-flag--credential_helper_timeout)`=<An immutable length of time.>` default: "10s" +Configures the timeout for a credential helper. + +Credential helpers failing to respond within this timeout will fail the invocation. + +[`--curses`](#common_options-flag--curses)`=<yes, no or auto>` default: "auto" +Use terminal cursor controls to minimize scrolling output. + +[`--disk_cache`](#common_options-flag--disk_cache)`=<a path>` default: see description +A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. + +[`--[no]enable_platform_specific_config`](#common_options-flag--enable_platform_specific_config) default: "true" +If true, Bazel picks up host-OS-specific config lines from bazelrc files. For example, if the host OS is Linux and you run bazel build, Bazel picks up lines starting with build:linux. Supported OS identifiers are linux, macos, windows, freebsd, and openbsd. Enabling this flag is equivalent to using --config=linux on Linux, --config=windows on Windows, etc. + +[`--experimental_action_cache_gc_idle_delay`](#common_options-flag--experimental_action_cache_gc_idle_delay)`=<An immutable length of time.>` default: "5m" +How long the server must remain idle before a garbage collection of the action cache is attempted. Ineffectual unless --experimental_action_cache_gc_max_age is nonzero. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--experimental_action_cache_gc_max_age`](#common_options-flag--experimental_action_cache_gc_max_age)`=<An immutable length of time.>` default: "0" +If set to a nonzero value, the action cache will be periodically garbage collected to remove entries older than this age. Garbage collection occurs in the background once the server has become idle, as determined by the --experimental_action_cache_gc_idle_delay and --experimental_action_cache_gc_threshold flags. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--experimental_action_cache_gc_threshold`](#common_options-flag--experimental_action_cache_gc_threshold)`=<an integer in 0-100 range>` default: "10" +The percentage of stale action cache entries required for garbage collection to be triggered. Ineffectual unless --experimental_action_cache_gc_max_age is nonzero. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--experimental_disk_cache_gc_idle_delay`](#common_options-flag--experimental_disk_cache_gc_idle_delay)`=<An immutable length of time.>` default: "5m" +How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental_disk_cache_gc_max_size and/or --experimental_disk_cache_gc_max_age. + +[`--experimental_disk_cache_gc_max_age`](#common_options-flag--experimental_disk_cache_gc_max_age)`=<An immutable length of time.>` default: "0" +If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental_disk_cache_gc_max_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag. + +[`--experimental_disk_cache_gc_max_size`](#common_options-flag--experimental_disk_cache_gc_max_size)`=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" +If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental_disk_cache_gc_max_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag. + +[`--[no]experimental_enable_thread_dump`](#common_options-flag--experimental_enable_thread_dump) default: "false" +Whether to enable thread dumps. If true, Bazel will dump the state of all threads (including virtual threads) to a file every --experimental_thread_dump_interval, or after action execution being inactive for --experimental_thread_dump_action_execution_inactivity_duration. The dumps will be written to the \<output_base\>/server/thread_dumps/ directory. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--experimental_install_base_gc_max_age`](#common_options-flag--experimental_install_base_gc_max_age)`=<An immutable length of time.>` default: "30d" +How long an install base must go unused before it's eligible for garbage collection. If nonzero, the server will attempt to garbage collect other install bases when idle. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]experimental_rule_extension_api`](#common_options-flag--experimental_rule_extension_api) default: "true" +Enable experimental rule extension API and subrule APIs + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_thread_dump_action_execution_inactivity_duration`](#common_options-flag--experimental_thread_dump_action_execution_inactivity_duration)`=<An immutable length of time.>` default: "0" +Dump the threads when action execution being inactive for this duration. If zero, no thread dumps are written for action execution being inactive. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--experimental_thread_dump_interval`](#common_options-flag--experimental_thread_dump_interval)`=<An immutable length of time.>` default: "0" +How often to dump the threads periodically. If zero, no thread dumps are written periodically. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]experimental_windows_watchfs`](#common_options-flag--experimental_windows_watchfs) default: "false" +If true, experimental Windows support for --watchfs is enabled. Otherwise --watchfsis a non-op on Windows. Make sure to also enable --watchfs. + +[`--google_auth_scopes`](#common_options-flag--google_auth_scopes)`=<comma-separated list of options>` default: "https://www.googleapis.com/auth/cloud-platform" +A comma-separated list of Google Cloud authentication scopes. + +[`--google_credentials`](#common_options-flag--google_credentials)`=<a string>` default: see description +Specifies the file to get authentication credentials from. See https://cloud.google.com/docs/authentication for details. + +[`--[no]google_default_credentials`](#common_options-flag--google_default_credentials) default: "false" +Whether to use 'Google Application Default Credentials' for authentication. See https://cloud.google.com/docs/authentication for details. Disabled by default. + +[`--grpc_keepalive_time`](#common_options-flag--grpc_keepalive_time)`=<An immutable length of time.>` default: see description +Configures keep-alive pings for outgoing gRPC connections. If this is set, then Bazel sends pings after this much time of no read operations on the connection, but only if there is at least one pending gRPC call. Times are treated as second granularity; it is an error to set a value less than one second. By default, keep-alive pings are disabled. You should coordinate with the service owner before enabling this setting. For example to set a value of 30 seconds to this flag, it should be done as this --grpc_keepalive_time=30s + +[`--grpc_keepalive_timeout`](#common_options-flag--grpc_keepalive_timeout)`=<An immutable length of time.>` default: "20s" +Configures a keep-alive timeout for outgoing gRPC connections. If keep-alive pings are enabled with --grpc_keepalive_time, then Bazel times out a connection if it does not receive a ping reply after this much time. Times are treated as second granularity; it is an error to set a value less than one second. If keep-alive pings are disabled, then this setting is ignored. + +[`--[no]incompatible_disable_non_executable_java_binary`](#common_options-flag--incompatible_disable_non_executable_java_binary) default: "false" +If true, java_binary is always executable. create_executable attribute is removed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_repo_env_ignores_action_env`](#common_options-flag--incompatible_repo_env_ignores_action_env) default: "true" +If true, \<code\>--action_env=NAME=VALUE\</code\> will no longer affect repository rule and module extension environments. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--inject_repository`](#common_options-flag--inject_repository)`=<an equals-separated mapping of repository name to path>` multiple uses are accumulated +Adds a new repository with a local path in the form of \<repository name\>=\<path\>. This only takes effect with --enable_bzlmod and is equivalent to adding a corresponding `local_repository` to the root module's MODULE.bazel file via `use_repo_rule`. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%', it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous injections. + +[`--invocation_id`](#common_options-flag--invocation_id)`=<a UUID>` default: "" +Unique identifier, in UUID format, for the command being run. If explicitly specified uniqueness must be ensured by the caller. The UUID is printed to stderr, the BEP and remote execution protocol. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--override_repository`](#common_options-flag--override_repository)`=<an equals-separated mapping of repository name to path>` multiple uses are accumulated +Override a repository with a local path in the form of \<repository name\>=\<path\>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. + +[`--[no]progress_in_terminal_title`](#common_options-flag--progress_in_terminal_title) default: "false" +Show the command progress in the terminal title. Useful to see what bazel is doing when having multiple terminal tabs. + +[`--[no]show_progress`](#common_options-flag--show_progress) default: "true" +Display progress messages during a build. + +[`--show_progress_rate_limit`](#common_options-flag--show_progress_rate_limit)`=<a double>` default: "0.2" +Minimum number of seconds between progress messages in the output. + +[`--[no]show_timestamps`](#common_options-flag--show_timestamps) default: "false" +Include timestamps in messages + +[`--tls_certificate`](#common_options-flag--tls_certificate)`=<a string>` default: see description +Specify a path to a TLS certificate that is trusted to sign server certificates. + +[`--tls_client_certificate`](#common_options-flag--tls_client_certificate)`=<a string>` default: see description +Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication. + +[`--tls_client_key`](#common_options-flag--tls_client_key)`=<a string>` default: see description +Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication. + +[`--ui_actions_shown`](#common_options-flag--ui_actions_shown)`=<an integer>` default: "8" +Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]watchfs`](#common_options-flag--watchfs) default: "false" +On Linux/macOS: If true, bazel tries to use the operating system's file watch service for local changes instead of scanning every file for a change. On Windows: this flag currently is a non-op but can be enabled in conjunction with --experimental_windows_watchfs. On any OS: The behavior is undefined if your workspace is on a network file system, and files are edited on a remote machine. + +## <span id="aquery">Aquery Options</span> + +Inherits all options from [build](#build). + +[`--aspect_deps`](#aquery-flag--aspect_deps)`=<off, conservative or precise>` default: "conservative" +How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]consistent_labels`](#aquery-flag--consistent_labels) default: "false" +If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]experimental_explicit_aspects`](#aquery-flag--experimental_explicit_aspects) default: "false" +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]graph:factored`](#aquery-flag--graph:factored) default: "true" +If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--graph:node_limit`](#aquery-flag--graph:node_limit)`=<an integer>` default: "512" +The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]implicit_deps`](#aquery-flag--implicit_deps) default: "true" +If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]include_artifacts`](#aquery-flag--include_artifacts) default: "true" +Includes names of the action inputs and outputs in the output (potentially large). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]include_aspects`](#aquery-flag--include_aspects) default: "true" +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]include_commandline`](#aquery-flag--include_commandline) default: "true" +Includes the content of the action command lines in the output (potentially large). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]include_file_write_contents`](#aquery-flag--include_file_write_contents) default: "false" +Include the file contents for the FileWrite, SourceSymlinkManifest, and RepoMappingManifest actions (potentially large). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]include_param_files`](#aquery-flag--include_param_files) default: "false" +Include the content of the param files used in the command (potentially large). Note: Enabling this flag will automatically enable the --include_commandline flag. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]include_pruned_inputs`](#aquery-flag--include_pruned_inputs) default: "true" +Includes action inputs that were pruned during action execution. Only affects actions that discover inputs and have been executed in a previous invocation. Only takes effect if --include_artifacts is also set. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]incompatible_package_group_includes_double_slash`](#aquery-flag--incompatible_package_group_includes_double_slash) default: "true" +If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]infer_universe_scope`](#aquery-flag--infer_universe_scope) default: "false" +If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]line_terminator_null`](#aquery-flag--line_terminator_null) default: "false" +Whether each format is terminated with \0 instead of newline. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]nodep_deps`](#aquery-flag--nodep_deps) default: "true" +If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--output`](#aquery-flag--output)`=<a string>` default: "text" +The format in which the aquery results should be printed. Allowed values for aquery are: text, textproto, proto, streamed_proto, jsonproto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--output_file`](#aquery-flag--output_file)`=<a string>` default: "" +When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:default_values`](#aquery-flag--proto:default_values) default: "true" +If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:definition_stack`](#aquery-flag--proto:definition_stack) default: "false" +Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:flatten_selects`](#aquery-flag--proto:flatten_selects) default: "true" +If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]proto:include_attribute_source_aspects`](#aquery-flag--proto:include_attribute_source_aspects) default: "false" +Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:include_starlark_rule_env`](#aquery-flag--proto:include_starlark_rule_env) default: "true" +Use the starlark environment in the value of the generated \$internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:include_synthetic_attribute_hash`](#aquery-flag--proto:include_synthetic_attribute_hash) default: "false" +Whether or not to calculate and populate the \$internal_attr_hash attribute. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:instantiation_stack`](#aquery-flag--proto:instantiation_stack) default: "false" +Populate the instantiation call stack of each rule. Note that this requires the stack to be present + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:locations`](#aquery-flag--proto:locations) default: "true" +Whether to output location information in proto output at all. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--proto:output_rule_attrs`](#aquery-flag--proto:output_rule_attrs)`=<comma-separated list of options>` default: "all" +Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:rule_classes`](#aquery-flag--proto:rule_classes) default: "false" +Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:rule_inputs_and_outputs`](#aquery-flag--proto:rule_inputs_and_outputs) default: "true" +Whether or not to populate the rule_input and rule_output fields. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--query_file`](#aquery-flag--query_file)`=<a string>` default: "" +If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--[no]relative_locations`](#aquery-flag--relative_locations) default: "false" +If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]skyframe_state`](#aquery-flag--skyframe_state) default: "false" +Without performing extra analysis, dump the current Action Graph from Skyframe. Note: Specifying a target with --skyframe_state is currently not supported. This flag is only available with --output=proto or --output=textproto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]tool_deps`](#aquery-flag--tool_deps) default: "true" +Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--universe_scope`](#aquery-flag--universe_scope)`=<comma-separated list of options>` default: "" +A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" +When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +Enable persistent Android dex and desugar actions by using workers. + +Expands to: +  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) +  [`--strategy=Desugar=worker`](#flag--strategy) +  [`--strategy=DexBuilder=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +Enable persistent Android resource processor by using workers. + +Expands to: +  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) +  [`--strategy=AaptPackage=worker`](#flag--strategy) +  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) +  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) +  [`--strategy=RClassGenerator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) +  [`--strategy=AndroidAapt2=worker`](#flag--strategy) +  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) +  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) +  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) +  [`--strategy=ManifestMerger=worker`](#flag--strategy) +  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) +  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) +  [`--strategy=AARGenerator=worker`](#flag--strategy) +  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) +  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: +  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: +  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: +  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) +  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" +Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" +Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compiler`](#flag--compiler)`=<a string>` default: see description +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--grte_top`](#flag--grte_top)`=<a label>` default: see description +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description +If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" +If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--platforms`](#flag--platforms)`=<a build target label>` default: "" +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_path`](#flag--python_path)`=<a string>` default: see description +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" +Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" +The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" +Sets the suffixes of header files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" +Sets the suffixes of source files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" +Run extra actions for alternative Java api versions in a proto_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" +If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" +If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]save_temps`](#flag--save_temps) default: "false" +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case +the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +\<br\> +Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" +Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cpu`](#flag--cpu)`=<a string>` default: "" +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description +The cs_fdo_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated +Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" +py_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description +The fdo_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--features`](#flag--features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]force_pic`](#flag--force_pic) default: "false" +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" +Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO backend step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO indexing step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" +If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description +Absolute path name of cc_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description +Absolute path name of ld_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]stamp`](#flag--stamp) default: "false" +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated +Additional options to pass to strip when generating a '\<name\>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--[no]check_visibility`](#flag--check_visibility) default: "true" +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_check_desugar_deps`](#flag--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`](#flag--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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" +When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" +When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description +An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" +Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" +Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +<!-- --> + +[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" +If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" +If true, make the default value true for alwayslink attributes in objc_library and objc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" +When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" +Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" +Use dex2oat in parallel to possibly speed up android_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" +Enable checking for memory leaks in ios_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +<!-- --> + +[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" +When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" +Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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`](#flag--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`](#flag--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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +<!-- --> + +[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" +If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +Enables reduced classpaths for Java compilations. + +[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]explicit_java_test_deps`](#flag--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. + +[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description +The Java launcher used by tools that are executed during a build. + +[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac when building tools that are executed during a build. + +[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. + +[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" +If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated +Additional options to pass to the J2ObjC tool. + +[`--java_debug`](#flag--java_debug) +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. + +Expands to: +  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) +  [`--test_output=streamed`](#flag--test_output) +  [`--test_strategy=exclusive`](#flag--test_strategy) +  [`--test_timeout=9999`](#flag--test_timeout) +  [`--nocache_test_results`](#flag--nocache_test_results) + +[`--[no]java_deps`](#flag--java_deps) default: "true" +Generate dependency information (for now, compile-time classpath) per Java target. + +[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" +Compile ijars directly from source. + +[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" +The Java language version + +[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" +The Java runtime version + +[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac. + +[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. + +[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description +Specifies a binary to use to do dexing without sharding. + +[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated +Plugins to use in the build. Currently works with java_plugin. + +[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description +Specifies which version of ProGuard to use for code removal when building a Java binary. + +[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]proto_profile`](#flag--proto_profile) default: "true" +Whether to pass profile_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description +The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" +Label of proto_lang_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" +Label of proto_lang_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" +Label of proto_lang_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" +Label of proto_lang_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +[`--test_filter`](#flag--test_filter)`=<a string>` default: see description +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" +This option is deprecated and has no effect. + +[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. + +[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" +The Java language version used to execute the tools that are needed during a build + +[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" +The Java runtime version used to execute tools during the build + +[`--[no]use_ijars`](#flag--use_ijars) default: "true" +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## <span id="build">Build Options</span> + +[`--[no]allow_one_action_on_resource_unavailable`](#build-flag--allow_one_action_on_resource_unavailable) default: "true" +If set, allow at least one action to run even if the resource is not enough or unavailable. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]check_up_to_date`](#build-flag--check_up_to_date) default: "false" +Don't perform the build, just check if it is up-to-date. If all targets are up-to-date, the build completes successfully. If any step needs to be executed an error is reported and the build fails. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--dynamic_local_execution_delay`](#build-flag--dynamic_local_execution_delay)`=<an integer>` default: "1000" +How many milliseconds should local execution be delayed, if remote execution was faster during a build at least once? + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--dynamic_local_strategy`](#build-flag--dynamic_local_strategy)`=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated +The local strategies, in order, to use for the given mnemonic - the first applicable strategy is used. For example, `worker,sandboxed` runs actions that support persistent workers using the worker strategy, and all others using the sandboxed strategy. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `worker,sandboxed`, or`worker,sandboxed,standalone` if `experimental_local_lockfree_output` is set. Takes \[mnemonic=\]local_strategy\[,local_strategy,...\] + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--dynamic_remote_strategy`](#build-flag--dynamic_remote_strategy)`=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated +The remote strategies, in order, to use for the given mnemonic - the first applicable strategy is used. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `remote`, so this flag usually does not need to be set explicitly. Takes \[mnemonic=\]remote_strategy\[,remote_strategy,...\] + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]experimental_async_execution`](#build-flag--experimental_async_execution) default: "false" +If set to true, Bazel is allowed to run action in a virtual thread. The number of actions in flight is still capped with --jobs. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--experimental_async_execution_max_concurrent_actions`](#build-flag--experimental_async_execution_max_concurrent_actions)`=<an integer>` default: "5000" +The number of maximum concurrent actions to run with async execution. If the value is less than --jobs, it is clamped to --jobs. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_docker_image`](#build-flag--experimental_docker_image)`=<a string>` default: "" +Specify a Docker image name (e.g. "ubuntu:latest") that should be used to execute a sandboxed action when using the docker strategy and the action itself doesn't already have a container-image attribute in its remote_execution_properties in the platform description. The value of this flag is passed verbatim to 'docker run', so it supports the same syntax and mechanisms as Docker itself. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_docker_use_customized_images`](#build-flag--experimental_docker_use_customized_images) default: "true" +If enabled, injects the uid and gid of the current user into the Docker image before using it. This is required if your build / tests depend on the user having a name and home directory inside the container. This is on by default, but you can disable it in case the automatic image customization feature doesn't work in your case or you know that you don't need it. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_dynamic_exclude_tools`](#build-flag--experimental_dynamic_exclude_tools) default: "true" +When set, targets that are build "for tool" are not subject to dynamic execution. Such targets are extremely unlikely to be built incrementally and thus not worth spending local cycles on. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--experimental_dynamic_local_load_factor`](#build-flag--experimental_dynamic_local_load_factor)`=<a double>` default: "0" +Controls how much load from dynamic execution to put on the local machine. This flag adjusts how many actions in dynamic execution we will schedule concurrently. It is based on the number of CPUs Blaze thinks is available, which can be controlled with the --local_resources=cpu= flag. +If this flag is 0, all actions are scheduled locally immediately. If \> 0, the amount of actions scheduled locally is limited by the number of CPUs available. If \< 1, the load factor is used to reduce the number of locally scheduled actions when the number of actions waiting to schedule is high. This lessens the load on the local machine in the clean build case, where the local machine does not contribute much. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--experimental_dynamic_slow_remote_time`](#build-flag--experimental_dynamic_slow_remote_time)`=<An immutable length of time.>` default: "0" +If \>0, the time a dynamically run action must run remote-only before we prioritize its local execution to avoid remote timeouts. This may hide some problems on the remote execution system. Do not turn this on without monitoring of remote execution issues. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]experimental_enable_docker_sandbox`](#build-flag--experimental_enable_docker_sandbox) default: "false" +Enable Docker-based sandboxing. This option has no effect if Docker is not installed. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_inmemory_sandbox_stashes`](#build-flag--experimental_inmemory_sandbox_stashes) default: "false" +If set to true, the contents of stashed sandboxes for reuse_sandbox_directories will be tracked in memory. This reduces the amount of I/O needed during reuse. Depending on the build this flag may improve wall time. Depending on the build as well this flag may use a significant amount of additional memory. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_sandbox_async_tree_delete_idle_threads`](#build-flag--experimental_sandbox_async_tree_delete_idle_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "4" +If 0, sandboxes are deleted as soon as actions finish, blocking action completion. If greater than 0, sandboxes are deleted asynchronously in the background without blocking action completion. Asynchronous deletion uses a single thread while a command is running, but ramps up to as many threads as the value of this flag once the server becomes idle. Set to `auto` to use as many threads as the number of CPUs. A server shutdown blocks on any pending asynchronous deletions. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_sandbox_enforce_resources_regexp`](#build-flag--experimental_sandbox_enforce_resources_regexp)`=<a valid Java regular expression>` default: "" +If true, actions whose mnemonic matches the input regex will have their resources request enforced as limits, overriding the value of --experimental_sandbox_limits, if the resource type supports it. For example a test that declares cpu:3 and resources:memory:10, will run with at most 3 cpus and 10 megabytes of memory. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_sandbox_limits`](#build-flag--experimental_sandbox_limits)`=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated +If \> 0, each Linux sandbox will be limited to the given amount for the specified resource. Requires --incompatible_use_new_cgroup_implementation and overrides --experimental_sandbox_memory_limit_mb. Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_sandbox_memory_limit_mb`](#build-flag--experimental_sandbox_memory_limit_mb)`=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" +If \> 0, each Linux sandbox will be limited to the given amount of memory (in MB). Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_shrink_worker_pool`](#build-flag--experimental_shrink_worker_pool) default: "false" +If enabled, could shrink worker pool if worker memory pressure is high. This flag works only when flag experimental_total_worker_memory_limit_mb is enabled. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--experimental_total_worker_memory_limit_mb`](#build-flag--experimental_total_worker_memory_limit_mb)`=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" +If this limit is greater than zero idle workers might be killed if the total memory usage of all workers exceed the limit. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]experimental_use_hermetic_linux_sandbox`](#build-flag--experimental_use_hermetic_linux_sandbox) default: "false" +If set to true, do not mount root, only mount whats provided with sandbox_add_mount_pair. Input files will be hardlinked to the sandbox instead of symlinked to from the sandbox. If action input files are located on a filesystem different from the sandbox, then the input files will be copied instead. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_use_windows_sandbox`](#build-flag--experimental_use_windows_sandbox) default: "false" +Use Windows sandbox to run actions. If "yes", the binary provided by --experimental_windows_sandbox_path must be valid and correspond to a supported version of sandboxfs. If "auto", the binary may be missing or not compatible. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_windows_sandbox_path`](#build-flag--experimental_windows_sandbox_path)`=<a string>` default: "BazelSandbox.exe" +Path to the Windows sandbox binary to use when --experimental_use_windows_sandbox is true. If a bare name, use the first binary of that name found in the PATH. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_worker_allowlist`](#build-flag--experimental_worker_allowlist)`=<comma-separated set of options>` default: see description +If non-empty, only allow using persistent workers with the given worker key mnemonic. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]experimental_worker_cancellation`](#build-flag--experimental_worker_cancellation) default: "false" +If enabled, Bazel may send cancellation requests to workers that support them. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_worker_memory_limit_mb`](#build-flag--experimental_worker_memory_limit_mb)`=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" +If this limit is greater than zero, workers might be killed if the memory usage of the worker exceeds the limit. If not used together with dynamic execution and `--experimental_dynamic_ignore_local_signals=9`, this may crash your build. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--experimental_worker_metrics_poll_interval`](#build-flag--experimental_worker_metrics_poll_interval)`=<An immutable length of time.>` default: "5s" +The interval between collecting worker metrics and possibly attempting evictions. Cannot effectively be less than 1s for performance reasons. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]experimental_worker_multiplex_sandboxing`](#build-flag--experimental_worker_multiplex_sandboxing) default: "false" +If enabled, multiplex workers with a 'supports-multiplex-sandboxing' execution requirement will run in a sandboxed environment, using a separate sandbox directory per work request. Multiplex workers with the execution requirement are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_worker_sandbox_hardening`](#build-flag--experimental_worker_sandbox_hardening) default: "false" +If enabled, workers are run in a hardened sandbox, if the implementation allows it. If hardening is enabled then tmp directories are distinct for different workers. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_worker_sandbox_inmemory_tracking`](#build-flag--experimental_worker_sandbox_inmemory_tracking)`=<a string>` multiple uses are accumulated +A worker key mnemonic for which the contents of the sandbox directory are tracked in memory. This may improve build performance at the cost of additional memory usage. Only affects sandboxed workers. May be specified multiple times for different mnemonics. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_worker_strict_flagfiles`](#build-flag--experimental_worker_strict_flagfiles) default: "false" +If enabled, actions arguments for workers that do not follow the worker specification will cause an error. Worker arguments must have exactly one @flagfile argument as the last of its list of arguments. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--genrule_strategy`](#build-flag--genrule_strategy)`=<comma-separated list of options>` default: "" +Specify how to execute genrules. This flag will be phased out. Instead, use --spawn_strategy=\<value\> to control all actions or --strategy=Genrule=\<value\> to control genrules only. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]incompatible_use_new_cgroup_implementation`](#build-flag--incompatible_use_new_cgroup_implementation) default: "true" +If true, use the new implementation for cgroups. The old implementation only supports the memory controller and ignores the value of --experimental_sandbox_limits. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]internal_spawn_scheduler`](#build-flag--internal_spawn_scheduler) default: "true" +Placeholder option so that we can tell in Blaze whether the spawn scheduler was enabled. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--jobs`](#build-flag--jobs)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` \[`-j`\] default: "auto" +The number of concurrent jobs to run. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". Values must be between 1 and 5000. Values above 2500 may cause memory issues. "auto" calculates a reasonable default based on host resources. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--[no]keep_going`](#build-flag--keep_going) \[`-k`\] default: "false" +Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--loading_phase_threads`](#build-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--[no]reuse_sandbox_directories`](#build-flag--reuse_sandbox_directories) default: "true" +If set to true, directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--sandbox_base`](#build-flag--sandbox_base)`=<a string>` default: "" +Lets the sandbox create its sandbox directories underneath this path. Specify a path on tmpfs (like /run/shm) to possibly improve performance a lot when your build / tests have many input files. Note: You need enough RAM and free space on the tmpfs to hold output and intermediate files generated by running actions. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--[no]sandbox_enable_loopback_device`](#build-flag--sandbox_enable_loopback_device) default: "true" +If true, a loopback device will be set up in the linux-sandbox network namespace for local actions. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]sandbox_explicit_pseudoterminal`](#build-flag--sandbox_explicit_pseudoterminal) default: "false" +Explicitly enable the creation of pseudoterminals for sandboxed actions. Some linux distributions require setting the group id of the process to 'tty' inside the sandbox in order for pseudoterminals to function. If this is causing issues, this flag can be disabled to enable other groups to be used. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--sandbox_tmpfs_path`](#build-flag--sandbox_tmpfs_path)`=<an absolute path>` multiple uses are accumulated +For sandboxed actions, mount an empty, writable directory at this absolute path (if supported by the sandboxing implementation, ignored otherwise). + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--[no]skip_incompatible_explicit_targets`](#build-flag--skip_incompatible_explicit_targets) default: "false" +Skip incompatible targets that are explicitly listed on the command line. By default, building such targets results in an error but they are silently skipped when this option is enabled. See: https://bazel.build/extending/platforms#skipping-incompatible-targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--spawn_strategy`](#build-flag--spawn_strategy)`=<comma-separated list of options>` default: "" +Specify how spawn actions are executed by default. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". See https://blog.bazel.build/2019/06/19/list-strategy.html for details. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--strategy`](#build-flag--strategy)`=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated +Specify how to distribute compilation of other spawn actions. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". This flag overrides the values set by --spawn_strategy (and --genrule_strategy if used with mnemonic Genrule). See https://blog.bazel.build/2019/06/19/list-strategy.html for details. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--strategy_regexp`](#build-flag--strategy_regexp)`=<a '<RegexFilter>=value[,value]' assignment>` multiple uses are accumulated +Override which spawn strategy should be used to execute spawn actions that have descriptions matching a certain regex_filter. See --per_file_copt for details onregex_filter matching. The last regex_filter that matches the description is used. This option overrides other flags for specifying strategy. Example: --strategy_regexp=//foo.*.cc,-//foo/bar=local means to run actions using local strategy if their descriptions match //foo.*.cc but not //foo/bar. Example: --strategy_regexp='Compiling.\*/bar=local --strategy_regexp=Compiling=sandboxed will run 'Compiling //foo/bar/baz' with the 'local' strategy, but reversing the order would run it with 'sandboxed'. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--worker_extra_flag`](#build-flag--worker_extra_flag)`=<a 'name=value' assignment>` multiple uses are accumulated +Extra command-flags that will be passed to worker processes in addition to --persistent_worker, keyed by mnemonic (e.g. --worker_extra_flag=Javac=--debug. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--worker_max_instances`](#build-flag--worker_max_instances)`=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated +How many instances of each kind of persistent worker may be launched if you use the 'worker' strategy. May be specified as \[name=value\] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--worker_max_multiplex_instances`](#build-flag--worker_max_multiplex_instances)`=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated +How many WorkRequests a multiplex worker process may receive in parallel if you use the 'worker' strategy with --worker_multiplex. May be specified as \[name=value\] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]worker_multiplex`](#build-flag--worker_multiplex) default: "true" +If enabled, workers will use multiplexing if they support it. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]worker_quit_after_build`](#build-flag--worker_quit_after_build) default: "false" +If enabled, all workers quit after a build is done. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]worker_sandboxing`](#build-flag--worker_sandboxing) default: "false" +If enabled, singleplex workers will run in a sandboxed environment. Singleplex workers are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]worker_verbose`](#build-flag--worker_verbose) default: "false" +If enabled, prints verbose messages when workers are started, shutdown, ... + +<!-- --> + +[`--[no]build`](#build-flag--build) default: "true" +Execute the build; this is the usual behaviour. Specifying --nobuild causes the build to stop before executing the build actions, returning zero iff the package loading and analysis phases completed successfully; this mode is useful for testing those phases. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_use_validation_aspect`](#build-flag--experimental_use_validation_aspect) default: "false" +Whether to run validation actions using aspect (for parallelism with tests). + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--output_groups`](#build-flag--output_groups)`=<comma-separated list of options>` multiple uses are accumulated +A list of comma-separated output group names, each of which optionally prefixed by a + or a -. A group prefixed by + is added to the default set of output groups, while a group prefixed by - is removed from the default set. If at least one group is not prefixed, the default set of output groups is omitted. For example, --output_groups=+foo,+bar builds the union of the default set, foo, and bar, while --output_groups=foo,bar overrides the default set such that only foo and bar are built. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]run_validations`](#build-flag--run_validations) default: "true" +Whether to run validation actions as part of the build. See https://bazel.build/extending/rules#validation_actions + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--serialized_frontier_profile`](#build-flag--serialized_frontier_profile)`=<a string>` default: "" +Dump a profile of serialized frontier bytes. Specifies the output path. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +<!-- --> + +[`--aspects`](#build-flag--aspects)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of aspects to be applied to top-level targets. In the list, if aspect some_aspect specifies required aspect providers via required_aspect_providers, some_aspect will run after every aspect that was mentioned before it in the aspects list whose advertised providers satisfy some_aspect required aspect providers. Moreover, some_aspect will run after all its required aspects specified by requires attribute. some_aspect will then have access to the values of those aspects' providers. \<bzl-file-label\>%\<aspect_name\>, for example '//tools:my_def.bzl%my_aspect', where 'my_aspect' is a top-level value from a file tools/my_def.bzl + +[`--bep_maximum_open_remote_upload_files`](#build-flag--bep_maximum_open_remote_upload_files)`=<an integer>` default: "-1" +Maximum number of open files allowed during BEP artifact upload. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_convenience_symlinks`](#build-flag--experimental_convenience_symlinks) default: "normal" +This flag controls how the convenience symlinks (the symlinks that appear in the workspace after the build) will be managed. Possible values: +normal (default): Each kind of convenience symlink will be created or deleted, as determined by the build. +clean: All symlinks will be unconditionally deleted. +ignore: Symlinks will not be created or cleaned up. +log_only: Generate log messages as if 'normal' were passed, but don't actually perform any filesystem operations (useful for tools). +Note that only symlinks whose names are generated by the current value of --symlink_prefix can be affected; if the prefix changes, any pre-existing symlinks will be left alone. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_convenience_symlinks_bep_event`](#build-flag--experimental_convenience_symlinks_bep_event) default: "true" +This flag controls whether or not we will post the build eventConvenienceSymlinksIdentified to the BuildEventProtocol. If the value is true, the BuildEventProtocol will have an entry for convenienceSymlinksIdentified, listing all of the convenience symlinks created in your workspace. If false, then the convenienceSymlinksIdentified entry in the BuildEventProtocol will be empty. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_all`](#build-flag--remote_download_all) +Downloads all remote outputs to the local machine. This flag is an alias for --remote_download_outputs=all. + +Expands to: +  [`--remote_download_outputs=all`](#flag--remote_download_outputs) + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_minimal`](#build-flag--remote_download_minimal) +Does not download any remote build outputs to the local machine. This flag is an alias for --remote_download_outputs=minimal. + +Expands to: +  [`--remote_download_outputs=minimal`](#flag--remote_download_outputs) + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_outputs`](#build-flag--remote_download_outputs)`=<all, minimal or toplevel>` default: "toplevel" +If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_symlink_template`](#build-flag--remote_download_symlink_template)`=<a string>` default: "" +Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_download_toplevel`](#build-flag--remote_download_toplevel) +Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote_download_outputs=toplevel. + +Expands to: +  [`--remote_download_outputs=toplevel`](#flag--remote_download_outputs) + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--symlink_prefix`](#build-flag--symlink_prefix)`=<a string>` default: see description +The prefix that is prepended to any of the convenience symlinks that are created after a build. If omitted, the default value is the name of the build tool followed by a hyphen. If '/' is passed, then no symlinks are created and no warning is emitted. Warning: the special functionality for '/' will be deprecated soon; use --experimental_convenience_symlinks=ignore instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--[no]experimental_docker_privileged`](#build-flag--experimental_docker_privileged) default: "false" +If enabled, Bazel will pass the --privileged flag to 'docker run' when running actions. This might be required by your build, but it might also result in reduced hermeticity. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_sandboxfs_map_symlink_targets`](#build-flag--experimental_sandboxfs_map_symlink_targets) default: "false" +No-op + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--sandbox_add_mount_pair`](#build-flag--sandbox_add_mount_pair)`=<a single path or a 'source:target' pair>` multiple uses are accumulated +Add additional path pair to mount in sandbox. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--sandbox_block_path`](#build-flag--sandbox_block_path)`=<a string>` multiple uses are accumulated +For sandboxed actions, disallow access to this path. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]sandbox_default_allow_network`](#build-flag--sandbox_default_allow_network) default: "true" +Allow network access by default for actions; this may not work with all sandboxing implementations. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]sandbox_fake_hostname`](#build-flag--sandbox_fake_hostname) default: "false" +Change the current hostname to 'localhost' for sandboxed actions. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]sandbox_fake_username`](#build-flag--sandbox_fake_username) default: "false" +Change the current username to 'nobody' for sandboxed actions. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--sandbox_writable_path`](#build-flag--sandbox_writable_path)`=<a string>` multiple uses are accumulated +For sandboxed actions, make an existing directory writable in the sandbox (if supported by the sandboxing implementation, ignored otherwise). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--[no]incompatible_config_setting_private_default_visibility`](#build-flag--incompatible_config_setting_private_default_visibility) default: "false" +If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enforce_config_setting_visibility`](#build-flag--incompatible_enforce_config_setting_visibility) default: "true" +If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]check_tests_up_to_date`](#build-flag--check_tests_up_to_date) default: "false" +Don't run tests, just check if they are up-to-date. If all tests results are up-to-date, the testing completes successfully. If any test needs to be built or executed, an error is reported and the testing fails. This option implies --check_up_to_date behavior. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--flaky_test_attempts`](#build-flag--flaky_test_attempts)`=<a positive integer, the string "default", or test_regex@attempts. This flag may be passed more than once>` multiple uses are accumulated +Each test will be retried up to the specified number of times in case of any test failure. Tests that required more than one attempt to pass are marked as 'FLAKY' in the test summary. Normally the value specified is just an integer or the string 'default'. If an integer, then all tests will be run up to N times. If 'default', then only a single test attempt will be made for regular tests and three for tests marked explicitly as flaky by their rule (flaky=1 attribute). Alternate syntax: regex_filter@flaky_test_attempts. Where flaky_test_attempts is as above and regex_filter stands for a list of include and exclude regular expression patterns (Also see --runs_per_test). Example: --flaky_test_attempts=//foo/.*,-//foo/bar/.*@3 deflakes all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, behavior is as if 'default' above. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--local_test_jobs`](#build-flag--local_test_jobs)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +The max number of local test jobs to run concurrently. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". 0 means local resources will limit the number of local test jobs to run concurrently instead. Setting this greater than the value for --jobs is ineffectual. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]test_keep_going`](#build-flag--test_keep_going) default: "true" +When disabled, any non-passing test will cause the entire build to stop. By default all tests are run, even if some do not pass. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--test_strategy`](#build-flag--test_strategy)`=<a string>` default: "" +Specifies which strategy to use when running tests. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--test_tmpdir`](#build-flag--test_tmpdir)`=<a path>` default: see description +Specifies the base temporary directory for 'bazel test' to use. + +<!-- --> + +[`--cache_computed_file_digests`](#build-flag--cache_computed_file_digests)`=<a long integer>` default: "50000" +If greater than 0, configures Bazel to cache file digests in memory based on their metadata instead of recomputing the digests from disk every time they are needed. Setting this to 0 ensures correctness because not all file changes can be noted from file metadata. When not 0, the number indicates the size of the cache as the number of file digests to be cached. + +[`--experimental_active_directories`](#build-flag--experimental_active_directories)`=<comma-separated list of options>` default: "" +Active directories for Skyfocus and remote analysis caching. Specify as comma-separated workspace root-relative paths. This is a stateful flag. Defining one persists it for subsequent invocations, until it is redefined with a new set. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]experimental_cpu_load_scheduling`](#build-flag--experimental_cpu_load_scheduling) default: "false" +Enables the experimental local execution scheduling based on CPU load, not estimation of actions one by one. Experimental scheduling have showed the large benefit on a large local builds on a powerful machines with the large number of cores. Reccommended to use with --local_resources=cpu=HOST_CPUS + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_dynamic_ignore_local_signals`](#build-flag--experimental_dynamic_ignore_local_signals)`=<a comma-separated list of signal numbers>` default: see description +Takes a list of OS signal numbers. If a local branch of dynamic execution gets killed with any of these signals, the remote branch will be allowed to finish instead. For persistent workers, this only affects signals that kill the worker process. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_enable_skyfocus`](#build-flag--experimental_enable_skyfocus) default: "false" +If true, enable the use of --experimental_active_directories to reduce Bazel's memory footprint for incremental builds. This feature is known as Skyfocus. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--local_cpu_resources`](#build-flag--local_cpu_resources)`=<an integer, or "HOST_CPUS", optionally followed by [-|*]<float>.>` default: "HOST_CPUS" +Explicitly set the total number of local CPU cores available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST_CPUS", optionally followed by \[-\|*\]\<float\> (eg. HOST_CPUS*.5 to use half the available CPU cores). By default, ("HOST_CPUS"), Bazel will query system configuration to estimate the number of CPU cores available. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--local_extra_resources`](#build-flag--local_extra_resources)`=<a named float, 'name=value'>` multiple uses are accumulated +Set the number of extra resources available to Bazel. Takes in a string-float pair. Can be used multiple times to specify multiple types of extra resources. Bazel will limit concurrently running actions based on the available extra resources and the extra resources required. Tests can declare the amount of extra resources they need by using a tag of the "resources:\<resoucename\>:\<amount\>" format. Available CPU, RAM and resources cannot be set with this flag. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--local_ram_resources`](#build-flag--local_ram_resources)`=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "HOST_RAM\*.67" +Explicitly set the total amount of local host RAM (in MB) available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST_RAM", optionally followed by \[-\|*\]\<float\> (eg. HOST_RAM*.5 to use half the available RAM). By default, ("HOST_RAM\*.67"), Bazel will query system configuration to estimate the amount of RAM available and will use 67% of it. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--local_resources`](#build-flag--local_resources)`=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated +Set the number of resources available to Bazel. Takes in an assignment to a float or HOST_RAM/HOST_CPUS, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.5 to use half the available RAM). Can be used multiple times to specify multiple types of resources. Bazel will limit concurrently running actions based on the available resources and the resources required. Tests can declare the amount of resources they need by using a tag of the "resources:\<resource name\>:\<amount\>" format. Overrides resources specified by --local\_{cpu\|ram\|extra}\_resources. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +<!-- --> + +[`--build_event_upload_max_retries`](#build-flag--build_event_upload_max_retries)`=<an integer>` default: "4" +The maximum number of times Bazel should retry uploading a build event. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--[no]debug_spawn_scheduler`](#build-flag--debug_spawn_scheduler) default: "false" + +[`--[no]experimental_bep_target_summary`](#build-flag--experimental_bep_target_summary) default: "false" +Whether to publish TargetSummary events. + +[`--[no]experimental_build_event_expand_filesets`](#build-flag--experimental_build_event_expand_filesets) default: "false" +If true, expand Filesets in the BEP when presenting output files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--experimental_build_event_output_group_mode`](#build-flag--experimental_build_event_output_group_mode)`=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated +Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED_SET_OF_FILES_ONLY', 'INLINE_ONLY', or 'BOTH'. The default value is 'NAMED_SET_OF_FILES_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental_build_event_output_group_mode=baseline.lcov=both + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--experimental_build_event_upload_retry_minimum_delay`](#build-flag--experimental_build_event_upload_retry_minimum_delay)`=<An immutable length of time.>` default: "1s" +Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--experimental_build_event_upload_strategy`](#build-flag--experimental_build_event_upload_strategy)`=<a string>` default: see description +Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_docker_verbose`](#build-flag--experimental_docker_verbose) default: "false" +If enabled, Bazel will print more verbose messages about the Docker sandbox strategy. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_frontier_violation_check`](#build-flag--experimental_frontier_violation_check)`=<strict, warn or disabled_for_testing>` default: "strict" +Strategies to handle potential incorrectness from changes beyond the frontier (i.e. outside the active directories) + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]experimental_frontier_violation_verbose`](#build-flag--experimental_frontier_violation_verbose) default: "false" +If true, Bazel will print instructions for fixing Skycache violations + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]experimental_materialize_param_files_directly`](#build-flag--experimental_materialize_param_files_directly) default: "false" +If materializing param files, do so with direct writes to disk. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_run_bep_event_include_residue`](#build-flag--experimental_run_bep_event_include_residue) default: "false" +Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--experimental_skyfocus_dump_keys`](#build-flag--experimental_skyfocus_dump_keys)`=<none, count or verbose>` default: "none" +For debugging Skyfocus. Dump the focused SkyKeys (roots, leafs, focused deps, focused rdeps). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]experimental_skyfocus_dump_post_gc_stats`](#build-flag--experimental_skyfocus_dump_post_gc_stats) default: "false" +For debugging Skyfocus. If enabled, trigger manual GC before/after focusing to report heap sizes reductions. This will increase the Skyfocus latency. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]experimental_stream_log_file_uploads`](#build-flag--experimental_stream_log_file_uploads) default: "false" +Stream log file uploads directly to the remote storage rather than writing them to disk. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--explain`](#build-flag--explain)`=<a path>` default: see description +Causes the build system to explain each executed step of the build. The explanation is written to the specified log file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]ignore_unsupported_sandboxing`](#build-flag--ignore_unsupported_sandboxing) default: "false" +Do not print a warning when sandboxed execution is not supported on this system. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]legacy_important_outputs`](#build-flag--legacy_important_outputs) default: "false" +Use this to suppress generation of the legacy important_outputs field in the TargetComplete event. important_outputs are required for Bazel to ResultStore/BTX integration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]materialize_param_files`](#build-flag--materialize_param_files) default: "false" +Writes intermediate parameter files to output tree even when using remote action execution or caching. Useful when debugging actions. This is implied by --subcommands and --verbose_failures. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--max_config_changes_to_show`](#build-flag--max_config_changes_to_show)`=<an integer>` default: "3" +When discarding the analysis cache due to a change in the build options, displays up to the given number of changed option names. If the number given is -1, all changed options will be displayed. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--max_test_output_bytes`](#build-flag--max_test_output_bytes)`=<an integer>` default: "-1" +Specifies maximum per-test-log size that can be emitted when --test_output is 'errors' or 'all'. Useful for avoiding overwhelming the output with excessively noisy test output. The test header is included in the log size. Negative values imply no limit. Output is all or nothing. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) + +[`--output_filter`](#build-flag--output_filter)`=<a valid Java regular expression>` default: see description +Only shows warnings and action outputs for rules with a name matching the provided regular expression. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--progress_report_interval`](#build-flag--progress_report_interval)`=<an integer in 0-3600 range>` default: "0" +The number of seconds to wait between reports on still running jobs. The default value 0 means the first report will be printed after 10 seconds, then 30 seconds and after that progress is reported once every minute. When --curses is enabled, progress is reported every second. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_analysis_json_log`](#build-flag--remote_analysis_json_log)`=<a string>` default: see description +If set, a JSON file is written to this location that contains a detailed log of the behavior of remote analysis caching. It's interpreted as a path relative to the current working directory. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--remote_print_execution_messages`](#build-flag--remote_print_execution_messages)`=<failure, success or all>` default: "failure" +Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]sandbox_debug`](#build-flag--sandbox_debug) default: "false" +Enables debugging features for the sandboxing feature. This includes two things: first, the sandbox root contents are left untouched after a build; and second, prints extra debugging information on execution. This can help developers of Bazel or Starlark rules with debugging failures due to missing input files, etc. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--show_result`](#build-flag--show_result)`=<an integer>` default: "1" +Show the results of the build. For each target, state whether or not it was brought up-to-date, and if so, a list of output files that were built. The printed files are convenient strings for copy+pasting to the shell, to execute them. +This option requires an integer argument, which is the threshold number of targets above which result information is not printed. Thus zero causes suppression of the message and MAX_INT causes printing of the result to occur always. The default is one. +If nothing was built for a target its results may be omitted to keep the output under the threshold. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]subcommands`](#build-flag--subcommands) \[`-s`\] default: "false" +Display the subcommands executed during a build. Related flags: --execution_log_json_file, --execution_log_binary_file (for logging subcommands to a file in a tool-friendly format). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--test_output`](#build-flag--test_output)`=<summary, errors, all or streamed>` default: "summary" +Specifies desired output mode. Valid values are 'summary' to output only test status summary, 'errors' to also print test logs for failed tests, 'all' to print logs for all tests and 'streamed' to output logs for all tests in real time (this will force tests to be executed locally one at a time regardless of --test_strategy value). + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) + +[`--test_summary`](#build-flag--test_summary)`=<short, terse, detailed, none or testcase>` default: "short" +Specifies the desired format of the test summary. Valid values are 'short' to print information only about tests executed, 'terse', to print information only about unsuccessful tests that were run, 'detailed' to print detailed information about failed test cases, 'testcase' to print summary in test case resolution, do not print detailed information about failed test cases and 'none' to omit the summary. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]verbose_failures`](#build-flag--verbose_failures) default: "false" +If a command fails, print out the full command line. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +<!-- --> + +[`--aspects_parameters`](#build-flag--aspects_parameters)`=<a 'name=value' assignment>` multiple uses are accumulated +Specifies the values of the command-line aspects parameters. Each parameter value is specified via \<param_name\>=\<param_value\>, for example 'my_param=my_val' where 'my_param' is a parameter of some aspect in --aspects list or required by an aspect in the list. This option can be used multiple times. However, it is not allowed to assign values to the same parameter more than once. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--target_pattern_file`](#build-flag--target_pattern_file)`=<a string>` default: "" +If set, build will read patterns from the file named here, rather than on the command line. It is an error to specify a file here as well as command-line patterns. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--experimental_circuit_breaker_strategy`](#build-flag--experimental_circuit_breaker_strategy)`=<failure>` default: see description +Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_remote_cache_compression_threshold`](#build-flag--experimental_remote_cache_compression_threshold)`=<an integer>` default: "100" +The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote_cache_compression is set. + +[`--experimental_remote_cache_eviction_retries`](#build-flag--experimental_remote_cache_eviction_retries)`=<an integer>` default: "5" +The maximum number of attempts to retry if the build encountered a transient remote cache error that would otherwise fail the build. Applies for example when artifacts are evicted from the remote cache, or in certain cache failure conditions. A new invocation id will be generated for each attempt. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_remote_cache_lease_extension`](#build-flag--experimental_remote_cache_lease_extension) default: "false" +If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. + +[`--experimental_remote_cache_ttl`](#build-flag--experimental_remote_cache_ttl)`=<An immutable length of time.>` default: "3h" +The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_remote_capture_corrupted_outputs`](#build-flag--experimental_remote_capture_corrupted_outputs)`=<a path>` default: see description +A path to a directory where the corrupted outputs will be captured to. + +[`--[no]experimental_remote_discard_merkle_trees`](#build-flag--experimental_remote_discard_merkle_trees) default: "true" +If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. + +[`--experimental_remote_downloader`](#build-flag--experimental_remote_downloader)`=<a string>` default: see description +A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote_asset.proto + +[`--[no]experimental_remote_downloader_local_fallback`](#build-flag--experimental_remote_downloader_local_fallback) default: "false" +Whether to fall back to the local downloader if remote downloader fails. + +[`--[no]experimental_remote_downloader_propagate_credentials`](#build-flag--experimental_remote_downloader_propagate_credentials) default: "false" +Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. + +[`--[no]experimental_remote_execution_keepalive`](#build-flag--experimental_remote_execution_keepalive) default: "false" +Whether to use keepalive for remote execution calls. + +[`--experimental_remote_failure_rate_threshold`](#build-flag--experimental_remote_failure_rate_threshold)`=<an integer in 0-100 range>` default: "10" +Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--experimental_remote_failure_window_interval`](#build-flag--experimental_remote_failure_window_interval)`=<An immutable length of time.>` default: "60s" +The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]experimental_remote_mark_tool_inputs`](#build-flag--experimental_remote_mark_tool_inputs) default: "false" +If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. + +[`--[no]experimental_remote_merkle_tree_cache`](#build-flag--experimental_remote_merkle_tree_cache) default: "false" +If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental_remote_merkle_tree_cache_size. + +[`--experimental_remote_merkle_tree_cache_size`](#build-flag--experimental_remote_merkle_tree_cache_size)`=<a long integer>` default: "1000" +The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. + +[`--experimental_remote_output_service`](#build-flag--experimental_remote_output_service)`=<a string>` default: see description +HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. + +[`--experimental_remote_output_service_output_path_prefix`](#build-flag--experimental_remote_output_service_output_path_prefix)`=<a string>` default: "" +The path under which the contents of output directories managed by the --experimental_remote_output_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. + +[`--[no]experimental_remote_require_cached`](#build-flag--experimental_remote_require_cached) default: "false" +If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. + +[`--experimental_remote_scrubbing_config`](#build-flag--experimental_remote_scrubbing_config)`=<Converts to a Scrubber>` default: see description +Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote_scrubbing.proto). + +This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. + +Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. + +Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. + +In order to successfully use this feature, you likely want to set a custom --host_platform together with --experimental_platform_in_output_dir (to normalize output prefixes) and --incompatible_strict_action_env (to normalize environment variables). + +[`--[no]guard_against_concurrent_changes`](#build-flag--guard_against_concurrent_changes) default: "lite" +Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]remote_accept_cached`](#build-flag--remote_accept_cached) default: "true" +Whether to accept remotely cached action results. + +[`--remote_build_event_upload`](#build-flag--remote_build_event_upload)`=<all or minimal>` default: "minimal" +If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. +If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. +Default to 'minimal'. + +[`--remote_bytestream_uri_prefix`](#build-flag--remote_bytestream_uri_prefix)`=<a string>` default: see description +The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote_executor and --remote_instance_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "\${hostname}/\${instance_name}". + +[`--remote_cache`](#build-flag--remote_cache)`=<a string>` default: see description +A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching + +[`--[no]remote_cache_async`](#build-flag--remote_cache_async) default: "true" +If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. + +[`--[no]remote_cache_compression`](#build-flag--remote_cache_compression) default: "false" +If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental_remote_cache_compression_threshold. + +[`--remote_cache_header`](#build-flag--remote_cache_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header that will be included in cache requests: --remote_cache_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +[`--remote_default_exec_properties`](#build-flag--remote_default_exec_properties)`=<a 'name=value' assignment>` multiple uses are accumulated +Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec_properties. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_default_platform_properties`](#build-flag--remote_default_platform_properties)`=<a string>` default: "" +Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote_execution_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. + +[`--remote_download_regex`](#build-flag--remote_download_regex)`=<a valid Java regular expression>` multiple uses are accumulated +Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote_download_outputs. Multiple patterns may be specified by repeating this flag. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--remote_downloader_header`](#build-flag--remote_downloader_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header that will be included in remote downloader requests: --remote_downloader_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +[`--remote_exec_header`](#build-flag--remote_exec_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header that will be included in execution requests: --remote_exec_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +[`--remote_execution_priority`](#build-flag--remote_execution_priority)`=<an integer>` default: "0" +The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. + +[`--remote_executor`](#build-flag--remote_executor)`=<a string>` default: see description +HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. + +[`--remote_grpc_log`](#build-flag--remote_grpc_log)`=<a path>` default: see description +If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). + +[`--remote_header`](#build-flag--remote_header)`=<a 'name=value' assignment>` multiple uses are accumulated +Specify a header that will be included in requests: --remote_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +[`--remote_instance_name`](#build-flag--remote_instance_name)`=<a string>` default: "" +Value to pass as instance_name in the remote execution API. + +[`--[no]remote_local_fallback`](#build-flag--remote_local_fallback) default: "false" +Whether to fall back to standalone local execution strategy if remote execution fails. + +[`--remote_local_fallback_strategy`](#build-flag--remote_local_fallback_strategy)`=<a string>` default: "local" +Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. + +[`--remote_max_connections`](#build-flag--remote_max_connections)`=<an integer>` default: "100" +Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. +For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote_max_connections concurrent requests. +For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--remote_proxy`](#build-flag--remote_proxy)`=<a string>` default: see description +Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). + +[`--remote_result_cache_priority`](#build-flag--remote_result_cache_priority)`=<an integer>` default: "0" +The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. + +[`--remote_retries`](#build-flag--remote_retries)`=<an integer>` default: "5" +The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. + +[`--remote_retry_max_delay`](#build-flag--remote_retry_max_delay)`=<An immutable length of time.>` default: "5s" +The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +[`--remote_timeout`](#build-flag--remote_timeout)`=<An immutable length of time.>` default: "60s" +The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +[`--[no]remote_upload_local_results`](#build-flag--remote_upload_local_results) default: "true" +Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. + +[`--[no]remote_verify_downloads`](#build-flag--remote_verify_downloads) default: "true" +If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. + +<!-- --> + +[`--[no]allow_analysis_cache_discard`](#build-flag--allow_analysis_cache_discard) default: "true" +If discarding the analysis cache due to a change in the build system, setting this option to false will cause bazel to exit, rather than continuing with the build. This option has no effect when 'discard_analysis_cache' is also set. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--auto_output_filter`](#build-flag--auto_output_filter)`=<none, all, packages or subpackages>` default: "none" +If --output_filter is not specified, then the value for this option is used create a filter automatically. Allowed values are 'none' (filter nothing / show everything), 'all' (filter everything / show nothing), 'packages' (include output from rules in packages mentioned on the Blaze command line), and 'subpackages' (like 'packages', but also include subpackages). For the 'packages' and 'subpackages' values //java/foo and //javatests/foo are treated as one package)'. + +[`--[no]build_manual_tests`](#build-flag--build_manual_tests) default: "false" +Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from processing. This option forces them to be built (but not executed). + +[`--build_tag_filters`](#build-flag--build_tag_filters)`=<comma-separated list of options>` default: "" +Specifies a comma-separated list of tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those targets will be built that contain at least one included tag and do not contain any excluded tags. This option does not affect the set of tests executed with the 'test' command; those are be governed by the test filtering options, for example '--test_tag_filters' + +[`--[no]build_tests_only`](#build-flag--build_tests_only) default: "false" +If specified, only \*\_test and test_suite rules will be built and other targets specified on the command line will be ignored. By default everything that was requested will be built. + +[`--combined_report`](#build-flag--combined_report)`=<none or lcov>` default: "lcov" +Specifies desired cumulative coverage report type. At this point only LCOV is supported. + +[`--[no]compile_one_dependency`](#build-flag--compile_one_dependency) default: "false" +Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single target that depends on the source file to detect errors as early as possible in the edit/build/test cycle. This argument affects the way all non-flag arguments are interpreted; instead of being targets to build they are source filenames. For each source filename an arbitrary target that depends on it will be built. + +[`--deleted_packages`](#build-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. + +[`--[no]discard_analysis_cache`](#build-flag--discard_analysis_cache) default: "false" +Discard the analysis cache immediately after the analysis phase completes. Reduces memory usage by ~10%, but makes further incremental builds slower. + +[`--disk_cache`](#build-flag--disk_cache)`=<a path>` default: see description +A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. + +[`--embed_label`](#build-flag--embed_label)`=<a one-line string>` default: "" +Embed source control revision or release label in binary + +[`--execution_log_binary_file`](#build-flag--execution_log_binary_file)`=<a path>` default: see description +Log the executed spawns into this file as length-delimited SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution_log_compact_file, which is significantly smaller and cheaper to produce. Related flags: --execution_log_compact_file (compact format; mutually exclusive), --execution_log_json_file (text JSON format; mutually exclusive), --execution_log_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). + +[`--execution_log_compact_file`](#build-flag--execution_log_compact_file)`=<a path>` default: see description +Log the executed spawns into this file as length-delimited ExecLogEntry protos, according to src/main/protobuf/spawn.proto. The entire file is zstd compressed. Related flags: --execution_log_binary_file (binary protobuf format; mutually exclusive), --execution_log_json_file (text JSON format; mutually exclusive), --subcommands (for displaying subcommands in terminal output). + +[`--execution_log_json_file`](#build-flag--execution_log_json_file)`=<a path>` default: see description +Log the executed spawns into this file as newline-delimited JSON representations of SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution_log_compact_file, which is significantly smaller and cheaper to produce. Related flags: --execution_log_compact_file (compact format; mutually exclusive), --execution_log_binary_file (binary protobuf format; mutually exclusive), --execution_log_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). + +[`--[no]execution_log_sort`](#build-flag--execution_log_sort) default: "true" +Whether to sort the execution log, making it easier to compare logs across invocations. Set to false to avoid potentially significant CPU and memory usage at the end of the invocation, at the cost of producing the log in nondeterministic execution order. Only applies to the binary and JSON formats; the compact format is never sorted. + +[`--[no]expand_test_suites`](#build-flag--expand_test_suites) default: "true" +Expand test_suite targets into their constituent tests before analysis. When this flag is turned on (the default), negative target patterns will apply to the tests belonging to the test suite, otherwise they will not. Turning off this flag is useful when top-level aspects are applied at command line: then they can analyze test_suite targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_disk_cache_gc_idle_delay`](#build-flag--experimental_disk_cache_gc_idle_delay)`=<An immutable length of time.>` default: "5m" +How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental_disk_cache_gc_max_size and/or --experimental_disk_cache_gc_max_age. + +[`--experimental_disk_cache_gc_max_age`](#build-flag--experimental_disk_cache_gc_max_age)`=<An immutable length of time.>` default: "0" +If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental_disk_cache_gc_max_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag. + +[`--experimental_disk_cache_gc_max_size`](#build-flag--experimental_disk_cache_gc_max_size)`=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" +If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental_disk_cache_gc_max_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag. + +[`--experimental_extra_action_filter`](#build-flag--experimental_extra_action_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "" +Deprecated in favor of aspects. Filters set of targets to schedule extra_actions for. + +[`--[no]experimental_extra_action_top_level_only`](#build-flag--experimental_extra_action_top_level_only) default: "false" +Deprecated in favor of aspects. Only schedules extra_actions for top level targets. + +[`--experimental_spawn_scheduler`](#build-flag--experimental_spawn_scheduler) +Enable dynamic execution by running actions locally and remotely in parallel. Bazel spawns each action locally and remotely and picks the one that completes first. If an action supports workers, the local action will be run in the persistent worker mode. To enable dynamic execution for an individual action mnemonic, use the `--internal_spawn_scheduler` and `--strategy=<mnemonic>=dynamic` flags instead. + +Expands to: +  [`--internal_spawn_scheduler`](#flag--internal_spawn_scheduler) +  [`--spawn_strategy=dynamic`](#flag--spawn_strategy) + +[`--[no]fetch`](#build-flag--fetch) default: "true" +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +[`--local_termination_grace_seconds`](#build-flag--local_termination_grace_seconds)`=<an integer>` default: "15" +Time to wait between terminating a local process due to timeout and forcefully shutting it down. + +[`--package_path`](#build-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +[`--[no]show_loading_progress`](#build-flag--show_loading_progress) default: "true" +If enabled, causes Bazel to print "Loading package:" messages. + +[`--test_lang_filters`](#build-flag--test_lang_filters)`=<comma-separated list of options>` default: "" +Specifies a comma-separated list of test languages. Each language can be optionally preceded with '-' to specify excluded languages. Only those test targets will be found that are written in the specified languages. The name used for each language should be the same as the language prefix in the \*\_test rule, e.g. one of 'cc', 'java', 'py', etc. This option affects --build_tests_only behavior and the test command. + +[`--test_size_filters`](#build-flag--test_size_filters)`=<comma-separated list of values: small, medium, large, or enormous>` default: "" +Specifies a comma-separated list of test sizes. Each size can be optionally preceded with '-' to specify excluded sizes. Only those test targets will be found that contain at least one included size and do not contain any excluded sizes. This option affects --build_tests_only behavior and the test command. + +[`--test_tag_filters`](#build-flag--test_tag_filters)`=<comma-separated list of options>` default: "" +Specifies a comma-separated list of test tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those test targets will be found that contain at least one included tag and do not contain any excluded tags. This option affects --build_tests_only behavior and the test command. + +[`--test_timeout_filters`](#build-flag--test_timeout_filters)`=<comma-separated list of values: short, moderate, long, or eternal>` default: "" +Specifies a comma-separated list of test timeouts. Each timeout can be optionally preceded with '-' to specify excluded timeouts. Only those test targets will be found that contain at least one included timeout and do not contain any excluded timeouts. This option affects --build_tests_only behavior and the test command. + +[`--workspace_status_command`](#build-flag--workspace_status_command)`=<path>` default: "" +A command invoked at the beginning of the build to provide status information about the workspace in the form of key/value pairs. See the User's Manual for the full specification. Also see tools/buildstamp/get_workspace_status for an example. + +<!-- --> + +[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" +When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +Enable persistent Android dex and desugar actions by using workers. + +Expands to: +  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) +  [`--strategy=Desugar=worker`](#flag--strategy) +  [`--strategy=DexBuilder=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +Enable persistent Android resource processor by using workers. + +Expands to: +  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) +  [`--strategy=AaptPackage=worker`](#flag--strategy) +  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) +  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) +  [`--strategy=RClassGenerator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) +  [`--strategy=AndroidAapt2=worker`](#flag--strategy) +  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) +  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) +  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) +  [`--strategy=ManifestMerger=worker`](#flag--strategy) +  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) +  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) +  [`--strategy=AARGenerator=worker`](#flag--strategy) +  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) +  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: +  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: +  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: +  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) +  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" +Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" +Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compiler`](#flag--compiler)`=<a string>` default: see description +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--grte_top`](#flag--grte_top)`=<a label>` default: see description +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description +If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" +If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--platforms`](#flag--platforms)`=<a build target label>` default: "" +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_path`](#flag--python_path)`=<a string>` default: see description +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" +Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" +The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" +Sets the suffixes of header files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" +Sets the suffixes of source files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" +Run extra actions for alternative Java api versions in a proto_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" +If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" +If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]save_temps`](#flag--save_temps) default: "false" +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case +the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +\<br\> +Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" +Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cpu`](#flag--cpu)`=<a string>` default: "" +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description +The cs_fdo_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated +Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" +py_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description +The fdo_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--features`](#flag--features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]force_pic`](#flag--force_pic) default: "false" +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" +Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO backend step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO indexing step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" +If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description +Absolute path name of cc_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description +Absolute path name of ld_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]stamp`](#flag--stamp) default: "false" +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated +Additional options to pass to strip when generating a '\<name\>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--[no]check_visibility`](#flag--check_visibility) default: "true" +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_check_desugar_deps`](#flag--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`](#flag--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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" +When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" +When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description +An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" +Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" +Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +<!-- --> + +[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" +If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" +If true, make the default value true for alwayslink attributes in objc_library and objc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" +When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" +Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" +Use dex2oat in parallel to possibly speed up android_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" +Enable checking for memory leaks in ios_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +<!-- --> + +[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" +When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" +Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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`](#flag--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`](#flag--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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +<!-- --> + +[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" +If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +Enables reduced classpaths for Java compilations. + +[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]explicit_java_test_deps`](#flag--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. + +[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description +The Java launcher used by tools that are executed during a build. + +[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac when building tools that are executed during a build. + +[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. + +[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" +If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated +Additional options to pass to the J2ObjC tool. + +[`--java_debug`](#flag--java_debug) +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. + +Expands to: +  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) +  [`--test_output=streamed`](#flag--test_output) +  [`--test_strategy=exclusive`](#flag--test_strategy) +  [`--test_timeout=9999`](#flag--test_timeout) +  [`--nocache_test_results`](#flag--nocache_test_results) + +[`--[no]java_deps`](#flag--java_deps) default: "true" +Generate dependency information (for now, compile-time classpath) per Java target. + +[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" +Compile ijars directly from source. + +[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" +The Java language version + +[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" +The Java runtime version + +[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac. + +[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. + +[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description +Specifies a binary to use to do dexing without sharding. + +[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated +Plugins to use in the build. Currently works with java_plugin. + +[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description +Specifies which version of ProGuard to use for code removal when building a Java binary. + +[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]proto_profile`](#flag--proto_profile) default: "true" +Whether to pass profile_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description +The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" +Label of proto_lang_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" +Label of proto_lang_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" +Label of proto_lang_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" +Label of proto_lang_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +[`--test_filter`](#flag--test_filter)`=<a string>` default: see description +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" +This option is deprecated and has no effect. + +[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. + +[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" +The Java language version used to execute the tools that are needed during a build + +[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" +The Java runtime version used to execute tools during the build + +[`--[no]use_ijars`](#flag--use_ijars) default: "true" +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## <span id="canonicalize-flags">Canonicalize-flags Options</span> + +Inherits all options from [build](#build). + +[`--[no]canonicalize_policy`](#canonicalize-flags-flag--canonicalize_policy) default: "false" +Output the canonical policy, after expansion and filtering. To keep the output clean, the canonicalized command arguments will NOT be shown when this option is set to true. Note that the command specified by --for_command affects the filtered policy, and if none is specified, the default command is 'build'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]experimental_include_default_values`](#canonicalize-flags-flag--experimental_include_default_values) default: "true" +Whether Starlark options set to their default values are included in the output. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +<!-- --> + +[`--[no]incompatible_config_setting_private_default_visibility`](#canonicalize-flags-flag--incompatible_config_setting_private_default_visibility) default: "false" +If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enforce_config_setting_visibility`](#canonicalize-flags-flag--incompatible_enforce_config_setting_visibility) default: "true" +If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--for_command`](#canonicalize-flags-flag--for_command)`=<a string>` default: "build" +The command for which the options should be canonicalized. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--invocation_policy`](#canonicalize-flags-flag--invocation_policy)`=<a string>` default: "" +Applies an invocation policy to the options to be canonicalized. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +<!-- --> + +[`--deleted_packages`](#canonicalize-flags-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. + +[`--[no]fetch`](#canonicalize-flags-flag--fetch) default: "true" +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +[`--package_path`](#canonicalize-flags-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +[`--[no]show_loading_progress`](#canonicalize-flags-flag--show_loading_progress) default: "true" +If enabled, causes Bazel to print "Loading package:" messages. + +## <span id="clean">Clean Options</span> + +Inherits all options from [build](#build). + +[`--[no]async`](#clean-flag--async) default: "false" +If true, output cleaning is asynchronous. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--[no]expunge`](#clean-flag--expunge) default: "false" +If true, clean removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +[`--expunge_async`](#clean-flag--expunge_async) +If specified, clean asynchronously removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. + +Expands to: +  [`--expunge`](#flag--expunge) +  [`--async`](#flag--async) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +## <span id="config">Config Options</span> + +## <span id="coverage">Coverage Options</span> + +Inherits all options from [test](#test). + +## <span id="cquery">Cquery Options</span> + +Inherits all options from [test](#test). + +[`--aspect_deps`](#cquery-flag--aspect_deps)`=<off, conservative or precise>` default: "conservative" +How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]consistent_labels`](#cquery-flag--consistent_labels) default: "false" +If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]experimental_explicit_aspects`](#cquery-flag--experimental_explicit_aspects) default: "false" +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]graph:factored`](#cquery-flag--graph:factored) default: "true" +If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--graph:node_limit`](#cquery-flag--graph:node_limit)`=<an integer>` default: "512" +The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]implicit_deps`](#cquery-flag--implicit_deps) default: "true" +If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]include_aspects`](#cquery-flag--include_aspects) default: "true" +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]incompatible_package_group_includes_double_slash`](#cquery-flag--incompatible_package_group_includes_double_slash) default: "true" +If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]infer_universe_scope`](#cquery-flag--infer_universe_scope) default: "false" +If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]line_terminator_null`](#cquery-flag--line_terminator_null) default: "false" +Whether each format is terminated with \0 instead of newline. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]nodep_deps`](#cquery-flag--nodep_deps) default: "true" +If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--output`](#cquery-flag--output)`=<a string>` default: "label" +The format in which the cquery results should be printed. Allowed values for cquery are: label, label_kind, textproto, transitions, proto, streamed_proto, jsonproto. If you select 'transitions', you also have to specify the --transitions=(lite\|full) option. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--output_file`](#cquery-flag--output_file)`=<a string>` default: "" +When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:default_values`](#cquery-flag--proto:default_values) default: "true" +If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:definition_stack`](#cquery-flag--proto:definition_stack) default: "false" +Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:flatten_selects`](#cquery-flag--proto:flatten_selects) default: "true" +If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]proto:include_attribute_source_aspects`](#cquery-flag--proto:include_attribute_source_aspects) default: "false" +Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:include_configurations`](#cquery-flag--proto:include_configurations) default: "true" +if enabled, proto output will include information about configurations. When disabled,cquery proto output format resembles query output format. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]proto:include_starlark_rule_env`](#cquery-flag--proto:include_starlark_rule_env) default: "true" +Use the starlark environment in the value of the generated \$internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:include_synthetic_attribute_hash`](#cquery-flag--proto:include_synthetic_attribute_hash) default: "false" +Whether or not to calculate and populate the \$internal_attr_hash attribute. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:instantiation_stack`](#cquery-flag--proto:instantiation_stack) default: "false" +Populate the instantiation call stack of each rule. Note that this requires the stack to be present + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:locations`](#cquery-flag--proto:locations) default: "true" +Whether to output location information in proto output at all. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--proto:output_rule_attrs`](#cquery-flag--proto:output_rule_attrs)`=<comma-separated list of options>` default: "all" +Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:rule_classes`](#cquery-flag--proto:rule_classes) default: "false" +Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:rule_inputs_and_outputs`](#cquery-flag--proto:rule_inputs_and_outputs) default: "true" +Whether or not to populate the rule_input and rule_output fields. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--query_file`](#cquery-flag--query_file)`=<a string>` default: "" +If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--[no]relative_locations`](#cquery-flag--relative_locations) default: "false" +If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--show_config_fragments`](#cquery-flag--show_config_fragments)`=<off, direct or transitive>` default: "off" +Shows the configuration fragments required by a rule and its transitive dependencies. This can be useful for evaluating how much a configured target graph can be trimmed. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--starlark:expr`](#cquery-flag--starlark:expr)`=<a string>` default: "" +A Starlark expression to format each configured target in cquery's --output=starlark mode. The configured target is bound to 'target'. If neither --starlark:expr nor --starlark:file is specified, this option will default to 'str(target.label)'. It is an error to specify both --starlark:expr and --starlark:file. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--starlark:file`](#cquery-flag--starlark:file)`=<a string>` default: "" +The name of a file that defines a Starlark function called 'format', of one argument, that is applied to each configured target to format it as a string. It is an error to specify both --starlark:expr and --starlark:file. See help for --output=starlark for additional detail. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]tool_deps`](#cquery-flag--tool_deps) default: "true" +Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--transitions`](#cquery-flag--transitions)`=<full, lite or none>` default: "none" +The format in which cquery will print transition information. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--universe_scope`](#cquery-flag--universe_scope)`=<comma-separated list of options>` default: "" +A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" +When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +Enable persistent Android dex and desugar actions by using workers. + +Expands to: +  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) +  [`--strategy=Desugar=worker`](#flag--strategy) +  [`--strategy=DexBuilder=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +Enable persistent Android resource processor by using workers. + +Expands to: +  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) +  [`--strategy=AaptPackage=worker`](#flag--strategy) +  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) +  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) +  [`--strategy=RClassGenerator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) +  [`--strategy=AndroidAapt2=worker`](#flag--strategy) +  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) +  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) +  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) +  [`--strategy=ManifestMerger=worker`](#flag--strategy) +  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) +  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) +  [`--strategy=AARGenerator=worker`](#flag--strategy) +  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) +  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: +  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: +  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: +  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) +  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" +Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" +Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compiler`](#flag--compiler)`=<a string>` default: see description +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--grte_top`](#flag--grte_top)`=<a label>` default: see description +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description +If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" +If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--platforms`](#flag--platforms)`=<a build target label>` default: "" +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_path`](#flag--python_path)`=<a string>` default: see description +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" +Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" +The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" +Sets the suffixes of header files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" +Sets the suffixes of source files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" +Run extra actions for alternative Java api versions in a proto_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" +If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" +If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]save_temps`](#flag--save_temps) default: "false" +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case +the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +\<br\> +Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" +Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cpu`](#flag--cpu)`=<a string>` default: "" +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description +The cs_fdo_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated +Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" +py_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description +The fdo_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--features`](#flag--features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]force_pic`](#flag--force_pic) default: "false" +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" +Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO backend step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO indexing step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" +If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description +Absolute path name of cc_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description +Absolute path name of ld_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]stamp`](#flag--stamp) default: "false" +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated +Additional options to pass to strip when generating a '\<name\>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--[no]check_visibility`](#flag--check_visibility) default: "true" +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_check_desugar_deps`](#flag--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`](#flag--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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" +When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" +When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description +An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" +Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" +Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +<!-- --> + +[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" +If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" +If true, make the default value true for alwayslink attributes in objc_library and objc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" +When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" +Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" +Use dex2oat in parallel to possibly speed up android_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" +Enable checking for memory leaks in ios_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +<!-- --> + +[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" +When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" +Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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`](#flag--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`](#flag--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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +<!-- --> + +[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" +If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +Enables reduced classpaths for Java compilations. + +[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]explicit_java_test_deps`](#flag--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. + +[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description +The Java launcher used by tools that are executed during a build. + +[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac when building tools that are executed during a build. + +[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. + +[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" +If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated +Additional options to pass to the J2ObjC tool. + +[`--java_debug`](#flag--java_debug) +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. + +Expands to: +  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) +  [`--test_output=streamed`](#flag--test_output) +  [`--test_strategy=exclusive`](#flag--test_strategy) +  [`--test_timeout=9999`](#flag--test_timeout) +  [`--nocache_test_results`](#flag--nocache_test_results) + +[`--[no]java_deps`](#flag--java_deps) default: "true" +Generate dependency information (for now, compile-time classpath) per Java target. + +[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" +Compile ijars directly from source. + +[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" +The Java language version + +[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" +The Java runtime version + +[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac. + +[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. + +[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description +Specifies a binary to use to do dexing without sharding. + +[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated +Plugins to use in the build. Currently works with java_plugin. + +[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description +Specifies which version of ProGuard to use for code removal when building a Java binary. + +[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]proto_profile`](#flag--proto_profile) default: "true" +Whether to pass profile_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description +The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" +Label of proto_lang_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" +Label of proto_lang_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" +Label of proto_lang_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" +Label of proto_lang_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +[`--test_filter`](#flag--test_filter)`=<a string>` default: see description +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" +This option is deprecated and has no effect. + +[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. + +[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" +The Java language version used to execute the tools that are needed during a build + +[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" +The Java runtime version used to execute tools during the build + +[`--[no]use_ijars`](#flag--use_ijars) default: "true" +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## <span id="dump">Dump Options</span> + +[`--[no]action_cache`](#dump-flag--action_cache) default: "false" +Dump action cache content. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--memory`](#dump-flag--memory)`=<memory mode>` default: see description +Dump the memory use of the given Skyframe node. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]packages`](#dump-flag--packages) default: "false" +Dump package cache content. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]rule_classes`](#dump-flag--rule_classes) default: "false" +Dump rule classes. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--[no]rules`](#dump-flag--rules) default: "false" +Dump rules, including counts and memory usage (if memory is tracked). + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--skyframe`](#dump-flag--skyframe)`=<off, summary, count, value, deps, rdeps, function_graph, active_directories or active_directories_frontier_deps>` default: "off" +Dump the Skyframe graph. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--skykey_filter`](#dump-flag--skykey_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: ".\*" +Regex filter of SkyKey names to output. Only used with --skyframe=deps, rdeps, function_graph. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +[`--skylark_memory`](#dump-flag--skylark_memory)`=<a string>` default: see description +Dumps a pprof-compatible memory profile to the specified path. To learn more please see https://github.com/google/pprof. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +## <span id="fetch">Fetch Options</span> + +Inherits all options from [test](#test). + +[`--[no]all`](#fetch-flag--all) default: "false" +Fetches all external repositories necessary for building any target or repository. This is the default if no other flags and arguments are provided. Only works when --enable_bzlmod is on. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--[no]keep_going`](#fetch-flag--keep_going) \[`-k`\] default: "false" +Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--loading_phase_threads`](#fetch-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +<!-- --> + +[`--[no]incompatible_config_setting_private_default_visibility`](#fetch-flag--incompatible_config_setting_private_default_visibility) default: "false" +If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enforce_config_setting_visibility`](#fetch-flag--incompatible_enforce_config_setting_visibility) default: "true" +If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]configure`](#fetch-flag--configure) default: "false" +Only fetches repositories marked as 'configure' for system-configuration purpose. Only works when --enable_bzlmod is on. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--[no]force`](#fetch-flag--force) default: "false" +Ignore existing repository if any and force fetch the repository again. Only works when --enable_bzlmod is on. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--repo`](#fetch-flag--repo)`=<a string>` multiple uses are accumulated +Only fetches the specified repository, which can be either {@apparent_repo_name} or {@@canonical_repo_name}. Only works when --enable_bzlmod is on. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--deleted_packages`](#fetch-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. + +[`--[no]fetch`](#fetch-flag--fetch) default: "true" +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +[`--package_path`](#fetch-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +[`--[no]show_loading_progress`](#fetch-flag--show_loading_progress) default: "true" +If enabled, causes Bazel to print "Loading package:" messages. + +<!-- --> + +[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" +When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +Enable persistent Android dex and desugar actions by using workers. + +Expands to: +  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) +  [`--strategy=Desugar=worker`](#flag--strategy) +  [`--strategy=DexBuilder=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +Enable persistent Android resource processor by using workers. + +Expands to: +  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) +  [`--strategy=AaptPackage=worker`](#flag--strategy) +  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) +  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) +  [`--strategy=RClassGenerator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) +  [`--strategy=AndroidAapt2=worker`](#flag--strategy) +  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) +  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) +  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) +  [`--strategy=ManifestMerger=worker`](#flag--strategy) +  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) +  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) +  [`--strategy=AARGenerator=worker`](#flag--strategy) +  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) +  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: +  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: +  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: +  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) +  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" +Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" +Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compiler`](#flag--compiler)`=<a string>` default: see description +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--grte_top`](#flag--grte_top)`=<a label>` default: see description +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description +If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" +If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--platforms`](#flag--platforms)`=<a build target label>` default: "" +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_path`](#flag--python_path)`=<a string>` default: see description +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" +Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" +The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" +Sets the suffixes of header files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" +Sets the suffixes of source files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" +Run extra actions for alternative Java api versions in a proto_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" +If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" +If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]save_temps`](#flag--save_temps) default: "false" +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case +the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +\<br\> +Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" +Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cpu`](#flag--cpu)`=<a string>` default: "" +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description +The cs_fdo_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated +Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" +py_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description +The fdo_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--features`](#flag--features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]force_pic`](#flag--force_pic) default: "false" +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" +Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO backend step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO indexing step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" +If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description +Absolute path name of cc_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description +Absolute path name of ld_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]stamp`](#flag--stamp) default: "false" +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated +Additional options to pass to strip when generating a '\<name\>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--[no]check_visibility`](#flag--check_visibility) default: "true" +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_check_desugar_deps`](#flag--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`](#flag--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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" +When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" +When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description +An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" +Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" +Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +<!-- --> + +[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" +If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" +If true, make the default value true for alwayslink attributes in objc_library and objc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" +When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" +Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" +Use dex2oat in parallel to possibly speed up android_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" +Enable checking for memory leaks in ios_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +<!-- --> + +[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" +When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" +Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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`](#flag--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`](#flag--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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +<!-- --> + +[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" +If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +Enables reduced classpaths for Java compilations. + +[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]explicit_java_test_deps`](#flag--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. + +[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description +The Java launcher used by tools that are executed during a build. + +[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac when building tools that are executed during a build. + +[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. + +[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" +If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated +Additional options to pass to the J2ObjC tool. + +[`--java_debug`](#flag--java_debug) +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. + +Expands to: +  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) +  [`--test_output=streamed`](#flag--test_output) +  [`--test_strategy=exclusive`](#flag--test_strategy) +  [`--test_timeout=9999`](#flag--test_timeout) +  [`--nocache_test_results`](#flag--nocache_test_results) + +[`--[no]java_deps`](#flag--java_deps) default: "true" +Generate dependency information (for now, compile-time classpath) per Java target. + +[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" +Compile ijars directly from source. + +[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" +The Java language version + +[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" +The Java runtime version + +[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac. + +[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. + +[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description +Specifies a binary to use to do dexing without sharding. + +[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated +Plugins to use in the build. Currently works with java_plugin. + +[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description +Specifies which version of ProGuard to use for code removal when building a Java binary. + +[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]proto_profile`](#flag--proto_profile) default: "true" +Whether to pass profile_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description +The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" +Label of proto_lang_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" +Label of proto_lang_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" +Label of proto_lang_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" +Label of proto_lang_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +[`--test_filter`](#flag--test_filter)`=<a string>` default: see description +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" +This option is deprecated and has no effect. + +[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. + +[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" +The Java language version used to execute the tools that are needed during a build + +[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" +The Java runtime version used to execute tools during the build + +[`--[no]use_ijars`](#flag--use_ijars) default: "true" +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## <span id="help">Help Options</span> + +[`--help_verbosity`](#help-flag--help_verbosity)`=<long, medium or short>` default: "medium" +Select the verbosity of the help command. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--long`](#help-flag--long) \[`-l`\] +Show full description of each option, instead of just its name. + +Expands to: +  [`--help_verbosity=long`](#flag--help_verbosity) + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--short`](#help-flag--short) +Show only the names of the options, not their types or meanings. + +Expands to: +  [`--help_verbosity=short`](#flag--help_verbosity) + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +## <span id="info">Info Options</span> + +Inherits all options from [build](#build). + +[`--info_output_type`](#info-flag--info_output_type)`=<stdout or response_proto>` default: "stdout" +If stdout, results are directly printed to the console. If response_proto, the info command results are packed in response extensions. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +<!-- --> + +[`--[no]show_make_env`](#info-flag--show_make_env) default: "false" +Include the "Make" environment in the output. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +## <span id="license">License Options</span> + +## <span id="mobile-install">Mobile-install Options</span> + +Inherits all options from [build](#build). + +[`--mode`](#mobile-install-flag--mode)`=<classic, classic_internal_test_do_not_use or skylark>` default: "skylark" +Deprecated no-effect flag. Only skylark mode is still supported. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--adb`](#mobile-install-flag--adb)`=<a string>` default: "" +adb binary to use for the 'mobile-install' command. If unspecified, the one in the Android SDK specified by the --android_sdk_channel command line option (or the default SDK if --android_sdk_channel is not specified) is used. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--[no]incremental`](#mobile-install-flag--incremental) default: "false" +Whether to do an incremental install. If true, try to avoid unnecessary additional work by reading the state of the device the code is to be installed on and using that information to avoid unnecessary work. If false (the default), always do a full install. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]split_apks`](#mobile-install-flag--split_apks) default: "false" +Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--adb_arg`](#mobile-install-flag--adb_arg)`=<a string>` multiple uses are accumulated +Extra arguments to pass to adb. Usually used to designate a device to install to. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--debug_app`](#mobile-install-flag--debug_app) +Whether to wait for the debugger before starting the app. + +Expands to: +  [`--start=DEBUG`](#flag--start) + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--device`](#mobile-install-flag--device)`=<a string>` default: "" +The adb device serial number. If not specified, the first device will be used. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--start`](#mobile-install-flag--start)`=<no, cold, warm or debug>` default: "NO" +How the app should be started after installing it. Set to WARM to preserve and restore application state on incremental installs. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--start_app`](#mobile-install-flag--start_app) +Whether to start the app after installing it. + +Expands to: +  [`--start=COLD`](#flag--start) + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--incremental_install_verbosity`](#mobile-install-flag--incremental_install_verbosity)`=<a string>` default: "" +The verbosity for incremental install. Set to 1 for debug logging. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +## <span id="mod">Mod Options</span> + +[`--[no]experimental_remotable_source_manifests`](#mod-flag--experimental_remotable_source_manifests) default: "false" +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_strict_fileset_output`](#mod-flag--experimental_strict_fileset_output) default: "false" +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_modify_execution_info_additive`](#mod-flag--incompatible_modify_execution_info_additive) default: "true" +When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--loading_phase_threads`](#mod-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--modify_execution_info`](#mod-flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]use_target_platform_for_tests`](#mod-flag--use_target_platform_for_tests) default: "false" +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--[no]incompatible_bazel_test_exec_run_under`](#mod-flag--incompatible_bazel_test_exec_run_under) default: "true" +If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]build_runfile_links`](#mod-flag--build_runfile_links) default: "true" +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_runfile_manifests`](#mod-flag--build_runfile_manifests) default: "true" +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_always_include_files_in_data`](#mod-flag--incompatible_always_include_files_in_data) default: "true" +If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_compact_repo_mapping_manifest`](#mod-flag--incompatible_compact_repo_mapping_manifest) default: "false" +If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_disable_select_on`](#mod-flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_filegroup_runfiles_for_data`](#mod-flag--incompatible_filegroup_runfiles_for_data) default: "true" +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--action_env`](#mod-flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case +the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +\<br\> +Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--allowed_cpu_values`](#mod-flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]collect_code_coverage`](#mod-flag--collect_code_coverage) default: "false" +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compilation_mode`](#mod-flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--cpu`](#mod-flag--cpu)`=<a string>` default: "" +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--define`](#mod-flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_runfiles`](#mod-flag--enable_runfiles) default: "auto" +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--exec_aspects`](#mod-flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_action_listener`](#mod-flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated +Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_collect_code_coverage_for_generated_files`](#mod-flag--experimental_collect_code_coverage_for_generated_files) default: "false" +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_output_paths`](#mod-flag--experimental_output_paths)`=<off or strip>` default: "off" +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_override_platform_cpu_name`](#mod-flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_platform_in_output_dir`](#mod-flag--experimental_platform_in_output_dir) default: "false" +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#mod-flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--features`](#mod-flag--features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_action_env`](#mod-flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_compilation_mode`](#mod-flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_cpu`](#mod-flag--host_cpu)`=<a string>` default: "" +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_features`](#mod-flag--host_features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_auto_exec_groups`](#mod-flag--incompatible_auto_exec_groups) default: "false" +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_merge_genfiles_directory`](#mod-flag--incompatible_merge_genfiles_directory) default: "true" +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_target_cpu_from_platform`](#mod-flag--incompatible_target_cpu_from_platform) default: "true" +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]instrument_test_targets`](#mod-flag--instrument_test_targets) default: "false" +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--instrumentation_filter`](#mod-flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_suffix`](#mod-flag--platform_suffix)`=<a string>` default: see description +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--run_under`](#mod-flag--run_under)`=<a prefix in front of command>` default: see description +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]stamp`](#mod-flag--stamp) default: "false" +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--[no]check_visibility`](#mod-flag--check_visibility) default: "true" +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]enforce_constraints`](#mod-flag--enforce_constraints) default: "true" +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_enforce_transitive_visibility`](#mod-flag--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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_check_testonly_for_output_files`](#mod-flag--incompatible_check_testonly_for_output_files) default: "false" +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]strict_filesets`](#mod-flag--strict_filesets) default: "false" +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--target_environment`](#mod-flag--target_environment)`=<a build target label>` multiple uses are accumulated +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--[no]incompatible_config_setting_private_default_visibility`](#mod-flag--incompatible_config_setting_private_default_visibility) default: "false" +If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enforce_config_setting_visibility`](#mod-flag--incompatible_enforce_config_setting_visibility) default: "true" +If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]allow_analysis_failures`](#mod-flag--allow_analysis_failures) default: "false" +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--analysis_testing_deps_limit`](#mod-flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" +Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--base_module`](#mod-flag--base_module)`=<"<root>" for the root module; <module>@<version> for a specific version of a module; <module> for all versions of a module; @<name> for a repo with the given apparent name; or @@<name> for a repo with the given canonical name>` default: "\<root\>" +Specify a module relative to which the specified target repos will be interpreted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--charset`](#mod-flag--charset)`=<utf8 or ascii>` default: "utf8" +Chooses the character set to use for the tree. Only affects text output. Valid values are "utf8" or "ascii". Default is "utf8" + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]cycles`](#mod-flag--cycles) default: "true" +Points out dependency cycles inside the displayed tree. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--depth`](#mod-flag--depth)`=<an integer>` default: "-1" +Maximum display depth of the dependency tree. A depth of 1 displays the direct dependencies, for example. For tree, path and all_paths it defaults to Integer.MAX_VALUE, while for deps and explain it defaults to 1 (only displays direct deps of the root besides the target leaves and their parents). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--extension_filter`](#mod-flag--extension_filter)`=<a comma-separated list of <extension>s>` default: see description +Only display the usages of these module extensions and the repos generated by them if their respective flags are set. If set, the result graph will only include paths that contain modules using the specified extensions. An empty list disables the filter, effectively specifying all possible extensions. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--extension_info`](#mod-flag--extension_info)`=<hidden, usages, repos or all>` default: "hidden" +Specify how much detail about extension usages to include in the query result. "Usages" will only show the extensions names, "repos" will also include repos imported with use_repo, and "all" will also show the other repositories generated by extensions. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--extension_usages`](#mod-flag--extension_usages)`=<a comma-separated list of <module>s>` default: "" +Specify modules whose extension usages will be displayed in the show_extension query. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--from`](#mod-flag--from)`=<a comma-separated list of <module>s>` default: "\<root\>" +The module(s) starting from which the dependency graph query will be displayed. Check each query’s description for the exact semantics. Defaults to \<root\>. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]include_builtin`](#mod-flag--include_builtin) default: "false" +Include built-in modules in the dependency graph. Disabled by default because it is quite noisy. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]include_unused`](#mod-flag--include_unused) default: "false" +The queries will also take into account and display the unused modules, which are not present in the module resolution graph after selection (due to the Minimal-Version Selection or override rules). This can have different effects for each of the query types i.e. include new paths in the all_paths command, or extra dependants in the explain command. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--output`](#mod-flag--output)`=<text, json or graph>` default: "text" +The format in which the query results should be printed. Allowed values for query are: text, json, graph + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]verbose`](#mod-flag--verbose) default: "false" +The queries will also display the reason why modules were resolved to their current version (if changed). Defaults to true only for the explain query. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +<!-- --> + +[`--[no]verbose_visibility_errors`](#mod-flag--verbose_visibility_errors) default: "false" +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--flag_alias`](#mod-flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--deleted_packages`](#mod-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. + +[`--[no]fetch`](#mod-flag--fetch) default: "true" +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +[`--package_path`](#mod-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +[`--[no]show_loading_progress`](#mod-flag--show_loading_progress) default: "true" +If enabled, causes Bazel to print "Loading package:" messages. + +## <span id="print_action">Print_action Options</span> + +Inherits all options from [build](#build). + +[`--print_action_mnemonics`](#print_action-flag--print_action_mnemonics)`=<a string>` multiple uses are accumulated +Lists which mnemonics to filter print_action data by, no filtering takes place when left empty. + +## <span id="query">Query Options</span> + +[`--[no]experimental_remotable_source_manifests`](#query-flag--experimental_remotable_source_manifests) default: "false" +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_strict_fileset_output`](#query-flag--experimental_strict_fileset_output) default: "false" +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_modify_execution_info_additive`](#query-flag--incompatible_modify_execution_info_additive) default: "true" +When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]keep_going`](#query-flag--keep_going) \[`-k`\] default: "false" +Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--loading_phase_threads`](#query-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +[`--modify_execution_info`](#query-flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]use_target_platform_for_tests`](#query-flag--use_target_platform_for_tests) default: "false" +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--[no]incompatible_bazel_test_exec_run_under`](#query-flag--incompatible_bazel_test_exec_run_under) default: "true" +If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]build_runfile_links`](#query-flag--build_runfile_links) default: "true" +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_runfile_manifests`](#query-flag--build_runfile_manifests) default: "true" +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_always_include_files_in_data`](#query-flag--incompatible_always_include_files_in_data) default: "true" +If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_compact_repo_mapping_manifest`](#query-flag--incompatible_compact_repo_mapping_manifest) default: "false" +If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_disable_select_on`](#query-flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_filegroup_runfiles_for_data`](#query-flag--incompatible_filegroup_runfiles_for_data) default: "true" +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--action_env`](#query-flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case +the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +\<br\> +Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--allowed_cpu_values`](#query-flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]collect_code_coverage`](#query-flag--collect_code_coverage) default: "false" +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compilation_mode`](#query-flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--cpu`](#query-flag--cpu)`=<a string>` default: "" +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--define`](#query-flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_runfiles`](#query-flag--enable_runfiles) default: "auto" +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--exec_aspects`](#query-flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_action_listener`](#query-flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated +Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_collect_code_coverage_for_generated_files`](#query-flag--experimental_collect_code_coverage_for_generated_files) default: "false" +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_output_paths`](#query-flag--experimental_output_paths)`=<off or strip>` default: "off" +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_override_platform_cpu_name`](#query-flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_platform_in_output_dir`](#query-flag--experimental_platform_in_output_dir) default: "false" +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#query-flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--features`](#query-flag--features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_action_env`](#query-flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_compilation_mode`](#query-flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_cpu`](#query-flag--host_cpu)`=<a string>` default: "" +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_features`](#query-flag--host_features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_auto_exec_groups`](#query-flag--incompatible_auto_exec_groups) default: "false" +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_merge_genfiles_directory`](#query-flag--incompatible_merge_genfiles_directory) default: "true" +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_target_cpu_from_platform`](#query-flag--incompatible_target_cpu_from_platform) default: "true" +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]instrument_test_targets`](#query-flag--instrument_test_targets) default: "false" +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--instrumentation_filter`](#query-flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_suffix`](#query-flag--platform_suffix)`=<a string>` default: see description +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--run_under`](#query-flag--run_under)`=<a prefix in front of command>` default: see description +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]stamp`](#query-flag--stamp) default: "false" +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--[no]check_visibility`](#query-flag--check_visibility) default: "true" +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]enforce_constraints`](#query-flag--enforce_constraints) default: "true" +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_enforce_transitive_visibility`](#query-flag--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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_check_testonly_for_output_files`](#query-flag--incompatible_check_testonly_for_output_files) default: "false" +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]strict_filesets`](#query-flag--strict_filesets) default: "false" +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--target_environment`](#query-flag--target_environment)`=<a build target label>` multiple uses are accumulated +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--[no]incompatible_config_setting_private_default_visibility`](#query-flag--incompatible_config_setting_private_default_visibility) default: "false" +If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enforce_config_setting_visibility`](#query-flag--incompatible_enforce_config_setting_visibility) default: "true" +If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]allow_analysis_failures`](#query-flag--allow_analysis_failures) default: "false" +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--analysis_testing_deps_limit`](#query-flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" +Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--aspect_deps`](#query-flag--aspect_deps)`=<off, conservative or precise>` default: "conservative" +How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]consistent_labels`](#query-flag--consistent_labels) default: "false" +If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]experimental_explicit_aspects`](#query-flag--experimental_explicit_aspects) default: "false" +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]experimental_graphless_query`](#query-flag--experimental_graphless_query) default: "auto" +If true, uses a Query implementation that does not make a copy of the graph. The new implementation only supports --order_output=no, as well as only a subset of output formatters. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--graph:conditional_edges_limit`](#query-flag--graph:conditional_edges_limit)`=<an integer>` default: "4" +The maximum number of condition labels to show. -1 means no truncation and 0 means no annotation. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]graph:factored`](#query-flag--graph:factored) default: "true" +If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--graph:node_limit`](#query-flag--graph:node_limit)`=<an integer>` default: "512" +The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]implicit_deps`](#query-flag--implicit_deps) default: "true" +If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]include_aspects`](#query-flag--include_aspects) default: "true" +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]incompatible_lexicographical_output`](#query-flag--incompatible_lexicographical_output) default: "true" +If this option is set, sorts --order_output=auto output in lexicographical order. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_package_group_includes_double_slash`](#query-flag--incompatible_package_group_includes_double_slash) default: "true" +If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]infer_universe_scope`](#query-flag--infer_universe_scope) default: "false" +If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]line_terminator_null`](#query-flag--line_terminator_null) default: "false" +Whether each format is terminated with \0 instead of newline. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]nodep_deps`](#query-flag--nodep_deps) default: "true" +If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--noorder_results`](#query-flag--noorder_results) +Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. + +Expands to: +  [`--order_output=no`](#flag--order_output) + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--null`](#query-flag--null) +Whether each format is terminated with \0 instead of newline. + +Expands to: +  [`--line_terminator_null=true`](#flag--line_terminator_null) + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--order_output`](#query-flag--order_output)`=<no, deps, auto or full>` default: "auto" +Output the results unordered (no), dependency-ordered (deps), or fully ordered (full). The default is 'auto', meaning that results are output either dependency-ordered or fully ordered, depending on the output formatter (dependency-ordered for proto, minrank, maxrank, and graph, fully ordered for all others). When output is fully ordered, nodes are printed in a fully deterministic (total) order. First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a post-order depth-first search in which outgoing edges to unvisited nodes are traversed in alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order in which they were visited. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--order_results`](#query-flag--order_results) +Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. + +Expands to: +  [`--order_output=auto`](#flag--order_output) + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--output`](#query-flag--output)`=<a string>` default: "label" +The format in which the query results should be printed. Allowed values for query are: build, graph, streamed_jsonproto, label, label_kind, location, maxrank, minrank, package, proto, streamed_proto, xml. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--output_file`](#query-flag--output_file)`=<a string>` default: "" +When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:default_values`](#query-flag--proto:default_values) default: "true" +If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:definition_stack`](#query-flag--proto:definition_stack) default: "false" +Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:flatten_selects`](#query-flag--proto:flatten_selects) default: "true" +If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]proto:include_attribute_source_aspects`](#query-flag--proto:include_attribute_source_aspects) default: "false" +Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:include_starlark_rule_env`](#query-flag--proto:include_starlark_rule_env) default: "true" +Use the starlark environment in the value of the generated \$internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:include_synthetic_attribute_hash`](#query-flag--proto:include_synthetic_attribute_hash) default: "false" +Whether or not to calculate and populate the \$internal_attr_hash attribute. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:instantiation_stack`](#query-flag--proto:instantiation_stack) default: "false" +Populate the instantiation call stack of each rule. Note that this requires the stack to be present + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:locations`](#query-flag--proto:locations) default: "true" +Whether to output location information in proto output at all. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--proto:output_rule_attrs`](#query-flag--proto:output_rule_attrs)`=<comma-separated list of options>` default: "all" +Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:rule_classes`](#query-flag--proto:rule_classes) default: "false" +Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]proto:rule_inputs_and_outputs`](#query-flag--proto:rule_inputs_and_outputs) default: "true" +Whether or not to populate the rule_input and rule_output fields. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--query_file`](#query-flag--query_file)`=<a string>` default: "" +If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--[no]relative_locations`](#query-flag--relative_locations) default: "false" +If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]strict_test_suite`](#query-flag--strict_test_suite) default: "false" +If true, the tests() expression gives an error if it encounters a test_suite containing non-test targets. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]tool_deps`](#query-flag--tool_deps) default: "true" +Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--universe_scope`](#query-flag--universe_scope)`=<comma-separated list of options>` default: "" +A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]xml:default_values`](#query-flag--xml:default_values) default: "false" +If true, rule attributes whose value is not explicitly specified in the BUILD file are printed; otherwise they are omitted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]xml:line_numbers`](#query-flag--xml:line_numbers) default: "true" +If true, XML output contains line numbers. Disabling this option may make diffs easier to read. This option is only applicable to --output=xml. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +<!-- --> + +[`--[no]verbose_visibility_errors`](#query-flag--verbose_visibility_errors) default: "false" +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--flag_alias`](#query-flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--deleted_packages`](#query-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. + +[`--[no]fetch`](#query-flag--fetch) default: "true" +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +[`--package_path`](#query-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +[`--[no]show_loading_progress`](#query-flag--show_loading_progress) default: "true" +If enabled, causes Bazel to print "Loading package:" messages. + +## <span id="run">Run Options</span> + +Inherits all options from [build](#build). + +[`--[no]portable_paths`](#run-flag--portable_paths) default: "false" +If true, includes paths to replace in ExecRequest to make the resulting paths portable. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]run`](#run-flag--run) default: "true" +If false, skip running the command line constructed for the built target. Note that this flag is ignored for all --script_path builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--run_env`](#run-flag--run_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to the target to run. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. Note that the executed target will generally see the full environment of the host except for those variables that have been explicitly unset. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--script_path`](#run-flag--script_path)`=<a path>` default: see description +If set, write a shell script to the given file which invokes the target. If this option is set, the target is not run from bazel. Use 'bazel run --script_path=foo //foo && ./foo' to invoke target '//foo' This differs from 'bazel run //foo' in that the bazel lock is released and the executable is connected to the terminal's stdin. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +## <span id="shutdown">Shutdown Options</span> + +[`--iff_heap_size_greater_than`](#shutdown-flag--iff_heap_size_greater_than)`=<an integer>` default: "0" +Iff non-zero, then shutdown will only shut down the server if the total memory (in MB) consumed by the JVM exceeds this value. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +## <span id="test">Test Options</span> + +Inherits all options from [build](#build). + +[`--[no]print_relative_test_log_paths`](#test-flag--print_relative_test_log_paths) default: "false" +If true, when printing the path to a test log, use relative path that makes use of the 'testlogs' convenience symlink. N.B. - A subsequent 'build'/'test'/etc invocation with a different configuration can cause the target of this symlink to change, making the path printed previously no longer useful. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]test_verbose_timeout_warnings`](#test-flag--test_verbose_timeout_warnings) default: "false" +If true, print additional warnings when the actual test execution time does not match the timeout defined by the test (whether implied or explicit). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]verbose_test_summary`](#test-flag--verbose_test_summary) default: "true" +If true, print additional information (timing, number of failed runs, etc) in the test summary. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +## <span id="vendor">Vendor Options</span> + +Inherits all options from [test](#test). + +[`--[no]keep_going`](#vendor-flag--keep_going) \[`-k`\] default: "false" +Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--loading_phase_threads`](#vendor-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +<!-- --> + +[`--[no]incompatible_config_setting_private_default_visibility`](#vendor-flag--incompatible_config_setting_private_default_visibility) default: "false" +If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enforce_config_setting_visibility`](#vendor-flag--incompatible_enforce_config_setting_visibility) default: "true" +If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--repo`](#vendor-flag--repo)`=<a string>` multiple uses are accumulated +Only vendors the specified repository, which can be either `@apparent_repo_name` or `@@canonical_repo_name`. This option can be set multiple times + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--deleted_packages`](#vendor-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. + +[`--[no]fetch`](#vendor-flag--fetch) default: "true" +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +[`--package_path`](#vendor-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +[`--[no]show_loading_progress`](#vendor-flag--show_loading_progress) default: "true" +If enabled, causes Bazel to print "Loading package:" messages. + +<!-- --> + +[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" +When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. +'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. +'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +Enable persistent Android dex and desugar actions by using workers. + +Expands to: +  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) +  [`--strategy=Desugar=worker`](#flag--strategy) +  [`--strategy=DexBuilder=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +Enable persistent Android resource processor by using workers. + +Expands to: +  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) +  [`--strategy=AaptPackage=worker`](#flag--strategy) +  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) +  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) +  [`--strategy=RClassGenerator=worker`](#flag--strategy) +  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) +  [`--strategy=AndroidAapt2=worker`](#flag--strategy) +  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) +  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) +  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) +  [`--strategy=ManifestMerger=worker`](#flag--strategy) +  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) +  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) +  [`--strategy=AARGenerator=worker`](#flag--strategy) +  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) +  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: +  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) +  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: +  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) +  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) +  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: +  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) +  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) +  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +<!-- --> + +[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" +Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" +Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compiler`](#flag--compiler)`=<a string>` default: see description +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--grte_top`](#flag--grte_top)`=<a label>` default: see description +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description +If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" +If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--platforms`](#flag--platforms)`=<a build target label>` default: "" +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_path`](#flag--python_path)`=<a string>` default: see description +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" +Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" +The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +<!-- --> + +[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" +Sets the suffixes of header files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" +Sets the suffixes of source files that a cc_proto_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" +Run extra actions for alternative Java api versions in a proto_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" +If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" +If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]save_temps`](#flag--save_temps) default: "false" +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case +the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +\<br\> +Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" +Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cpu`](#flag--cpu)`=<a string>` default: "" +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description +The cs_fdo_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated +Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" +Enables resource shrinking for android_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" +py_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description +The fdo_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--features`](#flag--features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]force_pic`](#flag--force_pic) default: "false" +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" +Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO backend step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated +Additional option to pass to the LTO indexing step (under --features=thin_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" +If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description +Absolute path name of cc_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description +Absolute path name of ld_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]stamp`](#flag--stamp) default: "false" +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated +Additional options to pass to strip when generating a '\<name\>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +<!-- --> + +[`--[no]check_visibility`](#flag--check_visibility) default: "true" +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +[`--[no]experimental_check_desugar_deps`](#flag--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`](#flag--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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" +When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" +When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description +An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" +Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" +Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +<!-- --> + +[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +<!-- --> + +[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" +If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" +If true, make the default value true for alwayslink attributes in objc_library and objc_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" +When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" +Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" +Use dex2oat in parallel to possibly speed up android_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" +Enable checking for memory leaks in ios_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +<!-- --> + +[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" +When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" +Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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`](#flag--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`](#flag--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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +<!-- --> + +[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +<!-- --> + +[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +<!-- --> + +[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" +If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +Enables reduced classpaths for Java compilations. + +[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +[`--[no]explicit_java_test_deps`](#flag--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. + +[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description +The Java launcher used by tools that are executed during a build. + +[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac when building tools that are executed during a build. + +[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. + +[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" +If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated +Additional options to pass to the J2ObjC tool. + +[`--java_debug`](#flag--java_debug) +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. + +Expands to: +  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) +  [`--test_output=streamed`](#flag--test_output) +  [`--test_strategy=exclusive`](#flag--test_strategy) +  [`--test_timeout=9999`](#flag--test_timeout) +  [`--nocache_test_results`](#flag--nocache_test_results) + +[`--[no]java_deps`](#flag--java_deps) default: "true" +Generate dependency information (for now, compile-time classpath) per Java target. + +[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" +Compile ijars directly from source. + +[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" +The Java language version + +[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" +The Java runtime version + +[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated +Additional options to pass to javac. + +[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. + +[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description +Specifies a binary to use to do dexing without sharding. + +[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated +Plugins to use in the build. Currently works with java_plugin. + +[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description +Specifies which version of ProGuard to use for code removal when building a Java binary. + +[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--[no]proto_profile`](#flag--proto_profile) default: "true" +Whether to pass profile_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description +The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" +Label of proto_lang_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" +Label of proto_lang_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" +Label of proto_lang_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" +Label of proto_lang_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +[`--test_filter`](#flag--test_filter)`=<a string>` default: see description +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" +This option is deprecated and has no effect. + +[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. + +[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" +The Java language version used to execute the tools that are needed during a build + +[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" +The Java runtime version used to execute tools during the build + +[`--[no]use_ijars`](#flag--use_ijars) default: "true" +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## <span id="version">Version Options</span> + +[`--[no]gnu_format`](#version-flag--gnu_format) default: "false" +If set, write the version to stdout using the conventions described in the GNU standards. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +### Option Effect Tags + +| | | +|----|----| +| `unknown` | This option has unknown, or undocumented, effect. | +| `no_op` | This option has literally no effect. | +| `loses_incremental_state` | Changing the value of this option can cause significant loss of incremental state, which slows builds. State could be lost due to a server restart or to invalidation of a large part of the dependency graph. | +| `changes_inputs` | This option actively changes the inputs that bazel considers for the build, such as filesystem restrictions, repository versions, or other options. | +| `affects_outputs` | This option affects bazel's outputs. This tag is intentionally broad, can include transitive affects, and does not specify the type of output it affects. | +| `build_file_semantics` | This option affects the semantics of BUILD or .bzl files. | +| `bazel_internal_configuration` | This option affects settings of bazel-internal machinery. This tag does not, on its own, mean that build artifacts are affected. | +| `loading_and_analysis` | This option affects the loading and analysis of dependencies, and the building of the dependency graph. | +| `execution` | This option affects the execution phase, such as sandboxing or remote execution related options. | +| `host_machine_resource_optimizations` | This option triggers an optimization that may be machine specific and is not guaranteed to work on all machines. The optimization could include a tradeoff with other aspects of performance, such as memory or cpu cost. | +| `eagerness_to_exit` | This option changes how eagerly bazel will exit from a failure, where a choice between continuing despite the failure and ending the invocation exists. | +| `bazel_monitoring` | This option is used to monitor bazel's behavior and performance. | +| `terminal_output` | This option affects bazel's terminal output. | +| `action_command_lines` | This option changes the command line arguments of one or more build actions. | +| `test_runner` | This option changes the testrunner environment of the build. | + +### Option Metadata Tags + +| | | +|----|----| +| `experimental` | This option triggers an experimental feature with no guarantees of functionality. | +| `incompatible_change` | This option triggers a breaking change. Use this option to test your migration readiness or get early access to the new feature | +| `deprecated` | This option is deprecated. It might be that the feature it affects is deprecated, or that another method of supplying the information is preferred. | +| `non_configurable` | This option cannot be changed in a transition or be used in a select() statement. | + + + + + diff --git a/rules/lib/builtins.mdx b/rules/lib/builtins.mdx index 5878e15..c97f74f 100644 --- a/rules/lib/builtins.mdx +++ b/rules/lib/builtins.mdx @@ -2,139 +2,69 @@ title: 'builtins' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> -<h1 class="page-title">Built-in Types</h1> +# Built-in Types {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} +{% include "\_buttons.html" %} This section lists types of Starlark objects. With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. -<ul> - -<li><a href="/rules/lib/builtins/Action">Action</a></li> - -<li><a href="/rules/lib/builtins/actions">actions</a></li> - -<li><a href="/rules/lib/builtins/apple_platform">apple_platform</a></li> - -<li><a href="/rules/lib/builtins/Args">Args</a></li> - -<li><a href="/rules/lib/builtins/Aspect">Aspect</a></li> - -<li><a href="/rules/lib/builtins/Attribute">Attribute</a></li> - -<li><a href="/rules/lib/builtins/bazel_module">bazel_module</a></li> - -<li><a href="/rules/lib/builtins/bazel_module_tags">bazel_module_tags</a></li> - -<li><a href="/rules/lib/builtins/BuildSetting">BuildSetting</a></li> - -<li><a href="/rules/lib/builtins/CcCompilationOutputs">CcCompilationOutputs</a></li> - -<li><a href="/rules/lib/builtins/CcLinkingOutputs">CcLinkingOutputs</a></li> - -<li><a href="/rules/lib/builtins/CompilationContext">CompilationContext</a></li> - -<li><a href="/rules/lib/builtins/configuration">configuration</a></li> - -<li><a href="/rules/lib/builtins/ctx">ctx</a></li> - -<li><a href="/rules/lib/builtins/depset">depset</a></li> - -<li><a href="/rules/lib/builtins/DirectoryExpander">DirectoryExpander</a></li> - -<li><a href="/rules/lib/builtins/DottedVersion">DottedVersion</a></li> - -<li><a href="/rules/lib/builtins/exec_result">exec_result</a></li> - -<li><a href="/rules/lib/builtins/ExecGroupCollection">ExecGroupCollection</a></li> - -<li><a href="/rules/lib/builtins/ExecGroupContext">ExecGroupContext</a></li> - -<li><a href="/rules/lib/builtins/ExecTransitionFactory">ExecTransitionFactory</a></li> - -<li><a href="/rules/lib/builtins/ExpandedDirectory">ExpandedDirectory</a></li> - -<li><a href="/rules/lib/builtins/extension_metadata">extension_metadata</a></li> - -<li><a href="/rules/lib/builtins/FeatureConfiguration">FeatureConfiguration</a></li> - -<li><a href="/rules/lib/builtins/File">File</a></li> - -<li><a href="/rules/lib/builtins/fragments">fragments</a></li> - -<li><a href="/rules/lib/builtins/java_annotation_processing">java_annotation_processing</a></li> - -<li><a href="/rules/lib/builtins/Label">Label</a></li> - -<li><a href="/rules/lib/builtins/LateBoundDefault">LateBoundDefault</a></li> - -<li><a href="/rules/lib/builtins/LibraryToLink">LibraryToLink</a></li> - -<li><a href="/rules/lib/builtins/License">License</a></li> - -<li><a href="/rules/lib/builtins/LinkerInput">LinkerInput</a></li> - -<li><a href="/rules/lib/builtins/LinkingContext">LinkingContext</a></li> - -<li><a href="/rules/lib/builtins/macro">macro</a></li> - -<li><a href="/rules/lib/builtins/mapped_root">mapped_root</a></li> - -<li><a href="/rules/lib/builtins/module_ctx">module_ctx</a></li> - -<li><a href="/rules/lib/builtins/path">path</a></li> - -<li><a href="/rules/lib/builtins/propagation_ctx">propagation_ctx</a></li> - -<li><a href="/rules/lib/builtins/Provider">Provider</a></li> - -<li><a href="/rules/lib/builtins/repo_metadata">repo_metadata</a></li> - -<li><a href="/rules/lib/builtins/repository_ctx">repository_ctx</a></li> - -<li><a href="/rules/lib/builtins/repository_os">repository_os</a></li> - -<li><a href="/rules/lib/builtins/repository_rule">repository_rule</a></li> - -<li><a href="/rules/lib/builtins/root">root</a></li> - -<li><a href="/rules/lib/builtins/rule">rule</a></li> - -<li><a href="/rules/lib/builtins/rule_attributes">rule_attributes</a></li> - -<li><a href="/rules/lib/builtins/runfiles">runfiles</a></li> - -<li><a href="/rules/lib/builtins/struct">struct</a></li> - -<li><a href="/rules/lib/builtins/Subrule">Subrule</a></li> - -<li><a href="/rules/lib/builtins/subrule_ctx">subrule_ctx</a></li> - -<li><a href="/rules/lib/builtins/SymlinkEntry">SymlinkEntry</a></li> - -<li><a href="/rules/lib/builtins/tag_class">tag_class</a></li> - -<li><a href="/rules/lib/builtins/Target">Target</a></li> - -<li><a href="/rules/lib/builtins/template_ctx">template_ctx</a></li> - -<li><a href="/rules/lib/builtins/TemplateDict">TemplateDict</a></li> - -<li><a href="/rules/lib/builtins/toolchain_type">toolchain_type</a></li> - -<li><a href="/rules/lib/builtins/ToolchainContext">ToolchainContext</a></li> - -<li><a href="/rules/lib/builtins/transition">transition</a></li> - -<li><a href="/rules/lib/builtins/wasm_exec_result">wasm_exec_result</a></li> - -<li><a href="/rules/lib/builtins/wasm_module">wasm_module</a></li> -</ul> -</body> -</html> +- [Action](/rules/lib/builtins/Action) +- [actions](/rules/lib/builtins/actions) +- [apple_platform](/rules/lib/builtins/apple_platform) +- [Args](/rules/lib/builtins/Args) +- [Aspect](/rules/lib/builtins/Aspect) +- [Attribute](/rules/lib/builtins/Attribute) +- [bazel_module](/rules/lib/builtins/bazel_module) +- [bazel_module_tags](/rules/lib/builtins/bazel_module_tags) +- [BuildSetting](/rules/lib/builtins/BuildSetting) +- [CcCompilationOutputs](/rules/lib/builtins/CcCompilationOutputs) +- [CcLinkingOutputs](/rules/lib/builtins/CcLinkingOutputs) +- [CompilationContext](/rules/lib/builtins/CompilationContext) +- [configuration](/rules/lib/builtins/configuration) +- [ctx](/rules/lib/builtins/ctx) +- [depset](/rules/lib/builtins/depset) +- [DirectoryExpander](/rules/lib/builtins/DirectoryExpander) +- [DottedVersion](/rules/lib/builtins/DottedVersion) +- [exec_result](/rules/lib/builtins/exec_result) +- [ExecGroupCollection](/rules/lib/builtins/ExecGroupCollection) +- [ExecGroupContext](/rules/lib/builtins/ExecGroupContext) +- [ExecTransitionFactory](/rules/lib/builtins/ExecTransitionFactory) +- [ExpandedDirectory](/rules/lib/builtins/ExpandedDirectory) +- [extension_metadata](/rules/lib/builtins/extension_metadata) +- [FeatureConfiguration](/rules/lib/builtins/FeatureConfiguration) +- [File](/rules/lib/builtins/File) +- [fragments](/rules/lib/builtins/fragments) +- [java_annotation_processing](/rules/lib/builtins/java_annotation_processing) +- [Label](/rules/lib/builtins/Label) +- [LateBoundDefault](/rules/lib/builtins/LateBoundDefault) +- [LibraryToLink](/rules/lib/builtins/LibraryToLink) +- [License](/rules/lib/builtins/License) +- [LinkerInput](/rules/lib/builtins/LinkerInput) +- [LinkingContext](/rules/lib/builtins/LinkingContext) +- [macro](/rules/lib/builtins/macro) +- [mapped_root](/rules/lib/builtins/mapped_root) +- [module_ctx](/rules/lib/builtins/module_ctx) +- [path](/rules/lib/builtins/path) +- [propagation_ctx](/rules/lib/builtins/propagation_ctx) +- [Provider](/rules/lib/builtins/Provider) +- [repo_metadata](/rules/lib/builtins/repo_metadata) +- [repository_ctx](/rules/lib/builtins/repository_ctx) +- [repository_os](/rules/lib/builtins/repository_os) +- [repository_rule](/rules/lib/builtins/repository_rule) +- [root](/rules/lib/builtins/root) +- [rule](/rules/lib/builtins/rule) +- [rule_attributes](/rules/lib/builtins/rule_attributes) +- [runfiles](/rules/lib/builtins/runfiles) +- [struct](/rules/lib/builtins/struct) +- [Subrule](/rules/lib/builtins/Subrule) +- [subrule_ctx](/rules/lib/builtins/subrule_ctx) +- [SymlinkEntry](/rules/lib/builtins/SymlinkEntry) +- [tag_class](/rules/lib/builtins/tag_class) +- [Target](/rules/lib/builtins/Target) +- [template_ctx](/rules/lib/builtins/template_ctx) +- [TemplateDict](/rules/lib/builtins/TemplateDict) +- [toolchain_type](/rules/lib/builtins/toolchain_type) +- [ToolchainContext](/rules/lib/builtins/ToolchainContext) +- [transition](/rules/lib/builtins/transition) +- [wasm_exec_result](/rules/lib/builtins/wasm_exec_result) +- [wasm_module](/rules/lib/builtins/wasm_module) diff --git a/rules/lib/builtins/Action.mdx b/rules/lib/builtins/Action.mdx index 9683390..606546f 100644 --- a/rules/lib/builtins/Action.mdx +++ b/rules/lib/builtins/Action.mdx @@ -2,95 +2,93 @@ title: 'Action' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.Action">Action</h1> +# Action {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +An action created during rule analysis. + +This object is visible for the purpose of testing, and may be obtained from an `Actions` provider. It is normally not necessary to access `Action` objects or their fields within a rule's implementation function. You may instead want to see the [Rules page](https://bazel.build/extending/rules#actions) for a general discussion of how to use actions when defining custom rules, or the [API reference](../builtins/actions.html) for creating actions. + +Some fields of this object are only applicable for certain kinds of actions. Fields that are inapplicable are set to `None`. + +## Members + +- [args](#args) +- [argv](#argv) +- [content](#content) +- [env](#env) +- [inputs](#inputs) +- [mnemonic](#mnemonic) +- [outputs](#outputs) +- [substitutions](#substitutions) + +## args + +``` rule-signature +sequence Action.args +``` + +A list of frozen [Args](../builtins/Args.html) objects containing information about the action arguments. These objects contain accurate argument information, including arguments involving expanded action output directories. However, [Args](../builtins/Args.html) objects are not readable in the analysis phase. For a less accurate account of arguments which is available in the analysis phase, see [argv](#argv). + +Note that some types of actions do not yet support exposure of this field. For such action types, this is `None`. +May return `None`. -An action created during rule analysis.<p>This object is visible for the purpose of testing, and may be obtained from an <code>Actions</code> provider. It is normally not necessary to access <code>Action</code> objects or their fields within a rule's implementation function. You may instead want to see the <a href='https://bazel.build/extending/rules#actions'>Rules page</a> for a general discussion of how to use actions when defining custom rules, or the <a href='../builtins/actions.html'>API reference</a> for creating actions.<p>Some fields of this object are only applicable for certain kinds of actions. Fields that are inapplicable are set to <code>None</code>. +## argv -<h2>Members</h2> -<ul> - <li> - <a href="#args">args</a> - </li> - <li> - <a href="#argv">argv</a> - </li> - <li> - <a href="#content">content</a> - </li> - <li> - <a href="#env">env</a> - </li> - <li> - <a href="#inputs">inputs</a> - </li> - <li> - <a href="#mnemonic">mnemonic</a> - </li> - <li> - <a href="#outputs">outputs</a> - </li> - <li> - <a href="#substitutions">substitutions</a> - </li> - </ul> +``` rule-signature +sequence Action.argv +``` - <h2 id="args">args</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> Action.args</pre></p> +For actions created by [ctx.actions.run()](../builtins/actions.html#run) or [ctx.actions.run_shell()](../builtins/actions.html#run_shell) an immutable list of the arguments for the command line to be executed. Note that for shell actions the first two arguments will be the shell path and `"-c"`. +May return `None`. - A list of frozen <a href="../builtins/Args.html">Args</a> objects containing information about the action arguments. These objects contain accurate argument information, including arguments involving expanded action output directories. However, <a href="../builtins/Args.html">Args</a> objects are not readable in the analysis phase. For a less accurate account of arguments which is available in the analysis phase, see <a href="#argv">argv</a>. <p>Note that some types of actions do not yet support exposure of this field. For such action types, this is <code>None</code>. - May return <code>None</code>. +## content - <h2 id="argv">argv</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> Action.argv</pre></p> +``` rule-signature +string Action.content +``` - For actions created by <a href="../builtins/actions.html#run">ctx.actions.run()</a> or <a href="../builtins/actions.html#run_shell">ctx.actions.run_shell()</a> an immutable list of the arguments for the command line to be executed. Note that for shell actions the first two arguments will be the shell path and <code>"-c"</code>. - May return <code>None</code>. +For actions created by [ctx.actions.write()](../builtins/actions.html#write) or [ctx.actions.expand_template()](../builtins/actions.html#expand_template), the contents of the file to be written, if those contents can be computed during the analysis phase. The value is `None` if the contents cannot be determined until the execution phase, such as when a directory in an [Args](../builtins/Args.html) object needs to be expanded. +May return `None`. - <h2 id="content">content</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Action.content</pre></p> +## env - For actions created by <a href="../builtins/actions.html#write">ctx.actions.write()</a> or <a href="../builtins/actions.html#expand_template">ctx.actions.expand_template()</a>, the contents of the file to be written, if those contents can be computed during the analysis phase. The value is <code>None</code> if the contents cannot be determined until the execution phase, such as when a directory in an <a href="../builtins/Args.html">Args</a> object needs to be expanded. - May return <code>None</code>. +``` rule-signature +dict Action.env +``` - <h2 id="env">env</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> Action.env</pre></p> +The 'fixed' environment variables for this action. This includes only environment settings which are explicitly set by the action definition, and thus omits settings which are only pre-set in the execution environment. - The 'fixed' environment variables for this action. This includes only environment settings which are explicitly set by the action definition, and thus omits settings which are only pre-set in the execution environment. +## inputs - <h2 id="inputs">inputs</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> Action.inputs</pre></p> +``` rule-signature +depset Action.inputs +``` - A set of the input files of this action. +A set of the input files of this action. - <h2 id="mnemonic">mnemonic</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Action.mnemonic</pre></p> +## mnemonic - The mnemonic for this action. +``` rule-signature +string Action.mnemonic +``` - <h2 id="outputs">outputs</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> Action.outputs</pre></p> +The mnemonic for this action. - A set of the output files of this action. +## outputs - <h2 id="substitutions">substitutions</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> Action.substitutions</pre></p> +``` rule-signature +depset Action.outputs +``` - For actions created by <a href="../builtins/actions.html#expand_template">ctx.actions.expand_template()</a>, an immutable dict holding the substitution mapping. - May return <code>None</code>. +A set of the output files of this action. +## substitutions -</body> -</html> +``` rule-signature +dict Action.substitutions +``` -<!-- {% endraw %} --> +For actions created by [ctx.actions.expand_template()](../builtins/actions.html#expand_template), an immutable dict holding the substitution mapping. +May return `None`. diff --git a/rules/lib/builtins/Args.mdx b/rules/lib/builtins/Args.mdx index 452f141..9157f4a 100644 --- a/rules/lib/builtins/Args.mdx +++ b/rules/lib/builtins/Args.mdx @@ -2,22 +2,40 @@ title: 'Args' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.Args">Args</h1> +# Args {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +An object that encapsulates, in a memory-efficient way, the data needed to build part or all of a command line. + +It often happens that an action requires a large command line containing values accumulated from transitive dependencies. For example, a linker command line might list every object file needed by all of the libraries being linked. It is best practice to store such transitive data in [`depset`](../builtins/depset.html)s, so that they can be shared by multiple targets. However, if the rule author had to convert these depsets into lists of strings in order to construct an action command line, it would defeat this memory-sharing optimization. + +For this reason, the action-constructing functions accept `Args` objects in addition to strings. Each `Args` object represents a concatenation of strings and depsets, with optional transformations for manipulating the data. `Args` objects do not process the depsets they encapsulate until the execution phase, when it comes time to calculate the command line. This helps defer any expensive copying until after the analysis phase is complete. See the [Optimizing Performance](https://bazel.build/rules/performance) page for more information. + +`Args` are constructed by calling [`ctx.actions.args()`](../builtins/actions.html#args). They can be passed as the `arguments` parameter of [`ctx.actions.run()`](../builtins/actions.html#run) or [`ctx.actions.run_shell()`](../builtins/actions.html#run_shell). Each mutation of an `Args` object appends values to the eventual command line. + +The `map_each` feature allows you to customize how items are transformed into strings. If you do not provide a `map_each` function, the standard conversion is as follows: + +- Values that are already strings are left as-is. +- [`File`](../builtins/File.html) objects are turned into their `File.path` values. +- [`Label`](../builtins/Label.html) objects are turned into a string representation that resolves back to the same object when resolved in the context of the main repository. If possible, the string representation uses the apparent name of a repository in favor of the repository's canonical name, which makes this representation suited for use in BUILD files. While the exact form of the representation is not guaranteed, typical examples are `//foo:bar`, `@repo//foo:bar` and `@@canonical_name+//foo:bar.bzl`. +- All other types are turned into strings in an *unspecified* manner. For this reason, you should avoid passing values that are not of string or `File` type to `add()`, and if you pass them to `add_all()` or `add_joined()` then you should provide a `map_each` function. + +When using string formatting (`format`, `format_each`, and `format_joined` params of the `add*()` methods), the format template is interpreted in the same way as `%`-substitution on strings, except that the template must have exactly one substitution placeholder and it must be `%s`. Literal percents may be escaped as `%%`. Formatting is applied after the value is converted to a string as per the above. + +Each of the `add*()` methods have an alternate form that accepts an extra positional parameter, an "arg name" string to insert before the rest of the arguments. For `add_all` and `add_joined` the extra string will not be added if the sequence turns out to be empty. For instance, the same usage can add either `--foo val1 val2 val3 --bar` or just `--bar` to the command line, depending on whether the given sequence contains `val1..val3` or is empty. + +If the size of the command line can grow longer than the maximum size allowed by the system, the arguments can be spilled over into parameter files. See [`use_param_file()`](#use_param_file) and [`set_param_file_format()`](#set_param_file_format). + +Example: Suppose we wanted to generate the command line: + + + --foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz + +We could use the following `Args` object: + +``` python -An object that encapsulates, in a memory-efficient way, the data needed to build part or all of a command line.<p>It often happens that an action requires a large command line containing values accumulated from transitive dependencies. For example, a linker command line might list every object file needed by all of the libraries being linked. It is best practice to store such transitive data in <a href='../builtins/depset.html'><code>depset</code></a>s, so that they can be shared by multiple targets. However, if the rule author had to convert these depsets into lists of strings in order to construct an action command line, it would defeat this memory-sharing optimization.<p>For this reason, the action-constructing functions accept <code>Args</code> objects in addition to strings. Each <code>Args</code> object represents a concatenation of strings and depsets, with optional transformations for manipulating the data. <code>Args</code> objects do not process the depsets they encapsulate until the execution phase, when it comes time to calculate the command line. This helps defer any expensive copying until after the analysis phase is complete. See the <a href='https://bazel.build/rules/performance'>Optimizing Performance</a> page for more information.<p><code>Args</code> are constructed by calling <a href='../builtins/actions.html#args'><code>ctx.actions.args()</code></a>. They can be passed as the <code>arguments</code> parameter of <a href='../builtins/actions.html#run'><code>ctx.actions.run()</code></a> or <a href='../builtins/actions.html#run_shell'><code>ctx.actions.run_shell()</code></a>. Each mutation of an <code>Args</code> object appends values to the eventual command line.<p>The <code>map_each</code> feature allows you to customize how items are transformed into strings. If you do not provide a <code>map_each</code> function, the standard conversion is as follows: <ul><li>Values that are already strings are left as-is.<li><a href='../builtins/File.html'><code>File</code></a> objects are turned into their <code>File.path</code> values.<li><a href='../builtins/Label.html'><code>Label</code></a> objects are turned into a string representation that resolves back to the same object when resolved in the context of the main repository. If possible, the string representation uses the apparent name of a repository in favor of the repository's canonical name, which makes this representation suited for use in BUILD files. While the exact form of the representation is not guaranteed, typical examples are <code>//foo:bar</code>, <code>@repo//foo:bar</code> and <code>@@canonical_name+//foo:bar.bzl</code>.<li>All other types are turned into strings in an <i>unspecified</i> manner. For this reason, you should avoid passing values that are not of string or <code>File</code> type to <code>add()</code>, and if you pass them to <code>add_all()</code> or <code>add_joined()</code> then you should provide a <code>map_each</code> function.</ul><p>When using string formatting (<code>format</code>, <code>format_each</code>, and <code>format_joined</code> params of the <code>add*()</code> methods), the format template is interpreted in the same way as <code>%</code>-substitution on strings, except that the template must have exactly one substitution placeholder and it must be <code>%s</code>. Literal percents may be escaped as <code>%%</code>. Formatting is applied after the value is converted to a string as per the above.<p>Each of the <code>add*()</code> methods have an alternate form that accepts an extra positional parameter, an "arg name" string to insert before the rest of the arguments. For <code>add_all</code> and <code>add_joined</code> the extra string will not be added if the sequence turns out to be empty. For instance, the same usage can add either <code>--foo val1 val2 val3 --bar</code> or just <code>--bar</code> to the command line, depending on whether the given sequence contains <code>val1..val3</code> or is empty.<p>If the size of the command line can grow longer than the maximum size allowed by the system, the arguments can be spilled over into parameter files. See <a href='#use_param_file'><code>use_param_file()</code></a> and <a href='#set_param_file_format'><code>set_param_file_format()</code></a>.<p>Example: Suppose we wanted to generate the command line: <pre> ---foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz -</pre>We could use the following <code>Args</code> object: <pre class=language-python> # foo_deps and bar_deps are depsets containing # File objects for the foo and bar .txt files. args = ctx.actions.args() @@ -29,395 +47,304 @@ ctx.actions.run( arguments = [args], ... ) -</pre> +``` + +## Members + +- [add](#add) +- [add_all](#add_all) +- [add_joined](#add_joined) +- [set_param_file_format](#set_param_file_format) +- [use_param_file](#use_param_file) + +## add + +``` rule-signature +Args Args.add(arg_name_or_value, value=unbound, *, format=None) +``` + +Appends an argument to this command line. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="add.arg_name_or_value"><code>arg_name_or_value</code></td> +<td>required<br /> +If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the value without any processing. If only one positional parameter is passed, it is interpreted as <code>value</code> (see below).</td> +</tr> +<tr> +<td id="add.value"><code>value</code></td> +<td>default is <code>unbound</code><br /> +The object to append. It will be converted to a string using the standard conversion mentioned above. Since there is no <code>map_each</code> parameter for this function, <code>value</code> should be either a string or a <code>File</code>. A list, tuple, depset, or directory <code>File</code> must be passed to <a href="#add_all"><code>add_all()</code> or</a> <a href="#add_joined"><code>add_joined()</code></a> instead of this method.</td> +</tr> +<tr> +<td id="add.format"><code>format</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A format string pattern, to be applied to the stringified version of <code>value</code>.</td> +</tr> +</tbody> +</table> + +## add_all + +``` rule-signature +Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False) +``` + +Appends multiple arguments to this command line. The items are processed lazily during the execution phase. -<h2>Members</h2> +Most of the processing occurs over a list of arguments to be appended, as per the following steps: + +1. Each directory `File` item is replaced by all `File`s recursively contained in that directory. +2. If `map_each` is given, it is applied to each item, and the resulting lists of strings are concatenated to form the initial argument list. Otherwise, the initial argument list is the result of applying the standard conversion to each item. +3. Each argument in the list is formatted with `format_each`, if present. +4. If `uniquify` is true, duplicate arguments are removed. The first occurrence is the one that remains. +5. If a `before_each` string is given, it is inserted as a new argument before each existing argument in the list. This effectively doubles the number of arguments to be appended by this point. +6. Except in the case that the list is empty and `omit_if_empty` is true (the default), the arg name and `terminate_with` are inserted as the first and last arguments, respectively, if they are given. + +Note that empty strings are valid arguments that are subject to all these processing steps. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="add_all.arg_name_or_values"><code>arg_name_or_values</code></td> +<td>required<br /> +If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the <code>values</code> as a separate argument without any processing. This arg name will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below).</td> +</tr> +<tr> +<td id="add_all.values"><code>values</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>unbound</code><br /> +The list, tuple, or depset whose items will be appended.</td> +</tr> +<tr> +<td id="add_all.map_each"><code>map_each</code></td> +<td>callable; or <code>None</code>; +default is <code>None</code><br /> +A function that converts each item to zero or more strings, which may be further processed before appending. If this param is not provided, the standard conversion is used. +<p>The function is passed either one or two positional arguments: the item to convert, followed by an optional <a href="../builtins/DirectoryExpander.html"><code>DirectoryExpander</code></a>. The second argument will be passed only if the supplied function is user-defined (not built-in) and declares more than one parameter.</p> +<p>The return value's type depends on how many arguments are to be produced for the item:</p> <ul> - <li> - <a href="#add">add</a> - </li> - <li> - <a href="#add_all">add_all</a> - </li> - <li> - <a href="#add_joined">add_joined</a> - </li> - <li> - <a href="#set_param_file_format">set_param_file_format</a> - </li> - <li> - <a href="#use_param_file">use_param_file</a> - </li> - </ul> - - <h2 id="add">add</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.add(arg_name_or_value, value=unbound, *, format=None)</pre></p> - - Appends an argument to this command line. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="add.arg_name_or_value"> - <code>arg_name_or_value</code> - </td> - <td> - required<br/> - If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the value without any processing. If only one positional parameter is passed, it is interpreted as <code>value</code> (see below). - </td> - </tr> - <tr> - <td id="add.value"> - <code>value</code> - </td> - <td> - default is <code>unbound</code><br/> - The object to append. It will be converted to a string using the standard conversion mentioned above. Since there is no <code>map_each</code> parameter for this function, <code>value</code> should be either a string or a <code>File</code>. A list, tuple, depset, or directory <code>File</code> must be passed to <a href='#add_all'><code>add_all()</code> or <a href='#add_joined'><code>add_joined()</code></a> instead of this method. - </td> - </tr> - <tr> - <td id="add.format"> - <code>format</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A format string pattern, to be applied to the stringified version of <code>value</code>. - </td> - </tr> - </tbody> - </table> - - <h2 id="add_all">add_all</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)</pre></p> - - Appends multiple arguments to this command line. The items are processed lazily during the execution phase.<p>Most of the processing occurs over a list of arguments to be appended, as per the following steps:<ol><li>Each directory <code>File</code> item is replaced by all <code>File</code>s recursively contained in that directory.</li><li>If <code>map_each</code> is given, it is applied to each item, and the resulting lists of strings are concatenated to form the initial argument list. Otherwise, the initial argument list is the result of applying the standard conversion to each item.<li>Each argument in the list is formatted with <code>format_each</code>, if present.<li>If <code>uniquify</code> is true, duplicate arguments are removed. The first occurrence is the one that remains.<li>If a <code>before_each</code> string is given, it is inserted as a new argument before each existing argument in the list. This effectively doubles the number of arguments to be appended by this point.<li>Except in the case that the list is empty and <code>omit_if_empty</code> is true (the default), the arg name and <code>terminate_with</code> are inserted as the first and last arguments, respectively, if they are given.</ol>Note that empty strings are valid arguments that are subject to all these processing steps. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="add_all.arg_name_or_values"> - <code>arg_name_or_values</code> - </td> - <td> - required<br/> - If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the <code>values</code> as a separate argument without any processing. This arg name will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below). - </td> - </tr> - <tr> - <td id="add_all.values"> - <code>values</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>unbound</code><br/> - The list, tuple, or depset whose items will be appended. - </td> - </tr> - <tr> - <td id="add_all.map_each"> - <code>map_each</code> - </td> - <td> - callable; or <code>None</code>; - default is <code>None</code><br/> - A function that converts each item to zero or more strings, which may be further processed before appending. If this param is not provided, the standard conversion is used.<p>The function is passed either one or two positional arguments: the item to convert, followed by an optional <a href='../builtins/DirectoryExpander.html'><code>DirectoryExpander</code></a>. The second argument will be passed only if the supplied function is user-defined (not built-in) and declares more than one parameter.<p>The return value's type depends on how many arguments are to be produced for the item:<ul><li>In the common case when each item turns into one string, the function should return that string.<li>If the item is to be filtered out entirely, the function should return <code>None</code>.<li>If the item turns into multiple strings, the function returns a list of those strings.</ul>Returning a single string or <code>None</code> has the same effect as returning a list of length 1 or length 0 respectively. However, it is more efficient and readable to avoid creating a list where it is not needed.<p>Ordinarily, items that are directories are automatically expanded to their contents when <code>expand_directories=True</code> is set. However, this will not expand directories contained inside other values -- for instance, when the items are structs that have directories as fields. In this situation, the <code>DirectoryExpander</code> argument can be applied to manually obtain the files of a given directory.<p>To avoid unintended retention of large analysis-phase data structures into the execution phase, the <code>map_each</code> function must be declared by a top-level <code>def</code> statement; it may not be a nested function closure by default.<p><i>Warning:</i> <a href='../globals/all.html#print'><code>print()</code></a> statements that are executed during the call to <code>map_each</code> will not produce any visible output. - </td> - </tr> - <tr> - <td id="add_all.format_each"> - <code>format_each</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - An optional format string pattern, applied to each string returned by the <code>map_each</code> function. The format string must have exactly one '%s' placeholder. - </td> - </tr> - <tr> - <td id="add_all.before_each"> - <code>before_each</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - An optional argument to append before each argument derived from <code>values</code> is appended. - </td> - </tr> - <tr> - <td id="add_all.omit_if_empty"> - <code>omit_if_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - If true, if there are no arguments derived from <code>values</code> to be appended, then all further processing is suppressed and the command line will be unchanged. If false, the arg name and <code>terminate_with</code>, if provided, will still be appended regardless of whether or not there are other arguments. - </td> - </tr> - <tr> - <td id="add_all.uniquify"> - <code>uniquify</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, duplicate arguments that are derived from <code>values</code> will be omitted. Only the first occurrence of each argument will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items. - </td> - </tr> - <tr> - <td id="add_all.expand_directories"> - <code>expand_directories</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - If true, any directories in <code>values</code> will be expanded to a flat list of files. This happens before <code>map_each</code> is applied. - </td> - </tr> - <tr> - <td id="add_all.terminate_with"> - <code>terminate_with</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - An optional argument to append after all other arguments. This argument will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered). - </td> - </tr> - <tr> - <td id="add_all.allow_closure"> - <code>allow_closure</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. - </td> - </tr> - </tbody> - </table> - - <h2 id="add_joined">add_joined</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)</pre></p> - - Appends an argument to this command line by concatenating together multiple values using a separator. The items are processed lazily during the execution phase.<p>Processing is similar to <a href='#add_all'><code>add_all()</code></a>, but the list of arguments derived from <code>values</code> is combined into a single argument as if by <code>join_with.join(...)</code>, and then formatted using the given <code>format_joined</code> string template. Unlike <code>add_all()</code>, there is no <code>before_each</code> or <code>terminate_with</code> parameter since these are not generally useful when the items are combined into a single argument.<p>If after filtering there are no strings to join into an argument, and if <code>omit_if_empty</code> is true (the default), no processing is done. Otherwise if there are no strings to join but <code>omit_if_empty</code> is false, the joined string will be an empty string. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="add_joined.arg_name_or_values"> - <code>arg_name_or_values</code> - </td> - <td> - required<br/> - If two positional parameters are passed this is interpreted as the arg name. The arg name is added before <code>values</code> without any processing. This arg will not be added if <code>omit_if_empty</code> is true (the default) and there are no strings derived from <code>values</code> to join together (which can happen if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below). - </td> - </tr> - <tr> - <td id="add_joined.values"> - <code>values</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>unbound</code><br/> - The list, tuple, or depset whose items will be joined. - </td> - </tr> - <tr> - <td id="add_joined.join_with"> - <code>join_with</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A delimiter string used to join together the strings obtained from applying <code>map_each</code> and <code>format_each</code>, in the same manner as <a href='../core/string.html#join'><code>string.join()</code></a>. - </td> - </tr> - <tr> - <td id="add_joined.map_each"> - <code>map_each</code> - </td> - <td> - callable; or <code>None</code>; - default is <code>None</code><br/> - Same as for <a href='#add_all.map_each'><code>add_all</code></a>. - </td> - </tr> - <tr> - <td id="add_joined.format_each"> - <code>format_each</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Same as for <a href='#add_all.format_each'><code>add_all</code></a>. - </td> - </tr> - <tr> - <td id="add_joined.format_joined"> - <code>format_joined</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. - </td> - </tr> - <tr> - <td id="add_joined.omit_if_empty"> - <code>omit_if_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - If true, if there are no strings to join together (either because <code>values</code> is empty or all its items are filtered), then all further processing is suppressed and the command line will be unchanged. If false, then even if there are no strings to join together, two arguments will be appended: the arg name followed by an empty string (which is the logical join of zero strings). - </td> - </tr> - <tr> - <td id="add_joined.uniquify"> - <code>uniquify</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Same as for <a href='#add_all.uniquify'><code>add_all</code></a>. - </td> - </tr> - <tr> - <td id="add_joined.expand_directories"> - <code>expand_directories</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - Same as for <a href='#add_all.expand_directories'><code>add_all</code></a>. - </td> - </tr> - <tr> - <td id="add_joined.allow_closure"> - <code>allow_closure</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Same as for <a href='#add_all.allow_closure'><code>add_all</code></a>. - </td> - </tr> - </tbody> - </table> - - <h2 id="set_param_file_format">set_param_file_format</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.set_param_file_format(format)</pre></p> - - Sets the format of the param file, if one is used - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="set_param_file_format.format"> - <code>format</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Must be one of:<ul><li>"multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it.</li><li>"shell": Same as "multiline", but the items are shell-quoted</li><li>"flag_per_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library.</li></ul><p>The format defaults to "shell" if not called. - </td> - </tr> - </tbody> - </table> - - <h2 id="use_param_file">use_param_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> Args.use_param_file(param_file_arg, *, use_always=False)</pre></p> - - Spills the args to a params file, replacing them with a pointer to the param file. Use when your args may be too large for the system's command length limits.<p>Bazel may choose to elide writing the params file to the output tree during execution for efficiency. If you are debugging actions and want to inspect the param file, pass <code>--materialize_param_files</code> to your build. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="use_param_file.param_file_arg"> - <code>param_file_arg</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A format string with a single "%s". If the args are spilled to a params file then they are replaced with an argument consisting of this string formatted with the path of the params file.<p>For example, if the args are spilled to a params file "params.txt", then specifying "--file=%s" would cause the action command line to contain "--file=params.txt". - </td> - </tr> - <tr> - <td id="use_param_file.use_always"> - <code>use_always</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether to always spill the args to a params file. If false, bazel will decide whether the arguments need to be spilled based on your system and arg length. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +<li>In the common case when each item turns into one string, the function should return that string.</li> +<li>If the item is to be filtered out entirely, the function should return <code>None</code>.</li> +<li>If the item turns into multiple strings, the function returns a list of those strings.</li> +</ul> +Returning a single string or <code>None</code> has the same effect as returning a list of length 1 or length 0 respectively. However, it is more efficient and readable to avoid creating a list where it is not needed. +<p>Ordinarily, items that are directories are automatically expanded to their contents when <code>expand_directories=True</code> is set. However, this will not expand directories contained inside other values -- for instance, when the items are structs that have directories as fields. In this situation, the <code>DirectoryExpander</code> argument can be applied to manually obtain the files of a given directory.</p> +<p>To avoid unintended retention of large analysis-phase data structures into the execution phase, the <code>map_each</code> function must be declared by a top-level <code>def</code> statement; it may not be a nested function closure by default.</p> +<p><em>Warning:</em> <a href="../globals/all.html#print"><code>print()</code></a> statements that are executed during the call to <code>map_each</code> will not produce any visible output.</p></td> +</tr> +<tr> +<td id="add_all.format_each"><code>format_each</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +An optional format string pattern, applied to each string returned by the <code>map_each</code> function. The format string must have exactly one '%s' placeholder.</td> +</tr> +<tr> +<td id="add_all.before_each"><code>before_each</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +An optional argument to append before each argument derived from <code>values</code> is appended.</td> +</tr> +<tr> +<td id="add_all.omit_if_empty"><code>omit_if_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +If true, if there are no arguments derived from <code>values</code> to be appended, then all further processing is suppressed and the command line will be unchanged. If false, the arg name and <code>terminate_with</code>, if provided, will still be appended regardless of whether or not there are other arguments.</td> +</tr> +<tr> +<td id="add_all.uniquify"><code>uniquify</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, duplicate arguments that are derived from <code>values</code> will be omitted. Only the first occurrence of each argument will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items.</td> +</tr> +<tr> +<td id="add_all.expand_directories"><code>expand_directories</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +If true, any directories in <code>values</code> will be expanded to a flat list of files. This happens before <code>map_each</code> is applied.</td> +</tr> +<tr> +<td id="add_all.terminate_with"><code>terminate_with</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +An optional argument to append after all other arguments. This argument will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered).</td> +</tr> +<tr> +<td id="add_all.allow_closure"><code>allow_closure</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase.</td> +</tr> +</tbody> +</table> + +## add_joined + +``` rule-signature +Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False) +``` + +Appends an argument to this command line by concatenating together multiple values using a separator. The items are processed lazily during the execution phase. + +Processing is similar to [`add_all()`](#add_all), but the list of arguments derived from `values` is combined into a single argument as if by `join_with.join(...)`, and then formatted using the given `format_joined` string template. Unlike `add_all()`, there is no `before_each` or `terminate_with` parameter since these are not generally useful when the items are combined into a single argument. + +If after filtering there are no strings to join into an argument, and if `omit_if_empty` is true (the default), no processing is done. Otherwise if there are no strings to join but `omit_if_empty` is false, the joined string will be an empty string. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="add_joined.arg_name_or_values"><code>arg_name_or_values</code></td> +<td>required<br /> +If two positional parameters are passed this is interpreted as the arg name. The arg name is added before <code>values</code> without any processing. This arg will not be added if <code>omit_if_empty</code> is true (the default) and there are no strings derived from <code>values</code> to join together (which can happen if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below).</td> +</tr> +<tr> +<td id="add_joined.values"><code>values</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>unbound</code><br /> +The list, tuple, or depset whose items will be joined.</td> +</tr> +<tr> +<td id="add_joined.join_with"><code>join_with</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A delimiter string used to join together the strings obtained from applying <code>map_each</code> and <code>format_each</code>, in the same manner as <a href="../core/string.html#join"><code>string.join()</code></a>.</td> +</tr> +<tr> +<td id="add_joined.map_each"><code>map_each</code></td> +<td>callable; or <code>None</code>; +default is <code>None</code><br /> +Same as for <a href="#add_all.map_each"><code>add_all</code></a>.</td> +</tr> +<tr> +<td id="add_joined.format_each"><code>format_each</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Same as for <a href="#add_all.format_each"><code>add_all</code></a>.</td> +</tr> +<tr> +<td id="add_joined.format_joined"><code>format_joined</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder.</td> +</tr> +<tr> +<td id="add_joined.omit_if_empty"><code>omit_if_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +If true, if there are no strings to join together (either because <code>values</code> is empty or all its items are filtered), then all further processing is suppressed and the command line will be unchanged. If false, then even if there are no strings to join together, two arguments will be appended: the arg name followed by an empty string (which is the logical join of zero strings).</td> +</tr> +<tr> +<td id="add_joined.uniquify"><code>uniquify</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Same as for <a href="#add_all.uniquify"><code>add_all</code></a>.</td> +</tr> +<tr> +<td id="add_joined.expand_directories"><code>expand_directories</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +Same as for <a href="#add_all.expand_directories"><code>add_all</code></a>.</td> +</tr> +<tr> +<td id="add_joined.allow_closure"><code>allow_closure</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Same as for <a href="#add_all.allow_closure"><code>add_all</code></a>.</td> +</tr> +</tbody> +</table> + +## set_param_file_format + +``` rule-signature +Args Args.set_param_file_format(format) +``` + +Sets the format of the param file, if one is used + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="set_param_file_format.format"><code>format</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Must be one of: +<ul> +<li>"multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it.</li> +<li>"shell": Same as "multiline", but the items are shell-quoted</li> +<li>"flag_per_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library.</li> +</ul> +<p>The format defaults to "shell" if not called.</p></td> +</tr> +</tbody> +</table> + +## use_param_file + +``` rule-signature +Args Args.use_param_file(param_file_arg, *, use_always=False) +``` + +Spills the args to a params file, replacing them with a pointer to the param file. Use when your args may be too large for the system's command length limits. + +Bazel may choose to elide writing the params file to the output tree during execution for efficiency. If you are debugging actions and want to inspect the param file, pass `--materialize_param_files` to your build. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="use_param_file.param_file_arg"><code>param_file_arg</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A format string with a single "%s". If the args are spilled to a params file then they are replaced with an argument consisting of this string formatted with the path of the params file. +<p>For example, if the args are spilled to a params file "params.txt", then specifying "--file=%s" would cause the action command line to contain "--file=params.txt".</p></td> +</tr> +<tr> +<td id="use_param_file.use_always"><code>use_always</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether to always spill the args to a params file. If false, bazel will decide whether the arguments need to be spilled based on your system and arg length.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/builtins/Aspect.mdx b/rules/lib/builtins/Aspect.mdx index 84fc178..6fbc509 100644 --- a/rules/lib/builtins/Aspect.mdx +++ b/rules/lib/builtins/Aspect.mdx @@ -2,26 +2,9 @@ title: 'Aspect' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.Aspect">Aspect</h1> +# Aspect {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} For more information about Aspects, please consult the -<a href="../globals/bzl.html#aspect">documentation of the aspect function</a> or the <a href="https://bazel.build/extending/aspects">introduction to Aspects</a>. - - - - -</body> -</html> - -<!-- {% endraw %} --> +[documentation of the aspect function](../globals/bzl.html#aspect) or the [introduction to Aspects](https://bazel.build/extending/aspects). diff --git a/rules/lib/builtins/Attribute.mdx b/rules/lib/builtins/Attribute.mdx index f1bfab9..cfb9b15 100644 --- a/rules/lib/builtins/Attribute.mdx +++ b/rules/lib/builtins/Attribute.mdx @@ -2,24 +2,8 @@ title: 'Attribute' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.Attribute">Attribute</h1> +# Attribute {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Representation of a definition of an attribute. Use the <a href="../toplevel/attr.html">attr</a> module to create an Attribute. They are only for use with a <a href="../globals/bzl.html#rule">rule</a> or an <a href="../globals/bzl.html#aspect">aspect</a>. - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +Representation of a definition of an attribute. Use the [attr](../toplevel/attr.html) module to create an Attribute. They are only for use with a [rule](../globals/bzl.html#rule) or an [aspect](../globals/bzl.html#aspect). diff --git a/rules/lib/builtins/BuildSetting.mdx b/rules/lib/builtins/BuildSetting.mdx index d9f72b4..11be963 100644 --- a/rules/lib/builtins/BuildSetting.mdx +++ b/rules/lib/builtins/BuildSetting.mdx @@ -2,24 +2,8 @@ title: 'BuildSetting' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.BuildSetting">BuildSetting</h1> +# BuildSetting {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} The descriptor for a single piece of configuration information. If configuration is a key-value map of settings like {'cpu': 'ppc', 'copt': '-DFoo'}, this describes a single entry in that map. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/builtins/CcCompilationOutputs.mdx b/rules/lib/builtins/CcCompilationOutputs.mdx index 0208207..e291103 100644 --- a/rules/lib/builtins/CcCompilationOutputs.mdx +++ b/rules/lib/builtins/CcCompilationOutputs.mdx @@ -2,43 +2,29 @@ title: 'CcCompilationOutputs' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.CcCompilationOutputs">CcCompilationOutputs</h1> +# CcCompilationOutputs {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationOutputsApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Helper class containing CC compilation outputs. -<h2>Members</h2> -<ul> - <li> - <a href="#objects">objects</a> - </li> - <li> - <a href="#pic_objects">pic_objects</a> - </li> - </ul> +## Members - <h2 id="objects">objects</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> CcCompilationOutputs.objects</pre></p> +- [objects](#objects) +- [pic_objects](#pic_objects) - Non-PIC object files. +## objects - <h2 id="pic_objects">pic_objects</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> CcCompilationOutputs.pic_objects</pre></p> +``` rule-signature +sequence CcCompilationOutputs.objects +``` - PIC object files. +Non-PIC object files. +## pic_objects -</body> -</html> +``` rule-signature +sequence CcCompilationOutputs.pic_objects +``` -<!-- {% endraw %} --> +PIC object files. diff --git a/rules/lib/builtins/CcLinkingOutputs.mdx b/rules/lib/builtins/CcLinkingOutputs.mdx index 55d6e98..975708f 100644 --- a/rules/lib/builtins/CcLinkingOutputs.mdx +++ b/rules/lib/builtins/CcLinkingOutputs.mdx @@ -2,45 +2,31 @@ title: 'CcLinkingOutputs' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.CcLinkingOutputs">CcLinkingOutputs</h1> +# CcLinkingOutputs {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Helper class containing CC compilation outputs. -<h2>Members</h2> -<ul> - <li> - <a href="#executable">executable</a> - </li> - <li> - <a href="#library_to_link">library_to_link</a> - </li> - </ul> +## Members - <h2 id="executable">executable</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> CcLinkingOutputs.executable</pre></p> +- [executable](#executable) +- [library_to_link](#library_to_link) - Represents the linked executable. - May return <code>None</code>. +## executable - <h2 id="library_to_link">library_to_link</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/LibraryToLink.html">LibraryToLink</a> CcLinkingOutputs.library_to_link</pre></p> +``` rule-signature +File CcLinkingOutputs.executable +``` - <code>LibraryToLink</code> for including these outputs in further linking. - May return <code>None</code>. +Represents the linked executable. +May return `None`. +## library_to_link -</body> -</html> +``` rule-signature +LibraryToLink CcLinkingOutputs.library_to_link +``` -<!-- {% endraw %} --> +`LibraryToLink` for including these outputs in further linking. +May return `None`. diff --git a/rules/lib/builtins/CompilationContext.mdx b/rules/lib/builtins/CompilationContext.mdx index 1b3bbfe..27c5f88 100644 --- a/rules/lib/builtins/CompilationContext.mdx +++ b/rules/lib/builtins/CompilationContext.mdx @@ -2,131 +2,128 @@ title: 'CompilationContext' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.CompilationContext">CompilationContext</h1> +# CompilationContext {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Immutable store of information needed for C++ compilation that is aggregated across dependencies. -<h2>Members</h2> -<ul> - <li> - <a href="#defines">defines</a> - </li> - <li> - <a href="#direct_headers">direct_headers</a> - </li> - <li> - <a href="#direct_private_headers">direct_private_headers</a> - </li> - <li> - <a href="#direct_public_headers">direct_public_headers</a> - </li> - <li> - <a href="#direct_textual_headers">direct_textual_headers</a> - </li> - <li> - <a href="#external_includes">external_includes</a> - </li> - <li> - <a href="#framework_includes">framework_includes</a> - </li> - <li> - <a href="#headers">headers</a> - </li> - <li> - <a href="#includes">includes</a> - </li> - <li> - <a href="#local_defines">local_defines</a> - </li> - <li> - <a href="#quote_includes">quote_includes</a> - </li> - <li> - <a href="#system_includes">system_includes</a> - </li> - <li> - <a href="#validation_artifacts">validation_artifacts</a> - </li> - </ul> +## Members + +- [defines](#defines) +- [direct_headers](#direct_headers) +- [direct_private_headers](#direct_private_headers) +- [direct_public_headers](#direct_public_headers) +- [direct_textual_headers](#direct_textual_headers) +- [external_includes](#external_includes) +- [framework_includes](#framework_includes) +- [headers](#headers) +- [includes](#includes) +- [local_defines](#local_defines) +- [quote_includes](#quote_includes) +- [system_includes](#system_includes) +- [validation_artifacts](#validation_artifacts) + +## defines + +``` rule-signature +depset CompilationContext.defines +``` + +Returns the set of defines needed to compile this target. Each define is a string. These values are propagated to the target's transitive dependents, that is, any rules that depend on this target. + +## direct_headers + +``` rule-signature +list CompilationContext.direct_headers +``` + +Returns the list of modular headers that are declared by this target. This includes both public headers (such as those listed in "hdrs") and private headers (such as those listed in "srcs"). + +## direct_private_headers + +``` rule-signature +list CompilationContext.direct_private_headers +``` + +Returns the list of modular private headers (those listed in "srcs") that are declared by this target. + +## direct_public_headers - <h2 id="defines">defines</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.defines</pre></p> +``` rule-signature +list CompilationContext.direct_public_headers +``` - Returns the set of defines needed to compile this target. Each define is a string. These values are propagated to the target's transitive dependents, that is, any rules that depend on this target. +Returns the list of modular public headers (those listed in "hdrs") that are declared by this target. - <h2 id="direct_headers">direct_headers</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> CompilationContext.direct_headers</pre></p> +## direct_textual_headers - Returns the list of modular headers that are declared by this target. This includes both public headers (such as those listed in "hdrs") and private headers (such as those listed in "srcs"). +``` rule-signature +list CompilationContext.direct_textual_headers +``` - <h2 id="direct_private_headers">direct_private_headers</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> CompilationContext.direct_private_headers</pre></p> +Returns the list of textual headers that are declared by this target. - Returns the list of modular private headers (those listed in "srcs") that are declared by this target. +## external_includes - <h2 id="direct_public_headers">direct_public_headers</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> CompilationContext.direct_public_headers</pre></p> +``` rule-signature +depset CompilationContext.external_includes +``` - Returns the list of modular public headers (those listed in "hdrs") that are declared by this target. +Returns the set of search paths (as strings) for external header files referenced by angle bracket. Usually passed with -isystem. - <h2 id="direct_textual_headers">direct_textual_headers</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> CompilationContext.direct_textual_headers</pre></p> +## framework_includes - Returns the list of textual headers that are declared by this target. +``` rule-signature +depset CompilationContext.framework_includes +``` - <h2 id="external_includes">external_includes</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.external_includes</pre></p> +Returns the set of search paths (as strings) for framework header files. Usually passed with -F. - Returns the set of search paths (as strings) for external header files referenced by angle bracket. Usually passed with -isystem. +## headers - <h2 id="framework_includes">framework_includes</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.framework_includes</pre></p> +``` rule-signature +depset CompilationContext.headers +``` - Returns the set of search paths (as strings) for framework header files. Usually passed with -F. +Returns the set of headers needed to compile this target. - <h2 id="headers">headers</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.headers</pre></p> +## includes - Returns the set of headers needed to compile this target. +``` rule-signature +depset CompilationContext.includes +``` - <h2 id="includes">includes</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.includes</pre></p> +Returns the set of search paths (as strings) for header files referenced both by angle bracket and quotes. Usually passed with -I. - Returns the set of search paths (as strings) for header files referenced both by angle bracket and quotes. Usually passed with -I. +## local_defines - <h2 id="local_defines">local_defines</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.local_defines</pre></p> +``` rule-signature +depset CompilationContext.local_defines +``` - Returns the set of defines needed to compile this target. Each define is a string. These values are not propagated to the target's transitive dependents. +Returns the set of defines needed to compile this target. Each define is a string. These values are not propagated to the target's transitive dependents. - <h2 id="quote_includes">quote_includes</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.quote_includes</pre></p> +## quote_includes - Returns the set of search paths (as strings) for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. +``` rule-signature +depset CompilationContext.quote_includes +``` - <h2 id="system_includes">system_includes</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.system_includes</pre></p> +Returns the set of search paths (as strings) for header files referenced by quotes, e.g. \#include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. - Returns the set of search paths (as strings) for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. +## system_includes - <h2 id="validation_artifacts">validation_artifacts</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> CompilationContext.validation_artifacts</pre></p> +``` rule-signature +depset CompilationContext.system_includes +``` - Returns the set of validation artifacts. +Returns the set of search paths (as strings) for header files referenced by angle brackets, e.g. \#include \<foo/bar/header.h\>. They can be either relative to the exec root or absolute. Usually passed with -isystem. +## validation_artifacts -</body> -</html> +``` rule-signature +depset CompilationContext.validation_artifacts +``` -<!-- {% endraw %} --> +Returns the set of validation artifacts. diff --git a/rules/lib/builtins/DirectoryExpander.mdx b/rules/lib/builtins/DirectoryExpander.mdx index 921b35a..f2f90dd 100644 --- a/rules/lib/builtins/DirectoryExpander.mdx +++ b/rules/lib/builtins/DirectoryExpander.mdx @@ -2,62 +2,39 @@ title: 'DirectoryExpander' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.DirectoryExpander">DirectoryExpander</h1> +# DirectoryExpander {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Expands directories created by <a href='../builtins/actions.html#declare_directory'><code>ctx.actions.declare_directory</code></a> during the execution phase. This is useful to expand directories in <a href='../builtins/Args.html#add_all.map_each'><code>map_each</code></a>. - -<h2>Members</h2> -<ul> - <li> - <a href="#expand">expand</a> - </li> - </ul> - - <h2 id="expand">expand</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> DirectoryExpander.expand(file)</pre></p> - - If the given <code>File</code> is a directory, this returns a list of <code>File</code>s recursively underneath the directory. Otherwise, this returns a list containing just the given <code>File</code> itself. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="expand.file"> - <code>file</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The directory or file to expand. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +Expands directories created by [`ctx.actions.declare_directory`](../builtins/actions.html#declare_directory) during the execution phase. This is useful to expand directories in [`map_each`](../builtins/Args.html#add_all.map_each). + +## Members + +- [expand](#expand) + +## expand + +``` rule-signature +list DirectoryExpander.expand(file) +``` + +If the given `File` is a directory, this returns a list of `File`s recursively underneath the directory. Otherwise, this returns a list containing just the given `File` itself. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="expand.file"><code>file</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The directory or file to expand.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/builtins/DottedVersion.mdx b/rules/lib/builtins/DottedVersion.mdx index 05363bb..0e665f3 100644 --- a/rules/lib/builtins/DottedVersion.mdx +++ b/rules/lib/builtins/DottedVersion.mdx @@ -2,62 +2,39 @@ title: 'DottedVersion' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.DottedVersion">DottedVersion</h1> +# DottedVersion {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/DottedVersionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A value representing a version with multiple components, separated by periods, such as 1.2.3.4. -<h2>Members</h2> -<ul> - <li> - <a href="#compare_to">compare_to</a> - </li> - </ul> - - <h2 id="compare_to">compare_to</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> DottedVersion.compare_to(other)</pre></p> - - Compares based on most significant (first) not-matching version component. So, for example, 1.2.3 < 1.2.4 - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="compare_to.other"> - <code>other</code> - </td> - <td> - <a class="anchor" href="../builtins/DottedVersion.html">DottedVersion</a>; - required<br/> - The other dotted version. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [compare_to](#compare_to) + +## compare_to + +``` rule-signature +int DottedVersion.compare_to(other) +``` + +Compares based on most significant (first) not-matching version component. So, for example, 1.2.3 \< 1.2.4 + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="compare_to.other"><code>other</code></td> +<td><a href="../builtins/DottedVersion.html" class="anchor">DottedVersion</a>; +required<br /> +The other dotted version.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/builtins/ExecGroupCollection.mdx b/rules/lib/builtins/ExecGroupCollection.mdx index ad4d800..295bd7e 100644 --- a/rules/lib/builtins/ExecGroupCollection.mdx +++ b/rules/lib/builtins/ExecGroupCollection.mdx @@ -2,24 +2,8 @@ title: 'ExecGroupCollection' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ExecGroupCollection">ExecGroupCollection</h1> +# ExecGroupCollection {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ExecGroupCollectionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Stores exec groups available to a given rule. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/builtins/ExecGroupContext.mdx b/rules/lib/builtins/ExecGroupContext.mdx index 63f5421..e68d256 100644 --- a/rules/lib/builtins/ExecGroupContext.mdx +++ b/rules/lib/builtins/ExecGroupContext.mdx @@ -2,35 +2,20 @@ title: 'ExecGroupContext' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ExecGroupContext">ExecGroupContext</h1> +# ExecGroupContext {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ExecGroupCollectionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Stores information about an exec group. -<h2>Members</h2> -<ul> - <li> - <a href="#toolchains">toolchains</a> - </li> - </ul> - - <h2 id="toolchains">toolchains</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/ToolchainContext.html">ToolchainContext</a> ExecGroupContext.toolchains</pre></p> +## Members - Toolchains required for this exec group +- [toolchains](#toolchains) +## toolchains -</body> -</html> +``` rule-signature +ToolchainContext ExecGroupContext.toolchains +``` -<!-- {% endraw %} --> +Toolchains required for this exec group diff --git a/rules/lib/builtins/ExecTransitionFactory.mdx b/rules/lib/builtins/ExecTransitionFactory.mdx index efad8bc..eb88c4d 100644 --- a/rules/lib/builtins/ExecTransitionFactory.mdx +++ b/rules/lib/builtins/ExecTransitionFactory.mdx @@ -2,24 +2,8 @@ title: 'ExecTransitionFactory' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ExecTransitionFactory">ExecTransitionFactory</h1> +# ExecTransitionFactory {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} an execution transition. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/builtins/ExpandedDirectory.mdx b/rules/lib/builtins/ExpandedDirectory.mdx index 9008d95..0477583 100644 --- a/rules/lib/builtins/ExpandedDirectory.mdx +++ b/rules/lib/builtins/ExpandedDirectory.mdx @@ -2,43 +2,29 @@ title: 'ExpandedDirectory' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ExpandedDirectory">ExpandedDirectory</h1> +# ExpandedDirectory {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ExpandedDirectoryApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Represents an expanded directory that makes the files within the it directly accessible. -<h2>Members</h2> -<ul> - <li> - <a href="#children">children</a> - </li> - <li> - <a href="#directory">directory</a> - </li> - </ul> +## Members - <h2 id="children">children</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> ExpandedDirectory.children</pre></p> +- [children](#children) +- [directory](#directory) - Contains the files within the directory. +## children - <h2 id="directory">directory</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> ExpandedDirectory.directory</pre></p> +``` rule-signature +list ExpandedDirectory.children +``` - The input directory that was expanded. +Contains the files within the directory. +## directory -</body> -</html> +``` rule-signature +File ExpandedDirectory.directory +``` -<!-- {% endraw %} --> +The input directory that was expanded. diff --git a/rules/lib/builtins/FeatureConfiguration.mdx b/rules/lib/builtins/FeatureConfiguration.mdx index da61d12..32b0277 100644 --- a/rules/lib/builtins/FeatureConfiguration.mdx +++ b/rules/lib/builtins/FeatureConfiguration.mdx @@ -2,24 +2,8 @@ title: 'FeatureConfiguration' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.FeatureConfiguration">FeatureConfiguration</h1> +# FeatureConfiguration {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/FeatureConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Class used to construct command lines from CROSSTOOL features. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/builtins/File.mdx b/rules/lib/builtins/File.mdx index 98d1f8a..1f12468 100644 --- a/rules/lib/builtins/File.mdx +++ b/rules/lib/builtins/File.mdx @@ -2,116 +2,113 @@ title: 'File' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.File">File</h1> +# File {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +This object is created during the analysis phase to represent a file or directory that will be read or written during the execution phase. It is not an open file handle, and cannot be used to directly read or write file contents. Rather, you use it to construct the action graph in a rule implementation function by passing it to action-creating functions. See the [Rules page](https://bazel.build/extending/rules#files) for more information. + +When a `File` is passed to an [`Args`](../builtins/Args.html) object without using a `map_each` function, it is converted to a string by taking the value of its `path` field. + +## Members + +- [basename](#basename) +- [dirname](#dirname) +- [extension](#extension) +- [is_directory](#is_directory) +- [is_source](#is_source) +- [is_symlink](#is_symlink) +- [owner](#owner) +- [path](#path) +- [root](#root) +- [short_path](#short_path) +- [tree_relative_path](#tree_relative_path) + +## basename + +``` rule-signature +string File.basename +``` + +The base name of this file. This is the name of the file inside the directory. + +## dirname + +``` rule-signature +string File.dirname +``` + +The name of the directory containing this file. It's taken from [path](#path) and is always relative to the execution directory. -This object is created during the analysis phase to represent a file or directory that will be read or written during the execution phase. It is not an open file handle, and cannot be used to directly read or write file contents. Rather, you use it to construct the action graph in a rule implementation function by passing it to action-creating functions. See the <a href='https://bazel.build/extending/rules#files'>Rules page</a> for more information.<p>When a <code>File</code> is passed to an <a href='../builtins/Args.html'><code>Args</code></a> object without using a <code>map_each</code> function, it is converted to a string by taking the value of its <code>path</code> field. +## extension -<h2>Members</h2> -<ul> - <li> - <a href="#basename">basename</a> - </li> - <li> - <a href="#dirname">dirname</a> - </li> - <li> - <a href="#extension">extension</a> - </li> - <li> - <a href="#is_directory">is_directory</a> - </li> - <li> - <a href="#is_source">is_source</a> - </li> - <li> - <a href="#is_symlink">is_symlink</a> - </li> - <li> - <a href="#owner">owner</a> - </li> - <li> - <a href="#path">path</a> - </li> - <li> - <a href="#root">root</a> - </li> - <li> - <a href="#short_path">short_path</a> - </li> - <li> - <a href="#tree_relative_path">tree_relative_path</a> - </li> - </ul> +``` rule-signature +string File.extension +``` - <h2 id="basename">basename</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.basename</pre></p> +The file extension of this file, following (not including) the rightmost period. Empty string if the file's basename includes no periods. - The base name of this file. This is the name of the file inside the directory. +## is_directory - <h2 id="dirname">dirname</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.dirname</pre></p> +``` rule-signature +bool File.is_directory +``` - The name of the directory containing this file. It's taken from <a href="#path">path</a> and is always relative to the execution directory. +Returns true if this is a directory. This reflects the type the file was declared as (i.e. ctx.actions.declare_directory), not its type on the filesystem, which might differ. - <h2 id="extension">extension</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.extension</pre></p> +## is_source - The file extension of this file, following (not including) the rightmost period. Empty string if the file's basename includes no periods. +``` rule-signature +bool File.is_source +``` - <h2 id="is_directory">is_directory</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_directory</pre></p> +Returns true if this is a source file, i.e. it is not generated. - Returns true if this is a directory. This reflects the type the file was declared as (i.e. ctx.actions.declare_directory), not its type on the filesystem, which might differ. +## is_symlink - <h2 id="is_source">is_source</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_source</pre></p> +``` rule-signature +bool File.is_symlink +``` - Returns true if this is a source file, i.e. it is not generated. +Returns true if this was declared as a symlink. This reflects the type the file was declared as (i.e. ctx.actions.declare_symlink), not its type on the filesystem, which might differ. - <h2 id="is_symlink">is_symlink</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_symlink</pre></p> +## owner - Returns true if this was declared as a symlink. This reflects the type the file was declared as (i.e. ctx.actions.declare_symlink), not its type on the filesystem, which might differ. +``` rule-signature +Label File.owner +``` - <h2 id="owner">owner</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> File.owner</pre></p> +A label of a target that produces this File. +May return `None`. - A label of a target that produces this File. - May return <code>None</code>. +## path - <h2 id="path">path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.path</pre></p> +``` rule-signature +string File.path +``` - The execution path of this file, relative to the workspace's execution directory. It consists of two parts, an optional first part called the <i>root</i> (see also the <a href="../builtins/root.html">root</a> module), and the second part which is the <code>short_path</code>. The root may be empty, which it usually is for non-generated files. For generated files it usually contains a configuration-specific path fragment that encodes things like the target CPU architecture that was used while building said file. Use the <code>short_path</code> for the path under which the file is mapped if it's in the runfiles of a binary. +The execution path of this file, relative to the workspace's execution directory. It consists of two parts, an optional first part called the *root* (see also the [root](../builtins/root.html) module), and the second part which is the `short_path`. The root may be empty, which it usually is for non-generated files. For generated files it usually contains a configuration-specific path fragment that encodes things like the target CPU architecture that was used while building said file. Use the `short_path` for the path under which the file is mapped if it's in the runfiles of a binary. - <h2 id="root">root</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/root.html">root</a> File.root</pre></p> +## root - The root beneath which this file resides. +``` rule-signature +root File.root +``` - <h2 id="short_path">short_path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.short_path</pre></p> +The root beneath which this file resides. - The path of this file relative to its root. This excludes the aforementioned <i>root</i>, i.e. configuration-specific fragments of the path. This is also the path under which the file is mapped if it's in the runfiles of a binary. +## short_path - <h2 id="tree_relative_path">tree_relative_path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.tree_relative_path</pre></p> +``` rule-signature +string File.short_path +``` - The path of this file relative to the root of the ancestor's tree, if the ancestor's <a href="#is_directory">is_directory</a> field is true. <code>tree_relative_path</code> is only available for expanded files of a directory in an action command, i.e. <a href="../builtins/Args.html#add_all">Args.add_all()</a>. For other types of files, it is an error to access this field. +The path of this file relative to its root. This excludes the aforementioned *root*, i.e. configuration-specific fragments of the path. This is also the path under which the file is mapped if it's in the runfiles of a binary. +## tree_relative_path -</body> -</html> +``` rule-signature +string File.tree_relative_path +``` -<!-- {% endraw %} --> +The path of this file relative to the root of the ancestor's tree, if the ancestor's [is_directory](#is_directory) field is true. `tree_relative_path` is only available for expanded files of a directory in an action command, i.e. [Args.add_all()](../builtins/Args.html#add_all). For other types of files, it is an error to access this field. diff --git a/rules/lib/builtins/Label.mdx b/rules/lib/builtins/Label.mdx index be83e2f..e7669bc 100644 --- a/rules/lib/builtins/Label.mdx +++ b/rules/lib/builtins/Label.mdx @@ -2,180 +2,189 @@ title: 'Label' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.Label">Label</h1> +# Label {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/cmdline/Label.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A BUILD target identifier.<p>For every <code>Label</code> instance <code>l</code>, the string representation <code>str(l)</code> has the property that <code>Label(str(l)) == l</code>, regardless of where the <code>Label()</code> call occurs.<p>When passed as positional arguments to <code>print()</code> or <code>fail()</code>, <code>Label</code> use a string representation optimized for human readability instead. This representation uses an <a href="/external/overview#apparent-repo-name">apparent repository name</a> from the perspective of the main repository if possible. - -<h2>Members</h2> -<ul> - <li> - <a href="#Label">Label</a> - </li> - <li> - <a href="#name">name</a> - </li> - <li> - <a href="#package">package</a> - </li> - <li> - <a href="#relative">relative</a> - </li> - <li> - <a href="#repo_name">repo_name</a> - </li> - <li> - <a href="#same_package_label">same_package_label</a> - </li> - <li> - <a href="#workspace_name">workspace_name</a> - </li> - <li> - <a href="#workspace_root">workspace_root</a> - </li> - </ul> - - <h2 id="Label">Label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> Label(input)</pre></p> - - Converts a label string into a <code>Label</code> object, in the context of the package where the calling <code>.bzl</code> source file lives. If the given value is already a <code>Label</code>, it is returned unchanged.<p>For macros, a related function, <code><a href='../toplevel/native.html#package_relative_label'>native.package_relative_label()</a></code>, converts the input into a <code>Label</code> in the context of the package currently being constructed. Use that function to mimic the string-to-label conversion that is automatically done by label-valued rule attributes. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="Label.input"> - <code>input</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; - required<br/> - The input label string or Label object. If a Label object is passed, it's returned as is. - </td> - </tr> - </tbody> - </table> - - <h2 id="name">name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.name</pre></p> - - The name of the target referred to by this label. For instance:<br><pre class=language-python>Label("@@foo//pkg/foo:abc").name == "abc"</pre> - - <h2 id="package">package</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.package</pre></p> - - The name of the package containing the target referred to by this label, without the repository name. For instance:<br><pre class=language-python>Label("@@repo//pkg/foo:abc").package == "pkg/foo"</pre> - - <h2 id="relative">relative</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> Label.relative(relName)</pre></p> - - <b>Experimental</b>. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--+incompatible_enable_deprecated_label_apis</code> <br><strong>Deprecated.</strong> This method behaves surprisingly when used with an argument containing an apparent repo name. Prefer <a href="#same_package_label"><code>Label.same_package_label()</code></a>, <a href="../toplevel/native.html#package_relative_label"><code>native.package_relative_label()</code></a>, or <a href="#Label"><code>Label()</code></a> instead.<p>Resolves a label that is either absolute (starts with <code>//</code>) or relative to the current package. If this label is in a remote repository, the argument will be resolved relative to that repository. If the argument contains a repository name, the current label is ignored and the argument is returned as-is, except that the repository name is rewritten if it is in the current repository mapping. Reserved labels will also be returned as-is.<br>For example:<br><pre class=language-python> +{% include "\_buttons.html" %} +A BUILD target identifier. + +For every `Label` instance `l`, the string representation `str(l)` has the property that `Label(str(l)) == l`, regardless of where the `Label()` call occurs. + +When passed as positional arguments to `print()` or `fail()`, `Label` use a string representation optimized for human readability instead. This representation uses an [apparent repository name](/external/overview#apparent-repo-name) from the perspective of the main repository if possible. + +## Members + +- [Label](#Label) +- [name](#name) +- [package](#package) +- [relative](#relative) +- [repo_name](#repo_name) +- [same_package_label](#same_package_label) +- [workspace_name](#workspace_name) +- [workspace_root](#workspace_root) + +## Label + +``` rule-signature +Label Label(input) +``` + +Converts a label string into a `Label` object, in the context of the package where the calling `.bzl` source file lives. If the given value is already a `Label`, it is returned unchanged. + +For macros, a related function, [`native.package_relative_label()`](../toplevel/native.html#package_relative_label), converts the input into a `Label` in the context of the package currently being constructed. Use that function to mimic the string-to-label conversion that is automatically done by label-valued rule attributes. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="Label.input"><code>input</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; +required<br /> +The input label string or Label object. If a Label object is passed, it's returned as is.</td> +</tr> +</tbody> +</table> + +## name + +``` rule-signature +string Label.name +``` + +The name of the target referred to by this label. For instance: + +``` python +Label("@@foo//pkg/foo:abc").name == "abc" +``` + +## package + +``` rule-signature +string Label.package +``` + +The name of the package containing the target referred to by this label, without the repository name. For instance: + +``` python +Label("@@repo//pkg/foo:abc").package == "pkg/foo" +``` + +## relative + +``` rule-signature +Label Label.relative(relName) +``` + +**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` +**Deprecated.** This method behaves surprisingly when used with an argument containing an apparent repo name. Prefer [`Label.same_package_label()`](#same_package_label), [`native.package_relative_label()`](../toplevel/native.html#package_relative_label), or [`Label()`](#Label) instead. + +Resolves a label that is either absolute (starts with `//`) or relative to the current package. If this label is in a remote repository, the argument will be resolved relative to that repository. If the argument contains a repository name, the current label is ignored and the argument is returned as-is, except that the repository name is rewritten if it is in the current repository mapping. Reserved labels will also be returned as-is. +For example: + +``` python + Label("//foo/bar:baz").relative(":quux") == Label("//foo/bar:quux") Label("//foo/bar:baz").relative("//wiz:quux") == Label("//wiz:quux") Label("@repo//foo/bar:baz").relative("//wiz:quux") == Label("@repo//wiz:quux") Label("@repo//foo/bar:baz").relative("//visibility:public") == Label("//visibility:public") Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@other//wiz:quux") -</pre><p>If the repository mapping passed in is <code>{'@other' : '@remapped'}</code>, then the following remapping will take place:<br><pre class=language-python> +``` + +If the repository mapping passed in is `{'@other' : '@remapped'}`, then the following remapping will take place: + +``` python + Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@remapped//wiz:quux") -</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="relative.relName"> - <code>relName</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The label that will be resolved relative to this one. - </td> - </tr> - </tbody> - </table> - - <h2 id="repo_name">repo_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.repo_name</pre></p> - - The canonical name of the repository containing the target referred to by this label, without any leading at-signs (<code>@</code>). For instance, <pre class=language-python>Label("@@foo//bar:baz").repo_name == "foo"</pre> - - <h2 id="same_package_label">same_package_label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> Label.same_package_label(target_name)</pre></p> - - Creates a label in the same package as this label with the given target name. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="same_package_label.target_name"> - <code>target_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The target name of the new label. - </td> - </tr> - </tbody> - </table> - - <h2 id="workspace_name">workspace_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.workspace_name</pre></p> - - <b>Experimental</b>. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--+incompatible_enable_deprecated_label_apis</code> <br><strong>Deprecated.</strong> The field name "workspace name" is a misnomer here; use the identically-behaving <a href="#repo_name"><code>Label.repo_name</code></a> instead.<p>The canonical name of the repository containing the target referred to by this label, without any leading at-signs (<code>@</code>). For instance, <pre class=language-python>Label("@@foo//bar:baz").workspace_name == "foo"</pre> - - <h2 id="workspace_root">workspace_root</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> Label.workspace_root</pre></p> - - Returns the execution root for the repository containing the target referred to by this label, relative to the execroot. For instance:<br><pre class=language-python>Label("@repo//pkg/foo:abc").workspace_root == "external/repo"</pre> - - -</body> -</html> - -<!-- {% endraw %} --> +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="relative.relName"><code>relName</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The label that will be resolved relative to this one.</td> +</tr> +</tbody> +</table> + +## repo_name + +``` rule-signature +string Label.repo_name +``` + +The canonical name of the repository containing the target referred to by this label, without any leading at-signs (`@`). For instance, + +``` python +Label("@@foo//bar:baz").repo_name == "foo" +``` + +## same_package_label + +``` rule-signature +Label Label.same_package_label(target_name) +``` + +Creates a label in the same package as this label with the given target name. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="same_package_label.target_name"><code>target_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The target name of the new label.</td> +</tr> +</tbody> +</table> + +## workspace_name + +``` rule-signature +string Label.workspace_name +``` + +**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` +**Deprecated.** The field name "workspace name" is a misnomer here; use the identically-behaving [`Label.repo_name`](#repo_name) instead. + +The canonical name of the repository containing the target referred to by this label, without any leading at-signs (`@`). For instance, + +``` python +Label("@@foo//bar:baz").workspace_name == "foo" +``` + +## workspace_root + +``` rule-signature +string Label.workspace_root +``` + +Returns the execution root for the repository containing the target referred to by this label, relative to the execroot. For instance: + +``` python +Label("@repo//pkg/foo:abc").workspace_root == "external/repo" +``` diff --git a/rules/lib/builtins/LateBoundDefault.mdx b/rules/lib/builtins/LateBoundDefault.mdx index 443f34e..b29aeb7 100644 --- a/rules/lib/builtins/LateBoundDefault.mdx +++ b/rules/lib/builtins/LateBoundDefault.mdx @@ -2,24 +2,10 @@ title: 'LateBoundDefault' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.LateBoundDefault">LateBoundDefault</h1> +# LateBoundDefault {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Represents a late-bound default attribute value of type 'Label'. The value of a LateBoundDefault is only resolvable in the context of a rule implementation function, and depends on the current build configuration. For example, a LateBoundDefault might represent the Label of the java toolchain in the current build configuration. <p>See <a href="../globals/bzl.html#configuration_field">configuration_field</a> for example usage. - - - -</body> -</html> +{% include "\_buttons.html" %} +Represents a late-bound default attribute value of type 'Label'. The value of a LateBoundDefault is only resolvable in the context of a rule implementation function, and depends on the current build configuration. For example, a LateBoundDefault might represent the Label of the java toolchain in the current build configuration. -<!-- {% endraw %} --> +See [configuration_field](../globals/bzl.html#configuration_field) for example usage. diff --git a/rules/lib/builtins/LibraryToLink.mdx b/rules/lib/builtins/LibraryToLink.mdx index 88374ef..324e45b 100644 --- a/rules/lib/builtins/LibraryToLink.mdx +++ b/rules/lib/builtins/LibraryToLink.mdx @@ -2,125 +2,120 @@ title: 'LibraryToLink' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.LibraryToLink">LibraryToLink</h1> +# LibraryToLink {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/LibraryToLinkApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A library the user can link against. -<h2>Members</h2> -<ul> - <li> - <a href="#alwayslink">alwayslink</a> - </li> - <li> - <a href="#dynamic_library">dynamic_library</a> - </li> - <li> - <a href="#interface_library">interface_library</a> - </li> - <li> - <a href="#lto_bitcode_files">lto_bitcode_files</a> - </li> - <li> - <a href="#objects">objects</a> - </li> - <li> - <a href="#pic_lto_bitcode_files">pic_lto_bitcode_files</a> - </li> - <li> - <a href="#pic_objects">pic_objects</a> - </li> - <li> - <a href="#pic_static_library">pic_static_library</a> - </li> - <li> - <a href="#resolved_symlink_dynamic_library">resolved_symlink_dynamic_library</a> - </li> - <li> - <a href="#resolved_symlink_interface_library">resolved_symlink_interface_library</a> - </li> - <li> - <a href="#static_library">static_library</a> - </li> - </ul> - - <h2 id="alwayslink">alwayslink</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> LibraryToLink.alwayslink</pre></p> - - Whether to link the static library/objects in the --whole_archive block. - - <h2 id="dynamic_library">dynamic_library</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.dynamic_library</pre></p> - - <code>Artifact</code> of dynamic library to be linked. Always used for runtime and used for linking if <code>interface_library</code> is not passed. - May return <code>None</code>. - - <h2 id="interface_library">interface_library</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.interface_library</pre></p> - - <code>Artifact</code> of interface library to be linked. - May return <code>None</code>. - - <h2 id="lto_bitcode_files">lto_bitcode_files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LibraryToLink.lto_bitcode_files</pre></p> - - <code>List</code> of LTO bitcode files in the library. - May return <code>None</code>. - - <h2 id="objects">objects</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LibraryToLink.objects</pre></p> - - <code>List</code> of object files in the library. - May return <code>None</code>. - - <h2 id="pic_lto_bitcode_files">pic_lto_bitcode_files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LibraryToLink.pic_lto_bitcode_files</pre></p> - - <code>List</code> of pic LTO bitcode files in the library. - May return <code>None</code>. - - <h2 id="pic_objects">pic_objects</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LibraryToLink.pic_objects</pre></p> - - <code>List</code> of pic object files in the library. - May return <code>None</code>. - - <h2 id="pic_static_library">pic_static_library</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.pic_static_library</pre></p> - - <code>Artifact</code> of pic static library to be linked. - May return <code>None</code>. - - <h2 id="resolved_symlink_dynamic_library">resolved_symlink_dynamic_library</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.resolved_symlink_dynamic_library</pre></p> - - The resolved <code>Artifact</code> of the dynamic library to be linked if <code>dynamic_library</code> is a symlink, otherwise this is None. - May return <code>None</code>. - - <h2 id="resolved_symlink_interface_library">resolved_symlink_interface_library</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.resolved_symlink_interface_library</pre></p> - - The resolved <code>Artifact</code> of the interface library to be linked if <code>interface_library</code> is a symlink, otherwise this is None. - May return <code>None</code>. - - <h2 id="static_library">static_library</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> LibraryToLink.static_library</pre></p> - - <code>Artifact</code> of static library to be linked. - May return <code>None</code>. - - -</body> -</html> +## Members + +- [alwayslink](#alwayslink) +- [dynamic_library](#dynamic_library) +- [interface_library](#interface_library) +- [lto_bitcode_files](#lto_bitcode_files) +- [objects](#objects) +- [pic_lto_bitcode_files](#pic_lto_bitcode_files) +- [pic_objects](#pic_objects) +- [pic_static_library](#pic_static_library) +- [resolved_symlink_dynamic_library](#resolved_symlink_dynamic_library) +- [resolved_symlink_interface_library](#resolved_symlink_interface_library) +- [static_library](#static_library) + +## alwayslink + +``` rule-signature +bool LibraryToLink.alwayslink +``` + +Whether to link the static library/objects in the --whole_archive block. + +## dynamic_library + +``` rule-signature +File LibraryToLink.dynamic_library +``` + +`Artifact` of dynamic library to be linked. Always used for runtime and used for linking if `interface_library` is not passed. +May return `None`. + +## interface_library + +``` rule-signature +File LibraryToLink.interface_library +``` + +`Artifact` of interface library to be linked. +May return `None`. + +## lto_bitcode_files + +``` rule-signature +sequence LibraryToLink.lto_bitcode_files +``` + +`List` of LTO bitcode files in the library. +May return `None`. + +## objects + +``` rule-signature +sequence LibraryToLink.objects +``` + +`List` of object files in the library. +May return `None`. + +## pic_lto_bitcode_files + +``` rule-signature +sequence LibraryToLink.pic_lto_bitcode_files +``` + +`List` of pic LTO bitcode files in the library. +May return `None`. + +## pic_objects + +``` rule-signature +sequence LibraryToLink.pic_objects +``` + +`List` of pic object files in the library. +May return `None`. + +## pic_static_library + +``` rule-signature +File LibraryToLink.pic_static_library +``` + +`Artifact` of pic static library to be linked. +May return `None`. + +## resolved_symlink_dynamic_library + +``` rule-signature +File LibraryToLink.resolved_symlink_dynamic_library +``` + +The resolved `Artifact` of the dynamic library to be linked if `dynamic_library` is a symlink, otherwise this is None. +May return `None`. + +## resolved_symlink_interface_library + +``` rule-signature +File LibraryToLink.resolved_symlink_interface_library +``` + +The resolved `Artifact` of the interface library to be linked if `interface_library` is a symlink, otherwise this is None. +May return `None`. + +## static_library + +``` rule-signature +File LibraryToLink.static_library +``` -<!-- {% endraw %} --> +`Artifact` of static library to be linked. +May return `None`. diff --git a/rules/lib/builtins/License.mdx b/rules/lib/builtins/License.mdx index 42229c5..d4f5d9b 100644 --- a/rules/lib/builtins/License.mdx +++ b/rules/lib/builtins/License.mdx @@ -2,24 +2,8 @@ title: 'License' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.License">License</h1> +# License {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LicenseApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} This API is deprecated and will be removed. Please do not depend on it. This object represents the value of a license attribute. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/builtins/LinkerInput.mdx b/rules/lib/builtins/LinkerInput.mdx index 8a26564..5f9dafb 100644 --- a/rules/lib/builtins/LinkerInput.mdx +++ b/rules/lib/builtins/LinkerInput.mdx @@ -2,59 +2,47 @@ title: 'LinkerInput' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.LinkerInput">LinkerInput</h1> +# LinkerInput {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/LinkerInputApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Either libraries, flags or other files that may be passed to the linker as inputs. -<h2>Members</h2> -<ul> - <li> - <a href="#additional_inputs">additional_inputs</a> - </li> - <li> - <a href="#libraries">libraries</a> - </li> - <li> - <a href="#owner">owner</a> - </li> - <li> - <a href="#user_link_flags">user_link_flags</a> - </li> - </ul> +## Members + +- [additional_inputs](#additional_inputs) +- [libraries](#libraries) +- [owner](#owner) +- [user_link_flags](#user_link_flags) + +## additional_inputs - <h2 id="additional_inputs">additional_inputs</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LinkerInput.additional_inputs</pre></p> +``` rule-signature +sequence LinkerInput.additional_inputs +``` - Returns the depset of additional inputs, e.g.: linker scripts. +Returns the depset of additional inputs, e.g.: linker scripts. - <h2 id="libraries">libraries</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LinkerInput.libraries</pre></p> +## libraries - Returns the depset of <code>LibraryToLink</code>. May return a list but this is deprecated. See #8118. +``` rule-signature +sequence LinkerInput.libraries +``` - <h2 id="owner">owner</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> LinkerInput.owner</pre></p> +Returns the depset of `LibraryToLink`. May return a list but this is deprecated. See \#8118. - Returns the owner of this LinkerInput. +## owner - <h2 id="user_link_flags">user_link_flags</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> LinkerInput.user_link_flags</pre></p> +``` rule-signature +Label LinkerInput.owner +``` - Returns the list of user link flags passed as strings. +Returns the owner of this LinkerInput. +## user_link_flags -</body> -</html> +``` rule-signature +sequence LinkerInput.user_link_flags +``` -<!-- {% endraw %} --> +Returns the list of user link flags passed as strings. diff --git a/rules/lib/builtins/LinkingContext.mdx b/rules/lib/builtins/LinkingContext.mdx index 67e1369..b24fb8f 100644 --- a/rules/lib/builtins/LinkingContext.mdx +++ b/rules/lib/builtins/LinkingContext.mdx @@ -2,35 +2,20 @@ title: 'LinkingContext' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.LinkingContext">LinkingContext</h1> +# LinkingContext {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingContextApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Immutable store of information needed for C++ linking that is aggregated across dependencies. -<h2>Members</h2> -<ul> - <li> - <a href="#linker_inputs">linker_inputs</a> - </li> - </ul> - - <h2 id="linker_inputs">linker_inputs</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> LinkingContext.linker_inputs</pre></p> +## Members - Returns the depset of linker inputs. +- [linker_inputs](#linker_inputs) +## linker_inputs -</body> -</html> +``` rule-signature +depset LinkingContext.linker_inputs +``` -<!-- {% endraw %} --> +Returns the depset of linker inputs. diff --git a/rules/lib/builtins/Provider.mdx b/rules/lib/builtins/Provider.mdx index 7206e4d..e42d987 100644 --- a/rules/lib/builtins/Provider.mdx +++ b/rules/lib/builtins/Provider.mdx @@ -2,28 +2,29 @@ title: 'Provider' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.Provider">Provider</h1> +# Provider {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +A constructor for simple value objects, known as provider instances. +This value has a dual purpose: + +- It is a function that can be called to construct 'struct'-like values: -A constructor for simple value objects, known as provider instances.<br>This value has a dual purpose: <ul> <li>It is a function that can be called to construct 'struct'-like values:<pre class="language-python">DataInfo = provider() -d = DataInfo(x = 2, y = 3) -print(d.x + d.y) # prints 5</pre> Note: Some providers, defined internally, do not allow instance creation </li> <li>It is a <i>key</i> to access a provider instance on a <a href="../builtins/Target.html">Target</a><pre class="language-python">DataInfo = provider() -def _rule_impl(ctx) - ... ctx.attr.dep[DataInfo]</pre> </li> </ul>Create a new <code>Provider</code> using the <a href="../globals/bzl.html#provider">provider</a> function. + ``` python + DataInfo = provider() + d = DataInfo(x = 2, y = 3) + print(d.x + d.y) # prints 5 + ``` + Note: Some providers, defined internally, do not allow instance creation +- It is a *key* to access a provider instance on a [Target](../builtins/Target.html) -</body> -</html> + ``` python + DataInfo = provider() + def _rule_impl(ctx) + ... ctx.attr.dep[DataInfo] + ``` -<!-- {% endraw %} --> +Create a new `Provider` using the [provider](../globals/bzl.html#provider) function. diff --git a/rules/lib/builtins/Subrule.mdx b/rules/lib/builtins/Subrule.mdx index 9fd6128..100313b 100644 --- a/rules/lib/builtins/Subrule.mdx +++ b/rules/lib/builtins/Subrule.mdx @@ -2,24 +2,8 @@ title: 'Subrule' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.Subrule">Subrule</h1> +# Subrule {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkSubruleApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Experimental: a building block for writing rules with shared code. For more information, please see the subrule proposal: https://docs.google.com/document/d/1RbNC88QieKvBEwir7iV5zZU08AaMlOzxhVkPnmKDedQ - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/builtins/SymlinkEntry.mdx b/rules/lib/builtins/SymlinkEntry.mdx index 5fadd60..7a6eba0 100644 --- a/rules/lib/builtins/SymlinkEntry.mdx +++ b/rules/lib/builtins/SymlinkEntry.mdx @@ -2,43 +2,29 @@ title: 'SymlinkEntry' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.SymlinkEntry">SymlinkEntry</h1> +# SymlinkEntry {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/SymlinkEntryApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A single runfiles symlink represented by a link name and target. -<h2>Members</h2> -<ul> - <li> - <a href="#path">path</a> - </li> - <li> - <a href="#target_file">target_file</a> - </li> - </ul> +## Members - <h2 id="path">path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> SymlinkEntry.path</pre></p> +- [path](#path) +- [target_file](#target_file) - The path of the symlink in the runfiles tree +## path - <h2 id="target_file">target_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> SymlinkEntry.target_file</pre></p> +``` rule-signature +string SymlinkEntry.path +``` - Target file of the symlink +The path of the symlink in the runfiles tree +## target_file -</body> -</html> +``` rule-signature +File SymlinkEntry.target_file +``` -<!-- {% endraw %} --> +Target file of the symlink diff --git a/rules/lib/builtins/Target.mdx b/rules/lib/builtins/Target.mdx index 0fa26fc..558a708 100644 --- a/rules/lib/builtins/Target.mdx +++ b/rules/lib/builtins/Target.mdx @@ -2,32 +2,18 @@ title: 'Target' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.Target">Target</h1> +# Target {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -The BUILD target for a dependency. Appears in the fields of <code><a href='../builtins/ctx.html#attr'>ctx.attr</a></code> corresponding to <a href='https://bazel.build/extending/rules#dependency_attributes'>dependency attributes</a> (<code><a href='../toplevel/attr.html#label'>label</a></code> or <code><a href='../toplevel/attr.html#label_list'>label_list</a></code>). Has the following fields: -<ul> -<li><h3 id='modules.Target.label'>label</h3> -<code><a href='../builtins/Label.html'>Label</a> Target.label</code><br/> -The identifier of the target.</li> -<li><h3 id='modules.Target.providers'>Providers</h3> -The <a href='https://bazel.build/extending/rules#providers'>providers</a> of a rule target can be accessed by type using index notation (<code>target[DefaultInfo]</code>). The presence of providers can be checked using the <code>in</code> operator (<code>SomeInfo in target</code>).<br/> -<br/> -</ul> +{% include "\_buttons.html" %} +The BUILD target for a dependency. Appears in the fields of [`ctx.attr`](../builtins/ctx.html#attr) corresponding to [dependency attributes](https://bazel.build/extending/rules#dependency_attributes) ([`label`](../toplevel/attr.html#label) or [`label_list`](../toplevel/attr.html#label_list)). Has the following fields: +- ### label + [`Label`](../builtins/Label.html)` Target.label` + The identifier of the target. -</body> -</html> +- ### Providers -<!-- {% endraw %} --> + The [providers](https://bazel.build/extending/rules#providers) of a rule target can be accessed by type using index notation (`target[DefaultInfo]`). The presence of providers can be checked using the `in` operator (`SomeInfo in target`). + diff --git a/rules/lib/builtins/TemplateDict.mdx b/rules/lib/builtins/TemplateDict.mdx index 6735156..92bad78 100644 --- a/rules/lib/builtins/TemplateDict.mdx +++ b/rules/lib/builtins/TemplateDict.mdx @@ -2,167 +2,109 @@ title: 'TemplateDict' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.TemplateDict">TemplateDict</h1> +# TemplateDict {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} An Args-like structure for use in ctx.actions.expand_template(), which allows for deferring evaluation of values till the execution phase. -<h2>Members</h2> -<ul> - <li> - <a href="#add">add</a> - </li> - <li> - <a href="#add_joined">add_joined</a> - </li> - </ul> +## Members + +- [add](#add) +- [add_joined](#add_joined) + +## add + +``` rule-signature +TemplateDict TemplateDict.add(key, value) +``` + +Add a String value - <h2 id="add">add</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/TemplateDict.html">TemplateDict</a> TemplateDict.add(key, value)</pre></p> +### Parameters - Add a String value - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="add.key"> - <code>key</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A String key - </td> - </tr> - <tr> - <td id="add.value"> - <code>value</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A String value - </td> - </tr> - </tbody> - </table> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="add.key"><code>key</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A String key</td> +</tr> +<tr> +<td id="add.value"><code>value</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A String value</td> +</tr> +</tbody> +</table> - <h2 id="add_joined">add_joined</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/TemplateDict.html">TemplateDict</a> TemplateDict.add_joined(key, values, *, join_with, map_each, uniquify=False, format_joined=None, allow_closure=False)</pre></p> +## add_joined - Add depset of values - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="add_joined.key"> - <code>key</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A String key - </td> - </tr> - <tr> - <td id="add_joined.values"> - <code>values</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; - required<br/> - The depset whose items will be joined. - </td> - </tr> - <tr> - <td id="add_joined.join_with"> - <code>join_with</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A delimiter string used to join together the strings obtained from applying <code>map_each</code>, in the same manner as <a href='../core/string.html#join'><code>string.join()</code></a>. - </td> - </tr> - <tr> - <td id="add_joined.map_each"> - <code>map_each</code> - </td> - <td> - callable; - required<br/> - A Starlark function accepting a single argument and returning either a string, <code>None</code>, or a list of strings. This function is applied to each item of the depset specified in the <code>values</code> parameter - </td> - </tr> - <tr> - <td id="add_joined.uniquify"> - <code>uniquify</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, duplicate strings derived from <code>values</code> will be omitted. Only the first occurrence of each string will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items. - </td> - </tr> - <tr> - <td id="add_joined.format_joined"> - <code>format_joined</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. - </td> - </tr> - <tr> - <td id="add_joined.allow_closure"> - <code>allow_closure</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. - </td> - </tr> - </tbody> - </table> +``` rule-signature +TemplateDict TemplateDict.add_joined(key, values, *, join_with, map_each, uniquify=False, format_joined=None, allow_closure=False) +``` +Add depset of values -</body> -</html> +### Parameters -<!-- {% endraw %} --> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="add_joined.key"><code>key</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A String key</td> +</tr> +<tr> +<td id="add_joined.values"><code>values</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; +required<br /> +The depset whose items will be joined.</td> +</tr> +<tr> +<td id="add_joined.join_with"><code>join_with</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A delimiter string used to join together the strings obtained from applying <code>map_each</code>, in the same manner as <a href="../core/string.html#join"><code>string.join()</code></a>.</td> +</tr> +<tr> +<td id="add_joined.map_each"><code>map_each</code></td> +<td>callable; +required<br /> +A Starlark function accepting a single argument and returning either a string, <code>None</code>, or a list of strings. This function is applied to each item of the depset specified in the <code>values</code> parameter</td> +</tr> +<tr> +<td id="add_joined.uniquify"><code>uniquify</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, duplicate strings derived from <code>values</code> will be omitted. Only the first occurrence of each string will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items.</td> +</tr> +<tr> +<td id="add_joined.format_joined"><code>format_joined</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder.</td> +</tr> +<tr> +<td id="add_joined.allow_closure"><code>allow_closure</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/builtins/ToolchainContext.mdx b/rules/lib/builtins/ToolchainContext.mdx index 7420c07..89a9c5e 100644 --- a/rules/lib/builtins/ToolchainContext.mdx +++ b/rules/lib/builtins/ToolchainContext.mdx @@ -2,24 +2,8 @@ title: 'ToolchainContext' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ToolchainContext">ToolchainContext</h1> +# ToolchainContext {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainContextApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in <code>ctx.toolchains["//pkg:my_toolchain_type"]</code>. If the toolchain was optional and no toolchain was resolved, this will return <code>None</code>. Accessing toolchains of an aspect or rule via <code>ctx.toolchains</code> returns the indexed toolchain as a <code>ToolchainInfo</code> provider. While when using aspects, <code>ToolchainContext</code> is also used to hold the toolchains of the base target. It can be accessed by <code>ctx.rule.toolchains["//pkg:my_toolchain_type"]</code> and it returns the list of providers resulted from applying the aspects on these toolchain targets. - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in `ctx.toolchains["//pkg:my_toolchain_type"]`. If the toolchain was optional and no toolchain was resolved, this will return `None`. Accessing toolchains of an aspect or rule via `ctx.toolchains` returns the indexed toolchain as a `ToolchainInfo` provider. While when using aspects, `ToolchainContext` is also used to hold the toolchains of the base target. It can be accessed by `ctx.rule.toolchains["//pkg:my_toolchain_type"]` and it returns the list of providers resulted from applying the aspects on these toolchain targets. diff --git a/rules/lib/builtins/actions.mdx b/rules/lib/builtins/actions.mdx index fff1554..78bb0ca 100644 --- a/rules/lib/builtins/actions.mdx +++ b/rules/lib/builtins/actions.mdx @@ -2,987 +2,718 @@ title: 'actions' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.actions">actions</h1> +# actions {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Module providing functions to create actions. Access this module using <a href="../builtins/ctx.html#actions"><code>ctx.actions</code></a>. - -<h2>Members</h2> -<ul> - <li> - <a href="#args">args</a> - </li> - <li> - <a href="#declare_directory">declare_directory</a> - </li> - <li> - <a href="#declare_file">declare_file</a> - </li> - <li> - <a href="#declare_symlink">declare_symlink</a> - </li> - <li> - <a href="#do_nothing">do_nothing</a> - </li> - <li> - <a href="#expand_template">expand_template</a> - </li> - <li> - <a href="#map_directory">map_directory</a> - </li> - <li> - <a href="#run">run</a> - </li> - <li> - <a href="#run_shell">run_shell</a> - </li> - <li> - <a href="#symlink">symlink</a> - </li> - <li> - <a href="#template_dict">template_dict</a> - </li> - <li> - <a href="#write">write</a> - </li> - </ul> - - <h2 id="args">args</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> actions.args()</pre></p> - - Returns an Args object that can be used to build memory-efficient command lines. - - <h2 id="declare_directory">declare_directory</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> actions.declare_directory(filename, *, sibling=None)</pre></p> - - Declares that the rule or aspect creates a directory with the given name, in the current package. You must create an action that generates the directory. The contents of the directory are not directly accessible from Starlark, but can be expanded in an action command with <a href="../builtins/Args.html#add_all"><code>Args.add_all()</code></a>. Only regular files and directories can be in the expanded contents of a declare_directory. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="declare_directory.filename"> - <code>filename</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - If no 'sibling' provided, path of the new directory, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). - </td> - </tr> - <tr> - <td id="declare_directory.sibling"> - <code>sibling</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - A file that lives in the same directory as the newly declared directory. The file must be in the current package. - </td> - </tr> - </tbody> - </table> - - <h2 id="declare_file">declare_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> actions.declare_file(filename, *, sibling=None)</pre></p> - - Declares that the rule or aspect creates a file with the given filename. If <code>sibling</code> is not specified, the file name is relative to the package directory, otherwise the file is in the same directory as <code>sibling</code>. Files cannot be created outside of the current package.<p>Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned <code>File</code> object to the action's construction function.<p>Note that <a href='https://bazel.build/extending/rules#files'>predeclared output files</a> do not need to be (and cannot be) declared using this function. You can obtain their <code>File</code> objects from <a href="../builtins/ctx.html#outputs"><code>ctx.outputs</code></a> instead. <a href="https://github.com/bazelbuild/examples/tree/main/rules/computed_dependencies/hash.bzl">See example of use</a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="declare_file.filename"> - <code>filename</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - If no 'sibling' provided, path of the new file, relative to the current package. Otherwise a base name for a file ('sibling' determines a directory). - </td> - </tr> - <tr> - <td id="declare_file.sibling"> - <code>sibling</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - A file that lives in the same directory as the newly created file. The file must be in the current package. - </td> - </tr> - </tbody> - </table> - - <h2 id="declare_symlink">declare_symlink</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> actions.declare_symlink(filename, *, sibling=None)</pre></p> - - Declares that the rule or aspect creates a symlink with the given name in the current package. You must create an action that generates this symlink. Bazel will never dereference this symlink and will transfer it verbatim to sandboxes or remote executors. Symlinks inside tree artifacts are not currently supported. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="declare_symlink.filename"> - <code>filename</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - If no 'sibling' provided, path of the new symlink, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). - </td> - </tr> - <tr> - <td id="declare_symlink.sibling"> - <code>sibling</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - A file that lives in the same directory as the newly declared symlink. - </td> - </tr> - </tbody> - </table> - - <h2 id="do_nothing">do_nothing</h2> - <p><pre class="rule-signature"><code>None</code> actions.do_nothing(*, mnemonic, inputs=[])</pre></p> - - Creates an empty action that neither executes a command nor produces any output, but that is useful for inserting 'extra actions'. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="do_nothing.mnemonic"> - <code>mnemonic</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A one-word description of the action, for example, CppCompile or GoLink. - </td> - </tr> - <tr> - <td id="do_nothing.inputs"> - <code>inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>[]</code><br/> - List of the input files of the action. - </td> - </tr> - </tbody> - </table> - - <h2 id="expand_template">expand_template</h2> - <p><pre class="rule-signature"><code>None</code> actions.expand_template(*, template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)</pre></p> - - Creates a template expansion action. When the action is executed, it will generate a file based on a template. Parts of the template will be replaced using the <code>substitutions</code> dictionary, in the order the substitutions are specified. Whenever a key of the dictionary appears in the template (or a result of a previous substitution), it is replaced with the associated value. There is no special syntax for the keys. You may, for example, use curly braces to avoid conflicts (for example, <code>{KEY}</code>). <a href="https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl">See example of use</a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="expand_template.template"> - <code>template</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The template file, which is a UTF-8 encoded text file. - </td> - </tr> - <tr> - <td id="expand_template.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The output file, which is a UTF-8 encoded text file. - </td> - </tr> - <tr> - <td id="expand_template.substitutions"> - <code>substitutions</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - Substitutions to make when expanding the template. - </td> - </tr> - <tr> - <td id="expand_template.is_executable"> - <code>is_executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether the output file should be executable. - </td> - </tr> - <tr> - <td id="expand_template.computed_substitutions"> - <code>computed_substitutions</code> - </td> - <td> - <a class="anchor" href="../builtins/TemplateDict.html">TemplateDict</a>; - default is <code>unbound</code><br/> - Substitutions to make when expanding the template. - </td> - </tr> - </tbody> - </table> - - <h2 id="map_directory">map_directory</h2> - <p><pre class="rule-signature"><code>None</code> actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation)</pre></p> - - Creates multiple actions based on the files within one or more input directories, to output one or more output directories. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="map_directory.input_directories"> - <code>input_directories</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - required<br/> - A dictionary mapping of strings to input directories, as declared by <code>ctx.actions.declare_directory()</code> (only directories are allowed as values here). The values specify the directories that we want expanded to access their files in the implementation function. The keys (strings) act as identifiers to easily reference a specific directory in the implementation function. - </td> - </tr> - <tr> - <td id="map_directory.additional_inputs"> - <code>additional_inputs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary of mapping of strings to additional inputs (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify any additional inputs that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific input from within the implementation function. - </td> - </tr> - <tr> - <td id="map_directory.output_directories"> - <code>output_directories</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - required<br/> - A dictionary mapping of strings to output directories, as declared by <code>ctx.actions.declare_directory()</code>. The values specify the output directories that we want to generate by the actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific output directory from within the implementation function. - </td> - </tr> - <tr> - <td id="map_directory.tools"> - <code>tools</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - required<br/> - A dictionary mapping of strings to tools (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify the tools that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific tool from within the implementation function. - </td> - </tr> - <tr> - <td id="map_directory.additional_params"> - <code>additional_params</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary mapping of strings to additional parameters (only string, boolean and integer values are allowed here). The values specify any additional parameters that we want to make accessible to the implementation function that could be used to influence its behavior. The keys (strings) act as identifiers to easily reference a specific parameter from within the implementation function. - </td> - </tr> - <tr> - <td id="map_directory.execution_requirements"> - <code>execution_requirements</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Information for scheduling the created actions. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys. - </td> - </tr> - <tr> - <td id="map_directory.exec_group"> - <code>exec_group</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Run the created actions on the given exec group's execution platform. If none, uses the target's default execution platform. - </td> - </tr> - <tr> - <td id="map_directory.toolchain"> - <code>toolchain</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - <p>Toolchain type of the executable or tools used by the created actions.</p><p>If executable and tools are not coming from a toolchain, set this parameter to <code>None</code>.</p><p>If executable and tools are coming from a toolchain, toolchain type must be set so that the created actions execute on the correct execution platform.</p><p>Note that the rule which creates these actions needs to define this toolchain inside its 'rule()' function.</p><p>When <code>toolchain</code> and <code>exec_group</code> parameters are both set, <code>exec_group</code> will be used. An error is raised in case the <code>exec_group</code> doesn't specify the same toolchain.</p> - </td> - </tr> - <tr> - <td id="map_directory.use_default_shell_env"> - <code>use_default_shell_env</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether the created actions should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. - </td> - </tr> - <tr> - <td id="map_directory.env"> - <code>env</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Sets the dictionary of environment variables.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. - </td> - </tr> - <tr> - <td id="map_directory.mnemonic"> - <code>mnemonic</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A one-word description of the created actions, for example, CppCompile or GoLink. - </td> - </tr> - <tr> - <td id="map_directory.implementation"> - <code>implementation</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - required<br/> - A Starlark function that gets called after input directories have been built to generate actions +{% include "\_buttons.html" %} +Module providing functions to create actions. Access this module using [`ctx.actions`](../builtins/ctx.html#actions). + +## Members + +- [args](#args) +- [declare_directory](#declare_directory) +- [declare_file](#declare_file) +- [declare_symlink](#declare_symlink) +- [do_nothing](#do_nothing) +- [expand_template](#expand_template) +- [map_directory](#map_directory) +- [run](#run) +- [run_shell](#run_shell) +- [symlink](#symlink) +- [template_dict](#template_dict) +- [write](#write) + +## args + +``` rule-signature +Args actions.args() +``` + +Returns an Args object that can be used to build memory-efficient command lines. + +## declare_directory + +``` rule-signature +File actions.declare_directory(filename, *, sibling=None) +``` + +Declares that the rule or aspect creates a directory with the given name, in the current package. You must create an action that generates the directory. The contents of the directory are not directly accessible from Starlark, but can be expanded in an action command with [`Args.add_all()`](../builtins/Args.html#add_all). Only regular files and directories can be in the expanded contents of a declare_directory. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="declare_directory.filename"><code>filename</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +If no 'sibling' provided, path of the new directory, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory).</td> +</tr> +<tr> +<td id="declare_directory.sibling"><code>sibling</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +A file that lives in the same directory as the newly declared directory. The file must be in the current package.</td> +</tr> +</tbody> +</table> + +## declare_file + +``` rule-signature +File actions.declare_file(filename, *, sibling=None) +``` + +Declares that the rule or aspect creates a file with the given filename. If `sibling` is not specified, the file name is relative to the package directory, otherwise the file is in the same directory as `sibling`. Files cannot be created outside of the current package. + +Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned `File` object to the action's construction function. + +Note that [predeclared output files](https://bazel.build/extending/rules#files) do not need to be (and cannot be) declared using this function. You can obtain their `File` objects from [`ctx.outputs`](../builtins/ctx.html#outputs) instead. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/computed_dependencies/hash.bzl). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="declare_file.filename"><code>filename</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +If no 'sibling' provided, path of the new file, relative to the current package. Otherwise a base name for a file ('sibling' determines a directory).</td> +</tr> +<tr> +<td id="declare_file.sibling"><code>sibling</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +A file that lives in the same directory as the newly created file. The file must be in the current package.</td> +</tr> +</tbody> +</table> + +## declare_symlink + +``` rule-signature +File actions.declare_symlink(filename, *, sibling=None) +``` + +Declares that the rule or aspect creates a symlink with the given name in the current package. You must create an action that generates this symlink. Bazel will never dereference this symlink and will transfer it verbatim to sandboxes or remote executors. Symlinks inside tree artifacts are not currently supported. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="declare_symlink.filename"><code>filename</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +If no 'sibling' provided, path of the new symlink, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory).</td> +</tr> +<tr> +<td id="declare_symlink.sibling"><code>sibling</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +A file that lives in the same directory as the newly declared symlink.</td> +</tr> +</tbody> +</table> + +## do_nothing + +``` rule-signature +None actions.do_nothing(*, mnemonic, inputs=[]) +``` + +Creates an empty action that neither executes a command nor produces any output, but that is useful for inserting 'extra actions'. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="do_nothing.mnemonic"><code>mnemonic</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A one-word description of the action, for example, CppCompile or GoLink.</td> +</tr> +<tr> +<td id="do_nothing.inputs"><code>inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>[]</code><br /> +List of the input files of the action.</td> +</tr> +</tbody> +</table> + +## expand_template + +``` rule-signature +None actions.expand_template(*, template, output, substitutions={}, is_executable=False, computed_substitutions=unbound) +``` + +Creates a template expansion action. When the action is executed, it will generate a file based on a template. Parts of the template will be replaced using the `substitutions` dictionary, in the order the substitutions are specified. Whenever a key of the dictionary appears in the template (or a result of a previous substitution), it is replaced with the associated value. There is no special syntax for the keys. You may, for example, use curly braces to avoid conflicts (for example, `{KEY}`). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="expand_template.template"><code>template</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The template file, which is a UTF-8 encoded text file.</td> +</tr> +<tr> +<td id="expand_template.output"><code>output</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The output file, which is a UTF-8 encoded text file.</td> +</tr> +<tr> +<td id="expand_template.substitutions"><code>substitutions</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +Substitutions to make when expanding the template.</td> +</tr> +<tr> +<td id="expand_template.is_executable"><code>is_executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether the output file should be executable.</td> +</tr> +<tr> +<td id="expand_template.computed_substitutions"><code>computed_substitutions</code></td> +<td><a href="../builtins/TemplateDict.html" class="anchor">TemplateDict</a>; +default is <code>unbound</code><br /> +Substitutions to make when expanding the template.</td> +</tr> +</tbody> +</table> + +## map_directory + +``` rule-signature +None actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation) +``` + +Creates multiple actions based on the files within one or more input directories, to output one or more output directories. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="map_directory.input_directories"><code>input_directories</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +required<br /> +A dictionary mapping of strings to input directories, as declared by <code>ctx.actions.declare_directory()</code> (only directories are allowed as values here). The values specify the directories that we want expanded to access their files in the implementation function. The keys (strings) act as identifiers to easily reference a specific directory in the implementation function.</td> +</tr> +<tr> +<td id="map_directory.additional_inputs"><code>additional_inputs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary of mapping of strings to additional inputs (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify any additional inputs that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific input from within the implementation function.</td> +</tr> +<tr> +<td id="map_directory.output_directories"><code>output_directories</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +required<br /> +A dictionary mapping of strings to output directories, as declared by <code>ctx.actions.declare_directory()</code>. The values specify the output directories that we want to generate by the actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific output directory from within the implementation function.</td> +</tr> +<tr> +<td id="map_directory.tools"><code>tools</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +required<br /> +A dictionary mapping of strings to tools (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify the tools that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific tool from within the implementation function.</td> +</tr> +<tr> +<td id="map_directory.additional_params"><code>additional_params</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary mapping of strings to additional parameters (only string, boolean and integer values are allowed here). The values specify any additional parameters that we want to make accessible to the implementation function that could be used to influence its behavior. The keys (strings) act as identifiers to easily reference a specific parameter from within the implementation function.</td> +</tr> +<tr> +<td id="map_directory.execution_requirements"><code>execution_requirements</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Information for scheduling the created actions. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys.</td> +</tr> +<tr> +<td id="map_directory.exec_group"><code>exec_group</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Run the created actions on the given exec group's execution platform. If none, uses the target's default execution platform.</td> +</tr> +<tr> +<td id="map_directory.toolchain"><code>toolchain</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> + <p>Toolchain type of the executable or tools used by the created actions.</p> +<p>If executable and tools are not coming from a toolchain, set this parameter to <code>None</code>.</p> +<p>If executable and tools are coming from a toolchain, toolchain type must be set so that the created actions execute on the correct execution platform.</p> +<p>Note that the rule which creates these actions needs to define this toolchain inside its 'rule()' function.</p> +<p>When <code>toolchain</code> and <code>exec_group</code> parameters are both set, <code>exec_group</code> will be used. An error is raised in case the <code>exec_group</code> doesn't specify the same toolchain.</p></td> +</tr> +<tr> +<td id="map_directory.use_default_shell_env"><code>use_default_shell_env</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether the created actions should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>. +<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> +</tr> +<tr> +<td id="map_directory.env"><code>env</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Sets the dictionary of environment variables. +<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> +</tr> +<tr> +<td id="map_directory.mnemonic"><code>mnemonic</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A one-word description of the created actions, for example, CppCompile or GoLink.</td> +</tr> +<tr> +<td id="map_directory.implementation"><code>implementation</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +required<br /> +A Starlark function that gets called after input directories have been built to generate actions that output files to the specified output directories. This function is passed the following arguments: - <ul> - <li><code>template_ctx</code> (positional): A <a - href='../builtins/template_ctx.html'><code>template_ctx</code></a> object that can be used to - create actions.</li> - <li><code>input_directories</code> (keyword-only): A dictionary mapping from the string keys of - the <code>input_directories</code> argument of <code>actions.map_directory()</code> to their - values' corresponding <a href='../builtins/File.html'><code>ExpandedDirectory</code></a> - objects.</li> - <li><code>output_directories</code> (keyword-only): The value of the - <code>output_directories</code> argument of <code>actions.map_directory()</code>; a - dictionary mapping from strings to output directories.</li> - <li><code>additional_inputs</code> (keyword-only): The value of the - <code>additional_inputs</code> argument of <code>actions.map_directory()</code>; a - dictionary mapping from strings to input files.</li> - <li><code>tools</code> (keyword-only): The value of the <code>tools</code> argument of - <code>actions.map_directory()</code>; a dictionary mapping from strings to tools.</li> - <li><code>additional_params</code> (keyword-only): The value of the - <code>additional_params</code> argument of <code>actions.map_directory()</code>; a - dictionary mapping from strings to strings, booleans, or integers.</li> +<li><code>template_ctx</code> (positional): A <a href="../builtins/template_ctx.html"><code>template_ctx</code></a> object that can be used to +create actions.</li> +<li><code>input_directories</code> (keyword-only): A dictionary mapping from the string keys of +the <code>input_directories</code> argument of <code>actions.map_directory()</code> to their +values' corresponding <a href="../builtins/File.html"><code>ExpandedDirectory</code></a> +objects.</li> +<li><code>output_directories</code> (keyword-only): The value of the +<code>output_directories</code> argument of <code>actions.map_directory()</code>; a +dictionary mapping from strings to output directories.</li> +<li><code>additional_inputs</code> (keyword-only): The value of the +<code>additional_inputs</code> argument of <code>actions.map_directory()</code>; a +dictionary mapping from strings to input files.</li> +<li><code>tools</code> (keyword-only): The value of the <code>tools</code> argument of +<code>actions.map_directory()</code>; a dictionary mapping from strings to tools.</li> +<li><code>additional_params</code> (keyword-only): The value of the +<code>additional_params</code> argument of <code>actions.map_directory()</code>; a +dictionary mapping from strings to strings, booleans, or integers.</li> </ul> - -This function must be top-level, i.e. lambdas and nested functions are not allowed. - - </td> - </tr> - </tbody> - </table> - - <h2 id="run">run</h2> - <p><pre class="rule-signature"><code>None</code> 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)</pre></p> - - Creates an action that runs an executable. <a href="https://github.com/bazelbuild/examples/tree/main/rules/actions_run/execute.bzl">See example of use</a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="run.outputs"> - <code>outputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - required<br/> - List of the output files of the action. - </td> - </tr> - <tr> - <td id="run.inputs"> - <code>inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>[]</code><br/> - List or depset of the input files of the action. - </td> - </tr> - <tr> - <td id="run.unused_inputs_list"> - <code>unused_inputs_list</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - File containing list of inputs unused by the action. <p>The content of this file (generally one of the outputs of the action) corresponds to the list of input files that were not used during the whole action execution. Any change in those files must not affect in any way the outputs of the action. - </td> - </tr> - <tr> - <td id="run.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a>; - required<br/> - The executable file to be called by the action. - </td> - </tr> - <tr> - <td id="run.tools"> - <code>tools</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>unbound</code><br/> - List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. <p> -When a list is provided, it can be a heterogenous collection of: +This function must be top-level, i.e. lambdas and nested functions are not allowed.</td> +</tr> +</tbody> +</table> + +## run + +``` rule-signature +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) +``` + +Creates an action that runs an executable. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/actions_run/execute.bzl). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="run.outputs"><code>outputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +required<br /> +List of the output files of the action.</td> +</tr> +<tr> +<td id="run.inputs"><code>inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>[]</code><br /> +List or depset of the input files of the action.</td> +</tr> +<tr> +<td id="run.unused_inputs_list"><code>unused_inputs_list</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +File containing list of inputs unused by the action. +<p>The content of this file (generally one of the outputs of the action) corresponds to the list of input files that were not used during the whole action execution. Any change in those files must not affect in any way the outputs of the action.</p></td> +</tr> +<tr> +<td id="run.executable"><code>executable</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <a href="../core/string.html" class="anchor">string</a>; or <a href="../providers/FilesToRunProvider.html" class="anchor">FilesToRunProvider</a>; +required<br /> +The executable file to be called by the action.</td> +</tr> +<tr> +<td id="run.tools"><code>tools</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>unbound</code><br /> +List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. +<p>When a list is provided, it can be a heterogenous collection of:</p> +<ul> +<li><code>File</code>s</li> +<li><code>FilesToRunProvider</code> instances</li> +<li><code>depset</code>s of <code>File</code>s</li> +</ul> +<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs.</td> +</tr> +<tr> +<td id="run.arguments"><code>arguments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects.</td> +</tr> +<tr> +<td id="run.mnemonic"><code>mnemonic</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A one-word description of the action, for example, CppCompile or GoLink.</td> +</tr> +<tr> +<td id="run.progress_message"><code>progress_message</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain <code>%{label}</code>, <code>%{input}</code>, or <code>%{output}</code> patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient.</td> +</tr> +<tr> +<td id="run.use_default_shell_env"><code>use_default_shell_env</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>. +<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> +</tr> +<tr> +<td id="run.env"><code>env</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Sets the dictionary of environment variables. +<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> +</tr> +<tr> +<td id="run.execution_requirements"><code>execution_requirements</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Information for scheduling the action. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys.</td> +</tr> +<tr> +<td id="run.input_manifests"><code>input_manifests</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; +default is <code>None</code><br /> +Legacy argument. Ignored.</td> +</tr> +<tr> +<td id="run.exec_group"><code>exec_group</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform.</td> +</tr> +<tr> +<td id="run.shadowed_action"><code>shadowed_action</code></td> +<td><a href="../builtins/Action.html" class="anchor">Action</a>; +default is <code>None</code><br /> +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.</td> +</tr> +<tr> +<td id="run.resource_set"><code>resource_set</code></td> +<td>callable; or <code>None</code>; +default is <code>None</code><br /> +A callback function that returns a resource set dictionary, used to estimate resource usage at execution time if this action is run locally. +<p>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:</p> <ul> - <li><code>File</code>s</li> - <li><code>FilesToRunProvider</code> instances</li> - <li><code>depset</code>s of <code>File</code>s</li> +<li>"cpu": number of CPUs; default 1</li> +<li>"memory": in MB; default 250</li> +<li>"local_test": number of local tests; default 1</li> </ul> -<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. -</p> - - </td> - </tr> - <tr> - <td id="run.arguments"> - <code>arguments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects. - </td> - </tr> - <tr> - <td id="run.mnemonic"> - <code>mnemonic</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A one-word description of the action, for example, CppCompile or GoLink. - </td> - </tr> - <tr> - <td id="run.progress_message"> - <code>progress_message</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain <code>%{label}</code>, <code>%{input}</code>, or <code>%{output}</code> patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. - </td> - </tr> - <tr> - <td id="run.use_default_shell_env"> - <code>use_default_shell_env</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. - </td> - </tr> - <tr> - <td id="run.env"> - <code>env</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Sets the dictionary of environment variables.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. - </td> - </tr> - <tr> - <td id="run.execution_requirements"> - <code>execution_requirements</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Information for scheduling the action. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys. - </td> - </tr> - <tr> - <td id="run.input_manifests"> - <code>input_manifests</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; - default is <code>None</code><br/> - Legacy argument. Ignored. - </td> - </tr> - <tr> - <td id="run.exec_group"> - <code>exec_group</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. - </td> - </tr> - <tr> - <td id="run.shadowed_action"> - <code>shadowed_action</code> - </td> - <td> - <a class="anchor" href="../builtins/Action.html">Action</a>; - default is <code>None</code><br/> - 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. - </td> - </tr> - <tr> - <td id="run.resource_set"> - <code>resource_set</code> - </td> - <td> - callable; or <code>None</code>; - default is <code>None</code><br/> - A callback function that returns a resource set dictionary, used to estimate resource usage at execution time if this action is run locally.<p>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:<ul><li>"cpu": number of CPUs; default 1<li>"memory": in MB; default 250<li>"local_test": number of local tests; default 1</ul><p>If this parameter is set to <code>None</code> , the default values are used.<p>The callback must be top-level (lambda and nested functions aren't allowed). - </td> - </tr> - <tr> - <td id="run.toolchain"> - <code>toolchain</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>unbound</code><br/> - <p>Toolchain type of the executable or tools used in this action.</p><p>If executable and tools are not coming from a toolchain, set this parameter to `None`.</p><p>If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform.</p><p>Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function.</p><p>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.</p> - </td> - </tr> - </tbody> - </table> - - <h2 id="run_shell">run_shell</h2> - <p><pre class="rule-signature"><code>None</code> 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)</pre></p> - - Creates an action that runs a shell command. <a href="https://github.com/bazelbuild/examples/tree/main/rules/shell_command/rules.bzl">See example of use</a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="run_shell.outputs"> - <code>outputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - required<br/> - List of the output files of the action. - </td> - </tr> - <tr> - <td id="run_shell.inputs"> - <code>inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>[]</code><br/> - List or depset of the input files of the action. - </td> - </tr> - <tr> - <td id="run_shell.tools"> - <code>tools</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>unbound</code><br/> - List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. <p> -When a list is provided, it can be a heterogenous collection of: +<p>If this parameter is set to <code>None</code> , the default values are used.</p> +<p>The callback must be top-level (lambda and nested functions aren't allowed).</p></td> +</tr> +<tr> +<td id="run.toolchain"><code>toolchain</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>unbound</code><br /> + <p>Toolchain type of the executable or tools used in this action.</p> +<p>If executable and tools are not coming from a toolchain, set this parameter to `None`.</p> +<p>If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform.</p> +<p>Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function.</p> +<p>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.</p></td> +</tr> +</tbody> +</table> + +## run_shell + +``` rule-signature +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) +``` + +Creates an action that runs a shell command. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/shell_command/rules.bzl). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="run_shell.outputs"><code>outputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +required<br /> +List of the output files of the action.</td> +</tr> +<tr> +<td id="run_shell.inputs"><code>inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>[]</code><br /> +List or depset of the input files of the action.</td> +</tr> +<tr> +<td id="run_shell.tools"><code>tools</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>unbound</code><br /> +List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. +<p>When a list is provided, it can be a heterogenous collection of:</p> <ul> - <li><code>File</code>s</li> - <li><code>FilesToRunProvider</code> instances</li> - <li><code>depset</code>s of <code>File</code>s</li> +<li><code>File</code>s</li> +<li><code>FilesToRunProvider</code> instances</li> +<li><code>depset</code>s of <code>File</code>s</li> </ul> -<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. -</p> - - </td> - </tr> - <tr> - <td id="run_shell.arguments"> - <code>arguments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects.<p>Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as <code>$1</code>, <code>$2</code>, etc. Note that since Args objects are flattened before indexing, if there is an Args object of unknown size then all subsequent strings will be at unpredictable indices. It may be useful to use <code>$@</code> (to retrieve all arguments) in conjunction with Args objects of indeterminate size.<p>In the case where <code>command</code> is a list of strings, this parameter may not be used. - </td> - </tr> - <tr> - <td id="run_shell.mnemonic"> - <code>mnemonic</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A one-word description of the action, for example, CppCompile or GoLink. - </td> - </tr> - <tr> - <td id="run_shell.command"> - <code>command</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - Shell command to execute. This may either be a string (preferred) or a sequence of strings <b>(deprecated)</b>.<p>If <code>command</code> is a string, then it is executed as if by <code>sh -c <command> "" <arguments></code> -- that is, the elements in <code>arguments</code> are made available to the command as <code>$1</code>, <code>$2</code> (or <code>%1</code>, <code>%2</code> if using Windows batch), etc. If <code>arguments</code> contains any <a href="#args"><code>actions.args()</code></a> objects, their contents are appended one by one to the command line, so <code>$</code><i>i</i> can refer to individual strings within an Args object. Note that if an Args object of unknown size is passed as part of <code>arguments</code>, then the strings will be at unknown indices; in this case the <code>$@</code> shell substitution (retrieve all arguments) may be useful.<p><b>(Deprecated)</b> If <code>command</code> is a sequence of strings, the first item is the executable to run and the remaining items are its arguments. If this form is used, the <code>arguments</code> parameter must not be supplied. <i>Note that this form is deprecated and will soon be removed. It is disabled with `--incompatible_run_shell_command_string`. Use this flag to verify your code is compatible. </i><p>Bazel uses the same shell to execute the command as it does for genrules. - </td> - </tr> - <tr> - <td id="run_shell.progress_message"> - <code>progress_message</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain <code>%{label}</code>, <code>%{input}</code>, or <code>%{output}</code> patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. - </td> - </tr> - <tr> - <td id="run_shell.use_default_shell_env"> - <code>use_default_shell_env</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. - </td> - </tr> - <tr> - <td id="run_shell.env"> - <code>env</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Sets the dictionary of environment variables.<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment. - </td> - </tr> - <tr> - <td id="run_shell.execution_requirements"> - <code>execution_requirements</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Information for scheduling the action. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys. - </td> - </tr> - <tr> - <td id="run_shell.input_manifests"> - <code>input_manifests</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; - default is <code>None</code><br/> - Legacy argument. Ignored. - </td> - </tr> - <tr> - <td id="run_shell.exec_group"> - <code>exec_group</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. - </td> - </tr> - <tr> - <td id="run_shell.shadowed_action"> - <code>shadowed_action</code> - </td> - <td> - <a class="anchor" href="../builtins/Action.html">Action</a>; - default is <code>None</code><br/> - 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. - </td> - </tr> - <tr> - <td id="run_shell.resource_set"> - <code>resource_set</code> - </td> - <td> - callable; or <code>None</code>; - default is <code>None</code><br/> - A callback function for estimating resource usage if run locally. See<a href="#run.resource_set"><code>ctx.actions.run()</code></a>. - </td> - </tr> - <tr> - <td id="run_shell.toolchain"> - <code>toolchain</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>unbound</code><br/> - <p>Toolchain type of the executable or tools used in this action.</p><p>If executable and tools are not coming from a toolchain, set this parameter to `None`.</p><p>If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform.</p><p>Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function.</p><p>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.</p> - </td> - </tr> - </tbody> - </table> - - <h2 id="symlink">symlink</h2> - <p><pre class="rule-signature"><code>None</code> actions.symlink(*, output, target_file=None, target_path=None, is_executable=False, progress_message=None)</pre></p> - - Creates an action that writes a symlink in the file system.<p>This function must be called with exactly one of <code>target_file</code> or <code>target_path</code> specified.</p><p>When you use <code>target_file</code>, declare <code>output</code> with <a href="#declare_file"><code>declare_file()</code></a> or <a href="#declare_directory"><code>declare_directory()</code></a> and match the type of <code>target_file</code>. This makes the symlink point to <code>target_file</code>. Bazel invalidates the output of this action whenever the target of the symlink or its contents change.</p><p>Otherwise, when you use <code>target_path</code>, declare <code>output</code> with <a href="#declare_symlink"><code>declare_symlink()</code></a>). In this case, the symlink points to <code>target_path</code>. Bazel never resolves the symlink and the output of this action is invalidated only when the text contents of the symlink (that is, the value of <code>readlink()</code>) changes. In particular, this can be used to create a dangling symlink.</p> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="symlink.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The output of this action. - </td> - </tr> - <tr> - <td id="symlink.target_file"> - <code>target_file</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - The File that the output symlink will point to. - </td> - </tr> - <tr> - <td id="symlink.target_path"> - <code>target_path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The exact path that the output symlink will point to. No normalization or other processing is applied. - </td> - </tr> - <tr> - <td id="symlink.is_executable"> - <code>is_executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - May only be used with <code>target_file</code>, not <code>target_path</code>. If true, when the action is executed, the <code>target_file</code>'s path is checked to confirm that it is executable, and an error is reported if it is not. Setting <code>is_executable</code> to False does not mean the target is not executable, just that no verification is done.<p>This feature does not make sense for <code>target_path</code> because dangling symlinks might not exist at build time.</p> - </td> - </tr> - <tr> - <td id="symlink.progress_message"> - <code>progress_message</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Progress message to show to the user during the build. - </td> - </tr> - </tbody> - </table> - - <h2 id="template_dict">template_dict</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/TemplateDict.html">TemplateDict</a> actions.template_dict()</pre></p> - - Returns a TemplateDict object for memory-efficient template expansion. - - <h2 id="write">write</h2> - <p><pre class="rule-signature"><code>None</code> actions.write(output, content, is_executable=False, *, mnemonic=None)</pre></p> - - Creates a file write action. When the action is executed, it will write the given content to a file. This is used to generate files using information available in the analysis phase. If the file is large and with a lot of static content, consider using <a href="#expand_template"><code>expand_template</code></a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="write.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The output file. - </td> - </tr> - <tr> - <td id="write.content"> - <code>content</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Args.html">Args</a>; - required<br/> - the contents of the file. May be a either a string or an <a href="#args"><code>actions.args()</code></a> object. - </td> - </tr> - <tr> - <td id="write.is_executable"> - <code>is_executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether the output file should be executable. - </td> - </tr> - <tr> - <td id="write.mnemonic"> - <code>mnemonic</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A one-word description of the action, for example, CppCompile or GoLink. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs.</td> +</tr> +<tr> +<td id="run_shell.arguments"><code>arguments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects. +<p>Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as <code>$1</code>, <code>$2</code>, etc. Note that since Args objects are flattened before indexing, if there is an Args object of unknown size then all subsequent strings will be at unpredictable indices. It may be useful to use <code>$@</code> (to retrieve all arguments) in conjunction with Args objects of indeterminate size.</p> +<p>In the case where <code>command</code> is a list of strings, this parameter may not be used.</p></td> +</tr> +<tr> +<td id="run_shell.mnemonic"><code>mnemonic</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A one-word description of the action, for example, CppCompile or GoLink.</td> +</tr> +<tr> +<td id="run_shell.command"><code>command</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +Shell command to execute. This may either be a string (preferred) or a sequence of strings <strong>(deprecated)</strong>. +<p>If <code>command</code> is a string, then it is executed as if by <code>sh -c <command> "" <arguments></code> -- that is, the elements in <code>arguments</code> are made available to the command as <code>$1</code>, <code>$2</code> (or <code>%1</code>, <code>%2</code> if using Windows batch), etc. If <code>arguments</code> contains any <a href="#args"><code>actions.args()</code></a> objects, their contents are appended one by one to the command line, so <code>$</code><em>i</em> can refer to individual strings within an Args object. Note that if an Args object of unknown size is passed as part of <code>arguments</code>, then the strings will be at unknown indices; in this case the <code>$@</code> shell substitution (retrieve all arguments) may be useful.</p> +<p><strong>(Deprecated)</strong> If <code>command</code> is a sequence of strings, the first item is the executable to run and the remaining items are its arguments. If this form is used, the <code>arguments</code> parameter must not be supplied. <em>Note that this form is deprecated and will soon be removed. It is disabled with `--incompatible_run_shell_command_string`. Use this flag to verify your code is compatible.</em></p> +<p>Bazel uses the same shell to execute the command as it does for genrules.</p></td> +</tr> +<tr> +<td id="run_shell.progress_message"><code>progress_message</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain <code>%{label}</code>, <code>%{input}</code>, or <code>%{output}</code> patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient.</td> +</tr> +<tr> +<td id="run_shell.use_default_shell_env"><code>use_default_shell_env</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>. +<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> +</tr> +<tr> +<td id="run_shell.env"><code>env</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Sets the dictionary of environment variables. +<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> +</tr> +<tr> +<td id="run_shell.execution_requirements"><code>execution_requirements</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Information for scheduling the action. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys.</td> +</tr> +<tr> +<td id="run_shell.input_manifests"><code>input_manifests</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; +default is <code>None</code><br /> +Legacy argument. Ignored.</td> +</tr> +<tr> +<td id="run_shell.exec_group"><code>exec_group</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform.</td> +</tr> +<tr> +<td id="run_shell.shadowed_action"><code>shadowed_action</code></td> +<td><a href="../builtins/Action.html" class="anchor">Action</a>; +default is <code>None</code><br /> +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.</td> +</tr> +<tr> +<td id="run_shell.resource_set"><code>resource_set</code></td> +<td>callable; or <code>None</code>; +default is <code>None</code><br /> +A callback function for estimating resource usage if run locally. See<a href="#run.resource_set"><code>ctx.actions.run()</code></a>.</td> +</tr> +<tr> +<td id="run_shell.toolchain"><code>toolchain</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>unbound</code><br /> + <p>Toolchain type of the executable or tools used in this action.</p> +<p>If executable and tools are not coming from a toolchain, set this parameter to `None`.</p> +<p>If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform.</p> +<p>Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function.</p> +<p>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.</p></td> +</tr> +</tbody> +</table> + +## symlink + +``` rule-signature +None actions.symlink(*, output, target_file=None, target_path=None, is_executable=False, progress_message=None) +``` + +Creates an action that writes a symlink in the file system. + +This function must be called with exactly one of `target_file` or `target_path` specified. + +When you use `target_file`, declare `output` with [`declare_file()`](#declare_file) or [`declare_directory()`](#declare_directory) and match the type of `target_file`. This makes the symlink point to `target_file`. Bazel invalidates the output of this action whenever the target of the symlink or its contents change. + +Otherwise, when you use `target_path`, declare `output` with [`declare_symlink()`](#declare_symlink)). In this case, the symlink points to `target_path`. Bazel never resolves the symlink and the output of this action is invalidated only when the text contents of the symlink (that is, the value of `readlink()`) changes. In particular, this can be used to create a dangling symlink. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="symlink.output"><code>output</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The output of this action.</td> +</tr> +<tr> +<td id="symlink.target_file"><code>target_file</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +The File that the output symlink will point to.</td> +</tr> +<tr> +<td id="symlink.target_path"><code>target_path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The exact path that the output symlink will point to. No normalization or other processing is applied.</td> +</tr> +<tr> +<td id="symlink.is_executable"><code>is_executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +May only be used with <code>target_file</code>, not <code>target_path</code>. If true, when the action is executed, the <code>target_file</code>'s path is checked to confirm that it is executable, and an error is reported if it is not. Setting <code>is_executable</code> to False does not mean the target is not executable, just that no verification is done. +<p>This feature does not make sense for <code>target_path</code> because dangling symlinks might not exist at build time.</p></td> +</tr> +<tr> +<td id="symlink.progress_message"><code>progress_message</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Progress message to show to the user during the build.</td> +</tr> +</tbody> +</table> + +## template_dict + +``` rule-signature +TemplateDict actions.template_dict() +``` + +Returns a TemplateDict object for memory-efficient template expansion. + +## write + +``` rule-signature +None actions.write(output, content, is_executable=False, *, mnemonic=None) +``` + +Creates a file write action. When the action is executed, it will write the given content to a file. This is used to generate files using information available in the analysis phase. If the file is large and with a lot of static content, consider using [`expand_template`](#expand_template). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="write.output"><code>output</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The output file.</td> +</tr> +<tr> +<td id="write.content"><code>content</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Args.html" class="anchor">Args</a>; +required<br /> +the contents of the file. May be a either a string or an <a href="#args"><code>actions.args()</code></a> object.</td> +</tr> +<tr> +<td id="write.is_executable"><code>is_executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether the output file should be executable.</td> +</tr> +<tr> +<td id="write.mnemonic"><code>mnemonic</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A one-word description of the action, for example, CppCompile or GoLink.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/builtins/apple_platform.mdx b/rules/lib/builtins/apple_platform.mdx index 7dd45d1..6fc1cb3 100644 --- a/rules/lib/builtins/apple_platform.mdx +++ b/rules/lib/builtins/apple_platform.mdx @@ -2,62 +2,68 @@ title: 'apple_platform' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.apple_platform">apple_platform</h1> +# apple_platform {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +Corresponds to Xcode's notion of a platform as would be found in `Xcode.app/Contents/Developer/Platforms`. Each platform represents an Apple platform type (such as iOS or tvOS) combined with one or more related CPU architectures. For example, the iOS simulator platform supports `x86_64` and `i386` architectures. + +Specific instances of this type can be retrieved from the fields of the [apple_common.platform](../toplevel/apple_common.html#platform) struct: + +- `apple_common.platform.ios_device` +- `apple_common.platform.ios_simulator` +- `apple_common.platform.macos` +- `apple_common.platform.tvos_device` +- `apple_common.platform.tvos_simulator` +- `apple_common.platform.watchos_device` +- `apple_common.platform.watchos_simulator` + +More commonly, however, the [apple](../fragments/apple.html) configuration fragment has fields/methods that allow rules to determine the platform for which a target is being built. + +Example: + +``` python -Corresponds to Xcode's notion of a platform as would be found in <code>Xcode.app/Contents/Developer/Platforms</code>. Each platform represents an Apple platform type (such as iOS or tvOS) combined with one or more related CPU architectures. For example, the iOS simulator platform supports <code>x86_64</code> and <code>i386</code> architectures.<p>Specific instances of this type can be retrieved from the fields of the <a href='../toplevel/apple_common.html#platform'>apple_common.platform</a> struct:<br><ul><li><code>apple_common.platform.ios_device</code></li><li><code>apple_common.platform.ios_simulator</code></li><li><code>apple_common.platform.macos</code></li><li><code>apple_common.platform.tvos_device</code></li><li><code>apple_common.platform.tvos_simulator</code></li><li><code>apple_common.platform.watchos_device</code></li><li><code>apple_common.platform.watchos_simulator</code></li></ul><p>More commonly, however, the <a href='../fragments/apple.html'>apple</a> configuration fragment has fields/methods that allow rules to determine the platform for which a target is being built.<p>Example:<br><pre class='language-python'> p = apple_common.platform.ios_device print(p.name_in_plist) # 'iPhoneOS' -</pre> +``` + +## Members + +- [is_device](#is_device) +- [name](#name) +- [name_in_plist](#name_in_plist) +- [platform_type](#platform_type) -<h2>Members</h2> -<ul> - <li> - <a href="#is_device">is_device</a> - </li> - <li> - <a href="#name">name</a> - </li> - <li> - <a href="#name_in_plist">name_in_plist</a> - </li> - <li> - <a href="#platform_type">platform_type</a> - </li> - </ul> +## is_device - <h2 id="is_device">is_device</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> apple_platform.is_device</pre></p> +``` rule-signature +bool apple_platform.is_device +``` - Returns <code>True</code> if this platform is a device platform or <code>False</code> if it is a simulator platform. +Returns `True` if this platform is a device platform or `False` if it is a simulator platform. - <h2 id="name">name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> apple_platform.name</pre></p> +## name - Returns the name aka starlarkKey of this platform. +``` rule-signature +string apple_platform.name +``` - <h2 id="name_in_plist">name_in_plist</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> apple_platform.name_in_plist</pre></p> +Returns the name aka starlarkKey of this platform. - The name of the platform as it appears in the <code>CFBundleSupportedPlatforms</code> entry of an Info.plist file and in Xcode's platforms directory, without the extension (for example, <code>iPhoneOS</code> or <code>iPhoneSimulator</code>).<br>This name, when converted to lowercase (e.g., <code>iphoneos</code>, <code>iphonesimulator</code>), can be passed to Xcode's command-line tools like <code>ibtool</code> and <code>actool</code> when they expect a platform name. +## name_in_plist - <h2 id="platform_type">platform_type</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> apple_platform.platform_type</pre></p> +``` rule-signature +string apple_platform.name_in_plist +``` - Returns the platform type of this platform. +The name of the platform as it appears in the `CFBundleSupportedPlatforms` entry of an Info.plist file and in Xcode's platforms directory, without the extension (for example, `iPhoneOS` or `iPhoneSimulator`). +This name, when converted to lowercase (e.g., `iphoneos`, `iphonesimulator`), can be passed to Xcode's command-line tools like `ibtool` and `actool` when they expect a platform name. +## platform_type -</body> -</html> +``` rule-signature +string apple_platform.platform_type +``` -<!-- {% endraw %} --> +Returns the platform type of this platform. diff --git a/rules/lib/builtins/bazel_module.mdx b/rules/lib/builtins/bazel_module.mdx index 66167cb..e52f7fd 100644 --- a/rules/lib/builtins/bazel_module.mdx +++ b/rules/lib/builtins/bazel_module.mdx @@ -2,59 +2,47 @@ title: 'bazel_module' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.bazel_module">bazel_module</h1> +# bazel_module {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Represents a Bazel module in the external dependency graph. -<h2>Members</h2> -<ul> - <li> - <a href="#is_root">is_root</a> - </li> - <li> - <a href="#name">name</a> - </li> - <li> - <a href="#tags">tags</a> - </li> - <li> - <a href="#version">version</a> - </li> - </ul> +## Members + +- [is_root](#is_root) +- [name](#name) +- [tags](#tags) +- [version](#version) + +## is_root - <h2 id="is_root">is_root</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> bazel_module.is_root</pre></p> +``` rule-signature +bool bazel_module.is_root +``` - Whether this module is the root module. +Whether this module is the root module. - <h2 id="name">name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> bazel_module.name</pre></p> +## name - The name of the module. +``` rule-signature +string bazel_module.name +``` - <h2 id="tags">tags</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/bazel_module_tags.html">bazel_module_tags</a> bazel_module.tags</pre></p> +The name of the module. - The tags in the module related to the module extension currently being processed. +## tags - <h2 id="version">version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> bazel_module.version</pre></p> +``` rule-signature +bazel_module_tags bazel_module.tags +``` - The version of the module. +The tags in the module related to the module extension currently being processed. +## version -</body> -</html> +``` rule-signature +string bazel_module.version +``` -<!-- {% endraw %} --> +The version of the module. diff --git a/rules/lib/builtins/bazel_module_tags.mdx b/rules/lib/builtins/bazel_module_tags.mdx index 40f42b6..d2a7c7e 100644 --- a/rules/lib/builtins/bazel_module_tags.mdx +++ b/rules/lib/builtins/bazel_module_tags.mdx @@ -2,26 +2,9 @@ title: 'bazel_module_tags' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.bazel_module_tags">bazel_module_tags</h1> +# bazel_module_tags {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Contains the tags in a module for the module extension currently being processed. This object has a field for each tag class of the extension, and the value of the field is a list containing an object for each tag instance. This "tag instance" object in turn has a field for each attribute of the tag class. - -When passed as positional arguments to <code>print()</code> or <code>fail()</code>, tag instance objects turn into a meaningful string representation of the form "'install' tag at /home/user/workspace/MODULE.bazel:3:4". This can be used to construct error messages that point to the location of the tag in the module file, e.g. <code>fail("Conflict between", tag1, "and", tag2)</code>. - - - -</body> -</html> - -<!-- {% endraw %} --> +When passed as positional arguments to `print()` or `fail()`, tag instance objects turn into a meaningful string representation of the form "'install' tag at /home/user/workspace/MODULE.bazel:3:4". This can be used to construct error messages that point to the location of the tag in the module file, e.g. `fail("Conflict between", tag1, "and", tag2)`. diff --git a/rules/lib/builtins/configuration.mdx b/rules/lib/builtins/configuration.mdx index 4410f93..37ab4da 100644 --- a/rules/lib/builtins/configuration.mdx +++ b/rules/lib/builtins/configuration.mdx @@ -2,69 +2,62 @@ title: 'configuration' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.configuration">configuration</h1> +# configuration {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +This object holds information about the environment in which the build is running. See the [Rules page](https://bazel.build/extending/rules#configurations) for more on the general concept of configurations. + +## Members + +- [coverage_enabled](#coverage_enabled) +- [default_shell_env](#default_shell_env) +- [host_path_separator](#host_path_separator) +- [short_id](#short_id) +- [test_env](#test_env) + +## coverage_enabled + +``` rule-signature +bool configuration.coverage_enabled +``` -This object holds information about the environment in which the build is running. See the <a href='https://bazel.build/extending/rules#configurations'>Rules page</a> for more on the general concept of configurations. +A boolean that tells whether code coverage is enabled for this run. Note that this does not compute whether a specific rule should be instrumented for code coverage data collection. For that, see the [`ctx.coverage_instrumented`](../builtins/ctx.html#coverage_instrumented) function. -<h2>Members</h2> -<ul> - <li> - <a href="#coverage_enabled">coverage_enabled</a> - </li> - <li> - <a href="#default_shell_env">default_shell_env</a> - </li> - <li> - <a href="#host_path_separator">host_path_separator</a> - </li> - <li> - <a href="#short_id">short_id</a> - </li> - <li> - <a href="#test_env">test_env</a> - </li> - </ul> +## default_shell_env - <h2 id="coverage_enabled">coverage_enabled</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> configuration.coverage_enabled</pre></p> +``` rule-signature +dict configuration.default_shell_env +``` - A boolean that tells whether code coverage is enabled for this run. Note that this does not compute whether a specific rule should be instrumented for code coverage data collection. For that, see the <a href="../builtins/ctx.html#coverage_instrumented"><code>ctx.coverage_instrumented</code></a> function. +A dictionary representing the static local shell environment. It maps variables to their values (strings). - <h2 id="default_shell_env">default_shell_env</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> configuration.default_shell_env</pre></p> +## host_path_separator - A dictionary representing the static local shell environment. It maps variables to their values (strings). +``` rule-signature +string configuration.host_path_separator +``` - <h2 id="host_path_separator">host_path_separator</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> configuration.host_path_separator</pre></p> +Returns the separator for PATH environment variable, which is ':' on Unix. - Returns the separator for PATH environment variable, which is ':' on Unix. +## short_id - <h2 id="short_id">short_id</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> configuration.short_id</pre></p> +``` rule-signature +string configuration.short_id +``` - A short identifier for this configuration understood by the <code>config</code> and </code>query</code> subcommands. -<p>Use this to distinguish different configurations for the same target in a way that is friendly to humans and tool usage, for example in an aspect used by an IDE. Keep in mind the following caveats: <ul> <li>The value may differ across Bazel versions, including patch releases. <li>The value encodes the value of <b>every</b> flag, including those that aren't otherwise relevant for the current target and may thus invalidate caches more frequently. +A short identifier for this configuration understood by the `config` and query subcommands. +Use this to distinguish different configurations for the same target in a way that is friendly to humans and tool usage, for example in an aspect used by an IDE. Keep in mind the following caveats: - <h2 id="test_env">test_env</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> configuration.test_env</pre></p> +The value may differ across Bazel versions, including patch releases. - A dictionary containing user-specified test environment variables and their values, as set by the --test_env options. DO NOT USE! This is not the complete environment! +The value encodes the value of **every** flag, including those that aren't otherwise relevant for the current target and may thus invalidate caches more frequently. +## test_env -</body> -</html> +``` rule-signature +dict configuration.test_env +``` -<!-- {% endraw %} --> +A dictionary containing user-specified test environment variables and their values, as set by the --test_env options. DO NOT USE! This is not the complete environment! diff --git a/rules/lib/builtins/ctx.mdx b/rules/lib/builtins/ctx.mdx index 1e9ebc2..8335a3c 100644 --- a/rules/lib/builtins/ctx.mdx +++ b/rules/lib/builtins/ctx.mdx @@ -2,624 +2,572 @@ title: 'ctx' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ctx">ctx</h1> +# ctx {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A context object that is passed to the implementation function for a rule or aspect. It provides access to the information and methods needed to analyze the current target.<p>In particular, it lets the implementation function access the current target's label, attributes, configuration, and the providers of its dependencies. It has methods for declaring output files and the actions that produce them.<p>Context objects essentially live for the duration of the call to the implementation function. It is not useful to access these objects outside of their associated function. See the <a href='https://bazel.build/extending/rules#implementation_function'>Rules page</a> for more information. - -<h2>Members</h2> -<ul> - <li> - <a href="#actions">actions</a> - </li> - <li> - <a href="#aspect_ids">aspect_ids</a> - </li> - <li> - <a href="#attr">attr</a> - </li> - <li> - <a href="#bin_dir">bin_dir</a> - </li> - <li> - <a href="#build_file_path">build_file_path</a> - </li> - <li> - <a href="#build_setting_value">build_setting_value</a> - </li> - <li> - <a href="#configuration">configuration</a> - </li> - <li> - <a href="#coverage_instrumented">coverage_instrumented</a> - </li> - <li> - <a href="#created_actions">created_actions</a> - </li> - <li> - <a href="#disabled_features">disabled_features</a> - </li> - <li> - <a href="#exec_groups">exec_groups</a> - </li> - <li> - <a href="#executable">executable</a> - </li> - <li> - <a href="#expand_location">expand_location</a> - </li> - <li> - <a href="#expand_make_variables">expand_make_variables</a> - </li> - <li> - <a href="#features">features</a> - </li> - <li> - <a href="#file">file</a> - </li> - <li> - <a href="#files">files</a> - </li> - <li> - <a href="#fragments">fragments</a> - </li> - <li> - <a href="#genfiles_dir">genfiles_dir</a> - </li> - <li> - <a href="#info_file">info_file</a> - </li> - <li> - <a href="#label">label</a> - </li> - <li> - <a href="#outputs">outputs</a> - </li> - <li> - <a href="#resolve_command">resolve_command</a> - </li> - <li> - <a href="#resolve_tools">resolve_tools</a> - </li> - <li> - <a href="#rule">rule</a> - </li> - <li> - <a href="#runfiles">runfiles</a> - </li> - <li> - <a href="#split_attr">split_attr</a> - </li> - <li> - <a href="#super">super</a> - </li> - <li> - <a href="#target_platform_has_constraint">target_platform_has_constraint</a> - </li> - <li> - <a href="#toolchains">toolchains</a> - </li> - <li> - <a href="#var">var</a> - </li> - <li> - <a href="#version_file">version_file</a> - </li> - <li> - <a href="#workspace_name">workspace_name</a> - </li> - </ul> - - <h2 id="actions">actions</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/actions.html">actions</a> ctx.actions</pre></p> - - Contains methods for declaring output files and the actions that produce them. - - <h2 id="aspect_ids">aspect_ids</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> ctx.aspect_ids</pre></p> - - A list of ids for all aspects applied to the target. Only available in aspect implementation functions. - - <h2 id="attr">attr</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.attr</pre></p> - - A struct to access the values of the <a href='https://bazel.build/extending/rules#attributes'>attributes</a>. The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the <a href='../globals/bzl.html#rule.attrs'><code>attrs</code> dict</a> provided to the <a href='../globals/bzl.html#rule'><code>rule</code> function</a>. <a href="https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl">See example of use</a>. - - <h2 id="bin_dir">bin_dir</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/root.html">root</a> ctx.bin_dir</pre></p> - - The root corresponding to bin directory. - - <h2 id="build_file_path">build_file_path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ctx.build_file_path</pre></p> - - Deprecated: Use <code>ctx.label.package + '/BUILD'</code>. The path to the BUILD file for this rule, relative to the source root. - - <h2 id="build_setting_value">build_setting_value</h2> - <p><pre class="rule-signature">unknown ctx.build_setting_value</pre></p> - - Value of the build setting represented by the current target. If this isn't the context for an instance of a rule that sets the <a href="https://bazel.build/extending/config#rule-parameter"><code>build_setting</code></a> attribute, reading this is an error. - - <h2 id="configuration">configuration</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/configuration.html">configuration</a> ctx.configuration</pre></p> - - The default configuration. See the <a href="../builtins/configuration.html">configuration</a> type for more details. - - <h2 id="coverage_instrumented">coverage_instrumented</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> ctx.coverage_instrumented(target=None)</pre></p> - - Returns whether code coverage instrumentation should be generated when performing compilation actions for this rule or, if <code>target</code> is provided, the rule specified by that Target. (If a non-rule or a Starlark rule Target is provided, this returns False.) Checks if the sources of the current rule (if no Target is provided) or the sources of Target should be instrumented based on the --instrumentation_filter and --instrument_test_targets config settings. This differs from <code>coverage_enabled</code> in the <a href="../builtins/configuration.html">configuration</a>, which notes whether coverage data collection is enabled for the entire run, but not whether a specific target should be instrumented. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="coverage_instrumented.target"> - <code>target</code> - </td> - <td> - <a class="anchor" href="../builtins/Target.html">Target</a>; or <code>None</code>; - default is <code>None</code><br/> - A Target specifying a rule. If not provided, defaults to the current rule. - </td> - </tr> - </tbody> - </table> - - <h2 id="created_actions">created_actions</h2> - <p><pre class="rule-signature">StarlarkValue ctx.created_actions()</pre></p> - - For rules with <a href="../globals/bzl.html#rule._skylark_testable">_skylark_testable</a> set to <code>True</code>, this returns an <code>Actions</code> provider representing all actions created so far for the current rule. For all other rules, returns <code>None</code>. Note that the provider is not updated when subsequent actions are created, so you will have to call this function again if you wish to inspect them. <br/><br/>This is intended to help write tests for rule-implementation helper functions, which may take in a <code>ctx</code> object and create actions on it. - - <h2 id="disabled_features">disabled_features</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> ctx.disabled_features</pre></p> - - The set of features that are explicitly disabled by the user for this rule. - - <h2 id="exec_groups">exec_groups</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/ExecGroupCollection.html">ExecGroupCollection</a> ctx.exec_groups</pre></p> - - A collection of the execution groups available for this rule, indexed by their name. Access with <code>ctx.exec_groups[name_of_group]</code>. - - <h2 id="executable">executable</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.executable</pre></p> - - A <code>struct</code> containing executable files defined in <a href='../toplevel/attr.html#label'>label type attributes</a> marked as <a href='../toplevel/attr.html#label.executable'><code>executable=True</code></a>. The struct fields correspond to the attribute names. Each value in the struct is either a <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an optional attribute is not specified in the rule then the corresponding struct value is <code>None</code>. If a label type is not marked as <code>executable=True</code>, no corresponding struct field is generated. <a href="https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl">See example of use</a>. - - <h2 id="expand_location">expand_location</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ctx.expand_location(input, targets=[])</pre></p> - - Expands all <code>$(location ...)</code> templates in the given string by replacing <code>$(location //x)</code> with the path of the output file of target //x. Expansion only works for labels that point to direct dependencies of this rule or that are explicitly listed in the optional argument <code>targets</code>. <br/><br/><code>$(location ...)</code> will cause an error if the referenced target has multiple outputs. In this case, please use <code>$(locations ...)</code> since it produces a space-separated list of output paths. It can be safely used for a single output file, too.<br/><br/>This function is useful to let the user specify a command in a BUILD file (like for <code>genrule</code>). In other cases, it is often better to manipulate labels directly. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="expand_location.input"> - <code>input</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - String to be expanded. - </td> - </tr> - <tr> - <td id="expand_location.targets"> - <code>targets</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Target.html">Target</a>s; - default is <code>[]</code><br/> - List of targets for additional lookup information. These are expanded as follows: A target with a single file in <code>DefaultInfo.files</code> expands to that file. Other targets expand to their <code>DefaultInfo.executable</code> file if set and if <code>--incompatible_locations_prefers_executable</code> is enabled, otherwise they expand to <code>DefaultInfo.files</code>. - </td> - </tr> - </tbody> - </table> - May return <code>None</code>. - - <h2 id="expand_make_variables">expand_make_variables</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ctx.expand_make_variables(attribute_name, command, additional_substitutions)</pre></p> - - <b>Deprecated.</b> Use <a href="../builtins/ctx.html#var">ctx.var</a> to access the variables instead.<br>Returns a string after expanding all references to "Make variables". The variables must have the following format: <code>$(VAR_NAME)</code>. Also, <code>$$VAR_NAME</code> expands to <code>$VAR_NAME</code>. Examples:<pre class=language-python> +{% include "\_buttons.html" %} +A context object that is passed to the implementation function for a rule or aspect. It provides access to the information and methods needed to analyze the current target. + +In particular, it lets the implementation function access the current target's label, attributes, configuration, and the providers of its dependencies. It has methods for declaring output files and the actions that produce them. + +Context objects essentially live for the duration of the call to the implementation function. It is not useful to access these objects outside of their associated function. See the [Rules page](https://bazel.build/extending/rules#implementation_function) for more information. + +## Members + +- [actions](#actions) +- [aspect_ids](#aspect_ids) +- [attr](#attr) +- [bin_dir](#bin_dir) +- [build_file_path](#build_file_path) +- [build_setting_value](#build_setting_value) +- [configuration](#configuration) +- [coverage_instrumented](#coverage_instrumented) +- [created_actions](#created_actions) +- [disabled_features](#disabled_features) +- [exec_groups](#exec_groups) +- [executable](#executable) +- [expand_location](#expand_location) +- [expand_make_variables](#expand_make_variables) +- [features](#features) +- [file](#file) +- [files](#files) +- [fragments](#fragments) +- [genfiles_dir](#genfiles_dir) +- [info_file](#info_file) +- [label](#label) +- [outputs](#outputs) +- [resolve_command](#resolve_command) +- [resolve_tools](#resolve_tools) +- [rule](#rule) +- [runfiles](#runfiles) +- [split_attr](#split_attr) +- [super](#super) +- [target_platform_has_constraint](#target_platform_has_constraint) +- [toolchains](#toolchains) +- [var](#var) +- [version_file](#version_file) +- [workspace_name](#workspace_name) + +## actions + +``` rule-signature +actions ctx.actions +``` + +Contains methods for declaring output files and the actions that produce them. + +## aspect_ids + +``` rule-signature +list ctx.aspect_ids +``` + +A list of ids for all aspects applied to the target. Only available in aspect implementation functions. + +## attr + +``` rule-signature +struct ctx.attr +``` + +A struct to access the values of the [attributes](https://bazel.build/extending/rules#attributes). The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the [`attrs` dict](../globals/bzl.html#rule.attrs) provided to the [`rule` function](../globals/bzl.html#rule). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl). + +## bin_dir + +``` rule-signature +root ctx.bin_dir +``` + +The root corresponding to bin directory. + +## build_file_path + +``` rule-signature +string ctx.build_file_path +``` + +Deprecated: Use `ctx.label.package + '/BUILD'`. The path to the BUILD file for this rule, relative to the source root. + +## build_setting_value + +``` rule-signature +unknown ctx.build_setting_value +``` + +Value of the build setting represented by the current target. If this isn't the context for an instance of a rule that sets the [`build_setting`](https://bazel.build/extending/config#rule-parameter) attribute, reading this is an error. + +## configuration + +``` rule-signature +configuration ctx.configuration +``` + +The default configuration. See the [configuration](../builtins/configuration.html) type for more details. + +## coverage_instrumented + +``` rule-signature +bool ctx.coverage_instrumented(target=None) +``` + +Returns whether code coverage instrumentation should be generated when performing compilation actions for this rule or, if `target` is provided, the rule specified by that Target. (If a non-rule or a Starlark rule Target is provided, this returns False.) Checks if the sources of the current rule (if no Target is provided) or the sources of Target should be instrumented based on the --instrumentation_filter and --instrument_test_targets config settings. This differs from `coverage_enabled` in the [configuration](../builtins/configuration.html), which notes whether coverage data collection is enabled for the entire run, but not whether a specific target should be instrumented. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="coverage_instrumented.target"><code>target</code></td> +<td><a href="../builtins/Target.html" class="anchor">Target</a>; or <code>None</code>; +default is <code>None</code><br /> +A Target specifying a rule. If not provided, defaults to the current rule.</td> +</tr> +</tbody> +</table> + +## created_actions + +``` rule-signature +StarlarkValue ctx.created_actions() +``` + +For rules with [\_skylark_testable](../globals/bzl.html#rule._skylark_testable) set to `True`, this returns an `Actions` provider representing all actions created so far for the current rule. For all other rules, returns `None`. Note that the provider is not updated when subsequent actions are created, so you will have to call this function again if you wish to inspect them. + +This is intended to help write tests for rule-implementation helper functions, which may take in a `ctx` object and create actions on it. + +## disabled_features + +``` rule-signature +list ctx.disabled_features +``` + +The set of features that are explicitly disabled by the user for this rule. + +## exec_groups + +``` rule-signature +ExecGroupCollection ctx.exec_groups +``` + +A collection of the execution groups available for this rule, indexed by their name. Access with `ctx.exec_groups[name_of_group]`. + +## executable + +``` rule-signature +struct ctx.executable +``` + +A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). + +## expand_location + +``` rule-signature +string ctx.expand_location(input, targets=[]) +``` + +Expands all `$(location ...)` templates in the given string by replacing `$(location //x)` with the path of the output file of target //x. Expansion only works for labels that point to direct dependencies of this rule or that are explicitly listed in the optional argument `targets`. + +`$(location ...)` will cause an error if the referenced target has multiple outputs. In this case, please use `$(locations ...)` since it produces a space-separated list of output paths. It can be safely used for a single output file, too. + +This function is useful to let the user specify a command in a BUILD file (like for `genrule`). In other cases, it is often better to manipulate labels directly. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="expand_location.input"><code>input</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +String to be expanded.</td> +</tr> +<tr> +<td id="expand_location.targets"><code>targets</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Target.html" class="anchor">Target</a>s; +default is <code>[]</code><br /> +List of targets for additional lookup information. These are expanded as follows: A target with a single file in <code>DefaultInfo.files</code> expands to that file. Other targets expand to their <code>DefaultInfo.executable</code> file if set and if <code>--incompatible_locations_prefers_executable</code> is enabled, otherwise they expand to <code>DefaultInfo.files</code>.</td> +</tr> +</tbody> +</table> + +May return `None`. + +## expand_make_variables + +``` rule-signature +string ctx.expand_make_variables(attribute_name, command, additional_substitutions) +``` + +**Deprecated.** Use [ctx.var](../builtins/ctx.html#var) to access the variables instead. +Returns a string after expanding all references to "Make variables". The variables must have the following format: `$(VAR_NAME)`. Also, `$$VAR_NAME` expands to `$VAR_NAME`. Examples: + +``` python + ctx.expand_make_variables("cmd", "$(MY_VAR)", {"MY_VAR": "Hi"}) # == "Hi" ctx.expand_make_variables("cmd", "$$PWD", {}) # == "$PWD" -</pre>Additional variables may come from other places, such as configurations. Note that this function is experimental. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="expand_make_variables.attribute_name"> - <code>attribute_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The attribute name. Used for error reporting. - </td> - </tr> - <tr> - <td id="expand_make_variables.command"> - <code>command</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The expression to expand. It can contain references to "Make variables". - </td> - </tr> - <tr> - <td id="expand_make_variables.additional_substitutions"> - <code>additional_substitutions</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - required<br/> - Additional substitutions to make beyond the default make variables. - </td> - </tr> - </tbody> - </table> - - <h2 id="features">features</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> ctx.features</pre></p> - - The set of features that are explicitly enabled by the user for this rule. <a href="https://github.com/bazelbuild/examples/blob/main/rules/features/rule.bzl">See example of use</a>. - - <h2 id="file">file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.file</pre></p> - - A <code>struct</code> containing files defined in <a href='../toplevel/attr.html#label'>label type attributes</a> marked as <a href='../toplevel/attr.html#label.allow_single_file'><code>allow_single_file</code></a>. The struct fields correspond to the attribute names. The struct value is always a <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an optional attribute is not specified in the rule then the corresponding struct value is <code>None</code>. If a label type is not marked as <code>allow_single_file</code>, no corresponding struct field is generated. It is a shortcut for:<pre class=language-python>list(ctx.attr.<ATTR>.files)[0]</pre>In other words, use <code>file</code> to access the (singular) <a href="https://bazel.build/extending/rules#requesting_output_files">default output</a> of a dependency. <a href="https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl">See example of use</a>. - - <h2 id="files">files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.files</pre></p> - - A <code>struct</code> containing files defined in <a href='../toplevel/attr.html#label'>label</a> or <a href='../toplevel/attr.html#label_list'>label list</a> type attributes. The struct fields correspond to the attribute names. The struct values are <code>list</code> of <a href='../builtins/File.html'><code>File</code></a>s. It is a shortcut for:<pre class=language-python>[f for t in ctx.attr.<ATTR> for f in t.files]</pre> In other words, use <code>files</code> to access the <a href="https://bazel.build/extending/rules#requesting_output_files"> default outputs</a> of a dependency. <a href="https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl">See example of use</a>. - - <h2 id="fragments">fragments</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/fragments.html">fragments</a> ctx.fragments</pre></p> - - Allows access to configuration fragments in target configuration. - - <h2 id="genfiles_dir">genfiles_dir</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/root.html">root</a> ctx.genfiles_dir</pre></p> - - The root corresponding to genfiles directory. - - <h2 id="info_file">info_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> ctx.info_file</pre></p> - - The file that is used to hold the non-volatile workspace status for the current build request. See documentation for --workspace_status_command for more information. - - <h2 id="label">label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> ctx.label</pre></p> - - The label of the target currently being analyzed. - - <h2 id="outputs">outputs</h2> - <p><pre class="rule-signature">structure ctx.outputs</pre></p> - - A pseudo-struct containing all the predeclared output files, represented by <a href='../builtins/File.html'><code>File</code></a> objects. See the <a href='https://bazel.build/extending/rules#files'>Rules page</a> for more information and examples.<p>This field does not exist on aspect contexts, since aspects do not have predeclared outputs.<p>The fields of this object are defined as follows. It is an error if two outputs produce the same field name or have the same label.<ul><li> If the rule declares an <a href='../globals/bzl.html#rule.outputs'><code>outputs</code></a> dict, then for every entry in the dict, there is a field whose name is the key and whose value is the corresponding <code>File</code>.<li>For every attribute of type <a href='../toplevel/attr.html#output'><code>attr.output</code></a> that the rule declares, there is a field whose name is the attribute's name. If the target specified a label for that attribute, then the field value is the corresponding <code>File</code>; otherwise the field value is <code>None</code>.<li>For every attribute of type <a href='../toplevel/attr.html#output_list'><code>attr.output_list</code></a> that the rule declares, there is a field whose name is the attribute's name. The field value is a list of <code>File</code> objects corresponding to the labels given for that attribute in the target, or an empty list if the attribute was not specified in the target.<li><b>(Deprecated)</b> If the rule is marked <a href='../globals/bzl.html#rule.executable'><code>executable</code></a> or <a href='../globals/bzl.html#rule.test'><code>test</code></a>, there is a field named <code>"executable"</code>, which is the default executable. It is recommended that instead of using this, you pass another file (either predeclared or not) to the <code>executable</code> arg of <a href='../providers/DefaultInfo.html'><code>DefaultInfo</code></a>.</ul> - - <h2 id="resolve_command">resolve_command</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> ctx.resolve_command(*, command='', attribute=None, expand_locations=False, make_variables=None, tools=[], label_dict={}, execution_requirements={})</pre></p> - - <i>(Experimental)</i> Returns a tuple <code>(inputs, command, empty list)</code> of the list of resolved inputs and the argv list for the resolved command both of them suitable for passing as the same-named arguments of the <code>ctx.action</code> method.<br/><b>Note for Windows users</b>: this method requires Bash (MSYS2). Consider using <code>resolve_tools()</code> instead (if that fits your needs). The empty list is returned as the third member of the tuple for backwards compatibility. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="resolve_command.command"> - <code>command</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Command to resolve. - </td> - </tr> - <tr> - <td id="resolve_command.attribute"> - <code>attribute</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Name of the associated attribute for which to issue an error, or None. - </td> - </tr> - <tr> - <td id="resolve_command.expand_locations"> - <code>expand_locations</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Shall we expand $(location) variables? See <a href="#expand_location">ctx.expand_location()</a> for more details. - </td> - </tr> - <tr> - <td id="resolve_command.make_variables"> - <code>make_variables</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Make variables to expand, or None. - </td> - </tr> - <tr> - <td id="resolve_command.tools"> - <code>tools</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Target.html">Target</a>s; - default is <code>[]</code><br/> - List of tools (list of targets). - </td> - </tr> - <tr> - <td id="resolve_command.label_dict"> - <code>label_dict</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - Dictionary of resolved labels and the corresponding list of Files (a dict of Label : list of Files). - </td> - </tr> - <tr> - <td id="resolve_command.execution_requirements"> - <code>execution_requirements</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - Information for scheduling the action to resolve this command. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys. - </td> - </tr> - </tbody> - </table> - - <h2 id="resolve_tools">resolve_tools</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> ctx.resolve_tools(*, tools=[])</pre></p> - - Returns a tuple <code>(inputs, empty list)</code> of the depset of resolved inputs required to run the tools, suitable for passing as the same-named argument of the <code>ctx.actions.run</code> and <code>ctx.actions.run_shell</code> methods. <br/><br/>In contrast to <code>ctx.resolve_command</code>, this method does not require that Bash be installed on the machine, so it's suitable for rules built on Windows. The empty list is returned as part of the tuple for backward compatibility. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="resolve_tools.tools"> - <code>tools</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Target.html">Target</a>s; - default is <code>[]</code><br/> - List of tools (list of targets). - </td> - </tr> - </tbody> - </table> - - <h2 id="rule">rule</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/rule_attributes.html">rule_attributes</a> ctx.rule</pre></p> - - Rule attributes descriptor for the rule that the aspect is applied to. Only available in aspect implementation functions. - - <h2 id="runfiles">runfiles</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> ctx.runfiles(files=[], transitive_files=None, collect_data=False, collect_default=False, symlinks={}, root_symlinks={})</pre></p> - - Creates a runfiles object. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="runfiles.files"> - <code>files</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - The list of files to be added to the runfiles. - </td> - </tr> - <tr> - <td id="runfiles.transitive_files"> - <code>transitive_files</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <code>None</code>; - default is <code>None</code><br/> - The (transitive) set of files to be added to the runfiles. The depset should use the <code>default</code> order (which, as the name implies, is the default). - </td> - </tr> - <tr> - <td id="runfiles.collect_data"> - <code>collect_data</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - <b>Use of this parameter is not recommended. See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a></b>. <p>Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes. - </td> - </tr> - <tr> - <td id="runfiles.collect_default"> - <code>collect_default</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - <b>Use of this parameter is not recommended. See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a></b>. <p>Whether to collect the default runfiles from the dependencies in srcs, data and deps attributes. - </td> - </tr> - <tr> - <td id="runfiles.symlinks"> - <code>symlinks</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <a class="anchor" href="../builtins/depset.html">depset</a> of <a class="anchor" href="../builtins/SymlinkEntry.html">SymlinkEntry</a>s; - default is <code>{}</code><br/> - Either a SymlinkEntry depset or the map of symlinks to be added to the runfiles. Symlinks are always added under the main workspace's runfiles directory (e.g. <code><runfiles_root>/_main/<symlink_path></code>, <b>not</b> the directory corresponding to the current target's repository. See <a href="https://bazel.build/extending/rules#runfiles_symlinks">Runfiles symlinks</a> in the rules guide. - </td> - </tr> - <tr> - <td id="runfiles.root_symlinks"> - <code>root_symlinks</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <a class="anchor" href="../builtins/depset.html">depset</a> of <a class="anchor" href="../builtins/SymlinkEntry.html">SymlinkEntry</a>s; - default is <code>{}</code><br/> - Either a SymlinkEntry depset or a map of symlinks to be added to the runfiles. See <a href="https://bazel.build/extending/rules#runfiles_symlinks">Runfiles symlinks</a> in the rules guide. - </td> - </tr> - </tbody> - </table> - - <h2 id="split_attr">split_attr</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> ctx.split_attr</pre></p> - - A struct to access the values of attributes with split configurations. If the attribute is a label list, the value of split_attr is a dict of the keys of the split (as strings) to lists of the ConfiguredTargets in that branch of the split. If the attribute is a label, then the value of split_attr is a dict of the keys of the split (as strings) to single ConfiguredTargets. Attributes with split configurations still appear in the attr struct, but their values will be single lists with all the branches of the split merged together. - - <h2 id="super">super</h2> - <p><pre class="rule-signature">unknown ctx.super()</pre></p> - - Experimental: Calls parent's implementation function and returns its providers - - <h2 id="target_platform_has_constraint">target_platform_has_constraint</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> ctx.target_platform_has_constraint(constraintValue)</pre></p> - - Returns true if the given constraint value is part of the current target platform. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="target_platform_has_constraint.constraintValue"> - <code>constraintValue</code> - </td> - <td> - <a class="anchor" href="../providers/ConstraintValueInfo.html">ConstraintValueInfo</a>; - required<br/> - The constraint value to check the target platform against. - </td> - </tr> - </tbody> - </table> - - <h2 id="toolchains">toolchains</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/ToolchainContext.html">ToolchainContext</a> ctx.toolchains</pre></p> - - Toolchains for the default exec group of this rule. - - <h2 id="var">var</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> ctx.var</pre></p> - - Dictionary (String to String) of configuration variables. - - <h2 id="version_file">version_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> ctx.version_file</pre></p> - - The file that is used to hold the volatile workspace status for the current build request. See documentation for --workspace_status_command for more information. - - <h2 id="workspace_name">workspace_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ctx.workspace_name</pre></p> - - The name of the workspace, which is effectively the execution root name and runfiles prefix for the main repo. If <code>--enable_bzlmod</code> is on, this is the fixed string <code>_main</code>. Otherwise, this is the workspace name as defined in the WORKSPACE file. - - -</body> -</html> - -<!-- {% endraw %} --> +``` + +Additional variables may come from other places, such as configurations. Note that this function is experimental. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="expand_make_variables.attribute_name"><code>attribute_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The attribute name. Used for error reporting.</td> +</tr> +<tr> +<td id="expand_make_variables.command"><code>command</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The expression to expand. It can contain references to "Make variables".</td> +</tr> +<tr> +<td id="expand_make_variables.additional_substitutions"><code>additional_substitutions</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +required<br /> +Additional substitutions to make beyond the default make variables.</td> +</tr> +</tbody> +</table> + +## features + +``` rule-signature +list ctx.features +``` + +The set of features that are explicitly enabled by the user for this rule. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/features/rule.bzl). + +## file + +``` rule-signature +struct ctx.file +``` + +A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: + +``` python +list(ctx.attr.<ATTR>.files)[0] +``` + +In other words, use `file` to access the (singular) [default output](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). + +## files + +``` rule-signature +struct ctx.files +``` + +A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.html)s. It is a shortcut for: + +``` python +[f for t in ctx.attr.<ATTR> for f in t.files] +``` + +In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). + +## fragments + +``` rule-signature +fragments ctx.fragments +``` + +Allows access to configuration fragments in target configuration. + +## genfiles_dir + +``` rule-signature +root ctx.genfiles_dir +``` + +The root corresponding to genfiles directory. + +## info_file + +``` rule-signature +File ctx.info_file +``` + +The file that is used to hold the non-volatile workspace status for the current build request. See documentation for --workspace_status_command for more information. + +## label + +``` rule-signature +Label ctx.label +``` + +The label of the target currently being analyzed. + +## outputs + +``` rule-signature +structure ctx.outputs +``` + +A pseudo-struct containing all the predeclared output files, represented by [`File`](../builtins/File.html) objects. See the [Rules page](https://bazel.build/extending/rules#files) for more information and examples. + +This field does not exist on aspect contexts, since aspects do not have predeclared outputs. + +The fields of this object are defined as follows. It is an error if two outputs produce the same field name or have the same label. + +- If the rule declares an [`outputs`](../globals/bzl.html#rule.outputs) dict, then for every entry in the dict, there is a field whose name is the key and whose value is the corresponding `File`. +- For every attribute of type [`attr.output`](../toplevel/attr.html#output) that the rule declares, there is a field whose name is the attribute's name. If the target specified a label for that attribute, then the field value is the corresponding `File`; otherwise the field value is `None`. +- For every attribute of type [`attr.output_list`](../toplevel/attr.html#output_list) that the rule declares, there is a field whose name is the attribute's name. The field value is a list of `File` objects corresponding to the labels given for that attribute in the target, or an empty list if the attribute was not specified in the target. +- **(Deprecated)** If the rule is marked [`executable`](../globals/bzl.html#rule.executable) or [`test`](../globals/bzl.html#rule.test), there is a field named `"executable"`, which is the default executable. It is recommended that instead of using this, you pass another file (either predeclared or not) to the `executable` arg of [`DefaultInfo`](../providers/DefaultInfo.html). + +## resolve_command + +``` rule-signature +tuple ctx.resolve_command(*, command='', attribute=None, expand_locations=False, make_variables=None, tools=[], label_dict={}, execution_requirements={}) +``` + +*(Experimental)* Returns a tuple `(inputs, command, empty list)` of the list of resolved inputs and the argv list for the resolved command both of them suitable for passing as the same-named arguments of the `ctx.action` method. +**Note for Windows users**: this method requires Bash (MSYS2). Consider using `resolve_tools()` instead (if that fits your needs). The empty list is returned as the third member of the tuple for backwards compatibility. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="resolve_command.command"><code>command</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Command to resolve.</td> +</tr> +<tr> +<td id="resolve_command.attribute"><code>attribute</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Name of the associated attribute for which to issue an error, or None.</td> +</tr> +<tr> +<td id="resolve_command.expand_locations"><code>expand_locations</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Shall we expand $(location) variables? See <a href="#expand_location">ctx.expand_location()</a> for more details.</td> +</tr> +<tr> +<td id="resolve_command.make_variables"><code>make_variables</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Make variables to expand, or None.</td> +</tr> +<tr> +<td id="resolve_command.tools"><code>tools</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Target.html" class="anchor">Target</a>s; +default is <code>[]</code><br /> +List of tools (list of targets).</td> +</tr> +<tr> +<td id="resolve_command.label_dict"><code>label_dict</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +Dictionary of resolved labels and the corresponding list of Files (a dict of Label : list of Files).</td> +</tr> +<tr> +<td id="resolve_command.execution_requirements"><code>execution_requirements</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +Information for scheduling the action to resolve this command. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys.</td> +</tr> +</tbody> +</table> + +## resolve_tools + +``` rule-signature +tuple ctx.resolve_tools(*, tools=[]) +``` + +Returns a tuple `(inputs, empty list)` of the depset of resolved inputs required to run the tools, suitable for passing as the same-named argument of the `ctx.actions.run` and `ctx.actions.run_shell` methods. + +In contrast to `ctx.resolve_command`, this method does not require that Bash be installed on the machine, so it's suitable for rules built on Windows. The empty list is returned as part of the tuple for backward compatibility. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="resolve_tools.tools"><code>tools</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Target.html" class="anchor">Target</a>s; +default is <code>[]</code><br /> +List of tools (list of targets).</td> +</tr> +</tbody> +</table> + +## rule + +``` rule-signature +rule_attributes ctx.rule +``` + +Rule attributes descriptor for the rule that the aspect is applied to. Only available in aspect implementation functions. + +## runfiles + +``` rule-signature +runfiles ctx.runfiles(files=[], transitive_files=None, collect_data=False, collect_default=False, symlinks={}, root_symlinks={}) +``` + +Creates a runfiles object. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="runfiles.files"><code>files</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +The list of files to be added to the runfiles.</td> +</tr> +<tr> +<td id="runfiles.transitive_files"><code>transitive_files</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <code>None</code>; +default is <code>None</code><br /> +The (transitive) set of files to be added to the runfiles. The depset should use the <code>default</code> order (which, as the name implies, is the default).</td> +</tr> +<tr> +<td id="runfiles.collect_data"><code>collect_data</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +<strong>Use of this parameter is not recommended. See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a></strong>. +<p>Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes.</p></td> +</tr> +<tr> +<td id="runfiles.collect_default"><code>collect_default</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +<strong>Use of this parameter is not recommended. See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a></strong>. +<p>Whether to collect the default runfiles from the dependencies in srcs, data and deps attributes.</p></td> +</tr> +<tr> +<td id="runfiles.symlinks"><code>symlinks</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <a href="../builtins/depset.html" class="anchor">depset</a> of <a href="../builtins/SymlinkEntry.html" class="anchor">SymlinkEntry</a>s; +default is <code>{}</code><br /> +Either a SymlinkEntry depset or the map of symlinks to be added to the runfiles. Symlinks are always added under the main workspace's runfiles directory (e.g. <code><runfiles_root>/_main/<symlink_path></code>, <strong>not</strong> the directory corresponding to the current target's repository. See <a href="https://bazel.build/extending/rules#runfiles_symlinks">Runfiles symlinks</a> in the rules guide.</td> +</tr> +<tr> +<td id="runfiles.root_symlinks"><code>root_symlinks</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <a href="../builtins/depset.html" class="anchor">depset</a> of <a href="../builtins/SymlinkEntry.html" class="anchor">SymlinkEntry</a>s; +default is <code>{}</code><br /> +Either a SymlinkEntry depset or a map of symlinks to be added to the runfiles. See <a href="https://bazel.build/extending/rules#runfiles_symlinks">Runfiles symlinks</a> in the rules guide.</td> +</tr> +</tbody> +</table> + +## split_attr + +``` rule-signature +struct ctx.split_attr +``` + +A struct to access the values of attributes with split configurations. If the attribute is a label list, the value of split_attr is a dict of the keys of the split (as strings) to lists of the ConfiguredTargets in that branch of the split. If the attribute is a label, then the value of split_attr is a dict of the keys of the split (as strings) to single ConfiguredTargets. Attributes with split configurations still appear in the attr struct, but their values will be single lists with all the branches of the split merged together. + +## super + +``` rule-signature +unknown ctx.super() +``` + +Experimental: Calls parent's implementation function and returns its providers + +## target_platform_has_constraint + +``` rule-signature +bool ctx.target_platform_has_constraint(constraintValue) +``` + +Returns true if the given constraint value is part of the current target platform. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="target_platform_has_constraint.constraintValue"><code>constraintValue</code></td> +<td><a href="../providers/ConstraintValueInfo.html" class="anchor">ConstraintValueInfo</a>; +required<br /> +The constraint value to check the target platform against.</td> +</tr> +</tbody> +</table> + +## toolchains + +``` rule-signature +ToolchainContext ctx.toolchains +``` + +Toolchains for the default exec group of this rule. + +## var + +``` rule-signature +dict ctx.var +``` + +Dictionary (String to String) of configuration variables. + +## version_file + +``` rule-signature +File ctx.version_file +``` + +The file that is used to hold the volatile workspace status for the current build request. See documentation for --workspace_status_command for more information. + +## workspace_name + +``` rule-signature +string ctx.workspace_name +``` + +The name of the workspace, which is effectively the execution root name and runfiles prefix for the main repo. If `--enable_bzlmod` is on, this is the fixed string `_main`. Otherwise, this is the workspace name as defined in the WORKSPACE file. diff --git a/rules/lib/builtins/depset.mdx b/rules/lib/builtins/depset.mdx index 2740279..23d8009 100644 --- a/rules/lib/builtins/depset.mdx +++ b/rules/lib/builtins/depset.mdx @@ -2,85 +2,60 @@ title: 'depset' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.depset">depset</h1> +# depset {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} -<p>A specialized data structure that supports efficient merge operations and has a defined traversal +A specialized data structure that supports efficient merge operations and has a defined traversal order. Commonly used for accumulating data from transitive dependencies in rules and aspects. For -more information see <a href="/extending/depsets">here</a>. +more information see [here](/extending/depsets). -<p>The elements of a depset must be hashable and all of the same type (as defined by the built-in -<a href="../globals/all#type"><code>type(x)</code></a> function), but depsets are not simply hash +The elements of a depset must be hashable and all of the same type (as defined by the built-in +[`type(x)`](../globals/all#type) function), but depsets are not simply hash sets and do not support fast membership tests. If you need a general set datatype, use the core -<a href="../core/set">Starlark set</a> type (available since Bazel 8.1); if your .bzl file needs to +[Starlark set](../core/set) type (available since Bazel 8.1); if your .bzl file needs to be compatible with older Bazel releases, you can simulate a set by using a dictionary where all keys -map to <code>True</code>. +map to `True`. -<p>When tested for truth (that is, when used in a Boolean context such as <code>if d:</code> where -<code>d</code> is a depset), a depset is True if and only if it is non-empty; this check is an O(1) +When tested for truth (that is, when used in a Boolean context such as `if d:` where +`d` is a depset), a depset is True if and only if it is non-empty; this check is an O(1) operation. -<p>Depsets are immutable. They should be created using their -<a href="../globals/bzl.html#depset">constructor function</a> and merged or augmented with other -depsets via the <code>transitive</code> argument. +Depsets are immutable. They should be created using their +[constructor function](../globals/bzl.html#depset) and merged or augmented with other +depsets via the `transitive` argument. -<p>The <code>order</code> parameter determines the kind of traversal that is done to convert the +The `order` parameter determines the kind of traversal that is done to convert the depset to an iterable. There are four possible values: -<ul> - <li> - <code>"default"</code> (formerly <code>"stable"</code>): Order is unspecified (but - deterministic). - </li> - <li> - <code>"postorder"</code> (formerly <code>"compile"</code>): A left-to-right post-ordering. - Precisely, this recursively traverses all children leftmost-first, then the direct elements - leftmost-first. - </li> - <li> - <code>"preorder"</code> (formerly <code>"naive_link"</code>): A left-to-right pre-ordering. - Precisely, this traverses the direct elements leftmost-first, then recursively traverses the - children leftmost-first. - </li> - <li> - <code>"topological"</code> (formerly <code>"link"</code>): A topological ordering from the root - down to the leaves. There is no left-to-right guarantee. - </li> -</ul> - -<p>Two depsets may only be merged if either both depsets have the same order, or one of them has -<code>"default"</code> order. In the latter case the resulting depset's order will be the same as +- `"default"` (formerly `"stable"`): Order is unspecified (but + deterministic). +- `"postorder"` (formerly `"compile"`): A left-to-right post-ordering. + Precisely, this recursively traverses all children leftmost-first, then the direct elements + leftmost-first. +- `"preorder"` (formerly `"naive_link"`): A left-to-right pre-ordering. + Precisely, this traverses the direct elements leftmost-first, then recursively traverses the + children leftmost-first. +- `"topological"` (formerly `"link"`): A topological ordering from the root + down to the leaves. There is no left-to-right guarantee. + +Two depsets may only be merged if either both depsets have the same order, or one of them has +`"default"` order. In the latter case the resulting depset's order will be the same as the other's order. -<p>Depsets may contain duplicate values but these will be suppressed when iterating (using -<a href="#to_list"><code>to_list()</code></a>). Duplicates may interfere with the ordering +Depsets may contain duplicate values but these will be suppressed when iterating (using +[`to_list()`](#to_list)). Duplicates may interfere with the ordering semantics. +## Members -<h2>Members</h2> -<ul> - <li> - <a href="#to_list">to_list</a> - </li> - </ul> - - <h2 id="to_list">to_list</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> depset.to_list()</pre></p> - - Returns a list of the elements, without duplicates, in the depset's traversal order. Note that order is unspecified (but deterministic) for elements that were added more than once to the depset. Order is also unspecified for <code>"default"</code>-ordered depsets, and for elements of child depsets whose order differs from that of the parent depset. The list is a copy; modifying it has no effect on the depset and vice versa. +- [to_list](#to_list) +## to_list -</body> -</html> +``` rule-signature +list depset.to_list() +``` -<!-- {% endraw %} --> +Returns a list of the elements, without duplicates, in the depset's traversal order. Note that order is unspecified (but deterministic) for elements that were added more than once to the depset. Order is also unspecified for `"default"`-ordered depsets, and for elements of child depsets whose order differs from that of the parent depset. The list is a copy; modifying it has no effect on the depset and vice versa. diff --git a/rules/lib/builtins/exec_result.mdx b/rules/lib/builtins/exec_result.mdx index 605d041..2251122 100644 --- a/rules/lib/builtins/exec_result.mdx +++ b/rules/lib/builtins/exec_result.mdx @@ -2,53 +2,38 @@ title: 'exec_result' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.exec_result">exec_result</h1> +# exec_result {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkExecutionResult.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A structure storing result of repository_ctx.execute() method. It contains the standard output stream content, the standard error stream content and the execution return code. +## Members -<h2>Members</h2> -<ul> - <li> - <a href="#return_code">return_code</a> - </li> - <li> - <a href="#stderr">stderr</a> - </li> - <li> - <a href="#stdout">stdout</a> - </li> - </ul> - - <h2 id="return_code">return_code</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> exec_result.return_code</pre></p> +- [return_code](#return_code) +- [stderr](#stderr) +- [stdout](#stdout) - The return code returned after the execution of the program. 256 if the process was terminated by a time out; values larger than 128 indicate termination by a signal. +## return_code +``` rule-signature +int exec_result.return_code +``` - <h2 id="stderr">stderr</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> exec_result.stderr</pre></p> +The return code returned after the execution of the program. 256 if the process was terminated by a time out; values larger than 128 indicate termination by a signal. - The content of the standard error output returned by the execution. +## stderr - <h2 id="stdout">stdout</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> exec_result.stdout</pre></p> +``` rule-signature +string exec_result.stderr +``` - The content of the standard output returned by the execution. +The content of the standard error output returned by the execution. +## stdout -</body> -</html> +``` rule-signature +string exec_result.stdout +``` -<!-- {% endraw %} --> +The content of the standard output returned by the execution. diff --git a/rules/lib/builtins/extension_metadata.mdx b/rules/lib/builtins/extension_metadata.mdx index a518c56..43ec1eb 100644 --- a/rules/lib/builtins/extension_metadata.mdx +++ b/rules/lib/builtins/extension_metadata.mdx @@ -2,24 +2,8 @@ title: 'extension_metadata' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.extension_metadata">extension_metadata</h1> +# extension_metadata {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionMetadata.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Return values of this type from a module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/builtins/fragments.mdx b/rules/lib/builtins/fragments.mdx index 24e47fa..62aa893 100644 --- a/rules/lib/builtins/fragments.mdx +++ b/rules/lib/builtins/fragments.mdx @@ -2,24 +2,12 @@ title: 'fragments' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.fragments">fragments</h1> +# fragments {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A collection of configuration fragments available in the current rule implementation context. Access a specific fragment by its field name. For example, <code>ctx.fragments.java</code> <p>Only configuration fragments which are declared in the rule definition may be accessed in this collection.</p><p>See the <a href="../fragments.html">configuration fragment reference</a> for a list of available fragments and the <a href="https://bazel.build/extending/rules#configuration_fragments">rules documentation</a> for how to use them. - - +{% include "\_buttons.html" %} +A collection of configuration fragments available in the current rule implementation context. Access a specific fragment by its field name. For example, `ctx.fragments.java` -</body> -</html> +Only configuration fragments which are declared in the rule definition may be accessed in this collection. -<!-- {% endraw %} --> +See the [configuration fragment reference](../fragments.html) for a list of available fragments and the [rules documentation](https://bazel.build/extending/rules#configuration_fragments) for how to use them. diff --git a/rules/lib/builtins/java_annotation_processing.mdx b/rules/lib/builtins/java_annotation_processing.mdx index 696cf91..7c10274 100644 --- a/rules/lib/builtins/java_annotation_processing.mdx +++ b/rules/lib/builtins/java_annotation_processing.mdx @@ -2,85 +2,76 @@ title: 'java_annotation_processing' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.java_annotation_processing">java_annotation_processing</h1> +# java_annotation_processing {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaAnnotationProcessingApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Information about jars that are a result of annotation processing for a Java rule. -<h2>Members</h2> -<ul> - <li> - <a href="#class_jar">class_jar</a> - </li> - <li> - <a href="#enabled">enabled</a> - </li> - <li> - <a href="#processor_classnames">processor_classnames</a> - </li> - <li> - <a href="#processor_classpath">processor_classpath</a> - </li> - <li> - <a href="#source_jar">source_jar</a> - </li> - <li> - <a href="#transitive_class_jars">transitive_class_jars</a> - </li> - <li> - <a href="#transitive_source_jars">transitive_source_jars</a> - </li> - </ul> +## Members + +- [class_jar](#class_jar) +- [enabled](#enabled) +- [processor_classnames](#processor_classnames) +- [processor_classpath](#processor_classpath) +- [source_jar](#source_jar) +- [transitive_class_jars](#transitive_class_jars) +- [transitive_source_jars](#transitive_source_jars) + +## class_jar + +``` rule-signature +File java_annotation_processing.class_jar +``` + +Deprecated: Please use `JavaInfo.java_outputs.generated_class_jar` instead. +May return `None`. + +## enabled - <h2 id="class_jar">class_jar</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_annotation_processing.class_jar</pre></p> +``` rule-signature +bool java_annotation_processing.enabled +``` - Deprecated: Please use <code>JavaInfo.java_outputs.generated_class_jar</code> instead. - May return <code>None</code>. +Deprecated. Returns true if annotation processing was applied on this target. - <h2 id="enabled">enabled</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java_annotation_processing.enabled</pre></p> +## processor_classnames - Deprecated. Returns true if annotation processing was applied on this target. +``` rule-signature +list java_annotation_processing.processor_classnames +``` - <h2 id="processor_classnames">processor_classnames</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java_annotation_processing.processor_classnames</pre></p> +Deprecated: Please use `JavaInfo.plugins` instead. Returns class names of annotation processors applied to this rule. - Deprecated: Please use <code>JavaInfo.plugins</code> instead. Returns class names of annotation processors applied to this rule. +## processor_classpath - <h2 id="processor_classpath">processor_classpath</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_annotation_processing.processor_classpath</pre></p> +``` rule-signature +depset java_annotation_processing.processor_classpath +``` - Deprecated: Please use <code>JavaInfo.plugins</code> instead. Returns a classpath of annotation processors applied to this rule. +Deprecated: Please use `JavaInfo.plugins` instead. Returns a classpath of annotation processors applied to this rule. - <h2 id="source_jar">source_jar</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_annotation_processing.source_jar</pre></p> +## source_jar - Deprecated: Please use <code>JavaInfo.java_outputs.generated_source_jar</code> instead. - May return <code>None</code>. +``` rule-signature +File java_annotation_processing.source_jar +``` - <h2 id="transitive_class_jars">transitive_class_jars</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_annotation_processing.transitive_class_jars</pre></p> +Deprecated: Please use `JavaInfo.java_outputs.generated_source_jar` instead. +May return `None`. - Deprecated. Returns a transitive set of class file jars resulting from annotation processing of this rule and its dependencies. +## transitive_class_jars - <h2 id="transitive_source_jars">transitive_source_jars</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_annotation_processing.transitive_source_jars</pre></p> +``` rule-signature +depset java_annotation_processing.transitive_class_jars +``` - Deprecated. Returns a transitive set of source archives resulting from annotation processing of this rule and its dependencies. +Deprecated. Returns a transitive set of class file jars resulting from annotation processing of this rule and its dependencies. +## transitive_source_jars -</body> -</html> +``` rule-signature +depset java_annotation_processing.transitive_source_jars +``` -<!-- {% endraw %} --> +Deprecated. Returns a transitive set of source archives resulting from annotation processing of this rule and its dependencies. diff --git a/rules/lib/builtins/macro.mdx b/rules/lib/builtins/macro.mdx index ef43a43..a89093d 100644 --- a/rules/lib/builtins/macro.mdx +++ b/rules/lib/builtins/macro.mdx @@ -2,30 +2,13 @@ title: 'macro' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.macro">macro</h1> +# macro {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/MacroFunctionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A callable Starlark value representing a symbolic macro; in other words, the return value of -<a href="../globals/bzl.html#macro"><code>macro()</code></a>. Invoking this value during package +[`macro()`](../globals/bzl.html#macro). Invoking this value during package construction time will instantiate the macro, and cause the macro's implementation function to be evaluated (in a separate context, different from the context in which the macro value was invoked), in most cases causing targets to be added to the package's target set. For more information, see -<a href="https://bazel.build/extending/macros">Macros</a>. - - - - -</body> -</html> - -<!-- {% endraw %} --> +[Macros](https://bazel.build/extending/macros). diff --git a/rules/lib/builtins/mapped_root.mdx b/rules/lib/builtins/mapped_root.mdx index 4e16d8e..bd66b22 100644 --- a/rules/lib/builtins/mapped_root.mdx +++ b/rules/lib/builtins/mapped_root.mdx @@ -2,35 +2,20 @@ title: 'mapped_root' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.mapped_root">mapped_root</h1> +# mapped_root {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/actions/PathMapper.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A root for files that have been subject to path mapping -<h2>Members</h2> -<ul> - <li> - <a href="#path">path</a> - </li> - </ul> - - <h2 id="path">path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> mapped_root.path</pre></p> +## Members - Returns the relative path from the exec root to the actual root. +- [path](#path) +## path -</body> -</html> +``` rule-signature +string mapped_root.path +``` -<!-- {% endraw %} --> +Returns the relative path from the exec root to the actual root. diff --git a/rules/lib/builtins/module_ctx.mdx b/rules/lib/builtins/module_ctx.mdx index 1089f19..a8c53f6 100644 --- a/rules/lib/builtins/module_ctx.mdx +++ b/rules/lib/builtins/module_ctx.mdx @@ -2,888 +2,634 @@ title: 'module_ctx' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.module_ctx">module_ctx</h1> +# module_ctx {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -The context of the module extension containing helper functions and information about pertinent tags across the dependency graph. You get a module_ctx object as an argument to the <code>implementation</code> function when you create a module extension. - -<h2>Members</h2> -<ul> - <li> - <a href="#download">download</a> - </li> - <li> - <a href="#download_and_extract">download_and_extract</a> - </li> - <li> - <a href="#execute">execute</a> - </li> - <li> - <a href="#extension_metadata">extension_metadata</a> - </li> - <li> - <a href="#extract">extract</a> - </li> - <li> - <a href="#file">file</a> - </li> - <li> - <a href="#getenv">getenv</a> - </li> - <li> - <a href="#is_dev_dependency">is_dev_dependency</a> - </li> - <li> - <a href="#modules">modules</a> - </li> - <li> - <a href="#os">os</a> - </li> - <li> - <a href="#path">path</a> - </li> - <li> - <a href="#read">read</a> - </li> - <li> - <a href="#report_progress">report_progress</a> - </li> - <li> - <a href="#root_module_has_non_dev_dependency">root_module_has_non_dev_dependency</a> - </li> - <li> - <a href="#watch">watch</a> - </li> - <li> - <a href="#which">which</a> - </li> - </ul> - - <h2 id="download">download</h2> - <p><pre class="rule-signature">unknown module_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True)</pre></p> - - Downloads a file to the output path for the provided url and returns a struct containing <code>success</code>, a flag which is <code>true</code> if the download completed successfully, and if successful, a hash of the file with the fields <code>sha256</code> and <code>integrity</code>. When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit <code>canonical_id</code> is highly recommended. e.g. <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="download.url"> - <code>url</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or Iterable of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - List of mirror URLs referencing the same file. - </td> - </tr> - <tr> - <td id="download.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - default is <code>''</code><br/> - path to the output file, relative to the repository directory. - </td> - </tr> - <tr> - <td id="download.sha256"> - <code>sha256</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. - - </td> - </tr> - <tr> - <td id="download.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Set the executable flag on the created file, false by default. - </td> - </tr> - <tr> - <td id="download.allow_fail"> - <code>allow_fail</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If set, indicate the error in the return value instead of raising an error for failed downloads. - - </td> - </tr> - <tr> - <td id="download.canonical_id"> - <code>canonical_id</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (<code>sha256</code> or <code>integrity</code>). - - </td> - </tr> - <tr> - <td id="download.auth"> - <code>auth</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying authentication information for some of the URLs. - </td> - </tr> - <tr> - <td id="download.headers"> - <code>headers</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying http headers for all URLs. - </td> - </tr> - <tr> - <td id="download.integrity"> - <code>integrity</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. - - </td> - </tr> - <tr> - <td id="download.block"> - <code>block</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. - - </td> - </tr> - </tbody> - </table> - - <h2 id="download_and_extract">download_and_extract</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> module_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={})</pre></p> - - Downloads a file to the output path for the provided url, extracts it, and returns a struct containing <code>success</code>, a flag which is <code>true</code> if the download completed successfully, and if successful, a hash of the file with the fields <code>sha256</code> and <code>integrity</code>. When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit <code>canonical_id</code> is highly recommended. e.g. <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="download_and_extract.url"> - <code>url</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or Iterable of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - List of mirror URLs referencing the same file. - </td> - </tr> - <tr> - <td id="download_and_extract.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - default is <code>''</code><br/> - Path to the directory where the archive will be unpacked, relative to the repository directory. - - </td> - </tr> - <tr> - <td id="download_and_extract.sha256"> - <code>sha256</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. - - </td> - </tr> - <tr> - <td id="download_and_extract.type"> - <code>type</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. - - </td> - </tr> - <tr> - <td id="download_and_extract.strip_prefix"> - <code>strip_prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - A directory prefix to strip from the extracted files. Many archives contain a +{% include "\_buttons.html" %} +The context of the module extension containing helper functions and information about pertinent tags across the dependency graph. You get a module_ctx object as an argument to the `implementation` function when you create a module extension. + +## Members + +- [download](#download) +- [download_and_extract](#download_and_extract) +- [execute](#execute) +- [extension_metadata](#extension_metadata) +- [extract](#extract) +- [file](#file) +- [getenv](#getenv) +- [is_dev_dependency](#is_dev_dependency) +- [modules](#modules) +- [os](#os) +- [path](#path) +- [read](#read) +- [report_progress](#report_progress) +- [root_module_has_non_dev_dependency](#root_module_has_non_dev_dependency) +- [watch](#watch) +- [which](#which) + +## download + +``` rule-signature +unknown module_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True) +``` + +Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="download.url"><code>url</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or Iterable of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +List of mirror URLs referencing the same file.</td> +</tr> +<tr> +<td id="download.output"><code>output</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +default is <code>''</code><br /> +path to the output file, relative to the repository directory.</td> +</tr> +<tr> +<td id="download.sha256"><code>sha256</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> +</tr> +<tr> +<td id="download.executable"><code>executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Set the executable flag on the created file, false by default.</td> +</tr> +<tr> +<td id="download.allow_fail"><code>allow_fail</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If set, indicate the error in the return value instead of raising an error for failed downloads.</td> +</tr> +<tr> +<td id="download.canonical_id"><code>canonical_id</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (<code>sha256</code> or <code>integrity</code>).</td> +</tr> +<tr> +<td id="download.auth"><code>auth</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying authentication information for some of the URLs.</td> +</tr> +<tr> +<td id="download.headers"><code>headers</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying http headers for all URLs.</td> +</tr> +<tr> +<td id="download.integrity"><code>integrity</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> +</tr> +<tr> +<td id="download.block"><code>block</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual.</td> +</tr> +</tbody> +</table> + +## download_and_extract + +``` rule-signature +struct module_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={}) +``` + +Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="download_and_extract.url"><code>url</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or Iterable of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +List of mirror URLs referencing the same file.</td> +</tr> +<tr> +<td id="download_and_extract.output"><code>output</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +default is <code>''</code><br /> +Path to the directory where the archive will be unpacked, relative to the repository directory.</td> +</tr> +<tr> +<td id="download_and_extract.sha256"><code>sha256</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> +</tr> +<tr> +<td id="download_and_extract.type"><code>type</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here.</td> +</tr> +<tr> +<td id="download_and_extract.strip_prefix"><code>strip_prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +A directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the <code>build_file</code>, this field can be used to strip it from extracted files. - <p>For compatibility, this parameter may also be used under the deprecated name -<code>stripPrefix</code>. - - </td> - </tr> - <tr> - <td id="download_and_extract.allow_fail"> - <code>allow_fail</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If set, indicate the error in the return value instead of raising an error for failed downloads. - - </td> - </tr> - <tr> - <td id="download_and_extract.canonical_id"> - <code>canonical_id</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum -(<code>sha256</code> or <code>integrity</code>). - - </td> - </tr> - <tr> - <td id="download_and_extract.auth"> - <code>auth</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying authentication information for some of the URLs. - </td> - </tr> - <tr> - <td id="download_and_extract.headers"> - <code>headers</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying http headers for all URLs. - </td> - </tr> - <tr> - <td id="download_and_extract.integrity"> - <code>integrity</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. - </td> - </tr> - <tr> - <td id="download_and_extract.rename_files"> - <code>rename_files</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. - - </td> - </tr> - </tbody> - </table> - - <h2 id="execute">execute</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/exec_result.html">exec_result</a> module_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="")</pre></p> - - Executes the command given by the list of arguments. The execution time of the command is limited by <code>timeout</code> (in seconds, default 600 seconds). This method returns an <code>exec_result</code> structure containing the output of the command. The <code>environment</code> map can be used to override some environment variables to be passed to the process. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="execute.arguments"> - <code>arguments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - required<br/> - List of arguments, the first element should be the path to the program to execute. - - </td> - </tr> - <tr> - <td id="execute.timeout"> - <code>timeout</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>600</code><br/> - Maximum duration of the command in seconds (default is 600 seconds). - </td> - </tr> - <tr> - <td id="execute.environment"> - <code>environment</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - Force some environment variables to be set to be passed to the process. The value can be <code>None</code> to remove the environment variable. - - </td> - </tr> - <tr> - <td id="execute.quiet"> - <code>quiet</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - If stdout and stderr should be printed to the terminal. - </td> - </tr> - <tr> - <td id="execute.working_directory"> - <code>working_directory</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>""</code><br/> - Working directory for command execution. +<code>stripPrefix</code>.</p></td> +</tr> +<tr> +<td id="download_and_extract.allow_fail"><code>allow_fail</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If set, indicate the error in the return value instead of raising an error for failed downloads.</td> +</tr> +<tr> +<td id="download_and_extract.canonical_id"><code>canonical_id</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum +(<code>sha256</code> or <code>integrity</code>).</td> +</tr> +<tr> +<td id="download_and_extract.auth"><code>auth</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying authentication information for some of the URLs.</td> +</tr> +<tr> +<td id="download_and_extract.headers"><code>headers</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying http headers for all URLs.</td> +</tr> +<tr> +<td id="download_and_extract.integrity"><code>integrity</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> +</tr> +<tr> +<td id="download_and_extract.rename_files"><code>rename_files</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems.</td> +</tr> +</tbody> +</table> + +## execute + +``` rule-signature +exec_result module_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="") +``` + +Executes the command given by the list of arguments. The execution time of the command is limited by `timeout` (in seconds, default 600 seconds). This method returns an `exec_result` structure containing the output of the command. The `environment` map can be used to override some environment variables to be passed to the process. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="execute.arguments"><code>arguments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +required<br /> +List of arguments, the first element should be the path to the program to execute.</td> +</tr> +<tr> +<td id="execute.timeout"><code>timeout</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>600</code><br /> +Maximum duration of the command in seconds (default is 600 seconds).</td> +</tr> +<tr> +<td id="execute.environment"><code>environment</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +Force some environment variables to be set to be passed to the process. The value can be <code>None</code> to remove the environment variable.</td> +</tr> +<tr> +<td id="execute.quiet"><code>quiet</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +If stdout and stderr should be printed to the terminal.</td> +</tr> +<tr> +<td id="execute.working_directory"><code>working_directory</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>""</code><br /> +Working directory for command execution. Can be relative to the repository root or absolute. -The default is the repository root. - - </td> - </tr> - </tbody> - </table> - - <h2 id="extension_metadata">extension_metadata</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/extension_metadata.html">extension_metadata</a> module_ctx.extension_metadata(*, root_module_direct_deps=None, root_module_direct_dev_deps=None, reproducible=False)</pre></p> - - Constructs an opaque object that can be returned from the module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="extension_metadata.root_module_direct_deps"> - <code>root_module_direct_deps</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The names of the repositories that the extension considers to be direct dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via <a href="../globals/module.html#use_repo"><code>use_repo</code></a>, Bazel will print a warning when the extension is evaluated, instructing the user to run <code>bazel mod tidy</code> to fix the <code>use_repo</code> calls automatically. <p>If one of <code>root_module_direct_deps</code> and will print a warning and a fixup command when the extension is evaluated.<p>If one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> is specified, the other has to be as well. The lists specified by these two parameters must be disjoint.<p>Exactly one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> can be set to the special value <code>"all"</code>, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. - </td> - </tr> - <tr> - <td id="extension_metadata.root_module_direct_dev_deps"> - <code>root_module_direct_dev_deps</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The names of the repositories that the extension considers to be direct dev dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via <a href="../globals/module.html#use_repo"><code>use_repo</code></a> on an extension proxy created with <code><a href="../globals/module.html#use_extension">use_extension</a>(..., dev_dependency = True)</code>, Bazel will print a warning when the extension is evaluated, instructing the user to run <code>bazel mod tidy</code> to fix the <code>use_repo</code> calls automatically. <p>If one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> is specified, the other has to be as well. The lists specified by these two parameters must be disjoint.<p>Exactly one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> can be set to the special value <code>"all"</code>, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. - </td> - </tr> - <tr> - <td id="extension_metadata.reproducible"> - <code>reproducible</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - States that this module extension ensures complete reproducibility, thereby it should not be stored in the lockfile. - </td> - </tr> - </tbody> - </table> - - <h2 id="extract">extract</h2> - <p><pre class="rule-signature"><code>None</code> module_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto')</pre></p> - - Extract an archive to the repository directory. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="extract.archive"> - <code>archive</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - path to the archive that will be unpacked, relative to the repository directory. - </td> - </tr> - <tr> - <td id="extract.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - default is <code>''</code><br/> - path to the directory where the archive will be unpacked, relative to the repository directory. - </td> - </tr> - <tr> - <td id="extract.strip_prefix"> - <code>strip_prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - a directory prefix to strip from the extracted files. Many archives contain a +The default is the repository root.</td> +</tr> +</tbody> +</table> + +## extension_metadata + +``` rule-signature +extension_metadata module_ctx.extension_metadata(*, root_module_direct_deps=None, root_module_direct_dev_deps=None, reproducible=False) +``` + +Constructs an opaque object that can be returned from the module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="extension_metadata.root_module_direct_deps"><code>root_module_direct_deps</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The names of the repositories that the extension considers to be direct dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via <a href="../globals/module.html#use_repo"><code>use_repo</code></a>, Bazel will print a warning when the extension is evaluated, instructing the user to run <code>bazel mod tidy</code> to fix the <code>use_repo</code> calls automatically. +<p>If one of <code>root_module_direct_deps</code> and will print a warning and a fixup command when the extension is evaluated.</p> +<p>If one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> is specified, the other has to be as well. The lists specified by these two parameters must be disjoint.</p> +<p>Exactly one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> can be set to the special value <code>"all"</code>, which is treated as if a list with the names of all repositories generated by the extension was specified as the value.</p></td> +</tr> +<tr> +<td id="extension_metadata.root_module_direct_dev_deps"><code>root_module_direct_dev_deps</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The names of the repositories that the extension considers to be direct dev dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via <a href="../globals/module.html#use_repo"><code>use_repo</code></a> on an extension proxy created with <a href="../globals/module.html#use_extension"><code>use_extension</code></a><code>(..., dev_dependency = True)</code>, Bazel will print a warning when the extension is evaluated, instructing the user to run <code>bazel mod tidy</code> to fix the <code>use_repo</code> calls automatically. +<p>If one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> is specified, the other has to be as well. The lists specified by these two parameters must be disjoint.</p> +<p>Exactly one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> can be set to the special value <code>"all"</code>, which is treated as if a list with the names of all repositories generated by the extension was specified as the value.</p></td> +</tr> +<tr> +<td id="extension_metadata.reproducible"><code>reproducible</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +States that this module extension ensures complete reproducibility, thereby it should not be stored in the lockfile.</td> +</tr> +</tbody> +</table> + +## extract + +``` rule-signature +None module_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto') +``` + +Extract an archive to the repository directory. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="extract.archive"><code>archive</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +path to the archive that will be unpacked, relative to the repository directory.</td> +</tr> +<tr> +<td id="extract.output"><code>output</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +default is <code>''</code><br /> +path to the directory where the archive will be unpacked, relative to the repository directory.</td> +</tr> +<tr> +<td id="extract.strip_prefix"><code>strip_prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +a directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the <code>build_file</code>, this field can be used to strip it from extracted files. - <p>For compatibility, this parameter may also be used under the deprecated name -<code>stripPrefix</code>. - - </td> - </tr> - <tr> - <td id="extract.rename_files"> - <code>rename_files</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. - </td> - </tr> - <tr> - <td id="extract.watch_archive"> - <code>watch_archive</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'auto'</code><br/> - whether to <a href="#watch">watch</a> the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. - </td> - </tr> - </tbody> - </table> - - <h2 id="file">file</h2> - <p><pre class="rule-signature"><code>None</code> module_ctx.file(path, content='', executable=True, legacy_utf8=False)</pre></p> - - Generates a file in the repository directory with the provided content. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="file.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the file to create, relative to the repository directory. - </td> - </tr> - <tr> - <td id="file.content"> - <code>content</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The content of the file to create, empty by default. - </td> - </tr> - <tr> - <td id="file.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - Set the executable flag on the created file, true by default. - </td> - </tr> - <tr> - <td id="file.legacy_utf8"> - <code>legacy_utf8</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - No-op. This parameter is deprecated and will be removed in a future version of Bazel. - - </td> - </tr> - </tbody> - </table> - - <h2 id="getenv">getenv</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> module_ctx.getenv(name, default=None)</pre></p> - - Returns the value of an environment variable <code>name</code> as a string if exists, or <code>default</code> if it doesn't. <p>When building incrementally, any change to the value of the variable named by <code>name</code> will cause this repository to be re-fetched. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="getenv.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of desired environment variable. - </td> - </tr> - <tr> - <td id="getenv.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Default value to return if <code>name</code> is not found. - </td> - </tr> - </tbody> - </table> - May return <code>None</code>. - - <h2 id="is_dev_dependency">is_dev_dependency</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> module_ctx.is_dev_dependency(tag)</pre></p> - - Returns whether the given tag was specified on the result of a <a href="../globals/module.html#use_extension">use_extension</a> call with <code>devDependency = True</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="is_dev_dependency.tag"> - <code>tag</code> - </td> - <td> - bazel_module_tag; - required<br/> - A tag obtained from <a href="../builtins/bazel_module.html#tags">bazel_module.tags</a>. - </td> - </tr> - </tbody> - </table> - - <h2 id="modules">modules</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> module_ctx.modules</pre></p> - - A list of all the Bazel modules in the external dependency graph that use this module extension, each of which is a <a href="../builtins/bazel_module.html">bazel_module</a> object that exposes all the tags it specified for this extension. The iteration order of this dictionary is guaranteed to be the same as breadth-first search starting from the root module. - - <h2 id="os">os</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/repository_os.html">repository_os</a> module_ctx.os</pre></p> - - A struct to access information from the system. - - <h2 id="path">path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> module_ctx.path(path)</pre></p> - - Returns a path from a string, label, or path. If this context is a <code>repository_ctx</code>, a relative path will resolve relative to the repository directory. If it is a <code>module_ctx</code>, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="path.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - <code>string</code>, <code>Label</code> or <code>path</code> from which to create a path from. - </td> - </tr> - </tbody> - </table> - - <h2 id="read">read</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> module_ctx.read(path, *, watch='auto')</pre></p> - - Reads the content of a file on the filesystem. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="read.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the file to read from. - </td> - </tr> - <tr> - <td id="read.watch"> - <code>watch</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'auto'</code><br/> - Whether to <a href="#watch">watch</a> the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. - - </td> - </tr> - </tbody> - </table> - - <h2 id="report_progress">report_progress</h2> - <p><pre class="rule-signature"><code>None</code> module_ctx.report_progress(status='')</pre></p> - - Updates the progress status for the fetching of this repository or module extension. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="report_progress.status"> - <code>status</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - <code>string</code> describing the current status of the fetch progress. - </td> - </tr> - </tbody> - </table> - - <h2 id="root_module_has_non_dev_dependency">root_module_has_non_dev_dependency</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> module_ctx.root_module_has_non_dev_dependency</pre></p> - - Whether the root module uses this extension as a non-dev dependency. - - <h2 id="watch">watch</h2> - <p><pre class="rule-signature"><code>None</code> module_ctx.watch(path)</pre></p> - - Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time.<p>"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does <em>not</em> include changes to any files under the directory if the path is a directory. For that, use <a href="path.html#readdir"><code>path.readdir()</code></a> instead.<p>Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="watch.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the file to watch. - </td> - </tr> - </tbody> - </table> - - <h2 id="which">which</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> module_ctx.which(program)</pre></p> - - Returns the <code>path</code> of the corresponding program or <code>None</code> if there is no such program in the path. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="which.program"> - <code>program</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Program to find in the path. - </td> - </tr> - </tbody> - </table> - May return <code>None</code>. - - -</body> -</html> - -<!-- {% endraw %} --> +<code>stripPrefix</code>.</p></td> +</tr> +<tr> +<td id="extract.rename_files"><code>rename_files</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems.</td> +</tr> +<tr> +<td id="extract.watch_archive"><code>watch_archive</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'auto'</code><br /> +whether to <a href="#watch">watch</a> the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> +</tr> +</tbody> +</table> + +## file + +``` rule-signature +None module_ctx.file(path, content='', executable=True, legacy_utf8=False) +``` + +Generates a file in the repository directory with the provided content. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="file.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the file to create, relative to the repository directory.</td> +</tr> +<tr> +<td id="file.content"><code>content</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The content of the file to create, empty by default.</td> +</tr> +<tr> +<td id="file.executable"><code>executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +Set the executable flag on the created file, true by default.</td> +</tr> +<tr> +<td id="file.legacy_utf8"><code>legacy_utf8</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +No-op. This parameter is deprecated and will be removed in a future version of Bazel.</td> +</tr> +</tbody> +</table> + +## getenv + +``` rule-signature +string module_ctx.getenv(name, default=None) +``` + +Returns the value of an environment variable `name` as a string if exists, or `default` if it doesn't. + +When building incrementally, any change to the value of the variable named by `name` will cause this repository to be re-fetched. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="getenv.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of desired environment variable.</td> +</tr> +<tr> +<td id="getenv.default"><code>default</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Default value to return if <code>name</code> is not found.</td> +</tr> +</tbody> +</table> + +May return `None`. + +## is_dev_dependency + +``` rule-signature +bool module_ctx.is_dev_dependency(tag) +``` + +Returns whether the given tag was specified on the result of a [use_extension](../globals/module.html#use_extension) call with `devDependency = True`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="is_dev_dependency.tag"><code>tag</code></td> +<td>bazel_module_tag; +required<br /> +A tag obtained from <a href="../builtins/bazel_module.html#tags">bazel_module.tags</a>.</td> +</tr> +</tbody> +</table> + +## modules + +``` rule-signature +list module_ctx.modules +``` + +A list of all the Bazel modules in the external dependency graph that use this module extension, each of which is a [bazel_module](../builtins/bazel_module.html) object that exposes all the tags it specified for this extension. The iteration order of this dictionary is guaranteed to be the same as breadth-first search starting from the root module. + +## os + +``` rule-signature +repository_os module_ctx.os +``` + +A struct to access information from the system. + +## path + +``` rule-signature +path module_ctx.path(path) +``` + +Returns a path from a string, label, or path. If this context is a `repository_ctx`, a relative path will resolve relative to the repository directory. If it is a `module_ctx`, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="path.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +<code>string</code>, <code>Label</code> or <code>path</code> from which to create a path from.</td> +</tr> +</tbody> +</table> + +## read + +``` rule-signature +string module_ctx.read(path, *, watch='auto') +``` + +Reads the content of a file on the filesystem. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="read.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the file to read from.</td> +</tr> +<tr> +<td id="read.watch"><code>watch</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'auto'</code><br /> +Whether to <a href="#watch">watch</a> the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> +</tr> +</tbody> +</table> + +## report_progress + +``` rule-signature +None module_ctx.report_progress(status='') +``` + +Updates the progress status for the fetching of this repository or module extension. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="report_progress.status"><code>status</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +<code>string</code> describing the current status of the fetch progress.</td> +</tr> +</tbody> +</table> + +## root_module_has_non_dev_dependency + +``` rule-signature +bool module_ctx.root_module_has_non_dev_dependency +``` + +Whether the root module uses this extension as a non-dev dependency. + +## watch + +``` rule-signature +None module_ctx.watch(path) +``` + +Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time. + +"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does *not* include changes to any files under the directory if the path is a directory. For that, use [`path.readdir()`](path.html#readdir) instead. + +Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="watch.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the file to watch.</td> +</tr> +</tbody> +</table> + +## which + +``` rule-signature +path module_ctx.which(program) +``` + +Returns the `path` of the corresponding program or `None` if there is no such program in the path. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="which.program"><code>program</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Program to find in the path.</td> +</tr> +</tbody> +</table> + +May return `None`. diff --git a/rules/lib/builtins/path.mdx b/rules/lib/builtins/path.mdx index 5e47bed..53d4582 100644 --- a/rules/lib/builtins/path.mdx +++ b/rules/lib/builtins/path.mdx @@ -2,143 +2,117 @@ title: 'path' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.path">path</h1> +# path {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkPath.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A structure representing a file to be used inside a repository. -<h2>Members</h2> -<ul> - <li> - <a href="#basename">basename</a> - </li> - <li> - <a href="#dirname">dirname</a> - </li> - <li> - <a href="#exists">exists</a> - </li> - <li> - <a href="#get_child">get_child</a> - </li> - <li> - <a href="#is_dir">is_dir</a> - </li> - <li> - <a href="#readdir">readdir</a> - </li> - <li> - <a href="#realpath">realpath</a> - </li> - </ul> - - <h2 id="basename">basename</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> path.basename</pre></p> - - A string giving the basename of the file. - - <h2 id="dirname">dirname</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> path.dirname</pre></p> - - The parent directory of this file, or None if this file does not have a parent. - May return <code>None</code>. - - <h2 id="exists">exists</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> path.exists</pre></p> - - Returns true if the file or directory denoted by this path exists.<p>Note that accessing this field does <em>not</em> cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to the path's existence, use the <code>watch()</code> method on the context object. - - - <h2 id="get_child">get_child</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> path.get_child(*relative_paths)</pre></p> - - Returns the path obtained by joining this path with the given relative paths. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="get_child.relative_paths"> - <code>relative_paths</code> - </td> - <td> - required<br/> - Zero or more relative path strings to append to this path with path separators added as needed. - - </td> - </tr> - </tbody> - </table> - - <h2 id="is_dir">is_dir</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> path.is_dir</pre></p> - - Returns true if this path points to a directory.<p>Note that accessing this field does <em>not</em> cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to whether the path is a directory or a file, use the <code>watch()</code> method on the context object. - - - <h2 id="readdir">readdir</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> path.readdir(*, watch='auto')</pre></p> - - Returns the list of entries in the directory denoted by this path. Each entry is a <code>path</code> object itself. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="readdir.watch"> - <code>watch</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'auto'</code><br/> - whether Bazel should watch the list of entries in this directory and refetch the repository or re-evaluate the module extension next time when any changes are detected. Changes to detect include entry creation, deletion, and renaming. Note that this doesn't watch the <em>contents</em> of any entries in the directory.<p>Can be the string 'yes', 'no', or 'auto'. If set to 'auto', Bazel will only watch this directory when it is legal to do so (see <a href="repository_ctx.html#watch"><code>repository_ctx.watch()</code></a> docs for more information). - - </td> - </tr> - </tbody> - </table> - - <h2 id="realpath">realpath</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> path.realpath</pre></p> - - Returns the canonical path for this path by repeatedly replacing all symbolic links with their referents. - - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [basename](#basename) +- [dirname](#dirname) +- [exists](#exists) +- [get_child](#get_child) +- [is_dir](#is_dir) +- [readdir](#readdir) +- [realpath](#realpath) + +## basename + +``` rule-signature +string path.basename +``` + +A string giving the basename of the file. + +## dirname + +``` rule-signature +path path.dirname +``` + +The parent directory of this file, or None if this file does not have a parent. +May return `None`. + +## exists + +``` rule-signature +bool path.exists +``` + +Returns true if the file or directory denoted by this path exists. + +Note that accessing this field does *not* cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to the path's existence, use the `watch()` method on the context object. + +## get_child + +``` rule-signature +path path.get_child(*relative_paths) +``` + +Returns the path obtained by joining this path with the given relative paths. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="get_child.relative_paths"><code>relative_paths</code></td> +<td>required<br /> +Zero or more relative path strings to append to this path with path separators added as needed.</td> +</tr> +</tbody> +</table> + +## is_dir + +``` rule-signature +bool path.is_dir +``` + +Returns true if this path points to a directory. + +Note that accessing this field does *not* cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to whether the path is a directory or a file, use the `watch()` method on the context object. + +## readdir + +``` rule-signature +list path.readdir(*, watch='auto') +``` + +Returns the list of entries in the directory denoted by this path. Each entry is a `path` object itself. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="readdir.watch"><code>watch</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'auto'</code><br /> +whether Bazel should watch the list of entries in this directory and refetch the repository or re-evaluate the module extension next time when any changes are detected. Changes to detect include entry creation, deletion, and renaming. Note that this doesn't watch the <em>contents</em> of any entries in the directory. +<p>Can be the string 'yes', 'no', or 'auto'. If set to 'auto', Bazel will only watch this directory when it is legal to do so (see <a href="repository_ctx.html#watch"><code>repository_ctx.watch()</code></a> docs for more information).</p></td> +</tr> +</tbody> +</table> + +## realpath + +``` rule-signature +path path.realpath +``` + +Returns the canonical path for this path by repeatedly replacing all symbolic links with their referents. diff --git a/rules/lib/builtins/propagation_ctx.mdx b/rules/lib/builtins/propagation_ctx.mdx index 7caad00..c58fd9b 100644 --- a/rules/lib/builtins/propagation_ctx.mdx +++ b/rules/lib/builtins/propagation_ctx.mdx @@ -2,43 +2,29 @@ title: 'propagation_ctx' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.propagation_ctx">propagation_ctx</h1> +# propagation_ctx {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectPropagationContextApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A context object that is passed to the <code>propagation_predicate</code>, <code>attr_aspects</code> and <code>toolchains_aspects</code> functions of aspects. It provides access to the information needed to determine whether the aspect should be propagated to the target and what attributes or toolchain types it should be propagated to next. +{% include "\_buttons.html" %} +A context object that is passed to the `propagation_predicate`, `attr_aspects` and `toolchains_aspects` functions of aspects. It provides access to the information needed to determine whether the aspect should be propagated to the target and what attributes or toolchain types it should be propagated to next. -<h2>Members</h2> -<ul> - <li> - <a href="#attr">attr</a> - </li> - <li> - <a href="#rule">rule</a> - </li> - </ul> +## Members - <h2 id="attr">attr</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> propagation_ctx.attr</pre></p> +- [attr](#attr) +- [rule](#rule) - A struct to access only the public parameters of the aspect. The keys and values of the struct are the parameters names and values. +## attr - <h2 id="rule">rule</h2> - <p><pre class="rule-signature">StarlarkAspectPropagationRuleApi propagation_ctx.rule</pre></p> +``` rule-signature +struct propagation_ctx.attr +``` - Allows access to the details of the rule. +A struct to access only the public parameters of the aspect. The keys and values of the struct are the parameters names and values. +## rule -</body> -</html> +``` rule-signature +StarlarkAspectPropagationRuleApi propagation_ctx.rule +``` -<!-- {% endraw %} --> +Allows access to the details of the rule. diff --git a/rules/lib/builtins/repo_metadata.mdx b/rules/lib/builtins/repo_metadata.mdx index 7220273..6fddea8 100644 --- a/rules/lib/builtins/repo_metadata.mdx +++ b/rules/lib/builtins/repo_metadata.mdx @@ -2,25 +2,8 @@ title: 'repo_metadata' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.repo_metadata">repo_metadata</h1> +# repo_metadata {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/RepoMetadata.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -See <a href="repository_ctx#repo_metadata"><code>repository_ctx.repo_metadata</code></a>. - - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +See [`repository_ctx.repo_metadata`](repository_ctx#repo_metadata). diff --git a/rules/lib/builtins/repository_ctx.mdx b/rules/lib/builtins/repository_ctx.mdx index 1e538a8..0dad60b 100644 --- a/rules/lib/builtins/repository_ctx.mdx +++ b/rules/lib/builtins/repository_ctx.mdx @@ -2,1168 +2,835 @@ title: 'repository_ctx' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.repository_ctx">repository_ctx</h1> +# repository_ctx {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryContext.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -The context of the repository rule containing helper functions and information about attributes. You get a repository_ctx object as an argument to the <code>implementation</code> function when you create a repository rule. - - -<h2>Members</h2> -<ul> - <li> - <a href="#attr">attr</a> - </li> - <li> - <a href="#delete">delete</a> - </li> - <li> - <a href="#download">download</a> - </li> - <li> - <a href="#download_and_extract">download_and_extract</a> - </li> - <li> - <a href="#execute">execute</a> - </li> - <li> - <a href="#extract">extract</a> - </li> - <li> - <a href="#file">file</a> - </li> - <li> - <a href="#getenv">getenv</a> - </li> - <li> - <a href="#name">name</a> - </li> - <li> - <a href="#original_name">original_name</a> - </li> - <li> - <a href="#os">os</a> - </li> - <li> - <a href="#patch">patch</a> - </li> - <li> - <a href="#path">path</a> - </li> - <li> - <a href="#read">read</a> - </li> - <li> - <a href="#rename">rename</a> - </li> - <li> - <a href="#repo_metadata">repo_metadata</a> - </li> - <li> - <a href="#report_progress">report_progress</a> - </li> - <li> - <a href="#symlink">symlink</a> - </li> - <li> - <a href="#template">template</a> - </li> - <li> - <a href="#watch">watch</a> - </li> - <li> - <a href="#watch_tree">watch_tree</a> - </li> - <li> - <a href="#which">which</a> - </li> - <li> - <a href="#workspace_root">workspace_root</a> - </li> - </ul> - - <h2 id="attr">attr</h2> - <p><pre class="rule-signature">structure repository_ctx.attr</pre></p> - - A struct to access the values of the attributes. The values are provided by the user (if not, a default value is used). - - - <h2 id="delete">delete</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> repository_ctx.delete(path)</pre></p> - - Deletes a file or a directory. Returns a bool, indicating whether the file or directory was actually deleted by this call. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="delete.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string. - - </td> - </tr> - </tbody> - </table> - - <h2 id="download">download</h2> - <p><pre class="rule-signature">unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True)</pre></p> - - Downloads a file to the output path for the provided url and returns a struct containing <code>success</code>, a flag which is <code>true</code> if the download completed successfully, and if successful, a hash of the file with the fields <code>sha256</code> and <code>integrity</code>. When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit <code>canonical_id</code> is highly recommended. e.g. <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="download.url"> - <code>url</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or Iterable of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - List of mirror URLs referencing the same file. - </td> - </tr> - <tr> - <td id="download.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - default is <code>''</code><br/> - path to the output file, relative to the repository directory. - </td> - </tr> - <tr> - <td id="download.sha256"> - <code>sha256</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. - - </td> - </tr> - <tr> - <td id="download.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Set the executable flag on the created file, false by default. - </td> - </tr> - <tr> - <td id="download.allow_fail"> - <code>allow_fail</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If set, indicate the error in the return value instead of raising an error for failed downloads. - - </td> - </tr> - <tr> - <td id="download.canonical_id"> - <code>canonical_id</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (<code>sha256</code> or <code>integrity</code>). - - </td> - </tr> - <tr> - <td id="download.auth"> - <code>auth</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying authentication information for some of the URLs. - </td> - </tr> - <tr> - <td id="download.headers"> - <code>headers</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying http headers for all URLs. - </td> - </tr> - <tr> - <td id="download.integrity"> - <code>integrity</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. - - </td> - </tr> - <tr> - <td id="download.block"> - <code>block</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. - - </td> - </tr> - </tbody> - </table> - - <h2 id="download_and_extract">download_and_extract</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={})</pre></p> - - Downloads a file to the output path for the provided url, extracts it, and returns a struct containing <code>success</code>, a flag which is <code>true</code> if the download completed successfully, and if successful, a hash of the file with the fields <code>sha256</code> and <code>integrity</code>. When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit <code>canonical_id</code> is highly recommended. e.g. <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="download_and_extract.url"> - <code>url</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or Iterable of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - List of mirror URLs referencing the same file. - </td> - </tr> - <tr> - <td id="download_and_extract.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - default is <code>''</code><br/> - Path to the directory where the archive will be unpacked, relative to the repository directory. - - </td> - </tr> - <tr> - <td id="download_and_extract.sha256"> - <code>sha256</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. - - </td> - </tr> - <tr> - <td id="download_and_extract.type"> - <code>type</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. - - </td> - </tr> - <tr> - <td id="download_and_extract.strip_prefix"> - <code>strip_prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - A directory prefix to strip from the extracted files. Many archives contain a +{% include "\_buttons.html" %} +The context of the repository rule containing helper functions and information about attributes. You get a repository_ctx object as an argument to the `implementation` function when you create a repository rule. + +## Members + +- [attr](#attr) +- [delete](#delete) +- [download](#download) +- [download_and_extract](#download_and_extract) +- [execute](#execute) +- [extract](#extract) +- [file](#file) +- [getenv](#getenv) +- [name](#name) +- [original_name](#original_name) +- [os](#os) +- [patch](#patch) +- [path](#path) +- [read](#read) +- [rename](#rename) +- [repo_metadata](#repo_metadata) +- [report_progress](#report_progress) +- [symlink](#symlink) +- [template](#template) +- [watch](#watch) +- [watch_tree](#watch_tree) +- [which](#which) +- [workspace_root](#workspace_root) + +## attr + +``` rule-signature +structure repository_ctx.attr +``` + +A struct to access the values of the attributes. The values are provided by the user (if not, a default value is used). + +## delete + +``` rule-signature +bool repository_ctx.delete(path) +``` + +Deletes a file or a directory. Returns a bool, indicating whether the file or directory was actually deleted by this call. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="delete.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string.</td> +</tr> +</tbody> +</table> + +## download + +``` rule-signature +unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True) +``` + +Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="download.url"><code>url</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or Iterable of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +List of mirror URLs referencing the same file.</td> +</tr> +<tr> +<td id="download.output"><code>output</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +default is <code>''</code><br /> +path to the output file, relative to the repository directory.</td> +</tr> +<tr> +<td id="download.sha256"><code>sha256</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> +</tr> +<tr> +<td id="download.executable"><code>executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Set the executable flag on the created file, false by default.</td> +</tr> +<tr> +<td id="download.allow_fail"><code>allow_fail</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If set, indicate the error in the return value instead of raising an error for failed downloads.</td> +</tr> +<tr> +<td id="download.canonical_id"><code>canonical_id</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (<code>sha256</code> or <code>integrity</code>).</td> +</tr> +<tr> +<td id="download.auth"><code>auth</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying authentication information for some of the URLs.</td> +</tr> +<tr> +<td id="download.headers"><code>headers</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying http headers for all URLs.</td> +</tr> +<tr> +<td id="download.integrity"><code>integrity</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> +</tr> +<tr> +<td id="download.block"><code>block</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual.</td> +</tr> +</tbody> +</table> + +## download_and_extract + +``` rule-signature +struct repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={}) +``` + +Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="download_and_extract.url"><code>url</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or Iterable of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +List of mirror URLs referencing the same file.</td> +</tr> +<tr> +<td id="download_and_extract.output"><code>output</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +default is <code>''</code><br /> +Path to the directory where the archive will be unpacked, relative to the repository directory.</td> +</tr> +<tr> +<td id="download_and_extract.sha256"><code>sha256</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> +</tr> +<tr> +<td id="download_and_extract.type"><code>type</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here.</td> +</tr> +<tr> +<td id="download_and_extract.strip_prefix"><code>strip_prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +A directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the <code>build_file</code>, this field can be used to strip it from extracted files. - <p>For compatibility, this parameter may also be used under the deprecated name -<code>stripPrefix</code>. - - </td> - </tr> - <tr> - <td id="download_and_extract.allow_fail"> - <code>allow_fail</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If set, indicate the error in the return value instead of raising an error for failed downloads. - - </td> - </tr> - <tr> - <td id="download_and_extract.canonical_id"> - <code>canonical_id</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum -(<code>sha256</code> or <code>integrity</code>). - - </td> - </tr> - <tr> - <td id="download_and_extract.auth"> - <code>auth</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying authentication information for some of the URLs. - </td> - </tr> - <tr> - <td id="download_and_extract.headers"> - <code>headers</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying http headers for all URLs. - </td> - </tr> - <tr> - <td id="download_and_extract.integrity"> - <code>integrity</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. - </td> - </tr> - <tr> - <td id="download_and_extract.rename_files"> - <code>rename_files</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. - - </td> - </tr> - </tbody> - </table> - - <h2 id="execute">execute</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/exec_result.html">exec_result</a> repository_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="")</pre></p> - - Executes the command given by the list of arguments. The execution time of the command is limited by <code>timeout</code> (in seconds, default 600 seconds). This method returns an <code>exec_result</code> structure containing the output of the command. The <code>environment</code> map can be used to override some environment variables to be passed to the process. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="execute.arguments"> - <code>arguments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - required<br/> - List of arguments, the first element should be the path to the program to execute. - - </td> - </tr> - <tr> - <td id="execute.timeout"> - <code>timeout</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>600</code><br/> - Maximum duration of the command in seconds (default is 600 seconds). - </td> - </tr> - <tr> - <td id="execute.environment"> - <code>environment</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - Force some environment variables to be set to be passed to the process. The value can be <code>None</code> to remove the environment variable. - - </td> - </tr> - <tr> - <td id="execute.quiet"> - <code>quiet</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - If stdout and stderr should be printed to the terminal. - </td> - </tr> - <tr> - <td id="execute.working_directory"> - <code>working_directory</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>""</code><br/> - Working directory for command execution. +<code>stripPrefix</code>.</p></td> +</tr> +<tr> +<td id="download_and_extract.allow_fail"><code>allow_fail</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If set, indicate the error in the return value instead of raising an error for failed downloads.</td> +</tr> +<tr> +<td id="download_and_extract.canonical_id"><code>canonical_id</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum +(<code>sha256</code> or <code>integrity</code>).</td> +</tr> +<tr> +<td id="download_and_extract.auth"><code>auth</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying authentication information for some of the URLs.</td> +</tr> +<tr> +<td id="download_and_extract.headers"><code>headers</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying http headers for all URLs.</td> +</tr> +<tr> +<td id="download_and_extract.integrity"><code>integrity</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> +</tr> +<tr> +<td id="download_and_extract.rename_files"><code>rename_files</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems.</td> +</tr> +</tbody> +</table> + +## execute + +``` rule-signature +exec_result repository_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="") +``` + +Executes the command given by the list of arguments. The execution time of the command is limited by `timeout` (in seconds, default 600 seconds). This method returns an `exec_result` structure containing the output of the command. The `environment` map can be used to override some environment variables to be passed to the process. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="execute.arguments"><code>arguments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +required<br /> +List of arguments, the first element should be the path to the program to execute.</td> +</tr> +<tr> +<td id="execute.timeout"><code>timeout</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>600</code><br /> +Maximum duration of the command in seconds (default is 600 seconds).</td> +</tr> +<tr> +<td id="execute.environment"><code>environment</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +Force some environment variables to be set to be passed to the process. The value can be <code>None</code> to remove the environment variable.</td> +</tr> +<tr> +<td id="execute.quiet"><code>quiet</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +If stdout and stderr should be printed to the terminal.</td> +</tr> +<tr> +<td id="execute.working_directory"><code>working_directory</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>""</code><br /> +Working directory for command execution. Can be relative to the repository root or absolute. -The default is the repository root. - - </td> - </tr> - </tbody> - </table> - - <h2 id="extract">extract</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto')</pre></p> - - Extract an archive to the repository directory. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="extract.archive"> - <code>archive</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - path to the archive that will be unpacked, relative to the repository directory. - </td> - </tr> - <tr> - <td id="extract.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - default is <code>''</code><br/> - path to the directory where the archive will be unpacked, relative to the repository directory. - </td> - </tr> - <tr> - <td id="extract.strip_prefix"> - <code>strip_prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - a directory prefix to strip from the extracted files. Many archives contain a +The default is the repository root.</td> +</tr> +</tbody> +</table> + +## extract + +``` rule-signature +None repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto') +``` + +Extract an archive to the repository directory. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="extract.archive"><code>archive</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +path to the archive that will be unpacked, relative to the repository directory.</td> +</tr> +<tr> +<td id="extract.output"><code>output</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +default is <code>''</code><br /> +path to the directory where the archive will be unpacked, relative to the repository directory.</td> +</tr> +<tr> +<td id="extract.strip_prefix"><code>strip_prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +a directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the <code>build_file</code>, this field can be used to strip it from extracted files. - <p>For compatibility, this parameter may also be used under the deprecated name -<code>stripPrefix</code>. - - </td> - </tr> - <tr> - <td id="extract.rename_files"> - <code>rename_files</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. - </td> - </tr> - <tr> - <td id="extract.watch_archive"> - <code>watch_archive</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'auto'</code><br/> - whether to <a href="#watch">watch</a> the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. - </td> - </tr> - </tbody> - </table> - - <h2 id="file">file</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.file(path, content='', executable=True, legacy_utf8=False)</pre></p> - - Generates a file in the repository directory with the provided content. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="file.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the file to create, relative to the repository directory. - </td> - </tr> - <tr> - <td id="file.content"> - <code>content</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The content of the file to create, empty by default. - </td> - </tr> - <tr> - <td id="file.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - Set the executable flag on the created file, true by default. - </td> - </tr> - <tr> - <td id="file.legacy_utf8"> - <code>legacy_utf8</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - No-op. This parameter is deprecated and will be removed in a future version of Bazel. - - </td> - </tr> - </tbody> - </table> - - <h2 id="getenv">getenv</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_ctx.getenv(name, default=None)</pre></p> - - Returns the value of an environment variable <code>name</code> as a string if exists, or <code>default</code> if it doesn't. <p>When building incrementally, any change to the value of the variable named by <code>name</code> will cause this repository to be re-fetched. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="getenv.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of desired environment variable. - </td> - </tr> - <tr> - <td id="getenv.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Default value to return if <code>name</code> is not found. - </td> - </tr> - </tbody> - </table> - May return <code>None</code>. - - <h2 id="name">name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_ctx.name</pre></p> - - The canonical name of the external repository created by this rule. This name is guaranteed to be unique among all external repositories, but its exact format is not specified. Use <a href='#original_name'><code>original_name</code></a> instead to get the name that was originally specified as the <code>name</code> when this repository rule was instantiated. - - <h2 id="original_name">original_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_ctx.original_name</pre></p> - - The name that was originally specified as the <code>name</code> attribute when this repository rule was instantiated. This name is not necessarily unique among external repositories. Use <a href='#name'><code>name</code></a> instead to get the canonical name of the external repository. - - <h2 id="os">os</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/repository_os.html">repository_os</a> repository_ctx.os</pre></p> - - A struct to access information from the system. - - <h2 id="patch">patch</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.patch(patch_file, strip=0, *, watch_patch='auto')</pre></p> - - Apply a patch file to the root directory of external repository. The patch file should be a standard <a href="https://en.wikipedia.org/wiki/Diff#Unified_format"> unified diff format</a> file. The Bazel-native patch implementation doesn't support fuzz match and binary patch like the patch command line tool. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="patch.patch_file"> - <code>patch_file</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - The patch file to apply, it can be label, relative path or absolute path. If it's a relative path, it will resolve to the repository directory. - - </td> - </tr> - <tr> - <td id="patch.strip"> - <code>strip</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>0</code><br/> - Strip the specified number of leading components from file names. - </td> - </tr> - <tr> - <td id="patch.watch_patch"> - <code>watch_patch</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'auto'</code><br/> - Whether to <a href="#watch">watch</a> the patch file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. - - </td> - </tr> - </tbody> - </table> - - <h2 id="path">path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> repository_ctx.path(path)</pre></p> - - Returns a path from a string, label, or path. If this context is a <code>repository_ctx</code>, a relative path will resolve relative to the repository directory. If it is a <code>module_ctx</code>, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="path.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - <code>string</code>, <code>Label</code> or <code>path</code> from which to create a path from. - </td> - </tr> - </tbody> - </table> - - <h2 id="read">read</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_ctx.read(path, *, watch='auto')</pre></p> - - Reads the content of a file on the filesystem. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="read.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the file to read from. - </td> - </tr> - <tr> - <td id="read.watch"> - <code>watch</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'auto'</code><br/> - Whether to <a href="#watch">watch</a> the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. - - </td> - </tr> - </tbody> - </table> - - <h2 id="rename">rename</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.rename(src, dst)</pre></p> - - Renames the file or directory from <code>src</code> to <code>dst</code>. Parent directories are created as needed. Fails if the destination path +<code>stripPrefix</code>.</p></td> +</tr> +<tr> +<td id="extract.rename_files"><code>rename_files</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems.</td> +</tr> +<tr> +<td id="extract.watch_archive"><code>watch_archive</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'auto'</code><br /> +whether to <a href="#watch">watch</a> the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> +</tr> +</tbody> +</table> + +## file + +``` rule-signature +None repository_ctx.file(path, content='', executable=True, legacy_utf8=False) +``` + +Generates a file in the repository directory with the provided content. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="file.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the file to create, relative to the repository directory.</td> +</tr> +<tr> +<td id="file.content"><code>content</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The content of the file to create, empty by default.</td> +</tr> +<tr> +<td id="file.executable"><code>executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +Set the executable flag on the created file, true by default.</td> +</tr> +<tr> +<td id="file.legacy_utf8"><code>legacy_utf8</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +No-op. This parameter is deprecated and will be removed in a future version of Bazel.</td> +</tr> +</tbody> +</table> + +## getenv + +``` rule-signature +string repository_ctx.getenv(name, default=None) +``` + +Returns the value of an environment variable `name` as a string if exists, or `default` if it doesn't. + +When building incrementally, any change to the value of the variable named by `name` will cause this repository to be re-fetched. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="getenv.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of desired environment variable.</td> +</tr> +<tr> +<td id="getenv.default"><code>default</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Default value to return if <code>name</code> is not found.</td> +</tr> +</tbody> +</table> + +May return `None`. + +## name + +``` rule-signature +string repository_ctx.name +``` + +The canonical name of the external repository created by this rule. This name is guaranteed to be unique among all external repositories, but its exact format is not specified. Use [`original_name`](#original_name) instead to get the name that was originally specified as the `name` when this repository rule was instantiated. + +## original_name + +``` rule-signature +string repository_ctx.original_name +``` + +The name that was originally specified as the `name` attribute when this repository rule was instantiated. This name is not necessarily unique among external repositories. Use [`name`](#name) instead to get the canonical name of the external repository. + +## os + +``` rule-signature +repository_os repository_ctx.os +``` + +A struct to access information from the system. + +## patch + +``` rule-signature +None repository_ctx.patch(patch_file, strip=0, *, watch_patch='auto') +``` + +Apply a patch file to the root directory of external repository. The patch file should be a standard [unified diff format](https://en.wikipedia.org/wiki/Diff#Unified_format) file. The Bazel-native patch implementation doesn't support fuzz match and binary patch like the patch command line tool. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="patch.patch_file"><code>patch_file</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +The patch file to apply, it can be label, relative path or absolute path. If it's a relative path, it will resolve to the repository directory.</td> +</tr> +<tr> +<td id="patch.strip"><code>strip</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>0</code><br /> +Strip the specified number of leading components from file names.</td> +</tr> +<tr> +<td id="patch.watch_patch"><code>watch_patch</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'auto'</code><br /> +Whether to <a href="#watch">watch</a> the patch file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> +</tr> +</tbody> +</table> + +## path + +``` rule-signature +path repository_ctx.path(path) +``` + +Returns a path from a string, label, or path. If this context is a `repository_ctx`, a relative path will resolve relative to the repository directory. If it is a `module_ctx`, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="path.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +<code>string</code>, <code>Label</code> or <code>path</code> from which to create a path from.</td> +</tr> +</tbody> +</table> + +## read + +``` rule-signature +string repository_ctx.read(path, *, watch='auto') +``` + +Reads the content of a file on the filesystem. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="read.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the file to read from.</td> +</tr> +<tr> +<td id="read.watch"><code>watch</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'auto'</code><br /> +Whether to <a href="#watch">watch</a> the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> +</tr> +</tbody> +</table> + +## rename + +``` rule-signature +None repository_ctx.rename(src, dst) +``` + +Renames the file or directory from `src` to `dst`. Parent directories are created as needed. Fails if the destination path already exists. Both paths must be located within the repository. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="rename.src"> - <code>src</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - The path of the existing file or directory to rename, relative -to the repository directory. - - </td> - </tr> - <tr> - <td id="rename.dst"> - <code>dst</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - The new name to which the file or directory will be renamed to, -relative to the repository directory. - - </td> - </tr> - </tbody> - </table> - - <h2 id="repo_metadata">repo_metadata</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/repo_metadata.html">repo_metadata</a> repository_ctx.repo_metadata(*, reproducible=False, attrs_for_reproducibility={})</pre></p> - - Constructs an opaque object that can be returned from the repo rule's implementation function to provide metadata about its reproducibility. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="repo_metadata.reproducible"> - <code>reproducible</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - States that this repo can be reproducibly refetched; that is, if it were fetched another time with exactly the same input attributes, repo rule definition, watched files and environment variables, etc., then exactly the same output would be produced. This property needs to hold even if other untracked conditions change, such as information from the internet, the path of the workspace root, output from running arbitrary executables, etc. If set to True, this allows the fetched repo contents to be cached across workspaces. <p>Note that setting this to True does not guarantee caching in the repo contents cache; for example, local repo rules are never cached. - - </td> - </tr> - <tr> - <td id="repo_metadata.attrs_for_reproducibility"> - <code>attrs_for_reproducibility</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - If <code>reproducible</code> is False, this can be specified to tell Bazel which attributes of the original repo rule to change to make it reproducible. - - </td> - </tr> - </tbody> - </table> - - <h2 id="report_progress">report_progress</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.report_progress(status='')</pre></p> - - Updates the progress status for the fetching of this repository or module extension. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="report_progress.status"> - <code>status</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - <code>string</code> describing the current status of the fetch progress. - </td> - </tr> - </tbody> - </table> - - <h2 id="symlink">symlink</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.symlink(target, link_name)</pre></p> - - Creates a symlink on the filesystem. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="symlink.target"> - <code>target</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - The path that the symlink should point to. - </td> - </tr> - <tr> - <td id="symlink.link_name"> - <code>link_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - The path of the symlink to create. - </td> - </tr> - </tbody> - </table> - - <h2 id="template">template</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.template(path, template, substitutions={}, executable=True, *, watch_template='auto')</pre></p> - - Generates a new file using a <code>template</code>. Every occurrence in <code>template</code> of a key of <code>substitutions</code> will be replaced by the corresponding value. The result is written in <code>path</code>. An optional <code>executable</code> argument (default to true) can be set to turn on or off the executable bit. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="template.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the file to create, relative to the repository directory. - </td> - </tr> - <tr> - <td id="template.template"> - <code>template</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path to the template file. - </td> - </tr> - <tr> - <td id="template.substitutions"> - <code>substitutions</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - Substitutions to make when expanding the template. - </td> - </tr> - <tr> - <td id="template.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - Set the executable flag on the created file, true by default. - </td> - </tr> - <tr> - <td id="template.watch_template"> - <code>watch_template</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'auto'</code><br/> - Whether to <a href="#watch">watch</a> the template file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information. - - </td> - </tr> - </tbody> - </table> - - <h2 id="watch">watch</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.watch(path)</pre></p> - - Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time.<p>"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does <em>not</em> include changes to any files under the directory if the path is a directory. For that, use <a href="path.html#readdir"><code>path.readdir()</code></a> instead.<p>Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="watch.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the file to watch. - </td> - </tr> - </tbody> - </table> - - <h2 id="watch_tree">watch_tree</h2> - <p><pre class="rule-signature"><code>None</code> repository_ctx.watch_tree(path)</pre></p> - - Tells Bazel to watch for changes to any files or directories transitively under the given path. Any changes to the contents of files, the existence of files or directories, file names or directory names, will cause this repo to be refetched.<p>Note that attempting to watch paths inside the repo currently being fetched will result in an error. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="watch_tree.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../builtins/path.html">path</a>; - required<br/> - Path of the directory tree to watch. - </td> - </tr> - </tbody> - </table> - - <h2 id="which">which</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> repository_ctx.which(program)</pre></p> - - Returns the <code>path</code> of the corresponding program or <code>None</code> if there is no such program in the path. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="which.program"> - <code>program</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Program to find in the path. - </td> - </tr> - </tbody> - </table> - May return <code>None</code>. - - <h2 id="workspace_root">workspace_root</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/path.html">path</a> repository_ctx.workspace_root</pre></p> - - The path to the root workspace of the bazel invocation. - - -</body> -</html> - -<!-- {% endraw %} --> +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="rename.src"><code>src</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +The path of the existing file or directory to rename, relative +to the repository directory.</td> +</tr> +<tr> +<td id="rename.dst"><code>dst</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +The new name to which the file or directory will be renamed to, +relative to the repository directory.</td> +</tr> +</tbody> +</table> + +## repo_metadata + +``` rule-signature +repo_metadata repository_ctx.repo_metadata(*, reproducible=False, attrs_for_reproducibility={}) +``` + +Constructs an opaque object that can be returned from the repo rule's implementation function to provide metadata about its reproducibility. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="repo_metadata.reproducible"><code>reproducible</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +States that this repo can be reproducibly refetched; that is, if it were fetched another time with exactly the same input attributes, repo rule definition, watched files and environment variables, etc., then exactly the same output would be produced. This property needs to hold even if other untracked conditions change, such as information from the internet, the path of the workspace root, output from running arbitrary executables, etc. If set to True, this allows the fetched repo contents to be cached across workspaces. +<p>Note that setting this to True does not guarantee caching in the repo contents cache; for example, local repo rules are never cached.</p></td> +</tr> +<tr> +<td id="repo_metadata.attrs_for_reproducibility"><code>attrs_for_reproducibility</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +If <code>reproducible</code> is False, this can be specified to tell Bazel which attributes of the original repo rule to change to make it reproducible.</td> +</tr> +</tbody> +</table> + +## report_progress + +``` rule-signature +None repository_ctx.report_progress(status='') +``` + +Updates the progress status for the fetching of this repository or module extension. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="report_progress.status"><code>status</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +<code>string</code> describing the current status of the fetch progress.</td> +</tr> +</tbody> +</table> + +## symlink + +``` rule-signature +None repository_ctx.symlink(target, link_name) +``` + +Creates a symlink on the filesystem. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="symlink.target"><code>target</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +The path that the symlink should point to.</td> +</tr> +<tr> +<td id="symlink.link_name"><code>link_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +The path of the symlink to create.</td> +</tr> +</tbody> +</table> + +## template + +``` rule-signature +None repository_ctx.template(path, template, substitutions={}, executable=True, *, watch_template='auto') +``` + +Generates a new file using a `template`. Every occurrence in `template` of a key of `substitutions` will be replaced by the corresponding value. The result is written in `path`. An optional `executable` argument (default to true) can be set to turn on or off the executable bit. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="template.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the file to create, relative to the repository directory.</td> +</tr> +<tr> +<td id="template.template"><code>template</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path to the template file.</td> +</tr> +<tr> +<td id="template.substitutions"><code>substitutions</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +Substitutions to make when expanding the template.</td> +</tr> +<tr> +<td id="template.executable"><code>executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +Set the executable flag on the created file, true by default.</td> +</tr> +<tr> +<td id="template.watch_template"><code>watch_template</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'auto'</code><br /> +Whether to <a href="#watch">watch</a> the template file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> +</tr> +</tbody> +</table> + +## watch + +``` rule-signature +None repository_ctx.watch(path) +``` + +Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time. + +"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does *not* include changes to any files under the directory if the path is a directory. For that, use [`path.readdir()`](path.html#readdir) instead. + +Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="watch.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the file to watch.</td> +</tr> +</tbody> +</table> + +## watch_tree + +``` rule-signature +None repository_ctx.watch_tree(path) +``` + +Tells Bazel to watch for changes to any files or directories transitively under the given path. Any changes to the contents of files, the existence of files or directories, file names or directory names, will cause this repo to be refetched. + +Note that attempting to watch paths inside the repo currently being fetched will result in an error. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="watch_tree.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; +required<br /> +Path of the directory tree to watch.</td> +</tr> +</tbody> +</table> + +## which + +``` rule-signature +path repository_ctx.which(program) +``` + +Returns the `path` of the corresponding program or `None` if there is no such program in the path. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="which.program"><code>program</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Program to find in the path.</td> +</tr> +</tbody> +</table> + +May return `None`. + +## workspace_root + +``` rule-signature +path repository_ctx.workspace_root +``` + +The path to the root workspace of the bazel invocation. diff --git a/rules/lib/builtins/repository_os.mdx b/rules/lib/builtins/repository_os.mdx index debe4c8..bb7f1fd 100644 --- a/rules/lib/builtins/repository_os.mdx +++ b/rules/lib/builtins/repository_os.mdx @@ -2,54 +2,40 @@ title: 'repository_os' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.repository_os">repository_os</h1> +# repository_os {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkOS.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Various data about the current platform Bazel is running on. -<h2>Members</h2> -<ul> - <li> - <a href="#arch">arch</a> - </li> - <li> - <a href="#environ">environ</a> - </li> - <li> - <a href="#name">name</a> - </li> - </ul> - - <h2 id="arch">arch</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_os.arch</pre></p> +## Members - A string identifying the architecture Bazel is running on (the value of the <code>"os.arch"</code> Java property converted to lower case). +- [arch](#arch) +- [environ](#environ) +- [name](#name) +## arch - <h2 id="environ">environ</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> repository_os.environ</pre></p> +``` rule-signature +string repository_os.arch +``` - The dictionary of environment variables. <p><b>NOTE</b>: Retrieving an environment variable from this dictionary does not establish a dependency from a repository rule or module extension to the environment variable. To establish a dependency when looking up an environment variable, use either <code>repository_ctx.getenv</code> or <code>module_ctx.getenv</code> instead. +A string identifying the architecture Bazel is running on (the value of the `"os.arch"` Java property converted to lower case). +## environ - <h2 id="name">name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_os.name</pre></p> +``` rule-signature +dict repository_os.environ +``` - A string identifying the operating system Bazel is running on (the value of the <code>"os.name"</code> Java property converted to lower case). +The dictionary of environment variables. +**NOTE**: Retrieving an environment variable from this dictionary does not establish a dependency from a repository rule or module extension to the environment variable. To establish a dependency when looking up an environment variable, use either `repository_ctx.getenv` or `module_ctx.getenv` instead. +## name -</body> -</html> +``` rule-signature +string repository_os.name +``` -<!-- {% endraw %} --> +A string identifying the operating system Bazel is running on (the value of the `"os.name"` Java property converted to lower case). diff --git a/rules/lib/builtins/repository_rule.mdx b/rules/lib/builtins/repository_rule.mdx index 79db2a3..9280546 100644 --- a/rules/lib/builtins/repository_rule.mdx +++ b/rules/lib/builtins/repository_rule.mdx @@ -2,25 +2,8 @@ title: 'repository_rule' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.repository_rule">repository_rule</h1> +# repository_rule {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A callable value that may be invoked within the implementation function of a module extension to instantiate and return a repository rule. Created by <a href="../globals/bzl.html#repository_rule"><code>repository_rule()</code></a>. - - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +A callable value that may be invoked within the implementation function of a module extension to instantiate and return a repository rule. Created by [`repository_rule()`](../globals/bzl.html#repository_rule). diff --git a/rules/lib/builtins/root.mdx b/rules/lib/builtins/root.mdx index 08e3e50..b53b1f1 100644 --- a/rules/lib/builtins/root.mdx +++ b/rules/lib/builtins/root.mdx @@ -2,35 +2,20 @@ title: 'root' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.root">root</h1> +# root {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileRootApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A root for files. The roots are the directories containing files, and they are mapped together into a single directory tree to form the execution environment. -<h2>Members</h2> -<ul> - <li> - <a href="#path">path</a> - </li> - </ul> - - <h2 id="path">path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> root.path</pre></p> +## Members - Returns the relative path from the exec root to the actual root. +- [path](#path) +## path -</body> -</html> +``` rule-signature +string root.path +``` -<!-- {% endraw %} --> +Returns the relative path from the exec root to the actual root. diff --git a/rules/lib/builtins/rule.mdx b/rules/lib/builtins/rule.mdx index 7c6069e..3e9629d 100644 --- a/rules/lib/builtins/rule.mdx +++ b/rules/lib/builtins/rule.mdx @@ -2,29 +2,12 @@ title: 'rule' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.rule">rule</h1> +# rule {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RuleFunctionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A callable value representing the type of a native or Starlark rule (created by -<a href="../globals/bzl.html#rule"><code>rule()</code></a>). Calling the value during +[`rule()`](../globals/bzl.html#rule)). Calling the value during evaluation of a package's BUILD file creates an instance of the rule and adds it to the package's target set. For more information, visit this page about -<a href ="https://bazel.build/extending/rules">Rules</a>. - - - - -</body> -</html> - -<!-- {% endraw %} --> +[Rules](https://bazel.build/extending/rules). diff --git a/rules/lib/builtins/rule_attributes.mdx b/rules/lib/builtins/rule_attributes.mdx index 8b444c4..71866c5 100644 --- a/rules/lib/builtins/rule_attributes.mdx +++ b/rules/lib/builtins/rule_attributes.mdx @@ -2,91 +2,95 @@ title: 'rule_attributes' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.rule_attributes">rule_attributes</h1> +# rule_attributes {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttributesCollectionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Information about attributes of a rule an aspect is applied to. -<h2>Members</h2> -<ul> - <li> - <a href="#attr">attr</a> - </li> - <li> - <a href="#exec_groups">exec_groups</a> - </li> - <li> - <a href="#executable">executable</a> - </li> - <li> - <a href="#file">file</a> - </li> - <li> - <a href="#files">files</a> - </li> - <li> - <a href="#kind">kind</a> - </li> - <li> - <a href="#toolchains">toolchains</a> - </li> - <li> - <a href="#var">var</a> - </li> - </ul> +## Members + +- [attr](#attr) +- [exec_groups](#exec_groups) +- [executable](#executable) +- [file](#file) +- [files](#files) +- [kind](#kind) +- [toolchains](#toolchains) +- [var](#var) + +## attr + +``` rule-signature +struct rule_attributes.attr +``` + +A struct to access the values of the [attributes](https://bazel.build/extending/rules#attributes). The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the [`attrs` dict](../globals/bzl.html#rule.attrs) provided to the [`rule` function](../globals/bzl.html#rule). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl). + +## exec_groups + +``` rule-signature +ExecGroupCollection rule_attributes.exec_groups +``` + +A collection of the execution groups available for the rule the aspect is applied to, indexed by their names. + +## executable + +``` rule-signature +struct rule_attributes.executable +``` + +A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). - <h2 id="attr">attr</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> rule_attributes.attr</pre></p> +## file - A struct to access the values of the <a href='https://bazel.build/extending/rules#attributes'>attributes</a>. The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the <a href='../globals/bzl.html#rule.attrs'><code>attrs</code> dict</a> provided to the <a href='../globals/bzl.html#rule'><code>rule</code> function</a>. <a href="https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl">See example of use</a>. +``` rule-signature +struct rule_attributes.file +``` - <h2 id="exec_groups">exec_groups</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/ExecGroupCollection.html">ExecGroupCollection</a> rule_attributes.exec_groups</pre></p> +A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: - A collection of the execution groups available for the rule the aspect is applied to, indexed by their names. +``` python +list(ctx.attr.<ATTR>.files)[0] +``` - <h2 id="executable">executable</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> rule_attributes.executable</pre></p> +In other words, use `file` to access the (singular) [default output](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). - A <code>struct</code> containing executable files defined in <a href='../toplevel/attr.html#label'>label type attributes</a> marked as <a href='../toplevel/attr.html#label.executable'><code>executable=True</code></a>. The struct fields correspond to the attribute names. Each value in the struct is either a <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an optional attribute is not specified in the rule then the corresponding struct value is <code>None</code>. If a label type is not marked as <code>executable=True</code>, no corresponding struct field is generated. <a href="https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl">See example of use</a>. +## files - <h2 id="file">file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> rule_attributes.file</pre></p> +``` rule-signature +struct rule_attributes.files +``` - A <code>struct</code> containing files defined in <a href='../toplevel/attr.html#label'>label type attributes</a> marked as <a href='../toplevel/attr.html#label.allow_single_file'><code>allow_single_file</code></a>. The struct fields correspond to the attribute names. The struct value is always a <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an optional attribute is not specified in the rule then the corresponding struct value is <code>None</code>. If a label type is not marked as <code>allow_single_file</code>, no corresponding struct field is generated. It is a shortcut for:<pre class=language-python>list(ctx.attr.<ATTR>.files)[0]</pre>In other words, use <code>file</code> to access the (singular) <a href="https://bazel.build/extending/rules#requesting_output_files">default output</a> of a dependency. <a href="https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl">See example of use</a>. +A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.html)s. It is a shortcut for: - <h2 id="files">files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> rule_attributes.files</pre></p> +``` python +[f for t in ctx.attr.<ATTR> for f in t.files] +``` - A <code>struct</code> containing files defined in <a href='../toplevel/attr.html#label'>label</a> or <a href='../toplevel/attr.html#label_list'>label list</a> type attributes. The struct fields correspond to the attribute names. The struct values are <code>list</code> of <a href='../builtins/File.html'><code>File</code></a>s. It is a shortcut for:<pre class=language-python>[f for t in ctx.attr.<ATTR> for f in t.files]</pre> In other words, use <code>files</code> to access the <a href="https://bazel.build/extending/rules#requesting_output_files"> default outputs</a> of a dependency. <a href="https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl">See example of use</a>. +In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). - <h2 id="kind">kind</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> rule_attributes.kind</pre></p> +## kind - The kind of a rule, such as 'cc_library' +``` rule-signature +string rule_attributes.kind +``` - <h2 id="toolchains">toolchains</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/ToolchainContext.html">ToolchainContext</a> rule_attributes.toolchains</pre></p> +The kind of a rule, such as 'cc_library' - Toolchains for the default exec group of the rule the aspect is applied to. +## toolchains - <h2 id="var">var</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> rule_attributes.var</pre></p> +``` rule-signature +ToolchainContext rule_attributes.toolchains +``` - Dictionary (String to String) of configuration variables. +Toolchains for the default exec group of the rule the aspect is applied to. +## var -</body> -</html> +``` rule-signature +dict rule_attributes.var +``` -<!-- {% endraw %} --> +Dictionary (String to String) of configuration variables. diff --git a/rules/lib/builtins/runfiles.mdx b/rules/lib/builtins/runfiles.mdx index 0333826..e5bd09e 100644 --- a/rules/lib/builtins/runfiles.mdx +++ b/rules/lib/builtins/runfiles.mdx @@ -2,135 +2,107 @@ title: 'runfiles' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.runfiles">runfiles</h1> +# runfiles {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A container of information regarding a set of files required at runtime by an executable. This object should be passed via <a href="../providers/DefaultInfo.html"><code>DefaultInfo</code></a> in order to tell the build system about the runfiles needed by the outputs produced by the rule. -<p> - See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a> for details. </p> - - -<h2>Members</h2> -<ul> - <li> - <a href="#empty_filenames">empty_filenames</a> - </li> - <li> - <a href="#files">files</a> - </li> - <li> - <a href="#merge">merge</a> - </li> - <li> - <a href="#merge_all">merge_all</a> - </li> - <li> - <a href="#root_symlinks">root_symlinks</a> - </li> - <li> - <a href="#symlinks">symlinks</a> - </li> - </ul> - - <h2 id="empty_filenames">empty_filenames</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> runfiles.empty_filenames</pre></p> - - Returns names of empty files to create. - - <h2 id="files">files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> runfiles.files</pre></p> - - Returns the set of runfiles as files. - - <h2 id="merge">merge</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> runfiles.merge(other)</pre></p> - - Returns a new runfiles object that includes all the contents of this one and the argument. <p> -<i>Note:</i> When you have many runfiles objects to merge, use <a href="#merge_all"><code>merge_all()</code></a> rather than calling <code>merge</code> in a loop. This avoids constructing deep depset structures which can cause build failures. </p> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="merge.other"> - <code>other</code> - </td> - <td> - <a class="anchor" href="../builtins/runfiles.html">runfiles</a>; - required<br/> - The runfiles object to merge into this. - </td> - </tr> - </tbody> - </table> - - <h2 id="merge_all">merge_all</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> runfiles.merge_all(other)</pre></p> - - Returns a new runfiles object that includes all the contents of this one and of the runfiles objects in the argument. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="merge_all.other"> - <code>other</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/runfiles.html">runfiles</a>s; - required<br/> - The sequence of runfiles objects to merge into this. - </td> - </tr> - </tbody> - </table> - - <h2 id="root_symlinks">root_symlinks</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> runfiles.root_symlinks</pre></p> - - Returns the set of root symlinks. - - <h2 id="symlinks">symlinks</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> runfiles.symlinks</pre></p> - - Returns the set of symlinks. - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +A container of information regarding a set of files required at runtime by an executable. This object should be passed via [`DefaultInfo`](../providers/DefaultInfo.html) in order to tell the build system about the runfiles needed by the outputs produced by the rule. + +See [runfiles guide](https://bazel.build/extending/rules#runfiles) for details. + +## Members + +- [empty_filenames](#empty_filenames) +- [files](#files) +- [merge](#merge) +- [merge_all](#merge_all) +- [root_symlinks](#root_symlinks) +- [symlinks](#symlinks) + +## empty_filenames + +``` rule-signature +depset runfiles.empty_filenames +``` + +Returns names of empty files to create. + +## files + +``` rule-signature +depset runfiles.files +``` + +Returns the set of runfiles as files. + +## merge + +``` rule-signature +runfiles runfiles.merge(other) +``` + +Returns a new runfiles object that includes all the contents of this one and the argument. + +*Note:* When you have many runfiles objects to merge, use [`merge_all()`](#merge_all) rather than calling `merge` in a loop. This avoids constructing deep depset structures which can cause build failures. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="merge.other"><code>other</code></td> +<td><a href="../builtins/runfiles.html" class="anchor">runfiles</a>; +required<br /> +The runfiles object to merge into this.</td> +</tr> +</tbody> +</table> + +## merge_all + +``` rule-signature +runfiles runfiles.merge_all(other) +``` + +Returns a new runfiles object that includes all the contents of this one and of the runfiles objects in the argument. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="merge_all.other"><code>other</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/runfiles.html" class="anchor">runfiles</a>s; +required<br /> +The sequence of runfiles objects to merge into this.</td> +</tr> +</tbody> +</table> + +## root_symlinks + +``` rule-signature +depset runfiles.root_symlinks +``` + +Returns the set of root symlinks. + +## symlinks + +``` rule-signature +depset runfiles.symlinks +``` + +Returns the set of symlinks. diff --git a/rules/lib/builtins/struct.mdx b/rules/lib/builtins/struct.mdx index 66a4b38..e44043c 100644 --- a/rules/lib/builtins/struct.mdx +++ b/rules/lib/builtins/struct.mdx @@ -2,62 +2,45 @@ title: 'struct' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.struct">struct</h1> +# struct {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/StructApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A generic object with fields.<p>Structs fields cannot be reassigned once the struct is created. Two structs are equal if they have the same fields and if corresponding field values are equal. - -<h2>Members</h2> -<ul> - <li> - <a href="#struct">struct</a> - </li> - </ul> - - <h2 id="struct">struct</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> struct(**kwargs)</pre></p> - - Creates an immutable struct using the keyword arguments as attributes. It is used to group multiple values together. Example:<br><pre class="language-python">s = struct(x = 2, y = 3) -return s.x + getattr(s, "y") # returns 5</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="struct.kwargs"> - <code>kwargs</code> - </td> - <td> - default is <code>{}</code><br/> - Dictionary of arguments. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +A generic object with fields. + +Structs fields cannot be reassigned once the struct is created. Two structs are equal if they have the same fields and if corresponding field values are equal. + +## Members + +- [struct](#struct) + +## struct + +``` rule-signature +struct struct(**kwargs) +``` + +Creates an immutable struct using the keyword arguments as attributes. It is used to group multiple values together. Example: + +``` python +s = struct(x = 2, y = 3) +return s.x + getattr(s, "y") # returns 5 +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="struct.kwargs"><code>kwargs</code></td> +<td>default is <code>{}</code><br /> +Dictionary of arguments.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/builtins/subrule_ctx.mdx b/rules/lib/builtins/subrule_ctx.mdx index c28d21d..7635743 100644 --- a/rules/lib/builtins/subrule_ctx.mdx +++ b/rules/lib/builtins/subrule_ctx.mdx @@ -2,59 +2,47 @@ title: 'subrule_ctx' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.subrule_ctx">subrule_ctx</h1> +# subrule_ctx {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkSubrule.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A context object passed to the implementation function of a subrule. -<h2>Members</h2> -<ul> - <li> - <a href="#actions">actions</a> - </li> - <li> - <a href="#fragments">fragments</a> - </li> - <li> - <a href="#label">label</a> - </li> - <li> - <a href="#toolchains">toolchains</a> - </li> - </ul> +## Members + +- [actions](#actions) +- [fragments](#fragments) +- [label](#label) +- [toolchains](#toolchains) + +## actions - <h2 id="actions">actions</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/actions.html">actions</a> subrule_ctx.actions</pre></p> +``` rule-signature +actions subrule_ctx.actions +``` - Contains methods for declaring output files and the actions that produce them +Contains methods for declaring output files and the actions that produce them - <h2 id="fragments">fragments</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/fragments.html">fragments</a> subrule_ctx.fragments</pre></p> +## fragments - Allows access to configuration fragments in target configuration. +``` rule-signature +fragments subrule_ctx.fragments +``` - <h2 id="label">label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> subrule_ctx.label</pre></p> +Allows access to configuration fragments in target configuration. - The label of the target currently being analyzed +## label - <h2 id="toolchains">toolchains</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/ToolchainContext.html">ToolchainContext</a> subrule_ctx.toolchains</pre></p> +``` rule-signature +Label subrule_ctx.label +``` - Contains methods for declaring output files and the actions that produce them +The label of the target currently being analyzed +## toolchains -</body> -</html> +``` rule-signature +ToolchainContext subrule_ctx.toolchains +``` -<!-- {% endraw %} --> +Contains methods for declaring output files and the actions that produce them diff --git a/rules/lib/builtins/tag_class.mdx b/rules/lib/builtins/tag_class.mdx index 07f5547..6af948b 100644 --- a/rules/lib/builtins/tag_class.mdx +++ b/rules/lib/builtins/tag_class.mdx @@ -2,25 +2,8 @@ title: 'tag_class' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.tag_class">tag_class</h1> +# tag_class {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Defines a schema of attributes for a tag, created by <a href="../globals/bzl.html#tag_class"><code>tag_class()</code></a>. - - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +Defines a schema of attributes for a tag, created by [`tag_class()`](../globals/bzl.html#tag_class). diff --git a/rules/lib/builtins/template_ctx.mdx b/rules/lib/builtins/template_ctx.mdx index bd42877..38433e7 100644 --- a/rules/lib/builtins/template_ctx.mdx +++ b/rules/lib/builtins/template_ctx.mdx @@ -2,174 +2,121 @@ title: 'template_ctx' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.template_ctx">template_ctx</h1> +# template_ctx {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkTemplateContextApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A context object that is passed to the action template expansion function. -<h2>Members</h2> -<ul> - <li> - <a href="#args">args</a> - </li> - <li> - <a href="#declare_file">declare_file</a> - </li> - <li> - <a href="#run">run</a> - </li> - </ul> - - <h2 id="args">args</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Args.html">Args</a> template_ctx.args()</pre></p> - - Returns an Args object that can be used to build memory-efficient command lines. - - <h2 id="declare_file">declare_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> template_ctx.declare_file(filename, *, directory)</pre></p> - - Declares that implementation creates a file with the given filename within the specified directory.<p>Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned <code>File</code> object to the action's construction function. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="declare_file.filename"> - <code>filename</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The relative path of the file within the directory. - </td> - </tr> - <tr> - <td id="declare_file.directory"> - <code>directory</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The directory in which the file should be created. - </td> - </tr> - </tbody> - </table> - - <h2 id="run">run</h2> - <p><pre class="rule-signature"><code>None</code> template_ctx.run(*, outputs, inputs=[], executable, tools=None, arguments=[], progress_message=None)</pre></p> - - Creates an action that runs an executable. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="run.outputs"> - <code>outputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - required<br/> - List of the output files of the action. - </td> - </tr> - <tr> - <td id="run.inputs"> - <code>inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>[]</code><br/> - List or depset of the input files of the action. - </td> - </tr> - <tr> - <td id="run.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a>; - required<br/> - The executable file to be called by the action. - </td> - </tr> - <tr> - <td id="run.tools"> - <code>tools</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. <p> -When a list is provided, it can be a heterogenous collection of: +## Members + +- [args](#args) +- [declare_file](#declare_file) +- [run](#run) + +## args + +``` rule-signature +Args template_ctx.args() +``` + +Returns an Args object that can be used to build memory-efficient command lines. + +## declare_file + +``` rule-signature +File template_ctx.declare_file(filename, *, directory) +``` + +Declares that implementation creates a file with the given filename within the specified directory. + +Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned `File` object to the action's construction function. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="declare_file.filename"><code>filename</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The relative path of the file within the directory.</td> +</tr> +<tr> +<td id="declare_file.directory"><code>directory</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The directory in which the file should be created.</td> +</tr> +</tbody> +</table> + +## run + +``` rule-signature +None template_ctx.run(*, outputs, inputs=[], executable, tools=None, arguments=[], progress_message=None) +``` + +Creates an action that runs an executable. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="run.outputs"><code>outputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +required<br /> +List of the output files of the action.</td> +</tr> +<tr> +<td id="run.inputs"><code>inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>[]</code><br /> +List or depset of the input files of the action.</td> +</tr> +<tr> +<td id="run.executable"><code>executable</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <a href="../core/string.html" class="anchor">string</a>; or <a href="../providers/FilesToRunProvider.html" class="anchor">FilesToRunProvider</a>; +required<br /> +The executable file to be called by the action.</td> +</tr> +<tr> +<td id="run.tools"><code>tools</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. +<p>When a list is provided, it can be a heterogenous collection of:</p> <ul> - <li><code>File</code>s</li> - <li><code>FilesToRunProvider</code> instances</li> - <li><code>depset</code>s of <code>File</code>s</li> +<li><code>File</code>s</li> +<li><code>FilesToRunProvider</code> instances</li> +<li><code>depset</code>s of <code>File</code>s</li> </ul> -<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. -</p> - - </td> - </tr> - <tr> - <td id="run.arguments"> - <code>arguments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects. - </td> - </tr> - <tr> - <td id="run.progress_message"> - <code>progress_message</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Progress message to show to the user during the build. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs.</td> +</tr> +<tr> +<td id="run.arguments"><code>arguments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects.</td> +</tr> +<tr> +<td id="run.progress_message"><code>progress_message</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Progress message to show to the user during the build.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/builtins/toolchain_type.mdx b/rules/lib/builtins/toolchain_type.mdx index 490100e..ee9df28 100644 --- a/rules/lib/builtins/toolchain_type.mdx +++ b/rules/lib/builtins/toolchain_type.mdx @@ -2,43 +2,29 @@ title: 'toolchain_type' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.toolchain_type">toolchain_type</h1> +# toolchain_type {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkToolchainTypeRequirement.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A data type describing a dependency on a specific toolchain type. -<h2>Members</h2> -<ul> - <li> - <a href="#mandatory">mandatory</a> - </li> - <li> - <a href="#toolchain_type">toolchain_type</a> - </li> - </ul> +## Members - <h2 id="mandatory">mandatory</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> toolchain_type.mandatory</pre></p> +- [mandatory](#mandatory) +- [toolchain_type](#toolchain_type) - Whether the toolchain type is mandatory or optional. +## mandatory - <h2 id="toolchain_type">toolchain_type</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> toolchain_type.toolchain_type</pre></p> +``` rule-signature +bool toolchain_type.mandatory +``` - The toolchain type that is required. +Whether the toolchain type is mandatory or optional. +## toolchain_type -</body> -</html> +``` rule-signature +Label toolchain_type.toolchain_type +``` -<!-- {% endraw %} --> +The toolchain type that is required. diff --git a/rules/lib/builtins/transition.mdx b/rules/lib/builtins/transition.mdx index cd002fc..d5e39f5 100644 --- a/rules/lib/builtins/transition.mdx +++ b/rules/lib/builtins/transition.mdx @@ -2,32 +2,29 @@ title: 'transition' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.transition">transition</h1> +# transition {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigurationTransitionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} + +Represents a configuration transition across a dependency edge. For example, if `//package:foo` depends on `//package:bar` with a configuration transition, then the configuration of `//package:bar` (and its dependencies) will be `//package:foo`'s configuration plus the changes specified by the transition function. + +## Members + +- [transition](#transition) + +## transition + +``` rule-signature +transition transition(*, implementation, inputs, outputs) +``` -<p>Represents a configuration transition across a dependency edge. For example, if <code>//package:foo</code> depends on <code>//package:bar</code> with a configuration transition, then the configuration of <code>//package:bar</code> (and its dependencies) will be <code>//package:foo</code>'s configuration plus the changes specified by the transition function. +A transition that reads a set of input build settings and writes a set of output build settings. -<h2>Members</h2> -<ul> - <li> - <a href="#transition">transition</a> - </li> - </ul> +Example: - <h2 id="transition">transition</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> transition(*, implementation, inputs, outputs)</pre></p> +``` python - A transition that reads a set of input build settings and writes a set of output build settings.<p>Example:</p><p><pre class="language-python"> def _transition_impl(settings, attr): # This transition just reads the current CPU value as a demonstration. # A real transition could incorporate this into its followup logic. @@ -38,57 +35,40 @@ build_in_debug_mode = transition( implementation = _transition_impl, inputs = ["//command_line_option:cpu"], outputs = ["//command_line_option:compilation_mode"], -)</pre></p><p>For more details see <a href="https://bazel.build/rules/config#user-defined-transitions">here</a>.</p> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="transition.implementation"> - <code>implementation</code> - </td> - <td> - callable; - required<br/> - The function implementing this transition. This function always has two parameters: <code>settings</code> and <code>attr</code>. The <code>settings</code> param is a dictionary whose set of keys is defined by the inputs parameter. So, for each build setting <code>--//foo=bar</code>, if <code>inputs</code> contains <code>//foo</code>, <code>settings</code> will have an entry <code>settings['//foo']='bar'</code>.<p>The <code>attr</code> param is a reference to <code>ctx.attr</code>. This gives the implementation function access to the rule's attributes to make attribute-parameterized transitions possible.<p>This function must return a <code>dict</code> from build setting identifier to build setting value; this represents the configuration transition: for each entry in the returned <code>dict</code>, the transition updates that setting to the new value. All other settings are unchanged. This function can also return a <code>list</code> of <code>dict</code>s or a <code>dict</code> of <code>dict</code>s in the case of a split transition. - </td> - </tr> - <tr> - <td id="transition.inputs"> - <code>inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - List of build settings that can be read by this transition. This becomes the key set of the settings parameter of the implementation function parameter. - </td> - </tr> - <tr> - <td id="transition.outputs"> - <code>outputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - List of build settings that can be written by this transition. This must be a superset of the key set of the dictionary returned by this transition. - </td> - </tr> - </tbody> - </table> +) +``` +For more details see [here](https://bazel.build/rules/config#user-defined-transitions). -</body> -</html> +### Parameters -<!-- {% endraw %} --> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="transition.implementation"><code>implementation</code></td> +<td>callable; +required<br /> +The function implementing this transition. This function always has two parameters: <code>settings</code> and <code>attr</code>. The <code>settings</code> param is a dictionary whose set of keys is defined by the inputs parameter. So, for each build setting <code>--//foo=bar</code>, if <code>inputs</code> contains <code>//foo</code>, <code>settings</code> will have an entry <code>settings['//foo']='bar'</code>. +<p>The <code>attr</code> param is a reference to <code>ctx.attr</code>. This gives the implementation function access to the rule's attributes to make attribute-parameterized transitions possible.</p> +<p>This function must return a <code>dict</code> from build setting identifier to build setting value; this represents the configuration transition: for each entry in the returned <code>dict</code>, the transition updates that setting to the new value. All other settings are unchanged. This function can also return a <code>list</code> of <code>dict</code>s or a <code>dict</code> of <code>dict</code>s in the case of a split transition.</p></td> +</tr> +<tr> +<td id="transition.inputs"><code>inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +List of build settings that can be read by this transition. This becomes the key set of the settings parameter of the implementation function parameter.</td> +</tr> +<tr> +<td id="transition.outputs"><code>outputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +List of build settings that can be written by this transition. This must be a superset of the key set of the dictionary returned by this transition.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/builtins/wasm_exec_result.mdx b/rules/lib/builtins/wasm_exec_result.mdx index b598a24..25f6706 100644 --- a/rules/lib/builtins/wasm_exec_result.mdx +++ b/rules/lib/builtins/wasm_exec_result.mdx @@ -2,59 +2,44 @@ title: 'wasm_exec_result' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.wasm_exec_result">wasm_exec_result</h1> +# wasm_exec_result {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkWasmExecutionResult.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} The result of executing a WebAssembly function with -<code>repository_ctx.execute_wasm()</code>. It contains the function's +`repository_ctx.execute_wasm()`. It contains the function's return value and output buffer. -<p>If execution failed before the function returned then the return code will be negative -and the <code>error_message</code> field will be set. +If execution failed before the function returned then the return code will be negative +and the `error_message` field will be set. +## Members -<h2>Members</h2> -<ul> - <li> - <a href="#error_message">error_message</a> - </li> - <li> - <a href="#output">output</a> - </li> - <li> - <a href="#return_code">return_code</a> - </li> - </ul> +- [error_message](#error_message) +- [output](#output) +- [return_code](#return_code) - <h2 id="error_message">error_message</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> wasm_exec_result.error_message</pre></p> +## error_message - Contains an error message if execution failed before the function returned. +``` rule-signature +string wasm_exec_result.error_message +``` - <h2 id="output">output</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> wasm_exec_result.output</pre></p> +Contains an error message if execution failed before the function returned. - The content of the output buffer returned by the WebAssembly function. +## output - <h2 id="return_code">return_code</h2> - <p><pre class="rule-signature">long wasm_exec_result.return_code</pre></p> +``` rule-signature +string wasm_exec_result.output +``` - The return value of the WebAssembly function, or a negative value if execution -was terminated before the function returned. +The content of the output buffer returned by the WebAssembly function. +## return_code +``` rule-signature +long wasm_exec_result.return_code +``` -</body> -</html> - -<!-- {% endraw %} --> +The return value of the WebAssembly function, or a negative value if execution +was terminated before the function returned. diff --git a/rules/lib/builtins/wasm_module.mdx b/rules/lib/builtins/wasm_module.mdx index 24c8de3..4bc626f 100644 --- a/rules/lib/builtins/wasm_module.mdx +++ b/rules/lib/builtins/wasm_module.mdx @@ -2,35 +2,20 @@ title: 'wasm_module' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.wasm_module">wasm_module</h1> +# wasm_module {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkWasmModule.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A WebAssembly module loaded by <code>repository_ctx.load_wasm()</code>. - -<h2>Members</h2> -<ul> - <li> - <a href="#path">path</a> - </li> - </ul> +{% include "\_buttons.html" %} +A WebAssembly module loaded by `repository_ctx.load_wasm()`. - <h2 id="path">path</h2> - <p><pre class="rule-signature">unknown wasm_module.path</pre></p> +## Members - The path this WebAssembly module was loaded from. +- [path](#path) +## path -</body> -</html> +``` rule-signature +unknown wasm_module.path +``` -<!-- {% endraw %} --> +The path this WebAssembly module was loaded from. diff --git a/rules/lib/core.mdx b/rules/lib/core.mdx index ecaeaba..1d1c5ce 100644 --- a/rules/lib/core.mdx +++ b/rules/lib/core.mdx @@ -2,43 +2,21 @@ title: 'core' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> -<h1 class="page-title">Core Starlark data types</h1> +# Core Starlark data types {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -This section lists the data types of the <a href='https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions'>Starlark core language</a>. With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. - -<ul> - -<li><a href="/rules/lib/core/bool">bool</a></li> - -<li><a href="/rules/lib/core/builtin_function_or_method">builtin_function_or_method</a></li> - -<li><a href="/rules/lib/core/dict">dict</a></li> - -<li><a href="/rules/lib/core/float">float</a></li> - -<li><a href="/rules/lib/core/function">function</a></li> - -<li><a href="/rules/lib/core/int">int</a></li> - -<li><a href="/rules/lib/core/json">json</a></li> - -<li><a href="/rules/lib/core/list">list</a></li> - -<li><a href="/rules/lib/core/range">range</a></li> - -<li><a href="/rules/lib/core/set">set</a></li> - -<li><a href="/rules/lib/core/string">string</a></li> - -<li><a href="/rules/lib/core/tuple">tuple</a></li> -</ul> -</body> -</html> +{% include "\_buttons.html" %} +This section lists the data types of the [Starlark core language](https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions). With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. + +- [bool](/rules/lib/core/bool) +- [builtin_function_or_method](/rules/lib/core/builtin_function_or_method) +- [dict](/rules/lib/core/dict) +- [float](/rules/lib/core/float) +- [function](/rules/lib/core/function) +- [int](/rules/lib/core/int) +- [json](/rules/lib/core/json) +- [list](/rules/lib/core/list) +- [range](/rules/lib/core/range) +- [set](/rules/lib/core/set) +- [string](/rules/lib/core/string) +- [tuple](/rules/lib/core/tuple) diff --git a/rules/lib/core/bool.mdx b/rules/lib/core/bool.mdx index 00b44be..82c316f 100644 --- a/rules/lib/core/bool.mdx +++ b/rules/lib/core/bool.mdx @@ -2,24 +2,8 @@ title: 'bool' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.bool">bool</h1> +# bool {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/MethodLibrary.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A type to represent booleans. There are only two possible values: True and False. Any value can be converted to a boolean using the <a href="../globals/all.html#bool">bool</a> function. - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +A type to represent booleans. There are only two possible values: True and False. Any value can be converted to a boolean using the [bool](../globals/all.html#bool) function. diff --git a/rules/lib/core/builtin_function_or_method.mdx b/rules/lib/core/builtin_function_or_method.mdx index 66dc664..bbb0cc6 100644 --- a/rules/lib/core/builtin_function_or_method.mdx +++ b/rules/lib/core/builtin_function_or_method.mdx @@ -2,24 +2,8 @@ title: 'builtin_function_or_method' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.builtin_function_or_method">builtin_function_or_method</h1> +# builtin_function_or_method {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/BuiltinFunction.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} The type of a built-in function, defined by Java code. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/core/dict.mdx b/rules/lib/core/dict.mdx index 83b5c4e..e77c454 100644 --- a/rules/lib/core/dict.mdx +++ b/rules/lib/core/dict.mdx @@ -2,266 +2,230 @@ title: 'dict' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.dict">dict</h1> +# dict {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/Dict.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -dict is a built-in type representing an associative mapping or <i>dictionary</i>. A dictionary supports indexing using <code>d[k]</code> and key membership testing using <code>k in d</code>; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to <code>d[k]</code> or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key. -<pre>d = {0: "x", 2: "z", 1: "y"} -[k for k in d] # [0, 2, 1] -d.pop(2) -d[0], d[2] = "a", "b" -0 in d, "a" in d # (True, False) -[(k, v) for k, v in d.items()] # [(0, "a"), (1, "y"), (2, "b")] -</pre> -<p>There are four ways to construct a dictionary: -<ol> -<li>A dictionary expression <code>{k: v, ...}</code> yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value. -<li>A dictionary comprehension <code>{k: v for vars in seq}</code> yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value. -<pre class="language-python"> -{k: v for k, v in (("a", 0), ("b", 1), ("a", 2))} # {"a": 2, "b": 1} -{i: 2*i for i in range(3)} # {0: 0, 1: 2, 2: 4} -</pre> -<li>A call to the built-in <a href="../globals/all.html#dict">dict</a> function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted. -<li>The union expression <code>x | y</code> yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key <code>k</code> in common, the right hand side dictionary's value of the key (in other words, <code>y[k]</code>) wins. The <code>|=</code> variant of the union operator modifies a dictionary in-place. Example:<br><pre class=language-python>d = {"foo": "FOO", "bar": "BAR"} | {"foo": "FOO2", "baz": "BAZ"} -# d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"} -d = {"a": 1, "b": 2} -d |= {"b": 3, "c": 4} -# d == {"a": 1, "b": 3, "c": 4}</pre></ol> - -<h2>Members</h2> -<ul> - <li> - <a href="#clear">clear</a> - </li> - <li> - <a href="#get">get</a> - </li> - <li> - <a href="#items">items</a> - </li> - <li> - <a href="#keys">keys</a> - </li> - <li> - <a href="#pop">pop</a> - </li> - <li> - <a href="#popitem">popitem</a> - </li> - <li> - <a href="#setdefault">setdefault</a> - </li> - <li> - <a href="#update">update</a> - </li> - <li> - <a href="#values">values</a> - </li> - </ul> - - <h2 id="clear">clear</h2> - <p><pre class="rule-signature"><code>None</code> dict.clear()</pre></p> - - Remove all items from the dictionary. - - <h2 id="get">get</h2> - <p><pre class="rule-signature">unknown dict.get(key, default=None)</pre></p> - - Returns the value for <code>key</code> if <code>key</code> is in the dictionary, else <code>default</code>. If <code>default</code> is not given, it defaults to <code>None</code>, so that this method never throws an error. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="get.key"> - <code>key</code> - </td> - <td> - required<br/> - The key to look for. - </td> - </tr> - <tr> - <td id="get.default"> - <code>default</code> - </td> - <td> - default is <code>None</code><br/> - The default value to use (instead of None) if the key is not found. - </td> - </tr> - </tbody> - </table> - - <h2 id="items">items</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.items()</pre></p> - - Returns the list of key-value tuples:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")]</pre> - - - <h2 id="keys">keys</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.keys()</pre></p> - - Returns the list of keys:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1]</pre> - - - <h2 id="pop">pop</h2> - <p><pre class="rule-signature">unknown dict.pop(key, default=unbound)</pre></p> - - Removes a <code>key</code> from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified <code>default</code> value; if no default value was specified, fail instead. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="pop.key"> - <code>key</code> - </td> - <td> - required<br/> - The key. - </td> - </tr> - <tr> - <td id="pop.default"> - <code>default</code> - </td> - <td> - default is <code>unbound</code><br/> - a default value if the key is absent. - </td> - </tr> - </tbody> - </table> - - <h2 id="popitem">popitem</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> dict.popitem()</pre></p> - - Remove and return the first <code>(key, value)</code> pair from the dictionary. <code>popitem</code> is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the <code>popitem</code> call fails. - - <h2 id="setdefault">setdefault</h2> - <p><pre class="rule-signature">unknown dict.setdefault(key, default=None)</pre></p> - - If <code>key</code> is in the dictionary, return its value. If not, insert key with a value of <code>default</code> and return <code>default</code>. <code>default</code> defaults to <code>None</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="setdefault.key"> - <code>key</code> - </td> - <td> - required<br/> - The key. - </td> - </tr> - <tr> - <td id="setdefault.default"> - <code>default</code> - </td> - <td> - default is <code>None</code><br/> - a default value if the key is absent. - </td> - </tr> - </tbody> - </table> - - <h2 id="update">update</h2> - <p><pre class="rule-signature"><code>None</code> dict.update(pairs=[], **kwargs)</pre></p> - - Updates the dictionary first with the optional positional argument, <code>pairs</code>, then with the optional keyword arguments +{% include "\_buttons.html" %} +dict is a built-in type representing an associative mapping or *dictionary*. A dictionary supports indexing using `d[k]` and key membership testing using `k in d`; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to `d[k]` or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key. + + d = {0: "x", 2: "z", 1: "y"} + [k for k in d] # [0, 2, 1] + d.pop(2) + d[0], d[2] = "a", "b" + 0 in d, "a" in d # (True, False) + [(k, v) for k, v in d.items()] # [(0, "a"), (1, "y"), (2, "b")] + +There are four ways to construct a dictionary: + +1. A dictionary expression `{k: v, ...}` yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value. + +2. A dictionary comprehension `{k: v for vars in seq}` yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value. + + ``` python + + {k: v for k, v in (("a", 0), ("b", 1), ("a", 2))} # {"a": 2, "b": 1} + {i: 2*i for i in range(3)} # {0: 0, 1: 2, 2: 4} + ``` + +3. A call to the built-in [dict](../globals/all.html#dict) function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted. + +4. The union expression `x | y` yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key `k` in common, the right hand side dictionary's value of the key (in other words, `y[k]`) wins. The `|=` variant of the union operator modifies a dictionary in-place. Example: + + ``` python + d = {"foo": "FOO", "bar": "BAR"} | {"foo": "FOO2", "baz": "BAZ"} + # d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"} + d = {"a": 1, "b": 2} + d |= {"b": 3, "c": 4} + # d == {"a": 1, "b": 3, "c": 4} + ``` + +## Members + +- [clear](#clear) +- [get](#get) +- [items](#items) +- [keys](#keys) +- [pop](#pop) +- [popitem](#popitem) +- [setdefault](#setdefault) +- [update](#update) +- [values](#values) + +## clear + +``` rule-signature +None dict.clear() +``` + +Remove all items from the dictionary. + +## get + +``` rule-signature +unknown dict.get(key, default=None) +``` + +Returns the value for `key` if `key` is in the dictionary, else `default`. If `default` is not given, it defaults to `None`, so that this method never throws an error. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="get.key"><code>key</code></td> +<td>required<br /> +The key to look for.</td> +</tr> +<tr> +<td id="get.default"><code>default</code></td> +<td>default is <code>None</code><br /> +The default value to use (instead of None) if the key is not found.</td> +</tr> +</tbody> +</table> + +## items + +``` rule-signature +list dict.items() +``` + +Returns the list of key-value tuples: + +``` python +{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")] +``` + +## keys + +``` rule-signature +list dict.keys() +``` + +Returns the list of keys: + +``` python +{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1] +``` + +## pop + +``` rule-signature +unknown dict.pop(key, default=unbound) +``` + +Removes a `key` from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified `default` value; if no default value was specified, fail instead. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="pop.key"><code>key</code></td> +<td>required<br /> +The key.</td> +</tr> +<tr> +<td id="pop.default"><code>default</code></td> +<td>default is <code>unbound</code><br /> +a default value if the key is absent.</td> +</tr> +</tbody> +</table> + +## popitem + +``` rule-signature +tuple dict.popitem() +``` + +Remove and return the first `(key, value)` pair from the dictionary. `popitem` is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the `popitem` call fails. + +## setdefault + +``` rule-signature +unknown dict.setdefault(key, default=None) +``` + +If `key` is in the dictionary, return its value. If not, insert key with a value of `default` and return `default`. `default` defaults to `None`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="setdefault.key"><code>key</code></td> +<td>required<br /> +The key.</td> +</tr> +<tr> +<td id="setdefault.default"><code>default</code></td> +<td>default is <code>None</code><br /> +a default value if the key is absent.</td> +</tr> +</tbody> +</table> + +## update + +``` rule-signature +None dict.update(pairs=[], **kwargs) +``` + +Updates the dictionary first with the optional positional argument, `pairs`, then with the optional keyword arguments If the positional argument is present, it must be a dict, iterable, or None. If it is a dict, then its key/value pairs are inserted into this dict. If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2), each of which is treated as a key/value pair to be inserted. -Each keyword argument <code>name=value</code> causes the name/value pair to be inserted into this dict. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="update.pairs"> - <code>pairs</code> - </td> - <td> - default is <code>[]</code><br/> - Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value. - </td> - </tr> - <tr> - <td id="update.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - Dictionary of additional entries. - </td> - </tr> - </tbody> - </table> - - <h2 id="values">values</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.values()</pre></p> - - Returns the list of values:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"]</pre> - - - -</body> -</html> - -<!-- {% endraw %} --> +Each keyword argument `name=value` causes the name/value pair to be inserted into this dict. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="update.pairs"><code>pairs</code></td> +<td>default is <code>[]</code><br /> +Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value.</td> +</tr> +<tr> +<td id="update.kwargs"><code>kwargs</code></td> +<td>required<br /> +Dictionary of additional entries.</td> +</tr> +</tbody> +</table> + +## values + +``` rule-signature +list dict.values() +``` + +Returns the list of values: + +``` python +{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"] +``` diff --git a/rules/lib/core/float.mdx b/rules/lib/core/float.mdx index 156305f..988c842 100644 --- a/rules/lib/core/float.mdx +++ b/rules/lib/core/float.mdx @@ -2,24 +2,8 @@ title: 'float' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.float">float</h1> +# float {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkFloat.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} The type of floating-point numbers in Starlark. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/core/function.mdx b/rules/lib/core/function.mdx index b35e701..1bc566e 100644 --- a/rules/lib/core/function.mdx +++ b/rules/lib/core/function.mdx @@ -2,24 +2,8 @@ title: 'function' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.function">function</h1> +# function {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkFunction.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} The type of functions declared in Starlark. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/core/int.mdx b/rules/lib/core/int.mdx index 5a0792e..59e9b50 100644 --- a/rules/lib/core/int.mdx +++ b/rules/lib/core/int.mdx @@ -2,31 +2,18 @@ title: 'int' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.int">int</h1> +# int {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkInt.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +The type of integers in Starlark. Starlark integers may be of any magnitude; arithmetic is exact. Examples of integer expressions: -The type of integers in Starlark. Starlark integers may be of any magnitude; arithmetic is exact. Examples of integer expressions:<br><pre class="language-python">153 +``` python +153 0x2A # hexadecimal literal 0o54 # octal literal 23 * 2 + 5 100 / -7 100 % -7 # -5 (unlike in some other languages) int("18") -</pre> - - - -</body> -</html> - -<!-- {% endraw %} --> +``` diff --git a/rules/lib/core/json.mdx b/rules/lib/core/json.mdx index 720a305..1fdcc7c 100644 --- a/rules/lib/core/json.mdx +++ b/rules/lib/core/json.mdx @@ -2,240 +2,175 @@ title: 'json' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.json">json</h1> +# json {% dynamic setvar source_file "src/main/java/net/starlark/java/lib/json/Json.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Module json is a Starlark module of JSON-related functions. -<h2>Members</h2> -<ul> - <li> - <a href="#decode">decode</a> - </li> - <li> - <a href="#encode">encode</a> - </li> - <li> - <a href="#encode_indent">encode_indent</a> - </li> - <li> - <a href="#indent">indent</a> - </li> - </ul> - - <h2 id="decode">decode</h2> - <p><pre class="rule-signature">unknown json.decode(x, default=unbound)</pre></p> - - The decode function has one required positional parameter: a JSON string. +## Members + +- [decode](#decode) +- [encode](#encode) +- [encode_indent](#encode_indent) +- [indent](#indent) + +## decode + +``` rule-signature +unknown json.decode(x, default=unbound) +``` + +The decode function has one required positional parameter: a JSON string. It returns the Starlark value that the string denotes. -<ul><li><code>"null"</code>, <code>"true"</code> and <code>"false"</code> are parsed as <code>None</code>, <code>True</code>, and <code>False</code>. -<li>Numbers are parsed as int, or as a float if they contain a decimal point or an exponent. Although JSON has no syntax for non-finite values, very large values may be decoded as infinity. -<li>a JSON object is parsed as a new unfrozen Starlark dict. If the same key string occurs more than once in the object, the last value for the key is kept. -<li>a JSON array is parsed as new unfrozen Starlark list. -</ul> -If <code>x</code> is not a valid JSON encoding and the optional <code>default</code> parameter is specified (including specified as <code>None</code>), this function returns the <code>default</code> value. -If <code>x</code> is not a valid JSON encoding and the optional <code>default</code> parameter is <em>not</em> specified, this function fails. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="decode.x"> - <code>x</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - JSON string to decode. - </td> - </tr> - <tr> - <td id="decode.default"> - <code>default</code> - </td> - <td> - default is <code>unbound</code><br/> - If specified, the value to return when <code>x</code> cannot be decoded. - </td> - </tr> - </tbody> - </table> - - <h2 id="encode">encode</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> json.encode(x)</pre></p> - - <p>The encode function accepts one required positional argument, which it converts to JSON by cases: -<ul> -<li>None, True, and False are converted to 'null', 'true', and 'false', respectively. -<li>An int, no matter how large, is encoded as a decimal integer. Some decoders may not be able to decode very large integers. -<li>A float is encoded using a decimal point or an exponent or both, even if its numeric value is an integer. It is an error to encode a non-finite floating-point value. -<li>A string value is encoded as a JSON string literal that denotes the value. Each unpaired surrogate is replaced by U+FFFD. -<li>A dict is encoded as a JSON object, in lexicographical key order. It is an error if any key is not a string. -<li>A list or tuple is encoded as a JSON array. -<li>A struct-like value is encoded as a JSON object, in field name order. -</ul> + +- `"null"`, `"true"` and `"false"` are parsed as `None`, `True`, and `False`. +- Numbers are parsed as int, or as a float if they contain a decimal point or an exponent. Although JSON has no syntax for non-finite values, very large values may be decoded as infinity. +- a JSON object is parsed as a new unfrozen Starlark dict. If the same key string occurs more than once in the object, the last value for the key is kept. +- a JSON array is parsed as new unfrozen Starlark list. + +If `x` is not a valid JSON encoding and the optional `default` parameter is specified (including specified as `None`), this function returns the `default` value. +If `x` is not a valid JSON encoding and the optional `default` parameter is *not* specified, this function fails. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="decode.x"><code>x</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +JSON string to decode.</td> +</tr> +<tr> +<td id="decode.default"><code>default</code></td> +<td>default is <code>unbound</code><br /> +If specified, the value to return when <code>x</code> cannot be decoded.</td> +</tr> +</tbody> +</table> + +## encode + +``` rule-signature +string json.encode(x) +``` + +The encode function accepts one required positional argument, which it converts to JSON by cases: + +- None, True, and False are converted to 'null', 'true', and 'false', respectively. +- An int, no matter how large, is encoded as a decimal integer. Some decoders may not be able to decode very large integers. +- A float is encoded using a decimal point or an exponent or both, even if its numeric value is an integer. It is an error to encode a non-finite floating-point value. +- A string value is encoded as a JSON string literal that denotes the value. Each unpaired surrogate is replaced by U+FFFD. +- A dict is encoded as a JSON object, in lexicographical key order. It is an error if any key is not a string. +- A list or tuple is encoded as a JSON array. +- A struct-like value is encoded as a JSON object, in field name order. + An application-defined type may define its own JSON encoding. Encoding any other value yields an error. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="encode.x"> - <code>x</code> - </td> - <td> - required<br/> - - </td> - </tr> - </tbody> - </table> - - <h2 id="encode_indent">encode_indent</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> json.encode_indent(x, *, prefix='', indent='\t')</pre></p> - - The encode_indent function is equivalent to <code>json.indent(json.encode(x), ...)</code>. See <code>indent</code> for description of formatting parameters. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="encode_indent.x"> - <code>x</code> - </td> - <td> - required<br/> - - </td> - </tr> - <tr> - <td id="encode_indent.prefix"> - <code>prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - - </td> - </tr> - <tr> - <td id="encode_indent.indent"> - <code>indent</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'\t'</code><br/> - - </td> - </tr> - </tbody> - </table> - - <h2 id="indent">indent</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> json.indent(s, *, prefix='', indent='\t')</pre></p> - - The indent function returns the indented form of a valid JSON-encoded string. +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="encode.x"><code>x</code></td> +<td>required<br /> +</td> +</tr> +</tbody> +</table> + +## encode_indent + +``` rule-signature +string json.encode_indent(x, *, prefix='', indent='\t') +``` + +The encode_indent function is equivalent to `json.indent(json.encode(x), ...)`. See `indent` for description of formatting parameters. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="encode_indent.x"><code>x</code></td> +<td>required<br /> +</td> +</tr> +<tr> +<td id="encode_indent.prefix"><code>prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +</td> +</tr> +<tr> +<td id="encode_indent.indent"><code>indent</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'\t'</code><br /> +</td> +</tr> +</tbody> +</table> + +## indent + +``` rule-signature +string json.indent(s, *, prefix='', indent='\t') +``` + +The indent function returns the indented form of a valid JSON-encoded string. Each array element or object field appears on a new line, beginning with the prefix string followed by one or more copies of the indent string, according to its nesting depth. The function accepts one required positional parameter, the JSON string, and two optional keyword-only string parameters, prefix and indent, that specify a prefix of each new line, and the unit of indentation. If the input is not valid, the function may fail or return invalid output. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="indent.s"> - <code>s</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - - </td> - </tr> - <tr> - <td id="indent.prefix"> - <code>prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - - </td> - </tr> - <tr> - <td id="indent.indent"> - <code>indent</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'\t'</code><br/> - - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="indent.s"><code>s</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +</td> +</tr> +<tr> +<td id="indent.prefix"><code>prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +</td> +</tr> +<tr> +<td id="indent.indent"><code>indent</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'\t'</code><br /> +</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/core/list.mdx b/rules/lib/core/list.mdx index 6e27002..593144f 100644 --- a/rules/lib/core/list.mdx +++ b/rules/lib/core/list.mdx @@ -2,275 +2,230 @@ title: 'list' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.list">list</h1> +# list {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkList.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +The built-in list type. Example list expressions: + +``` python +x = [1, 2, 3] +``` + +Accessing elements is possible using indexing (starts from `0`): + +``` python +e = x[1] # e == 2 +``` -The built-in list type. Example list expressions:<br><pre class=language-python>x = [1, 2, 3]</pre>Accessing elements is possible using indexing (starts from <code>0</code>):<br><pre class=language-python>e = x[1] # e == 2</pre>Lists support the <code>+</code> operator to concatenate two lists. Example:<br><pre class=language-python>x = [1, 2] + [3, 4] # x == [1, 2, 3, 4] +Lists support the `+` operator to concatenate two lists. Example: + +``` python +x = [1, 2] + [3, 4] # x == [1, 2, 3, 4] x = ["a", "b"] -x += ["c"] # x == ["a", "b", "c"]</pre>Similar to strings, lists support slice operations:<pre class=language-python>['a', 'b', 'c', 'd'][1:3] # ['b', 'c'] +x += ["c"] # x == ["a", "b", "c"] +``` + +Similar to strings, lists support slice operations: + +``` python +['a', 'b', 'c', 'd'][1:3] # ['b', 'c'] ['a', 'b', 'c', 'd'][::2] # ['a', 'c'] -['a', 'b', 'c', 'd'][3:0:-1] # ['d', 'c', 'b']</pre>Lists are mutable, as in Python. - -<h2>Members</h2> -<ul> - <li> - <a href="#append">append</a> - </li> - <li> - <a href="#clear">clear</a> - </li> - <li> - <a href="#extend">extend</a> - </li> - <li> - <a href="#index">index</a> - </li> - <li> - <a href="#insert">insert</a> - </li> - <li> - <a href="#pop">pop</a> - </li> - <li> - <a href="#remove">remove</a> - </li> - </ul> - - <h2 id="append">append</h2> - <p><pre class="rule-signature"><code>None</code> list.append(item)</pre></p> - - Adds an item to the end of the list. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="append.item"> - <code>item</code> - </td> - <td> - required<br/> - Item to add at the end. - </td> - </tr> - </tbody> - </table> - - <h2 id="clear">clear</h2> - <p><pre class="rule-signature"><code>None</code> list.clear()</pre></p> - - Removes all the elements of the list. - - <h2 id="extend">extend</h2> - <p><pre class="rule-signature"><code>None</code> list.extend(items)</pre></p> - - Adds all items to the end of the list. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="extend.items"> - <code>items</code> - </td> - <td> - iterable; - required<br/> - Items to add at the end. - </td> - </tr> - </tbody> - </table> - - <h2 id="index">index</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> list.index(x, start=unbound, end=unbound)</pre></p> - - Returns the index in the list of the first item whose value is x. It is an error if there is no such item. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="index.x"> - <code>x</code> - </td> - <td> - required<br/> - The object to search. - </td> - </tr> - <tr> - <td id="index.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>unbound</code><br/> - The start index of the list portion to inspect. - </td> - </tr> - <tr> - <td id="index.end"> - <code>end</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>unbound</code><br/> - The end index of the list portion to inspect. - </td> - </tr> - </tbody> - </table> - - <h2 id="insert">insert</h2> - <p><pre class="rule-signature"><code>None</code> list.insert(index, item)</pre></p> - - Inserts an item at a given position. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="insert.index"> - <code>index</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - required<br/> - The index of the given position. - </td> - </tr> - <tr> - <td id="insert.item"> - <code>item</code> - </td> - <td> - required<br/> - The item. - </td> - </tr> - </tbody> - </table> - - <h2 id="pop">pop</h2> - <p><pre class="rule-signature">unknown list.pop(i=-1)</pre></p> - - Removes the item at the given position in the list, and returns it. If no <code>index</code> is specified, it removes and returns the last item in the list. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="pop.i"> - <code>i</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>-1</code><br/> - The index of the item. - </td> - </tr> - </tbody> - </table> - - <h2 id="remove">remove</h2> - <p><pre class="rule-signature"><code>None</code> list.remove(x)</pre></p> - - Removes the first item from the list whose value is x. It is an error if there is no such item. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="remove.x"> - <code>x</code> - </td> - <td> - required<br/> - The object to remove. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +['a', 'b', 'c', 'd'][3:0:-1] # ['d', 'c', 'b'] +``` + +Lists are mutable, as in Python. + +## Members + +- [append](#append) +- [clear](#clear) +- [extend](#extend) +- [index](#index) +- [insert](#insert) +- [pop](#pop) +- [remove](#remove) + +## append + +``` rule-signature +None list.append(item) +``` + +Adds an item to the end of the list. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="append.item"><code>item</code></td> +<td>required<br /> +Item to add at the end.</td> +</tr> +</tbody> +</table> + +## clear + +``` rule-signature +None list.clear() +``` + +Removes all the elements of the list. + +## extend + +``` rule-signature +None list.extend(items) +``` + +Adds all items to the end of the list. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="extend.items"><code>items</code></td> +<td>iterable; +required<br /> +Items to add at the end.</td> +</tr> +</tbody> +</table> + +## index + +``` rule-signature +int list.index(x, start=unbound, end=unbound) +``` + +Returns the index in the list of the first item whose value is x. It is an error if there is no such item. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="index.x"><code>x</code></td> +<td>required<br /> +The object to search.</td> +</tr> +<tr> +<td id="index.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>unbound</code><br /> +The start index of the list portion to inspect.</td> +</tr> +<tr> +<td id="index.end"><code>end</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>unbound</code><br /> +The end index of the list portion to inspect.</td> +</tr> +</tbody> +</table> + +## insert + +``` rule-signature +None list.insert(index, item) +``` + +Inserts an item at a given position. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="insert.index"><code>index</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +required<br /> +The index of the given position.</td> +</tr> +<tr> +<td id="insert.item"><code>item</code></td> +<td>required<br /> +The item.</td> +</tr> +</tbody> +</table> + +## pop + +``` rule-signature +unknown list.pop(i=-1) +``` + +Removes the item at the given position in the list, and returns it. If no `index` is specified, it removes and returns the last item in the list. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="pop.i"><code>i</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>-1</code><br /> +The index of the item.</td> +</tr> +</tbody> +</table> + +## remove + +``` rule-signature +None list.remove(x) +``` + +Removes the first item from the list whose value is x. It is an error if there is no such item. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="remove.x"><code>x</code></td> +<td>required<br /> +The object to remove.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/core/range.mdx b/rules/lib/core/range.mdx index ca91cf4..277a4f8 100644 --- a/rules/lib/core/range.mdx +++ b/rules/lib/core/range.mdx @@ -2,26 +2,28 @@ title: 'range' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.range">range</h1> +# range {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/RangeList.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +A language built-in type to support ranges. Example of range literal: -A language built-in type to support ranges. Example of range literal:<br><pre class=language-python>x = range(1, 10, 3)</pre>Accessing elements is possible using indexing (starts from <code>0</code>):<br><pre class=language-python>e = x[1] # e == 2</pre>Ranges do not support the <code>+</code> operator for concatenation.Similar to strings, ranges support slice operations:<pre class=language-python>range(10)[1:3] # range(1, 3) -range(10)[::2] # range(0, 10, 2) -range(10)[3:0:-1] # range(3, 0, -1)</pre>Ranges are immutable, as in Python 3. +``` python +x = range(1, 10, 3) +``` +Accessing elements is possible using indexing (starts from `0`): +``` python +e = x[1] # e == 2 +``` -</body> -</html> +Ranges do not support the `+` operator for concatenation.Similar to strings, ranges support slice operations: + +``` python +range(10)[1:3] # range(1, 3) +range(10)[::2] # range(0, 10, 2) +range(10)[3:0:-1] # range(3, 0, -1) +``` -<!-- {% endraw %} --> +Ranges are immutable, as in Python 3. diff --git a/rules/lib/core/set.mdx b/rules/lib/core/set.mdx index 910b749..90b416d 100644 --- a/rules/lib/core/set.mdx +++ b/rules/lib/core/set.mdx @@ -2,808 +2,715 @@ title: 'set' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.set">set</h1> +# set {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkSet.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -The built-in set type. A set is a mutable collection of unique values – the set's -<em>elements</em>. The <a href="../globals/all#type">type name</a> of a set is <code>"set"</code>. +{% include "\_buttons.html" %} +The built-in set type. A set is a mutable collection of unique values – the set's +*elements*. The [type name](../globals/all#type) of a set is `"set"`. -<p>Sets provide constant-time operations to insert, remove, or check for the presence of a value. +Sets provide constant-time operations to insert, remove, or check for the presence of a value. Sets are implemented using a hash table, and therefore, just like keys of a -<a href="../dict">dictionary</a>, elements of a set must be hashable. A value may be used as an +[dictionary](../dict), elements of a set must be hashable. A value may be used as an element of a set if and only if it may be used as a key of a dictionary. -<p>Sets may be constructed using the <a href="../globals/all#set"><code>set()</code></a> built-in +Sets may be constructed using the [`set()`](../globals/all#set) built-in function, which returns a new set containing the unique elements of its optional argument, which -must be an iterable. Calling <code>set()</code> without an argument constructs an empty set. Sets +must be an iterable. Calling `set()` without an argument constructs an empty set. Sets have no literal syntax. -<p>The <code>in</code> and <code>not in</code> operations check whether a value is (or is not) in a +The `in` and `not in` operations check whether a value is (or is not) in a set: -<pre class=language-python> +``` python + s = set(["a", "b", "c"]) "a" in s # True "z" in s # False -</pre> +``` -<p>A set is iterable, and thus may be used as the operand of a <code>for</code> loop, a list +A set is iterable, and thus may be used as the operand of a `for` loop, a list comprehension, and the various built-in functions that operate on iterables. Its length can be -retrieved using the <a href="../globals/all#len"><code>len()</code></a> built-in function, and the +retrieved using the [`len()`](../globals/all#len) built-in function, and the order of iteration is the order in which elements were first added to the set: -<pre class=language-python> +``` python + s = set(["z", "y", "z", "y"]) len(s) # prints 2 s.add("x") len(s) # prints 3 for e in s: print e # prints "z", "y", "x" -</pre> +``` + +A set used in Boolean context is true if and only if it is non-empty. -<p>A set used in Boolean context is true if and only if it is non-empty. +``` python -<pre class=language-python> s = set() "non-empty" if s else "empty" # "empty" t = set(["x", "y"]) "non-empty" if t else "empty" # "non-empty" -</pre> +``` -<p>Sets may be compared for equality or inequality using <code>==</code> and <code>!=</code>. A set -<code>s</code> is equal to <code>t</code> if and only if <code>t</code> is a set containing the same -elements; iteration order is not significant. In particular, a set is <em>not</em> equal to the list +Sets may be compared for equality or inequality using `==` and `!=`. A set +`s` is equal to `t` if and only if `t` is a set containing the same +elements; iteration order is not significant. In particular, a set is *not* equal to the list of its elements. Sets are not ordered with respect to other sets, and an attempt to compare two sets -using <code><</code>, <code><=</code>, <code>></code>, <code>>=</code>, or to sort a +using `<`, `<=`, `>`, `>=`, or to sort a sequence of sets, will fail. -<pre class=language-python> +``` python + set() == set() # True set() != [] # True set([1, 2]) == set([2, 1]) # True set([1, 2]) != [1, 2] # True -</pre> +``` -<p>The <code>|</code> operation on two sets returns the union of the two sets: a set containing the +The `|` operation on two sets returns the union of the two sets: a set containing the elements found in either one or both of the original sets. -<pre class=language-python> +``` python + set([1, 2]) | set([3, 2]) # set([1, 2, 3]) -</pre> +``` -<p>The <code>&</code> operation on two sets returns the intersection of the two sets: a set +The `&` operation on two sets returns the intersection of the two sets: a set containing only the elements found in both of the original sets. -<pre class=language-python> -set([1, 2]) & set([2, 3]) # set([2]) -set([1, 2]) & set([3, 4]) # set() -</pre> +``` python + +set([1, 2]) & set([2, 3]) # set([2]) +set([1, 2]) & set([3, 4]) # set() +``` -<p>The <code>-</code> operation on two sets returns the difference of the two sets: a set containing +The `-` operation on two sets returns the difference of the two sets: a set containing the elements found in the left-hand side set but not the right-hand side set. -<pre class=language-python> +``` python + set([1, 2]) - set([2, 3]) # set([1]) set([1, 2]) - set([3, 4]) # set([1, 2]) -</pre> +``` -<p>The <code>^</code> operation on two sets returns the symmetric difference of the two sets: a set +The `^` operation on two sets returns the symmetric difference of the two sets: a set containing the elements found in exactly one of the two original sets, but not in both. -<pre class=language-python> +``` python + set([1, 2]) ^ set([2, 3]) # set([1, 3]) set([1, 2]) ^ set([3, 4]) # set([1, 2, 3, 4]) -</pre> +``` -<p>In each of the above operations, the elements of the resulting set retain their order from the +In each of the above operations, the elements of the resulting set retain their order from the two operand sets, with all elements that were drawn from the left-hand side ordered before any element that was only present in the right-hand side. -<p>The corresponding augmented assignments, <code>|=</code>, <code>&=</code>, <code>-=</code>, -and <code>^=</code>, modify the left-hand set in place. +The corresponding augmented assignments, `|=`, `&=`, `-=`, +and `^=`, modify the left-hand set in place. + +``` python -<pre class=language-python> s = set([1, 2]) s |= set([2, 3, 4]) # s now equals set([1, 2, 3, 4]) -s &= set([0, 1, 2, 3]) # s now equals set([1, 2, 3]) +s &= set([0, 1, 2, 3]) # s now equals set([1, 2, 3]) s -= set([0, 1]) # s now equals set([2, 3]) s ^= set([3, 4]) # s now equals set([2, 4]) -</pre> +``` -<p>Like all mutable values in Starlark, a set can be frozen, and once frozen, all subsequent +Like all mutable values in Starlark, a set can be frozen, and once frozen, all subsequent operations that attempt to update it will fail. - -<h2>Members</h2> -<ul> - <li> - <a href="#add">add</a> - </li> - <li> - <a href="#clear">clear</a> - </li> - <li> - <a href="#difference">difference</a> - </li> - <li> - <a href="#difference_update">difference_update</a> - </li> - <li> - <a href="#discard">discard</a> - </li> - <li> - <a href="#intersection">intersection</a> - </li> - <li> - <a href="#intersection_update">intersection_update</a> - </li> - <li> - <a href="#isdisjoint">isdisjoint</a> - </li> - <li> - <a href="#issubset">issubset</a> - </li> - <li> - <a href="#issuperset">issuperset</a> - </li> - <li> - <a href="#pop">pop</a> - </li> - <li> - <a href="#remove">remove</a> - </li> - <li> - <a href="#symmetric_difference">symmetric_difference</a> - </li> - <li> - <a href="#symmetric_difference_update">symmetric_difference_update</a> - </li> - <li> - <a href="#union">union</a> - </li> - <li> - <a href="#update">update</a> - </li> - </ul> - - <h2 id="add">add</h2> - <p><pre class="rule-signature"><code>None</code> set.add(element)</pre></p> - - Adds an element to the set. - -<p>It is permissible to <code>add</code> a value already present in the set; this leaves the set +## Members + +- [add](#add) +- [clear](#clear) +- [difference](#difference) +- [difference_update](#difference_update) +- [discard](#discard) +- [intersection](#intersection) +- [intersection_update](#intersection_update) +- [isdisjoint](#isdisjoint) +- [issubset](#issubset) +- [issuperset](#issuperset) +- [pop](#pop) +- [remove](#remove) +- [symmetric_difference](#symmetric_difference) +- [symmetric_difference_update](#symmetric_difference_update) +- [union](#union) +- [update](#update) + +## add + +``` rule-signature +None set.add(element) +``` + +Adds an element to the set. + +It is permissible to `add` a value already present in the set; this leaves the set unchanged. -<p>If you need to add multiple elements to a set, see <a href="#update"><code>update</code></a> or -the <code>|=</code> augmented assignment operation. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="add.element"> - <code>element</code> - </td> - <td> - required<br/> - Element to add. - </td> - </tr> - </tbody> - </table> - - <h2 id="clear">clear</h2> - <p><pre class="rule-signature"><code>None</code> set.clear()</pre></p> - - Removes all the elements of the set. - - <h2 id="difference">difference</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set.difference(*others)</pre></p> - - Returns a new mutable set containing the difference of this set with others. - -<p>If <code>s</code> and <code>t</code> are sets, <code>s.difference(t)</code> is equivalent to -<code>s - t</code>; however, note that the <code>-</code> operation requires both sides to be sets, -while the <code>difference</code> method also accepts sequences and dicts. - -<p>It is permissible to call <code>difference</code> without any arguments; this returns a copy of +If you need to add multiple elements to a set, see [`update`](#update) or +the `|=` augmented assignment operation. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="add.element"><code>element</code></td> +<td>required<br /> +Element to add.</td> +</tr> +</tbody> +</table> + +## clear + +``` rule-signature +None set.clear() +``` + +Removes all the elements of the set. + +## difference + +``` rule-signature +set set.difference(*others) +``` + +Returns a new mutable set containing the difference of this set with others. + +If `s` and `t` are sets, `s.difference(t)` is equivalent to +`s - t`; however, note that the `-` operation requires both sides to be sets, +while the `difference` method also accepts sequences and dicts. + +It is permissible to call `difference` without any arguments; this returns a copy of the set. -<p>For example, -<pre class=language-python> +For example, + +``` python + set([1, 2, 3]).difference([2]) # set([1, 3]) set([1, 2, 3]).difference([0, 1], [3, 4]) # set([2]) -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="difference.others"> - <code>others</code> - </td> - <td> - required<br/> - Collections of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="difference_update">difference_update</h2> - <p><pre class="rule-signature"><code>None</code> set.difference_update(*others)</pre></p> - - Removes any elements found in any others from this set. - -<p>If <code>s</code> and <code>t</code> are sets, <code>s.difference_update(t)</code> is equivalent -to <code>s -= t</code>; however, note that the <code>-=</code> augmented assignment requires both -sides to be sets, while the <code>difference_update</code> method also accepts sequences and dicts. - -<p>It is permissible to call <code>difference_update</code> without any arguments; this leaves the +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="difference.others"><code>others</code></td> +<td>required<br /> +Collections of hashable elements.</td> +</tr> +</tbody> +</table> + +## difference_update + +``` rule-signature +None set.difference_update(*others) +``` + +Removes any elements found in any others from this set. + +If `s` and `t` are sets, `s.difference_update(t)` is equivalent +to `s -= t`; however, note that the `-=` augmented assignment requires both +sides to be sets, while the `difference_update` method also accepts sequences and dicts. + +It is permissible to call `difference_update` without any arguments; this leaves the set unchanged. -<p>For example, -<pre class=language-python> +For example, + +``` python + s = set([1, 2, 3, 4]) s.difference_update([2]) # None; s is set([1, 3, 4]) s.difference_update([0, 1], [4, 5]) # None; s is set([3]) -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="difference_update.others"> - <code>others</code> - </td> - <td> - required<br/> - Collections of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="discard">discard</h2> - <p><pre class="rule-signature"><code>None</code> set.discard(element)</pre></p> - - Removes an element from the set if it is present. - -<p>It is permissible to <code>discard</code> a value not present in the set; this leaves the set +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="difference_update.others"><code>others</code></td> +<td>required<br /> +Collections of hashable elements.</td> +</tr> +</tbody> +</table> + +## discard + +``` rule-signature +None set.discard(element) +``` + +Removes an element from the set if it is present. + +It is permissible to `discard` a value not present in the set; this leaves the set unchanged. If you want to fail on an attempt to remove a non-present element, use -<a href="#remove"><code>remove</code></a> instead. If you need to remove multiple elements from a -set, see <a href="#difference_update"><code>difference_update</code></a> or the <code>-=</code> +[`remove`](#remove) instead. If you need to remove multiple elements from a +set, see [`difference_update`](#difference_update) or the `-=` augmented assignment operation. -<p>For example, -<pre class=language-python> +For example, + +``` python + s = set(["x", "y"]) s.discard("y") # None; s == set(["x"]) s.discard("y") # None; s == set(["x"]) -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="discard.element"> - <code>element</code> - </td> - <td> - required<br/> - Element to discard. Must be hashable. - </td> - </tr> - </tbody> - </table> - - <h2 id="intersection">intersection</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set.intersection(*others)</pre></p> - - Returns a new mutable set containing the intersection of this set with others. - -<p>If <code>s</code> and <code>t</code> are sets, <code>s.intersection(t)</code> is equivalent to -<code>s & t</code>; however, note that the <code>&</code> operation requires both sides to -be sets, while the <code>intersection</code> method also accepts sequences and dicts. - -<p>It is permissible to call <code>intersection</code> without any arguments; this returns a copy of +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="discard.element"><code>element</code></td> +<td>required<br /> +Element to discard. Must be hashable.</td> +</tr> +</tbody> +</table> + +## intersection + +``` rule-signature +set set.intersection(*others) +``` + +Returns a new mutable set containing the intersection of this set with others. + +If `s` and `t` are sets, `s.intersection(t)` is equivalent to +`s & t`; however, note that the `&` operation requires both sides to +be sets, while the `intersection` method also accepts sequences and dicts. + +It is permissible to call `intersection` without any arguments; this returns a copy of the set. -<p>For example, -<pre class=language-python> +For example, + +``` python + set([1, 2]).intersection([2, 3]) # set([2]) set([1, 2, 3]).intersection([0, 1], [1, 2]) # set([1]) -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="intersection.others"> - <code>others</code> - </td> - <td> - required<br/> - Collections of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="intersection_update">intersection_update</h2> - <p><pre class="rule-signature"><code>None</code> set.intersection_update(*others)</pre></p> - - Removes any elements not found in all others from this set. - -<p>If <code>s</code> and <code>t</code> are sets, <code>s.intersection_update(t)</code> is -equivalent to <code>s &= t</code>; however, note that the <code>&=</code> augmented -assignment requires both sides to be sets, while the <code>intersection_update</code> method also +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="intersection.others"><code>others</code></td> +<td>required<br /> +Collections of hashable elements.</td> +</tr> +</tbody> +</table> + +## intersection_update + +``` rule-signature +None set.intersection_update(*others) +``` + +Removes any elements not found in all others from this set. + +If `s` and `t` are sets, `s.intersection_update(t)` is +equivalent to `s &= t`; however, note that the `&=` augmented +assignment requires both sides to be sets, while the `intersection_update` method also accepts sequences and dicts. -<p>It is permissible to call <code>intersection_update</code> without any arguments; this leaves the +It is permissible to call `intersection_update` without any arguments; this leaves the set unchanged. -<p>For example, -<pre class=language-python> +For example, + +``` python + s = set([1, 2, 3, 4]) s.intersection_update([0, 1, 2]) # None; s is set([1, 2]) s.intersection_update([0, 1], [1, 2]) # None; s is set([1]) -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="intersection_update.others"> - <code>others</code> - </td> - <td> - required<br/> - Collections of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="isdisjoint">isdisjoint</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> set.isdisjoint(other)</pre></p> - - Returns true if this set has no elements in common with another. - -<p>For example, -<pre class=language-python> +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="intersection_update.others"><code>others</code></td> +<td>required<br /> +Collections of hashable elements.</td> +</tr> +</tbody> +</table> + +## isdisjoint + +``` rule-signature +bool set.isdisjoint(other) +``` + +Returns true if this set has no elements in common with another. + +For example, + +``` python + set([1, 2]).isdisjoint([3, 4]) # True set().isdisjoint(set()) # True set([1, 2]).isdisjoint([2, 3]) # False -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="isdisjoint.other"> - <code>other</code> - </td> - <td> - required<br/> - A collection of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="issubset">issubset</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> set.issubset(other)</pre></p> - - Returns true of this set is a subset of another. - -<p>Note that a set is always considered to be a subset of itself. - -<p>For example, -<pre class=language-python> +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="isdisjoint.other"><code>other</code></td> +<td>required<br /> +A collection of hashable elements.</td> +</tr> +</tbody> +</table> + +## issubset + +``` rule-signature +bool set.issubset(other) +``` + +Returns true of this set is a subset of another. + +Note that a set is always considered to be a subset of itself. + +For example, + +``` python + set([1, 2]).issubset([1, 2, 3]) # True set([1, 2]).issubset([1, 2]) # True set([1, 2]).issubset([2, 3]) # False -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="issubset.other"> - <code>other</code> - </td> - <td> - required<br/> - A collection of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="issuperset">issuperset</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> set.issuperset(other)</pre></p> - - Returns true of this set is a superset of another. - -<p>Note that a set is always considered to be a superset of itself. - -<p>For example, -<pre class=language-python> +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="issubset.other"><code>other</code></td> +<td>required<br /> +A collection of hashable elements.</td> +</tr> +</tbody> +</table> + +## issuperset + +``` rule-signature +bool set.issuperset(other) +``` + +Returns true of this set is a superset of another. + +Note that a set is always considered to be a superset of itself. + +For example, + +``` python + set([1, 2, 3]).issuperset([1, 2]) # True set([1, 2, 3]).issuperset([1, 2, 3]) # True set([1, 2, 3]).issuperset([2, 3, 4]) # False -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="issuperset.other"> - <code>other</code> - </td> - <td> - required<br/> - A collection of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="pop">pop</h2> - <p><pre class="rule-signature">unknown set.pop()</pre></p> - - Removes and returns the first element of the set (in iteration order, which is the order in which +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="issuperset.other"><code>other</code></td> +<td>required<br /> +A collection of hashable elements.</td> +</tr> +</tbody> +</table> + +## pop + +``` rule-signature +unknown set.pop() +``` + +Removes and returns the first element of the set (in iteration order, which is the order in which elements were first added to the set). -<p>Fails if the set is empty. +Fails if the set is empty. + +For example, + +``` python -<p>For example, -<pre class=language-python> s = set([3, 1, 2]) s.pop() # 3; s == set([1, 2]) s.pop() # 1; s == set([2]) s.pop() # 2; s == set() s.pop() # error: empty set -</pre> +``` +## remove - <h2 id="remove">remove</h2> - <p><pre class="rule-signature"><code>None</code> set.remove(element)</pre></p> +``` rule-signature +None set.remove(element) +``` - Removes an element, which must be present in the set, from the set. +Removes an element, which must be present in the set, from the set. -<p><code>remove</code> fails if the element was not present in the set. If you don't want to fail on -an attempt to remove a non-present element, use <a href="#discard"><code>discard</code></a> instead. +`remove` fails if the element was not present in the set. If you don't want to fail on +an attempt to remove a non-present element, use [`discard`](#discard) instead. If you need to remove multiple elements from a set, see -<a href="#difference_update"><code>difference_update</code></a> or the <code>-=</code> augmented +[`difference_update`](#difference_update) or the `-=` augmented assignment operation. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="remove.element"> - <code>element</code> - </td> - <td> - required<br/> - Element to remove. Must be an element of the set (and hashable). - </td> - </tr> - </tbody> - </table> - - <h2 id="symmetric_difference">symmetric_difference</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set.symmetric_difference(other)</pre></p> - - Returns a new mutable set containing the symmetric difference of this set with another collection of +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="remove.element"><code>element</code></td> +<td>required<br /> +Element to remove. Must be an element of the set (and hashable).</td> +</tr> +</tbody> +</table> + +## symmetric_difference + +``` rule-signature +set set.symmetric_difference(other) +``` + +Returns a new mutable set containing the symmetric difference of this set with another collection of hashable elements. -<p>If <code>s</code> and <code>t</code> are sets, <code>s.symmetric_difference(t)</code> is -equivalent to <code>s ^ t</code>; however, note that the <code>^</code> operation requires both -sides to be sets, while the <code>symmetric_difference</code> method also accepts a sequence or a +If `s` and `t` are sets, `s.symmetric_difference(t)` is +equivalent to `s ^ t`; however, note that the `^` operation requires both +sides to be sets, while the `symmetric_difference` method also accepts a sequence or a dict. -<p>For example, -<pre class=language-python> +For example, + +``` python + set([1, 2]).symmetric_difference([2, 3]) # set([1, 3]) -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="symmetric_difference.other"> - <code>other</code> - </td> - <td> - required<br/> - A collection of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="symmetric_difference_update">symmetric_difference_update</h2> - <p><pre class="rule-signature"><code>None</code> set.symmetric_difference_update(other)</pre></p> - - Returns a new mutable set containing the symmetric difference of this set with another collection of +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="symmetric_difference.other"><code>other</code></td> +<td>required<br /> +A collection of hashable elements.</td> +</tr> +</tbody> +</table> + +## symmetric_difference_update + +``` rule-signature +None set.symmetric_difference_update(other) +``` + +Returns a new mutable set containing the symmetric difference of this set with another collection of hashable elements. -<p>If <code>s</code> and <code>t</code> are sets, <code>s.symmetric_difference_update(t)</code> is -equivalent to `s ^= t<code>; however, note that the </code>^=` augmented assignment requires both -sides to be sets, while the <code>symmetric_difference_update</code> method also accepts a sequence +If `s` and `t` are sets, `s.symmetric_difference_update(t)` is +equivalent to \`s ^= t`; however, note that the `^=\` augmented assignment requires both +sides to be sets, while the `symmetric_difference_update` method also accepts a sequence or a dict. -<p>For example, -<pre class=language-python> +For example, + +``` python + s = set([1, 2]) s.symmetric_difference_update([2, 3]) # None; s == set([1, 3]) -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="symmetric_difference_update.other"> - <code>other</code> - </td> - <td> - required<br/> - A collection of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="union">union</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set.union(*others)</pre></p> - - Returns a new mutable set containing the union of this set with others. - -<p>If <code>s</code> and <code>t</code> are sets, <code>s.union(t)</code> is equivalent to -<code>s | t</code>; however, note that the <code>|</code> operation requires both sides to be sets, -while the <code>union</code> method also accepts sequences and dicts. - -<p>It is permissible to call <code>union</code> without any arguments; this returns a copy of the +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="symmetric_difference_update.other"><code>other</code></td> +<td>required<br /> +A collection of hashable elements.</td> +</tr> +</tbody> +</table> + +## union + +``` rule-signature +set set.union(*others) +``` + +Returns a new mutable set containing the union of this set with others. + +If `s` and `t` are sets, `s.union(t)` is equivalent to +`s | t`; however, note that the `|` operation requires both sides to be sets, +while the `union` method also accepts sequences and dicts. + +It is permissible to call `union` without any arguments; this returns a copy of the set. -<p>For example, -<pre class=language-python> +For example, + +``` python + set([1, 2]).union([2, 3]) # set([1, 2, 3]) set([1, 2]).union([2, 3], {3: "a", 4: "b"}) # set([1, 2, 3, 4]) -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="union.others"> - <code>others</code> - </td> - <td> - required<br/> - Collections of hashable elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="update">update</h2> - <p><pre class="rule-signature"><code>None</code> set.update(*others)</pre></p> - - Adds the elements found in others to this set. - -<p>For example, -<pre class=language-python> +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="union.others"><code>others</code></td> +<td>required<br /> +Collections of hashable elements.</td> +</tr> +</tbody> +</table> + +## update + +``` rule-signature +None set.update(*others) +``` + +Adds the elements found in others to this set. + +For example, + +``` python + s = set() s.update([1, 2]) # None; s is set([1, 2]) s.update([2, 3], [3, 4]) # None; s is set([1, 2, 3, 4]) -</pre> +``` -<p>If <code>s</code> and <code>t</code> are sets, <code>s.update(t)</code> is equivalent to -<code>s |= t</code>; however, note that the <code>|=</code> augmented assignment requires both sides -to be sets, while the <code>update</code> method also accepts sequences and dicts. +If `s` and `t` are sets, `s.update(t)` is equivalent to +`s |= t`; however, note that the `|=` augmented assignment requires both sides +to be sets, while the `update` method also accepts sequences and dicts. -<p>It is permissible to call <code>update</code> without any arguments; this leaves the set +It is permissible to call `update` without any arguments; this leaves the set unchanged. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="update.others"> - <code>others</code> - </td> - <td> - required<br/> - Collections of hashable elements. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="update.others"><code>others</code></td> +<td>required<br /> +Collections of hashable elements.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/core/string.mdx b/rules/lib/core/string.mdx index 33d7a3b..c3c298c 100644 --- a/rules/lib/core/string.mdx +++ b/rules/lib/core/string.mdx @@ -2,20 +2,14 @@ title: 'string' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.string">string</h1> +# string {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StringModule.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +A language built-in type to support strings. Examples of string literals: -A language built-in type to support strings. Examples of string literals:<br><pre class="language-python">a = 'abc\ndef' +``` python +a = 'abc\ndef' b = "ab'cd" c = """multiline string""" @@ -26,1006 +20,821 @@ z = "hello"[:4] # "hell" # Slice steps can be used, too: s = "hello"[::2] # "hlo" t = "hello"[3:0:-1] # "lle" -</pre>Strings are not directly iterable, use the <code>.elems()</code> method to iterate over their characters. Examples:<br><pre class="language-python">"bc" in "abcd" # evaluates to True -x = [c for c in "abc".elems()] # x == ["a", "b", "c"]</pre> -Implicit concatenation of strings is not allowed; use the <code>+</code> operator instead. Comparison operators perform a lexicographical comparison; use <code>==</code> to test for equality. - -<h2>Members</h2> -<ul> - <li> - <a href="#capitalize">capitalize</a> - </li> - <li> - <a href="#count">count</a> - </li> - <li> - <a href="#elems">elems</a> - </li> - <li> - <a href="#endswith">endswith</a> - </li> - <li> - <a href="#find">find</a> - </li> - <li> - <a href="#format">format</a> - </li> - <li> - <a href="#index">index</a> - </li> - <li> - <a href="#isalnum">isalnum</a> - </li> - <li> - <a href="#isalpha">isalpha</a> - </li> - <li> - <a href="#isdigit">isdigit</a> - </li> - <li> - <a href="#islower">islower</a> - </li> - <li> - <a href="#isspace">isspace</a> - </li> - <li> - <a href="#istitle">istitle</a> - </li> - <li> - <a href="#isupper">isupper</a> - </li> - <li> - <a href="#join">join</a> - </li> - <li> - <a href="#lower">lower</a> - </li> - <li> - <a href="#lstrip">lstrip</a> - </li> - <li> - <a href="#partition">partition</a> - </li> - <li> - <a href="#removeprefix">removeprefix</a> - </li> - <li> - <a href="#removesuffix">removesuffix</a> - </li> - <li> - <a href="#replace">replace</a> - </li> - <li> - <a href="#rfind">rfind</a> - </li> - <li> - <a href="#rindex">rindex</a> - </li> - <li> - <a href="#rpartition">rpartition</a> - </li> - <li> - <a href="#rsplit">rsplit</a> - </li> - <li> - <a href="#rstrip">rstrip</a> - </li> - <li> - <a href="#split">split</a> - </li> - <li> - <a href="#splitlines">splitlines</a> - </li> - <li> - <a href="#startswith">startswith</a> - </li> - <li> - <a href="#strip">strip</a> - </li> - <li> - <a href="#title">title</a> - </li> - <li> - <a href="#upper">upper</a> - </li> - </ul> - - <h2 id="capitalize">capitalize</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.capitalize()</pre></p> - - Returns a copy of the string with its first character (if any) capitalized and the rest lowercased. This method does not support non-ascii characters. - - <h2 id="count">count</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.count(sub, start=0, end=None)</pre></p> - - Returns the number of (non-overlapping) occurrences of substring <code>sub</code> in string, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="count.sub"> - <code>sub</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The substring to count. - </td> - </tr> - <tr> - <td id="count.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>0</code><br/> - Restrict to search from this position. - </td> - </tr> - <tr> - <td id="count.end"> - <code>end</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>None</code><br/> - optional position before which to restrict to search. - </td> - </tr> - </tbody> - </table> - - <h2 id="elems">elems</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> string.elems()</pre></p> - - Returns an iterable value containing successive 1-element substrings of the string. Equivalent to <code>[s[i] for i in range(len(s))]</code>, except that the returned value might not be a list. - - <h2 id="endswith">endswith</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.endswith(sub, start=0, end=None)</pre></p> - - Returns True if the string ends with <code>sub</code>, otherwise False, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="endswith.sub"> - <code>sub</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/tuple.html">tuple</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The suffix (or tuple of alternative suffixes) to match. - </td> - </tr> - <tr> - <td id="endswith.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>0</code><br/> - Test beginning at this position. - </td> - </tr> - <tr> - <td id="endswith.end"> - <code>end</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>None</code><br/> - optional position at which to stop comparing. - </td> - </tr> - </tbody> - </table> - - <h2 id="find">find</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.find(sub, start=0, end=None)</pre></p> - - Returns the first index where <code>sub</code> is found, or -1 if no such index exists, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="find.sub"> - <code>sub</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The substring to find. - </td> - </tr> - <tr> - <td id="find.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>0</code><br/> - Restrict to search from this position. - </td> - </tr> - <tr> - <td id="find.end"> - <code>end</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>None</code><br/> - optional position before which to restrict to search. - </td> - </tr> - </tbody> - </table> - - <h2 id="format">format</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.format(*args, **kwargs)</pre></p> - - Perform string interpolation. Format strings contain replacement fields surrounded by curly braces <code>{}</code>. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output.If you need to include a brace character in the literal text, it can be escaped by doubling: <code>{{</code> and <code>}}</code>A replacement field can be either a name, a number, or empty. Values are converted to strings using the <a href="../globals/all.html#str">str</a> function.<pre class="language-python"># Access in order: -"{} < {}".format(4, 5) == "4 < 5" +``` + +Strings are not directly iterable, use the `.elems()` method to iterate over their characters. Examples: + +``` python +"bc" in "abcd" # evaluates to True +x = [c for c in "abc".elems()] # x == ["a", "b", "c"] +``` + +Implicit concatenation of strings is not allowed; use the `+` operator instead. Comparison operators perform a lexicographical comparison; use `==` to test for equality. + +## Members + +- [capitalize](#capitalize) +- [count](#count) +- [elems](#elems) +- [endswith](#endswith) +- [find](#find) +- [format](#format) +- [index](#index) +- [isalnum](#isalnum) +- [isalpha](#isalpha) +- [isdigit](#isdigit) +- [islower](#islower) +- [isspace](#isspace) +- [istitle](#istitle) +- [isupper](#isupper) +- [join](#join) +- [lower](#lower) +- [lstrip](#lstrip) +- [partition](#partition) +- [removeprefix](#removeprefix) +- [removesuffix](#removesuffix) +- [replace](#replace) +- [rfind](#rfind) +- [rindex](#rindex) +- [rpartition](#rpartition) +- [rsplit](#rsplit) +- [rstrip](#rstrip) +- [split](#split) +- [splitlines](#splitlines) +- [startswith](#startswith) +- [strip](#strip) +- [title](#title) +- [upper](#upper) + +## capitalize + +``` rule-signature +string string.capitalize() +``` + +Returns a copy of the string with its first character (if any) capitalized and the rest lowercased. This method does not support non-ascii characters. + +## count + +``` rule-signature +int string.count(sub, start=0, end=None) +``` + +Returns the number of (non-overlapping) occurrences of substring `sub` in string, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="count.sub"><code>sub</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The substring to count.</td> +</tr> +<tr> +<td id="count.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>0</code><br /> +Restrict to search from this position.</td> +</tr> +<tr> +<td id="count.end"><code>end</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>None</code><br /> +optional position before which to restrict to search.</td> +</tr> +</tbody> +</table> + +## elems + +``` rule-signature +sequence string.elems() +``` + +Returns an iterable value containing successive 1-element substrings of the string. Equivalent to `[s[i] for i in range(len(s))]`, except that the returned value might not be a list. + +## endswith + +``` rule-signature +bool string.endswith(sub, start=0, end=None) +``` + +Returns True if the string ends with `sub`, otherwise False, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="endswith.sub"><code>sub</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/tuple.html" class="anchor">tuple</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The suffix (or tuple of alternative suffixes) to match.</td> +</tr> +<tr> +<td id="endswith.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>0</code><br /> +Test beginning at this position.</td> +</tr> +<tr> +<td id="endswith.end"><code>end</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>None</code><br /> +optional position at which to stop comparing.</td> +</tr> +</tbody> +</table> + +## find + +``` rule-signature +int string.find(sub, start=0, end=None) +``` + +Returns the first index where `sub` is found, or -1 if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="find.sub"><code>sub</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The substring to find.</td> +</tr> +<tr> +<td id="find.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>0</code><br /> +Restrict to search from this position.</td> +</tr> +<tr> +<td id="find.end"><code>end</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>None</code><br /> +optional position before which to restrict to search.</td> +</tr> +</tbody> +</table> + +## format + +``` rule-signature +string string.format(*args, **kwargs) +``` + +Perform string interpolation. Format strings contain replacement fields surrounded by curly braces `{}`. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output.If you need to include a brace character in the literal text, it can be escaped by doubling: `{{` and `}}`A replacement field can be either a name, a number, or empty. Values are converted to strings using the [str](../globals/all.html#str) function. + +``` python +# Access in order: +"{} < {}".format(4, 5) == "4 < 5" # Access by position: "{1}, {0}".format(2, 1) == "1, 2" # Access by name: -"x{key}x".format(key = 2) == "x2x"</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="format.args"> - <code>args</code> - </td> - <td> - default is <code>()</code><br/> - List of arguments. - </td> - </tr> - <tr> - <td id="format.kwargs"> - <code>kwargs</code> - </td> - <td> - default is <code>{}</code><br/> - Dictionary of arguments. - </td> - </tr> - </tbody> - </table> - - <h2 id="index">index</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.index(sub, start=0, end=None)</pre></p> - - Returns the first index where <code>sub</code> is found, or raises an error if no such index exists, optionally restricting to <code>[start:end]</code><code>start</code> being inclusive and <code>end</code> being exclusive. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="index.sub"> - <code>sub</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The substring to find. - </td> - </tr> - <tr> - <td id="index.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>0</code><br/> - Restrict to search from this position. - </td> - </tr> - <tr> - <td id="index.end"> - <code>end</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>None</code><br/> - optional position before which to restrict to search. - </td> - </tr> - </tbody> - </table> - - <h2 id="isalnum">isalnum</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isalnum()</pre></p> - - Returns True if all characters in the string are alphanumeric ([a-zA-Z0-9]) and there is at least one character. - - <h2 id="isalpha">isalpha</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isalpha()</pre></p> - - Returns True if all characters in the string are alphabetic ([a-zA-Z]) and there is at least one character. - - <h2 id="isdigit">isdigit</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isdigit()</pre></p> - - Returns True if all characters in the string are digits ([0-9]) and there is at least one character. - - <h2 id="islower">islower</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.islower()</pre></p> - - Returns True if all cased characters in the string are lowercase and there is at least one character. - - <h2 id="isspace">isspace</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isspace()</pre></p> - - Returns True if all characters are white space characters and the string contains at least one character. - - <h2 id="istitle">istitle</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.istitle()</pre></p> - - Returns True if the string is in title case and it contains at least one character. This means that every uppercase character must follow an uncased one (e.g. whitespace) and every lowercase character must follow a cased one (e.g. uppercase or lowercase). - - <h2 id="isupper">isupper</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.isupper()</pre></p> - - Returns True if all cased characters in the string are uppercase and there is at least one character. - - <h2 id="join">join</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.join(elements)</pre></p> - - Returns a string in which the string elements of the argument have been joined by this string as a separator. Example:<br><pre class="language-python">"|".join(["a", "b", "c"]) == "a|b|c"</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="join.elements"> - <code>elements</code> - </td> - <td> - iterable of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The objects to join. - </td> - </tr> - </tbody> - </table> - - <h2 id="lower">lower</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.lower()</pre></p> - - Returns the lower case version of this string. - - <h2 id="lstrip">lstrip</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.lstrip(chars=None)</pre></p> - - Returns a copy of the string where leading characters that appear in <code>chars</code> are removed. Note that <code>chars</code> is not a prefix: all combinations of its value are removed:<pre class="language-python">"abcba".lstrip("ba") == "cba"</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="lstrip.chars"> - <code>chars</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The characters to remove, or all whitespace if None. - </td> - </tr> - </tbody> - </table> - - <h2 id="partition">partition</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> string.partition(sep)</pre></p> - - Splits the input string at the first occurrence of the separator <code>sep</code> and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, partition returns (self, '', ''). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="partition.sep"> - <code>sep</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The string to split on. - </td> - </tr> - </tbody> - </table> - - <h2 id="removeprefix">removeprefix</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.removeprefix(prefix)</pre></p> - - If the string starts with <code>prefix</code>, returns a new string with the prefix removed. Otherwise, returns the string. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="removeprefix.prefix"> - <code>prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The prefix to remove if present. - </td> - </tr> - </tbody> - </table> - - <h2 id="removesuffix">removesuffix</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.removesuffix(suffix)</pre></p> - - If the string ends with <code>suffix</code>, returns a new string with the suffix removed. Otherwise, returns the string. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="removesuffix.suffix"> - <code>suffix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The suffix to remove if present. - </td> - </tr> - </tbody> - </table> - - <h2 id="replace">replace</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.replace(old, new, count=-1)</pre></p> - - Returns a copy of the string in which the occurrences of <code>old</code> have been replaced with <code>new</code>, optionally restricting the number of replacements to <code>count</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="replace.old"> - <code>old</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The string to be replaced. - </td> - </tr> - <tr> - <td id="replace.new"> - <code>new</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The string to replace with. - </td> - </tr> - <tr> - <td id="replace.count"> - <code>count</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>-1</code><br/> - The maximum number of replacements. If omitted, or if the value is negative, there is no limit. - </td> - </tr> - </tbody> - </table> - - <h2 id="rfind">rfind</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.rfind(sub, start=0, end=None)</pre></p> - - Returns the last index where <code>sub</code> is found, or -1 if no such index exists, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="rfind.sub"> - <code>sub</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The substring to find. - </td> - </tr> - <tr> - <td id="rfind.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>0</code><br/> - Restrict to search from this position. - </td> - </tr> - <tr> - <td id="rfind.end"> - <code>end</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>None</code><br/> - optional position before which to restrict to search. - </td> - </tr> - </tbody> - </table> - - <h2 id="rindex">rindex</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> string.rindex(sub, start=0, end=None)</pre></p> - - Returns the last index where <code>sub</code> is found, or raises an error if no such index exists, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="rindex.sub"> - <code>sub</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The substring to find. - </td> - </tr> - <tr> - <td id="rindex.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>0</code><br/> - Restrict to search from this position. - </td> - </tr> - <tr> - <td id="rindex.end"> - <code>end</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>None</code><br/> - optional position before which to restrict to search. - </td> - </tr> - </tbody> - </table> - - <h2 id="rpartition">rpartition</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> string.rpartition(sep)</pre></p> - - Splits the input string at the last occurrence of the separator <code>sep</code> and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, rpartition returns ('', '', self). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="rpartition.sep"> - <code>sep</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The string to split on. - </td> - </tr> - </tbody> - </table> - - <h2 id="rsplit">rsplit</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> string.rsplit(sep, maxsplit=unbound)</pre></p> - - Returns a list of all the words in the string, using <code>sep</code> as the separator, optionally limiting the number of splits to <code>maxsplit</code>. Except for splitting from the right, this method behaves like split(). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="rsplit.sep"> - <code>sep</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The string to split on. - </td> - </tr> - <tr> - <td id="rsplit.maxsplit"> - <code>maxsplit</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>unbound</code><br/> - The maximum number of splits. - </td> - </tr> - </tbody> - </table> - - <h2 id="rstrip">rstrip</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.rstrip(chars=None)</pre></p> - - Returns a copy of the string where trailing characters that appear in <code>chars</code> are removed. Note that <code>chars</code> is not a suffix: all combinations of its value are removed:<pre class="language-python">"abcbaa".rstrip("ab") == "abc"</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="rstrip.chars"> - <code>chars</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The characters to remove, or all whitespace if None. - </td> - </tr> - </tbody> - </table> - - <h2 id="split">split</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> string.split(sep, maxsplit=unbound)</pre></p> - - Returns a list of all the words in the string, using <code>sep</code> as the separator, optionally limiting the number of splits to <code>maxsplit</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="split.sep"> - <code>sep</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The string to split on. - </td> - </tr> - <tr> - <td id="split.maxsplit"> - <code>maxsplit</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>unbound</code><br/> - The maximum number of splits. - </td> - </tr> - </tbody> - </table> - - <h2 id="splitlines">splitlines</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> string.splitlines(keepends=False)</pre></p> - - Splits the string at line boundaries ('\n', '\r\n', '\r') and returns the result as a new mutable list. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="splitlines.keepends"> - <code>keepends</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether the line breaks should be included in the resulting list. - </td> - </tr> - </tbody> - </table> - - <h2 id="startswith">startswith</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> string.startswith(sub, start=0, end=None)</pre></p> - - Returns True if the string starts with <code>sub</code>, otherwise False, optionally restricting to <code>[start:end]</code>, <code>start</code> being inclusive and <code>end</code> being exclusive. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="startswith.sub"> - <code>sub</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/tuple.html">tuple</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The prefix (or tuple of alternative prefixes) to match. - </td> - </tr> - <tr> - <td id="startswith.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>0</code><br/> - Test beginning at this position. - </td> - </tr> - <tr> - <td id="startswith.end"> - <code>end</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <code>None</code>; - default is <code>None</code><br/> - Stop comparing at this position. - </td> - </tr> - </tbody> - </table> - - <h2 id="strip">strip</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.strip(chars=None)</pre></p> - - Returns a copy of the string where leading or trailing characters that appear in <code>chars</code> are removed. Note that <code>chars</code> is neither a prefix nor a suffix: all combinations of its value are removed:<pre class="language-python">"aabcbcbaa".strip("ab") == "cbc"</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="strip.chars"> - <code>chars</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The characters to remove, or all whitespace if None. - </td> - </tr> - </tbody> - </table> - - <h2 id="title">title</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.title()</pre></p> - - Converts the input string into title case, i.e. every word starts with an uppercase letter while the remaining letters are lowercase. In this context, a word means strictly a sequence of letters. This method does not support supplementary Unicode characters. - - <h2 id="upper">upper</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> string.upper()</pre></p> - - Returns the upper case version of this string. - - -</body> -</html> - -<!-- {% endraw %} --> +"x{key}x".format(key = 2) == "x2x" +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="format.args"><code>args</code></td> +<td>default is <code>()</code><br /> +List of arguments.</td> +</tr> +<tr> +<td id="format.kwargs"><code>kwargs</code></td> +<td>default is <code>{}</code><br /> +Dictionary of arguments.</td> +</tr> +</tbody> +</table> + +## index + +``` rule-signature +int string.index(sub, start=0, end=None) +``` + +Returns the first index where `sub` is found, or raises an error if no such index exists, optionally restricting to `[start:end]``start` being inclusive and `end` being exclusive. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="index.sub"><code>sub</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The substring to find.</td> +</tr> +<tr> +<td id="index.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>0</code><br /> +Restrict to search from this position.</td> +</tr> +<tr> +<td id="index.end"><code>end</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>None</code><br /> +optional position before which to restrict to search.</td> +</tr> +</tbody> +</table> + +## isalnum + +``` rule-signature +bool string.isalnum() +``` + +Returns True if all characters in the string are alphanumeric (\[a-zA-Z0-9\]) and there is at least one character. + +## isalpha + +``` rule-signature +bool string.isalpha() +``` + +Returns True if all characters in the string are alphabetic (\[a-zA-Z\]) and there is at least one character. + +## isdigit + +``` rule-signature +bool string.isdigit() +``` + +Returns True if all characters in the string are digits (\[0-9\]) and there is at least one character. + +## islower + +``` rule-signature +bool string.islower() +``` + +Returns True if all cased characters in the string are lowercase and there is at least one character. + +## isspace + +``` rule-signature +bool string.isspace() +``` + +Returns True if all characters are white space characters and the string contains at least one character. + +## istitle + +``` rule-signature +bool string.istitle() +``` + +Returns True if the string is in title case and it contains at least one character. This means that every uppercase character must follow an uncased one (e.g. whitespace) and every lowercase character must follow a cased one (e.g. uppercase or lowercase). + +## isupper + +``` rule-signature +bool string.isupper() +``` + +Returns True if all cased characters in the string are uppercase and there is at least one character. + +## join + +``` rule-signature +string string.join(elements) +``` + +Returns a string in which the string elements of the argument have been joined by this string as a separator. Example: + +``` python +"|".join(["a", "b", "c"]) == "a|b|c" +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="join.elements"><code>elements</code></td> +<td>iterable of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The objects to join.</td> +</tr> +</tbody> +</table> + +## lower + +``` rule-signature +string string.lower() +``` + +Returns the lower case version of this string. + +## lstrip + +``` rule-signature +string string.lstrip(chars=None) +``` + +Returns a copy of the string where leading characters that appear in `chars` are removed. Note that `chars` is not a prefix: all combinations of its value are removed: + +``` python +"abcba".lstrip("ba") == "cba" +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="lstrip.chars"><code>chars</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The characters to remove, or all whitespace if None.</td> +</tr> +</tbody> +</table> + +## partition + +``` rule-signature +tuple string.partition(sep) +``` + +Splits the input string at the first occurrence of the separator `sep` and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, partition returns (self, '', ''). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="partition.sep"><code>sep</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The string to split on.</td> +</tr> +</tbody> +</table> + +## removeprefix + +``` rule-signature +string string.removeprefix(prefix) +``` + +If the string starts with `prefix`, returns a new string with the prefix removed. Otherwise, returns the string. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="removeprefix.prefix"><code>prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The prefix to remove if present.</td> +</tr> +</tbody> +</table> + +## removesuffix + +``` rule-signature +string string.removesuffix(suffix) +``` + +If the string ends with `suffix`, returns a new string with the suffix removed. Otherwise, returns the string. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="removesuffix.suffix"><code>suffix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The suffix to remove if present.</td> +</tr> +</tbody> +</table> + +## replace + +``` rule-signature +string string.replace(old, new, count=-1) +``` + +Returns a copy of the string in which the occurrences of `old` have been replaced with `new`, optionally restricting the number of replacements to `count`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="replace.old"><code>old</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The string to be replaced.</td> +</tr> +<tr> +<td id="replace.new"><code>new</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The string to replace with.</td> +</tr> +<tr> +<td id="replace.count"><code>count</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>-1</code><br /> +The maximum number of replacements. If omitted, or if the value is negative, there is no limit.</td> +</tr> +</tbody> +</table> + +## rfind + +``` rule-signature +int string.rfind(sub, start=0, end=None) +``` + +Returns the last index where `sub` is found, or -1 if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="rfind.sub"><code>sub</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The substring to find.</td> +</tr> +<tr> +<td id="rfind.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>0</code><br /> +Restrict to search from this position.</td> +</tr> +<tr> +<td id="rfind.end"><code>end</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>None</code><br /> +optional position before which to restrict to search.</td> +</tr> +</tbody> +</table> + +## rindex + +``` rule-signature +int string.rindex(sub, start=0, end=None) +``` + +Returns the last index where `sub` is found, or raises an error if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="rindex.sub"><code>sub</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The substring to find.</td> +</tr> +<tr> +<td id="rindex.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>0</code><br /> +Restrict to search from this position.</td> +</tr> +<tr> +<td id="rindex.end"><code>end</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>None</code><br /> +optional position before which to restrict to search.</td> +</tr> +</tbody> +</table> + +## rpartition + +``` rule-signature +tuple string.rpartition(sep) +``` + +Splits the input string at the last occurrence of the separator `sep` and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, rpartition returns ('', '', self). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="rpartition.sep"><code>sep</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The string to split on.</td> +</tr> +</tbody> +</table> + +## rsplit + +``` rule-signature +list string.rsplit(sep, maxsplit=unbound) +``` + +Returns a list of all the words in the string, using `sep` as the separator, optionally limiting the number of splits to `maxsplit`. Except for splitting from the right, this method behaves like split(). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="rsplit.sep"><code>sep</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The string to split on.</td> +</tr> +<tr> +<td id="rsplit.maxsplit"><code>maxsplit</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>unbound</code><br /> +The maximum number of splits.</td> +</tr> +</tbody> +</table> + +## rstrip + +``` rule-signature +string string.rstrip(chars=None) +``` + +Returns a copy of the string where trailing characters that appear in `chars` are removed. Note that `chars` is not a suffix: all combinations of its value are removed: + +``` python +"abcbaa".rstrip("ab") == "abc" +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="rstrip.chars"><code>chars</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The characters to remove, or all whitespace if None.</td> +</tr> +</tbody> +</table> + +## split + +``` rule-signature +list string.split(sep, maxsplit=unbound) +``` + +Returns a list of all the words in the string, using `sep` as the separator, optionally limiting the number of splits to `maxsplit`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="split.sep"><code>sep</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The string to split on.</td> +</tr> +<tr> +<td id="split.maxsplit"><code>maxsplit</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>unbound</code><br /> +The maximum number of splits.</td> +</tr> +</tbody> +</table> + +## splitlines + +``` rule-signature +sequence string.splitlines(keepends=False) +``` + +Splits the string at line boundaries ('\n', '\r\n', '\r') and returns the result as a new mutable list. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="splitlines.keepends"><code>keepends</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether the line breaks should be included in the resulting list.</td> +</tr> +</tbody> +</table> + +## startswith + +``` rule-signature +bool string.startswith(sub, start=0, end=None) +``` + +Returns True if the string starts with `sub`, otherwise False, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="startswith.sub"><code>sub</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/tuple.html" class="anchor">tuple</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The prefix (or tuple of alternative prefixes) to match.</td> +</tr> +<tr> +<td id="startswith.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>0</code><br /> +Test beginning at this position.</td> +</tr> +<tr> +<td id="startswith.end"><code>end</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; +default is <code>None</code><br /> +Stop comparing at this position.</td> +</tr> +</tbody> +</table> + +## strip + +``` rule-signature +string string.strip(chars=None) +``` + +Returns a copy of the string where leading or trailing characters that appear in `chars` are removed. Note that `chars` is neither a prefix nor a suffix: all combinations of its value are removed: + +``` python +"aabcbcbaa".strip("ab") == "cbc" +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="strip.chars"><code>chars</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The characters to remove, or all whitespace if None.</td> +</tr> +</tbody> +</table> + +## title + +``` rule-signature +string string.title() +``` + +Converts the input string into title case, i.e. every word starts with an uppercase letter while the remaining letters are lowercase. In this context, a word means strictly a sequence of letters. This method does not support supplementary Unicode characters. + +## upper + +``` rule-signature +string string.upper() +``` + +Returns the upper case version of this string. diff --git a/rules/lib/core/tuple.mdx b/rules/lib/core/tuple.mdx index c517520..b468c96 100644 --- a/rules/lib/core/tuple.mdx +++ b/rules/lib/core/tuple.mdx @@ -2,28 +2,36 @@ title: 'tuple' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.tuple">tuple</h1> +# tuple {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/Tuple.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +The built-in tuple type. Example tuple expressions: -The built-in tuple type. Example tuple expressions:<br><pre class=language-python>x = (1, 2, 3)</pre>Accessing elements is possible using indexing (starts from <code>0</code>):<br><pre class=language-python>e = x[1] # e == 2</pre>Lists support the <code>+</code> operator to concatenate two tuples. Example:<br><pre class=language-python>x = (1, 2) + (3, 4) # x == (1, 2, 3, 4) -x = ("a", "b") -x += ("c",) # x == ("a", "b", "c")</pre>Similar to lists, tuples support slice operations:<pre class=language-python>('a', 'b', 'c', 'd')[1:3] # ('b', 'c') -('a', 'b', 'c', 'd')[::2] # ('a', 'c') -('a', 'b', 'c', 'd')[3:0:-1] # ('d', 'c', 'b')</pre>Tuples are immutable, therefore <code>x[1] = "a"</code> is not supported. +``` python +x = (1, 2, 3) +``` + +Accessing elements is possible using indexing (starts from `0`): +``` python +e = x[1] # e == 2 +``` +Lists support the `+` operator to concatenate two tuples. Example: -</body> -</html> +``` python +x = (1, 2) + (3, 4) # x == (1, 2, 3, 4) +x = ("a", "b") +x += ("c",) # x == ("a", "b", "c") +``` + +Similar to lists, tuples support slice operations: + +``` python +('a', 'b', 'c', 'd')[1:3] # ('b', 'c') +('a', 'b', 'c', 'd')[::2] # ('a', 'c') +('a', 'b', 'c', 'd')[3:0:-1] # ('d', 'c', 'b') +``` -<!-- {% endraw %} --> +Tuples are immutable, therefore `x[1] = "a"` is not supported. diff --git a/rules/lib/fragments.mdx b/rules/lib/fragments.mdx index 2578698..bc620dc 100644 --- a/rules/lib/fragments.mdx +++ b/rules/lib/fragments.mdx @@ -2,41 +2,22 @@ title: 'fragments' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> -<h1 class="page-title">Configuration Fragments</h1> +# Configuration Fragments {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -Configuration fragments give rules access to language-specific parts of <a href="builtins/configuration.html">configuration</a>. <p>Rule implementations can get them using <code><a href="builtins/ctx.html#fragments">ctx.fragments</a>.<i>[fragment name]</i></code> - -<ul> - -<li><a href="/rules/lib/fragments/apple">apple</a></li> - -<li><a href="/rules/lib/fragments/bazel_android">bazel_android</a></li> - -<li><a href="/rules/lib/fragments/bazel_py">bazel_py</a></li> - -<li><a href="/rules/lib/fragments/coverage">coverage</a></li> - -<li><a href="/rules/lib/fragments/cpp">cpp</a></li> - -<li><a href="/rules/lib/fragments/j2objc">j2objc</a></li> - -<li><a href="/rules/lib/fragments/java">java</a></li> - -<li><a href="/rules/lib/fragments/objc">objc</a></li> - -<li><a href="/rules/lib/fragments/platform">platform</a></li> - -<li><a href="/rules/lib/fragments/proto">proto</a></li> - -<li><a href="/rules/lib/fragments/py">py</a></li> -</ul> -</body> -</html> +{% include "\_buttons.html" %} +Configuration fragments give rules access to language-specific parts of [configuration](builtins/configuration.html). + +Rule implementations can get them using [`ctx.fragments`](builtins/ctx.html#fragments)`.`*`[fragment name]`* + +- [apple](/rules/lib/fragments/apple) +- [bazel_android](/rules/lib/fragments/bazel_android) +- [bazel_py](/rules/lib/fragments/bazel_py) +- [coverage](/rules/lib/fragments/coverage) +- [cpp](/rules/lib/fragments/cpp) +- [j2objc](/rules/lib/fragments/j2objc) +- [java](/rules/lib/fragments/java) +- [objc](/rules/lib/fragments/objc) +- [platform](/rules/lib/fragments/platform) +- [proto](/rules/lib/fragments/proto) +- [py](/rules/lib/fragments/py) diff --git a/rules/lib/fragments/apple.mdx b/rules/lib/fragments/apple.mdx index c186887..a3e00a9 100644 --- a/rules/lib/fragments/apple.mdx +++ b/rules/lib/fragments/apple.mdx @@ -2,78 +2,57 @@ title: 'apple' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.apple">apple</h1> +# apple {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A configuration fragment for Apple platforms. -<h2>Members</h2> -<ul> - <li> - <a href="#multi_arch_platform">multi_arch_platform</a> - </li> - <li> - <a href="#single_arch_cpu">single_arch_cpu</a> - </li> - <li> - <a href="#single_arch_platform">single_arch_platform</a> - </li> - </ul> +## Members + +- [multi_arch_platform](#multi_arch_platform) +- [single_arch_cpu](#single_arch_cpu) +- [single_arch_platform](#single_arch_platform) + +## multi_arch_platform + +``` rule-signature +apple_platform apple.multi_arch_platform(platform_type) +``` - <h2 id="multi_arch_platform">multi_arch_platform</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/apple_platform.html">apple_platform</a> apple.multi_arch_platform(platform_type)</pre></p> +The platform of the current configuration for the given platform type. This should only be invoked in a context where multiple architectures may be supported; consider [single_arch_platform](#single_arch_platform) for other cases. - The platform of the current configuration for the given platform type. This should only be invoked in a context where multiple architectures may be supported; consider <a href='#single_arch_platform'>single_arch_platform</a> for other cases. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="multi_arch_platform.platform_type"> - <code>platform_type</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The apple platform type. - </td> - </tr> - </tbody> - </table> +### Parameters - <h2 id="single_arch_cpu">single_arch_cpu</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> apple.single_arch_cpu</pre></p> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="multi_arch_platform.platform_type"><code>platform_type</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The apple platform type.</td> +</tr> +</tbody> +</table> - The single "effective" architecture for this configuration (e.g., <code>i386</code> or <code>arm64</code>) in the context of rule logic that is only concerned with a single architecture (such as <code>objc_library</code>, which registers single-architecture compile actions). +## single_arch_cpu - <h2 id="single_arch_platform">single_arch_platform</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/apple_platform.html">apple_platform</a> apple.single_arch_platform</pre></p> +``` rule-signature +string apple.single_arch_cpu +``` - The platform of the current configuration. This should only be invoked in a context where only a single architecture may be supported; consider <a href='#multi_arch_platform'>multi_arch_platform</a> for other cases. +The single "effective" architecture for this configuration (e.g., `i386` or `arm64`) in the context of rule logic that is only concerned with a single architecture (such as `objc_library`, which registers single-architecture compile actions). +## single_arch_platform -</body> -</html> +``` rule-signature +apple_platform apple.single_arch_platform +``` -<!-- {% endraw %} --> +The platform of the current configuration. This should only be invoked in a context where only a single architecture may be supported; consider [multi_arch_platform](#multi_arch_platform) for other cases. diff --git a/rules/lib/fragments/bazel_android.mdx b/rules/lib/fragments/bazel_android.mdx index 5077e73..393b736 100644 --- a/rules/lib/fragments/bazel_android.mdx +++ b/rules/lib/fragments/bazel_android.mdx @@ -2,35 +2,19 @@ title: 'bazel_android' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.bazel_android">bazel_android</h1> +# bazel_android {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/rules/android/BazelAndroidConfiguration.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - - - -<h2>Members</h2> -<ul> - <li> - <a href="#merge_android_manifest_permissions">merge_android_manifest_permissions</a> - </li> - </ul> +{% include "\_buttons.html" %} - <h2 id="merge_android_manifest_permissions">merge_android_manifest_permissions</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> bazel_android.merge_android_manifest_permissions</pre></p> +## Members - The value of --merge_android_manifest_permissions flag. +- [merge_android_manifest_permissions](#merge_android_manifest_permissions) +## merge_android_manifest_permissions -</body> -</html> +``` rule-signature +bool bazel_android.merge_android_manifest_permissions +``` -<!-- {% endraw %} --> +The value of --merge_android_manifest_permissions flag. diff --git a/rules/lib/fragments/bazel_py.mdx b/rules/lib/fragments/bazel_py.mdx index 44e3174..b1246d4 100644 --- a/rules/lib/fragments/bazel_py.mdx +++ b/rules/lib/fragments/bazel_py.mdx @@ -2,43 +2,28 @@ title: 'bazel_py' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.bazel_py">bazel_py</h1> +# bazel_py {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - - +{% include "\_buttons.html" %} -<h2>Members</h2> -<ul> - <li> - <a href="#python_import_all_repositories">python_import_all_repositories</a> - </li> - <li> - <a href="#python_path">python_path</a> - </li> - </ul> +## Members - <h2 id="python_import_all_repositories">python_import_all_repositories</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> bazel_py.python_import_all_repositories</pre></p> +- [python_import_all_repositories](#python_import_all_repositories) +- [python_path](#python_path) - The value of the --experimental_python_import_all_repositories flag. +## python_import_all_repositories - <h2 id="python_path">python_path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> bazel_py.python_path</pre></p> +``` rule-signature +bool bazel_py.python_import_all_repositories +``` - The value of the --python_path flag. +The value of the --experimental_python_import_all_repositories flag. +## python_path -</body> -</html> +``` rule-signature +string bazel_py.python_path +``` -<!-- {% endraw %} --> +The value of the --python_path flag. diff --git a/rules/lib/fragments/coverage.mdx b/rules/lib/fragments/coverage.mdx index 40a4ec7..782c9b2 100644 --- a/rules/lib/fragments/coverage.mdx +++ b/rules/lib/fragments/coverage.mdx @@ -2,36 +2,29 @@ title: 'coverage' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.coverage">coverage</h1> +# coverage {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A configuration fragment representing the coverage configuration. -<h2>Members</h2> -<ul> - <li> - <a href="#output_generator">output_generator</a> - </li> - </ul> +## Members + +- [output_generator](#output_generator) - <h2 id="output_generator">output_generator</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> coverage.output_generator</pre></p> +## output_generator - Returns the label pointed to by the <a href="https://bazel.build/reference/command-line-reference#flag--coverage_output_generator"><code>--coverage_output_generator</code></a> option if coverage collection is enabled, otherwise returns <code>None</code>. Can be accessed with <a href="../globals/bzl.html#configuration_field"><code>configuration_field</code></a>:<br/><pre>attr.label(<br/> default = configuration_field(<br/> fragment = "coverage",<br/> name = "output_generator"<br/> )<br/>)</pre> - May return <code>None</code>. +``` rule-signature +Label coverage.output_generator +``` +Returns the label pointed to by the [`--coverage_output_generator`](https://bazel.build/reference/command-line-reference#flag--coverage_output_generator) option if coverage collection is enabled, otherwise returns `None`. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): -</body> -</html> + attr.label( + default = configuration_field( + fragment = "coverage", + name = "output_generator" + ) + ) -<!-- {% endraw %} --> +May return `None`. diff --git a/rules/lib/fragments/cpp.mdx b/rules/lib/fragments/cpp.mdx index 385b7a5..6c28cb9 100644 --- a/rules/lib/fragments/cpp.mdx +++ b/rules/lib/fragments/cpp.mdx @@ -2,100 +2,101 @@ title: 'cpp' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.cpp">cpp</h1> +# cpp {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A configuration fragment for C++. -<h2>Members</h2> -<ul> - <li> - <a href="#apple_generate_dsym">apple_generate_dsym</a> - </li> - <li> - <a href="#conlyopts">conlyopts</a> - </li> - <li> - <a href="#copts">copts</a> - </li> - <li> - <a href="#custom_malloc">custom_malloc</a> - </li> - <li> - <a href="#cxxopts">cxxopts</a> - </li> - <li> - <a href="#linkopts">linkopts</a> - </li> - <li> - <a href="#objc_generate_linkmap">objc_generate_linkmap</a> - </li> - <li> - <a href="#objc_should_strip_binary">objc_should_strip_binary</a> - </li> - <li> - <a href="#objccopts">objccopts</a> - </li> - </ul> +## Members + +- [apple_generate_dsym](#apple_generate_dsym) +- [conlyopts](#conlyopts) +- [copts](#copts) +- [custom_malloc](#custom_malloc) +- [cxxopts](#cxxopts) +- [linkopts](#linkopts) +- [objc_generate_linkmap](#objc_generate_linkmap) +- [objc_should_strip_binary](#objc_should_strip_binary) +- [objccopts](#objccopts) + +## apple_generate_dsym + +``` rule-signature +bool cpp.apple_generate_dsym +``` + +Whether to generate Apple debug symbol(.dSYM) artifacts. + +## conlyopts + +``` rule-signature +list cpp.conlyopts +``` + +The flags passed to Bazel by [`--conlyopt`](/docs/user-manual#flag--conlyopt) option. + +## copts + +``` rule-signature +list cpp.copts +``` - <h2 id="apple_generate_dsym">apple_generate_dsym</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cpp.apple_generate_dsym</pre></p> +The flags passed to Bazel by [`--copt`](/docs/user-manual#flag--copt) option. - Whether to generate Apple debug symbol(.dSYM) artifacts. +## custom_malloc - <h2 id="conlyopts">conlyopts</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.conlyopts</pre></p> +``` rule-signature +Label cpp.custom_malloc +``` - The flags passed to Bazel by <a href="/docs/user-manual#flag--conlyopt"><code>--conlyopt</code></a> option. +Returns label pointed to by [`--custom_malloc`](/docs/user-manual#flag--custom_malloc) option. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): - <h2 id="copts">copts</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.copts</pre></p> + attr.label( + default = configuration_field( + fragment = "cpp", + name = "custom_malloc" + ) + ) - The flags passed to Bazel by <a href="/docs/user-manual#flag--copt"><code>--copt</code></a> option. +May return `None`. - <h2 id="custom_malloc">custom_malloc</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> cpp.custom_malloc</pre></p> +## cxxopts - Returns label pointed to by <a href="/docs/user-manual#flag--custom_malloc"><code>--custom_malloc</code></a> option. Can be accessed with <a href="../globals/bzl.html#configuration_field"><code>configuration_field</code></a>:<br/><pre>attr.label(<br/> default = configuration_field(<br/> fragment = "cpp",<br/> name = "custom_malloc"<br/> )<br/>)</pre> - May return <code>None</code>. +``` rule-signature +list cpp.cxxopts +``` - <h2 id="cxxopts">cxxopts</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.cxxopts</pre></p> +The flags passed to Bazel by [`--cxxopt`](/docs/user-manual#flag--cxxopt) option. - The flags passed to Bazel by <a href="/docs/user-manual#flag--cxxopt"><code>--cxxopt</code></a> option. +## linkopts - <h2 id="linkopts">linkopts</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.linkopts</pre></p> +``` rule-signature +list cpp.linkopts +``` - The flags passed to Bazel by <a href="/docs/user-manual#flag--linkopt"><code>--linkopt</code></a> option. +The flags passed to Bazel by [`--linkopt`](/docs/user-manual#flag--linkopt) option. - <h2 id="objc_generate_linkmap">objc_generate_linkmap</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cpp.objc_generate_linkmap</pre></p> +## objc_generate_linkmap - (Apple-only) Whether to generate linkmap artifacts. +``` rule-signature +bool cpp.objc_generate_linkmap +``` - <h2 id="objc_should_strip_binary">objc_should_strip_binary</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cpp.objc_should_strip_binary</pre></p> +(Apple-only) Whether to generate linkmap artifacts. - (Apple-only) whether to perform symbol and dead-code strippings on linked binaries. +## objc_should_strip_binary - <h2 id="objccopts">objccopts</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> cpp.objccopts</pre></p> +``` rule-signature +bool cpp.objc_should_strip_binary +``` - The flags passed to Bazel by <a href="/docs/user-manual#flag--objccopt"><code>--objccopt</code></a> option. +(Apple-only) whether to perform symbol and dead-code strippings on linked binaries. +## objccopts -</body> -</html> +``` rule-signature +list cpp.objccopts +``` -<!-- {% endraw %} --> +The flags passed to Bazel by [`--objccopt`](/docs/user-manual#flag--objccopt) option. diff --git a/rules/lib/fragments/j2objc.mdx b/rules/lib/fragments/j2objc.mdx index 05e9d79..23f0ffd 100644 --- a/rules/lib/fragments/j2objc.mdx +++ b/rules/lib/fragments/j2objc.mdx @@ -2,35 +2,20 @@ title: 'j2objc' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.j2objc">j2objc</h1> +# j2objc {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/J2ObjcConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A configuration fragment for j2Objc. -<h2>Members</h2> -<ul> - <li> - <a href="#translation_flags">translation_flags</a> - </li> - </ul> - - <h2 id="translation_flags">translation_flags</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> j2objc.translation_flags</pre></p> +## Members - The list of flags to be used when the j2objc compiler is invoked. +- [translation_flags](#translation_flags) +## translation_flags -</body> -</html> +``` rule-signature +list j2objc.translation_flags +``` -<!-- {% endraw %} --> +The list of flags to be used when the j2objc compiler is invoked. diff --git a/rules/lib/fragments/java.mdx b/rules/lib/fragments/java.mdx index 729eab5..fcbb189 100644 --- a/rules/lib/fragments/java.mdx +++ b/rules/lib/fragments/java.mdx @@ -2,139 +2,137 @@ title: 'java' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.java">java</h1> +# java {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A java compiler configuration. -<h2>Members</h2> -<ul> - <li> - <a href="#bytecode_optimization_pass_actions">bytecode_optimization_pass_actions</a> - </li> - <li> - <a href="#bytecode_optimizer_mnemonic">bytecode_optimizer_mnemonic</a> - </li> - <li> - <a href="#default_javac_flags">default_javac_flags</a> - </li> - <li> - <a href="#default_javac_flags_depset">default_javac_flags_depset</a> - </li> - <li> - <a href="#default_jvm_opts">default_jvm_opts</a> - </li> - <li> - <a href="#disallow_java_import_exports">disallow_java_import_exports</a> - </li> - <li> - <a href="#multi_release_deploy_jars">multi_release_deploy_jars</a> - </li> - <li> - <a href="#one_version_enforcement_level">one_version_enforcement_level</a> - </li> - <li> - <a href="#plugins">plugins</a> - </li> - <li> - <a href="#run_android_lint">run_android_lint</a> - </li> - <li> - <a href="#split_bytecode_optimization_pass">split_bytecode_optimization_pass</a> - </li> - <li> - <a href="#strict_java_deps">strict_java_deps</a> - </li> - <li> - <a href="#use_header_compilation_direct_deps">use_header_compilation_direct_deps</a> - </li> - <li> - <a href="#use_ijars">use_ijars</a> - </li> - </ul> +## Members + +- [bytecode_optimization_pass_actions](#bytecode_optimization_pass_actions) +- [bytecode_optimizer_mnemonic](#bytecode_optimizer_mnemonic) +- [default_javac_flags](#default_javac_flags) +- [default_javac_flags_depset](#default_javac_flags_depset) +- [default_jvm_opts](#default_jvm_opts) +- [disallow_java_import_exports](#disallow_java_import_exports) +- [multi_release_deploy_jars](#multi_release_deploy_jars) +- [one_version_enforcement_level](#one_version_enforcement_level) +- [plugins](#plugins) +- [run_android_lint](#run_android_lint) +- [split_bytecode_optimization_pass](#split_bytecode_optimization_pass) +- [strict_java_deps](#strict_java_deps) +- [use_header_compilation_direct_deps](#use_header_compilation_direct_deps) +- [use_ijars](#use_ijars) + +## bytecode_optimization_pass_actions + +``` rule-signature +int java.bytecode_optimization_pass_actions +``` + +This specifies the number of actions to divide the OPTIMIZATION stage of the bytecode optimizer into. Note that if split_bytecode_optimization_pass is set, this will only change behavior if it is \> 2. + +## bytecode_optimizer_mnemonic + +``` rule-signature +string java.bytecode_optimizer_mnemonic +``` + +The mnemonic for the bytecode optimizer. + +## default_javac_flags + +``` rule-signature +list java.default_javac_flags +``` + +The default flags for the Java compiler. + +## default_javac_flags_depset + +``` rule-signature +depset java.default_javac_flags_depset +``` - <h2 id="bytecode_optimization_pass_actions">bytecode_optimization_pass_actions</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> java.bytecode_optimization_pass_actions</pre></p> +The default flags for the Java compiler. - This specifies the number of actions to divide the OPTIMIZATION stage of the bytecode optimizer into. Note that if split_bytecode_optimization_pass is set, this will only change behavior if it is > 2. +## default_jvm_opts - <h2 id="bytecode_optimizer_mnemonic">bytecode_optimizer_mnemonic</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> java.bytecode_optimizer_mnemonic</pre></p> +``` rule-signature +list java.default_jvm_opts +``` - The mnemonic for the bytecode optimizer. +Additional options to pass to the Java VM for each java_binary target - <h2 id="default_javac_flags">default_javac_flags</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java.default_javac_flags</pre></p> +## disallow_java_import_exports - The default flags for the Java compiler. +``` rule-signature +bool java.disallow_java_import_exports() +``` - <h2 id="default_javac_flags_depset">default_javac_flags_depset</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java.default_javac_flags_depset</pre></p> +Returns true if java_import exports are not allowed. - The default flags for the Java compiler. +## multi_release_deploy_jars - <h2 id="default_jvm_opts">default_jvm_opts</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java.default_jvm_opts</pre></p> +``` rule-signature +bool java.multi_release_deploy_jars +``` - Additional options to pass to the Java VM for each java_binary target +The value of the --incompatible_multi_release_deploy_jars flag. - <h2 id="disallow_java_import_exports">disallow_java_import_exports</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.disallow_java_import_exports()</pre></p> +## one_version_enforcement_level - Returns true if java_import exports are not allowed. +``` rule-signature +string java.one_version_enforcement_level +``` - <h2 id="multi_release_deploy_jars">multi_release_deploy_jars</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.multi_release_deploy_jars</pre></p> +The value of the --experimental_one_version_enforcement flag. - The value of the --incompatible_multi_release_deploy_jars flag. +## plugins - <h2 id="one_version_enforcement_level">one_version_enforcement_level</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> java.one_version_enforcement_level</pre></p> +``` rule-signature +list java.plugins +``` - The value of the --experimental_one_version_enforcement flag. +A list containing the labels provided with --plugins, if any. - <h2 id="plugins">plugins</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java.plugins</pre></p> +## run_android_lint - A list containing the labels provided with --plugins, if any. +``` rule-signature +bool java.run_android_lint +``` - <h2 id="run_android_lint">run_android_lint</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.run_android_lint</pre></p> +The value of the --experimental_run_android_lint_on_java_rules flag. - The value of the --experimental_run_android_lint_on_java_rules flag. +## split_bytecode_optimization_pass - <h2 id="split_bytecode_optimization_pass">split_bytecode_optimization_pass</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.split_bytecode_optimization_pass</pre></p> +``` rule-signature +bool java.split_bytecode_optimization_pass +``` - Returns whether the OPTIMIZATION stage of the bytecode optimizer will be split across two actions. +Returns whether the OPTIMIZATION stage of the bytecode optimizer will be split across two actions. - <h2 id="strict_java_deps">strict_java_deps</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> java.strict_java_deps</pre></p> +## strict_java_deps - The value of the strict_java_deps flag. +``` rule-signature +string java.strict_java_deps +``` - <h2 id="use_header_compilation_direct_deps">use_header_compilation_direct_deps</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.use_header_compilation_direct_deps()</pre></p> +The value of the strict_java_deps flag. - Returns true if Java header compilation should use separate outputs for direct deps. +## use_header_compilation_direct_deps - <h2 id="use_ijars">use_ijars</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> java.use_ijars()</pre></p> +``` rule-signature +bool java.use_header_compilation_direct_deps() +``` - Returns true iff Java compilation should use ijars. +Returns true if Java header compilation should use separate outputs for direct deps. +## use_ijars -</body> -</html> +``` rule-signature +bool java.use_ijars() +``` -<!-- {% endraw %} --> +Returns true iff Java compilation should use ijars. diff --git a/rules/lib/fragments/objc.mdx b/rules/lib/fragments/objc.mdx index d560201..c6dd982 100644 --- a/rules/lib/fragments/objc.mdx +++ b/rules/lib/fragments/objc.mdx @@ -2,110 +2,104 @@ title: 'objc' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.objc">objc</h1> +# objc {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ObjcConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A configuration fragment for Objective-C. -<h2>Members</h2> -<ul> - <li> - <a href="#alwayslink_by_default">alwayslink_by_default</a> - </li> - <li> - <a href="#builtin_objc_strip_action">builtin_objc_strip_action</a> - </li> - <li> - <a href="#copts_for_current_compilation_mode">copts_for_current_compilation_mode</a> - </li> - <li> - <a href="#disallow_sdk_frameworks_attributes">disallow_sdk_frameworks_attributes</a> - </li> - <li> - <a href="#ios_simulator_device">ios_simulator_device</a> - </li> - <li> - <a href="#ios_simulator_version">ios_simulator_version</a> - </li> - <li> - <a href="#run_memleaks">run_memleaks</a> - </li> - <li> - <a href="#signing_certificate_name">signing_certificate_name</a> - </li> - <li> - <a href="#strip_executable_safely">strip_executable_safely</a> - </li> - <li> - <a href="#uses_device_debug_entitlements">uses_device_debug_entitlements</a> - </li> - </ul> +## Members + +- [alwayslink_by_default](#alwayslink_by_default) +- [builtin_objc_strip_action](#builtin_objc_strip_action) +- [copts_for_current_compilation_mode](#copts_for_current_compilation_mode) +- [disallow_sdk_frameworks_attributes](#disallow_sdk_frameworks_attributes) +- [ios_simulator_device](#ios_simulator_device) +- [ios_simulator_version](#ios_simulator_version) +- [run_memleaks](#run_memleaks) +- [signing_certificate_name](#signing_certificate_name) +- [strip_executable_safely](#strip_executable_safely) +- [uses_device_debug_entitlements](#uses_device_debug_entitlements) + +## alwayslink_by_default + +``` rule-signature +bool objc.alwayslink_by_default +``` + +Returns whether objc_library and objc_import should default to alwayslink=True. + +## builtin_objc_strip_action + +``` rule-signature +bool objc.builtin_objc_strip_action +``` + +Returns whether to emit a strip action as part of objc linking. + +## copts_for_current_compilation_mode - <h2 id="alwayslink_by_default">alwayslink_by_default</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.alwayslink_by_default</pre></p> +``` rule-signature +list objc.copts_for_current_compilation_mode +``` - Returns whether objc_library and objc_import should default to alwayslink=True. +Returns a list of default options to use for compiling Objective-C in the current mode. - <h2 id="builtin_objc_strip_action">builtin_objc_strip_action</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.builtin_objc_strip_action</pre></p> +## disallow_sdk_frameworks_attributes - Returns whether to emit a strip action as part of objc linking. +``` rule-signature +bool objc.disallow_sdk_frameworks_attributes +``` - <h2 id="copts_for_current_compilation_mode">copts_for_current_compilation_mode</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> objc.copts_for_current_compilation_mode</pre></p> +Returns whether sdk_frameworks and weak_sdk_frameworks are disallowed attributes. - Returns a list of default options to use for compiling Objective-C in the current mode. +## ios_simulator_device - <h2 id="disallow_sdk_frameworks_attributes">disallow_sdk_frameworks_attributes</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.disallow_sdk_frameworks_attributes</pre></p> +``` rule-signature +string objc.ios_simulator_device +``` - Returns whether sdk_frameworks and weak_sdk_frameworks are disallowed attributes. +The type of device (e.g. 'iPhone 6') to use when running on the simulator. +May return `None`. - <h2 id="ios_simulator_device">ios_simulator_device</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> objc.ios_simulator_device</pre></p> +## ios_simulator_version - The type of device (e.g. 'iPhone 6') to use when running on the simulator. - May return <code>None</code>. +``` rule-signature +DottedVersion objc.ios_simulator_version +``` - <h2 id="ios_simulator_version">ios_simulator_version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/DottedVersion.html">DottedVersion</a> objc.ios_simulator_version</pre></p> +The SDK version of the iOS simulator to use when running on the simulator. +May return `None`. - The SDK version of the iOS simulator to use when running on the simulator. - May return <code>None</code>. +## run_memleaks - <h2 id="run_memleaks">run_memleaks</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.run_memleaks</pre></p> +``` rule-signature +bool objc.run_memleaks +``` - Returns a boolean indicating whether memleaks should be run during tests or not. +Returns a boolean indicating whether memleaks should be run during tests or not. - <h2 id="signing_certificate_name">signing_certificate_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> objc.signing_certificate_name</pre></p> +## signing_certificate_name - Returns the flag-supplied certificate name to be used in signing, or None if no such certificate was specified. - May return <code>None</code>. +``` rule-signature +string objc.signing_certificate_name +``` - <h2 id="strip_executable_safely">strip_executable_safely</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.strip_executable_safely</pre></p> +Returns the flag-supplied certificate name to be used in signing, or None if no such certificate was specified. +May return `None`. - Returns whether executable strip action should use flag -x, which does not break dynamic symbol resolution. +## strip_executable_safely - <h2 id="uses_device_debug_entitlements">uses_device_debug_entitlements</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> objc.uses_device_debug_entitlements</pre></p> +``` rule-signature +bool objc.strip_executable_safely +``` - Returns whether device debug entitlements should be included when signing an application. +Returns whether executable strip action should use flag -x, which does not break dynamic symbol resolution. +## uses_device_debug_entitlements -</body> -</html> +``` rule-signature +bool objc.uses_device_debug_entitlements +``` -<!-- {% endraw %} --> +Returns whether device debug entitlements should be included when signing an application. diff --git a/rules/lib/fragments/platform.mdx b/rules/lib/fragments/platform.mdx index 877d00c..bd008c5 100644 --- a/rules/lib/fragments/platform.mdx +++ b/rules/lib/fragments/platform.mdx @@ -2,43 +2,29 @@ title: 'platform' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.platform">platform</h1> +# platform {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} The platform configuration. -<h2>Members</h2> -<ul> - <li> - <a href="#host_platform">host_platform</a> - </li> - <li> - <a href="#platform">platform</a> - </li> - </ul> +## Members - <h2 id="host_platform">host_platform</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> platform.host_platform</pre></p> +- [host_platform](#host_platform) +- [platform](#platform) - The current host platform +## host_platform - <h2 id="platform">platform</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> platform.platform</pre></p> +``` rule-signature +Label platform.host_platform +``` - The current target platform +The current host platform +## platform -</body> -</html> +``` rule-signature +Label platform.platform +``` -<!-- {% endraw %} --> +The current target platform diff --git a/rules/lib/fragments/proto.mdx b/rules/lib/fragments/proto.mdx index a9686e6..e04ae09 100644 --- a/rules/lib/fragments/proto.mdx +++ b/rules/lib/fragments/proto.mdx @@ -2,24 +2,8 @@ title: 'proto' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.proto">proto</h1> +# proto {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ProtoConfigurationApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A configuration fragment representing protocol buffers. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/fragments/py.mdx b/rules/lib/fragments/py.mdx index 06080f0..d3721fd 100644 --- a/rules/lib/fragments/py.mdx +++ b/rules/lib/fragments/py.mdx @@ -2,83 +2,74 @@ title: 'py' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.py">py</h1> +# py {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/rules/python/PythonConfiguration.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A configuration fragment for Python. -<h2>Members</h2> -<ul> - <li> - <a href="#build_python_zip">build_python_zip</a> - </li> - <li> - <a href="#default_python_version">default_python_version</a> - </li> - <li> - <a href="#default_to_explicit_init_py">default_to_explicit_init_py</a> - </li> - <li> - <a href="#disable_py2">disable_py2</a> - </li> - <li> - <a href="#disallow_native_rules">disallow_native_rules</a> - </li> - <li> - <a href="#include_label_in_linkstamp">include_label_in_linkstamp</a> - </li> - <li> - <a href="#use_toolchains">use_toolchains</a> - </li> - </ul> +## Members + +- [build_python_zip](#build_python_zip) +- [default_python_version](#default_python_version) +- [default_to_explicit_init_py](#default_to_explicit_init_py) +- [disable_py2](#disable_py2) +- [disallow_native_rules](#disallow_native_rules) +- [include_label_in_linkstamp](#include_label_in_linkstamp) +- [use_toolchains](#use_toolchains) + +## build_python_zip + +``` rule-signature +bool py.build_python_zip +``` + +The effective value of --build_python_zip + +## default_python_version - <h2 id="build_python_zip">build_python_zip</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.build_python_zip</pre></p> +``` rule-signature +string py.default_python_version +``` - The effective value of --build_python_zip +No-op: PY3 is the default Python version. - <h2 id="default_python_version">default_python_version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> py.default_python_version</pre></p> +## default_to_explicit_init_py - No-op: PY3 is the default Python version. +``` rule-signature +bool py.default_to_explicit_init_py +``` - <h2 id="default_to_explicit_init_py">default_to_explicit_init_py</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.default_to_explicit_init_py</pre></p> +The value from the --incompatible_default_to_explicit_init_py flag - The value from the --incompatible_default_to_explicit_init_py flag +## disable_py2 - <h2 id="disable_py2">disable_py2</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.disable_py2</pre></p> +``` rule-signature +bool py.disable_py2 +``` - No-op: PY2 is no longer supported. +No-op: PY2 is no longer supported. - <h2 id="disallow_native_rules">disallow_native_rules</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.disallow_native_rules</pre></p> +## disallow_native_rules - The value of the --incompatible_python_disallow_native_rules flag. +``` rule-signature +bool py.disallow_native_rules +``` - <h2 id="include_label_in_linkstamp">include_label_in_linkstamp</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.include_label_in_linkstamp</pre></p> +The value of the --incompatible_python_disallow_native_rules flag. - Whether the build label is included in unstamped builds. +## include_label_in_linkstamp - <h2 id="use_toolchains">use_toolchains</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> py.use_toolchains</pre></p> +``` rule-signature +bool py.include_label_in_linkstamp +``` - No-op: Python toolchains are always used. +Whether the build label is included in unstamped builds. +## use_toolchains -</body> -</html> +``` rule-signature +bool py.use_toolchains +``` -<!-- {% endraw %} --> +No-op: Python toolchains are always used. diff --git a/rules/lib/globals.mdx b/rules/lib/globals.mdx index 5d948e3..b8d5af2 100644 --- a/rules/lib/globals.mdx +++ b/rules/lib/globals.mdx @@ -2,31 +2,15 @@ title: 'globals' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> -<h1 class="page-title">Global functions</h1> +# Global functions {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} +{% include "\_buttons.html" %} This section lists the global functions available in Starlark. The list of available functions differs depending on the file type (whether a BUILD file, or a .bzl file, etc). -<ul> - -<li><a href="/rules/lib/globals/bzl">.bzl files</a></li> - -<li><a href="/rules/lib/globals/all">All Bazel files</a></li> - -<li><a href="/rules/lib/globals/build">BUILD files</a></li> - -<li><a href="/rules/lib/globals/module">MODULE.bazel files</a></li> - -<li><a href="/rules/lib/globals/repo">REPO.bazel files</a></li> - -<li><a href="/rules/lib/globals/vendor">VENDOR.bazel files</a></li> -</ul> -</body> -</html> +- [.bzl files](/rules/lib/globals/bzl) +- [All Bazel files](/rules/lib/globals/all) +- [BUILD files](/rules/lib/globals/build) +- [MODULE.bazel files](/rules/lib/globals/module) +- [REPO.bazel files](/rules/lib/globals/repo) +- [VENDOR.bazel files](/rules/lib/globals/vendor) diff --git a/rules/lib/globals/all.mdx b/rules/lib/globals/all.mdx index ee767ec..bc01aa1 100644 --- a/rules/lib/globals/all.mdx +++ b/rules/lib/globals/all.mdx @@ -2,569 +2,463 @@ title: 'all' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.all">All Bazel files</h1> +# All Bazel files {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Methods available in all Bazel files, including .bzl files, BUILD, MODULE.bazel, VENDOR.bazel, and WORKSPACE. -<h2>Members</h2> -<ul> - <li> - <a href="#abs">abs</a> - </li> - <li> - <a href="#all">all</a> - </li> - <li> - <a href="#any">any</a> - </li> - <li> - <a href="#bool">bool</a> - </li> - <li> - <a href="#dict">dict</a> - </li> - <li> - <a href="#dir">dir</a> - </li> - <li> - <a href="#enumerate">enumerate</a> - </li> - <li> - <a href="#fail">fail</a> - </li> - <li> - <a href="#float">float</a> - </li> - <li> - <a href="#getattr">getattr</a> - </li> - <li> - <a href="#hasattr">hasattr</a> - </li> - <li> - <a href="#hash">hash</a> - </li> - <li> - <a href="#int">int</a> - </li> - <li> - <a href="#len">len</a> - </li> - <li> - <a href="#list">list</a> - </li> - <li> - <a href="#max">max</a> - </li> - <li> - <a href="#min">min</a> - </li> - <li> - <a href="#print">print</a> - </li> - <li> - <a href="#range">range</a> - </li> - <li> - <a href="#repr">repr</a> - </li> - <li> - <a href="#reversed">reversed</a> - </li> - <li> - <a href="#set">set</a> - </li> - <li> - <a href="#sorted">sorted</a> - </li> - <li> - <a href="#str">str</a> - </li> - <li> - <a href="#tuple">tuple</a> - </li> - <li> - <a href="#type">type</a> - </li> - <li> - <a href="#zip">zip</a> - </li> - </ul> - - <h2 id="abs">abs</h2> - <p><pre class="rule-signature">unknown abs(x)</pre></p> - - Returns the absolute value of a number (a non-negative number with the same magnitude).<pre class="language-python">abs(-2.3) == 2.3</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="abs.x"> - <code>x</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; or <a class="anchor" href="../core/float.html">float</a>; - required<br/> - A number (int or float) - </td> - </tr> - </tbody> - </table> - - <h2 id="all">all</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> all(elements)</pre></p> - - Returns true if all elements evaluate to True or if the collection is empty. Elements are converted to boolean using the <a href="#bool">bool</a> function.<pre class="language-python">all(["hello", 3, True]) == True -all([-1, 0, 1]) == False</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="all.elements"> - <code>elements</code> - </td> - <td> - iterable; - required<br/> - A collection of elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="any">any</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> any(elements)</pre></p> - - Returns true if at least one element evaluates to True. Elements are converted to boolean using the <a href="#bool">bool</a> function.<pre class="language-python">any([-1, 0, 1]) == True -any([False, 0, ""]) == False</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="any.elements"> - <code>elements</code> - </td> - <td> - iterable; - required<br/> - A collection of elements. - </td> - </tr> - </tbody> - </table> - - <h2 id="bool">bool</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> bool(x=False)</pre></p> - - Constructor for the bool type. It returns <code>False</code> if the object is <code>None</code>, <code>False</code>, an empty string (<code>""</code>), the number <code>0</code>, or an empty collection (e.g. <code>()</code>, <code>[]</code>). Otherwise, it returns <code>True</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="bool.x"> - <code>x</code> - </td> - <td> - default is <code>False</code><br/> - The variable to convert. - </td> - </tr> - </tbody> - </table> - - <h2 id="dict">dict</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> dict(pairs=[], **kwargs)</pre></p> - - Creates a <a href="../core/dict.html">dictionary</a> from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="dict.pairs"> - <code>pairs</code> - </td> - <td> - default is <code>[]</code><br/> - A dict, or an iterable whose elements are each of length 2 (key, value). - </td> - </tr> - <tr> - <td id="dict.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - Dictionary of additional entries. - </td> - </tr> - </tbody> - </table> - - <h2 id="dir">dir</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dir(x)</pre></p> - - Returns a list of strings: the names of the attributes and methods of the parameter object. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="dir.x"> - <code>x</code> - </td> - <td> - required<br/> - The object to check. - </td> - </tr> - </tbody> - </table> - - <h2 id="enumerate">enumerate</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> enumerate(list, start=0)</pre></p> - - Returns a list of pairs (two-element tuples), with the index (int) and the item from the input sequence. -<pre class="language-python">enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="enumerate.list"> - <code>list</code> - </td> - <td> - required<br/> - input sequence. - </td> - </tr> - <tr> - <td id="enumerate.start"> - <code>start</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>0</code><br/> - start index. - </td> - </tr> - </tbody> - </table> - - <h2 id="fail">fail</h2> - <p><pre class="rule-signature"><code>None</code> fail(*args, msg=None, attr=None, sep=" ")</pre></p> - - Causes execution to fail with an error. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="fail.msg"> - <code>msg</code> - </td> - <td> - default is <code>None</code><br/> - Deprecated: use positional arguments instead. This argument acts like an implicit leading positional argument. - </td> - </tr> - <tr> - <td id="fail.attr"> - <code>attr</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Deprecated. Causes an optional prefix containing this string to be added to the error message. - </td> - </tr> - <tr> - <td id="fail.sep"> - <code>sep</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>" "</code><br/> - The separator string between the objects, default is space (" "). - </td> - </tr> - <tr> - <td id="fail.args"> - <code>args</code> - </td> - <td> - required<br/> - A list of values, formatted with debugPrint (which is equivalent to str by default) and joined with sep (defaults to " "), that appear in the error message. - </td> - </tr> - </tbody> - </table> - - <h2 id="float">float</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/float.html">float</a> float(x=unbound)</pre></p> - - Returns x as a float value. <ul><li>If <code>x</code> is already a float, <code>float</code> returns it unchanged. <li>If <code>x</code> is a bool, <code>float</code> returns 1.0 for True and 0.0 for False. <li>If <code>x</code> is an int, <code>float</code> returns the nearest finite floating-point value to x, or an error if the magnitude is too large. <li>If <code>x</code> is a string, it must be a valid floating-point literal, or be equal (ignoring case) to <code>NaN</code>, <code>Inf</code>, or <code>Infinity</code>, optionally preceded by a <code>+</code> or <code>-</code> sign. </ul>Any other value causes an error. With no argument, <code>float()</code> returns 0.0. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="float.x"> - <code>x</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/int.html">int</a>; or <a class="anchor" href="../core/float.html">float</a>; - default is <code>unbound</code><br/> - The value to convert. - </td> - </tr> - </tbody> - </table> - - <h2 id="getattr">getattr</h2> - <p><pre class="rule-signature">unknown getattr(x, name, default=unbound)</pre></p> - - Returns the struct's field of the given name if it exists. If not, it either returns <code>default</code> (if specified) or raises an error. <code>getattr(x, "foobar")</code> is equivalent to <code>x.foobar</code>.<pre class="language-python">getattr(ctx.attr, "myattr") -getattr(ctx.attr, "myattr", "mydefault")</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="getattr.x"> - <code>x</code> - </td> - <td> - required<br/> - The struct whose attribute is accessed. - </td> - </tr> - <tr> - <td id="getattr.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the struct attribute. - </td> - </tr> - <tr> - <td id="getattr.default"> - <code>default</code> - </td> - <td> - default is <code>unbound</code><br/> - The default value to return in case the struct doesn't have an attribute of the given name. - </td> - </tr> - </tbody> - </table> - - <h2 id="hasattr">hasattr</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> hasattr(x, name)</pre></p> - - Returns True if the object <code>x</code> has an attribute or method of the given <code>name</code>, otherwise False. Example:<br><pre class="language-python">hasattr(ctx.attr, "myattr")</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="hasattr.x"> - <code>x</code> - </td> - <td> - required<br/> - The object to check. - </td> - </tr> - <tr> - <td id="hasattr.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the attribute. - </td> - </tr> - </tbody> - </table> - - <h2 id="hash">hash</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> hash(value)</pre></p> - - Return a hash value for a string. This is computed deterministically using the same algorithm as Java's <code>String.hashCode()</code>, namely: <pre class="language-python">s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1]</pre> Hashing of values besides strings is not currently supported. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="hash.value"> - <code>value</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - String value to hash. - </td> - </tr> - </tbody> - </table> - - <h2 id="int">int</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> int(x, base=unbound)</pre></p> - - Returns x as an int value.<ul><li>If <code>x</code> is already an int, <code>int</code> returns it unchanged.<li>If <code>x</code> is a bool, <code>int</code> returns 1 for True and 0 for False.<li>If <code>x</code> is a string, it must have the format <code><sign><prefix><digits></code>. <code><sign></code> is either <code>"+"</code>, <code>"-"</code>, or empty (interpreted as positive). <code><digits></code> are a sequence of digits from 0 up to <code>base</code> - 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where <code>base</code> is 2/8/16, <code><prefix></code> is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the <code>base</code> is any other value besides these bases or the special value 0, the prefix must be empty. In the case where <code>base</code> is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If <code>base</code> is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type.<li>If <code>x</code> is a float, <code>int</code> returns the integer value of the float, rounding towards zero. It is an error if x is non-finite (NaN or infinity).</ul>This function fails if <code>x</code> is any other type, or if the value is a string not satisfying the above format. Unlike Python's <code>int</code> function, this function does not allow zero arguments, and does not allow extraneous whitespace for string arguments.<p>Examples:<pre class="language-python">int("123") == 123 +## Members + +- [abs](#abs) +- [all](#all) +- [any](#any) +- [bool](#bool) +- [dict](#dict) +- [dir](#dir) +- [enumerate](#enumerate) +- [fail](#fail) +- [float](#float) +- [getattr](#getattr) +- [hasattr](#hasattr) +- [hash](#hash) +- [int](#int) +- [len](#len) +- [list](#list) +- [max](#max) +- [min](#min) +- [print](#print) +- [range](#range) +- [repr](#repr) +- [reversed](#reversed) +- [set](#set) +- [sorted](#sorted) +- [str](#str) +- [tuple](#tuple) +- [type](#type) +- [zip](#zip) + +## abs + +``` rule-signature +unknown abs(x) +``` + +Returns the absolute value of a number (a non-negative number with the same magnitude). + +``` python +abs(-2.3) == 2.3 +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="abs.x"><code>x</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; or <a href="../core/float.html" class="anchor">float</a>; +required<br /> +A number (int or float)</td> +</tr> +</tbody> +</table> + +## all + +``` rule-signature +bool all(elements) +``` + +Returns true if all elements evaluate to True or if the collection is empty. Elements are converted to boolean using the [bool](#bool) function. + +``` python +all(["hello", 3, True]) == True +all([-1, 0, 1]) == False +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="all.elements"><code>elements</code></td> +<td>iterable; +required<br /> +A collection of elements.</td> +</tr> +</tbody> +</table> + +## any + +``` rule-signature +bool any(elements) +``` + +Returns true if at least one element evaluates to True. Elements are converted to boolean using the [bool](#bool) function. + +``` python +any([-1, 0, 1]) == True +any([False, 0, ""]) == False +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="any.elements"><code>elements</code></td> +<td>iterable; +required<br /> +A collection of elements.</td> +</tr> +</tbody> +</table> + +## bool + +``` rule-signature +bool bool(x=False) +``` + +Constructor for the bool type. It returns `False` if the object is `None`, `False`, an empty string (`""`), the number `0`, or an empty collection (e.g. `()`, `[]`). Otherwise, it returns `True`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="bool.x"><code>x</code></td> +<td>default is <code>False</code><br /> +The variable to convert.</td> +</tr> +</tbody> +</table> + +## dict + +``` rule-signature +dict dict(pairs=[], **kwargs) +``` + +Creates a [dictionary](../core/dict.html) from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="dict.pairs"><code>pairs</code></td> +<td>default is <code>[]</code><br /> +A dict, or an iterable whose elements are each of length 2 (key, value).</td> +</tr> +<tr> +<td id="dict.kwargs"><code>kwargs</code></td> +<td>required<br /> +Dictionary of additional entries.</td> +</tr> +</tbody> +</table> + +## dir + +``` rule-signature +list dir(x) +``` + +Returns a list of strings: the names of the attributes and methods of the parameter object. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="dir.x"><code>x</code></td> +<td>required<br /> +The object to check.</td> +</tr> +</tbody> +</table> + +## enumerate + +``` rule-signature +list enumerate(list, start=0) +``` + +Returns a list of pairs (two-element tuples), with the index (int) and the item from the input sequence. + +``` python +enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)] +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="enumerate.list"><code>list</code></td> +<td>required<br /> +input sequence.</td> +</tr> +<tr> +<td id="enumerate.start"><code>start</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>0</code><br /> +start index.</td> +</tr> +</tbody> +</table> + +## fail + +``` rule-signature +None fail(*args, msg=None, attr=None, sep=" ") +``` + +Causes execution to fail with an error. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="fail.msg"><code>msg</code></td> +<td>default is <code>None</code><br /> +Deprecated: use positional arguments instead. This argument acts like an implicit leading positional argument.</td> +</tr> +<tr> +<td id="fail.attr"><code>attr</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Deprecated. Causes an optional prefix containing this string to be added to the error message.</td> +</tr> +<tr> +<td id="fail.sep"><code>sep</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>" "</code><br /> +The separator string between the objects, default is space (" ").</td> +</tr> +<tr> +<td id="fail.args"><code>args</code></td> +<td>required<br /> +A list of values, formatted with debugPrint (which is equivalent to str by default) and joined with sep (defaults to " "), that appear in the error message.</td> +</tr> +</tbody> +</table> + +## float + +``` rule-signature +float float(x=unbound) +``` + +Returns x as a float value. + +- If `x` is already a float, `float` returns it unchanged. +- If `x` is a bool, `float` returns 1.0 for True and 0.0 for False. +- If `x` is an int, `float` returns the nearest finite floating-point value to x, or an error if the magnitude is too large. +- If `x` is a string, it must be a valid floating-point literal, or be equal (ignoring case) to `NaN`, `Inf`, or `Infinity`, optionally preceded by a `+` or `-` sign. + +Any other value causes an error. With no argument, `float()` returns 0.0. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="float.x"><code>x</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/int.html" class="anchor">int</a>; or <a href="../core/float.html" class="anchor">float</a>; +default is <code>unbound</code><br /> +The value to convert.</td> +</tr> +</tbody> +</table> + +## getattr + +``` rule-signature +unknown getattr(x, name, default=unbound) +``` + +Returns the struct's field of the given name if it exists. If not, it either returns `default` (if specified) or raises an error. `getattr(x, "foobar")` is equivalent to `x.foobar`. + +``` python +getattr(ctx.attr, "myattr") +getattr(ctx.attr, "myattr", "mydefault") +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="getattr.x"><code>x</code></td> +<td>required<br /> +The struct whose attribute is accessed.</td> +</tr> +<tr> +<td id="getattr.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the struct attribute.</td> +</tr> +<tr> +<td id="getattr.default"><code>default</code></td> +<td>default is <code>unbound</code><br /> +The default value to return in case the struct doesn't have an attribute of the given name.</td> +</tr> +</tbody> +</table> + +## hasattr + +``` rule-signature +bool hasattr(x, name) +``` + +Returns True if the object `x` has an attribute or method of the given `name`, otherwise False. Example: + +``` python +hasattr(ctx.attr, "myattr") +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="hasattr.x"><code>x</code></td> +<td>required<br /> +The object to check.</td> +</tr> +<tr> +<td id="hasattr.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the attribute.</td> +</tr> +</tbody> +</table> + +## hash + +``` rule-signature +int hash(value) +``` + +Return a hash value for a string. This is computed deterministically using the same algorithm as Java's `String.hashCode()`, namely: + +``` python +s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1] +``` + +Hashing of values besides strings is not currently supported. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="hash.value"><code>value</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +String value to hash.</td> +</tr> +</tbody> +</table> + +## int + +``` rule-signature +int int(x, base=unbound) +``` + +Returns x as an int value. + +- If `x` is already an int, `int` returns it unchanged. +- If `x` is a bool, `int` returns 1 for True and 0 for False. +- If `x` is a string, it must have the format `<sign><prefix><digits>`. `<sign>` is either `"+"`, `"-"`, or empty (interpreted as positive). `<digits>` are a sequence of digits from 0 up to `base` - 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where `base` is 2/8/16, `<prefix>` is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the `base` is any other value besides these bases or the special value 0, the prefix must be empty. In the case where `base` is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If `base` is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type. +- If `x` is a float, `int` returns the integer value of the float, rounding towards zero. It is an error if x is non-finite (NaN or infinity). + +This function fails if `x` is any other type, or if the value is a string not satisfying the above format. Unlike Python's `int` function, this function does not allow zero arguments, and does not allow extraneous whitespace for string arguments. + +Examples: + +``` python +int("123") == 123 int("-123") == -123 int("+123") == 123 int("FF", 16) == 255 @@ -573,597 +467,530 @@ int("10", 0) == 10 int("-0x10", 0) == -16 int("-0x10", 0) == -16 int("123.456") == 123 -</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="int.x"> - <code>x</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/int.html">int</a>; or <a class="anchor" href="../core/float.html">float</a>; - required<br/> - The string to convert. - </td> - </tr> - <tr> - <td id="int.base"> - <code>base</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>unbound</code><br/> - The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if <code>x</code> were an integer literal. This parameter must not be supplied if the value is not a string. - </td> - </tr> - </tbody> - </table> - - <h2 id="len">len</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> len(x)</pre></p> - - Returns the length of a string, sequence (such as a list or tuple), dict, set, or other iterable. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="len.x"> - <code>x</code> - </td> - <td> - iterable; or <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The value whose length to report. - </td> - </tr> - </tbody> - </table> - - <h2 id="list">list</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> list(x=[])</pre></p> - - Returns a new list with the same elements as the given iterable value.<pre class="language-python">list([1, 2]) == [1, 2] +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="int.x"><code>x</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/int.html" class="anchor">int</a>; or <a href="../core/float.html" class="anchor">float</a>; +required<br /> +The string to convert.</td> +</tr> +<tr> +<td id="int.base"><code>base</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>unbound</code><br /> +The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if <code>x</code> were an integer literal. This parameter must not be supplied if the value is not a string.</td> +</tr> +</tbody> +</table> + +## len + +``` rule-signature +int len(x) +``` + +Returns the length of a string, sequence (such as a list or tuple), dict, set, or other iterable. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="len.x"><code>x</code></td> +<td>iterable; or <a href="../core/string.html" class="anchor">string</a>; +required<br /> +The value whose length to report.</td> +</tr> +</tbody> +</table> + +## list + +``` rule-signature +list list(x=[]) +``` + +Returns a new list with the same elements as the given iterable value. + +``` python +list([1, 2]) == [1, 2] list((2, 3, 2)) == [2, 3, 2] -list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4]</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="list.x"> - <code>x</code> - </td> - <td> - iterable; - default is <code>[]</code><br/> - The object to convert. - </td> - </tr> - </tbody> - </table> - - <h2 id="max">max</h2> - <p><pre class="rule-signature">unknown max(*args, key=None)</pre></p> - - Returns the largest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable.It is an error if elements are not comparable (for example int with string), or if no arguments are given.<pre class="language-python"> +list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4] +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="list.x"><code>x</code></td> +<td>iterable; +default is <code>[]</code><br /> +The object to convert.</td> +</tr> +</tbody> +</table> + +## max + +``` rule-signature +unknown max(*args, key=None) +``` + +Returns the largest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable.It is an error if elements are not comparable (for example int with string), or if no arguments are given. + +``` python + max(2, 5, 4) == 5 max([5, 6, 3]) == 6 max("two", "three", "four", key = len) =="three" # the longest max([1, -1, -2, 2], key = abs) == -2 # the first encountered with maximal key value -</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="max.key"> - <code>key</code> - </td> - <td> - callable; or <code>None</code>; - default is <code>None</code><br/> - An optional function applied to each element before comparison. - </td> - </tr> - <tr> - <td id="max.args"> - <code>args</code> - </td> - <td> - required<br/> - The elements to be checked. - </td> - </tr> - </tbody> - </table> - - <h2 id="min">min</h2> - <p><pre class="rule-signature">unknown min(*args, key=None)</pre></p> - - Returns the smallest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable. It is an error if elements are not comparable (for example int with string), or if no arguments are given.<pre class="language-python"> +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="max.key"><code>key</code></td> +<td>callable; or <code>None</code>; +default is <code>None</code><br /> +An optional function applied to each element before comparison.</td> +</tr> +<tr> +<td id="max.args"><code>args</code></td> +<td>required<br /> +The elements to be checked.</td> +</tr> +</tbody> +</table> + +## min + +``` rule-signature +unknown min(*args, key=None) +``` + +Returns the smallest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable. It is an error if elements are not comparable (for example int with string), or if no arguments are given. + +``` python + min(2, 5, 4) == 2 min([5, 6, 3]) == 3 min("six", "three", "four", key = len) == "six" # the shortest min([2, -2, -1, 1], key = abs) == -1 # the first encountered with minimal key value -</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="min.key"> - <code>key</code> - </td> - <td> - callable; or <code>None</code>; - default is <code>None</code><br/> - An optional function applied to each element before comparison. - </td> - </tr> - <tr> - <td id="min.args"> - <code>args</code> - </td> - <td> - required<br/> - The elements to be checked. - </td> - </tr> - </tbody> - </table> - - <h2 id="print">print</h2> - <p><pre class="rule-signature"><code>None</code> print(*args, sep=" ")</pre></p> - - Prints <code>args</code> as debug output. It will be prefixed with the string <code>"DEBUG"</code> and the location (file and line number) of this call. The exact way in which the arguments are converted to strings is unspecified and may change at any time. In particular, it may be different from (and more detailed than) the formatting done by <a href='#str'><code>str()</code></a> and <a href='#repr'><code>repr()</code></a>.<p>Using <code>print</code> in production code is discouraged due to the spam it creates for users. For deprecations, prefer a hard error using <a href="#fail"><code>fail()</code></a> whenever possible. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="print.sep"> - <code>sep</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>" "</code><br/> - The separator string between the objects, default is space (" "). - </td> - </tr> - <tr> - <td id="print.args"> - <code>args</code> - </td> - <td> - required<br/> - The objects to print. - </td> - </tr> - </tbody> - </table> - - <h2 id="range">range</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> range(start_or_stop, stop=unbound, step=1)</pre></p> - - Creates a list where items go from <code>start</code> to <code>stop</code>, using a <code>step</code> increment. If a single argument is provided, items will range from 0 to that element.<pre class="language-python">range(4) == [0, 1, 2, 3] +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="min.key"><code>key</code></td> +<td>callable; or <code>None</code>; +default is <code>None</code><br /> +An optional function applied to each element before comparison.</td> +</tr> +<tr> +<td id="min.args"><code>args</code></td> +<td>required<br /> +The elements to be checked.</td> +</tr> +</tbody> +</table> + +## print + +``` rule-signature +None print(*args, sep=" ") +``` + +Prints `args` as debug output. It will be prefixed with the string `"DEBUG"` and the location (file and line number) of this call. The exact way in which the arguments are converted to strings is unspecified and may change at any time. In particular, it may be different from (and more detailed than) the formatting done by [`str()`](#str) and [`repr()`](#repr). + +Using `print` in production code is discouraged due to the spam it creates for users. For deprecations, prefer a hard error using [`fail()`](#fail) whenever possible. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="print.sep"><code>sep</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>" "</code><br /> +The separator string between the objects, default is space (" ").</td> +</tr> +<tr> +<td id="print.args"><code>args</code></td> +<td>required<br /> +The objects to print.</td> +</tr> +</tbody> +</table> + +## range + +``` rule-signature +sequence range(start_or_stop, stop=unbound, step=1) +``` + +Creates a list where items go from `start` to `stop`, using a `step` increment. If a single argument is provided, items will range from 0 to that element. + +``` python +range(4) == [0, 1, 2, 3] range(3, 9, 2) == [3, 5, 7] -range(3, 0, -1) == [3, 2, 1]</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="range.start_or_stop"> - <code>start_or_stop</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - required<br/> - Value of the start element if stop is provided, otherwise value of stop and the actual start is 0 - </td> - </tr> - <tr> - <td id="range.stop"> - <code>stop</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>unbound</code><br/> - optional index of the first item <i>not</i> to be included in the resulting list; generation of the list stops before <code>stop</code> is reached. - </td> - </tr> - <tr> - <td id="range.step"> - <code>step</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>1</code><br/> - The increment (default is 1). It may be negative. - </td> - </tr> - </tbody> - </table> - - <h2 id="repr">repr</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repr(x)</pre></p> - - Converts any object to a string representation. This is useful for debugging.<br><pre class="language-python">repr("ab") == '"ab"'</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="repr.x"> - <code>x</code> - </td> - <td> - required<br/> - The object to convert. - </td> - </tr> - </tbody> - </table> - - <h2 id="reversed">reversed</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> reversed(sequence)</pre></p> - - Returns a new, unfrozen list that contains the elements of the original iterable sequence in reversed order.<pre class="language-python">reversed([3, 5, 4]) == [4, 5, 3]</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="reversed.sequence"> - <code>sequence</code> - </td> - <td> - iterable; - required<br/> - The iterable sequence (e.g. list) to be reversed. - </td> - </tr> - </tbody> - </table> - - <h2 id="set">set</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/set.html">set</a> set(elements=[])</pre></p> - - Creates a new <a href="../core/set.html">set</a> containing the unique elements of a given +range(3, 0, -1) == [3, 2, 1] +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="range.start_or_stop"><code>start_or_stop</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +required<br /> +Value of the start element if stop is provided, otherwise value of stop and the actual start is 0</td> +</tr> +<tr> +<td id="range.stop"><code>stop</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>unbound</code><br /> +optional index of the first item <em>not</em> to be included in the resulting list; generation of the list stops before <code>stop</code> is reached.</td> +</tr> +<tr> +<td id="range.step"><code>step</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>1</code><br /> +The increment (default is 1). It may be negative.</td> +</tr> +</tbody> +</table> + +## repr + +``` rule-signature +string repr(x) +``` + +Converts any object to a string representation. This is useful for debugging. + +``` python +repr("ab") == '"ab"' +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="repr.x"><code>x</code></td> +<td>required<br /> +The object to convert.</td> +</tr> +</tbody> +</table> + +## reversed + +``` rule-signature +list reversed(sequence) +``` + +Returns a new, unfrozen list that contains the elements of the original iterable sequence in reversed order. + +``` python +reversed([3, 5, 4]) == [4, 5, 3] +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="reversed.sequence"><code>sequence</code></td> +<td>iterable; +required<br /> +The iterable sequence (e.g. list) to be reversed.</td> +</tr> +</tbody> +</table> + +## set + +``` rule-signature +set set(elements=[]) +``` + +Creates a new [set](../core/set.html) containing the unique elements of a given iterable, preserving iteration order. -<p>If called with no argument, <code>set()</code> returns a new empty set. +If called with no argument, `set()` returns a new empty set. + +For example, + +``` python -<p>For example, -<pre class=language-python> set() # an empty set set([3, 1, 1, 2]) # set([3, 1, 2]), a set of three elements set({"k1": "v1", "k2": "v2"}) # set(["k1", "k2"]), a set of two elements -</pre> - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="set.elements"> - <code>elements</code> - </td> - <td> - iterable; - default is <code>[]</code><br/> - An iterable of hashable values. - </td> - </tr> - </tbody> - </table> - - <h2 id="sorted">sorted</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> sorted(iterable, key=None, *, reverse=False)</pre></p> - - Returns a new sorted list containing all the elements of the supplied iterable sequence. An error may occur if any pair of elements x, y may not be compared using x < y. The elements are sorted into ascending order, unless the reverse argument is True, in which case the order is descending. - Sorting is stable: elements that compare equal retain their original relative order. -<pre class="language-python"> +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="set.elements"><code>elements</code></td> +<td>iterable; +default is <code>[]</code><br /> +An iterable of hashable values.</td> +</tr> +</tbody> +</table> + +## sorted + +``` rule-signature +list sorted(iterable, key=None, *, reverse=False) +``` + +Returns a new sorted list containing all the elements of the supplied iterable sequence. An error may occur if any pair of elements x, y may not be compared using x \< y. The elements are sorted into ascending order, unless the reverse argument is True, in which case the order is descending. +Sorting is stable: elements that compare equal retain their original relative order. + +``` python + sorted([3, 5, 4]) == [3, 4, 5] sorted([3, 5, 4], reverse = True) == [5, 4, 3] sorted(["two", "three", "four"], key = len) == ["two", "four", "three"] # sort by length -</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="sorted.iterable"> - <code>iterable</code> - </td> - <td> - iterable; - required<br/> - The iterable sequence to sort. - </td> - </tr> - <tr> - <td id="sorted.key"> - <code>key</code> - </td> - <td> - callable; or <code>None</code>; - default is <code>None</code><br/> - An optional function applied to each element before comparison. - </td> - </tr> - <tr> - <td id="sorted.reverse"> - <code>reverse</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Return results in descending order. - </td> - </tr> - </tbody> - </table> - - <h2 id="str">str</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> str(x)</pre></p> - - Converts any object to string. This is useful for debugging.<pre class="language-python">str("ab") == "ab" -str(8) == "8"</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="str.x"> - <code>x</code> - </td> - <td> - required<br/> - The object to convert. - </td> - </tr> - </tbody> - </table> - - <h2 id="tuple">tuple</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> tuple(x=())</pre></p> - - Returns a tuple with the same elements as the given iterable value.<pre class="language-python">tuple([1, 2]) == (1, 2) +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="sorted.iterable"><code>iterable</code></td> +<td>iterable; +required<br /> +The iterable sequence to sort.</td> +</tr> +<tr> +<td id="sorted.key"><code>key</code></td> +<td>callable; or <code>None</code>; +default is <code>None</code><br /> +An optional function applied to each element before comparison.</td> +</tr> +<tr> +<td id="sorted.reverse"><code>reverse</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Return results in descending order.</td> +</tr> +</tbody> +</table> + +## str + +``` rule-signature +string str(x) +``` + +Converts any object to string. This is useful for debugging. + +``` python +str("ab") == "ab" +str(8) == "8" +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="str.x"><code>x</code></td> +<td>required<br /> +The object to convert.</td> +</tr> +</tbody> +</table> + +## tuple + +``` rule-signature +tuple tuple(x=()) +``` + +Returns a tuple with the same elements as the given iterable value. + +``` python +tuple([1, 2]) == (1, 2) tuple((2, 3, 2)) == (2, 3, 2) -tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4)</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="tuple.x"> - <code>x</code> - </td> - <td> - iterable; - default is <code>()</code><br/> - The object to convert. - </td> - </tr> - </tbody> - </table> - - <h2 id="type">type</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> type(x)</pre></p> - - Returns the type name of its argument. This is useful for debugging and type-checking. Examples:<pre class="language-python">type(2) == "int" +tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4) +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="tuple.x"><code>x</code></td> +<td>iterable; +default is <code>()</code><br /> +The object to convert.</td> +</tr> +</tbody> +</table> + +## type + +``` rule-signature +string type(x) +``` + +Returns the type name of its argument. This is useful for debugging and type-checking. Examples: + +``` python +type(2) == "int" type([1]) == "list" -type(struct(a = 2)) == "struct"</pre>This function might change in the future. To write Python-compatible code and be future-proof, use it only to compare return values: <pre class="language-python">if type(x) == type([]): # if x is a list</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="type.x"> - <code>x</code> - </td> - <td> - required<br/> - The object to check type of. - </td> - </tr> - </tbody> - </table> - - <h2 id="zip">zip</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> zip(*args)</pre></p> - - Returns a <code>list</code> of <code>tuple</code>s, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The list has the size of the shortest input. With a single iterable argument, it returns a list of 1-tuples. With no arguments, it returns an empty list. Examples:<pre class="language-python">zip() # == [] +type(struct(a = 2)) == "struct" +``` + +This function might change in the future. To write Python-compatible code and be future-proof, use it only to compare return values: + +``` python +if type(x) == type([]): # if x is a list +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="type.x"><code>x</code></td> +<td>required<br /> +The object to check type of.</td> +</tr> +</tbody> +</table> + +## zip + +``` rule-signature +list zip(*args) +``` + +Returns a `list` of `tuple`s, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The list has the size of the shortest input. With a single iterable argument, it returns a list of 1-tuples. With no arguments, it returns an empty list. Examples: + +``` python +zip() # == [] zip([1, 2]) # == [(1,), (2,)] zip([1, 2], [3, 4]) # == [(1, 3), (2, 4)] -zip([1, 2], [3, 4, 5]) # == [(1, 3), (2, 4)]</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="zip.args"> - <code>args</code> - </td> - <td> - required<br/> - lists to zip. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +zip([1, 2], [3, 4, 5]) # == [(1, 3), (2, 4)] +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="zip.args"><code>args</code></td> +<td>required<br /> +lists to zip.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/globals/build.mdx b/rules/lib/globals/build.mdx index 42eeec9..74130b3 100644 --- a/rules/lib/globals/build.mdx +++ b/rules/lib/globals/build.mdx @@ -2,525 +2,438 @@ title: 'build' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.build">BUILD files</h1> +# BUILD files {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Methods available in BUILD files. See also the Build Encyclopedia for extra <a href="/reference/be/functions">functions</a> and build rules, which can also be used in BUILD files. - -<h2>Members</h2> -<ul> - <li> - <a href="#depset">depset</a> - </li> - <li> - <a href="#existing_rule">existing_rule</a> - </li> - <li> - <a href="#existing_rules">existing_rules</a> - </li> - <li> - <a href="#exports_files">exports_files</a> - </li> - <li> - <a href="#glob">glob</a> - </li> - <li> - <a href="#module_name">module_name</a> - </li> - <li> - <a href="#module_version">module_version</a> - </li> - <li> - <a href="#package">package</a> - </li> - <li> - <a href="#package_default_visibility">package_default_visibility</a> - </li> - <li> - <a href="#package_group">package_group</a> - </li> - <li> - <a href="#package_name">package_name</a> - </li> - <li> - <a href="#package_relative_label">package_relative_label</a> - </li> - <li> - <a href="#repo_name">repo_name</a> - </li> - <li> - <a href="#repository_name">repository_name</a> - </li> - <li> - <a href="#select">select</a> - </li> - <li> - <a href="#subpackages">subpackages</a> - </li> - </ul> - - <h2 id="depset">depset</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> depset(direct=None, order="default", *, transitive=None)</pre></p> - - Creates a <a href="../builtins/depset.html">depset</a>. The <code>direct</code> parameter is a list of direct elements of the depset, and <code>transitive</code> parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the <code>order</code> parameter. See the <a href="https://bazel.build/extending/depsets">Depsets overview</a> for more information. -<p>All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression <a href="../globals/all#type"><code>type(x)</code></a>. -<p>Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see <a href='https://github.com/bazelbuild/bazel/issues/10313'>Issue 10313</a>. -<p>In addition, elements must currently be immutable, though this restriction will be relaxed in future. -<p> The order of the created depset should be <i>compatible</i> with the order of its <code>transitive</code> depsets. <code>"default"</code> order is compatible with any other order, all other orders are only compatible with themselves. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="depset.direct"> - <code>direct</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; - default is <code>None</code><br/> - A list of <i>direct</i> elements of a depset. - </td> - </tr> - <tr> - <td id="depset.order"> - <code>order</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>"default"</code><br/> - The traversal strategy for the new depset. See <a href="../builtins/depset.html">here</a> for the possible values. - </td> - </tr> - <tr> - <td id="depset.transitive"> - <code>transitive</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/depset.html">depset</a>s; or <code>None</code>; - default is <code>None</code><br/> - A list of depsets whose elements will become indirect elements of the depset. - </td> - </tr> - </tbody> - </table> - - <h2 id="existing_rule">existing_rule</h2> - <p><pre class="rule-signature">unknown existing_rule(name)</pre></p> - - Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or <code>None</code> if no rule instance of that name exists.<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>, <code>x.keys()</code>, and <code>x.values()</code>.<p>The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's <code>name</code> and <code>kind</code> (for example, <code>'cc_binary'</code>).<p>The values of the result represent attribute values as follows:<ul><li>Attributes of type str, int, and bool are represented as is.</li><li>Labels are converted to strings of the form <code>':foo'</code> for targets in the same package or <code>'//pkg:name'</code> for targets in a different package.</li><li>Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion.</li><li><code>select</code> values are returned with their contents transformed as described above.</li><li>Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.).</li></ul><p>If possible, use this function only in <a href="https://bazel.build/extending/macros#finalizers">implementation functions of rule finalizer symbolic macros</a>. Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes <code>BUILD</code> files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by <code>ctx.attr.foo</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="existing_rule.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the target. - </td> - </tr> - </tbody> - </table> - - <h2 id="existing_rules">existing_rules</h2> - <p><pre class="rule-signature">unknown existing_rules()</pre></p> - - Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by <code>existing_rule(name)</code>.<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>, <code>x.keys()</code>, and <code>x.values()</code>.<p>If possible, use this function only in <a href="https://bazel.build/extending/macros#finalizers">implementation functions of rule finalizer symbolic macros</a>. Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes <code>BUILD</code> files brittle and order-dependent. - - <h2 id="exports_files">exports_files</h2> - <p><pre class="rule-signature"><code>None</code> exports_files(srcs, visibility=None, licenses=None)</pre></p> - - Specifies a list of files belonging to this package that are exported to other packages. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="exports_files.srcs"> - <code>srcs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The list of files to export. - </td> - </tr> - <tr> - <td id="exports_files.visibility"> - <code>visibility</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; - default is <code>None</code><br/> - A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. - </td> - </tr> - <tr> - <td id="exports_files.licenses"> - <code>licenses</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Licenses to be specified. - </td> - </tr> - </tbody> - </table> - - <h2 id="glob">glob</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)</pre></p> - - Glob returns a new, mutable, sorted list of every file in the current package that:<ul> -<li>Matches at least one pattern in <code>include</code>.</li> -<li>Does not match any of the patterns in <code>exclude</code> (default <code>[]</code>).</li></ul> -If the <code>exclude_directories</code> argument is enabled (set to <code>1</code>), files of type directory will be omitted from the results (default <code>1</code>). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="glob.include"> - <code>include</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - The list of glob patterns to include. - </td> - </tr> - <tr> - <td id="glob.exclude"> - <code>exclude</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - The list of glob patterns to exclude. - </td> - </tr> - <tr> - <td id="glob.exclude_directories"> - <code>exclude_directories</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>1</code><br/> - A flag whether to exclude directories or not. - </td> - </tr> - <tr> - <td id="glob.allow_empty"> - <code>allow_empty</code> - </td> - <td> - default is <code>unbound</code><br/> - Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). - </td> - </tr> - </tbody> - </table> - - <h2 id="module_name">module_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> module_name()</pre></p> - - The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the <code>module.name</code> field seen in <code>module_ctx.modules</code>. - May return <code>None</code>. - - <h2 id="module_version">module_version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> module_version()</pre></p> - - The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the <code>module.version</code> field seen in <code>module_ctx.modules</code>. - May return <code>None</code>. - - <h2 id="package">package</h2> - <p><pre class="rule-signature">unknown package(**kwargs)</pre></p> - - Declares metadata that applies to every rule in the package. It must be called at most once within a package (BUILD file). If called, it should be the first call in the BUILD file, right after the <code>load()</code> statements. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="package.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - See the <a href="/reference/be/functions#package"><code>package()</code></a> function in the Build Encyclopedia for applicable arguments. - </td> - </tr> - </tbody> - </table> - - <h2 id="package_default_visibility">package_default_visibility</h2> - <p><pre class="rule-signature">List package_default_visibility()</pre></p> - - Returns the default visibility of the package being evaluated. This is the value of the <code>default_visibility</code> parameter of <code>package()</code>, extended to include the package itself. - - <h2 id="package_group">package_group</h2> - <p><pre class="rule-signature"><code>None</code> package_group(*, name, packages=[], includes=[])</pre></p> - - This function defines a set of packages and assigns a label to the group. The label can be referenced in <code>visibility</code> attributes. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="package_group.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The unique name for this rule. - </td> - </tr> - <tr> - <td id="package_group.packages"> - <code>packages</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A complete enumeration of packages in this group. - </td> - </tr> - <tr> - <td id="package_group.includes"> - <code>includes</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Other package groups that are included in this one. - </td> - </tr> - </tbody> - </table> - - <h2 id="package_name">package_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> package_name()</pre></p> - - The name of the package being evaluated, without the repository name. For example, in the BUILD file <code>some/package/BUILD</code>, its value will be <code>some/package</code>. If the BUILD file calls a function defined in a .bzl file, <code>package_name()</code> will match the caller BUILD file package. The value will always be an empty string for the root package. - - <h2 id="package_relative_label">package_relative_label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> package_relative_label(input)</pre></p> - - Converts the input string into a <a href='../builtins/Label.html'>Label</a> object, in the context of the package currently being initialized (that is, the <code>BUILD</code> file for which the current macro is executing). If the input is already a <code>Label</code>, it is returned unchanged.<p>This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. <p>The result of this function is the same <code>Label</code> value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file. <p><i>Usage note:</i> The difference between this function and <a href='../builtins/Label.html#Label'>Label()</a></code> is that <code>Label()</code> uses the context of the package of the <code>.bzl</code> file that called it, not the package of the <code>BUILD</code> file. Use <code>Label()</code> when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use <code>package_relative_label()</code> when you need to normalize a label string supplied by the BUILD file to a <code>Label</code> object. (There is no way to convert a string to a <code>Label</code> in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="package_relative_label.input"> - <code>input</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; - required<br/> - The input label string or Label object. If a Label object is passed, it's returned as is. - </td> - </tr> - </tbody> - </table> - - <h2 id="repo_name">repo_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repo_name()</pre></p> - - The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. - - <h2 id="repository_name">repository_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> repository_name()</pre></p> - - <b>Experimental</b>. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--+incompatible_enable_deprecated_label_apis</code> <br><strong>Deprecated.</strong> Prefer to use <a href="#repo_name"><code>repo_name</code></a> instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise.<p>The canonical name of the repository containing the package currently being evaluated, with a single at-sign (<code>@</code>) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza <code>local_repository(name='local', path=...)</code> it will be set to <code>@local</code>. In packages in the main repository, it will be set to <code>@</code>. - - <h2 id="select">select</h2> - <p><pre class="rule-signature">unknown select(x, no_match_error='')</pre></p> - - <code>select()</code> is the helper function that makes a rule attribute <a href="/reference/be/common-definitions#configurable-attributes">configurable</a>. See <a href="/reference/be/functions#select">build encyclopedia</a> for details. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="select.x"> - <code>x</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - required<br/> - A dict that maps configuration conditions to values. Each key is a <a href="../builtins/Label.html">Label</a> or a label string that identifies a config_setting or constraint_value instance. See the <a href="https://bazel.build/extending/legacy-macros#label-resolution">documentation on macros</a> for when to use a Label instead of a string. If <code>--incompatible_resolve_select_keys_eagerly</code> is enabled, the keys are resolved to <code>Label</code> objects relative to the package of the file that contains this call to <code>select</code>. - </td> - </tr> - <tr> - <td id="select.no_match_error"> - <code>no_match_error</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Optional custom error to report if no condition matches. - </td> - </tr> - </tbody> - </table> - - <h2 id="subpackages">subpackages</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> subpackages(*, include, exclude=[], allow_empty=False)</pre></p> - - Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel_skylib.subpackages module rather than calling this function directly. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="subpackages.include"> - <code>include</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The list of glob patterns to include in subpackages scan. - </td> - </tr> - <tr> - <td id="subpackages.exclude"> - <code>exclude</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - The list of glob patterns to exclude from subpackages scan. - </td> - </tr> - <tr> - <td id="subpackages.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +Methods available in BUILD files. See also the Build Encyclopedia for extra [functions](/reference/be/functions) and build rules, which can also be used in BUILD files. + +## Members + +- [depset](#depset) +- [existing_rule](#existing_rule) +- [existing_rules](#existing_rules) +- [exports_files](#exports_files) +- [glob](#glob) +- [module_name](#module_name) +- [module_version](#module_version) +- [package](#package) +- [package_default_visibility](#package_default_visibility) +- [package_group](#package_group) +- [package_name](#package_name) +- [package_relative_label](#package_relative_label) +- [repo_name](#repo_name) +- [repository_name](#repository_name) +- [select](#select) +- [subpackages](#subpackages) + +## depset + +``` rule-signature +depset depset(direct=None, order="default", *, transitive=None) +``` + +Creates a [depset](../builtins/depset.html). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. + +All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression [`type(x)`](../globals/all#type). + +Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see [Issue 10313](https://github.com/bazelbuild/bazel/issues/10313). + +In addition, elements must currently be immutable, though this restriction will be relaxed in future. + +The order of the created depset should be *compatible* with the order of its `transitive` depsets. `"default"` order is compatible with any other order, all other orders are only compatible with themselves. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="depset.direct"><code>direct</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; +default is <code>None</code><br /> +A list of <em>direct</em> elements of a depset.</td> +</tr> +<tr> +<td id="depset.order"><code>order</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>"default"</code><br /> +The traversal strategy for the new depset. See <a href="../builtins/depset.html">here</a> for the possible values.</td> +</tr> +<tr> +<td id="depset.transitive"><code>transitive</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/depset.html" class="anchor">depset</a>s; or <code>None</code>; +default is <code>None</code><br /> +A list of depsets whose elements will become indirect elements of the depset.</td> +</tr> +</tbody> +</table> + +## existing_rule + +``` rule-signature +unknown existing_rule(name) +``` + +Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or `None` if no rule instance of that name exists. + +Here, an *immutable dict-like object* means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. + +The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's `name` and `kind` (for example, `'cc_binary'`). + +The values of the result represent attribute values as follows: + +- Attributes of type str, int, and bool are represented as is. +- Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. +- Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. +- `select` values are returned with their contents transformed as described above. +- Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). + +If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by `ctx.attr.foo`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="existing_rule.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the target.</td> +</tr> +</tbody> +</table> + +## existing_rules + +``` rule-signature +unknown existing_rules() +``` + +Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by `existing_rule(name)`. + +Here, an *immutable dict-like object* means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. + +If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. + +## exports_files + +``` rule-signature +None exports_files(srcs, visibility=None, licenses=None) +``` + +Specifies a list of files belonging to this package that are exported to other packages. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="exports_files.srcs"><code>srcs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The list of files to export.</td> +</tr> +<tr> +<td id="exports_files.visibility"><code>visibility</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; +default is <code>None</code><br /> +A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package.</td> +</tr> +<tr> +<td id="exports_files.licenses"><code>licenses</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Licenses to be specified.</td> +</tr> +</tbody> +</table> + +## glob + +``` rule-signature +sequence glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound) +``` + +Glob returns a new, mutable, sorted list of every file in the current package that: + +- Matches at least one pattern in `include`. +- Does not match any of the patterns in `exclude` (default `[]`). + +If the `exclude_directories` argument is enabled (set to `1`), files of type directory will be omitted from the results (default `1`). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="glob.include"><code>include</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +The list of glob patterns to include.</td> +</tr> +<tr> +<td id="glob.exclude"><code>exclude</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +The list of glob patterns to exclude.</td> +</tr> +<tr> +<td id="glob.exclude_directories"><code>exclude_directories</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>1</code><br /> +A flag whether to exclude directories or not.</td> +</tr> +<tr> +<td id="glob.allow_empty"><code>allow_empty</code></td> +<td>default is <code>unbound</code><br /> +Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded).</td> +</tr> +</tbody> +</table> + +## module_name + +``` rule-signature +string module_name() +``` + +The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the `module.name` field seen in `module_ctx.modules`. +May return `None`. + +## module_version + +``` rule-signature +string module_version() +``` + +The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the `module.version` field seen in `module_ctx.modules`. +May return `None`. + +## package + +``` rule-signature +unknown package(**kwargs) +``` + +Declares metadata that applies to every rule in the package. It must be called at most once within a package (BUILD file). If called, it should be the first call in the BUILD file, right after the `load()` statements. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="package.kwargs"><code>kwargs</code></td> +<td>required<br /> +See the <a href="/reference/be/functions#package"><code>package()</code></a> function in the Build Encyclopedia for applicable arguments.</td> +</tr> +</tbody> +</table> + +## package_default_visibility + +``` rule-signature +List package_default_visibility() +``` + +Returns the default visibility of the package being evaluated. This is the value of the `default_visibility` parameter of `package()`, extended to include the package itself. + +## package_group + +``` rule-signature +None package_group(*, name, packages=[], includes=[]) +``` + +This function defines a set of packages and assigns a label to the group. The label can be referenced in `visibility` attributes. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="package_group.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The unique name for this rule.</td> +</tr> +<tr> +<td id="package_group.packages"><code>packages</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A complete enumeration of packages in this group.</td> +</tr> +<tr> +<td id="package_group.includes"><code>includes</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Other package groups that are included in this one.</td> +</tr> +</tbody> +</table> + +## package_name + +``` rule-signature +string package_name() +``` + +The name of the package being evaluated, without the repository name. For example, in the BUILD file `some/package/BUILD`, its value will be `some/package`. If the BUILD file calls a function defined in a .bzl file, `package_name()` will match the caller BUILD file package. The value will always be an empty string for the root package. + +## package_relative_label + +``` rule-signature +Label package_relative_label(input) +``` + +Converts the input string into a [Label](../builtins/Label.html) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. + +This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. + +The result of this function is the same `Label` value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file. + +*Usage note:* The difference between this function and [Label()](../builtins/Label.html#Label) is that `Label()` uses the context of the package of the `.bzl` file that called it, not the package of the `BUILD` file. Use `Label()` when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use `package_relative_label()` when you need to normalize a label string supplied by the BUILD file to a `Label` object. (There is no way to convert a string to a `Label` in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="package_relative_label.input"><code>input</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; +required<br /> +The input label string or Label object. If a Label object is passed, it's returned as is.</td> +</tr> +</tbody> +</table> + +## repo_name + +``` rule-signature +string repo_name() +``` + +The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. + +## repository_name + +``` rule-signature +string repository_name() +``` + +**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` +**Deprecated.** Prefer to use [`repo_name`](#repo_name) instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise. + +The canonical name of the repository containing the package currently being evaluated, with a single at-sign (`@`) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza `local_repository(name='local', path=...)` it will be set to `@local`. In packages in the main repository, it will be set to `@`. + +## select + +``` rule-signature +unknown select(x, no_match_error='') +``` + +`select()` is the helper function that makes a rule attribute [configurable](/reference/be/common-definitions#configurable-attributes). See [build encyclopedia](/reference/be/functions#select) for details. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="select.x"><code>x</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +required<br /> +A dict that maps configuration conditions to values. Each key is a <a href="../builtins/Label.html">Label</a> or a label string that identifies a config_setting or constraint_value instance. See the <a href="https://bazel.build/extending/legacy-macros#label-resolution">documentation on macros</a> for when to use a Label instead of a string. If <code>--incompatible_resolve_select_keys_eagerly</code> is enabled, the keys are resolved to <code>Label</code> objects relative to the package of the file that contains this call to <code>select</code>.</td> +</tr> +<tr> +<td id="select.no_match_error"><code>no_match_error</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Optional custom error to report if no condition matches.</td> +</tr> +</tbody> +</table> + +## subpackages + +``` rule-signature +sequence subpackages(*, include, exclude=[], allow_empty=False) +``` + +Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel_skylib.subpackages module rather than calling this function directly. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="subpackages.include"><code>include</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The list of glob patterns to include in subpackages scan.</td> +</tr> +<tr> +<td id="subpackages.exclude"><code>exclude</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +The list of glob patterns to exclude from subpackages scan.</td> +</tr> +<tr> +<td id="subpackages.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/globals/bzl.mdx b/rules/lib/globals/bzl.mdx index d8f6105..9ad26a5 100644 --- a/rules/lib/globals/bzl.mdx +++ b/rules/lib/globals/bzl.mdx @@ -2,1445 +2,1145 @@ title: 'bzl' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.bzl">.bzl files</h1> +# .bzl files {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Global methods available in all .bzl files. -<h2>Members</h2> -<ul> - <li> - <a href="#analysis_test_transition">analysis_test_transition</a> - </li> - <li> - <a href="#aspect">aspect</a> - </li> - <li> - <a href="#configuration_field">configuration_field</a> - </li> - <li> - <a href="#depset">depset</a> - </li> - <li> - <a href="#exec_group">exec_group</a> - </li> - <li> - <a href="#exec_transition">exec_transition</a> - </li> - <li> - <a href="#macro">macro</a> - </li> - <li> - <a href="#materializer_rule">materializer_rule</a> - </li> - <li> - <a href="#module_extension">module_extension</a> - </li> - <li> - <a href="#provider">provider</a> - </li> - <li> - <a href="#repository_rule">repository_rule</a> - </li> - <li> - <a href="#rule">rule</a> - </li> - <li> - <a href="#select">select</a> - </li> - <li> - <a href="#subrule">subrule</a> - </li> - <li> - <a href="#tag_class">tag_class</a> - </li> - <li> - <a href="#visibility">visibility</a> - </li> - </ul> - - <h2 id="analysis_test_transition">analysis_test_transition</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> analysis_test_transition(*, settings)</pre></p> - - <p> Creates a configuration transition to be applied on an analysis-test rule's dependencies. This transition may only be applied on attributes of rules with <code>analysis_test = True</code>. Such rules are restricted in capabilities (for example, the size of their dependency tree is limited), so transitions created using this function are limited in potential scope as compared to transitions created using <a href="../builtins/transition.html"><code>transition()</code></a>. <p>This function is primarily designed to facilitate the <a href="https://bazel.build/rules/testing">Analysis Test Framework</a> core library. See its documentation (or its implementation) for best practices. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="analysis_test_transition.settings"> - <code>settings</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - required<br/> - A dictionary containing information about configuration settings which should be set by this configuration transition. Keys are build setting labels and values are their new post-transition values. All other settings are unchanged. Use this to declare specific configuration settings that an analysis test requires to be set in order to pass. - </td> - </tr> - </tbody> - </table> - - <h2 id="aspect">aspect</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Aspect.html">Aspect</a> aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], propagation_predicate=None, fragments=[], host_fragments=[], toolchains=[], doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])</pre></p> - - Creates a new aspect. The result of this function must be stored in a global value. Please see the <a href="https://bazel.build/extending/aspects">introduction to Aspects</a> for more details. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="aspect.implementation"> - <code>implementation</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - required<br/> - A Starlark function that implements this aspect, with exactly two parameters: <a href="../builtins/Target.html">Target</a> (the target to which the aspect is applied) and <a href="../builtins/ctx.html">ctx</a> (the rule context which the target is created from). Attributes of the target are available via the <code>ctx.rule</code> field. This function is evaluated during the analysis phase for each application of an aspect to a target. - </td> - </tr> - <tr> - <td id="aspect.attr_aspects"> - <code>attr_aspects</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/function.html">function</a>; - default is <code>[]</code><br/> - Accepts a list of attribute names or [Experimental] a function that returns the list of attribute names. The aspect propagates along dependencies specified in the attributes of a target with these names. Common values here include <code>deps</code> and <code>exports</code>. The list can also contain a single string <code>"*"</code> to propagate along all dependencies of a target. - </td> - </tr> - <tr> - <td id="aspect.toolchains_aspects"> - <code>toolchains_aspects</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../core/function.html">function</a>; - default is <code>[]</code><br/> - Accepts a list of toolchain types or [Experimental] a function that returns the list of toolchain types. The aspect propagates to target toolchains which match these toolchain types. - </td> - </tr> - <tr> - <td id="aspect.attrs"> - <code>attrs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary declaring all the attributes of the aspect. It maps from an attribute name to an attribute object, like <code>attr.label</code> or <code>attr.string</code> (see <a href="../toplevel/attr.html"><code>attr</code></a> module). Aspect attributes are available to implementation function as fields of <code>ctx</code> parameter. <p>Implicit attributes starting with <code>_</code> must have default values, and have type <code>label</code> or <code>label_list</code>.</p> <p>Explicit attributes must have type <code>string</code>, and must use the <code>values</code> restriction. Explicit attributes restrict the aspect to only be used with rules that have attributes of the same name, type, and valid values according to the restriction.</p> -<p>Declared attributes will convert <code>None</code> to the default value.</p> - - </td> - </tr> - <tr> - <td id="aspect.required_providers"> - <code>required_providers</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its required providers. The value must be a list containing either individual providers or lists of providers but not both. For example, <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code> is a valid value while <code>[FooInfo, BarInfo, [BazInfo, QuxInfo]]</code> is not valid.<p>An unnested list of providers will automatically be converted to a list containing one list of providers. That is, <code>[FooInfo, BarInfo]</code> will automatically be converted to <code>[[FooInfo, BarInfo]]</code>.<p>To make some rule (e.g. <code>some_rule</code>) targets visible to an aspect, <code>some_rule</code> must advertise all providers from at least one of the required providers lists. For example, if the <code>required_providers</code> of an aspect are <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code>, this aspect can see <code>some_rule</code> targets if and only if <code>some_rule</code> provides <code>FooInfo</code>, <em>or</em> <code>BarInfo</code>, <em>or</em> both <code>BazInfo</code> <em>and</em> <code>QuxInfo</code>. - </td> - </tr> - <tr> - <td id="aspect.required_aspect_providers"> - <code>required_aspect_providers</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - This attribute allows this aspect to inspect other aspects. The value must be a list containing either individual providers or lists of providers but not both. For example, <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code> is a valid value while <code>[FooInfo, BarInfo, [BazInfo, QuxInfo]]</code> is not valid.<p>An unnested list of providers will automatically be converted to a list containing one list of providers. That is, <code>[FooInfo, BarInfo]</code> will automatically be converted to <code>[[FooInfo, BarInfo]]</code>. <p>To make another aspect (e.g. <code>other_aspect</code>) visible to this aspect, <code>other_aspect</code> must provide all providers from at least one of the lists. In the example of <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code>, this aspect can see <code>other_aspect</code> if and only if <code>other_aspect</code> provides <code>FooInfo</code>, <em>or</em> <code>BarInfo</code>, <em>or</em> both <code>BazInfo</code> <em>and</em> <code>QuxInfo</code>. - </td> - </tr> - <tr> - <td id="aspect.provides"> - <code>provides</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - A list of providers that the implementation function must return.<p>It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.<p>Each element of the list is an <code>*Info</code> object returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a>. When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The <a href='../globals/bzl.html#aspect.required_providers'><code>required_providers</code></a> field of an <a href='../globals/bzl.html#aspect'>aspect</a> does, however, require that providers are specified here. - </td> - </tr> - <tr> - <td id="aspect.requires"> - <code>requires</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; - default is <code>[]</code><br/> - List of aspects required to be propagated before this aspect. - </td> - </tr> - <tr> - <td id="aspect.propagation_predicate"> - <code>propagation_predicate</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; or <code>None</code>; - default is <code>None</code><br/> - Experimental: a function that returns a boolean value indicating whether the aspect should be propagated to a target. - </td> - </tr> - <tr> - <td id="aspect.fragments"> - <code>fragments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - List of names of configuration fragments that the aspect requires in target configuration. - </td> - </tr> - <tr> - <td id="aspect.host_fragments"> - <code>host_fragments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - List of names of configuration fragments that the aspect requires in host configuration. - </td> - </tr> - <tr> - <td id="aspect.toolchains"> - <code>toolchains</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - If set, the set of toolchains this aspect requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the aspect implementation via <code>ctx.toolchain</code>. - </td> - </tr> - <tr> - <td id="aspect.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the aspect that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="aspect.apply_to_generating_rules"> - <code>apply_to_generating_rules</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the aspect will, when applied to an output file, instead apply to the output file's generating rule. <p>For example, suppose an aspect propagates transitively through attribute `deps` and it is applied to target `alpha`. Suppose `alpha` has `deps = [':beta_output']`, where `beta_output` is a declared output of a target `beta`. Suppose `beta` has a target `charlie` as one of its `deps`. If `apply_to_generating_rules=True` for the aspect, then the aspect will propagate through `alpha`, `beta`, and `charlie`. If False, then the aspect will propagate only to `alpha`. </p><p>False by default.</p> - </td> - </tr> - <tr> - <td id="aspect.exec_compatible_with"> - <code>exec_compatible_with</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A list of constraints on the execution platform that apply to all instances of this aspect. - </td> - </tr> - <tr> - <td id="aspect.exec_groups"> - <code>exec_groups</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Dict of execution group name (string) to <a href='../globals/bzl.html#exec_group'><code>exec_group</code>s</a>. If set, allows aspects to run actions on multiple execution platforms within a single instance. See <a href='/reference/exec-groups'>execution groups documentation</a> for more info. - </td> - </tr> - <tr> - <td id="aspect.subrules"> - <code>subrules</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Subrule.html">Subrule</a>s; - default is <code>[]</code><br/> - Experimental: list of subrules used by this aspect. - </td> - </tr> - </tbody> - </table> - - <h2 id="configuration_field">configuration_field</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/LateBoundDefault.html">LateBoundDefault</a> configuration_field(fragment, name)</pre></p> - - References a late-bound default value for an attribute of type <a href="../toplevel/attr.html#label">label</a>. A value is 'late-bound' if it requires the configuration to be built before determining the value. Any attribute using this as a value must <a href="https://bazel.build/extending/rules#private-attributes">be private</a>. <p>Example usage: <p>Defining a rule attribute: <br><pre class=language-python>'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))</pre><p>Accessing in rule implementation: <br><pre class=language-python> def _rule_impl(ctx): +## Members + +- [analysis_test_transition](#analysis_test_transition) +- [aspect](#aspect) +- [configuration_field](#configuration_field) +- [depset](#depset) +- [exec_group](#exec_group) +- [exec_transition](#exec_transition) +- [macro](#macro) +- [materializer_rule](#materializer_rule) +- [module_extension](#module_extension) +- [provider](#provider) +- [repository_rule](#repository_rule) +- [rule](#rule) +- [select](#select) +- [subrule](#subrule) +- [tag_class](#tag_class) +- [visibility](#visibility) + +## analysis_test_transition + +``` rule-signature +transition analysis_test_transition(*, settings) +``` + +Creates a configuration transition to be applied on an analysis-test rule's dependencies. This transition may only be applied on attributes of rules with `analysis_test = True`. Such rules are restricted in capabilities (for example, the size of their dependency tree is limited), so transitions created using this function are limited in potential scope as compared to transitions created using [`transition()`](../builtins/transition.html). + +This function is primarily designed to facilitate the [Analysis Test Framework](https://bazel.build/rules/testing) core library. See its documentation (or its implementation) for best practices. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="analysis_test_transition.settings"><code>settings</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +required<br /> +A dictionary containing information about configuration settings which should be set by this configuration transition. Keys are build setting labels and values are their new post-transition values. All other settings are unchanged. Use this to declare specific configuration settings that an analysis test requires to be set in order to pass.</td> +</tr> +</tbody> +</table> + +## aspect + +``` rule-signature +Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], propagation_predicate=None, fragments=[], host_fragments=[], toolchains=[], doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[]) +``` + +Creates a new aspect. The result of this function must be stored in a global value. Please see the [introduction to Aspects](https://bazel.build/extending/aspects) for more details. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="aspect.implementation"><code>implementation</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +required<br /> +A Starlark function that implements this aspect, with exactly two parameters: <a href="../builtins/Target.html">Target</a> (the target to which the aspect is applied) and <a href="../builtins/ctx.html">ctx</a> (the rule context which the target is created from). Attributes of the target are available via the <code>ctx.rule</code> field. This function is evaluated during the analysis phase for each application of an aspect to a target.</td> +</tr> +<tr> +<td id="aspect.attr_aspects"><code>attr_aspects</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/function.html" class="anchor">function</a>; +default is <code>[]</code><br /> +Accepts a list of attribute names or [Experimental] a function that returns the list of attribute names. The aspect propagates along dependencies specified in the attributes of a target with these names. Common values here include <code>deps</code> and <code>exports</code>. The list can also contain a single string <code>"*"</code> to propagate along all dependencies of a target.</td> +</tr> +<tr> +<td id="aspect.toolchains_aspects"><code>toolchains_aspects</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../core/function.html" class="anchor">function</a>; +default is <code>[]</code><br /> +Accepts a list of toolchain types or [Experimental] a function that returns the list of toolchain types. The aspect propagates to target toolchains which match these toolchain types.</td> +</tr> +<tr> +<td id="aspect.attrs"><code>attrs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary declaring all the attributes of the aspect. It maps from an attribute name to an attribute object, like <code>attr.label</code> or <code>attr.string</code> (see <a href="../toplevel/attr.html"><code>attr</code></a> module). Aspect attributes are available to implementation function as fields of <code>ctx</code> parameter. +<p>Implicit attributes starting with <code>_</code> must have default values, and have type <code>label</code> or <code>label_list</code>.</p> +<p>Explicit attributes must have type <code>string</code>, and must use the <code>values</code> restriction. Explicit attributes restrict the aspect to only be used with rules that have attributes of the same name, type, and valid values according to the restriction.</p> +<p>Declared attributes will convert <code>None</code> to the default value.</p></td> +</tr> +<tr> +<td id="aspect.required_providers"><code>required_providers</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its required providers. The value must be a list containing either individual providers or lists of providers but not both. For example, <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code> is a valid value while <code>[FooInfo, BarInfo, [BazInfo, QuxInfo]]</code> is not valid. +<p>An unnested list of providers will automatically be converted to a list containing one list of providers. That is, <code>[FooInfo, BarInfo]</code> will automatically be converted to <code>[[FooInfo, BarInfo]]</code>.</p> +<p>To make some rule (e.g. <code>some_rule</code>) targets visible to an aspect, <code>some_rule</code> must advertise all providers from at least one of the required providers lists. For example, if the <code>required_providers</code> of an aspect are <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code>, this aspect can see <code>some_rule</code> targets if and only if <code>some_rule</code> provides <code>FooInfo</code>, <em>or</em> <code>BarInfo</code>, <em>or</em> both <code>BazInfo</code> <em>and</em> <code>QuxInfo</code>.</p></td> +</tr> +<tr> +<td id="aspect.required_aspect_providers"><code>required_aspect_providers</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +This attribute allows this aspect to inspect other aspects. The value must be a list containing either individual providers or lists of providers but not both. For example, <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code> is a valid value while <code>[FooInfo, BarInfo, [BazInfo, QuxInfo]]</code> is not valid. +<p>An unnested list of providers will automatically be converted to a list containing one list of providers. That is, <code>[FooInfo, BarInfo]</code> will automatically be converted to <code>[[FooInfo, BarInfo]]</code>.</p> +<p>To make another aspect (e.g. <code>other_aspect</code>) visible to this aspect, <code>other_aspect</code> must provide all providers from at least one of the lists. In the example of <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code>, this aspect can see <code>other_aspect</code> if and only if <code>other_aspect</code> provides <code>FooInfo</code>, <em>or</em> <code>BarInfo</code>, <em>or</em> both <code>BazInfo</code> <em>and</em> <code>QuxInfo</code>.</p></td> +</tr> +<tr> +<td id="aspect.provides"><code>provides</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +A list of providers that the implementation function must return. +<p>It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.</p> +<p>Each element of the list is an <code>*Info</code> object returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a>. When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The <a href="../globals/bzl.html#aspect.required_providers"><code>required_providers</code></a> field of an <a href="../globals/bzl.html#aspect">aspect</a> does, however, require that providers are specified here.</p></td> +</tr> +<tr> +<td id="aspect.requires"><code>requires</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; +default is <code>[]</code><br /> +List of aspects required to be propagated before this aspect.</td> +</tr> +<tr> +<td id="aspect.propagation_predicate"><code>propagation_predicate</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; or <code>None</code>; +default is <code>None</code><br /> +Experimental: a function that returns a boolean value indicating whether the aspect should be propagated to a target.</td> +</tr> +<tr> +<td id="aspect.fragments"><code>fragments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +List of names of configuration fragments that the aspect requires in target configuration.</td> +</tr> +<tr> +<td id="aspect.host_fragments"><code>host_fragments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +List of names of configuration fragments that the aspect requires in host configuration.</td> +</tr> +<tr> +<td id="aspect.toolchains"><code>toolchains</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +If set, the set of toolchains this aspect requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the aspect implementation via <code>ctx.toolchain</code>.</td> +</tr> +<tr> +<td id="aspect.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the aspect that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="aspect.apply_to_generating_rules"><code>apply_to_generating_rules</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the aspect will, when applied to an output file, instead apply to the output file's generating rule. +<p>For example, suppose an aspect propagates transitively through attribute `deps` and it is applied to target `alpha`. Suppose `alpha` has `deps = [':beta_output']`, where `beta_output` is a declared output of a target `beta`. Suppose `beta` has a target `charlie` as one of its `deps`. If `apply_to_generating_rules=True` for the aspect, then the aspect will propagate through `alpha`, `beta`, and `charlie`. If False, then the aspect will propagate only to `alpha`.</p> +<p>False by default.</p></td> +</tr> +<tr> +<td id="aspect.exec_compatible_with"><code>exec_compatible_with</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A list of constraints on the execution platform that apply to all instances of this aspect.</td> +</tr> +<tr> +<td id="aspect.exec_groups"><code>exec_groups</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Dict of execution group name (string) to <a href="../globals/bzl.html#exec_group"><code>exec_group</code>s</a>. If set, allows aspects to run actions on multiple execution platforms within a single instance. See <a href="/reference/exec-groups">execution groups documentation</a> for more info.</td> +</tr> +<tr> +<td id="aspect.subrules"><code>subrules</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Subrule.html" class="anchor">Subrule</a>s; +default is <code>[]</code><br /> +Experimental: list of subrules used by this aspect.</td> +</tr> +</tbody> +</table> + +## configuration_field + +``` rule-signature +LateBoundDefault configuration_field(fragment, name) +``` + +References a late-bound default value for an attribute of type [label](../toplevel/attr.html#label). A value is 'late-bound' if it requires the configuration to be built before determining the value. Any attribute using this as a value must [be private](https://bazel.build/extending/rules#private-attributes). + +Example usage: + +Defining a rule attribute: + +``` python +'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain')) +``` + +Accessing in rule implementation: + +``` python + def _rule_impl(ctx): foo_info = ctx.attr._foo - ...</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="configuration_field.fragment"> - <code>fragment</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of a configuration fragment which contains the late-bound value. - </td> - </tr> - <tr> - <td id="configuration_field.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the value to obtain from the configuration fragment. - </td> - </tr> - </tbody> - </table> - - <h2 id="depset">depset</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> depset(direct=None, order="default", *, transitive=None)</pre></p> - - Creates a <a href="../builtins/depset.html">depset</a>. The <code>direct</code> parameter is a list of direct elements of the depset, and <code>transitive</code> parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the <code>order</code> parameter. See the <a href="https://bazel.build/extending/depsets">Depsets overview</a> for more information. -<p>All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression <a href="../globals/all#type"><code>type(x)</code></a>. -<p>Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see <a href='https://github.com/bazelbuild/bazel/issues/10313'>Issue 10313</a>. -<p>In addition, elements must currently be immutable, though this restriction will be relaxed in future. -<p> The order of the created depset should be <i>compatible</i> with the order of its <code>transitive</code> depsets. <code>"default"</code> order is compatible with any other order, all other orders are only compatible with themselves. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="depset.direct"> - <code>direct</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; - default is <code>None</code><br/> - A list of <i>direct</i> elements of a depset. - </td> - </tr> - <tr> - <td id="depset.order"> - <code>order</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>"default"</code><br/> - The traversal strategy for the new depset. See <a href="../builtins/depset.html">here</a> for the possible values. - </td> - </tr> - <tr> - <td id="depset.transitive"> - <code>transitive</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/depset.html">depset</a>s; or <code>None</code>; - default is <code>None</code><br/> - A list of depsets whose elements will become indirect elements of the depset. - </td> - </tr> - </tbody> - </table> - - <h2 id="exec_group">exec_group</h2> - <p><pre class="rule-signature">exec_group exec_group(*, toolchains=[], exec_compatible_with=[])</pre></p> - - Creates an <a href='/reference/exec-groups'>execution group</a> which can be used to create actions for a specific execution platform during rule implementation. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="exec_group.toolchains"> - <code>toolchains</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - The set of toolchains this execution group requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. - </td> - </tr> - <tr> - <td id="exec_group.exec_compatible_with"> - <code>exec_compatible_with</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A list of constraints on the execution platform. - </td> - </tr> - </tbody> - </table> - - <h2 id="exec_transition">exec_transition</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> exec_transition(*, implementation, inputs, outputs)</pre></p> - - A specialized version of <a href="../builtins/transition.html"><code>transition()</code></a> used to define the exec transition. See its documentation (or its implementation) for best practices. Only usable from the Bazel builtins. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="exec_transition.implementation"> - <code>implementation</code> - </td> - <td> - callable; - required<br/> - - </td> - </tr> - <tr> - <td id="exec_transition.inputs"> - <code>inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - - </td> - </tr> - <tr> - <td id="exec_transition.outputs"> - <code>outputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - - </td> - </tr> - </tbody> - </table> - - <h2 id="macro">macro</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/macro.html">macro</a> macro(*, implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)</pre></p> - - Defines a symbolic macro, which may be called in <code>BUILD</code> files or macros (legacy or -symbolic) to define targets – possibly multiple ones. - -<p>The value returned by <code>macro(...)</code> must be assigned to a global variable in a .bzl + ... +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="configuration_field.fragment"><code>fragment</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of a configuration fragment which contains the late-bound value.</td> +</tr> +<tr> +<td id="configuration_field.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the value to obtain from the configuration fragment.</td> +</tr> +</tbody> +</table> + +## depset + +``` rule-signature +depset depset(direct=None, order="default", *, transitive=None) +``` + +Creates a [depset](../builtins/depset.html). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. + +All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression [`type(x)`](../globals/all#type). + +Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see [Issue 10313](https://github.com/bazelbuild/bazel/issues/10313). + +In addition, elements must currently be immutable, though this restriction will be relaxed in future. + +The order of the created depset should be *compatible* with the order of its `transitive` depsets. `"default"` order is compatible with any other order, all other orders are only compatible with themselves. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="depset.direct"><code>direct</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; +default is <code>None</code><br /> +A list of <em>direct</em> elements of a depset.</td> +</tr> +<tr> +<td id="depset.order"><code>order</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>"default"</code><br /> +The traversal strategy for the new depset. See <a href="../builtins/depset.html">here</a> for the possible values.</td> +</tr> +<tr> +<td id="depset.transitive"><code>transitive</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/depset.html" class="anchor">depset</a>s; or <code>None</code>; +default is <code>None</code><br /> +A list of depsets whose elements will become indirect elements of the depset.</td> +</tr> +</tbody> +</table> + +## exec_group + +``` rule-signature +exec_group exec_group(*, toolchains=[], exec_compatible_with=[]) +``` + +Creates an [execution group](/reference/exec-groups) which can be used to create actions for a specific execution platform during rule implementation. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="exec_group.toolchains"><code>toolchains</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +The set of toolchains this execution group requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination.</td> +</tr> +<tr> +<td id="exec_group.exec_compatible_with"><code>exec_compatible_with</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A list of constraints on the execution platform.</td> +</tr> +</tbody> +</table> + +## exec_transition + +``` rule-signature +transition exec_transition(*, implementation, inputs, outputs) +``` + +A specialized version of [`transition()`](../builtins/transition.html) used to define the exec transition. See its documentation (or its implementation) for best practices. Only usable from the Bazel builtins. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="exec_transition.implementation"><code>implementation</code></td> +<td>callable; +required<br /> +</td> +</tr> +<tr> +<td id="exec_transition.inputs"><code>inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +</td> +</tr> +<tr> +<td id="exec_transition.outputs"><code>outputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +</td> +</tr> +</tbody> +</table> + +## macro + +``` rule-signature +macro macro(*, implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None) +``` + +Defines a symbolic macro, which may be called in `BUILD` files or macros (legacy or +symbolic) to define targets – possibly multiple ones. + +The value returned by `macro(...)` must be assigned to a global variable in a .bzl file; the name of the global variable will be the macro symbol's name. -<p>See <a href="/extending/macros">Macros</a> for a comprehensive guide on how to use symbolic +See [Macros](/extending/macros) for a comprehensive guide on how to use symbolic macros. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="macro.implementation"> - <code>implementation</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - required<br/> - The Starlark function implementing this macro. The values of the macro's attributes are passed to +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="macro.implementation"><code>implementation</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +required<br /> +The Starlark function implementing this macro. The values of the macro's attributes are passed to the implementation function as keyword arguments. The implementation function must have at least two named parameters, <code>name</code> and <code>visibility</code>, and if the macro inherits attributes (see <code>inherit_attrs</code> below), it must have a <code>**kwargs</code> residual keyword parameter. - <p>By convention, the implementation function should have a named parameter for any attribute that the macro needs to examine, modify, or pass to non-"main" targets, while the "bulk" inherited -attributes which will be passed to the "main" target unchanged are passed as <code>**kwargs</code>. - +attributes which will be passed to the "main" target unchanged are passed as <code>**kwargs</code>.</p> <p>The implementation function must not return a value. Instead, the implementation function -<em>declares targets</em> by calling rule or macro symbols. - +<em>declares targets</em> by calling rule or macro symbols.</p> <p>The name of any target or inner symbolic macro declared by a symbolic macro (including by any Starlark function that the macro's implementation function transitively calls) must either equal <code>name</code> (this is referred to as the "main" target) or start with <code>name</code>, followed by a separator chracter (<code>"_"</code>, <code>"-"</code>, or <code>"."</code>) and a string suffix. (Targets violating this naming scheme are allowed to be declared, but cannot be -built, configured, or depended upon.) - +built, configured, or depended upon.)</p> <p>By default, targets declared by a symbolic macro (including by any Starlark function that the macro's implementation function transitively calls) are visible only in the package containing the .bzl file defining the macro. To declare targets visible externally, <em>including to the caller of the symbolic macro</em>, the implementation function must set <code>visibility</code> appropriately -– typically, by passing <code>visibility = visibility</code> to the rule or macro symbol being -called. - +– typically, by passing <code>visibility = visibility</code> to the rule or macro symbol being +called.</p> <p>The following APIs are unavailable within a macro implementation function and any Starlark -function it transitively calls: +function it transitively calls:</p> <ul> - <li><a href="/reference/be/functions#package"><code>package()</code>, <code>licenses()</code> - <li><code>environment_group()</code> - <li><a href="../toplevel/native#glob"><code>native.glob()</code></a> – instead, you may pass - a glob into the macro via a label list attribute - <li><a href="../toplevel/native#subpackages"><code>native.subpackages()</code></a> - <li>(allowed in rule finalizers only, see <code>finalizer</code> below) - <a href="../toplevel/native#existing_rules"><code>native.existing_rules()</code></a>, - <a href="../toplevel/native#existing_rule"><code>native.existing_rule()</code></a> - <li>(for <code>WORKSPACE</code> threads) - <a href="../globals/workspace#workspace"><code>workspace()</code></a>, - <a href="../globals/workspace#register_toolchains"><code>register_toolchains()</code></a>, - <a href="../globals/workspace#register_execution_platforms><code>register_execution_platforms()</code></a>, - <a href="../globals/workspace#bind"><code>bind()</code></a>, repository rule instantiation -</ul> - - </td> - </tr> - <tr> - <td id="macro.attrs"> - <code>attrs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary of the attributes this macro supports, analogous to +<li><a href="/reference/be/functions#package"><code>package()</code>, <code>licenses()</code></a></li> +<li><code>environment_group()</code></li> +<li><a href="../toplevel/native#glob"><code>native.glob()</code></a> – instead, you may pass +a glob into the macro via a label list attribute</li> +<li><a href="../toplevel/native#subpackages"><code>native.subpackages()</code></a></li> +<li>(allowed in rule finalizers only, see <code>finalizer</code> below) +<a href="../toplevel/native#existing_rules"><code>native.existing_rules()</code></a>, +<a href="../toplevel/native#existing_rule"><code>native.existing_rule()</code></a></li> +<li>(for <code>WORKSPACE</code> threads) +<a href="../globals/workspace#workspace"><code>workspace()</code></a>, +<a href="../globals/workspace#register_toolchains"><code>register_toolchains()</code></a>, +<a href="../globals/workspace#register_execution_platforms%3E%3Ccode%3Eregister_execution_platforms()%3C/code%3E%3C/a%3E,%0A%20%20%20%20%3Ca%20href=" data-..="" data-globals="" data-workspace#bind"=""><code>bind()</code></a>, repository rule instantiation</li> +</ul></td> +</tr> +<tr> +<td id="macro.attrs"><code>attrs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary of the attributes this macro supports, analogous to <a href="#rule.attrs">rule.attrs</a>. Keys are attribute names, and values are either attribute objects like <code>attr.label_list(...)</code> (see the <a href="../toplevel/attr.html">attr</a> module), or <code>None</code>. A <code>None</code> entry means that the macro does not have an attribute by that name, even if it would have otherwise inherited one via <code>inherit_attrs</code> (see below). - <p>The special <code>name</code> attribute is predeclared and must not be included in the dictionary. The <code>visibility</code> attribute name is reserved and must not be included in the -dictionary. - +dictionary.</p> <p>Attributes whose names start with <code>_</code> are private -- they cannot be passed at the call site of the rule. Such attributes can be assigned a default value (as in -<code>attr.label(default="//pkg:foo")</code>) to create an implicit dependency on a label. - -<p>To limit memory usage, there is a cap on the number of attributes that may be declared. - - </td> - </tr> - <tr> - <td id="macro.inherit_attrs"> - <code>inherit_attrs</code> - </td> - <td> - <a class="anchor" href="../builtins/rule.html">rule</a>; or <a class="anchor" href="../builtins/macro.html">macro</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A rule symbol, macro symbol, or the name of a built-in common attribute list (see below) from which +<code>attr.label(default="//pkg:foo")</code>) to create an implicit dependency on a label.</p> +<p>To limit memory usage, there is a cap on the number of attributes that may be declared.</p></td> +</tr> +<tr> +<td id="macro.inherit_attrs"><code>inherit_attrs</code></td> +<td><a href="../builtins/rule.html" class="anchor">rule</a>; or <a href="../builtins/macro.html" class="anchor">macro</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A rule symbol, macro symbol, or the name of a built-in common attribute list (see below) from which the macro should inherit attributes. - <p>If <code>inherit_attrs</code> is set to the string <code>"common"</code>, the macro will inherit <a href="/reference/be/common-definitions#common-attributes">common rule attribute definitions</a> -used by all Starlark rules. - +used by all Starlark rules.</p> <p>Note that if the return value of <code>rule()</code> or <code>macro()</code> was not assigned to a global variable in a .bzl file, then such a value has not been registered as a rule or macro -symbol, and therefore cannot be used for <code>inherit_attrs</code>. - +symbol, and therefore cannot be used for <code>inherit_attrs</code>.</p> <p>The inheritance mechanism works as follows:</p> <ol> - <li>The special <code>name</code> and <code>visibility</code> attributes are never inherited; - <li>Hidden attributes (ones whose name starts with <code>"_"</code>) are never inherited; - <li>Attributes whose names are already defined in the <code>attrs</code> dictionary are never - inherited (the entry in <code>attrs</code> takes precedence; note that an entry may be set to - <code>None</code> to ensure that no attribute by that name gets defined on the macro); - <li>All other attributes are inherited from the rule or macro and effectively merged into the - <code>attrs</code> dict. +<li>The special <code>name</code> and <code>visibility</code> attributes are never inherited;</li> +<li>Hidden attributes (ones whose name starts with <code>"_"</code>) are never inherited;</li> +<li>Attributes whose names are already defined in the <code>attrs</code> dictionary are never +inherited (the entry in <code>attrs</code> takes precedence; note that an entry may be set to +<code>None</code> to ensure that no attribute by that name gets defined on the macro);</li> +<li>All other attributes are inherited from the rule or macro and effectively merged into the +<code>attrs</code> dict.</li> </ol> - <p>When a non-mandatory attribute is inherited, the default value of the attribute is overridden to be <code>None</code>, regardless of what it was specified in the original rule or macro. This ensures that when the macro forwards the attribute's value to an instance of the wrapped rule or -macro – such as by passing in the unmodified <code>**kwargs</code> – a value that was +macro – such as by passing in the unmodified <code>**kwargs</code> – a value that was absent from the outer macro's call will also be absent in the inner rule or macro's call (since passing <code>None</code> to an attribute is treated the same as omitting the attribute). This is important because omitting an attribute has subtly different semantics from passing -its apparent default value. In particular, omitted attributes are not shown in some <code>bazel -query</code> output formats, and computed defaults only execute when the value is omitted. If the -macro needs to examine or modify an inherited attribute – for example, to add a value to an -inherited <code>tags</code> attribute – you must make sure to handle the <code>None</code> -case in the macro's implementation function. - +its apparent default value. In particular, omitted attributes are not shown in some <code>bazel query</code> output formats, and computed defaults only execute when the value is omitted. If the +macro needs to examine or modify an inherited attribute – for example, to add a value to an +inherited <code>tags</code> attribute – you must make sure to handle the <code>None</code> +case in the macro's implementation function.</p> <p>For example, the following macro inherits all attributes from <code>native.cc_library</code>, except for <code>cxxopts</code> (which is removed from the attribute list) and <code>copts</code> (which is given a new definition). It also takes care to checks for the default <code>None</code> -value of the inherited <code>tags</code> attribute before appending an additional tag. - -<pre class="language-python"> +value of the inherited <code>tags</code> attribute before appending an additional tag.</p> +<pre class="language-python"><code> def _my_cc_library_impl(name, visibility, tags, **kwargs): # Append a tag; tags attr was inherited from native.cc_library, and # therefore is None unless explicitly set by the caller of my_cc_library() - my_tags = (tags or []) + ["my_custom_tag"] + my_tags = (tags or []) + ["my_custom_tag"] native.cc_library( name = name, visibility = visibility, tags = my_tags, **kwargs ) - -my_cc_library = macro( + my_cc_library = macro( implementation = _my_cc_library_impl, inherit_attrs = native.cc_library, attrs = { - "cxxopts": None, - "copts": attr.string_list(default = ["-D_FOO"]), + "cxxopts": None, + "copts": attr.string_list(default = ["-D_FOO"]), }, -) -</pre> - +)</code></pre> <p>If <code>inherit_attrs</code> is set, the macro's implementation function <em>must</em> have a -<code>**kwargs</code> residual keyword parameter. - +<code>**kwargs</code> residual keyword parameter.</p> <p>By convention, a macro should pass inherited, non-overridden attributes unchanged to the "main" rule or macro symbol which the macro is wrapping. Typically, most inherited attributes will not have a parameter in the implementation function's parameter list, and will simply be passed via <code>**kwargs</code>. It can be convenient for the implementation function to have explicit parameters for some inherited attributes (most commonly, <code>tags</code> and <code>testonly</code>) if the macro needs to pass those attributes to both "main" and non-"main" -targets – but if the macro also needs to examine or manipulate those attributes, you must take -care to handle the <code>None</code> default value of non-mandatory inherited attributes. - - </td> - </tr> - <tr> - <td id="macro.finalizer"> - <code>finalizer</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether this macro is a rule finalizer, which is a macro that, regardless of its position in a +targets – but if the macro also needs to examine or manipulate those attributes, you must take +care to handle the <code>None</code> default value of non-mandatory inherited attributes.</p></td> +</tr> +<tr> +<td id="macro.finalizer"><code>finalizer</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether this macro is a rule finalizer, which is a macro that, regardless of its position in a <code>BUILD</code> file, is evaluated at the end of package loading, after all non-finalizer targets have been defined. - <p>Unlike ordinary symbolic macros, rule finalizers may call <a href="../toplevel/native#existing_rule"><code>native.existing_rule()</code></a> and <a href="../toplevel/native#existing_rules"><code>native.existing_rules()</code></a> to query the set of <em>non-finalizer</em> rule targets defined in the current package. Note that <code>native.existing_rule()</code> and <code>native.existing_rules()</code> cannot access the -targets defined by any rule finalizer, including this one. - - </td> - </tr> - <tr> - <td id="macro.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the macro that can be extracted by documentation generating tools. - </td> - </tr> - </tbody> - </table> - - <h2 id="materializer_rule">materializer_rule</h2> - <p><pre class="rule-signature">callable materializer_rule(*, implementation, attrs={}, doc=None)</pre></p> - - Creates a new materializer rule, which can be called from a BUILD file or a macro to create materializer targets.<p>Materializer targets are used to dynamically select dependencies at analysis time. Targets which depend on a materializer target will see the materialized dependencies, rather than the materializer target itself. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="materializer_rule.implementation"> - <code>implementation</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - required<br/> - The Starlark function implementing this materializer rule. It must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. This function is called during the analysis phase for each instance of the rule. Materializer rules return exactly one and only one MaterializedDepsInfo provider which specifies the dependencies to materialize in place of any instance of this rule in the attributes of another target. - </td> - </tr> - <tr> - <td id="materializer_rule.attrs"> - <code>attrs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see +targets defined by any rule finalizer, including this one.</p></td> +</tr> +<tr> +<td id="macro.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the macro that can be extracted by documentation generating tools.</td> +</tr> +</tbody> +</table> + +## materializer_rule + +``` rule-signature +callable materializer_rule(*, implementation, attrs={}, doc=None) +``` + +Creates a new materializer rule, which can be called from a BUILD file or a macro to create materializer targets. + +Materializer targets are used to dynamically select dependencies at analysis time. Targets which depend on a materializer target will see the materialized dependencies, rather than the materializer target itself. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="materializer_rule.implementation"><code>implementation</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +required<br /> +The Starlark function implementing this materializer rule. It must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. This function is called during the analysis phase for each instance of the rule. Materializer rules return exactly one and only one MaterializedDepsInfo provider which specifies the dependencies to materialize in place of any instance of this rule in the attributes of another target.</td> +</tr> +<tr> +<td id="materializer_rule.attrs"><code>attrs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see <a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label. The attribute <code>name</code> is implicitly added and must not be specified. Attributes <code>visibility</code>, <code>deprecation</code>, <code>tags</code>, <code>testonly</code>, and <code>features</code> are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. -<p>Declared attributes will convert <code>None</code> to the default value.</p> - - </td> - </tr> - <tr> - <td id="materializer_rule.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the rule that can be extracted by documentation generating tools. - </td> - </tr> - </tbody> - </table> - - <h2 id="module_extension">module_extension</h2> - <p><pre class="rule-signature">unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)</pre></p> - - Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with <code><a href="../globals/module.html#use_extension">use_extension</a></code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="module_extension.implementation"> - <code>implementation</code> - </td> - <td> - callable; - required<br/> - The function that implements this module extension. Must take a single parameter, <code><a href="../builtins/module_ctx.html">module_ctx</a></code>. The function is called once at the beginning of a build to determine the set of available repos. - </td> - </tr> - <tr> - <td id="module_extension.tag_classes"> - <code>tag_classes</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary to declare all the tag classes used by the extension. It maps from the name of the tag class to a <code><a href="../builtins/tag_class.html">tag_class</a></code> object. - </td> - </tr> - <tr> - <td id="module_extension.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the module extension that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="module_extension.environ"> - <code>environ</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated. - </td> - </tr> - <tr> - <td id="module_extension.os_dependent"> - <code>os_dependent</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Indicates whether this extension is OS-dependent or not - </td> - </tr> - <tr> - <td id="module_extension.arch_dependent"> - <code>arch_dependent</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Indicates whether this extension is architecture-dependent or not - </td> - </tr> - </tbody> - </table> - - <h2 id="provider">provider</h2> - <p><pre class="rule-signature">unknown provider(doc=None, *, fields=None, init=None)</pre></p> - - Defines a provider symbol. The resulting value of this function must be stored in a global value to be usable in a rule or aspect implementation. Providers can be instantiated by calling the resulting value as a function, or used directly as an index key for retrieving an instance of that provider from a target. Example:<br><pre class="language-python">MyInfo = provider() +<p>Declared attributes will convert <code>None</code> to the default value.</p></td> +</tr> +<tr> +<td id="materializer_rule.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the rule that can be extracted by documentation generating tools.</td> +</tr> +</tbody> +</table> + +## module_extension + +``` rule-signature +unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False) +``` + +Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with [`use_extension`](../globals/module.html#use_extension). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="module_extension.implementation"><code>implementation</code></td> +<td>callable; +required<br /> +The function that implements this module extension. Must take a single parameter, <a href="../builtins/module_ctx.html"><code>module_ctx</code></a>. The function is called once at the beginning of a build to determine the set of available repos.</td> +</tr> +<tr> +<td id="module_extension.tag_classes"><code>tag_classes</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary to declare all the tag classes used by the extension. It maps from the name of the tag class to a <a href="../builtins/tag_class.html"><code>tag_class</code></a> object.</td> +</tr> +<tr> +<td id="module_extension.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the module extension that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="module_extension.environ"><code>environ</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated.</td> +</tr> +<tr> +<td id="module_extension.os_dependent"><code>os_dependent</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Indicates whether this extension is OS-dependent or not</td> +</tr> +<tr> +<td id="module_extension.arch_dependent"><code>arch_dependent</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Indicates whether this extension is architecture-dependent or not</td> +</tr> +</tbody> +</table> + +## provider + +``` rule-signature +unknown provider(doc=None, *, fields=None, init=None) +``` + +Defines a provider symbol. The resulting value of this function must be stored in a global value to be usable in a rule or aspect implementation. Providers can be instantiated by calling the resulting value as a function, or used directly as an index key for retrieving an instance of that provider from a target. Example: + +``` python +MyInfo = provider() ... def _my_library_impl(ctx): ... my_info = MyInfo(x = 2, y = 3) # my_info.x == 2 # my_info.y == 3 - ...</pre><p>See <a href='https://bazel.build/extending/rules#providers'>Rules (Providers)</a> for a comprehensive guide on how to use providers.<p>Returns a <a href='../builtins/Provider.html'><code>Provider</code></a> callable value if <code>init</code> is not specified.<p>If <code>init</code> is specified, returns a tuple of 2 elements: a <a href='../builtins/Provider.html'><code>Provider</code></a> callable value and a <em>raw constructor</em> callable value. See <a href='https://bazel.build/extending/rules#custom_initialization_of_providers'> Rules (Custom initialization of custom providers)</a> and the discussion of the <code>init</code> parameter below for details. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="provider.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the provider that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="provider.fields"> - <code>fields</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - If specified, restricts the set of allowed fields. <br>Possible values are:<ul> <li> list of fields:<br> <pre class="language-python">provider(fields = ['a', 'b'])</pre><p> <li> dictionary field name -> documentation:<br> <pre class="language-python">provider( - fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })</pre></ul>All fields are optional. - </td> - </tr> - <tr> - <td id="provider.init"> - <code>init</code> - </td> - <td> - callable; or <code>None</code>; - default is <code>None</code><br/> - An optional callback for preprocessing and validating the provider's field values during instantiation. If <code>init</code> is specified, <code>provider()</code> returns a tuple of 2 elements: the normal provider symbol and a <em>raw constructor</em>.<p>A precise description follows; see <a href='https://bazel.build/extending/rules#custom_initialization_of_providers'>Rules (Custom initialization of providers)</a> for an intuitive discussion and use cases.<p>Let <code>P</code> be the provider symbol created by calling <code>provider()</code>. Conceptually, an instance of <code>P</code> is generated by calling a default constructor function <code>c(*args, **kwargs)</code>, which does the following:<ul><li>If <code>args</code> is non-empty, an error occurs.</li><li>If the <code>fields</code> parameter was specified when <code>provider()</code> was called, and if <code>kwargs</code> contains any key that was not listed in <code>fields</code>, an error occurs.</li><li>Otherwise, <code>c</code> returns a new instance that has, for each <code>k: v</code> entry in <code>kwargs</code>, a field named <code>k</code> with value <code>v</code>.</ul>In the case where an <code>init</code> callback is <em>not</em> given, a call to the symbol <code>P</code> itself acts as a call to the default constructor function <code>c</code>; in other words, <code>P(*args, **kwargs)</code> returns <code>c(*args, **kwargs)</code>. For example,<pre class="language-python">MyInfo = provider() -m = MyInfo(foo = 1)</pre>will straightforwardly make it so that <code>m</code> is a <code>MyInfo</code> instance with <code>m.foo == 1</code>.<p>But in the case where <code>init</code> is specified, the call <code>P(*args, **kwargs)</code> will perform the following steps instead:<ol><li>The callback is invoked as <code>init(*args, **kwargs)</code>, that is, with the exact same positional and keyword arguments as were passed to <code>P</code>.</li><li>The return value of <code>init</code> is expected to be a dictionary, <code>d</code>, whose keys are field name strings. If it is not, an error occurs.</li><li>A new instance of <code>P</code> is generated as if by calling the default constructor with <code>d</code>'s entries as keyword arguments, as in <code>c(**d)</code>.</li></ol><p>NB: the above steps imply that an error occurs if <code>*args</code> or <code>**kwargs</code> does not match <code>init</code>'s signature, or the evaluation of <code>init</code>'s body fails (perhaps intentionally via a call to <a href="../globals/all.html#fail"><code>fail()</code></a>), or if the return value of <code>init</code> is not a dictionary with the expected schema.<p>In this way, the <code>init</code> callback generalizes normal provider construction by allowing positional arguments and arbitrary logic for preprocessing and validation. It does <em>not</em> enable circumventing the list of allowed <code>fields</code>.<p>When <code>init</code> is specified, the return value of <code>provider()</code> becomes a tuple <code>(P, r)</code>, where <code>r</code> is the <em>raw constructor</em>. In fact, the behavior of <code>r</code> is exactly that of the default constructor function <code>c</code> discussed above. Typically, <code>r</code> is bound to a variable whose name is prefixed with an underscore, so that only the current .bzl file has direct access to it:<pre class="language-python">MyInfo, _new_myinfo = provider(init = ...)</pre> - </td> - </tr> - </tbody> - </table> - - <h2 id="repository_rule">repository_rule</h2> - <p><pre class="rule-signature">callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)</pre></p> - - Creates a new repository rule. Store it in a global value, so that it can be loaded and called from a <a href="#module_extension"><code>module_extension()</code></a> implementation function, or used by <a href="../globals/module.html#use_repo_rule"><code>use_repo_rule()</code></a>. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="repository_rule.implementation"> - <code>implementation</code> - </td> - <td> - callable; - required<br/> - the function that implements this rule. Must have a single parameter, <code><a href="../builtins/repository_ctx.html">repository_ctx</a></code>. The function is called during the loading phase for each instance of the rule. - </td> - </tr> - <tr> - <td id="repository_rule.attrs"> - <code>attrs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - A dictionary to declare all the attributes of the repository rule. It maps from an attribute name to an attribute object (see + ... +``` + +See [Rules (Providers)](https://bazel.build/extending/rules#providers) for a comprehensive guide on how to use providers. + +Returns a [`Provider`](../builtins/Provider.html) callable value if `init` is not specified. + +If `init` is specified, returns a tuple of 2 elements: a [`Provider`](../builtins/Provider.html) callable value and a *raw constructor* callable value. See [Rules (Custom initialization of custom providers)](https://bazel.build/extending/rules#custom_initialization_of_providers) and the discussion of the `init` parameter below for details. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="provider.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the provider that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="provider.fields"><code>fields</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +If specified, restricts the set of allowed fields.<br /> +Possible values are: +<ul> +<li><p>list of fields:<br /> +</p> +<pre class="language-python"><code>provider(fields = ['a', 'b'])</code></pre></li> +<li><p>dictionary field name -> documentation:<br /> +</p> +<pre class="language-python"><code>provider( + fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })</code></pre></li> +</ul> +All fields are optional.</td> +</tr> +<tr> +<td id="provider.init"><code>init</code></td> +<td>callable; or <code>None</code>; +default is <code>None</code><br /> +An optional callback for preprocessing and validating the provider's field values during instantiation. If <code>init</code> is specified, <code>provider()</code> returns a tuple of 2 elements: the normal provider symbol and a <em>raw constructor</em>. +<p>A precise description follows; see <a href="https://bazel.build/extending/rules#custom_initialization_of_providers">Rules (Custom initialization of providers)</a> for an intuitive discussion and use cases.</p> +<p>Let <code>P</code> be the provider symbol created by calling <code>provider()</code>. Conceptually, an instance of <code>P</code> is generated by calling a default constructor function <code>c(*args, **kwargs)</code>, which does the following:</p> +<ul> +<li>If <code>args</code> is non-empty, an error occurs.</li> +<li>If the <code>fields</code> parameter was specified when <code>provider()</code> was called, and if <code>kwargs</code> contains any key that was not listed in <code>fields</code>, an error occurs.</li> +<li>Otherwise, <code>c</code> returns a new instance that has, for each <code>k: v</code> entry in <code>kwargs</code>, a field named <code>k</code> with value <code>v</code>.</li> +</ul> +In the case where an <code>init</code> callback is <em>not</em> given, a call to the symbol <code>P</code> itself acts as a call to the default constructor function <code>c</code>; in other words, <code>P(*args, **kwargs)</code> returns <code>c(*args, **kwargs)</code>. For example, +<pre class="language-python"><code>MyInfo = provider() +m = MyInfo(foo = 1)</code></pre> +will straightforwardly make it so that <code>m</code> is a <code>MyInfo</code> instance with <code>m.foo == 1</code>. +<p>But in the case where <code>init</code> is specified, the call <code>P(*args, **kwargs)</code> will perform the following steps instead:</p> +<ol> +<li>The callback is invoked as <code>init(*args, **kwargs)</code>, that is, with the exact same positional and keyword arguments as were passed to <code>P</code>.</li> +<li>The return value of <code>init</code> is expected to be a dictionary, <code>d</code>, whose keys are field name strings. If it is not, an error occurs.</li> +<li>A new instance of <code>P</code> is generated as if by calling the default constructor with <code>d</code>'s entries as keyword arguments, as in <code>c(**d)</code>.</li> +</ol> +<p>NB: the above steps imply that an error occurs if <code>*args</code> or <code>**kwargs</code> does not match <code>init</code>'s signature, or the evaluation of <code>init</code>'s body fails (perhaps intentionally via a call to <a href="../globals/all.html#fail"><code>fail()</code></a>), or if the return value of <code>init</code> is not a dictionary with the expected schema.</p> +<p>In this way, the <code>init</code> callback generalizes normal provider construction by allowing positional arguments and arbitrary logic for preprocessing and validation. It does <em>not</em> enable circumventing the list of allowed <code>fields</code>.</p> +<p>When <code>init</code> is specified, the return value of <code>provider()</code> becomes a tuple <code>(P, r)</code>, where <code>r</code> is the <em>raw constructor</em>. In fact, the behavior of <code>r</code> is exactly that of the default constructor function <code>c</code> discussed above. Typically, <code>r</code> is bound to a variable whose name is prefixed with an underscore, so that only the current .bzl file has direct access to it:</p> +<pre class="language-python"><code>MyInfo, _new_myinfo = provider(init = ...)</code></pre></td> +</tr> +</tbody> +</table> + +## repository_rule + +``` rule-signature +callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None) +``` + +Creates a new repository rule. Store it in a global value, so that it can be loaded and called from a [`module_extension()`](#module_extension) implementation function, or used by [`use_repo_rule()`](../globals/module.html#use_repo_rule). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="repository_rule.implementation"><code>implementation</code></td> +<td>callable; +required<br /> +the function that implements this rule. Must have a single parameter, <a href="../builtins/repository_ctx.html"><code>repository_ctx</code></a>. The function is called during the loading phase for each instance of the rule.</td> +</tr> +<tr> +<td id="repository_rule.attrs"><code>attrs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +A dictionary to declare all the attributes of the repository rule. It maps from an attribute name to an attribute object (see <a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label to a file (a repository rule cannot depend on a generated artifact). The attribute <code>name</code> is implicitly added and must not be specified. -<p>Declared attributes will convert <code>None</code> to the default value.</p> - - </td> - </tr> - <tr> - <td id="repository_rule.local"> - <code>local</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch. - </td> - </tr> - <tr> - <td id="repository_rule.environ"> - <code>environ</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - <b>Deprecated</b>. This parameter has been deprecated. Migrate to <code>repository_ctx.getenv</code> instead.<br/>Provides a list of environment variable that this repository rule depends on. If an environment variable in that list change, the repository will be refetched. - </td> - </tr> - <tr> - <td id="repository_rule.configure"> - <code>configure</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Indicate that the repository inspects the system for configuration purpose - </td> - </tr> - <tr> - <td id="repository_rule.remotable"> - <code>remotable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - <b>Experimental</b>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_repo_remote_exec</code> <br>Compatible with remote execution - </td> - </tr> - <tr> - <td id="repository_rule.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the repository rule that can be extracted by documentation generating tools. - </td> - </tr> - </tbody> - </table> - - <h2 id="rule">rule</h2> - <p><pre class="rule-signature">callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])</pre></p> - - Creates a new rule, which can be called from a BUILD file or a macro to create targets.<p>Rules must be assigned to global variables in a .bzl file; the name of the global variable is the rule's name.<p>Test rules are required to have a name ending in <code>_test</code>, while all other rules must not have this suffix. (This restriction applies only to rules, not to their targets.) - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="rule.implementation"> - <code>implementation</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - required<br/> - the Starlark function implementing this rule, must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. The function is called during the analysis phase for each instance of the rule. It can access the attributes provided by the user. It must create actions to generate all the declared outputs. - </td> - </tr> - <tr> - <td id="rule.test"> - <code>test</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>unbound</code><br/> - Whether this rule is a test rule, that is, whether it may be the subject of a <code>bazel test</code> command. All test rules are automatically considered <a href='#rule.executable'>executable</a>; it is unnecessary (and discouraged) to explicitly set <code>executable = True</code> for a test rule. The value defaults to <code>False</code>. See the <a href='https://bazel.build/extending/rules#executable_rules_and_test_rules'> Rules page</a> for more information. - </td> - </tr> - <tr> - <td id="rule.attrs"> - <code>attrs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see +<p>Declared attributes will convert <code>None</code> to the default value.</p></td> +</tr> +<tr> +<td id="repository_rule.local"><code>local</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch.</td> +</tr> +<tr> +<td id="repository_rule.environ"><code>environ</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +<strong>Deprecated</strong>. This parameter has been deprecated. Migrate to <code>repository_ctx.getenv</code> instead.<br /> +Provides a list of environment variable that this repository rule depends on. If an environment variable in that list change, the repository will be refetched.</td> +</tr> +<tr> +<td id="repository_rule.configure"><code>configure</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Indicate that the repository inspects the system for configuration purpose</td> +</tr> +<tr> +<td id="repository_rule.remotable"><code>remotable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +<strong>Experimental</strong>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_repo_remote_exec</code><br /> +Compatible with remote execution</td> +</tr> +<tr> +<td id="repository_rule.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the repository rule that can be extracted by documentation generating tools.</td> +</tr> +</tbody> +</table> + +## rule + +``` rule-signature +callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[]) +``` + +Creates a new rule, which can be called from a BUILD file or a macro to create targets. + +Rules must be assigned to global variables in a .bzl file; the name of the global variable is the rule's name. + +Test rules are required to have a name ending in `_test`, while all other rules must not have this suffix. (This restriction applies only to rules, not to their targets.) + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="rule.implementation"><code>implementation</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +required<br /> +the Starlark function implementing this rule, must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. The function is called during the analysis phase for each instance of the rule. It can access the attributes provided by the user. It must create actions to generate all the declared outputs.</td> +</tr> +<tr> +<td id="rule.test"><code>test</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>unbound</code><br /> +Whether this rule is a test rule, that is, whether it may be the subject of a <code>bazel test</code> command. All test rules are automatically considered <a href="#rule.executable">executable</a>; it is unnecessary (and discouraged) to explicitly set <code>executable = True</code> for a test rule. The value defaults to <code>False</code>. See the <a href="https://bazel.build/extending/rules#executable_rules_and_test_rules">Rules page</a> for more information.</td> +</tr> +<tr> +<td id="rule.attrs"><code>attrs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see <a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label. The attribute <code>name</code> is implicitly added and must not be specified. Attributes <code>visibility</code>, <code>deprecation</code>, <code>tags</code>, <code>testonly</code>, and <code>features</code> are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. -<p>Declared attributes will convert <code>None</code> to the default value.</p> - - </td> - </tr> - <tr> - <td id="rule.outputs"> - <code>outputs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; or <a class="anchor" href="../core/function.html">function</a>; - default is <code>None</code><br/> - <b>Deprecated</b>. This parameter is deprecated and will be removed soon. Please do not depend on it. It is <i>disabled</i> with <code>--incompatible_no_rule_outputs_param</code>. Use this flag to verify your code is compatible with its imminent removal. <br>This parameter has been deprecated. Migrate rules to use <code>OutputGroupInfo</code> or <code>attr.output</code> instead. <p>A schema for defining predeclared outputs. Unlike <a href='../toplevel/attr.html#output'><code>output</code></a> and <a href='../toplevel/attr.html#output_list'><code>output_list</code></a> attributes, the user does not specify the labels for these files. See the <a href='https://bazel.build/extending/rules#files'>Rules page</a> for more on predeclared outputs.<p>The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass <code>outputs = _my_func</code> with the definition <code>def _my_func(srcs, deps): ...</code>, the function has access to the attributes <code>srcs</code> and <code>deps</code>. Whether the dictionary is specified directly or via a function, it is interpreted as follows.<p>Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's <a href='../builtins/File.html'><code>File</code></a> in <a href='../builtins/ctx.html#outputs'><code>ctx.outputs</code></a>. The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form <code>"%{ATTR}"</code> with a string formed from the value of the attribute <code>ATTR</code>:<ul><li>String-typed attributes are substituted verbatim.<li>Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label <code>"//pkg:a/b.c"</code> becomes <code>"a/b"</code>.<li>Output-typed attributes become the part of the label after the package, including the file extension (for the above example, <code>"a/b.c"</code>).<li>All list-typed attributes (for example, <code>attr.label_list</code>) used in placeholders are required to have <i>exactly one element</i>. Their conversion is the same as their non-list version (<code>attr.label</code>).<li>Other attribute types may not appear in placeholders.<li>The special non-attribute placeholders <code>%{dirname}</code> and <code>%{basename}</code> expand to those parts of the rule's label, excluding its package. For example, in <code>"//pkg:a/b.c"</code>, the dirname is <code>a</code> and the basename is <code>b.c</code>.</ul><p>In practice, the most common substitution placeholder is <code>"%{name}"</code>. For example, for a target named "foo", the outputs dict <code>{"bin": "%{name}.exe"}</code> predeclares an output named <code>foo.exe</code> that is accessible in the implementation function as <code>ctx.outputs.bin</code>. - </td> - </tr> - <tr> - <td id="rule.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>unbound</code><br/> - Whether this rule is considered executable, that is, whether it may be the subject of a <code>bazel run</code> command. It defaults to <code>False</code>. See the <a href='https://bazel.build/extending/rules#executable_rules_and_test_rules'> Rules page</a> for more information. - </td> - </tr> - <tr> - <td id="rule.output_to_genfiles"> - <code>output_to_genfiles</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the files will be generated in the genfiles directory instead of the bin directory. Unless you need it for compatibility with existing rules (e.g. when generating header files for C++), do not set this flag. - </td> - </tr> - <tr> - <td id="rule.fragments"> - <code>fragments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - List of names of configuration fragments that the rule requires in target configuration. - </td> - </tr> - <tr> - <td id="rule.host_fragments"> - <code>host_fragments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - List of names of configuration fragments that the rule requires in host configuration. - </td> - </tr> - <tr> - <td id="rule._skylark_testable"> - <code>_skylark_testable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - <i>(Experimental)</i><br/><br/>If true, this rule will expose its actions for inspection by rules that depend on it via an <code>Actions</code> provider. The provider is also available to the rule itself by calling <a href="../builtins/ctx.html#created_actions">ctx.created_actions()</a>.<br/><br/>This should only be used for testing the analysis-time behavior of Starlark rules. This flag may be removed in the future. - </td> - </tr> - <tr> - <td id="rule.toolchains"> - <code>toolchains</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - If set, the set of toolchains this rule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the rule implementation via <code>ctx.toolchain</code>. - </td> - </tr> - <tr> - <td id="rule.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the rule that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="rule.provides"> - <code>provides</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - A list of providers that the implementation function must return.<p>It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.<p>Each element of the list is an <code>*Info</code> object returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a>. When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The <a href='../globals/bzl.html#aspect.required_providers'><code>required_providers</code></a> field of an <a href='../globals/bzl.html#aspect'>aspect</a> does, however, require that providers are specified here. - </td> - </tr> - <tr> - <td id="rule.dependency_resolution_rule"> - <code>dependency_resolution_rule</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If set, the rule can be a dependency through attributes also marked as available in materializers. Every attribute of rules with this flag set must be marked as available in materializers also. This is so that rules so marked cannot depend on rules that are not so marked. - </td> - </tr> - <tr> - <td id="rule.exec_compatible_with"> - <code>exec_compatible_with</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A list of constraints on the execution platform that apply to all targets of this rule type. - </td> - </tr> - <tr> - <td id="rule.analysis_test"> - <code>analysis_test</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, then this rule is treated as an analysis test. <p>Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See <a href="https://bazel.build/rules/testing#testing-rules">Testing</a> for guidance. <p>If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using <a href="#analysis_test_transition">analysis_test_transition</a> on its attributes, but opts into some restrictions: <ul><li>Targets of this rule are limited in the number of transitive dependencies they may have. <li>The rule is considered a test rule (as if <code>test=True</code> were set). This supersedes the value of <code>test</code></li> <li>The rule implementation function may not register actions. Instead, it must register a pass/fail result via providing <a href='../providers/AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>.</li></ul> - </td> - </tr> - <tr> - <td id="rule.build_setting"> - <code>build_setting</code> - </td> - <td> - <a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a>; or <code>None</code>; - default is <code>None</code><br/> - If set, describes what kind of <a href='/rules/config#user-defined-build-settings'><code>build setting</code></a> this rule is. See the <a href='../toplevel/config.html'><code>config</code></a> module. If this is set, a mandatory attribute named "build_setting_default" is automatically added to this rule, with a type corresponding to the value passed in here. - </td> - </tr> - <tr> - <td id="rule.cfg"> - <code>cfg</code> - </td> - <td> - default is <code>None</code><br/> - If set, points to the configuration transition the rule will apply to its own configuration before analysis. - </td> - </tr> - <tr> - <td id="rule.exec_groups"> - <code>exec_groups</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <code>None</code>; - default is <code>None</code><br/> - Dict of execution group name (string) to <a href='../globals/bzl.html#exec_group'><code>exec_group</code>s</a>. If set, allows rules to run actions on multiple execution platforms within a single target. See <a href='/reference/exec-groups'>execution groups documentation</a> for more info. - </td> - </tr> - <tr> - <td id="rule.initializer"> - <code>initializer</code> - </td> - <td> - default is <code>None</code><br/> - Experimental: the Stalark function initializing the attributes of the rule. <p>The function is called at load time for each instance of the rule. It's called with <code>name</code> and the values of public attributes defined by the rule (not with generic attributes, for example <code>tags</code>). <p>It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning <code>None</code> as value results in using the default value specified in the attribute definition. <p>Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning <code>None</code>). <p>Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases. <p>It's a good practice to use <code>**kwargs</code> for attributes that are not handled.<p>In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about. - </td> - </tr> - <tr> - <td id="rule.parent"> - <code>parent</code> - </td> - <td> - default is <code>None</code><br/> - Experimental: the Stalark rule that is extended. When set the public attributes are merged as well as advertised providers. The rule matches <code>executable</code> and <code>test</code> from the parent. Values of <code>fragments</code>, <code>toolchains</code>, <code>exec_compatible_with</code>, and <code>exec_groups</code> are merged. Legacy or deprecated parameters may not be set. Incoming configuration transition <code>cfg</code> of parent is applied after thisrule's incoming configuration. - </td> - </tr> - <tr> - <td id="rule.extendable"> - <code>extendable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Experimental: A label of an allowlist defining which rules can extending this rule. It can be set also to True/False to always allow/disallow extending. Bazel defaults to always allowing extensions. - </td> - </tr> - <tr> - <td id="rule.subrules"> - <code>subrules</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Subrule.html">Subrule</a>s; - default is <code>[]</code><br/> - Experimental: List of subrules used by this rule. - </td> - </tr> - </tbody> - </table> - - <h2 id="select">select</h2> - <p><pre class="rule-signature">unknown select(x, no_match_error='')</pre></p> - - <code>select()</code> is the helper function that makes a rule attribute <a href="/reference/be/common-definitions#configurable-attributes">configurable</a>. See <a href="/reference/be/functions#select">build encyclopedia</a> for details. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="select.x"> - <code>x</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - required<br/> - A dict that maps configuration conditions to values. Each key is a <a href="../builtins/Label.html">Label</a> or a label string that identifies a config_setting or constraint_value instance. See the <a href="https://bazel.build/extending/legacy-macros#label-resolution">documentation on macros</a> for when to use a Label instead of a string. If <code>--incompatible_resolve_select_keys_eagerly</code> is enabled, the keys are resolved to <code>Label</code> objects relative to the package of the file that contains this call to <code>select</code>. - </td> - </tr> - <tr> - <td id="select.no_match_error"> - <code>no_match_error</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Optional custom error to report if no condition matches. - </td> - </tr> - </tbody> - </table> - - <h2 id="subrule">subrule</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Subrule.html">Subrule</a> subrule(*, implementation, attrs={}, toolchains=[], fragments=[], subrules=[])</pre></p> - - Constructs a new instance of a subrule. The result of this function must be stored in a global variable before it can be used. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="subrule.implementation"> - <code>implementation</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - required<br/> - The Starlark function implementing this subrule - </td> - </tr> - <tr> - <td id="subrule.attrs"> - <code>attrs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary to declare all the (private) attributes of the subrule. <p/>Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be: <ul><li><code>FilesToRunProvider</code> for label attributes with <code>executable=True</code></li><li><code>File</code> for label attributes with <code>allow_single_file=True</code></li><li><code>Target</code> for all other label attributes</li><li><code>[Target]</code> for all label-list attributes</li></ul> - </td> - </tr> - <tr> - <td id="subrule.toolchains"> - <code>toolchains</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - If set, the set of toolchains this subrule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the subrule implementation via <code>ctx.toolchains</code>. Note that AEGs need to be enabled on the consuming rule(s) if this parameter is set. In case you haven't migrated to AEGs yet, see https://bazel.build/extending/auto-exec-groups#migration-aegs. - </td> - </tr> - <tr> - <td id="subrule.fragments"> - <code>fragments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - List of names of configuration fragments that the subrule requires in target configuration. - </td> - </tr> - <tr> - <td id="subrule.subrules"> - <code>subrules</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Subrule.html">Subrule</a>s; - default is <code>[]</code><br/> - List of other subrules needed by this subrule. - </td> - </tr> - </tbody> - </table> - - <h2 id="tag_class">tag_class</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/tag_class.html">tag_class</a> tag_class(attrs={}, *, doc=None)</pre></p> - - Creates a new tag_class object, which defines an attribute schema for a class of tags, which are data objects usable by a module extension. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="tag_class.attrs"> - <code>attrs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dictionary to declare all the attributes of this tag class. It maps from an attribute name to an attribute object (see <a href="../toplevel/attr.html"> -attr</a> module). +<p>Declared attributes will convert <code>None</code> to the default value.</p></td> +</tr> +<tr> +<td id="rule.outputs"><code>outputs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; or <a href="../core/function.html" class="anchor">function</a>; +default is <code>None</code><br /> +<strong>Deprecated</strong>. This parameter is deprecated and will be removed soon. Please do not depend on it. It is <em>disabled</em> with <code>--incompatible_no_rule_outputs_param</code>. Use this flag to verify your code is compatible with its imminent removal.<br /> +This parameter has been deprecated. Migrate rules to use <code>OutputGroupInfo</code> or <code>attr.output</code> instead. +<p>A schema for defining predeclared outputs. Unlike <a href="../toplevel/attr.html#output"><code>output</code></a> and <a href="../toplevel/attr.html#output_list"><code>output_list</code></a> attributes, the user does not specify the labels for these files. See the <a href="https://bazel.build/extending/rules#files">Rules page</a> for more on predeclared outputs.</p> +<p>The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass <code>outputs = _my_func</code> with the definition <code>def _my_func(srcs, deps): ...</code>, the function has access to the attributes <code>srcs</code> and <code>deps</code>. Whether the dictionary is specified directly or via a function, it is interpreted as follows.</p> +<p>Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's <a href="../builtins/File.html"><code>File</code></a> in <a href="../builtins/ctx.html#outputs"><code>ctx.outputs</code></a>. The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form <code>"%{ATTR}"</code> with a string formed from the value of the attribute <code>ATTR</code>:</p> +<ul> +<li>String-typed attributes are substituted verbatim.</li> +<li>Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label <code>"//pkg:a/b.c"</code> becomes <code>"a/b"</code>.</li> +<li>Output-typed attributes become the part of the label after the package, including the file extension (for the above example, <code>"a/b.c"</code>).</li> +<li>All list-typed attributes (for example, <code>attr.label_list</code>) used in placeholders are required to have <em>exactly one element</em>. Their conversion is the same as their non-list version (<code>attr.label</code>).</li> +<li>Other attribute types may not appear in placeholders.</li> +<li>The special non-attribute placeholders <code>%{dirname}</code> and <code>%{basename}</code> expand to those parts of the rule's label, excluding its package. For example, in <code>"//pkg:a/b.c"</code>, the dirname is <code>a</code> and the basename is <code>b.c</code>.</li> +</ul> +<p>In practice, the most common substitution placeholder is <code>"%{name}"</code>. For example, for a target named "foo", the outputs dict <code>{"bin": "%{name}.exe"}</code> predeclares an output named <code>foo.exe</code> that is accessible in the implementation function as <code>ctx.outputs.bin</code>.</p></td> +</tr> +<tr> +<td id="rule.executable"><code>executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>unbound</code><br /> +Whether this rule is considered executable, that is, whether it may be the subject of a <code>bazel run</code> command. It defaults to <code>False</code>. See the <a href="https://bazel.build/extending/rules#executable_rules_and_test_rules">Rules page</a> for more information.</td> +</tr> +<tr> +<td id="rule.output_to_genfiles"><code>output_to_genfiles</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the files will be generated in the genfiles directory instead of the bin directory. Unless you need it for compatibility with existing rules (e.g. when generating header files for C++), do not set this flag.</td> +</tr> +<tr> +<td id="rule.fragments"><code>fragments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +List of names of configuration fragments that the rule requires in target configuration.</td> +</tr> +<tr> +<td id="rule.host_fragments"><code>host_fragments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +List of names of configuration fragments that the rule requires in host configuration.</td> +</tr> +<tr> +<td id="rule._skylark_testable"><code>_skylark_testable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +<em>(Experimental)</em><br /> +<br /> +If true, this rule will expose its actions for inspection by rules that depend on it via an <code>Actions</code> provider. The provider is also available to the rule itself by calling <a href="../builtins/ctx.html#created_actions">ctx.created_actions()</a>.<br /> +<br /> +This should only be used for testing the analysis-time behavior of Starlark rules. This flag may be removed in the future.</td> +</tr> +<tr> +<td id="rule.toolchains"><code>toolchains</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +If set, the set of toolchains this rule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the rule implementation via <code>ctx.toolchain</code>.</td> +</tr> +<tr> +<td id="rule.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the rule that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="rule.provides"><code>provides</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +A list of providers that the implementation function must return. +<p>It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.</p> +<p>Each element of the list is an <code>*Info</code> object returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a>. When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The <a href="../globals/bzl.html#aspect.required_providers"><code>required_providers</code></a> field of an <a href="../globals/bzl.html#aspect">aspect</a> does, however, require that providers are specified here.</p></td> +</tr> +<tr> +<td id="rule.dependency_resolution_rule"><code>dependency_resolution_rule</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If set, the rule can be a dependency through attributes also marked as available in materializers. Every attribute of rules with this flag set must be marked as available in materializers also. This is so that rules so marked cannot depend on rules that are not so marked.</td> +</tr> +<tr> +<td id="rule.exec_compatible_with"><code>exec_compatible_with</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A list of constraints on the execution platform that apply to all targets of this rule type.</td> +</tr> +<tr> +<td id="rule.analysis_test"><code>analysis_test</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, then this rule is treated as an analysis test. +<p>Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See <a href="https://bazel.build/rules/testing#testing-rules">Testing</a> for guidance.</p> +<p>If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using <a href="#analysis_test_transition">analysis_test_transition</a> on its attributes, but opts into some restrictions:</p> +<ul> +<li>Targets of this rule are limited in the number of transitive dependencies they may have.</li> +<li>The rule is considered a test rule (as if <code>test=True</code> were set). This supersedes the value of <code>test</code></li> +<li>The rule implementation function may not register actions. Instead, it must register a pass/fail result via providing <a href="../providers/AnalysisTestResultInfo.html">AnalysisTestResultInfo</a>.</li> +</ul></td> +</tr> +<tr> +<td id="rule.build_setting"><code>build_setting</code></td> +<td><a href="../builtins/BuildSetting.html" class="anchor">BuildSetting</a>; or <code>None</code>; +default is <code>None</code><br /> +If set, describes what kind of <a href="/rules/config#user-defined-build-settings"><code>build setting</code></a> this rule is. See the <a href="../toplevel/config.html"><code>config</code></a> module. If this is set, a mandatory attribute named "build_setting_default" is automatically added to this rule, with a type corresponding to the value passed in here.</td> +</tr> +<tr> +<td id="rule.cfg"><code>cfg</code></td> +<td>default is <code>None</code><br /> +If set, points to the configuration transition the rule will apply to its own configuration before analysis.</td> +</tr> +<tr> +<td id="rule.exec_groups"><code>exec_groups</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; +default is <code>None</code><br /> +Dict of execution group name (string) to <a href="../globals/bzl.html#exec_group"><code>exec_group</code>s</a>. If set, allows rules to run actions on multiple execution platforms within a single target. See <a href="/reference/exec-groups">execution groups documentation</a> for more info.</td> +</tr> +<tr> +<td id="rule.initializer"><code>initializer</code></td> +<td>default is <code>None</code><br /> +Experimental: the Stalark function initializing the attributes of the rule. +<p>The function is called at load time for each instance of the rule. It's called with <code>name</code> and the values of public attributes defined by the rule (not with generic attributes, for example <code>tags</code>).</p> +<p>It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning <code>None</code> as value results in using the default value specified in the attribute definition.</p> +<p>Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning <code>None</code>).</p> +<p>Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases.</p> +<p>It's a good practice to use <code>**kwargs</code> for attributes that are not handled.</p> +<p>In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about.</p></td> +</tr> +<tr> +<td id="rule.parent"><code>parent</code></td> +<td>default is <code>None</code><br /> +Experimental: the Stalark rule that is extended. When set the public attributes are merged as well as advertised providers. The rule matches <code>executable</code> and <code>test</code> from the parent. Values of <code>fragments</code>, <code>toolchains</code>, <code>exec_compatible_with</code>, and <code>exec_groups</code> are merged. Legacy or deprecated parameters may not be set. Incoming configuration transition <code>cfg</code> of parent is applied after thisrule's incoming configuration.</td> +</tr> +<tr> +<td id="rule.extendable"><code>extendable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Experimental: A label of an allowlist defining which rules can extending this rule. It can be set also to True/False to always allow/disallow extending. Bazel defaults to always allowing extensions.</td> +</tr> +<tr> +<td id="rule.subrules"><code>subrules</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Subrule.html" class="anchor">Subrule</a>s; +default is <code>[]</code><br /> +Experimental: List of subrules used by this rule.</td> +</tr> +</tbody> +</table> + +## select + +``` rule-signature +unknown select(x, no_match_error='') +``` + +`select()` is the helper function that makes a rule attribute [configurable](/reference/be/common-definitions#configurable-attributes). See [build encyclopedia](/reference/be/functions#select) for details. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="select.x"><code>x</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +required<br /> +A dict that maps configuration conditions to values. Each key is a <a href="../builtins/Label.html">Label</a> or a label string that identifies a config_setting or constraint_value instance. See the <a href="https://bazel.build/extending/legacy-macros#label-resolution">documentation on macros</a> for when to use a Label instead of a string. If <code>--incompatible_resolve_select_keys_eagerly</code> is enabled, the keys are resolved to <code>Label</code> objects relative to the package of the file that contains this call to <code>select</code>.</td> +</tr> +<tr> +<td id="select.no_match_error"><code>no_match_error</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Optional custom error to report if no condition matches.</td> +</tr> +</tbody> +</table> + +## subrule + +``` rule-signature +Subrule subrule(*, implementation, attrs={}, toolchains=[], fragments=[], subrules=[]) +``` + +Constructs a new instance of a subrule. The result of this function must be stored in a global variable before it can be used. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="subrule.implementation"><code>implementation</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +required<br /> +The Starlark function implementing this subrule</td> +</tr> +<tr> +<td id="subrule.attrs"><code>attrs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary to declare all the (private) attributes of the subrule. +Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be: +<ul> +<li><code>FilesToRunProvider</code> for label attributes with <code>executable=True</code></li> +<li><code>File</code> for label attributes with <code>allow_single_file=True</code></li> +<li><code>Target</code> for all other label attributes</li> +<li><code>[Target]</code> for all label-list attributes</li> +</ul></td> +</tr> +<tr> +<td id="subrule.toolchains"><code>toolchains</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +If set, the set of toolchains this subrule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the subrule implementation via <code>ctx.toolchains</code>. Note that AEGs need to be enabled on the consuming rule(s) if this parameter is set. In case you haven't migrated to AEGs yet, see https://bazel.build/extending/auto-exec-groups#migration-aegs.</td> +</tr> +<tr> +<td id="subrule.fragments"><code>fragments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +List of names of configuration fragments that the subrule requires in target configuration.</td> +</tr> +<tr> +<td id="subrule.subrules"><code>subrules</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Subrule.html" class="anchor">Subrule</a>s; +default is <code>[]</code><br /> +List of other subrules needed by this subrule.</td> +</tr> +</tbody> +</table> + +## tag_class + +``` rule-signature +tag_class tag_class(attrs={}, *, doc=None) +``` + +Creates a new tag_class object, which defines an attribute schema for a class of tags, which are data objects usable by a module extension. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="tag_class.attrs"><code>attrs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dictionary to declare all the attributes of this tag class. It maps from an attribute name to an attribute object (see +<a href="../toplevel/attr.html">attr</a> module). <p>Note that unlike <a href="../globals/bzl.html#rule"><code>rule()</code></a>, <a href="../globals/bzl.html#aspect"><code>aspect()</code></a> and <a href="../globals/bzl.html#repository_rule"><code>repository_rule()</code></a>, -declared attributes will not convert <code>None</code> to the default value. For the default to be used, the attribute must be omitted entirely by the caller.</p> - - </td> - </tr> - <tr> - <td id="tag_class.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the tag class that can be extracted by documentation generating tools. - </td> - </tr> - </tbody> - </table> - - <h2 id="visibility">visibility</h2> - <p><pre class="rule-signature"><code>None</code> visibility(value)</pre></p> - - <p>Sets the load visibility of the .bzl module currently being initialized.<p>The load visibility of a module governs whether or not other BUILD and .bzl files may load it. (This is distinct from the target visibility of the underlying .bzl source file, which governs whether the file may appear as a dependency of other targets.) Load visibility works at the level of packages: To load a module the file doing the loading must live in a package that has been granted visibility to the module. A module can always be loaded within its own package, regardless of its visibility.<p><code>visibility()</code> may only be called once per .bzl file, and only at the top level, not inside a function. The preferred style is to put this call immediately below the <code>load()</code> statements and any brief logic needed to determine the argument.<p>If the flag <code>--check_bzl_visibility</code> is set to false, load visibility violations will emit warnings but not fail the build. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="visibility.value"> - <code>value</code> - </td> - <td> - required<br/> - A list of package specification strings, or a single package specification string.<p>Package specifications follow the same format as for <code><a href='/reference/be/functions#package_group'>package_group</a></code>, except that negative package specifications are not permitted. That is, a specification may have the forms:<ul><li><code>"//foo"</code>: the package <code>//foo</code><li><code>"//foo/..."</code>: the package <code>//foo</code> and all of its subpackages.<li><code>"public"</code> or <code>"private"</code>: all packages or no packages, respectively</ul><p>The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository.<p>If <code>value</code> is a list of strings, the set of packages granted visibility to this module is the union of the packages represented by each specification. (An empty list has the same effect as <code>private</code>.) If <code>value</code> is a single string, it is treated as if it were the singleton list <code>[value]</code>.<p>Note that the flags <code>--incompatible_package_group_has_public_syntax</code> and <code>--incompatible_fix_package_group_reporoot_syntax</code> have no effect on this argument. The <code>"public"</code> and <code>"private"</code> values are always available, and <code>"//..."</code> is always interpreted as "all packages in the current repository". - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +declared attributes will not convert <code>None</code> to the default value. For the default to be used, the attribute must be omitted entirely by the caller.</p></td> +</tr> +<tr> +<td id="tag_class.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the tag class that can be extracted by documentation generating tools.</td> +</tr> +</tbody> +</table> + +## visibility + +``` rule-signature +None visibility(value) +``` + +Sets the load visibility of the .bzl module currently being initialized. + +The load visibility of a module governs whether or not other BUILD and .bzl files may load it. (This is distinct from the target visibility of the underlying .bzl source file, which governs whether the file may appear as a dependency of other targets.) Load visibility works at the level of packages: To load a module the file doing the loading must live in a package that has been granted visibility to the module. A module can always be loaded within its own package, regardless of its visibility. + +`visibility()` may only be called once per .bzl file, and only at the top level, not inside a function. The preferred style is to put this call immediately below the `load()` statements and any brief logic needed to determine the argument. + +If the flag `--check_bzl_visibility` is set to false, load visibility violations will emit warnings but not fail the build. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="visibility.value"><code>value</code></td> +<td>required<br /> +A list of package specification strings, or a single package specification string. +<p>Package specifications follow the same format as for <a href="/reference/be/functions#package_group"><code>package_group</code></a>, except that negative package specifications are not permitted. That is, a specification may have the forms:</p> +<ul> +<li><code>"//foo"</code>: the package <code>//foo</code></li> +<li><code>"//foo/..."</code>: the package <code>//foo</code> and all of its subpackages.</li> +<li><code>"public"</code> or <code>"private"</code>: all packages or no packages, respectively</li> +</ul> +<p>The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository.</p> +<p>If <code>value</code> is a list of strings, the set of packages granted visibility to this module is the union of the packages represented by each specification. (An empty list has the same effect as <code>private</code>.) If <code>value</code> is a single string, it is treated as if it were the singleton list <code>[value]</code>.</p> +<p>Note that the flags <code>--incompatible_package_group_has_public_syntax</code> and <code>--incompatible_fix_package_group_reporoot_syntax</code> have no effect on this argument. The <code>"public"</code> and <code>"private"</code> values are always available, and <code>"//..."</code> is always interpreted as "all packages in the current repository".</p></td> +</tr> +</tbody> +</table> diff --git a/rules/lib/globals/module.mdx b/rules/lib/globals/module.mdx index 43c378b..2091e8a 100644 --- a/rules/lib/globals/module.mdx +++ b/rules/lib/globals/module.mdx @@ -2,946 +2,702 @@ title: 'module' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.module">MODULE.bazel files</h1> +# MODULE.bazel files {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Methods available in MODULE.bazel files. -<h2>Members</h2> -<ul> - <li> - <a href="#archive_override">archive_override</a> - </li> - <li> - <a href="#bazel_dep">bazel_dep</a> - </li> - <li> - <a href="#flag_alias">flag_alias</a> - </li> - <li> - <a href="#git_override">git_override</a> - </li> - <li> - <a href="#include">include</a> - </li> - <li> - <a href="#inject_repo">inject_repo</a> - </li> - <li> - <a href="#local_path_override">local_path_override</a> - </li> - <li> - <a href="#module">module</a> - </li> - <li> - <a href="#multiple_version_override">multiple_version_override</a> - </li> - <li> - <a href="#override_repo">override_repo</a> - </li> - <li> - <a href="#register_execution_platforms">register_execution_platforms</a> - </li> - <li> - <a href="#register_toolchains">register_toolchains</a> - </li> - <li> - <a href="#single_version_override">single_version_override</a> - </li> - <li> - <a href="#use_extension">use_extension</a> - </li> - <li> - <a href="#use_repo">use_repo</a> - </li> - <li> - <a href="#use_repo_rule">use_repo_rule</a> - </li> - </ul> - - <h2 id="archive_override">archive_override</h2> - <p><pre class="rule-signature"><code>None</code> archive_override(*, module_name, **kwargs)</pre></p> - - Specifies that this dependency should come from an archive file (zip, gzip, etc) at a +## Members + +- [archive_override](#archive_override) +- [bazel_dep](#bazel_dep) +- [flag_alias](#flag_alias) +- [git_override](#git_override) +- [include](#include) +- [inject_repo](#inject_repo) +- [local_path_override](#local_path_override) +- [module](#module) +- [multiple_version_override](#multiple_version_override) +- [override_repo](#override_repo) +- [register_execution_platforms](#register_execution_platforms) +- [register_toolchains](#register_toolchains) +- [single_version_override](#single_version_override) +- [use_extension](#use_extension) +- [use_repo](#use_repo) +- [use_repo_rule](#use_repo_rule) + +## archive_override + +``` rule-signature +None archive_override(*, module_name, **kwargs) +``` + +Specifies that this dependency should come from an archive file (zip, gzip, etc) at a certain location, instead of from a registry. Effectively, this dependency will be -backed by an <a href="../repo/http#http_archive"><code>http_archive</code></a> rule. +backed by an [`http_archive`](../repo/http#http_archive) rule. -<p>This directive only takes effect in the root module; in other words, if a module is +This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="archive_override.module_name"> - <code>module_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the Bazel module dependency to apply this override to. - </td> - </tr> - <tr> - <td id="archive_override.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - All other arguments are forwarded to the underlying <code>http_archive</code> repo + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="archive_override.module_name"><code>module_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the Bazel module dependency to apply this override to.</td> +</tr> +<tr> +<td id="archive_override.kwargs"><code>kwargs</code></td> +<td>required<br /> +All other arguments are forwarded to the underlying <code>http_archive</code> repo rule. Note that the <code>name</code> attribute shouldn't be specified; use -<code>module_name</code> instead. - </td> - </tr> - </tbody> - </table> - - <h2 id="bazel_dep">bazel_dep</h2> - <p><pre class="rule-signature"><code>None</code> bazel_dep(*, name, version='', max_compatibility_level=-1, repo_name='', dev_dependency=False)</pre></p> - - Declares a direct dependency on another Bazel module. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="bazel_dep.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the module to be added as a direct dependency. - </td> - </tr> - <tr> - <td id="bazel_dep.version"> - <code>version</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The version of the module to be added as a direct dependency. - </td> - </tr> - <tr> - <td id="bazel_dep.max_compatibility_level"> - <code>max_compatibility_level</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>-1</code><br/> - The maximum <code>compatibility_level</code> supported for the module to be added as a direct dependency. The version of the module implies the minimum compatibility_level supported, as well as the maximum if this attribute is not specified. - </td> - </tr> - <tr> - <td id="bazel_dep.repo_name"> - <code>repo_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>''</code><br/> - The name of the external repo representing this dependency. This is by default the +<code>module_name</code> instead.</td> +</tr> +</tbody> +</table> + +## bazel_dep + +``` rule-signature +None bazel_dep(*, name, version='', max_compatibility_level=-1, repo_name='', dev_dependency=False) +``` + +Declares a direct dependency on another Bazel module. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="bazel_dep.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the module to be added as a direct dependency.</td> +</tr> +<tr> +<td id="bazel_dep.version"><code>version</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The version of the module to be added as a direct dependency.</td> +</tr> +<tr> +<td id="bazel_dep.max_compatibility_level"><code>max_compatibility_level</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>-1</code><br /> +The maximum <code>compatibility_level</code> supported for the module to be added as a direct dependency. The version of the module implies the minimum compatibility_level supported, as well as the maximum if this attribute is not specified.</td> +</tr> +<tr> +<td id="bazel_dep.repo_name"><code>repo_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>''</code><br /> +The name of the external repo representing this dependency. This is by default the name of the module. Can be set to <code>None</code> to make this dependency a "<em>nodep</em>" dependency: in this case, this <code>bazel_dep</code> specification is only honored if the target module already exists in the dependency graph by some -other means. - - </td> - </tr> - <tr> - <td id="bazel_dep.dev_dependency"> - <code>dev_dependency</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, this dependency will be ignored if the current module is not the root module or <code>--ignore_dev_dependency</code> is enabled. - </td> - </tr> - </tbody> - </table> - - <h2 id="flag_alias">flag_alias</h2> - <p><pre class="rule-signature"><code>None</code> flag_alias(name, starlark_flag)</pre></p> - - Maps a command-line flag --foo to a Starlark flag --@repo//defs:foo. Bazel translates all - instances of $ bazel build //target --foo to $ bazel build //target --@repo//defs:foo. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="flag_alias.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the flag. - </td> - </tr> - <tr> - <td id="flag_alias.starlark_flag"> - <code>starlark_flag</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The label of the Starlark flag to alias to. - </td> - </tr> - </tbody> - </table> - - <h2 id="git_override">git_override</h2> - <p><pre class="rule-signature"><code>None</code> git_override(*, module_name, **kwargs)</pre></p> - - Specifies that this dependency should come from a certain commit in a Git repository, +other means.</td> +</tr> +<tr> +<td id="bazel_dep.dev_dependency"><code>dev_dependency</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, this dependency will be ignored if the current module is not the root module or <code>--ignore_dev_dependency</code> is enabled.</td> +</tr> +</tbody> +</table> + +## flag_alias + +``` rule-signature +None flag_alias(name, starlark_flag) +``` + +Maps a command-line flag --foo to a Starlark flag --@repo//defs:foo. Bazel translates all +instances of \$ bazel build //target --foo to \$ bazel build //target --@repo//defs:foo. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="flag_alias.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the flag.</td> +</tr> +<tr> +<td id="flag_alias.starlark_flag"><code>starlark_flag</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The label of the Starlark flag to alias to.</td> +</tr> +</tbody> +</table> + +## git_override + +``` rule-signature +None git_override(*, module_name, **kwargs) +``` + +Specifies that this dependency should come from a certain commit in a Git repository, instead of from a registry. Effectively, this dependency will be backed by a -<a href="../repo/git#git_repository"><code>git_repository</code></a> rule. +[`git_repository`](../repo/git#git_repository) rule. -<p>This directive only takes effect in the root module; in other words, if a module is +This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="git_override.module_name"> - <code>module_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the Bazel module dependency to apply this override to. - </td> - </tr> - <tr> - <td id="git_override.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - All other arguments are forwarded to the underlying <code>git_repository</code> + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="git_override.module_name"><code>module_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the Bazel module dependency to apply this override to.</td> +</tr> +<tr> +<td id="git_override.kwargs"><code>kwargs</code></td> +<td>required<br /> +All other arguments are forwarded to the underlying <code>git_repository</code> repo rule. Note that the <code>name</code> attribute shouldn't be specified; use -<code>module_name</code> instead. - </td> - </tr> - </tbody> - </table> - - <h2 id="include">include</h2> - <p><pre class="rule-signature"><code>None</code> include(label)</pre></p> - - Includes the contents of another MODULE.bazel-like file. Effectively, <code>include()</code> behaves as if the included file is textually placed at the location of the <code>include()</code> call, except that variable bindings (such as those used for <code>use_extension</code>) are only ever visible in the file they occur in, not in any included or including files.<p>Only the root module may use <code>include()</code>; it is an error if a <code>bazel_dep</code>'s MODULE file uses <code>include()</code>.<p>Only files in the main repo may be included.<p><code>include()</code> allows you to segment the root module file into multiple parts, to avoid having an enormous MODULE.bazel file or to better manage access control for individual semantic segments. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="include.label"> - <code>label</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The label pointing to the file to include. The label must point to a file in the main repo; in other words, it <strong>must<strong> start with double slashes (<code>//</code>). The name of the file must end with <code>.MODULE.bazel</code> and must not start with <code>.</code>. - </td> - </tr> - </tbody> - </table> - - <h2 id="inject_repo">inject_repo</h2> - <p><pre class="rule-signature"><code>None</code> inject_repo(extension_proxy, *args, **kwargs)</pre></p> - - Injects one or more new repos into the given module extension. +<code>module_name</code> instead.</td> +</tr> +</tbody> +</table> + +## include + +``` rule-signature +None include(label) +``` + +Includes the contents of another MODULE.bazel-like file. Effectively, `include()` behaves as if the included file is textually placed at the location of the `include()` call, except that variable bindings (such as those used for `use_extension`) are only ever visible in the file they occur in, not in any included or including files. + +Only the root module may use `include()`; it is an error if a `bazel_dep`'s MODULE file uses `include()`. + +Only files in the main repo may be included. + +`include()` allows you to segment the root module file into multiple parts, to avoid having an enormous MODULE.bazel file or to better manage access control for individual semantic segments. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="include.label"><code>label</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The label pointing to the file to include. The label must point to a file in the main repo; in other words, it +must +start with double slashes (<code>//</code>). The name of the file must end with <code>.MODULE.bazel</code> and must not start with <code>.</code>.</td> +</tr> +</tbody> +</table> + +## inject_repo + +``` rule-signature +None inject_repo(extension_proxy, *args, **kwargs) +``` + +Injects one or more new repos into the given module extension. This is ignored if the current module is not the root module or -<code>--ignore_dev_dependency</code> is enabled. +`--ignore_dev_dependency` is enabled. -<p>Use <a href="#override_repo"><code>override_repo</code></a> instead to override an +Use [`override_repo`](#override_repo) instead to override an existing repo. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="inject_repo.extension_proxy"> - <code>extension_proxy</code> - </td> - <td> - module_extension_proxy; - required<br/> - A module extension proxy object returned by a <code>use_extension</code> call. - </td> - </tr> - <tr> - <td id="inject_repo.args"> - <code>args</code> - </td> - <td> - required<br/> - The repos visible to the current module that should be injected into the -extension under the same name. - </td> - </tr> - <tr> - <td id="inject_repo.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - The new repos to inject into the extension, where the values are the names of + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="inject_repo.extension_proxy"><code>extension_proxy</code></td> +<td>module_extension_proxy; +required<br /> +A module extension proxy object returned by a <code>use_extension</code> call.</td> +</tr> +<tr> +<td id="inject_repo.args"><code>args</code></td> +<td>required<br /> +The repos visible to the current module that should be injected into the +extension under the same name.</td> +</tr> +<tr> +<td id="inject_repo.kwargs"><code>kwargs</code></td> +<td>required<br /> +The new repos to inject into the extension, where the values are the names of repos in the scope of the current module and the keys are the name they will be visible under in the extension. <p>Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., -<code>inject_repo(extension_proxy, **{"foo.2": "foo"})</code>. +<code>inject_repo(extension_proxy, **{"foo.2": "foo"})</code>.</p></td> +</tr> +</tbody> +</table> - </td> - </tr> - </tbody> - </table> +## local_path_override - <h2 id="local_path_override">local_path_override</h2> - <p><pre class="rule-signature"><code>None</code> local_path_override(*, module_name, path)</pre></p> +``` rule-signature +None local_path_override(*, module_name, path) +``` - Specifies that this dependency should come from a certain directory on local disk, +Specifies that this dependency should come from a certain directory on local disk, instead of from a registry. Effectively, this dependency will be backed by a -<a href="../repo/local#local_repository"><code>local_repository</code></a> rule. +[`local_repository`](../repo/local#local_repository) rule. -<p>This directive only takes effect in the root module; in other words, if a module is +This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="local_path_override.module_name"> - <code>module_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the Bazel module dependency to apply this override to. - </td> - </tr> - <tr> - <td id="local_path_override.path"> - <code>path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The path to the directory where this module is. - </td> - </tr> - </tbody> - </table> - - <h2 id="module">module</h2> - <p><pre class="rule-signature"><code>None</code> module(*, name='', version='', compatibility_level=0, repo_name='', bazel_compatibility=[])</pre></p> - - Declares certain properties of the Bazel module represented by the current Bazel repo. These properties are either essential metadata of the module (such as the name and version), or affect behavior of the current module and its dependents. <p>It should be called at most once, and if called, it must be the very first directive in the MODULE.bazel file. It can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="module.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The name of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). A valid module name must: 1) only contain lowercase letters (a-z), digits (0-9), dots (.), hyphens (-), and underscores (_); 2) begin with a lowercase letter; 3) end with a lowercase letter or digit. - </td> - </tr> - <tr> - <td id="module.version"> - <code>version</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The version of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). The version must be in a relaxed SemVer format; see <a href="/external/module#version_format">the documentation</a> for more details. - </td> - </tr> - <tr> - <td id="module.compatibility_level"> - <code>compatibility_level</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>0</code><br/> - The compatibility level of the module; this should be changed every time a major incompatible change is introduced. This is essentially the "major version" of the module in terms of SemVer, except that it's not embedded in the version string itself, but exists as a separate field. Modules with different compatibility levels participate in version resolution as if they're modules with different names, but the final dependency graph cannot contain multiple modules with the same name but different compatibility levels (unless <code>multiple_version_override</code> is in effect). See <a href="/external/module#compatibility_level">the documentation</a> for more details. - </td> - </tr> - <tr> - <td id="module.repo_name"> - <code>repo_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The name of the repository representing this module, as seen by the module itself. By default, the name of the repo is the name of the module. This can be specified to ease migration for projects that have been using a repo name for itself that differs from its module name. - </td> - </tr> - <tr> - <td id="module.bazel_compatibility"> - <code>bazel_compatibility</code> - </td> - <td> - Iterable of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A list of bazel versions that allows users to declare which Bazel versions are compatible with this module. It does NOT affect dependency resolution, but bzlmod will use this information to check if your current Bazel version is compatible. The format of this value is a string of some constraint values separated by comma. Three constraints are supported: <=X.X.X: The Bazel version must be equal or older than X.X.X. Used when there is a known incompatible change in a newer version. >=X.X.X: The Bazel version must be equal or newer than X.X.X.Used when you depend on some features that are only available since X.X.X. -X.X.X: The Bazel version X.X.X is not compatible. Used when there is a bug in X.X.X that breaks you, but fixed in later versions. - </td> - </tr> - </tbody> - </table> - - <h2 id="multiple_version_override">multiple_version_override</h2> - <p><pre class="rule-signature"><code>None</code> multiple_version_override(*, module_name, versions, registry='')</pre></p> - - Specifies that a dependency should still come from a registry, but multiple versions of it should be allowed to coexist. See <a href="/external/module#multiple-version_override">the documentation</a> for more details. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="multiple_version_override.module_name"> - <code>module_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the Bazel module dependency to apply this override to. - </td> - </tr> - <tr> - <td id="multiple_version_override.versions"> - <code>versions</code> - </td> - <td> - Iterable of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - Explicitly specifies the versions allowed to coexist. These versions must already be present in the dependency graph pre-selection. Dependencies on this module will be "upgraded" to the nearest higher allowed version at the same compatibility level, whereas dependencies that have a higher version than any allowed versions at the same compatibility level will cause an error. - </td> - </tr> - <tr> - <td id="multiple_version_override.registry"> - <code>registry</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. - </td> - </tr> - </tbody> - </table> - - <h2 id="override_repo">override_repo</h2> - <p><pre class="rule-signature"><code>None</code> override_repo(extension_proxy, *args, **kwargs)</pre></p> - - Overrides one or more repos defined by the given module extension with the given repos + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="local_path_override.module_name"><code>module_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the Bazel module dependency to apply this override to.</td> +</tr> +<tr> +<td id="local_path_override.path"><code>path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The path to the directory where this module is.</td> +</tr> +</tbody> +</table> + +## module + +``` rule-signature +None module(*, name='', version='', compatibility_level=0, repo_name='', bazel_compatibility=[]) +``` + +Declares certain properties of the Bazel module represented by the current Bazel repo. These properties are either essential metadata of the module (such as the name and version), or affect behavior of the current module and its dependents. + +It should be called at most once, and if called, it must be the very first directive in the MODULE.bazel file. It can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="module.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The name of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). A valid module name must: 1) only contain lowercase letters (a-z), digits (0-9), dots (.), hyphens (-), and underscores (_); 2) begin with a lowercase letter; 3) end with a lowercase letter or digit.</td> +</tr> +<tr> +<td id="module.version"><code>version</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The version of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). The version must be in a relaxed SemVer format; see <a href="/external/module#version_format">the documentation</a> for more details.</td> +</tr> +<tr> +<td id="module.compatibility_level"><code>compatibility_level</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>0</code><br /> +The compatibility level of the module; this should be changed every time a major incompatible change is introduced. This is essentially the "major version" of the module in terms of SemVer, except that it's not embedded in the version string itself, but exists as a separate field. Modules with different compatibility levels participate in version resolution as if they're modules with different names, but the final dependency graph cannot contain multiple modules with the same name but different compatibility levels (unless <code>multiple_version_override</code> is in effect). See <a href="/external/module#compatibility_level">the documentation</a> for more details.</td> +</tr> +<tr> +<td id="module.repo_name"><code>repo_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The name of the repository representing this module, as seen by the module itself. By default, the name of the repo is the name of the module. This can be specified to ease migration for projects that have been using a repo name for itself that differs from its module name.</td> +</tr> +<tr> +<td id="module.bazel_compatibility"><code>bazel_compatibility</code></td> +<td>Iterable of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A list of bazel versions that allows users to declare which Bazel versions are compatible with this module. It does NOT affect dependency resolution, but bzlmod will use this information to check if your current Bazel version is compatible. The format of this value is a string of some constraint values separated by comma. Three constraints are supported: <=X.X.X: The Bazel version must be equal or older than X.X.X. Used when there is a known incompatible change in a newer version. >=X.X.X: The Bazel version must be equal or newer than X.X.X.Used when you depend on some features that are only available since X.X.X. -X.X.X: The Bazel version X.X.X is not compatible. Used when there is a bug in X.X.X that breaks you, but fixed in later versions.</td> +</tr> +</tbody> +</table> + +## multiple_version_override + +``` rule-signature +None multiple_version_override(*, module_name, versions, registry='') +``` + +Specifies that a dependency should still come from a registry, but multiple versions of it should be allowed to coexist. See [the documentation](/external/module#multiple-version_override) for more details. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="multiple_version_override.module_name"><code>module_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the Bazel module dependency to apply this override to.</td> +</tr> +<tr> +<td id="multiple_version_override.versions"><code>versions</code></td> +<td>Iterable of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +Explicitly specifies the versions allowed to coexist. These versions must already be present in the dependency graph pre-selection. Dependencies on this module will be "upgraded" to the nearest higher allowed version at the same compatibility level, whereas dependencies that have a higher version than any allowed versions at the same compatibility level will cause an error.</td> +</tr> +<tr> +<td id="multiple_version_override.registry"><code>registry</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used.</td> +</tr> +</tbody> +</table> + +## override_repo + +``` rule-signature +None override_repo(extension_proxy, *args, **kwargs) +``` + +Overrides one or more repos defined by the given module extension with the given repos visible to the current module. This is ignored if the current module is not the root -module or `--ignore_dev_dependency` is enabled. - -<p>Use <a href="#inject_repo"><code>inject_repo</code></a> instead to add a new repo. - - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="override_repo.extension_proxy"> - <code>extension_proxy</code> - </td> - <td> - module_extension_proxy; - required<br/> - A module extension proxy object returned by a <code>use_extension</code> call. - </td> - </tr> - <tr> - <td id="override_repo.args"> - <code>args</code> - </td> - <td> - required<br/> - The repos in the extension that should be overridden with the repos of the same -name in the current module. - </td> - </tr> - <tr> - <td id="override_repo.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - The overrides to apply to the repos generated by the extension, where the values +module or \`--ignore_dev_dependency\` is enabled. + +Use [`inject_repo`](#inject_repo) instead to add a new repo. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="override_repo.extension_proxy"><code>extension_proxy</code></td> +<td>module_extension_proxy; +required<br /> +A module extension proxy object returned by a <code>use_extension</code> call.</td> +</tr> +<tr> +<td id="override_repo.args"><code>args</code></td> +<td>required<br /> +The repos in the extension that should be overridden with the repos of the same +name in the current module.</td> +</tr> +<tr> +<td id="override_repo.kwargs"><code>kwargs</code></td> +<td>required<br /> +The overrides to apply to the repos generated by the extension, where the values are the names of repos in the scope of the current module and the keys are the names of the repos they will override in the extension. <p>Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., -<code>override_repo(extension_proxy, **{"foo.2": "foo"})</code>. - - </td> - </tr> - </tbody> - </table> - - <h2 id="register_execution_platforms">register_execution_platforms</h2> - <p><pre class="rule-signature"><code>None</code> register_execution_platforms(*platform_labels, dev_dependency=False)</pre></p> - - Specifies already-defined execution platforms to be registered when this module is selected. Should be absolute <a href='https://bazel.build/reference/glossary#target-pattern'>target patterns</a> (ie. beginning with either <code>@</code> or <code>//</code>). See <a href="/docs/toolchains">toolchain resolution</a> for more information. Patterns that expand to multiple targets, such as <code>:all</code>, will be registered in lexicographical order by name. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="register_execution_platforms.dev_dependency"> - <code>dev_dependency</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the execution platforms will not be registered if the current module is not the root module or `--ignore_dev_dependency` is enabled. - </td> - </tr> - <tr> - <td id="register_execution_platforms.platform_labels"> - <code>platform_labels</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The target patterns to register. - </td> - </tr> - </tbody> - </table> - - <h2 id="register_toolchains">register_toolchains</h2> - <p><pre class="rule-signature"><code>None</code> register_toolchains(*toolchain_labels, dev_dependency=False)</pre></p> - - Specifies already-defined toolchains to be registered when this module is selected. Should be absolute <a href='https://bazel.build/reference/glossary#target-pattern'>target patterns</a> (ie. beginning with either <code>@</code> or <code>//</code>). See <a href="/docs/toolchains">toolchain resolution</a> for more information. Patterns that expand to multiple targets, such as <code>:all</code>, will be registered in lexicographical order by target name (not the name of the toolchain implementation). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="register_toolchains.dev_dependency"> - <code>dev_dependency</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the toolchains will not be registered if the current module is not the root module or `--ignore_dev_dependency` is enabled. - </td> - </tr> - <tr> - <td id="register_toolchains.toolchain_labels"> - <code>toolchain_labels</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The target patterns to register. - </td> - </tr> - </tbody> - </table> - - <h2 id="single_version_override">single_version_override</h2> - <p><pre class="rule-signature"><code>None</code> single_version_override(*, module_name, version='', registry='', patches=[], patch_cmds=[], patch_strip=0)</pre></p> - - Specifies that a dependency should still come from a registry, but its version should be pinned, or its registry overridden, or a list of patches applied. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="single_version_override.module_name"> - <code>module_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the Bazel module dependency to apply this override to. - </td> - </tr> - <tr> - <td id="single_version_override.version"> - <code>version</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Overrides the declared version of this module in the dependency graph. In other words, this module will be "pinned" to this override version. This attribute can be omitted if all one wants to override is the registry or the patches. - </td> - </tr> - <tr> - <td id="single_version_override.registry"> - <code>registry</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. - </td> - </tr> - <tr> - <td id="single_version_override.patches"> - <code>patches</code> - </td> - <td> - Iterable of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A list of labels pointing to patch files to apply for this module. The patch files must exist in the source tree of the top level project. They are applied in the list order.<p>If a patch makes changes to the MODULE.bazel file, these changes will only be effective if the patch file is provided by the root module. - </td> - </tr> - <tr> - <td id="single_version_override.patch_cmds"> - <code>patch_cmds</code> - </td> - <td> - Iterable of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Sequence of Bash commands to be applied on Linux/Macos after patches are applied.<p>Changes to the MODULE.bazel file will not be effective. - </td> - </tr> - <tr> - <td id="single_version_override.patch_strip"> - <code>patch_strip</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>0</code><br/> - Same as the --strip argument of Unix patch. - </td> - </tr> - </tbody> - </table> - - <h2 id="use_extension">use_extension</h2> - <p><pre class="rule-signature">module_extension_proxy use_extension(extension_bzl_file, extension_name, *, dev_dependency=False, isolate=False)</pre></p> - - Returns a proxy object representing a module extension; its methods can be invoked to create module extension tags. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="use_extension.extension_bzl_file"> - <code>extension_bzl_file</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A label to the Starlark file defining the module extension. - </td> - </tr> - <tr> - <td id="use_extension.extension_name"> - <code>extension_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the module extension to use. A symbol with this name must be exported by the Starlark file. - </td> - </tr> - <tr> - <td id="use_extension.dev_dependency"> - <code>dev_dependency</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, this usage of the module extension will be ignored if the current module is not the root module or `--ignore_dev_dependency` is enabled. - </td> - </tr> - <tr> - <td id="use_extension.isolate"> - <code>isolate</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - <b>Experimental</b>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_isolated_extension_usages</code> <br>If true, this usage of the module extension will be isolated from all other usages, both in this and other modules. Tags created for this usage do not affect other usages and the repositories generated by the extension for this usage will be distinct from all other repositories generated by the extension.<p>This parameter is currently experimental and only available with the flag <code>--experimental_isolated_extension_usages</code>. - </td> - </tr> - </tbody> - </table> - - <h2 id="use_repo">use_repo</h2> - <p><pre class="rule-signature"><code>None</code> use_repo(extension_proxy, *args, **kwargs)</pre></p> - - Imports one or more repos generated by the given module extension into the scope of the current module. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="use_repo.extension_proxy"> - <code>extension_proxy</code> - </td> - <td> - module_extension_proxy; - required<br/> - A module extension proxy object returned by a <code>use_extension</code> call. - </td> - </tr> - <tr> - <td id="use_repo.args"> - <code>args</code> - </td> - <td> - required<br/> - The names of the repos to import. - </td> - </tr> - <tr> - <td id="use_repo.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - Specifies certain repos to import into the scope of the current module with +<code>override_repo(extension_proxy, **{"foo.2": "foo"})</code>.</p></td> +</tr> +</tbody> +</table> + +## register_execution_platforms + +``` rule-signature +None register_execution_platforms(*platform_labels, dev_dependency=False) +``` + +Specifies already-defined execution platforms to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](/docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by name. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="register_execution_platforms.dev_dependency"><code>dev_dependency</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the execution platforms will not be registered if the current module is not the root module or `--ignore_dev_dependency` is enabled.</td> +</tr> +<tr> +<td id="register_execution_platforms.platform_labels"><code>platform_labels</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The target patterns to register.</td> +</tr> +</tbody> +</table> + +## register_toolchains + +``` rule-signature +None register_toolchains(*toolchain_labels, dev_dependency=False) +``` + +Specifies already-defined toolchains to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](/docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by target name (not the name of the toolchain implementation). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="register_toolchains.dev_dependency"><code>dev_dependency</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the toolchains will not be registered if the current module is not the root module or `--ignore_dev_dependency` is enabled.</td> +</tr> +<tr> +<td id="register_toolchains.toolchain_labels"><code>toolchain_labels</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The target patterns to register.</td> +</tr> +</tbody> +</table> + +## single_version_override + +``` rule-signature +None single_version_override(*, module_name, version='', registry='', patches=[], patch_cmds=[], patch_strip=0) +``` + +Specifies that a dependency should still come from a registry, but its version should be pinned, or its registry overridden, or a list of patches applied. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="single_version_override.module_name"><code>module_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the Bazel module dependency to apply this override to.</td> +</tr> +<tr> +<td id="single_version_override.version"><code>version</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Overrides the declared version of this module in the dependency graph. In other words, this module will be "pinned" to this override version. This attribute can be omitted if all one wants to override is the registry or the patches.</td> +</tr> +<tr> +<td id="single_version_override.registry"><code>registry</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used.</td> +</tr> +<tr> +<td id="single_version_override.patches"><code>patches</code></td> +<td>Iterable of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A list of labels pointing to patch files to apply for this module. The patch files must exist in the source tree of the top level project. They are applied in the list order. +<p>If a patch makes changes to the MODULE.bazel file, these changes will only be effective if the patch file is provided by the root module.</p></td> +</tr> +<tr> +<td id="single_version_override.patch_cmds"><code>patch_cmds</code></td> +<td>Iterable of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Sequence of Bash commands to be applied on Linux/Macos after patches are applied. +<p>Changes to the MODULE.bazel file will not be effective.</p></td> +</tr> +<tr> +<td id="single_version_override.patch_strip"><code>patch_strip</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>0</code><br /> +Same as the --strip argument of Unix patch.</td> +</tr> +</tbody> +</table> + +## use_extension + +``` rule-signature +module_extension_proxy use_extension(extension_bzl_file, extension_name, *, dev_dependency=False, isolate=False) +``` + +Returns a proxy object representing a module extension; its methods can be invoked to create module extension tags. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="use_extension.extension_bzl_file"><code>extension_bzl_file</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A label to the Starlark file defining the module extension.</td> +</tr> +<tr> +<td id="use_extension.extension_name"><code>extension_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the module extension to use. A symbol with this name must be exported by the Starlark file.</td> +</tr> +<tr> +<td id="use_extension.dev_dependency"><code>dev_dependency</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, this usage of the module extension will be ignored if the current module is not the root module or `--ignore_dev_dependency` is enabled.</td> +</tr> +<tr> +<td id="use_extension.isolate"><code>isolate</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +<strong>Experimental</strong>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_isolated_extension_usages</code><br /> +If true, this usage of the module extension will be isolated from all other usages, both in this and other modules. Tags created for this usage do not affect other usages and the repositories generated by the extension for this usage will be distinct from all other repositories generated by the extension. +<p>This parameter is currently experimental and only available with the flag <code>--experimental_isolated_extension_usages</code>.</p></td> +</tr> +</tbody> +</table> + +## use_repo + +``` rule-signature +None use_repo(extension_proxy, *args, **kwargs) +``` + +Imports one or more repos generated by the given module extension into the scope of the current module. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="use_repo.extension_proxy"><code>extension_proxy</code></td> +<td>module_extension_proxy; +required<br /> +A module extension proxy object returned by a <code>use_extension</code> call.</td> +</tr> +<tr> +<td id="use_repo.args"><code>args</code></td> +<td>required<br /> +The names of the repos to import.</td> +</tr> +<tr> +<td id="use_repo.kwargs"><code>kwargs</code></td> +<td>required<br /> +Specifies certain repos to import into the scope of the current module with different names. The keys should be the name to use in the current scope, whereas the values should be the original names exported by the module extension. <p>Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., -<code>use_repo(extension_proxy, **{"foo.2": "foo"})</code>. - - </td> - </tr> - </tbody> - </table> - - <h2 id="use_repo_rule">use_repo_rule</h2> - <p><pre class="rule-signature">repo_rule_proxy use_repo_rule(repo_rule_bzl_file, repo_rule_name)</pre></p> - - Returns a proxy value that can be directly invoked in the MODULE.bazel file as a repository rule, one or more times. Repos created in such a way are only visible to the current module, under the name declared using the <code>name</code> attribute on the proxy. The implicit Boolean <code>dev_dependency</code> attribute can also be used on the proxy to denote that a certain repo is only to be created when the current module is the root module. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="use_repo_rule.repo_rule_bzl_file"> - <code>repo_rule_bzl_file</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A label to the Starlark file defining the repo rule. - </td> - </tr> - <tr> - <td id="use_repo_rule.repo_rule_name"> - <code>repo_rule_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the repo rule to use. A symbol with this name must be exported by the Starlark file. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +<code>use_repo(extension_proxy, **{"foo.2": "foo"})</code>.</p></td> +</tr> +</tbody> +</table> + +## use_repo_rule + +``` rule-signature +repo_rule_proxy use_repo_rule(repo_rule_bzl_file, repo_rule_name) +``` + +Returns a proxy value that can be directly invoked in the MODULE.bazel file as a repository rule, one or more times. Repos created in such a way are only visible to the current module, under the name declared using the `name` attribute on the proxy. The implicit Boolean `dev_dependency` attribute can also be used on the proxy to denote that a certain repo is only to be created when the current module is the root module. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="use_repo_rule.repo_rule_bzl_file"><code>repo_rule_bzl_file</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A label to the Starlark file defining the repo rule.</td> +</tr> +<tr> +<td id="use_repo_rule.repo_rule_name"><code>repo_rule_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the repo rule to use. A symbol with this name must be exported by the Starlark file.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/globals/repo.mdx b/rules/lib/globals/repo.mdx index 7bd98fd..979443f 100644 --- a/rules/lib/globals/repo.mdx +++ b/rules/lib/globals/repo.mdx @@ -2,96 +2,68 @@ title: 'repo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.repo">REPO.bazel files</h1> +# REPO.bazel files {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Methods available in REPO.bazel files. -<h2>Members</h2> -<ul> - <li> - <a href="#ignore_directories">ignore_directories</a> - </li> - <li> - <a href="#repo">repo</a> - </li> - </ul> +## Members + +- [ignore_directories](#ignore_directories) +- [repo](#repo) + +## ignore_directories + +``` rule-signature +None ignore_directories(dirs) +``` + +The list of directories to ignore in this repository. - <h2 id="ignore_directories">ignore_directories</h2> - <p><pre class="rule-signature"><code>None</code> ignore_directories(dirs)</pre></p> +This function takes a list of strings and a directory is ignored if any of the given strings matches its repository-relative path according to the semantics of the `glob()` function. This function can be used to ignore directories that are implementation details of source control systems, output files of other build systems, etc. - The list of directories to ignore in this repository. <p>This function takes a list of strings and a directory is ignored if any of the given strings matches its repository-relative path according to the semantics of the <code>glob()</code> function. This function can be used to ignore directories that are implementation details of source control systems, output files of other build systems, etc. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="ignore_directories.dirs"> - <code>dirs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> +### Parameters - </td> - </tr> - </tbody> - </table> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="ignore_directories.dirs"><code>dirs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +</td> +</tr> +</tbody> +</table> - <h2 id="repo">repo</h2> - <p><pre class="rule-signature"><code>None</code> repo(**kwargs)</pre></p> +## repo - Declares metadata that applies to every rule in the repository. It must be called at most once per REPO.bazel file. If called, it must be the first call in the REPO.bazel file. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="repo.kwargs"> - <code>kwargs</code> - </td> - <td> - required<br/> - The <code>repo()</code> function accepts exactly the same arguments as the <a href="/reference/be/functions#package"><code>package()</code></a> function in BUILD files. - </td> - </tr> - </tbody> - </table> +``` rule-signature +None repo(**kwargs) +``` +Declares metadata that applies to every rule in the repository. It must be called at most once per REPO.bazel file. If called, it must be the first call in the REPO.bazel file. -</body> -</html> +### Parameters -<!-- {% endraw %} --> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="repo.kwargs"><code>kwargs</code></td> +<td>required<br /> +The <code>repo()</code> function accepts exactly the same arguments as the <a href="/reference/be/functions#package"><code>package()</code></a> function in BUILD files.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/globals/vendor.mdx b/rules/lib/globals/vendor.mdx index 8cc6169..bda7740 100644 --- a/rules/lib/globals/vendor.mdx +++ b/rules/lib/globals/vendor.mdx @@ -2,95 +2,65 @@ title: 'vendor' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.vendor">VENDOR.bazel files</h1> +# VENDOR.bazel files {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Methods available in VENDOR.bazel files. -<h2>Members</h2> -<ul> - <li> - <a href="#ignore">ignore</a> - </li> - <li> - <a href="#pin">pin</a> - </li> - </ul> +## Members + +- [ignore](#ignore) +- [pin](#pin) + +## ignore + +``` rule-signature +None ignore(*args) +``` + +Ignore this repo from vendoring. Bazel will never vendor it or use the corresponding directory (if exists) while building in vendor mode. - <h2 id="ignore">ignore</h2> - <p><pre class="rule-signature"><code>None</code> ignore(*args)</pre></p> +### Parameters - Ignore this repo from vendoring. Bazel will never vendor it or use the corresponding directory (if exists) while building in vendor mode. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="ignore.args"> - <code>args</code> - </td> - <td> - required<br/> - The canonical repo names of the repos to ignore. - </td> - </tr> - </tbody> - </table> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="ignore.args"><code>args</code></td> +<td>required<br /> +The canonical repo names of the repos to ignore.</td> +</tr> +</tbody> +</table> - <h2 id="pin">pin</h2> - <p><pre class="rule-signature"><code>None</code> pin(*args)</pre></p> +## pin - Pin the contents of this repo under the vendor directory. Bazel will not update this repo while vendoring, and will use the vendored source as if there is a --override_repository flag when building in vendor mode - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="pin.args"> - <code>args</code> - </td> - <td> - required<br/> - The canonical repo names of the repos to pin. - </td> - </tr> - </tbody> - </table> +``` rule-signature +None pin(*args) +``` +Pin the contents of this repo under the vendor directory. Bazel will not update this repo while vendoring, and will use the vendored source as if there is a --override_repository flag when building in vendor mode -</body> -</html> +### Parameters -<!-- {% endraw %} --> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="pin.args"><code>args</code></td> +<td>required<br /> +The canonical repo names of the repos to pin.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/overview.mdx b/rules/lib/overview.mdx index 523d812..4740201 100644 --- a/rules/lib/overview.mdx +++ b/rules/lib/overview.mdx @@ -2,1093 +2,153 @@ title: 'overview' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> -<h1 class="page-title">One-Page Overview</h1> +# One-Page Overview {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm" %} -{% include "_buttons.html" %} -<h2> - - - <a href="/rules/lib/globals">Global functions</a> - - -</h2> -<ul> - - <li> - - - <a href="/rules/lib/globals/bzl">.bzl files</a> - - </li> - - - <li> - - - <a href="/rules/lib/globals/all">All Bazel files</a> - - </li> - - - <li> - - - <a href="/rules/lib/globals/build">BUILD files</a> - - </li> - - - <li> - - - <a href="/rules/lib/globals/module">MODULE.bazel files</a> - - </li> - - - <li> - - - <a href="/rules/lib/globals/repo">REPO.bazel files</a> - - </li> - - - <li> - - - <a href="/rules/lib/globals/vendor">VENDOR.bazel files</a> - - </li> - -</ul> -<h2> - - - <a href="/rules/lib/fragments">Configuration Fragments</a> - - -</h2> -<ul> - - <li> - - - <a href="/rules/lib/fragments/apple">apple</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/bazel_android">bazel_android</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/bazel_py">bazel_py</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/coverage">coverage</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/cpp">cpp</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/j2objc">j2objc</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/java">java</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/objc">objc</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/platform">platform</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/proto">proto</a> - - </li> - - - <li> - - - <a href="/rules/lib/fragments/py">py</a> - - </li> - -</ul> -<h2> - - - <a href="/rules/lib/providers">Providers</a> - - -</h2> -<ul> - - <li> - - - <a href="/rules/lib/providers/AnalysisTestResultInfo">AnalysisTestResultInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/CcInfo">CcInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/CcToolchainConfigInfo">CcToolchainConfigInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/CcToolchainInfo">CcToolchainInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/ConstraintCollection">ConstraintCollection</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/ConstraintSettingInfo">ConstraintSettingInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/ConstraintValueInfo">ConstraintValueInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/DebugPackageInfo">DebugPackageInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/DefaultInfo">DefaultInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/ExecutionInfo">ExecutionInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/FeatureFlagInfo">FeatureFlagInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/file_provider">file_provider</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/FilesToRunProvider">FilesToRunProvider</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/IncompatiblePlatformProvider">IncompatiblePlatformProvider</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/InstrumentedFilesInfo">InstrumentedFilesInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/java_compilation_info">java_compilation_info</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/java_output_jars">java_output_jars</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/JavaRuntimeInfo">JavaRuntimeInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/JavaToolchainInfo">JavaToolchainInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/MaterializedDepsInfo">MaterializedDepsInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/ObjcProvider">ObjcProvider</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/OutputGroupInfo">OutputGroupInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/PackageSpecificationInfo">PackageSpecificationInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/PlatformInfo">PlatformInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/RunEnvironmentInfo">RunEnvironmentInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/TemplateVariableInfo">TemplateVariableInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/ToolchainInfo">ToolchainInfo</a> - - </li> - - - <li> - - - <a href="/rules/lib/providers/ToolchainTypeInfo">ToolchainTypeInfo</a> - - </li> - -</ul> -<h2> - - - <a href="/rules/lib/builtins">Built-in Types</a> - - -</h2> -<ul> - - <li> - - - <a href="/rules/lib/builtins/Action">Action</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/actions">actions</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/apple_platform">apple_platform</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/Args">Args</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/Aspect">Aspect</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/Attribute">Attribute</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/bazel_module">bazel_module</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/bazel_module_tags">bazel_module_tags</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/BuildSetting">BuildSetting</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/CcCompilationOutputs">CcCompilationOutputs</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/CcLinkingOutputs">CcLinkingOutputs</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/CompilationContext">CompilationContext</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/configuration">configuration</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/ctx">ctx</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/depset">depset</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/DirectoryExpander">DirectoryExpander</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/DottedVersion">DottedVersion</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/exec_result">exec_result</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/ExecGroupCollection">ExecGroupCollection</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/ExecGroupContext">ExecGroupContext</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/ExecTransitionFactory">ExecTransitionFactory</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/ExpandedDirectory">ExpandedDirectory</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/extension_metadata">extension_metadata</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/FeatureConfiguration">FeatureConfiguration</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/File">File</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/fragments">fragments</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/java_annotation_processing">java_annotation_processing</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/Label">Label</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/LateBoundDefault">LateBoundDefault</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/LibraryToLink">LibraryToLink</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/License">License</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/LinkerInput">LinkerInput</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/LinkingContext">LinkingContext</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/macro">macro</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/mapped_root">mapped_root</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/module_ctx">module_ctx</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/path">path</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/propagation_ctx">propagation_ctx</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/Provider">Provider</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/repo_metadata">repo_metadata</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/repository_ctx">repository_ctx</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/repository_os">repository_os</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/repository_rule">repository_rule</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/root">root</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/rule">rule</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/rule_attributes">rule_attributes</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/runfiles">runfiles</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/struct">struct</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/Subrule">Subrule</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/subrule_ctx">subrule_ctx</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/SymlinkEntry">SymlinkEntry</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/tag_class">tag_class</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/Target">Target</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/template_ctx">template_ctx</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/TemplateDict">TemplateDict</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/toolchain_type">toolchain_type</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/ToolchainContext">ToolchainContext</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/transition">transition</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/wasm_exec_result">wasm_exec_result</a> - - </li> - - - <li> - - - <a href="/rules/lib/builtins/wasm_module">wasm_module</a> - - </li> - -</ul> -<h2> - - - <a href="/rules/lib/toplevel">Top-level Modules</a> - - -</h2> -<ul> - - <li> - - - <a href="/rules/lib/toplevel/apple_common">apple_common</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/attr">attr</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/cc_common">cc_common</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/config">config</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/config_common">config_common</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/coverage_common">coverage_common</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/java_common">java_common</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/native">native</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/platform_common">platform_common</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/proto">proto</a> - - </li> - - - <li> - - - <a href="/rules/lib/toplevel/testing">testing</a> - - </li> - -</ul> -<h2> - - - <a href="/rules/lib/core">Core Starlark data types</a> - - -</h2> -<ul> - - <li> - - - <a href="/rules/lib/core/bool">bool</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/builtin_function_or_method">builtin_function_or_method</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/dict">dict</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/float">float</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/function">function</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/int">int</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/json">json</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/list">list</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/range">range</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/set">set</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/string">string</a> - - </li> - - - <li> - - - <a href="/rules/lib/core/tuple">tuple</a> - - </li> - -</ul> -</body> -</html> +{% include "\_buttons.html" %} + +## [Global functions](/rules/lib/globals) + +- [.bzl files](/rules/lib/globals/bzl) +- [All Bazel files](/rules/lib/globals/all) +- [BUILD files](/rules/lib/globals/build) +- [MODULE.bazel files](/rules/lib/globals/module) +- [REPO.bazel files](/rules/lib/globals/repo) +- [VENDOR.bazel files](/rules/lib/globals/vendor) + +## [Configuration Fragments](/rules/lib/fragments) + +- [apple](/rules/lib/fragments/apple) +- [bazel_android](/rules/lib/fragments/bazel_android) +- [bazel_py](/rules/lib/fragments/bazel_py) +- [coverage](/rules/lib/fragments/coverage) +- [cpp](/rules/lib/fragments/cpp) +- [j2objc](/rules/lib/fragments/j2objc) +- [java](/rules/lib/fragments/java) +- [objc](/rules/lib/fragments/objc) +- [platform](/rules/lib/fragments/platform) +- [proto](/rules/lib/fragments/proto) +- [py](/rules/lib/fragments/py) + +## [Providers](/rules/lib/providers) + +- [AnalysisTestResultInfo](/rules/lib/providers/AnalysisTestResultInfo) +- [CcInfo](/rules/lib/providers/CcInfo) +- [CcToolchainConfigInfo](/rules/lib/providers/CcToolchainConfigInfo) +- [CcToolchainInfo](/rules/lib/providers/CcToolchainInfo) +- [ConstraintCollection](/rules/lib/providers/ConstraintCollection) +- [ConstraintSettingInfo](/rules/lib/providers/ConstraintSettingInfo) +- [ConstraintValueInfo](/rules/lib/providers/ConstraintValueInfo) +- [DebugPackageInfo](/rules/lib/providers/DebugPackageInfo) +- [DefaultInfo](/rules/lib/providers/DefaultInfo) +- [ExecutionInfo](/rules/lib/providers/ExecutionInfo) +- [FeatureFlagInfo](/rules/lib/providers/FeatureFlagInfo) +- [file_provider](/rules/lib/providers/file_provider) +- [FilesToRunProvider](/rules/lib/providers/FilesToRunProvider) +- [IncompatiblePlatformProvider](/rules/lib/providers/IncompatiblePlatformProvider) +- [InstrumentedFilesInfo](/rules/lib/providers/InstrumentedFilesInfo) +- [java_compilation_info](/rules/lib/providers/java_compilation_info) +- [java_output_jars](/rules/lib/providers/java_output_jars) +- [JavaRuntimeInfo](/rules/lib/providers/JavaRuntimeInfo) +- [JavaToolchainInfo](/rules/lib/providers/JavaToolchainInfo) +- [MaterializedDepsInfo](/rules/lib/providers/MaterializedDepsInfo) +- [ObjcProvider](/rules/lib/providers/ObjcProvider) +- [OutputGroupInfo](/rules/lib/providers/OutputGroupInfo) +- [PackageSpecificationInfo](/rules/lib/providers/PackageSpecificationInfo) +- [PlatformInfo](/rules/lib/providers/PlatformInfo) +- [RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo) +- [TemplateVariableInfo](/rules/lib/providers/TemplateVariableInfo) +- [ToolchainInfo](/rules/lib/providers/ToolchainInfo) +- [ToolchainTypeInfo](/rules/lib/providers/ToolchainTypeInfo) + +## [Built-in Types](/rules/lib/builtins) + +- [Action](/rules/lib/builtins/Action) +- [actions](/rules/lib/builtins/actions) +- [apple_platform](/rules/lib/builtins/apple_platform) +- [Args](/rules/lib/builtins/Args) +- [Aspect](/rules/lib/builtins/Aspect) +- [Attribute](/rules/lib/builtins/Attribute) +- [bazel_module](/rules/lib/builtins/bazel_module) +- [bazel_module_tags](/rules/lib/builtins/bazel_module_tags) +- [BuildSetting](/rules/lib/builtins/BuildSetting) +- [CcCompilationOutputs](/rules/lib/builtins/CcCompilationOutputs) +- [CcLinkingOutputs](/rules/lib/builtins/CcLinkingOutputs) +- [CompilationContext](/rules/lib/builtins/CompilationContext) +- [configuration](/rules/lib/builtins/configuration) +- [ctx](/rules/lib/builtins/ctx) +- [depset](/rules/lib/builtins/depset) +- [DirectoryExpander](/rules/lib/builtins/DirectoryExpander) +- [DottedVersion](/rules/lib/builtins/DottedVersion) +- [exec_result](/rules/lib/builtins/exec_result) +- [ExecGroupCollection](/rules/lib/builtins/ExecGroupCollection) +- [ExecGroupContext](/rules/lib/builtins/ExecGroupContext) +- [ExecTransitionFactory](/rules/lib/builtins/ExecTransitionFactory) +- [ExpandedDirectory](/rules/lib/builtins/ExpandedDirectory) +- [extension_metadata](/rules/lib/builtins/extension_metadata) +- [FeatureConfiguration](/rules/lib/builtins/FeatureConfiguration) +- [File](/rules/lib/builtins/File) +- [fragments](/rules/lib/builtins/fragments) +- [java_annotation_processing](/rules/lib/builtins/java_annotation_processing) +- [Label](/rules/lib/builtins/Label) +- [LateBoundDefault](/rules/lib/builtins/LateBoundDefault) +- [LibraryToLink](/rules/lib/builtins/LibraryToLink) +- [License](/rules/lib/builtins/License) +- [LinkerInput](/rules/lib/builtins/LinkerInput) +- [LinkingContext](/rules/lib/builtins/LinkingContext) +- [macro](/rules/lib/builtins/macro) +- [mapped_root](/rules/lib/builtins/mapped_root) +- [module_ctx](/rules/lib/builtins/module_ctx) +- [path](/rules/lib/builtins/path) +- [propagation_ctx](/rules/lib/builtins/propagation_ctx) +- [Provider](/rules/lib/builtins/Provider) +- [repo_metadata](/rules/lib/builtins/repo_metadata) +- [repository_ctx](/rules/lib/builtins/repository_ctx) +- [repository_os](/rules/lib/builtins/repository_os) +- [repository_rule](/rules/lib/builtins/repository_rule) +- [root](/rules/lib/builtins/root) +- [rule](/rules/lib/builtins/rule) +- [rule_attributes](/rules/lib/builtins/rule_attributes) +- [runfiles](/rules/lib/builtins/runfiles) +- [struct](/rules/lib/builtins/struct) +- [Subrule](/rules/lib/builtins/Subrule) +- [subrule_ctx](/rules/lib/builtins/subrule_ctx) +- [SymlinkEntry](/rules/lib/builtins/SymlinkEntry) +- [tag_class](/rules/lib/builtins/tag_class) +- [Target](/rules/lib/builtins/Target) +- [template_ctx](/rules/lib/builtins/template_ctx) +- [TemplateDict](/rules/lib/builtins/TemplateDict) +- [toolchain_type](/rules/lib/builtins/toolchain_type) +- [ToolchainContext](/rules/lib/builtins/ToolchainContext) +- [transition](/rules/lib/builtins/transition) +- [wasm_exec_result](/rules/lib/builtins/wasm_exec_result) +- [wasm_module](/rules/lib/builtins/wasm_module) + +## [Top-level Modules](/rules/lib/toplevel) + +- [apple_common](/rules/lib/toplevel/apple_common) +- [attr](/rules/lib/toplevel/attr) +- [cc_common](/rules/lib/toplevel/cc_common) +- [config](/rules/lib/toplevel/config) +- [config_common](/rules/lib/toplevel/config_common) +- [coverage_common](/rules/lib/toplevel/coverage_common) +- [java_common](/rules/lib/toplevel/java_common) +- [native](/rules/lib/toplevel/native) +- [platform_common](/rules/lib/toplevel/platform_common) +- [proto](/rules/lib/toplevel/proto) +- [testing](/rules/lib/toplevel/testing) + +## [Core Starlark data types](/rules/lib/core) + +- [bool](/rules/lib/core/bool) +- [builtin_function_or_method](/rules/lib/core/builtin_function_or_method) +- [dict](/rules/lib/core/dict) +- [float](/rules/lib/core/float) +- [function](/rules/lib/core/function) +- [int](/rules/lib/core/int) +- [json](/rules/lib/core/json) +- [list](/rules/lib/core/list) +- [range](/rules/lib/core/range) +- [set](/rules/lib/core/set) +- [string](/rules/lib/core/string) +- [tuple](/rules/lib/core/tuple) diff --git a/rules/lib/providers.mdx b/rules/lib/providers.mdx index 4254fc1..ab815e6 100644 --- a/rules/lib/providers.mdx +++ b/rules/lib/providers.mdx @@ -2,75 +2,37 @@ title: 'providers' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> -<h1 class="page-title">Providers</h1> +# Providers {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} -This section lists providers available on built-in rules. See the <a href='https://bazel.build/extending/rules#providers'>Rules page</a> for more on providers. These symbols are available only in .bzl files. - -<ul> - -<li><a href="/rules/lib/providers/AnalysisTestResultInfo">AnalysisTestResultInfo</a></li> - -<li><a href="/rules/lib/providers/CcInfo">CcInfo</a></li> - -<li><a href="/rules/lib/providers/CcToolchainConfigInfo">CcToolchainConfigInfo</a></li> - -<li><a href="/rules/lib/providers/CcToolchainInfo">CcToolchainInfo</a></li> - -<li><a href="/rules/lib/providers/ConstraintCollection">ConstraintCollection</a></li> - -<li><a href="/rules/lib/providers/ConstraintSettingInfo">ConstraintSettingInfo</a></li> - -<li><a href="/rules/lib/providers/ConstraintValueInfo">ConstraintValueInfo</a></li> - -<li><a href="/rules/lib/providers/DebugPackageInfo">DebugPackageInfo</a></li> - -<li><a href="/rules/lib/providers/DefaultInfo">DefaultInfo</a></li> - -<li><a href="/rules/lib/providers/ExecutionInfo">ExecutionInfo</a></li> - -<li><a href="/rules/lib/providers/FeatureFlagInfo">FeatureFlagInfo</a></li> - -<li><a href="/rules/lib/providers/file_provider">file_provider</a></li> - -<li><a href="/rules/lib/providers/FilesToRunProvider">FilesToRunProvider</a></li> - -<li><a href="/rules/lib/providers/IncompatiblePlatformProvider">IncompatiblePlatformProvider</a></li> - -<li><a href="/rules/lib/providers/InstrumentedFilesInfo">InstrumentedFilesInfo</a></li> - -<li><a href="/rules/lib/providers/java_compilation_info">java_compilation_info</a></li> - -<li><a href="/rules/lib/providers/java_output_jars">java_output_jars</a></li> - -<li><a href="/rules/lib/providers/JavaRuntimeInfo">JavaRuntimeInfo</a></li> - -<li><a href="/rules/lib/providers/JavaToolchainInfo">JavaToolchainInfo</a></li> - -<li><a href="/rules/lib/providers/MaterializedDepsInfo">MaterializedDepsInfo</a></li> - -<li><a href="/rules/lib/providers/ObjcProvider">ObjcProvider</a></li> - -<li><a href="/rules/lib/providers/OutputGroupInfo">OutputGroupInfo</a></li> - -<li><a href="/rules/lib/providers/PackageSpecificationInfo">PackageSpecificationInfo</a></li> - -<li><a href="/rules/lib/providers/PlatformInfo">PlatformInfo</a></li> - -<li><a href="/rules/lib/providers/RunEnvironmentInfo">RunEnvironmentInfo</a></li> - -<li><a href="/rules/lib/providers/TemplateVariableInfo">TemplateVariableInfo</a></li> - -<li><a href="/rules/lib/providers/ToolchainInfo">ToolchainInfo</a></li> - -<li><a href="/rules/lib/providers/ToolchainTypeInfo">ToolchainTypeInfo</a></li> -</ul> -</body> -</html> +{% include "\_buttons.html" %} +This section lists providers available on built-in rules. See the [Rules page](https://bazel.build/extending/rules#providers) for more on providers. These symbols are available only in .bzl files. + +- [AnalysisTestResultInfo](/rules/lib/providers/AnalysisTestResultInfo) +- [CcInfo](/rules/lib/providers/CcInfo) +- [CcToolchainConfigInfo](/rules/lib/providers/CcToolchainConfigInfo) +- [CcToolchainInfo](/rules/lib/providers/CcToolchainInfo) +- [ConstraintCollection](/rules/lib/providers/ConstraintCollection) +- [ConstraintSettingInfo](/rules/lib/providers/ConstraintSettingInfo) +- [ConstraintValueInfo](/rules/lib/providers/ConstraintValueInfo) +- [DebugPackageInfo](/rules/lib/providers/DebugPackageInfo) +- [DefaultInfo](/rules/lib/providers/DefaultInfo) +- [ExecutionInfo](/rules/lib/providers/ExecutionInfo) +- [FeatureFlagInfo](/rules/lib/providers/FeatureFlagInfo) +- [file_provider](/rules/lib/providers/file_provider) +- [FilesToRunProvider](/rules/lib/providers/FilesToRunProvider) +- [IncompatiblePlatformProvider](/rules/lib/providers/IncompatiblePlatformProvider) +- [InstrumentedFilesInfo](/rules/lib/providers/InstrumentedFilesInfo) +- [java_compilation_info](/rules/lib/providers/java_compilation_info) +- [java_output_jars](/rules/lib/providers/java_output_jars) +- [JavaRuntimeInfo](/rules/lib/providers/JavaRuntimeInfo) +- [JavaToolchainInfo](/rules/lib/providers/JavaToolchainInfo) +- [MaterializedDepsInfo](/rules/lib/providers/MaterializedDepsInfo) +- [ObjcProvider](/rules/lib/providers/ObjcProvider) +- [OutputGroupInfo](/rules/lib/providers/OutputGroupInfo) +- [PackageSpecificationInfo](/rules/lib/providers/PackageSpecificationInfo) +- [PlatformInfo](/rules/lib/providers/PlatformInfo) +- [RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo) +- [TemplateVariableInfo](/rules/lib/providers/TemplateVariableInfo) +- [ToolchainInfo](/rules/lib/providers/ToolchainInfo) +- [ToolchainTypeInfo](/rules/lib/providers/ToolchainTypeInfo) diff --git a/rules/lib/providers/AnalysisTestResultInfo.mdx b/rules/lib/providers/AnalysisTestResultInfo.mdx index 0121624..d1bbd00 100644 --- a/rules/lib/providers/AnalysisTestResultInfo.mdx +++ b/rules/lib/providers/AnalysisTestResultInfo.mdx @@ -2,88 +2,63 @@ title: 'AnalysisTestResultInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.AnalysisTestResultInfo">AnalysisTestResultInfo</h1> +# AnalysisTestResultInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/AnalysisTestResultInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +Encapsulates the result of analyis-phase testing. Build targets which return an instance of this provider signal to the build system that it should generate a 'stub' test executable which generates the equivalent test result. Analysis test rules (rules created with `analysis_test=True` **must** return an instance of this provider, and non-analysis-phase test rules **cannot** return this provider. + +## Members + +- [AnalysisTestResultInfo](#AnalysisTestResultInfo) +- [message](#message) +- [success](#success) -Encapsulates the result of analyis-phase testing. Build targets which return an instance of this provider signal to the build system that it should generate a 'stub' test executable which generates the equivalent test result. Analysis test rules (rules created with <code>analysis_test=True</code> <b>must</b> return an instance of this provider, and non-analysis-phase test rules <b>cannot</b> return this provider. +## AnalysisTestResultInfo -<h2>Members</h2> -<ul> - <li> - <a href="#AnalysisTestResultInfo">AnalysisTestResultInfo</a> - </li> - <li> - <a href="#message">message</a> - </li> - <li> - <a href="#success">success</a> - </li> - </ul> +``` rule-signature +AnalysisTestResultInfo AnalysisTestResultInfo(success, message) +``` - <h2 id="AnalysisTestResultInfo">AnalysisTestResultInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/AnalysisTestResultInfo.html">AnalysisTestResultInfo</a> AnalysisTestResultInfo(success, message)</pre></p> +The `AnalysisTestResultInfo` constructor. - The <code>AnalysisTestResultInfo</code> constructor. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="AnalysisTestResultInfo.success"> - <code>success</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - required<br/> - If true, then the analysis-phase test represented by this target should pass. If false, the test should fail. - </td> - </tr> - <tr> - <td id="AnalysisTestResultInfo.message"> - <code>message</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A descriptive message containing information about the test and its success/failure. - </td> - </tr> - </tbody> - </table> +### Parameters - <h2 id="message">message</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> AnalysisTestResultInfo.message</pre></p> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="AnalysisTestResultInfo.success"><code>success</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +required<br /> +If true, then the analysis-phase test represented by this target should pass. If false, the test should fail.</td> +</tr> +<tr> +<td id="AnalysisTestResultInfo.message"><code>message</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +A descriptive message containing information about the test and its success/failure.</td> +</tr> +</tbody> +</table> - A descriptive message containing information about the test and its success/failure. +## message - <h2 id="success">success</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> AnalysisTestResultInfo.success</pre></p> +``` rule-signature +string AnalysisTestResultInfo.message +``` - If true, then the analysis-phase test represented by this target passed. If false, the test failed. +A descriptive message containing information about the test and its success/failure. +## success -</body> -</html> +``` rule-signature +bool AnalysisTestResultInfo.success +``` -<!-- {% endraw %} --> +If true, then the analysis-phase test represented by this target passed. If false, the test failed. diff --git a/rules/lib/providers/CcInfo.mdx b/rules/lib/providers/CcInfo.mdx index fb7fc77..2120d5a 100644 --- a/rules/lib/providers/CcInfo.mdx +++ b/rules/lib/providers/CcInfo.mdx @@ -2,98 +2,69 @@ title: 'CcInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.CcInfo">CcInfo</h1> +# CcInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A provider for compilation and linking of C++. This is also a marking provider telling C++ rules that they can depend on the rule with this provider. If it is not intended for the rule to be depended on by C++, the rule should wrap the CcInfo in some other provider. -<h2>Members</h2> -<ul> - <li> - <a href="#CcInfo">CcInfo</a> - </li> - <li> - <a href="#compilation_context">compilation_context</a> - </li> - <li> - <a href="#linking_context">linking_context</a> - </li> - </ul> +## Members + +- [CcInfo](#CcInfo) +- [compilation_context](#compilation_context) +- [linking_context](#linking_context) + +## CcInfo + +``` rule-signature +CcInfo CcInfo(*, compilation_context=None, linking_context=None, debug_context=None) +``` - <h2 id="CcInfo">CcInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/CcInfo.html">CcInfo</a> CcInfo(*, compilation_context=None, linking_context=None, debug_context=None)</pre></p> +The `CcInfo` constructor. - The <code>CcInfo</code> constructor. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="CcInfo.compilation_context"> - <code>compilation_context</code> - </td> - <td> - <a class="anchor" href="../builtins/CompilationContext.html">CompilationContext</a>; or <code>None</code>; - default is <code>None</code><br/> - The <code>CompilationContext</code>. - </td> - </tr> - <tr> - <td id="CcInfo.linking_context"> - <code>linking_context</code> - </td> - <td> - <a class="anchor" href="../builtins/struct.html">struct</a>; or <code>None</code>; - default is <code>None</code><br/> - The <code>LinkingContext</code>. - </td> - </tr> - <tr> - <td id="CcInfo.debug_context"> - <code>debug_context</code> - </td> - <td> - <a class="anchor" href="../builtins/struct.html">struct</a>; or <code>None</code>; - default is <code>None</code><br/> - The <code>DebugContext</code>. - </td> - </tr> - </tbody> - </table> +### Parameters - <h2 id="compilation_context">compilation_context</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/CompilationContext.html">CompilationContext</a> CcInfo.compilation_context</pre></p> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="CcInfo.compilation_context"><code>compilation_context</code></td> +<td><a href="../builtins/CompilationContext.html" class="anchor">CompilationContext</a>; or <code>None</code>; +default is <code>None</code><br /> +The <code>CompilationContext</code>.</td> +</tr> +<tr> +<td id="CcInfo.linking_context"><code>linking_context</code></td> +<td><a href="../builtins/struct.html" class="anchor">struct</a>; or <code>None</code>; +default is <code>None</code><br /> +The <code>LinkingContext</code>.</td> +</tr> +<tr> +<td id="CcInfo.debug_context"><code>debug_context</code></td> +<td><a href="../builtins/struct.html" class="anchor">struct</a>; or <code>None</code>; +default is <code>None</code><br /> +The <code>DebugContext</code>.</td> +</tr> +</tbody> +</table> - Returns the <code>CompilationContext</code> +## compilation_context - <h2 id="linking_context">linking_context</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> CcInfo.linking_context</pre></p> +``` rule-signature +CompilationContext CcInfo.compilation_context +``` - Returns the <code>LinkingContext</code> +Returns the `CompilationContext` +## linking_context -</body> -</html> +``` rule-signature +struct CcInfo.linking_context +``` -<!-- {% endraw %} --> +Returns the `LinkingContext` diff --git a/rules/lib/providers/CcToolchainConfigInfo.mdx b/rules/lib/providers/CcToolchainConfigInfo.mdx index 2b5d5c5..788e882 100644 --- a/rules/lib/providers/CcToolchainConfigInfo.mdx +++ b/rules/lib/providers/CcToolchainConfigInfo.mdx @@ -2,24 +2,8 @@ title: 'CcToolchainConfigInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.CcToolchainConfigInfo">CcToolchainConfigInfo</h1> +# CcToolchainConfigInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcToolchainConfigInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Additional layer of configurability for C++ rules. Encapsulates platform-dependent specifics of C++ actions through features and action configs. It is used to configure the C++ toolchain, and later on for command line construction. Replaces the functionality of CROSSTOOL file. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/providers/CcToolchainInfo.mdx b/rules/lib/providers/CcToolchainInfo.mdx index 495d795..a45733d 100644 --- a/rules/lib/providers/CcToolchainInfo.mdx +++ b/rules/lib/providers/CcToolchainInfo.mdx @@ -2,257 +2,236 @@ title: 'CcToolchainInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.CcToolchainInfo">CcToolchainInfo</h1> +# CcToolchainInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcToolchainProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Information about the C++ compiler being used. -<h2>Members</h2> -<ul> - <li> - <a href="#all_files">all_files</a> - </li> - <li> - <a href="#ar_executable">ar_executable</a> - </li> - <li> - <a href="#built_in_include_directories">built_in_include_directories</a> - </li> - <li> - <a href="#compiler">compiler</a> - </li> - <li> - <a href="#compiler_executable">compiler_executable</a> - </li> - <li> - <a href="#cpu">cpu</a> - </li> - <li> - <a href="#dynamic_runtime_lib">dynamic_runtime_lib</a> - </li> - <li> - <a href="#gcov_executable">gcov_executable</a> - </li> - <li> - <a href="#ld_executable">ld_executable</a> - </li> - <li> - <a href="#libc">libc</a> - </li> - <li> - <a href="#needs_pic_for_dynamic_libraries">needs_pic_for_dynamic_libraries</a> - </li> - <li> - <a href="#nm_executable">nm_executable</a> - </li> - <li> - <a href="#objcopy_executable">objcopy_executable</a> - </li> - <li> - <a href="#objdump_executable">objdump_executable</a> - </li> - <li> - <a href="#preprocessor_executable">preprocessor_executable</a> - </li> - <li> - <a href="#static_runtime_lib">static_runtime_lib</a> - </li> - <li> - <a href="#strip_executable">strip_executable</a> - </li> - <li> - <a href="#sysroot">sysroot</a> - </li> - <li> - <a href="#target_gnu_system_name">target_gnu_system_name</a> - </li> - </ul> - - <h2 id="all_files">all_files</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.all_files</pre></p> - - Returns all toolchain files (so they can be passed to actions using this toolchain as inputs). - - <h2 id="ar_executable">ar_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.ar_executable</pre></p> - - The path to the ar binary. - - <h2 id="built_in_include_directories">built_in_include_directories</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.built_in_include_directories</pre></p> - - Returns the list of built-in directories of the compiler. - - <h2 id="compiler">compiler</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.compiler</pre></p> - - C++ compiler. - - <h2 id="compiler_executable">compiler_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.compiler_executable</pre></p> - - The path to the compiler binary. - - <h2 id="cpu">cpu</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.cpu</pre></p> - - Target CPU of the C++ toolchain. - - <h2 id="dynamic_runtime_lib">dynamic_runtime_lib</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.dynamic_runtime_lib(*, feature_configuration)</pre></p> - - Returns the files from `dynamic_runtime_lib` attribute (so they can be passed to actions using this toolchain as inputs). The caller can check whether the feature_configuration enables `static_link_cpp_runtimes` feature (if not, neither `static_runtime_lib` nor `dynamic_runtime_lib` have to be used), and use `static_runtime_lib` if static linking mode is active. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="dynamic_runtime_lib.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - required<br/> - Feature configuration to be queried. - </td> - </tr> - </tbody> - </table> - - <h2 id="gcov_executable">gcov_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.gcov_executable</pre></p> - - The path to the gcov binary. - - <h2 id="ld_executable">ld_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.ld_executable</pre></p> - - The path to the ld binary. - - <h2 id="libc">libc</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.libc</pre></p> - - libc version string. - - <h2 id="needs_pic_for_dynamic_libraries">needs_pic_for_dynamic_libraries</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.needs_pic_for_dynamic_libraries(*, feature_configuration)</pre></p> - - Returns true if this rule's compilations should apply -fPIC, false otherwise. Determines if we should apply -fPIC for this rule's C++ compilations depending on the C++ toolchain and presence of `--force_pic` Bazel option. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="needs_pic_for_dynamic_libraries.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - required<br/> - Feature configuration to be queried. - </td> - </tr> - </tbody> - </table> - - <h2 id="nm_executable">nm_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.nm_executable</pre></p> - - The path to the nm binary. - - <h2 id="objcopy_executable">objcopy_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.objcopy_executable</pre></p> - - The path to the objcopy binary. - - <h2 id="objdump_executable">objdump_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.objdump_executable</pre></p> - - The path to the objdump binary. - - <h2 id="preprocessor_executable">preprocessor_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.preprocessor_executable</pre></p> - - The path to the preprocessor binary. - - <h2 id="static_runtime_lib">static_runtime_lib</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.static_runtime_lib(*, feature_configuration)</pre></p> - - Returns the files from `static_runtime_lib` attribute (so they can be passed to actions using this toolchain as inputs). The caller should check whether the feature_configuration enables `static_link_cpp_runtimes` feature (if not, neither `static_runtime_lib` nor `dynamic_runtime_lib` should be used), and use `dynamic_runtime_lib` if dynamic linking mode is active. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="static_runtime_lib.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - required<br/> - Feature configuration to be queried. - </td> - </tr> - </tbody> - </table> - - <h2 id="strip_executable">strip_executable</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.strip_executable</pre></p> - - The path to the strip binary. - - <h2 id="sysroot">sysroot</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.sysroot</pre></p> - - Returns the sysroot to be used. If the toolchain compiler does not support different sysroots, or the sysroot is the same as the default sysroot, then this method returns <code>None</code>. - - <h2 id="target_gnu_system_name">target_gnu_system_name</h2> - <p><pre class="rule-signature"><code>None</code> CcToolchainInfo.target_gnu_system_name</pre></p> - - The GNU System Name. - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [all_files](#all_files) +- [ar_executable](#ar_executable) +- [built_in_include_directories](#built_in_include_directories) +- [compiler](#compiler) +- [compiler_executable](#compiler_executable) +- [cpu](#cpu) +- [dynamic_runtime_lib](#dynamic_runtime_lib) +- [gcov_executable](#gcov_executable) +- [ld_executable](#ld_executable) +- [libc](#libc) +- [needs_pic_for_dynamic_libraries](#needs_pic_for_dynamic_libraries) +- [nm_executable](#nm_executable) +- [objcopy_executable](#objcopy_executable) +- [objdump_executable](#objdump_executable) +- [preprocessor_executable](#preprocessor_executable) +- [static_runtime_lib](#static_runtime_lib) +- [strip_executable](#strip_executable) +- [sysroot](#sysroot) +- [target_gnu_system_name](#target_gnu_system_name) + +## all_files + +``` rule-signature +None CcToolchainInfo.all_files +``` + +Returns all toolchain files (so they can be passed to actions using this toolchain as inputs). + +## ar_executable + +``` rule-signature +None CcToolchainInfo.ar_executable +``` + +The path to the ar binary. + +## built_in_include_directories + +``` rule-signature +None CcToolchainInfo.built_in_include_directories +``` + +Returns the list of built-in directories of the compiler. + +## compiler + +``` rule-signature +None CcToolchainInfo.compiler +``` + +C++ compiler. + +## compiler_executable + +``` rule-signature +None CcToolchainInfo.compiler_executable +``` + +The path to the compiler binary. + +## cpu + +``` rule-signature +None CcToolchainInfo.cpu +``` + +Target CPU of the C++ toolchain. + +## dynamic_runtime_lib + +``` rule-signature +None CcToolchainInfo.dynamic_runtime_lib(*, feature_configuration) +``` + +Returns the files from \`dynamic_runtime_lib\` attribute (so they can be passed to actions using this toolchain as inputs). The caller can check whether the feature_configuration enables \`static_link_cpp_runtimes\` feature (if not, neither \`static_runtime_lib\` nor \`dynamic_runtime_lib\` have to be used), and use \`static_runtime_lib\` if static linking mode is active. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="dynamic_runtime_lib.feature_configuration"><code>feature_configuration</code></td> +<td>required<br /> +Feature configuration to be queried.</td> +</tr> +</tbody> +</table> + +## gcov_executable + +``` rule-signature +None CcToolchainInfo.gcov_executable +``` + +The path to the gcov binary. + +## ld_executable + +``` rule-signature +None CcToolchainInfo.ld_executable +``` + +The path to the ld binary. + +## libc + +``` rule-signature +None CcToolchainInfo.libc +``` + +libc version string. + +## needs_pic_for_dynamic_libraries + +``` rule-signature +None CcToolchainInfo.needs_pic_for_dynamic_libraries(*, feature_configuration) +``` + +Returns true if this rule's compilations should apply -fPIC, false otherwise. Determines if we should apply -fPIC for this rule's C++ compilations depending on the C++ toolchain and presence of \`--force_pic\` Bazel option. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="needs_pic_for_dynamic_libraries.feature_configuration"><code>feature_configuration</code></td> +<td>required<br /> +Feature configuration to be queried.</td> +</tr> +</tbody> +</table> + +## nm_executable + +``` rule-signature +None CcToolchainInfo.nm_executable +``` + +The path to the nm binary. + +## objcopy_executable + +``` rule-signature +None CcToolchainInfo.objcopy_executable +``` + +The path to the objcopy binary. + +## objdump_executable + +``` rule-signature +None CcToolchainInfo.objdump_executable +``` + +The path to the objdump binary. + +## preprocessor_executable + +``` rule-signature +None CcToolchainInfo.preprocessor_executable +``` + +The path to the preprocessor binary. + +## static_runtime_lib + +``` rule-signature +None CcToolchainInfo.static_runtime_lib(*, feature_configuration) +``` + +Returns the files from \`static_runtime_lib\` attribute (so they can be passed to actions using this toolchain as inputs). The caller should check whether the feature_configuration enables \`static_link_cpp_runtimes\` feature (if not, neither \`static_runtime_lib\` nor \`dynamic_runtime_lib\` should be used), and use \`dynamic_runtime_lib\` if dynamic linking mode is active. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="static_runtime_lib.feature_configuration"><code>feature_configuration</code></td> +<td>required<br /> +Feature configuration to be queried.</td> +</tr> +</tbody> +</table> + +## strip_executable + +``` rule-signature +None CcToolchainInfo.strip_executable +``` + +The path to the strip binary. + +## sysroot + +``` rule-signature +None CcToolchainInfo.sysroot +``` + +Returns the sysroot to be used. If the toolchain compiler does not support different sysroots, or the sysroot is the same as the default sysroot, then this method returns `None`. + +## target_gnu_system_name + +``` rule-signature +None CcToolchainInfo.target_gnu_system_name +``` + +The GNU System Name. diff --git a/rules/lib/providers/ConstraintCollection.mdx b/rules/lib/providers/ConstraintCollection.mdx index 899e483..cc2ba7c 100644 --- a/rules/lib/providers/ConstraintCollection.mdx +++ b/rules/lib/providers/ConstraintCollection.mdx @@ -2,24 +2,9 @@ title: 'ConstraintCollection' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ConstraintCollection">ConstraintCollection</h1> +# ConstraintCollection {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintCollectionApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Provides access to data about a collection of ConstraintValueInfo providers. <br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +Provides access to data about a collection of ConstraintValueInfo providers. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* diff --git a/rules/lib/providers/ConstraintSettingInfo.mdx b/rules/lib/providers/ConstraintSettingInfo.mdx index 51825f5..1635b7d 100644 --- a/rules/lib/providers/ConstraintSettingInfo.mdx +++ b/rules/lib/providers/ConstraintSettingInfo.mdx @@ -2,35 +2,21 @@ title: 'ConstraintSettingInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ConstraintSettingInfo">ConstraintSettingInfo</h1> +# ConstraintSettingInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintSettingInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A specific constraint setting that may be used to define a platform. See <a href='/docs/platforms#constraints-platforms'>Defining Constraints and Platforms</a> for more information.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> - -<h2>Members</h2> -<ul> - <li> - <a href="#has_default_constraint_value">has_default_constraint_value</a> - </li> - </ul> +{% include "\_buttons.html" %} +A specific constraint setting that may be used to define a platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* - <h2 id="has_default_constraint_value">has_default_constraint_value</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> ConstraintSettingInfo.has_default_constraint_value</pre></p> +## Members - Whether there is a default constraint_value for this setting. +- [has_default_constraint_value](#has_default_constraint_value) +## has_default_constraint_value -</body> -</html> +``` rule-signature +bool ConstraintSettingInfo.has_default_constraint_value +``` -<!-- {% endraw %} --> +Whether there is a default constraint_value for this setting. diff --git a/rules/lib/providers/ConstraintValueInfo.mdx b/rules/lib/providers/ConstraintValueInfo.mdx index e37a096..262a6fa 100644 --- a/rules/lib/providers/ConstraintValueInfo.mdx +++ b/rules/lib/providers/ConstraintValueInfo.mdx @@ -2,24 +2,9 @@ title: 'ConstraintValueInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ConstraintValueInfo">ConstraintValueInfo</h1> +# ConstraintValueInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintValueInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A value for a constraint setting that can be used to define a platform. See <a href='/docs/platforms#constraints-platforms'>Defining Constraints and Platforms</a> for more information.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +A value for a constraint setting that can be used to define a platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* diff --git a/rules/lib/providers/DebugPackageInfo.mdx b/rules/lib/providers/DebugPackageInfo.mdx index ba5c589..62e52de 100644 --- a/rules/lib/providers/DebugPackageInfo.mdx +++ b/rules/lib/providers/DebugPackageInfo.mdx @@ -2,126 +2,95 @@ title: 'DebugPackageInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.DebugPackageInfo">DebugPackageInfo</h1> +# DebugPackageInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/DebugPackageInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A provider for the binary file and its associated .dwp files, if fission is enabled.If Fission ({@url https://gcc.gnu.org/wiki/DebugFission}) is not enabled, the dwp file will be null. -<h2>Members</h2> -<ul> - <li> - <a href="#DebugPackageInfo">DebugPackageInfo</a> - </li> - <li> - <a href="#dwp_file">dwp_file</a> - </li> - <li> - <a href="#stripped_file">stripped_file</a> - </li> - <li> - <a href="#target_label">target_label</a> - </li> - <li> - <a href="#unstripped_file">unstripped_file</a> - </li> - </ul> - - <h2 id="DebugPackageInfo">DebugPackageInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/DebugPackageInfo.html">DebugPackageInfo</a> DebugPackageInfo(*, target_label, stripped_file=None, unstripped_file, dwp_file=None)</pre></p> - - The <code>DebugPackageInfo</code> constructor. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="DebugPackageInfo.target_label"> - <code>target_label</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; - required<br/> - The label for the *_binary target - </td> - </tr> - <tr> - <td id="DebugPackageInfo.stripped_file"> - <code>stripped_file</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - The stripped file (the explicit ".stripped" target) - </td> - </tr> - <tr> - <td id="DebugPackageInfo.unstripped_file"> - <code>unstripped_file</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The unstripped file (the default executable target). - </td> - </tr> - <tr> - <td id="DebugPackageInfo.dwp_file"> - <code>dwp_file</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - The .dwp file (for fission builds) or null if --fission=no. - </td> - </tr> - </tbody> - </table> - - <h2 id="dwp_file">dwp_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> DebugPackageInfo.dwp_file</pre></p> - - Returns the .dwp file (for fission builds) or null if --fission=no. - May return <code>None</code>. - - <h2 id="stripped_file">stripped_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> DebugPackageInfo.stripped_file</pre></p> - - Returns the stripped file (the explicit ".stripped" target). - May return <code>None</code>. - - <h2 id="target_label">target_label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> DebugPackageInfo.target_label</pre></p> - - Returns the label for the *_binary target - - <h2 id="unstripped_file">unstripped_file</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> DebugPackageInfo.unstripped_file</pre></p> - - Returns the unstripped file (the default executable target) - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [DebugPackageInfo](#DebugPackageInfo) +- [dwp_file](#dwp_file) +- [stripped_file](#stripped_file) +- [target_label](#target_label) +- [unstripped_file](#unstripped_file) + +## DebugPackageInfo + +``` rule-signature +DebugPackageInfo DebugPackageInfo(*, target_label, stripped_file=None, unstripped_file, dwp_file=None) +``` + +The `DebugPackageInfo` constructor. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="DebugPackageInfo.target_label"><code>target_label</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; +required<br /> +The label for the *_binary target</td> +</tr> +<tr> +<td id="DebugPackageInfo.stripped_file"><code>stripped_file</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +The stripped file (the explicit ".stripped" target)</td> +</tr> +<tr> +<td id="DebugPackageInfo.unstripped_file"><code>unstripped_file</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The unstripped file (the default executable target).</td> +</tr> +<tr> +<td id="DebugPackageInfo.dwp_file"><code>dwp_file</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +The .dwp file (for fission builds) or null if --fission=no.</td> +</tr> +</tbody> +</table> + +## dwp_file + +``` rule-signature +File DebugPackageInfo.dwp_file +``` + +Returns the .dwp file (for fission builds) or null if --fission=no. +May return `None`. + +## stripped_file + +``` rule-signature +File DebugPackageInfo.stripped_file +``` + +Returns the stripped file (the explicit ".stripped" target). +May return `None`. + +## target_label + +``` rule-signature +Label DebugPackageInfo.target_label +``` + +Returns the label for the \*\_binary target + +## unstripped_file + +``` rule-signature +File DebugPackageInfo.unstripped_file +``` + +Returns the unstripped file (the default executable target) diff --git a/rules/lib/providers/DefaultInfo.mdx b/rules/lib/providers/DefaultInfo.mdx index 5544755..2678287 100644 --- a/rules/lib/providers/DefaultInfo.mdx +++ b/rules/lib/providers/DefaultInfo.mdx @@ -2,143 +2,107 @@ title: 'DefaultInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.DefaultInfo">DefaultInfo</h1> +# DefaultInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A provider that gives general information about a target's direct and transitive files. Every rule type has this provider, even if it is not returned explicitly by the rule's implementation function. -<p> -See the <a href="https://bazel.build/extending/rules">rules</a> page for extensive guides on how to use this provider. -</p> - - -<h2>Members</h2> -<ul> - <li> - <a href="#DefaultInfo">DefaultInfo</a> - </li> - <li> - <a href="#data_runfiles">data_runfiles</a> - </li> - <li> - <a href="#default_runfiles">default_runfiles</a> - </li> - <li> - <a href="#files">files</a> - </li> - <li> - <a href="#files_to_run">files_to_run</a> - </li> - </ul> - - <h2 id="DefaultInfo">DefaultInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/DefaultInfo.html">DefaultInfo</a> DefaultInfo(*, files=None, runfiles=None, data_runfiles=None, default_runfiles=None, executable=None)</pre></p> - - The <code>DefaultInfo</code> constructor. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="DefaultInfo.files"> - <code>files</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - A <a href='../builtins/depset.html'><code>depset</code></a> of <a href='../builtins/File.html'><code>File</code></a> objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. - </td> - </tr> - <tr> - <td id="DefaultInfo.runfiles"> - <code>runfiles</code> - </td> - <td> - <a class="anchor" href="../builtins/runfiles.html">runfiles</a>; or <code>None</code>; - default is <code>None</code><br/> - <a href="../builtins/runfiles.html"><code>runfiles</code></a> descriptor describing the files that this target needs when run (e.g. via the <code>run</code> command or as a tool dependency for an action). - - </td> - </tr> - <tr> - <td id="DefaultInfo.data_runfiles"> - <code>data_runfiles</code> - </td> - <td> - <a class="anchor" href="../builtins/runfiles.html">runfiles</a>; or <code>None</code>; - default is <code>None</code><br/> - <p><b>It is recommended that you avoid using this parameter (see <a href='https://bazel.build/extending/rules#runfiles_features_to_avoid'>"runfiles features to avoid"</a>)</b></p> runfiles descriptor describing the runfiles this target needs to run when it is a dependency via the <code>data</code> attribute. - </td> - </tr> - <tr> - <td id="DefaultInfo.default_runfiles"> - <code>default_runfiles</code> - </td> - <td> - <a class="anchor" href="../builtins/runfiles.html">runfiles</a>; or <code>None</code>; - default is <code>None</code><br/> - <p><b>It is recommended that you avoid using this parameter (see <a href='https://bazel.build/extending/rules#runfiles_features_to_avoid'>"runfiles features to avoid"</a>)</b></p> runfiles descriptor describing the runfiles this target needs to run when it is a dependency via any attribute other than the <code>data</code> attribute. - </td> - </tr> - <tr> - <td id="DefaultInfo.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - If this rule is marked <a href='../globals/bzl.html#rule.executable'><code>executable</code></a> or <a href='../globals/bzl.html#rule.test'><code>test</code></a>, this is a <a href='../builtins/File.html'><code>File</code></a> object representing the file that should be executed to run the target. By default it is the predeclared output <code>ctx.outputs.executable</code> but it is recommended to pass another file (either predeclared or not) explicitly. - </td> - </tr> - </tbody> - </table> - - <h2 id="data_runfiles">data_runfiles</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> DefaultInfo.data_runfiles</pre></p> - - runfiles descriptor describing the files that this target needs when run in the condition that it is a <code>data</code> dependency attribute. Under most circumstances, use the <code>default_runfiles</code> parameter instead. See <a href='https://bazel.build/extending/rules#runfiles_features_to_avoid'>"runfiles features to avoid"</a> for details. - May return <code>None</code>. - - <h2 id="default_runfiles">default_runfiles</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/runfiles.html">runfiles</a> DefaultInfo.default_runfiles</pre></p> - - runfiles descriptor describing the files that this target needs when run (via the <code>run</code> command or as a tool dependency). - May return <code>None</code>. - - <h2 id="files">files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> DefaultInfo.files</pre></p> - - A <a href='../builtins/depset.html'><code>depset</code></a> of <a href='../builtins/File.html'><code>File</code></a> objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. - May return <code>None</code>. - - <h2 id="files_to_run">files_to_run</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> DefaultInfo.files_to_run</pre></p> - - A <a href='../providers/FilesToRunProvider.html'><code>FilesToRunProvider</code></a> object containing information about the executable and runfiles of the target. - May return <code>None</code>. - - -</body> -</html> - -<!-- {% endraw %} --> + +See the [rules](https://bazel.build/extending/rules) page for extensive guides on how to use this provider. + +## Members + +- [DefaultInfo](#DefaultInfo) +- [data_runfiles](#data_runfiles) +- [default_runfiles](#default_runfiles) +- [files](#files) +- [files_to_run](#files_to_run) + +## DefaultInfo + +``` rule-signature +DefaultInfo DefaultInfo(*, files=None, runfiles=None, data_runfiles=None, default_runfiles=None, executable=None) +``` + +The `DefaultInfo` constructor. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="DefaultInfo.files"><code>files</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +A <a href="../builtins/depset.html"><code>depset</code></a> of <a href="../builtins/File.html"><code>File</code></a> objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs.</td> +</tr> +<tr> +<td id="DefaultInfo.runfiles"><code>runfiles</code></td> +<td><a href="../builtins/runfiles.html" class="anchor">runfiles</a>; or <code>None</code>; +default is <code>None</code><br /> +<a href="../builtins/runfiles.html"><code>runfiles</code></a> descriptor describing the files that this target needs when run (e.g. via the <code>run</code> command or as a tool dependency for an action).</td> +</tr> +<tr> +<td id="DefaultInfo.data_runfiles"><code>data_runfiles</code></td> +<td><a href="../builtins/runfiles.html" class="anchor">runfiles</a>; or <code>None</code>; +default is <code>None</code><br /> + <p><strong>It is recommended that you avoid using this parameter (see <a href="https://bazel.build/extending/rules#runfiles_features_to_avoid">"runfiles features to avoid"</a>)</strong></p> +runfiles descriptor describing the runfiles this target needs to run when it is a dependency via the <code>data</code> attribute.</td> +</tr> +<tr> +<td id="DefaultInfo.default_runfiles"><code>default_runfiles</code></td> +<td><a href="../builtins/runfiles.html" class="anchor">runfiles</a>; or <code>None</code>; +default is <code>None</code><br /> + <p><strong>It is recommended that you avoid using this parameter (see <a href="https://bazel.build/extending/rules#runfiles_features_to_avoid">"runfiles features to avoid"</a>)</strong></p> +runfiles descriptor describing the runfiles this target needs to run when it is a dependency via any attribute other than the <code>data</code> attribute.</td> +</tr> +<tr> +<td id="DefaultInfo.executable"><code>executable</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +If this rule is marked <a href="../globals/bzl.html#rule.executable"><code>executable</code></a> or <a href="../globals/bzl.html#rule.test"><code>test</code></a>, this is a <a href="../builtins/File.html"><code>File</code></a> object representing the file that should be executed to run the target. By default it is the predeclared output <code>ctx.outputs.executable</code> but it is recommended to pass another file (either predeclared or not) explicitly.</td> +</tr> +</tbody> +</table> + +## data_runfiles + +``` rule-signature +runfiles DefaultInfo.data_runfiles +``` + +runfiles descriptor describing the files that this target needs when run in the condition that it is a `data` dependency attribute. Under most circumstances, use the `default_runfiles` parameter instead. See ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid) for details. +May return `None`. + +## default_runfiles + +``` rule-signature +runfiles DefaultInfo.default_runfiles +``` + +runfiles descriptor describing the files that this target needs when run (via the `run` command or as a tool dependency). +May return `None`. + +## files + +``` rule-signature +depset DefaultInfo.files +``` + +A [`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. +May return `None`. + +## files_to_run + +``` rule-signature +FilesToRunProvider DefaultInfo.files_to_run +``` + +A [`FilesToRunProvider`](../providers/FilesToRunProvider.html) object containing information about the executable and runfiles of the target. +May return `None`. diff --git a/rules/lib/providers/ExecutionInfo.mdx b/rules/lib/providers/ExecutionInfo.mdx index 2c57ccd..39db8c3 100644 --- a/rules/lib/providers/ExecutionInfo.mdx +++ b/rules/lib/providers/ExecutionInfo.mdx @@ -2,88 +2,63 @@ title: 'ExecutionInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ExecutionInfo">ExecutionInfo</h1> +# ExecutionInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/ExecutionInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Use this provider to specify special environment requirements needed to run tests. -<h2>Members</h2> -<ul> - <li> - <a href="#ExecutionInfo">ExecutionInfo</a> - </li> - <li> - <a href="#exec_group">exec_group</a> - </li> - <li> - <a href="#requirements">requirements</a> - </li> - </ul> +## Members + +- [ExecutionInfo](#ExecutionInfo) +- [exec_group](#exec_group) +- [requirements](#requirements) + +## ExecutionInfo + +``` rule-signature +ExecutionInfo ExecutionInfo(requirements={}, exec_group='test') +``` - <h2 id="ExecutionInfo">ExecutionInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/ExecutionInfo.html">ExecutionInfo</a> ExecutionInfo(requirements={}, exec_group='test')</pre></p> +Creates an instance. - Creates an instance. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="ExecutionInfo.requirements"> - <code>requirements</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A dict indicating special execution requirements, such as hardware platforms. - </td> - </tr> - <tr> - <td id="ExecutionInfo.exec_group"> - <code>exec_group</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'test'</code><br/> - The name of the exec group that is used to execute the test. - </td> - </tr> - </tbody> - </table> +### Parameters - <h2 id="exec_group">exec_group</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> ExecutionInfo.exec_group</pre></p> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="ExecutionInfo.requirements"><code>requirements</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A dict indicating special execution requirements, such as hardware platforms.</td> +</tr> +<tr> +<td id="ExecutionInfo.exec_group"><code>exec_group</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'test'</code><br /> +The name of the exec group that is used to execute the test.</td> +</tr> +</tbody> +</table> - The name of the exec group that is used to execute the test. +## exec_group - <h2 id="requirements">requirements</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> ExecutionInfo.requirements</pre></p> +``` rule-signature +string ExecutionInfo.exec_group +``` - A dict indicating special execution requirements, such as hardware platforms. +The name of the exec group that is used to execute the test. +## requirements -</body> -</html> +``` rule-signature +dict ExecutionInfo.requirements +``` -<!-- {% endraw %} --> +A dict indicating special execution requirements, such as hardware platforms. diff --git a/rules/lib/providers/FeatureFlagInfo.mdx b/rules/lib/providers/FeatureFlagInfo.mdx index fb2e9da..fe90ac4 100644 --- a/rules/lib/providers/FeatureFlagInfo.mdx +++ b/rules/lib/providers/FeatureFlagInfo.mdx @@ -2,80 +2,59 @@ title: 'FeatureFlagInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.FeatureFlagInfo">FeatureFlagInfo</h1> +# FeatureFlagInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigFeatureFlagProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A provider used to access information about config_feature_flag rules. -<h2>Members</h2> -<ul> - <li> - <a href="#error">error</a> - </li> - <li> - <a href="#is_valid_value">is_valid_value</a> - </li> - <li> - <a href="#value">value</a> - </li> - </ul> +## Members + +- [error](#error) +- [is_valid_value](#is_valid_value) +- [value](#value) + +## error + +``` rule-signature +string FeatureFlagInfo.error +``` - <h2 id="error">error</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> FeatureFlagInfo.error</pre></p> +If non-None, this error was generated when trying to compute current value of flag. +May return `None`. - If non-None, this error was generated when trying to compute current value of flag. - May return <code>None</code>. +## is_valid_value - <h2 id="is_valid_value">is_valid_value</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> FeatureFlagInfo.is_valid_value(value)</pre></p> +``` rule-signature +bool FeatureFlagInfo.is_valid_value(value) +``` - The value of the flag in the configuration used by the flag rule. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="is_valid_value.value"> - <code>value</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - String, the value to check for validity for this flag. - </td> - </tr> - </tbody> - </table> +The value of the flag in the configuration used by the flag rule. - <h2 id="value">value</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> FeatureFlagInfo.value</pre></p> +### Parameters - The current value of the flag in the flag's current configuration. None if there is an error. - May return <code>None</code>. +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="is_valid_value.value"><code>value</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +String, the value to check for validity for this flag.</td> +</tr> +</tbody> +</table> +## value -</body> -</html> +``` rule-signature +string FeatureFlagInfo.value +``` -<!-- {% endraw %} --> +The current value of the flag in the flag's current configuration. None if there is an error. +May return `None`. diff --git a/rules/lib/providers/FilesToRunProvider.mdx b/rules/lib/providers/FilesToRunProvider.mdx index efed2c0..6f46edb 100644 --- a/rules/lib/providers/FilesToRunProvider.mdx +++ b/rules/lib/providers/FilesToRunProvider.mdx @@ -2,55 +2,41 @@ title: 'FilesToRunProvider' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.FilesToRunProvider">FilesToRunProvider</h1> +# FilesToRunProvider {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FilesToRunProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Contains information about executables produced by a target and the files needed to run it. This provider can not be created directly, it is an implicit output of executable targets accessible via <a href="../providers/DefaultInfo.html#files_to_run"><code>DefaultInfo.files_to_run</code></a>. +{% include "\_buttons.html" %} +Contains information about executables produced by a target and the files needed to run it. This provider can not be created directly, it is an implicit output of executable targets accessible via [`DefaultInfo.files_to_run`](../providers/DefaultInfo.html#files_to_run). +## Members -<h2>Members</h2> -<ul> - <li> - <a href="#executable">executable</a> - </li> - <li> - <a href="#repo_mapping_manifest">repo_mapping_manifest</a> - </li> - <li> - <a href="#runfiles_manifest">runfiles_manifest</a> - </li> - </ul> +- [executable](#executable) +- [repo_mapping_manifest](#repo_mapping_manifest) +- [runfiles_manifest](#runfiles_manifest) - <h2 id="executable">executable</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> FilesToRunProvider.executable</pre></p> +## executable - The main executable or None if it does not exist. - May return <code>None</code>. +``` rule-signature +File FilesToRunProvider.executable +``` - <h2 id="repo_mapping_manifest">repo_mapping_manifest</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> FilesToRunProvider.repo_mapping_manifest</pre></p> +The main executable or None if it does not exist. +May return `None`. - The repo mapping manifest or None if it does not exist. - May return <code>None</code>. +## repo_mapping_manifest - <h2 id="runfiles_manifest">runfiles_manifest</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> FilesToRunProvider.runfiles_manifest</pre></p> +``` rule-signature +File FilesToRunProvider.repo_mapping_manifest +``` - The runfiles manifest or None if it does not exist. - May return <code>None</code>. +The repo mapping manifest or None if it does not exist. +May return `None`. +## runfiles_manifest -</body> -</html> +``` rule-signature +File FilesToRunProvider.runfiles_manifest +``` -<!-- {% endraw %} --> +The runfiles manifest or None if it does not exist. +May return `None`. diff --git a/rules/lib/providers/IncompatiblePlatformProvider.mdx b/rules/lib/providers/IncompatiblePlatformProvider.mdx index 979502e..a080314 100644 --- a/rules/lib/providers/IncompatiblePlatformProvider.mdx +++ b/rules/lib/providers/IncompatiblePlatformProvider.mdx @@ -2,24 +2,8 @@ title: 'IncompatiblePlatformProvider' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.IncompatiblePlatformProvider">IncompatiblePlatformProvider</h1> +# IncompatiblePlatformProvider {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/IncompatiblePlatformProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A provider for targets that are incompatible with the target platform. See <a href='/docs/platforms#detecting-incompatible-targets-using-bazel-cquery'>Detecting incompatible targets using <code>bazel cquery</code></a> for more information. - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +A provider for targets that are incompatible with the target platform. See [Detecting incompatible targets using `bazel cquery`](/docs/platforms#detecting-incompatible-targets-using-bazel-cquery) for more information. diff --git a/rules/lib/providers/InstrumentedFilesInfo.mdx b/rules/lib/providers/InstrumentedFilesInfo.mdx index 4b82296..bffb123 100644 --- a/rules/lib/providers/InstrumentedFilesInfo.mdx +++ b/rules/lib/providers/InstrumentedFilesInfo.mdx @@ -2,43 +2,29 @@ title: 'InstrumentedFilesInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.InstrumentedFilesInfo">InstrumentedFilesInfo</h1> +# InstrumentedFilesInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Contains information about source files and instrumentation metadata files for rule targets matched by <a href="https://bazel.build/reference/command-line-reference#flag--instrumentation_filter"><code>--instrumentation_filter</code></a> for purposes of <a href="https://bazel.build/extending/rules#code_coverage">code coverage data collection</a>. When coverage data collection is enabled, a manifest containing the combined paths in <a href="#instrumented_files"><code>instrumented_files</code></a> and <a href="#metadata_files"><code>metadata_files</code></a> are passed to the test action as inputs, with the manifest's path noted in the environment variable <code>COVERAGE_MANIFEST</code>. The metadata files, but not the source files, are also passed to the test action as inputs. When <code>InstrumentedFilesInfo</code> is returned by an <a href="https://bazel.build/extending/aspects">aspect</a>'s implementation function, any <code>InstrumentedFilesInfo</code> from the base rule target is ignored. +{% include "\_buttons.html" %} +Contains information about source files and instrumentation metadata files for rule targets matched by [`--instrumentation_filter`](https://bazel.build/reference/command-line-reference#flag--instrumentation_filter) for purposes of [code coverage data collection](https://bazel.build/extending/rules#code_coverage). When coverage data collection is enabled, a manifest containing the combined paths in [`instrumented_files`](#instrumented_files) and [`metadata_files`](#metadata_files) are passed to the test action as inputs, with the manifest's path noted in the environment variable `COVERAGE_MANIFEST`. The metadata files, but not the source files, are also passed to the test action as inputs. When `InstrumentedFilesInfo` is returned by an [aspect](https://bazel.build/extending/aspects)'s implementation function, any `InstrumentedFilesInfo` from the base rule target is ignored. -<h2>Members</h2> -<ul> - <li> - <a href="#instrumented_files">instrumented_files</a> - </li> - <li> - <a href="#metadata_files">metadata_files</a> - </li> - </ul> +## Members - <h2 id="instrumented_files">instrumented_files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> InstrumentedFilesInfo.instrumented_files</pre></p> +- [instrumented_files](#instrumented_files) +- [metadata_files](#metadata_files) - <a href="../builtins/depset.html"><code>depset</code></a> of <a href="../builtins/File.html"><code>File</code></a> objects representing instrumented source files for this target and its dependencies. +## instrumented_files - <h2 id="metadata_files">metadata_files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> InstrumentedFilesInfo.metadata_files</pre></p> +``` rule-signature +depset InstrumentedFilesInfo.instrumented_files +``` - <a href="../builtins/depset.html"><code>depset</code></a> of <a href="../builtins/File.html"><code>File</code></a> objects representing coverage metadata files for this target and its dependencies. These files contain additional information required to generate LCOV-format coverage output after the code is executed, e.g. the <code>.gcno</code> files generated when <code>gcc</code> is run with <code>-ftest-coverage</code>. +[`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing instrumented source files for this target and its dependencies. +## metadata_files -</body> -</html> +``` rule-signature +depset InstrumentedFilesInfo.metadata_files +``` -<!-- {% endraw %} --> +[`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing coverage metadata files for this target and its dependencies. These files contain additional information required to generate LCOV-format coverage output after the code is executed, e.g. the `.gcno` files generated when `gcc` is run with `-ftest-coverage`. diff --git a/rules/lib/providers/JavaRuntimeInfo.mdx b/rules/lib/providers/JavaRuntimeInfo.mdx index 1d63277..953e39e 100644 --- a/rules/lib/providers/JavaRuntimeInfo.mdx +++ b/rules/lib/providers/JavaRuntimeInfo.mdx @@ -2,118 +2,113 @@ title: 'JavaRuntimeInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.JavaRuntimeInfo">JavaRuntimeInfo</h1> +# JavaRuntimeInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaRuntimeInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Information about the Java runtime being used. -<h2>Members</h2> -<ul> - <li> - <a href="#default_cds">default_cds</a> - </li> - <li> - <a href="#files">files</a> - </li> - <li> - <a href="#hermetic_files">hermetic_files</a> - </li> - <li> - <a href="#hermetic_static_libs">hermetic_static_libs</a> - </li> - <li> - <a href="#java_executable_exec_path">java_executable_exec_path</a> - </li> - <li> - <a href="#java_executable_runfiles_path">java_executable_runfiles_path</a> - </li> - <li> - <a href="#java_home">java_home</a> - </li> - <li> - <a href="#java_home_runfiles_path">java_home_runfiles_path</a> - </li> - <li> - <a href="#lib_ct_sym">lib_ct_sym</a> - </li> - <li> - <a href="#lib_modules">lib_modules</a> - </li> - <li> - <a href="#version">version</a> - </li> - </ul> +## Members + +- [default_cds](#default_cds) +- [files](#files) +- [hermetic_files](#hermetic_files) +- [hermetic_static_libs](#hermetic_static_libs) +- [java_executable_exec_path](#java_executable_exec_path) +- [java_executable_runfiles_path](#java_executable_runfiles_path) +- [java_home](#java_home) +- [java_home_runfiles_path](#java_home_runfiles_path) +- [lib_ct_sym](#lib_ct_sym) +- [lib_modules](#lib_modules) +- [version](#version) + +## default_cds + +``` rule-signature +File JavaRuntimeInfo.default_cds +``` + +Returns the JDK default CDS archive. +May return `None`. + +## files + +``` rule-signature +depset JavaRuntimeInfo.files +``` + +Returns the files in the Java runtime. + +## hermetic_files + +``` rule-signature +depset JavaRuntimeInfo.hermetic_files +``` - <h2 id="default_cds">default_cds</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> JavaRuntimeInfo.default_cds</pre></p> +Returns the files in the Java runtime needed for hermetic deployments. - Returns the JDK default CDS archive. - May return <code>None</code>. +## hermetic_static_libs - <h2 id="files">files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaRuntimeInfo.files</pre></p> +``` rule-signature +sequence JavaRuntimeInfo.hermetic_static_libs +``` - Returns the files in the Java runtime. +Returns the JDK static libraries. - <h2 id="hermetic_files">hermetic_files</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaRuntimeInfo.hermetic_files</pre></p> +## java_executable_exec_path - Returns the files in the Java runtime needed for hermetic deployments. +``` rule-signature +string JavaRuntimeInfo.java_executable_exec_path +``` - <h2 id="hermetic_static_libs">hermetic_static_libs</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> JavaRuntimeInfo.hermetic_static_libs</pre></p> +Returns the execpath of the Java executable. - Returns the JDK static libraries. +## java_executable_runfiles_path - <h2 id="java_executable_exec_path">java_executable_exec_path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaRuntimeInfo.java_executable_exec_path</pre></p> +``` rule-signature +string JavaRuntimeInfo.java_executable_runfiles_path +``` - Returns the execpath of the Java executable. +Returns the path of the Java executable in runfiles trees. This should only be used when one needs to access the JVM during the execution of a binary or a test built by Bazel. In particular, when one needs to invoke the JVM during an action, java_executable_exec_path should be used instead. - <h2 id="java_executable_runfiles_path">java_executable_runfiles_path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaRuntimeInfo.java_executable_runfiles_path</pre></p> +## java_home - Returns the path of the Java executable in runfiles trees. This should only be used when one needs to access the JVM during the execution of a binary or a test built by Bazel. In particular, when one needs to invoke the JVM during an action, java_executable_exec_path should be used instead. +``` rule-signature +string JavaRuntimeInfo.java_home +``` - <h2 id="java_home">java_home</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaRuntimeInfo.java_home</pre></p> +Returns the execpath of the root of the Java installation. - Returns the execpath of the root of the Java installation. +## java_home_runfiles_path - <h2 id="java_home_runfiles_path">java_home_runfiles_path</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaRuntimeInfo.java_home_runfiles_path</pre></p> +``` rule-signature +string JavaRuntimeInfo.java_home_runfiles_path +``` - Returns the path of the Java installation in runfiles trees. This should only be used when one needs to access the JDK during the execution of a binary or a test built by Bazel. In particular, when one needs the JDK during an action, java_home should be used instead. +Returns the path of the Java installation in runfiles trees. This should only be used when one needs to access the JDK during the execution of a binary or a test built by Bazel. In particular, when one needs the JDK during an action, java_home should be used instead. - <h2 id="lib_ct_sym">lib_ct_sym</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> JavaRuntimeInfo.lib_ct_sym</pre></p> +## lib_ct_sym - Returns the lib/ct.sym file. - May return <code>None</code>. +``` rule-signature +File JavaRuntimeInfo.lib_ct_sym +``` - <h2 id="lib_modules">lib_modules</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> JavaRuntimeInfo.lib_modules</pre></p> +Returns the lib/ct.sym file. +May return `None`. - Returns the lib/modules file. - May return <code>None</code>. +## lib_modules - <h2 id="version">version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/int.html">int</a> JavaRuntimeInfo.version</pre></p> +``` rule-signature +File JavaRuntimeInfo.lib_modules +``` - The Java feature version of the runtime. This is 0 if the version is unknown. +Returns the lib/modules file. +May return `None`. +## version -</body> -</html> +``` rule-signature +int JavaRuntimeInfo.version +``` -<!-- {% endraw %} --> +The Java feature version of the runtime. This is 0 if the version is unknown. diff --git a/rules/lib/providers/JavaToolchainInfo.mdx b/rules/lib/providers/JavaToolchainInfo.mdx index 969e061..c924433 100644 --- a/rules/lib/providers/JavaToolchainInfo.mdx +++ b/rules/lib/providers/JavaToolchainInfo.mdx @@ -2,117 +2,112 @@ title: 'JavaToolchainInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.JavaToolchainInfo">JavaToolchainInfo</h1> +# JavaToolchainInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaToolchainStarlarkApiProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Provides access to information about the Java toolchain rule. Accessible as a 'java_toolchain' field on a Target struct. -<h2>Members</h2> -<ul> - <li> - <a href="#bootclasspath">bootclasspath</a> - </li> - <li> - <a href="#ijar">ijar</a> - </li> - <li> - <a href="#jacocorunner">jacocorunner</a> - </li> - <li> - <a href="#java_runtime">java_runtime</a> - </li> - <li> - <a href="#jvm_opt">jvm_opt</a> - </li> - <li> - <a href="#label">label</a> - </li> - <li> - <a href="#proguard_allowlister">proguard_allowlister</a> - </li> - <li> - <a href="#single_jar">single_jar</a> - </li> - <li> - <a href="#source_version">source_version</a> - </li> - <li> - <a href="#target_version">target_version</a> - </li> - <li> - <a href="#tools">tools</a> - </li> - </ul> +## Members + +- [bootclasspath](#bootclasspath) +- [ijar](#ijar) +- [jacocorunner](#jacocorunner) +- [java_runtime](#java_runtime) +- [jvm_opt](#jvm_opt) +- [label](#label) +- [proguard_allowlister](#proguard_allowlister) +- [single_jar](#single_jar) +- [source_version](#source_version) +- [target_version](#target_version) +- [tools](#tools) + +## bootclasspath + +``` rule-signature +depset JavaToolchainInfo.bootclasspath +``` + +The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. + +## ijar + +``` rule-signature +FilesToRunProvider JavaToolchainInfo.ijar +``` + +A FilesToRunProvider representing the ijar executable. + +## jacocorunner + +``` rule-signature +FilesToRunProvider JavaToolchainInfo.jacocorunner +``` - <h2 id="bootclasspath">bootclasspath</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaToolchainInfo.bootclasspath</pre></p> +The jacocorunner used by the toolchain. +May return `None`. - The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. +## java_runtime - <h2 id="ijar">ijar</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> JavaToolchainInfo.ijar</pre></p> +``` rule-signature +JavaRuntimeInfo JavaToolchainInfo.java_runtime +``` - A FilesToRunProvider representing the ijar executable. +The java runtime information. - <h2 id="jacocorunner">jacocorunner</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> JavaToolchainInfo.jacocorunner</pre></p> +## jvm_opt - The jacocorunner used by the toolchain. - May return <code>None</code>. +``` rule-signature +depset JavaToolchainInfo.jvm_opt +``` - <h2 id="java_runtime">java_runtime</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/JavaRuntimeInfo.html">JavaRuntimeInfo</a> JavaToolchainInfo.java_runtime</pre></p> +The default options for the JVM running the java compiler and associated tools. - The java runtime information. +## label - <h2 id="jvm_opt">jvm_opt</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaToolchainInfo.jvm_opt</pre></p> +``` rule-signature +Label JavaToolchainInfo.label +``` - The default options for the JVM running the java compiler and associated tools. +The toolchain label. - <h2 id="label">label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> JavaToolchainInfo.label</pre></p> +## proguard_allowlister - The toolchain label. +``` rule-signature +FilesToRunProvider JavaToolchainInfo.proguard_allowlister +``` - <h2 id="proguard_allowlister">proguard_allowlister</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> JavaToolchainInfo.proguard_allowlister</pre></p> +Return the binary to validate proguard configuration +May return `None`. - Return the binary to validate proguard configuration - May return <code>None</code>. +## single_jar - <h2 id="single_jar">single_jar</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/FilesToRunProvider.html">FilesToRunProvider</a> JavaToolchainInfo.single_jar</pre></p> +``` rule-signature +FilesToRunProvider JavaToolchainInfo.single_jar +``` - The SingleJar deploy jar. +The SingleJar deploy jar. - <h2 id="source_version">source_version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaToolchainInfo.source_version</pre></p> +## source_version - The java source version. +``` rule-signature +string JavaToolchainInfo.source_version +``` - <h2 id="target_version">target_version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> JavaToolchainInfo.target_version</pre></p> +The java source version. - The java target version. +## target_version - <h2 id="tools">tools</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> JavaToolchainInfo.tools</pre></p> +``` rule-signature +string JavaToolchainInfo.target_version +``` - The compilation tools. +The java target version. +## tools -</body> -</html> +``` rule-signature +depset JavaToolchainInfo.tools +``` -<!-- {% endraw %} --> +The compilation tools. diff --git a/rules/lib/providers/MaterializedDepsInfo.mdx b/rules/lib/providers/MaterializedDepsInfo.mdx index 71dab22..4aaf374 100644 --- a/rules/lib/providers/MaterializedDepsInfo.mdx +++ b/rules/lib/providers/MaterializedDepsInfo.mdx @@ -2,35 +2,20 @@ title: 'MaterializedDepsInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.MaterializedDepsInfo">MaterializedDepsInfo</h1> +# MaterializedDepsInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/MaterializedDepsInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} The provider returned from materializer rules to materialize dependencies. -<h2>Members</h2> -<ul> - <li> - <a href="#deps">deps</a> - </li> - </ul> - - <h2 id="deps">deps</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> MaterializedDepsInfo.deps</pre></p> +## Members - The list of dependencies. These may be ConfiguredTarget or DormantDependency objects. +- [deps](#deps) +## deps -</body> -</html> +``` rule-signature +list MaterializedDepsInfo.deps +``` -<!-- {% endraw %} --> +The list of dependencies. These may be ConfiguredTarget or DormantDependency objects. diff --git a/rules/lib/providers/ObjcProvider.mdx b/rules/lib/providers/ObjcProvider.mdx index 9f19344..ac2ad41 100644 --- a/rules/lib/providers/ObjcProvider.mdx +++ b/rules/lib/providers/ObjcProvider.mdx @@ -2,83 +2,74 @@ title: 'ObjcProvider' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ObjcProvider">ObjcProvider</h1> +# ObjcProvider {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/ObjcProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A provider for compilation and linking of objc. -<h2>Members</h2> -<ul> - <li> - <a href="#direct_module_maps">direct_module_maps</a> - </li> - <li> - <a href="#direct_sources">direct_sources</a> - </li> - <li> - <a href="#j2objc_library">j2objc_library</a> - </li> - <li> - <a href="#module_map">module_map</a> - </li> - <li> - <a href="#source">source</a> - </li> - <li> - <a href="#strict_include">strict_include</a> - </li> - <li> - <a href="#umbrella_header">umbrella_header</a> - </li> - </ul> +## Members + +- [direct_module_maps](#direct_module_maps) +- [direct_sources](#direct_sources) +- [j2objc_library](#j2objc_library) +- [module_map](#module_map) +- [source](#source) +- [strict_include](#strict_include) +- [umbrella_header](#umbrella_header) + +## direct_module_maps + +``` rule-signature +sequence ObjcProvider.direct_module_maps +``` + +Module map files from this target directly (no transitive module maps). Used to enforce proper use of private header files and for Swift compilation. + +## direct_sources - <h2 id="direct_module_maps">direct_module_maps</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> ObjcProvider.direct_module_maps</pre></p> +``` rule-signature +sequence ObjcProvider.direct_sources +``` - Module map files from this target directly (no transitive module maps). Used to enforce proper use of private header files and for Swift compilation. +All direct source files from this target (no transitive files), including any headers in the 'srcs' attribute. - <h2 id="direct_sources">direct_sources</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> ObjcProvider.direct_sources</pre></p> +## j2objc_library - All direct source files from this target (no transitive files), including any headers in the 'srcs' attribute. +``` rule-signature +depset ObjcProvider.j2objc_library +``` - <h2 id="j2objc_library">j2objc_library</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.j2objc_library</pre></p> +Static libraries that are built from J2ObjC-translated Java code. - Static libraries that are built from J2ObjC-translated Java code. +## module_map - <h2 id="module_map">module_map</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.module_map</pre></p> +``` rule-signature +depset ObjcProvider.module_map +``` - Clang module maps, used to enforce proper use of private header files. +Clang module maps, used to enforce proper use of private header files. - <h2 id="source">source</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.source</pre></p> +## source - All transitive source files. +``` rule-signature +depset ObjcProvider.source +``` - <h2 id="strict_include">strict_include</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.strict_include</pre></p> +All transitive source files. - Non-propagated include search paths specified with '-I' on the command line. Also known as header search paths (and distinct from <em>user</em> header search paths). +## strict_include - <h2 id="umbrella_header">umbrella_header</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> ObjcProvider.umbrella_header</pre></p> +``` rule-signature +depset ObjcProvider.strict_include +``` - Clang umbrella header. Public headers are #included in umbrella headers to be compatible with J2ObjC segmented headers. +Non-propagated include search paths specified with '-I' on the command line. Also known as header search paths (and distinct from *user* header search paths). +## umbrella_header -</body> -</html> +``` rule-signature +depset ObjcProvider.umbrella_header +``` -<!-- {% endraw %} --> +Clang umbrella header. Public headers are \#included in umbrella headers to be compatible with J2ObjC segmented headers. diff --git a/rules/lib/providers/OutputGroupInfo.mdx b/rules/lib/providers/OutputGroupInfo.mdx index 5d7c1de..e44fa62 100644 --- a/rules/lib/providers/OutputGroupInfo.mdx +++ b/rules/lib/providers/OutputGroupInfo.mdx @@ -2,61 +2,45 @@ title: 'OutputGroupInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.OutputGroupInfo">OutputGroupInfo</h1> +# OutputGroupInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/OutputGroupInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A provider that indicates what output groups a rule has.<br>See <a href="https://bazel.build/extending/rules#requesting_output_files">Requesting output files</a> for more information. - -<h2>Members</h2> -<ul> - <li> - <a href="#OutputGroupInfo">OutputGroupInfo</a> - </li> - </ul> - - <h2 id="OutputGroupInfo">OutputGroupInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/OutputGroupInfo.html">OutputGroupInfo</a> OutputGroupInfo(**kwargs)</pre></p> - - Instantiate this provider with <br><pre class=language-python>OutputGroupInfo(group1 = <files>, group2 = <files>...)</pre>See <a href="https://bazel.build/extending/rules#requesting_output_files">Requesting output files </a> for more information. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="OutputGroupInfo.kwargs"> - <code>kwargs</code> - </td> - <td> - default is <code>{}</code><br/> - Dictionary of arguments. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +A provider that indicates what output groups a rule has. +See [Requesting output files](https://bazel.build/extending/rules#requesting_output_files) for more information. + +## Members + +- [OutputGroupInfo](#OutputGroupInfo) + +## OutputGroupInfo + +``` rule-signature +OutputGroupInfo OutputGroupInfo(**kwargs) +``` + +Instantiate this provider with + +``` python +OutputGroupInfo(group1 = <files>, group2 = <files>...) +``` + +See [Requesting output files](https://bazel.build/extending/rules#requesting_output_files) for more information. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="OutputGroupInfo.kwargs"><code>kwargs</code></td> +<td>default is <code>{}</code><br /> +Dictionary of arguments.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/providers/PackageSpecificationInfo.mdx b/rules/lib/providers/PackageSpecificationInfo.mdx index d2437e4..0b6dedc 100644 --- a/rules/lib/providers/PackageSpecificationInfo.mdx +++ b/rules/lib/providers/PackageSpecificationInfo.mdx @@ -2,62 +2,39 @@ title: 'PackageSpecificationInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.PackageSpecificationInfo">PackageSpecificationInfo</h1> +# PackageSpecificationInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/PackageSpecificationProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Information about transitive package specifications used in package groups. -<h2>Members</h2> -<ul> - <li> - <a href="#contains">contains</a> - </li> - </ul> - - <h2 id="contains">contains</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> PackageSpecificationInfo.contains(target)</pre></p> - - Checks if a target exists in a package group. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="contains.target"> - <code>target</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; - required<br/> - A target which is checked if it exists inside the package group. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [contains](#contains) + +## contains + +``` rule-signature +bool PackageSpecificationInfo.contains(target) +``` + +Checks if a target exists in a package group. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="contains.target"><code>target</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; +required<br /> +A target which is checked if it exists inside the package group.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/providers/PlatformInfo.mdx b/rules/lib/providers/PlatformInfo.mdx index 27aaf6b..0e6a33f 100644 --- a/rules/lib/providers/PlatformInfo.mdx +++ b/rules/lib/providers/PlatformInfo.mdx @@ -2,24 +2,9 @@ title: 'PlatformInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.PlatformInfo">PlatformInfo</h1> +# PlatformInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Provides access to data about a specific platform. See <a href='/docs/platforms#constraints-platforms'>Defining Constraints and Platforms</a> for more information.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +Provides access to data about a specific platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* diff --git a/rules/lib/providers/RunEnvironmentInfo.mdx b/rules/lib/providers/RunEnvironmentInfo.mdx index 6df0bd6..1a53862 100644 --- a/rules/lib/providers/RunEnvironmentInfo.mdx +++ b/rules/lib/providers/RunEnvironmentInfo.mdx @@ -2,43 +2,29 @@ title: 'RunEnvironmentInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.RunEnvironmentInfo">RunEnvironmentInfo</h1> +# RunEnvironmentInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunEnvironmentInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A provider that can be returned from executable rules to control the environment in which their executable is executed. -<h2>Members</h2> -<ul> - <li> - <a href="#environment">environment</a> - </li> - <li> - <a href="#inherited_environment">inherited_environment</a> - </li> - </ul> +## Members - <h2 id="environment">environment</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> RunEnvironmentInfo.environment</pre></p> +- [environment](#environment) +- [inherited_environment](#inherited_environment) - A map of string keys and values that represent environment variables and their values. These will be made available when the target that returns this provider is executed, either as a test or via the run command. +## environment - <h2 id="inherited_environment">inherited_environment</h2> - <p><pre class="rule-signature">List RunEnvironmentInfo.inherited_environment</pre></p> +``` rule-signature +dict RunEnvironmentInfo.environment +``` - A sequence of names of environment variables. These variables are made available with their current value taken from the shell environment when the target that returns this provider is executed, either as a test or via the run command. If a variable is contained in both <code>environment</code> and <code>inherited_environment</code>, the value inherited from the shell environment will take precedence if set. This is most useful for test rules, which run with a hermetic environment under <code>bazel test</code> and can use this mechanism to non-hermetically include a variable from the outer environment. By contrast, <code>bazel run</code> already forwards the outer environment. Note, though, that it may be surprising for an otherwise hermetic test to hardcode a non-hermetic dependency on the environment, and that this may even accidentally expose sensitive information. Prefer setting the test environment explicitly with the <code>--test_env</code> flag, and even then prefer to avoid using this flag and instead populate the environment explicitly. +A map of string keys and values that represent environment variables and their values. These will be made available when the target that returns this provider is executed, either as a test or via the run command. +## inherited_environment -</body> -</html> +``` rule-signature +List RunEnvironmentInfo.inherited_environment +``` -<!-- {% endraw %} --> +A sequence of names of environment variables. These variables are made available with their current value taken from the shell environment when the target that returns this provider is executed, either as a test or via the run command. If a variable is contained in both `environment` and `inherited_environment`, the value inherited from the shell environment will take precedence if set. This is most useful for test rules, which run with a hermetic environment under `bazel test` and can use this mechanism to non-hermetically include a variable from the outer environment. By contrast, `bazel run` already forwards the outer environment. Note, though, that it may be surprising for an otherwise hermetic test to hardcode a non-hermetic dependency on the environment, and that this may even accidentally expose sensitive information. Prefer setting the test environment explicitly with the `--test_env` flag, and even then prefer to avoid using this flag and instead populate the environment explicitly. diff --git a/rules/lib/providers/TemplateVariableInfo.mdx b/rules/lib/providers/TemplateVariableInfo.mdx index d603e39..e4328dd 100644 --- a/rules/lib/providers/TemplateVariableInfo.mdx +++ b/rules/lib/providers/TemplateVariableInfo.mdx @@ -2,35 +2,24 @@ title: 'TemplateVariableInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.TemplateVariableInfo">TemplateVariableInfo</h1> +# TemplateVariableInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateVariableInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +Encapsulates template variables, that is, variables that can be referenced by strings like `$(VARIABLE)` in BUILD files and expanded by `ctx.expand_make_variables` and implicitly in certain attributes of built-in rules. -Encapsulates template variables, that is, variables that can be referenced by strings like <code>$(VARIABLE)</code> in BUILD files and expanded by <code>ctx.expand_make_variables</code> and implicitly in certain attributes of built-in rules.</p><p><code>TemplateVariableInfo</code> can be created by calling its eponymous constructor with a string-to-string dict as an argument that specifies the variables provided.</p><p>Example: <code>platform_common.TemplateVariableInfo({'FOO': 'bar'})</code></p> +`TemplateVariableInfo` can be created by calling its eponymous constructor with a string-to-string dict as an argument that specifies the variables provided. -<h2>Members</h2> -<ul> - <li> - <a href="#variables">variables</a> - </li> - </ul> +Example: `platform_common.TemplateVariableInfo({'FOO': 'bar'})` - <h2 id="variables">variables</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> TemplateVariableInfo.variables</pre></p> +## Members - Returns the make variables defined by this target as a dictionary with string keys and string values +- [variables](#variables) +## variables -</body> -</html> +``` rule-signature +dict TemplateVariableInfo.variables +``` -<!-- {% endraw %} --> +Returns the make variables defined by this target as a dictionary with string keys and string values diff --git a/rules/lib/providers/ToolchainInfo.mdx b/rules/lib/providers/ToolchainInfo.mdx index 67dc9c5..7997940 100644 --- a/rules/lib/providers/ToolchainInfo.mdx +++ b/rules/lib/providers/ToolchainInfo.mdx @@ -2,24 +2,8 @@ title: 'ToolchainInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ToolchainInfo">ToolchainInfo</h1> +# ToolchainInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Provider returned by <a href="/docs/toolchains#defining-toolchains">toolchain rules</a> to share data with <a href="/docs/toolchains#writing-rules-that-use-toolchains">rules which depend on toolchains</a>. Read about <a href='/docs/toolchains'>toolchains</a> for more information. - - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +Provider returned by [toolchain rules](/docs/toolchains#defining-toolchains) to share data with [rules which depend on toolchains](/docs/toolchains#writing-rules-that-use-toolchains). Read about [toolchains](/docs/toolchains) for more information. diff --git a/rules/lib/providers/ToolchainTypeInfo.mdx b/rules/lib/providers/ToolchainTypeInfo.mdx index a03d6b4..b71acf2 100644 --- a/rules/lib/providers/ToolchainTypeInfo.mdx +++ b/rules/lib/providers/ToolchainTypeInfo.mdx @@ -2,35 +2,21 @@ title: 'ToolchainTypeInfo' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.ToolchainTypeInfo">ToolchainTypeInfo</h1> +# ToolchainTypeInfo {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainTypeInfoApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -Provides access to data about a specific toolchain type. <br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> - -<h2>Members</h2> -<ul> - <li> - <a href="#type_label">type_label</a> - </li> - </ul> +{% include "\_buttons.html" %} +Provides access to data about a specific toolchain type. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* - <h2 id="type_label">type_label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> ToolchainTypeInfo.type_label</pre></p> +## Members - The label uniquely identifying this toolchain type. +- [type_label](#type_label) +## type_label -</body> -</html> +``` rule-signature +Label ToolchainTypeInfo.type_label +``` -<!-- {% endraw %} --> +The label uniquely identifying this toolchain type. diff --git a/rules/lib/providers/file_provider.mdx b/rules/lib/providers/file_provider.mdx index 61c05f6..fda26a3 100644 --- a/rules/lib/providers/file_provider.mdx +++ b/rules/lib/providers/file_provider.mdx @@ -2,24 +2,8 @@ title: 'file_provider' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.file_provider">file_provider</h1> +# file_provider {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} An interface for rules that provide files. - - - -</body> -</html> - -<!-- {% endraw %} --> diff --git a/rules/lib/providers/java_compilation_info.mdx b/rules/lib/providers/java_compilation_info.mdx index 01961c0..3eeec55 100644 --- a/rules/lib/providers/java_compilation_info.mdx +++ b/rules/lib/providers/java_compilation_info.mdx @@ -2,59 +2,47 @@ title: 'java_compilation_info' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.java_compilation_info">java_compilation_info</h1> +# java_compilation_info {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCompilationInfoProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Provides access to compilation information for Java rules. -<h2>Members</h2> -<ul> - <li> - <a href="#boot_classpath">boot_classpath</a> - </li> - <li> - <a href="#compilation_classpath">compilation_classpath</a> - </li> - <li> - <a href="#javac_options">javac_options</a> - </li> - <li> - <a href="#runtime_classpath">runtime_classpath</a> - </li> - </ul> +## Members + +- [boot_classpath](#boot_classpath) +- [compilation_classpath](#compilation_classpath) +- [javac_options](#javac_options) +- [runtime_classpath](#runtime_classpath) + +## boot_classpath - <h2 id="boot_classpath">boot_classpath</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java_compilation_info.boot_classpath</pre></p> +``` rule-signature +list java_compilation_info.boot_classpath +``` - Boot classpath for this Java target. +Boot classpath for this Java target. - <h2 id="compilation_classpath">compilation_classpath</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_compilation_info.compilation_classpath</pre></p> +## compilation_classpath - Compilation classpath for this Java target. +``` rule-signature +depset java_compilation_info.compilation_classpath +``` - <h2 id="javac_options">javac_options</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_compilation_info.javac_options</pre></p> +Compilation classpath for this Java target. - A depset of options to java compiler. To get the exact list of options passed to javac in the correct order, use the tokenize_javacopts utility in rules_java +## javac_options - <h2 id="runtime_classpath">runtime_classpath</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/depset.html">depset</a> java_compilation_info.runtime_classpath</pre></p> +``` rule-signature +depset java_compilation_info.javac_options +``` - Run-time classpath for this Java target. +A depset of options to java compiler. To get the exact list of options passed to javac in the correct order, use the tokenize_javacopts utility in rules_java +## runtime_classpath -</body> -</html> +``` rule-signature +depset java_compilation_info.runtime_classpath +``` -<!-- {% endraw %} --> +Run-time classpath for this Java target. diff --git a/rules/lib/providers/java_output_jars.mdx b/rules/lib/providers/java_output_jars.mdx index 3074340..53ecf4c 100644 --- a/rules/lib/providers/java_output_jars.mdx +++ b/rules/lib/providers/java_output_jars.mdx @@ -2,53 +2,40 @@ title: 'java_output_jars' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.java_output_jars">java_output_jars</h1> +# java_output_jars {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaRuleOutputJarsProviderApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Information about outputs of a Java rule. Deprecated: use java_info.java_outputs. -<h2>Members</h2> -<ul> - <li> - <a href="#jars">jars</a> - </li> - <li> - <a href="#jdeps">jdeps</a> - </li> - <li> - <a href="#native_headers">native_headers</a> - </li> - </ul> +## Members + +- [jars](#jars) +- [jdeps](#jdeps) +- [native_headers](#native_headers) - <h2 id="jars">jars</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> java_output_jars.jars</pre></p> +## jars - Returns information about outputs of this Java/Java-like target. Deprecated: Use java_info.java_outputs. +``` rule-signature +list java_output_jars.jars +``` - <h2 id="jdeps">jdeps</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_output_jars.jdeps</pre></p> +Returns information about outputs of this Java/Java-like target. Deprecated: Use java_info.java_outputs. - A manifest proto file. The protobuf file containing the manifest generated from JavaBuilder. This function returns a value when exactly one manifest proto file is present in the outputs. Deprecated: Use java_info.java_outputs[i].jdeps. - May return <code>None</code>. +## jdeps - <h2 id="native_headers">native_headers</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_output_jars.native_headers</pre></p> +``` rule-signature +File java_output_jars.jdeps +``` - A jar containing CC header files supporting native method implementation. This function returns a value when exactly one native headers jar file is present in the outputs. Deprecated: Use java_info.java_outputs[i].native_headers_jar. - May return <code>None</code>. +A manifest proto file. The protobuf file containing the manifest generated from JavaBuilder. This function returns a value when exactly one manifest proto file is present in the outputs. Deprecated: Use java_info.java_outputs\[i\].jdeps. +May return `None`. +## native_headers -</body> -</html> +``` rule-signature +File java_output_jars.native_headers +``` -<!-- {% endraw %} --> +A jar containing CC header files supporting native method implementation. This function returns a value when exactly one native headers jar file is present in the outputs. Deprecated: Use java_info.java_outputs\[i\].native_headers_jar. +May return `None`. diff --git a/rules/lib/toplevel.mdx b/rules/lib/toplevel.mdx index b0cc8ce..d49bc13 100644 --- a/rules/lib/toplevel.mdx +++ b/rules/lib/toplevel.mdx @@ -2,41 +2,20 @@ title: 'toplevel' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> -<h1 class="page-title">Top-level Modules</h1> +# Top-level Modules {% dynamic setvar source_file "NONE" %} -{% include "_buttons.html" %} +{% include "\_buttons.html" %} This section lists top-level modules. These symbols are available only in .bzl files. -<ul> - -<li><a href="/rules/lib/toplevel/apple_common">apple_common</a></li> - -<li><a href="/rules/lib/toplevel/attr">attr</a></li> - -<li><a href="/rules/lib/toplevel/cc_common">cc_common</a></li> - -<li><a href="/rules/lib/toplevel/config">config</a></li> - -<li><a href="/rules/lib/toplevel/config_common">config_common</a></li> - -<li><a href="/rules/lib/toplevel/coverage_common">coverage_common</a></li> - -<li><a href="/rules/lib/toplevel/java_common">java_common</a></li> - -<li><a href="/rules/lib/toplevel/native">native</a></li> - -<li><a href="/rules/lib/toplevel/platform_common">platform_common</a></li> - -<li><a href="/rules/lib/toplevel/proto">proto</a></li> - -<li><a href="/rules/lib/toplevel/testing">testing</a></li> -</ul> -</body> -</html> +- [apple_common](/rules/lib/toplevel/apple_common) +- [attr](/rules/lib/toplevel/attr) +- [cc_common](/rules/lib/toplevel/cc_common) +- [config](/rules/lib/toplevel/config) +- [config_common](/rules/lib/toplevel/config_common) +- [coverage_common](/rules/lib/toplevel/coverage_common) +- [java_common](/rules/lib/toplevel/java_common) +- [native](/rules/lib/toplevel/native) +- [platform_common](/rules/lib/toplevel/platform_common) +- [proto](/rules/lib/toplevel/proto) +- [testing](/rules/lib/toplevel/testing) diff --git a/rules/lib/toplevel/apple_common.mdx b/rules/lib/toplevel/apple_common.mdx index d6cb53e..a0315a9 100644 --- a/rules/lib/toplevel/apple_common.mdx +++ b/rules/lib/toplevel/apple_common.mdx @@ -2,184 +2,178 @@ title: 'apple_common' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.apple_common">apple_common</h1> +# apple_common {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Functions for Starlark to access internals of the apple rule implementations. -<h2>Members</h2> -<ul> - <li> - <a href="#apple_host_system_env">apple_host_system_env</a> - </li> - <li> - <a href="#apple_toolchain">apple_toolchain</a> - </li> - <li> - <a href="#dotted_version">dotted_version</a> - </li> - <li> - <a href="#platform">platform</a> - </li> - <li> - <a href="#platform_type">platform_type</a> - </li> - <li> - <a href="#target_apple_env">target_apple_env</a> - </li> - <li> - <a href="#XcodeProperties">XcodeProperties</a> - </li> - <li> - <a href="#XcodeVersionConfig">XcodeVersionConfig</a> - </li> - </ul> - - <h2 id="apple_host_system_env">apple_host_system_env</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> apple_common.apple_host_system_env(xcode_config)</pre></p> - - Returns a <a href='../core/dict.html'>dict</a> of environment variables that should be set for actions that need to run build tools on an Apple host system, such as the version of Xcode that should be used. The keys are variable names and the values are their corresponding values. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="apple_host_system_env.xcode_config"> - <code>xcode_config</code> - </td> - <td> - required<br/> - A provider containing information about the Xcode configuration. - </td> - </tr> - </tbody> - </table> - - <h2 id="apple_toolchain">apple_toolchain</h2> - <p><pre class="rule-signature">unknown apple_common.apple_toolchain()</pre></p> - - Utilities for resolving items from the apple toolchain. - - <h2 id="dotted_version">dotted_version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/DottedVersion.html">DottedVersion</a> apple_common.dotted_version(version)</pre></p> - - Creates a new <a href="../builtins/DottedVersion.html">DottedVersion</a> instance. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="dotted_version.version"> - <code>version</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The string representation of the DottedVersion. - </td> - </tr> - </tbody> - </table> - - <h2 id="platform">platform</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> apple_common.platform</pre></p> - - An enum-like struct that contains the following fields corresponding to Apple platforms:<br><ul><li><code>ios_device</code></li><li><code>ios_simulator</code></li><li><code>macos</code></li><li><code>tvos_device</code></li><li><code>tvos_simulator</code></li><li><code>visionos_device</code></li><li><code>visionos_simulator</code></li><li><code>watchos_device</code></li><li><code>watchos_simulator</code></li></ul><p>These values can be passed to methods that expect a platform, like <a href='../providers/XcodeVersionConfig.html#sdk_version_for_platform'>XcodeVersionConfig.sdk_version_for_platform</a>. - - <h2 id="platform_type">platform_type</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> apple_common.platform_type</pre></p> - - An enum-like struct that contains the following fields corresponding to Apple platform types:<br><ul><li><code>ios</code></li><li><code>macos</code></li><li><code>tvos</code></li><li><code>visionos</code></li><li><code>watchos</code></li></ul><p>These values can be passed to methods that expect a platform type, like the 'apple' configuration fragment's <a href='../fragments/apple.html#multi_arch_platform'>multi_arch_platform</a> method.<p>Example:<p><pre class='language-python'> +## Members + +- [apple_host_system_env](#apple_host_system_env) +- [apple_toolchain](#apple_toolchain) +- [dotted_version](#dotted_version) +- [platform](#platform) +- [platform_type](#platform_type) +- [target_apple_env](#target_apple_env) +- [XcodeProperties](#XcodeProperties) +- [XcodeVersionConfig](#XcodeVersionConfig) + +## apple_host_system_env + +``` rule-signature +dict apple_common.apple_host_system_env(xcode_config) +``` + +Returns a [dict](../core/dict.html) of environment variables that should be set for actions that need to run build tools on an Apple host system, such as the version of Xcode that should be used. The keys are variable names and the values are their corresponding values. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="apple_host_system_env.xcode_config"><code>xcode_config</code></td> +<td>required<br /> +A provider containing information about the Xcode configuration.</td> +</tr> +</tbody> +</table> + +## apple_toolchain + +``` rule-signature +unknown apple_common.apple_toolchain() +``` + +Utilities for resolving items from the apple toolchain. + +## dotted_version + +``` rule-signature +DottedVersion apple_common.dotted_version(version) +``` + +Creates a new [DottedVersion](../builtins/DottedVersion.html) instance. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="dotted_version.version"><code>version</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The string representation of the DottedVersion.</td> +</tr> +</tbody> +</table> + +## platform + +``` rule-signature +struct apple_common.platform +``` + +An enum-like struct that contains the following fields corresponding to Apple platforms: + +- `ios_device` +- `ios_simulator` +- `macos` +- `tvos_device` +- `tvos_simulator` +- `visionos_device` +- `visionos_simulator` +- `watchos_device` +- `watchos_simulator` + +These values can be passed to methods that expect a platform, like [XcodeVersionConfig.sdk_version_for_platform](../providers/XcodeVersionConfig.html#sdk_version_for_platform). + +## platform_type + +``` rule-signature +struct apple_common.platform_type +``` + +An enum-like struct that contains the following fields corresponding to Apple platform types: + +- `ios` +- `macos` +- `tvos` +- `visionos` +- `watchos` + +These values can be passed to methods that expect a platform type, like the 'apple' configuration fragment's [multi_arch_platform](../fragments/apple.html#multi_arch_platform) method. + +Example: + +``` python + ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios) -</pre> - - <h2 id="target_apple_env">target_apple_env</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> apple_common.target_apple_env(xcode_config, platform)</pre></p> - - Returns a <code>dict</code> of environment variables that should be set for actions that build targets of the given Apple platform type. For example, this dictionary contains variables that denote the platform name and SDK version with which to build. The keys are variable names and the values are their corresponding values. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="target_apple_env.xcode_config"> - <code>xcode_config</code> - </td> - <td> - required<br/> - A provider containing information about the Xcode configuration. - </td> - </tr> - <tr> - <td id="target_apple_env.platform"> - <code>platform</code> - </td> - <td> - required<br/> - The apple platform. - </td> - </tr> - </tbody> - </table> - - <h2 id="XcodeProperties">XcodeProperties</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> apple_common.XcodeProperties</pre></p> - - The constructor/key for the <code>XcodeVersionProperties</code> provider.<p>If a target propagates the <code>XcodeVersionProperties</code> provider, use this as the key with which to retrieve it. Example:<br><pre class='language-python'> -dep = ctx.attr.deps[0] -p = dep[apple_common.XcodeVersionProperties] -</pre> +``` + +## target_apple_env - <h2 id="XcodeVersionConfig">XcodeVersionConfig</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> apple_common.XcodeVersionConfig</pre></p> +``` rule-signature +dict apple_common.target_apple_env(xcode_config, platform) +``` - The constructor/key for the <code>XcodeVersionConfig</code> provider. +Returns a `dict` of environment variables that should be set for actions that build targets of the given Apple platform type. For example, this dictionary contains variables that denote the platform name and SDK version with which to build. The keys are variable names and the values are their corresponding values. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="target_apple_env.xcode_config"><code>xcode_config</code></td> +<td>required<br /> +A provider containing information about the Xcode configuration.</td> +</tr> +<tr> +<td id="target_apple_env.platform"><code>platform</code></td> +<td>required<br /> +The apple platform.</td> +</tr> +</tbody> +</table> + +## XcodeProperties + +``` rule-signature +Provider apple_common.XcodeProperties +``` + +The constructor/key for the `XcodeVersionProperties` provider. + +If a target propagates the `XcodeVersionProperties` provider, use this as the key with which to retrieve it. Example: + +``` python + +dep = ctx.attr.deps[0] +p = dep[apple_common.XcodeVersionProperties] +``` +## XcodeVersionConfig -</body> -</html> +``` rule-signature +Provider apple_common.XcodeVersionConfig +``` -<!-- {% endraw %} --> +The constructor/key for the `XcodeVersionConfig` provider. diff --git a/rules/lib/toplevel/attr.mdx b/rules/lib/toplevel/attr.mdx index 87bef4a..b6517ed 100644 --- a/rules/lib/toplevel/attr.mdx +++ b/rules/lib/toplevel/attr.mdx @@ -2,1275 +2,903 @@ title: 'attr' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.attr">attr</h1> +# attr {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -This is a top-level module for defining the attribute schemas of a rule or aspect. Each function returns an object representing the schema of a single attribute. These objects are used as the values of the <code>attrs</code> dictionary argument of <a href="../globals/bzl.html#rule"><code>rule()</code></a>, <a href="../globals/bzl.html#aspect"><code>aspect()</code></a>, <a href="../globals/bzl.html#repository_rule"><code>repository_rule()</code></a> and <a href="../globals/bzl.html#tag_class"><code>tag_class()</code></a>. <p>See the Rules page for more on <a href="https://bazel.build/extending/rules#attributes">defining</a> -and <a href="https://bazel.build/extending/rules#implementation_function">using</a> attributes.</p> - - -<h2>Members</h2> -<ul> - <li> - <a href="#bool">bool</a> - </li> - <li> - <a href="#int">int</a> - </li> - <li> - <a href="#int_list">int_list</a> - </li> - <li> - <a href="#label">label</a> - </li> - <li> - <a href="#label_keyed_string_dict">label_keyed_string_dict</a> - </li> - <li> - <a href="#label_list">label_list</a> - </li> - <li> - <a href="#output">output</a> - </li> - <li> - <a href="#output_list">output_list</a> - </li> - <li> - <a href="#string">string</a> - </li> - <li> - <a href="#string_dict">string_dict</a> - </li> - <li> - <a href="#string_keyed_label_dict">string_keyed_label_dict</a> - </li> - <li> - <a href="#string_list">string_list</a> - </li> - <li> - <a href="#string_list_dict">string_list_dict</a> - </li> - </ul> - - <h2 id="bool">bool</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.bool(*, configurable=unbound, default=False, doc=None, mandatory=False)</pre></p> - - Creates a schema for a boolean attribute. The corresponding <a href='../builtins/ctx.html#attr'><code>ctx.attr</code></a> attribute will be of type <a href='../core/bool.html'><code>bool</code></a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="bool.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="bool.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule. - </td> - </tr> - <tr> - <td id="bool.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="bool.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - </tbody> - </table> - - <h2 id="int">int</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.int(*, configurable=unbound, default=0, doc=None, mandatory=False, values=[])</pre></p> - - Creates a schema for an integer attribute. The value must be in the signed 32-bit range. The corresponding <a href='../builtins/ctx.html#attr'><code>ctx.attr</code></a> attribute will be of type <a href='../core/int.html'><code>int</code></a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="int.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="int.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>0</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule. - </td> - </tr> - <tr> - <td id="int.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="int.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - <tr> - <td id="int.values"> - <code>values</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/int.html">int</a>s; - default is <code>[]</code><br/> - The list of allowed values for the attribute. An error is raised if any other value is given. - </td> - </tr> - </tbody> - </table> - - <h2 id="int_list">int_list</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.int_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None)</pre></p> - - Creates a schema for a list-of-integers attribute. Each element must be in the signed 32-bit range. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="int_list.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - <tr> - <td id="int_list.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True if the attribute can be empty. - </td> - </tr> - <tr> - <td id="int_list.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="int_list.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/int.html">int</a>s; - default is <code>[]</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule. - </td> - </tr> - <tr> - <td id="int_list.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - </tbody> - </table> - - <h2 id="label">label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.label(*, configurable=unbound, default=None, materializer=None, doc=None, executable=False, allow_files=None, allow_single_file=None, mandatory=False, skip_validations=False, providers=[], for_dependency_resolution=unbound, allow_rules=None, cfg=None, aspects=[], flags=[])</pre></p> - - <p>Creates a schema for a label attribute. This is a dependency attribute.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time (within the rule's implementation function), when retrieving the attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access the providers of the current target's dependencies.<p>In addition to ordinary source files, this kind of attribute is often used to refer to a tool -- for example, a compiler. Such tools are considered to be dependencies, just like source files. To avoid requiring users to specify the tool's label every time they use the rule in their BUILD files, you can hard-code the label of a canonical tool as the <code>default</code> value of this attribute. If you also want to prevent users from overriding this default, you can make the attribute private by giving it a name that starts with an underscore. See the <a href='https://bazel.build/extending/rules#private-attributes'>Rules</a> page for more information. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="label.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="label.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; or <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/LateBoundDefault.html">LateBoundDefault</a>; or NativeComputedDefault; or <a class="anchor" href="../core/function.html">function</a>; or <code>None</code>; - default is <code>None</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify a default value, for example, <code>attr.label(default = "//a:b")</code>. - </td> - </tr> - <tr> - <td id="label.materializer"> - <code>materializer</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - default is <code>None</code><br/> - <b>Experimental</b>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_dormant_deps</code> <br>If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute - </td> - </tr> - <tr> - <td id="label.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="label.executable"> - <code>executable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - True if the dependency has to be executable. This means the label must refer to an executable file, or to a rule that outputs an executable file. Access the label with <code>ctx.executable.<attribute_name></code>. - </td> - </tr> - <tr> - <td id="label.allow_files"> - <code>allow_files</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>). - </td> - </tr> - <tr> - <td id="label.allow_single_file"> - <code>allow_single_file</code> - </td> - <td> - default is <code>None</code><br/> - This is similar to <code>allow_files</code>, with the restriction that the label must correspond to a single <a href="../builtins/File.html">File</a>. Access it through <code>ctx.file.<attribute_name></code>. - </td> - </tr> - <tr> - <td id="label.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - <tr> - <td id="label.skip_validations"> - <code>skip_validations</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. - </td> - </tr> - <tr> - <td id="label.providers"> - <code>providers</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - The providers that must be given by any dependency appearing in this attribute.<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice. - </td> - </tr> - <tr> - <td id="label.for_dependency_resolution"> - <code>for_dependency_resolution</code> - </td> - <td> - default is <code>unbound</code><br/> - If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. - </td> - </tr> - <tr> - <td id="label.allow_rules"> - <code>allow_rules</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. - </td> - </tr> - <tr> - <td id="label.cfg"> - <code>cfg</code> - </td> - <td> - default is <code>None</code><br/> - <a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. This parameter is required if <code>executable</code> is True to guard against accidentally building host tools in the target configuration. <code>"target"</code> has no semantic effect, so don't set it when <code>executable</code> is False unless it really helps clarify your intentions. - </td> - </tr> - <tr> - <td id="label.aspects"> - <code>aspects</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; - default is <code>[]</code><br/> - Aspects that should be applied to the dependency or dependencies specified by this attribute. - </td> - </tr> - <tr> - <td id="label.flags"> - <code>flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Deprecated, will be removed. - </td> - </tr> - </tbody> - </table> - - <h2 id="label_keyed_string_dict">label_keyed_string_dict</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.label_keyed_string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[])</pre></p> - - <p>Creates a schema for an attribute holding a dictionary, where the keys are labels and the values are strings. This is a dependency attribute.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time (within the rule's implementation function), when retrieving the attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access the providers of the current target's dependencies. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="label_keyed_string_dict.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True if the attribute can be empty. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <a class="anchor" href="../core/function.html">function</a>; - default is <code>{}</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"})</code>. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.allow_files"> - <code>allow_files</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>). - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.allow_rules"> - <code>allow_rules</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.providers"> - <code>providers</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - The providers that must be given by any dependency appearing in this attribute.<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.for_dependency_resolution"> - <code>for_dependency_resolution</code> - </td> - <td> - default is <code>unbound</code><br/> - If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.flags"> - <code>flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Deprecated, will be removed. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.skip_validations"> - <code>skip_validations</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.cfg"> - <code>cfg</code> - </td> - <td> - default is <code>None</code><br/> - <a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. - </td> - </tr> - <tr> - <td id="label_keyed_string_dict.aspects"> - <code>aspects</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; - default is <code>[]</code><br/> - Aspects that should be applied to the dependency or dependencies specified by this attribute. - </td> - </tr> - </tbody> - </table> - - <h2 id="label_list">label_list</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.label_list(allow_empty=True, *, configurable=unbound, default=[], materializer=None, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[])</pre></p> - - <p>Creates a schema for a list-of-labels attribute. This is a dependency attribute. The corresponding <a href='../builtins/ctx.html#attr'><code>ctx.attr</code></a> attribute will be of type <a href='../core/list.html'>list</a> of <a href='../builtins/Target.html'><code>Target</code>s</a>.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time (within the rule's implementation function), when retrieving the attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access the providers of the current target's dependencies. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="label_list.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True if the attribute can be empty. - </td> - </tr> - <tr> - <td id="label_list.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="label_list.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Label.html">Label</a>s; or <a class="anchor" href="../core/function.html">function</a>; - default is <code>[]</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.label_list(default = ["//a:b", "//a:c"])</code>. - </td> - </tr> - <tr> - <td id="label_list.materializer"> - <code>materializer</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - default is <code>None</code><br/> - <b>Experimental</b>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_dormant_deps</code> <br>If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute - </td> - </tr> - <tr> - <td id="label_list.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="label_list.allow_files"> - <code>allow_files</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>). - </td> - </tr> - <tr> - <td id="label_list.allow_rules"> - <code>allow_rules</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. - </td> - </tr> - <tr> - <td id="label_list.providers"> - <code>providers</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - The providers that must be given by any dependency appearing in this attribute.<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice. - </td> - </tr> - <tr> - <td id="label_list.for_dependency_resolution"> - <code>for_dependency_resolution</code> - </td> - <td> - default is <code>unbound</code><br/> - If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. - </td> - </tr> - <tr> - <td id="label_list.flags"> - <code>flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Deprecated, will be removed. - </td> - </tr> - <tr> - <td id="label_list.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - <tr> - <td id="label_list.skip_validations"> - <code>skip_validations</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. - </td> - </tr> - <tr> - <td id="label_list.cfg"> - <code>cfg</code> - </td> - <td> - default is <code>None</code><br/> - <a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. - </td> - </tr> - <tr> - <td id="label_list.aspects"> - <code>aspects</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; - default is <code>[]</code><br/> - Aspects that should be applied to the dependency or dependencies specified by this attribute. - </td> - </tr> - </tbody> - </table> - - <h2 id="output">output</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.output(*, doc=None, mandatory=False)</pre></p> - - <p>Creates a schema for an output (label) attribute.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time, the corresponding <a href='../builtins/File.html'><code>File</code></a> can be retrieved using <a href='../builtins/ctx.html#outputs'><code>ctx.outputs</code></a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="output.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="output.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - </tbody> - </table> - - <h2 id="output_list">output_list</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.output_list(allow_empty=True, *, doc=None, mandatory=False)</pre></p> - - Creates a schema for a list-of-outputs attribute.<p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time, the corresponding <a href='../builtins/File.html'><code>File</code></a> can be retrieved using <a href='../builtins/ctx.html#outputs'><code>ctx.outputs</code></a>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="output_list.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True if the attribute can be empty. - </td> - </tr> - <tr> - <td id="output_list.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="output_list.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - </tbody> - </table> - - <h2 id="string">string</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string(*, configurable=unbound, default='', doc=None, mandatory=False, values=[])</pre></p> - - Creates a schema for a <a href='../core/string.html#attr'>string</a> attribute. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="string.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="string.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or NativeComputedDefault; - default is <code>''</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule. - </td> - </tr> - <tr> - <td id="string.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="string.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - <tr> - <td id="string.values"> - <code>values</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - The list of allowed values for the attribute. An error is raised if any other value is given. - </td> - </tr> - </tbody> - </table> - - <h2 id="string_dict">string_dict</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False)</pre></p> - - Creates a schema for an attribute holding a dictionary, where the keys and values are strings. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="string_dict.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True if the attribute can be empty. - </td> - </tr> - <tr> - <td id="string_dict.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="string_dict.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule. - </td> - </tr> - <tr> - <td id="string_dict.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="string_dict.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - </tbody> - </table> - - <h2 id="string_keyed_label_dict">string_keyed_label_dict</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string_keyed_label_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, cfg=None, aspects=[])</pre></p> - - <p>Creates a schema for an attribute whose value is a dictionary where the keys are strings and the values are labels. This is a dependency attribute.</p><p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a> values. If a string is supplied in place of a <code>Label</code>, it will be converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.<p>At analysis time (within the rule's implementation function), when retrieving the attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access the providers of the current target's dependencies. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="string_keyed_label_dict.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True if the attribute can be empty. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; or <a class="anchor" href="../core/function.html">function</a>; - default is <code>{}</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.string_keyed_label_dict(default = {"foo": "//a:b", "bar": "//a:c"})</code>. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.allow_files"> - <code>allow_files</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>). - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.allow_rules"> - <code>allow_rules</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.providers"> - <code>providers</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - The providers that must be given by any dependency appearing in this attribute.<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.for_dependency_resolution"> - <code>for_dependency_resolution</code> - </td> - <td> - default is <code>unbound</code><br/> - If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.flags"> - <code>flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Deprecated, will be removed. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.cfg"> - <code>cfg</code> - </td> - <td> - default is <code>None</code><br/> - <a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. - </td> - </tr> - <tr> - <td id="string_keyed_label_dict.aspects"> - <code>aspects</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/Aspect.html">Aspect</a>s; - default is <code>[]</code><br/> - Aspects that should be applied to the dependency or dependencies specified by this attribute. - </td> - </tr> - </tbody> - </table> - - <h2 id="string_list">string_list</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None)</pre></p> - - Creates a schema for a list-of-strings attribute. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="string_list.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - <tr> - <td id="string_list.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True if the attribute can be empty. - </td> - </tr> - <tr> - <td id="string_list.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="string_list.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or NativeComputedDefault; - default is <code>[]</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule. - </td> - </tr> - <tr> - <td id="string_list.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - </tbody> - </table> - - <h2 id="string_list_dict">string_list_dict</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Attribute.html">Attribute</a> attr.string_list_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False)</pre></p> - - Creates a schema for an attribute holding a dictionary, where the keys are strings and the values are lists of strings. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="string_list_dict.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True if the attribute can be empty. - </td> - </tr> - <tr> - <td id="string_list_dict.configurable"> - <code>configurable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; or unbound; - default is <code>unbound</code><br/> - This argument can only be specified for an attribute of a symbolic macro.<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable. - </td> - </tr> - <tr> - <td id="string_list_dict.default"> - <code>default</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - A default value to use if no value for this attribute is given when instantiating the rule. - </td> - </tr> - <tr> - <td id="string_list_dict.doc"> - <code>doc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - A description of the attribute that can be extracted by documentation generating tools. - </td> - </tr> - <tr> - <td id="string_list_dict.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If true, the value must be specified explicitly (even if it has a <code>default</code>). - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +This is a top-level module for defining the attribute schemas of a rule or aspect. Each function returns an object representing the schema of a single attribute. These objects are used as the values of the `attrs` dictionary argument of [`rule()`](../globals/bzl.html#rule), [`aspect()`](../globals/bzl.html#aspect), [`repository_rule()`](../globals/bzl.html#repository_rule) and [`tag_class()`](../globals/bzl.html#tag_class). + +See the Rules page for more on [defining](https://bazel.build/extending/rules#attributes) +and [using](https://bazel.build/extending/rules#implementation_function) attributes. + +## Members + +- [bool](#bool) +- [int](#int) +- [int_list](#int_list) +- [label](#label) +- [label_keyed_string_dict](#label_keyed_string_dict) +- [label_list](#label_list) +- [output](#output) +- [output_list](#output_list) +- [string](#string) +- [string_dict](#string_dict) +- [string_keyed_label_dict](#string_keyed_label_dict) +- [string_list](#string_list) +- [string_list_dict](#string_list_dict) + +## bool + +``` rule-signature +Attribute attr.bool(*, configurable=unbound, default=False, doc=None, mandatory=False) +``` + +Creates a schema for a boolean attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`bool`](../core/bool.html). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="bool.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="bool.default"><code>default</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.</td> +</tr> +<tr> +<td id="bool.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="bool.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +</tbody> +</table> + +## int + +``` rule-signature +Attribute attr.int(*, configurable=unbound, default=0, doc=None, mandatory=False, values=[]) +``` + +Creates a schema for an integer attribute. The value must be in the signed 32-bit range. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`int`](../core/int.html). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="int.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="int.default"><code>default</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>0</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.</td> +</tr> +<tr> +<td id="int.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="int.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +<tr> +<td id="int.values"><code>values</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/int.html" class="anchor">int</a>s; +default is <code>[]</code><br /> +The list of allowed values for the attribute. An error is raised if any other value is given.</td> +</tr> +</tbody> +</table> + +## int_list + +``` rule-signature +Attribute attr.int_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None) +``` + +Creates a schema for a list-of-integers attribute. Each element must be in the signed 32-bit range. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="int_list.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +<tr> +<td id="int_list.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True if the attribute can be empty.</td> +</tr> +<tr> +<td id="int_list.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="int_list.default"><code>default</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/int.html" class="anchor">int</a>s; +default is <code>[]</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.</td> +</tr> +<tr> +<td id="int_list.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +</tbody> +</table> + +## label + +``` rule-signature +Attribute attr.label(*, configurable=unbound, default=None, materializer=None, doc=None, executable=False, allow_files=None, allow_single_file=None, mandatory=False, skip_validations=False, providers=[], for_dependency_resolution=unbound, allow_rules=None, cfg=None, aspects=[], flags=[]) +``` + +Creates a schema for a label attribute. This is a dependency attribute. + +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html)s. This allows you to access the providers of the current target's dependencies. + +In addition to ordinary source files, this kind of attribute is often used to refer to a tool -- for example, a compiler. Such tools are considered to be dependencies, just like source files. To avoid requiring users to specify the tool's label every time they use the rule in their BUILD files, you can hard-code the label of a canonical tool as the `default` value of this attribute. If you also want to prevent users from overriding this default, you can make the attribute private by giving it a name that starts with an underscore. See the [Rules](https://bazel.build/extending/rules#private-attributes) page for more information. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="label.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="label.default"><code>default</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/LateBoundDefault.html" class="anchor">LateBoundDefault</a>; or NativeComputedDefault; or <a href="../core/function.html" class="anchor">function</a>; or <code>None</code>; +default is <code>None</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify a default value, for example, <code>attr.label(default = "//a:b")</code>.</td> +</tr> +<tr> +<td id="label.materializer"><code>materializer</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +default is <code>None</code><br /> +<strong>Experimental</strong>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_dormant_deps</code><br /> +If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute</td> +</tr> +<tr> +<td id="label.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="label.executable"><code>executable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +True if the dependency has to be executable. This means the label must refer to an executable file, or to a rule that outputs an executable file. Access the label with <code>ctx.executable.<attribute_name></code>.</td> +</tr> +<tr> +<td id="label.allow_files"><code>allow_files</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>).</td> +</tr> +<tr> +<td id="label.allow_single_file"><code>allow_single_file</code></td> +<td>default is <code>None</code><br /> +This is similar to <code>allow_files</code>, with the restriction that the label must correspond to a single <a href="../builtins/File.html">File</a>. Access it through <code>ctx.file.<attribute_name></code>.</td> +</tr> +<tr> +<td id="label.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +<tr> +<td id="label.skip_validations"><code>skip_validations</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future.</td> +</tr> +<tr> +<td id="label.providers"><code>providers</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +The providers that must be given by any dependency appearing in this attribute. +<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice.</p></td> +</tr> +<tr> +<td id="label.for_dependency_resolution"><code>for_dependency_resolution</code></td> +<td>default is <code>unbound</code><br /> +If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes.</td> +</tr> +<tr> +<td id="label.allow_rules"><code>allow_rules</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.</td> +</tr> +<tr> +<td id="label.cfg"><code>cfg</code></td> +<td>default is <code>None</code><br /> +<a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. This parameter is required if <code>executable</code> is True to guard against accidentally building host tools in the target configuration. <code>"target"</code> has no semantic effect, so don't set it when <code>executable</code> is False unless it really helps clarify your intentions.</td> +</tr> +<tr> +<td id="label.aspects"><code>aspects</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; +default is <code>[]</code><br /> +Aspects that should be applied to the dependency or dependencies specified by this attribute.</td> +</tr> +<tr> +<td id="label.flags"><code>flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Deprecated, will be removed.</td> +</tr> +</tbody> +</table> + +## label_keyed_string_dict + +``` rule-signature +Attribute attr.label_keyed_string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[]) +``` + +Creates a schema for an attribute holding a dictionary, where the keys are labels and the values are strings. This is a dependency attribute. + +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html)s. This allows you to access the providers of the current target's dependencies. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="label_keyed_string_dict.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True if the attribute can be empty.</td> +</tr> +<tr> +<td id="label_keyed_string_dict.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="label_keyed_string_dict.default"><code>default</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <a href="../core/function.html" class="anchor">function</a>; +default is <code>{}</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"})</code>.</td> +</tr> +<tr> +<td id="label_keyed_string_dict.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="label_keyed_string_dict.allow_files"><code>allow_files</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>).</td> +</tr> +<tr> +<td id="label_keyed_string_dict.allow_rules"><code>allow_rules</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.</td> +</tr> +<tr> +<td id="label_keyed_string_dict.providers"><code>providers</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +The providers that must be given by any dependency appearing in this attribute. +<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice.</p></td> +</tr> +<tr> +<td id="label_keyed_string_dict.for_dependency_resolution"><code>for_dependency_resolution</code></td> +<td>default is <code>unbound</code><br /> +If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes.</td> +</tr> +<tr> +<td id="label_keyed_string_dict.flags"><code>flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Deprecated, will be removed.</td> +</tr> +<tr> +<td id="label_keyed_string_dict.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +<tr> +<td id="label_keyed_string_dict.skip_validations"><code>skip_validations</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future.</td> +</tr> +<tr> +<td id="label_keyed_string_dict.cfg"><code>cfg</code></td> +<td>default is <code>None</code><br /> +<a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>.</td> +</tr> +<tr> +<td id="label_keyed_string_dict.aspects"><code>aspects</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; +default is <code>[]</code><br /> +Aspects that should be applied to the dependency or dependencies specified by this attribute.</td> +</tr> +</tbody> +</table> + +## label_list + +``` rule-signature +Attribute attr.label_list(allow_empty=True, *, configurable=unbound, default=[], materializer=None, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[]) +``` + +Creates a schema for a list-of-labels attribute. This is a dependency attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [list](../core/list.html) of [`Target`s](../builtins/Target.html). + +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html)s. This allows you to access the providers of the current target's dependencies. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="label_list.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True if the attribute can be empty.</td> +</tr> +<tr> +<td id="label_list.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="label_list.default"><code>default</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Label.html" class="anchor">Label</a>s; or <a href="../core/function.html" class="anchor">function</a>; +default is <code>[]</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.label_list(default = ["//a:b", "//a:c"])</code>.</td> +</tr> +<tr> +<td id="label_list.materializer"><code>materializer</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +default is <code>None</code><br /> +<strong>Experimental</strong>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_dormant_deps</code><br /> +If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute</td> +</tr> +<tr> +<td id="label_list.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="label_list.allow_files"><code>allow_files</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>).</td> +</tr> +<tr> +<td id="label_list.allow_rules"><code>allow_rules</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.</td> +</tr> +<tr> +<td id="label_list.providers"><code>providers</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +The providers that must be given by any dependency appearing in this attribute. +<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice.</p></td> +</tr> +<tr> +<td id="label_list.for_dependency_resolution"><code>for_dependency_resolution</code></td> +<td>default is <code>unbound</code><br /> +If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes.</td> +</tr> +<tr> +<td id="label_list.flags"><code>flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Deprecated, will be removed.</td> +</tr> +<tr> +<td id="label_list.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +<tr> +<td id="label_list.skip_validations"><code>skip_validations</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future.</td> +</tr> +<tr> +<td id="label_list.cfg"><code>cfg</code></td> +<td>default is <code>None</code><br /> +<a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>.</td> +</tr> +<tr> +<td id="label_list.aspects"><code>aspects</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; +default is <code>[]</code><br /> +Aspects that should be applied to the dependency or dependencies specified by this attribute.</td> +</tr> +</tbody> +</table> + +## output + +``` rule-signature +Attribute attr.output(*, doc=None, mandatory=False) +``` + +Creates a schema for an output (label) attribute. + +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time, the corresponding [`File`](../builtins/File.html) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="output.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="output.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +</tbody> +</table> + +## output_list + +``` rule-signature +Attribute attr.output_list(allow_empty=True, *, doc=None, mandatory=False) +``` + +Creates a schema for a list-of-outputs attribute. + +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time, the corresponding [`File`](../builtins/File.html) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="output_list.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True if the attribute can be empty.</td> +</tr> +<tr> +<td id="output_list.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="output_list.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +</tbody> +</table> + +## string + +``` rule-signature +Attribute attr.string(*, configurable=unbound, default='', doc=None, mandatory=False, values=[]) +``` + +Creates a schema for a [string](../core/string.html#attr) attribute. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="string.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="string.default"><code>default</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or NativeComputedDefault; +default is <code>''</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.</td> +</tr> +<tr> +<td id="string.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="string.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +<tr> +<td id="string.values"><code>values</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +The list of allowed values for the attribute. An error is raised if any other value is given.</td> +</tr> +</tbody> +</table> + +## string_dict + +``` rule-signature +Attribute attr.string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False) +``` + +Creates a schema for an attribute holding a dictionary, where the keys and values are strings. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="string_dict.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True if the attribute can be empty.</td> +</tr> +<tr> +<td id="string_dict.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="string_dict.default"><code>default</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.</td> +</tr> +<tr> +<td id="string_dict.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="string_dict.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +</tbody> +</table> + +## string_keyed_label_dict + +``` rule-signature +Attribute attr.string_keyed_label_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, cfg=None, aspects=[]) +``` + +Creates a schema for an attribute whose value is a dictionary where the keys are strings and the values are labels. This is a dependency attribute. + +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html)s. This allows you to access the providers of the current target's dependencies. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="string_keyed_label_dict.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True if the attribute can be empty.</td> +</tr> +<tr> +<td id="string_keyed_label_dict.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="string_keyed_label_dict.default"><code>default</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; or <a href="../core/function.html" class="anchor">function</a>; +default is <code>{}</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.string_keyed_label_dict(default = {"foo": "//a:b", "bar": "//a:c"})</code>.</td> +</tr> +<tr> +<td id="string_keyed_label_dict.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="string_keyed_label_dict.allow_files"><code>allow_files</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>).</td> +</tr> +<tr> +<td id="string_keyed_label_dict.allow_rules"><code>allow_rules</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.</td> +</tr> +<tr> +<td id="string_keyed_label_dict.providers"><code>providers</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +The providers that must be given by any dependency appearing in this attribute. +<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice.</p></td> +</tr> +<tr> +<td id="string_keyed_label_dict.for_dependency_resolution"><code>for_dependency_resolution</code></td> +<td>default is <code>unbound</code><br /> +If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes.</td> +</tr> +<tr> +<td id="string_keyed_label_dict.flags"><code>flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Deprecated, will be removed.</td> +</tr> +<tr> +<td id="string_keyed_label_dict.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +<tr> +<td id="string_keyed_label_dict.cfg"><code>cfg</code></td> +<td>default is <code>None</code><br /> +<a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>.</td> +</tr> +<tr> +<td id="string_keyed_label_dict.aspects"><code>aspects</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; +default is <code>[]</code><br /> +Aspects that should be applied to the dependency or dependencies specified by this attribute.</td> +</tr> +</tbody> +</table> + +## string_list + +``` rule-signature +Attribute attr.string_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None) +``` + +Creates a schema for a list-of-strings attribute. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="string_list.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +<tr> +<td id="string_list.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True if the attribute can be empty.</td> +</tr> +<tr> +<td id="string_list.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="string_list.default"><code>default</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or NativeComputedDefault; +default is <code>[]</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.</td> +</tr> +<tr> +<td id="string_list.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +</tbody> +</table> + +## string_list_dict + +``` rule-signature +Attribute attr.string_list_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False) +``` + +Creates a schema for an attribute holding a dictionary, where the keys are strings and the values are lists of strings. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="string_list_dict.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True if the attribute can be empty.</td> +</tr> +<tr> +<td id="string_list_dict.configurable"><code>configurable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; +default is <code>unbound</code><br /> +This argument can only be specified for an attribute of a symbolic macro. +<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> +<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> +</tr> +<tr> +<td id="string_list_dict.default"><code>default</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +A default value to use if no value for this attribute is given when instantiating the rule.</td> +</tr> +<tr> +<td id="string_list_dict.doc"><code>doc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +A description of the attribute that can be extracted by documentation generating tools.</td> +</tr> +<tr> +<td id="string_list_dict.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/toplevel/cc_common.mdx b/rules/lib/toplevel/cc_common.mdx index 0f63f0d..fd8a39f 100644 --- a/rules/lib/toplevel/cc_common.mdx +++ b/rules/lib/toplevel/cc_common.mdx @@ -2,2021 +2,1391 @@ title: 'cc_common' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.cc_common">cc_common</h1> +# cc_common {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcModuleApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Utilities for C++ compilation, linking, and command line generation. -<h2>Members</h2> -<ul> - <li> - <a href="#action_is_enabled">action_is_enabled</a> - </li> - <li> - <a href="#CcToolchainInfo">CcToolchainInfo</a> - </li> - <li> - <a href="#compile">compile</a> - </li> - <li> - <a href="#configure_features">configure_features</a> - </li> - <li> - <a href="#create_cc_toolchain_config_info">create_cc_toolchain_config_info</a> - </li> - <li> - <a href="#create_compilation_context">create_compilation_context</a> - </li> - <li> - <a href="#create_compilation_outputs">create_compilation_outputs</a> - </li> - <li> - <a href="#create_compile_variables">create_compile_variables</a> - </li> - <li> - <a href="#create_library_to_link">create_library_to_link</a> - </li> - <li> - <a href="#create_link_variables">create_link_variables</a> - </li> - <li> - <a href="#create_linker_input">create_linker_input</a> - </li> - <li> - <a href="#create_linking_context">create_linking_context</a> - </li> - <li> - <a href="#create_linking_context_from_compilation_outputs">create_linking_context_from_compilation_outputs</a> - </li> - <li> - <a href="#create_lto_compilation_context">create_lto_compilation_context</a> - </li> - <li> - <a href="#do_not_use_tools_cpp_compiler_present">do_not_use_tools_cpp_compiler_present</a> - </li> - <li> - <a href="#get_environment_variables">get_environment_variables</a> - </li> - <li> - <a href="#get_execution_requirements">get_execution_requirements</a> - </li> - <li> - <a href="#get_memory_inefficient_command_line">get_memory_inefficient_command_line</a> - </li> - <li> - <a href="#get_tool_for_action">get_tool_for_action</a> - </li> - <li> - <a href="#is_enabled">is_enabled</a> - </li> - <li> - <a href="#link">link</a> - </li> - <li> - <a href="#merge_cc_infos">merge_cc_infos</a> - </li> - <li> - <a href="#merge_compilation_contexts">merge_compilation_contexts</a> - </li> - <li> - <a href="#merge_compilation_outputs">merge_compilation_outputs</a> - </li> - </ul> - - <h2 id="action_is_enabled">action_is_enabled</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cc_common.action_is_enabled(*, feature_configuration, action_name)</pre></p> - - Returns True if given action_config is enabled in the feature configuration. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="action_is_enabled.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - Feature configuration to be queried. - </td> - </tr> - <tr> - <td id="action_is_enabled.action_name"> - <code>action_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of the action_config. - </td> - </tr> - </tbody> - </table> - - <h2 id="CcToolchainInfo">CcToolchainInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> cc_common.CcToolchainInfo</pre></p> - - The key used to retrieve the provider that contains information about the C++ toolchain being used - - <h2 id="compile">compile</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> cc_common.compile(*, actions, feature_configuration, cc_toolchain, srcs=[], public_hdrs=[], private_hdrs=[], includes=[], quote_includes=[], system_includes=[], framework_includes=[], defines=[], local_defines=[], include_prefix='', strip_include_prefix='', user_compile_flags=[], conly_flags=[], cxx_flags=[], compilation_contexts=[], name, disallow_pic_outputs=False, disallow_nopic_outputs=False, additional_inputs=[], module_interfaces=unbound)</pre></p> - - Should be used for C++ compilation. Returns tuple of (<code>CompilationContext</code>, <code>CcCompilationOutputs</code>). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="compile.actions"> - <code>actions</code> - </td> - <td> - <a class="anchor" href="../builtins/actions.html">actions</a>; - required<br/> - <code>actions</code> object. - </td> - </tr> - <tr> - <td id="compile.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - <code>feature_configuration</code> to be queried. - </td> - </tr> - <tr> - <td id="compile.cc_toolchain"> - <code>cc_toolchain</code> - </td> - <td> - Info; - required<br/> - <code>CcToolchainInfo</code> provider to be used. - </td> - </tr> - <tr> - <td id="compile.srcs"> - <code>srcs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - The list of source files to be compiled. - </td> - </tr> - <tr> - <td id="compile.public_hdrs"> - <code>public_hdrs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of headers needed for compilation of srcs and may be included by dependent rules transitively. - </td> - </tr> - <tr> - <td id="compile.private_hdrs"> - <code>private_hdrs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of headers needed for compilation of srcs and NOT to be included by dependent rules. - </td> - </tr> - <tr> - <td id="compile.includes"> - <code>includes</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>[]</code><br/> - Search paths for header files referenced both by angle bracket and quotes. Usually passed with -I. Propagated to dependents transitively. - </td> - </tr> - <tr> - <td id="compile.quote_includes"> - <code>quote_includes</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Search paths for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. Propagated to dependents transitively. - </td> - </tr> - <tr> - <td id="compile.system_includes"> - <code>system_includes</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Search paths for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. Propagated to dependents transitively. - </td> - </tr> - <tr> - <td id="compile.framework_includes"> - <code>framework_includes</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Search paths for header files from Apple frameworks. They can be either relative to the exec root or absolute. Usually passed with -F. Propagated to dependents transitively. - </td> - </tr> - <tr> - <td id="compile.defines"> - <code>defines</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Set of defines needed to compile this target. Each define is a string. Propagated to dependents transitively. - </td> - </tr> - <tr> - <td id="compile.local_defines"> - <code>local_defines</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Set of defines needed to compile this target. Each define is a string. Not propagated to dependents transitively. - </td> - </tr> - <tr> - <td id="compile.include_prefix"> - <code>include_prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the strip_include_prefix attribute is removed before this prefix is added. - </td> - </tr> - <tr> - <td id="compile.strip_include_prefix"> - <code>strip_include_prefix</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the include_prefix attribute is added after this prefix is stripped. - </td> - </tr> - <tr> - <td id="compile.user_compile_flags"> - <code>user_compile_flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Additional list of compilation options. - </td> - </tr> - <tr> - <td id="compile.conly_flags"> - <code>conly_flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Additional list of compilation options for C compiles. - </td> - </tr> - <tr> - <td id="compile.cxx_flags"> - <code>cxx_flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Additional list of compilation options for C++ compiles. - </td> - </tr> - <tr> - <td id="compile.compilation_contexts"> - <code>compilation_contexts</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Headers from dependencies used for compilation. - </td> - </tr> - <tr> - <td id="compile.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - This is used for naming the output artifacts of actions created by this method. See also the `main_output` arg. - </td> - </tr> - <tr> - <td id="compile.disallow_pic_outputs"> - <code>disallow_pic_outputs</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether PIC outputs should be created. - </td> - </tr> - <tr> - <td id="compile.disallow_nopic_outputs"> - <code>disallow_nopic_outputs</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether NOPIC outputs should be created. - </td> - </tr> - <tr> - <td id="compile.additional_inputs"> - <code>additional_inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of additional files needed for compilation of srcs - </td> - </tr> - <tr> - <td id="compile.module_interfaces"> - <code>module_interfaces</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>unbound</code><br/> - The list of module interfaces source files to be compiled. Note: this is an experimental feature, only enabled with --experimental_cpp_modules - </td> - </tr> - </tbody> - </table> - - <h2 id="configure_features">configure_features</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a> cc_common.configure_features(*, ctx, cc_toolchain, language=None, requested_features=[], unsupported_features=[])</pre></p> - - Creates a feature_configuration instance. Requires the cpp configuration fragment. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="configure_features.ctx"> - <code>ctx</code> - </td> - <td> - <a class="anchor" href="../builtins/ctx.html">ctx</a>; - required<br/> - The rule context. - </td> - </tr> - <tr> - <td id="configure_features.cc_toolchain"> - <code>cc_toolchain</code> - </td> - <td> - Info; - required<br/> - cc_toolchain for which we configure features. - </td> - </tr> - <tr> - <td id="configure_features.language"> - <code>language</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The language to configure for: either c++ or objc (default c++) - </td> - </tr> - <tr> - <td id="configure_features.requested_features"> - <code>requested_features</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of features to be enabled. - </td> - </tr> - <tr> - <td id="configure_features.unsupported_features"> - <code>unsupported_features</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of features that are unsupported by the current rule. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_cc_toolchain_config_info">create_cc_toolchain_config_info</h2> - <p><pre class="rule-signature"><code>None</code> cc_common.create_cc_toolchain_config_info(*, ctx, features=[], action_configs=[], artifact_name_patterns=[], cxx_builtin_include_directories=[], toolchain_identifier, host_system_name=None, target_system_name=None, target_cpu=None, target_libc=None, compiler, abi_version=None, abi_libc_version=None, tool_paths=[], make_variables=[], builtin_sysroot=None)</pre></p> - - Creates a <code>CcToolchainConfigInfo</code> provider - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_cc_toolchain_config_info.ctx"> - <code>ctx</code> - </td> - <td> - <a class="anchor" href="../builtins/ctx.html">ctx</a>; - required<br/> - The rule context. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.features"> - <code>features</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Contains all flag specifications for one feature.<p>Arguments:</p><p><code>name</code>: The feature's name. It is possible to introduce a feature without a change to Bazel by adding a 'feature' section to the toolchain and adding the corresponding string as feature in the <code>BUILD</code> file.</p><p><code>enabled</code>: If 'True', this feature is enabled unless a rule type explicitly marks it as unsupported.</p><p><code>flag_sets</code>: A FlagSet list. If the given feature is enabled, the flag sets will be applied for the actions are specified for. </p><p><code>env_sets</code>: an EnvSet list. If the given feature is enabled, the env sets will be applied for the actions they are specified for. </p><p><code>requires</code>: A list of feature sets defining when this feature is supported by the toolchain. The feature is supported if any of the feature sets fully apply, that is, when all features of a feature set are enabled. If <code>requires</code> is omitted, the feature is supported independently of which other features are enabled. Use this for example to filter flags depending on the build mode enabled (opt / fastbuild / dbg). </p><p><code>implies</code>: A string list of features or action configs that are automatically enabled when this feature is enabled. If any of the implied features or action configs cannot be enabled, this feature will (silently) not be enabled either. </p><p><code>provides</code>: A list of names this feature conflicts with. </p>A feature cannot be enabled if:</br>- <code>provides</code> contains the name of a different feature or action config that we want to enable.</br>- <code>provides</code> contains the same value as a 'provides' in a different feature or action config that we want to enable. Use this in order to ensure that incompatible features cannot be accidentally activated at the same time, leading to hard to diagnose compiler errors. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.action_configs"> - <code>action_configs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - An action config corresponds to a Bazel action, and allows selection of a tool based on activated features. Action config activation occurs by the same semantics as features: a feature can 'require' or 'imply' an action config in the same way that it would another feature.<p>Arguments:</p><p><code>action_name</code>: The name of the Bazel action that this config applies to, e.g. 'c-compile' or 'c-module-compile'.</p><p><code>enabled</code>: If 'True', this action is enabled unless a rule type explicitly marks it as unsupported.</p><p><code>tools</code>: The tool applied to the action will be the first tool with a feature set that matches the feature configuration. An error will be thrown if no tool matches a provided feature configuration - for that reason, it's a good idea to provide a default tool with an empty feature set.</p><p><code>flag_sets</code>: If the given action config is enabled, the flag sets will be applied to the corresponding action.</p><p><code>implies</code>: A list of features or action configs that are automatically enabled when this action config is enabled. If any of the implied features or action configs cannot be enabled, this action config will (silently) not be enabled either.</p> - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.artifact_name_patterns"> - <code>artifact_name_patterns</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - The name for an artifact of a given category of input or output artifacts to an action.<p>Arguments:</p><p><code>category_name</code>: The category of artifacts that this selection applies to. This field is compared against a list of categories defined in Bazel. Example categories include "linked_output" or the artifact for this selection. Together with the extension it is used to create an artifact name based on the target name.</p><p><code>extension</code>: The extension for creating the artifact for this selection. Together with the prefix it is used to create an artifact name based on the target name.</p> - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.cxx_builtin_include_directories"> - <code>cxx_builtin_include_directories</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - <p>Built-in include directories for C++ compilation. These should be the exact paths used by the compiler, and are generally relative to the exec root.</p><p>The paths used by the compiler can be determined by 'gcc -E -xc++ - -v'.</p><p>We currently use the C++ paths also for C compilation, which is safe as long as there are no name clashes between C++ and C header files.</p><p>Relative paths are resolved relative to the configuration file directory.</p><p>If the compiler has --sysroot support, then these paths should use %sysroot% rather than the include path, and specify the sysroot attribute in order to give blaze the information necessary to make the correct replacements.</p> - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.toolchain_identifier"> - <code>toolchain_identifier</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - <p>The unique identifier of the toolchain within the crosstool release. It must be possible to use this as a directory name in a path.</p><p>It has to match the following regex: [a-zA-Z_][\.\- \w]*</p> - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.host_system_name"> - <code>host_system_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Ignored. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.target_system_name"> - <code>target_system_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Deprecated. The GNU System Name. The string is exposed to CcToolchainInfo.target_gnu_system_name. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.target_cpu"> - <code>target_cpu</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Deprecated: Use cpu based constraints instead. If the string is "k8", `target_cpu` will be omitted from the filename of raw FDO profile data. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.target_libc"> - <code>target_libc</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Deprecated: Use OS based constraints instead. The libc version string (e.g. "glibc-2.2.2"). If the string is "macosx", platform is assumed to be MacOS. Otherwise, Linux. The string is exposed to CcToolchainInfo.libc. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.compiler"> - <code>compiler</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The compiler string (e.g. "gcc"). The current toolchain's compiler is exposed to `@bazel_tools//tools/cpp:compiler (compiler_flag)` as a flag value. Targets that require compiler-specific flags can use the config_settings in https://github.com/bazelbuild/rules_cc/blob/main/cc/compiler/BUILD in select() statements or create custom config_setting if the existing settings don't suffice. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.abi_version"> - <code>abi_version</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The abi in use, which is a gcc version. E.g.: "gcc-3.4". The string is set to C++ toolchain variable ABI. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.abi_libc_version"> - <code>abi_libc_version</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The glibc version used by the abi we're using. The string is set to C++ toolchain variable ABI_LIBC_VERSION. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.tool_paths"> - <code>tool_paths</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Tool locations.<p>Arguments:</p><p><code>name</code>: Name of the tool.</p><p><code>path</code>: Location of the tool; Can be absolute path (in case of non hermetic toolchain), or path relative to the cc_toolchain's package.</p> - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.make_variables"> - <code>make_variables</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - A make variable that is made accessible to rules. - </td> - </tr> - <tr> - <td id="create_cc_toolchain_config_info.builtin_sysroot"> - <code>builtin_sysroot</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The built-in sysroot. If this attribute is not present, Bazel does not allow using a different sysroot, i.e. through the --grte_top option. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_compilation_context">create_compilation_context</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/CompilationContext.html">CompilationContext</a> cc_common.create_compilation_context(*, headers=unbound, system_includes=unbound, includes=unbound, quote_includes=unbound, framework_includes=unbound, defines=unbound, local_defines=unbound)</pre></p> - - Creates a <code>CompilationContext</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_compilation_context.headers"> - <code>headers</code> - </td> - <td> - default is <code>unbound</code><br/> - Set of headers needed to compile this target - </td> - </tr> - <tr> - <td id="create_compilation_context.system_includes"> - <code>system_includes</code> - </td> - <td> - default is <code>unbound</code><br/> - Set of search paths for header files referenced by angle brackets, i.e. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem - </td> - </tr> - <tr> - <td id="create_compilation_context.includes"> - <code>includes</code> - </td> - <td> - default is <code>unbound</code><br/> - Set of search paths for header files referenced both by angle bracket and quotes.Usually passed with -I - </td> - </tr> - <tr> - <td id="create_compilation_context.quote_includes"> - <code>quote_includes</code> - </td> - <td> - default is <code>unbound</code><br/> - Set of search paths for header files referenced by quotes, i.e. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote - </td> - </tr> - <tr> - <td id="create_compilation_context.framework_includes"> - <code>framework_includes</code> - </td> - <td> - default is <code>unbound</code><br/> - Set of framework search paths for header files (Apple platform only) - </td> - </tr> - <tr> - <td id="create_compilation_context.defines"> - <code>defines</code> - </td> - <td> - default is <code>unbound</code><br/> - Set of defines needed to compile this target. Each define is a string. Propagated transitively to dependents. - </td> - </tr> - <tr> - <td id="create_compilation_context.local_defines"> - <code>local_defines</code> - </td> - <td> - default is <code>unbound</code><br/> - Set of defines needed to compile this target. Each define is a string. Not propagated transitively to dependents. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_compilation_outputs">create_compilation_outputs</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/CcCompilationOutputs.html">CcCompilationOutputs</a> cc_common.create_compilation_outputs(*, objects=None, pic_objects=None)</pre></p> - - Create compilation outputs object. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_compilation_outputs.objects"> - <code>objects</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - List of object files. - </td> - </tr> - <tr> - <td id="create_compilation_outputs.pic_objects"> - <code>pic_objects</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - List of pic object files. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_compile_variables">create_compile_variables</h2> - <p><pre class="rule-signature">Variables cc_common.create_compile_variables(*, cc_toolchain, feature_configuration, source_file=None, output_file=None, user_compile_flags=None, include_directories=None, quote_include_directories=None, system_include_directories=None, framework_include_directories=None, preprocessor_defines=None, thinlto_index=None, thinlto_input_bitcode_file=None, thinlto_output_object_file=None, use_pic=False, add_legacy_cxx_options=False, variables_extension=unbound)</pre></p> - - Returns variables used for compilation actions. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_compile_variables.cc_toolchain"> - <code>cc_toolchain</code> - </td> - <td> - Info; - required<br/> - cc_toolchain for which we are creating build variables. - </td> - </tr> - <tr> - <td id="create_compile_variables.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - Feature configuration to be queried. - </td> - </tr> - <tr> - <td id="create_compile_variables.source_file"> - <code>source_file</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Optional source file path for the compilation. Please prefer passing source_file here over appending it to the end of the command line generated from cc_common.get_memory_inefficient_command_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. - </td> - </tr> - <tr> - <td id="create_compile_variables.output_file"> - <code>output_file</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Optional output file path of the compilation. Please prefer passing output_file here over appending it to the end of the command line generated from cc_common.get_memory_inefficient_command_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. - </td> - </tr> - <tr> - <td id="create_compile_variables.user_compile_flags"> - <code>user_compile_flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - List of additional compilation flags (copts). - </td> - </tr> - <tr> - <td id="create_compile_variables.include_directories"> - <code>include_directories</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - Depset of include directories. - </td> - </tr> - <tr> - <td id="create_compile_variables.quote_include_directories"> - <code>quote_include_directories</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - Depset of quote include directories. - </td> - </tr> - <tr> - <td id="create_compile_variables.system_include_directories"> - <code>system_include_directories</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - Depset of system include directories. - </td> - </tr> - <tr> - <td id="create_compile_variables.framework_include_directories"> - <code>framework_include_directories</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - Depset of framework include directories. - </td> - </tr> - <tr> - <td id="create_compile_variables.preprocessor_defines"> - <code>preprocessor_defines</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; or <code>None</code>; - default is <code>None</code><br/> - Depset of preprocessor defines. - </td> - </tr> - <tr> - <td id="create_compile_variables.thinlto_index"> - <code>thinlto_index</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - LTO index file path. - </td> - </tr> - <tr> - <td id="create_compile_variables.thinlto_input_bitcode_file"> - <code>thinlto_input_bitcode_file</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Bitcode file that is input to LTO backend. - </td> - </tr> - <tr> - <td id="create_compile_variables.thinlto_output_object_file"> - <code>thinlto_output_object_file</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - Object file that is output by LTO backend. - </td> - </tr> - <tr> - <td id="create_compile_variables.use_pic"> - <code>use_pic</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - When true the compilation will generate position independent code. - </td> - </tr> - <tr> - <td id="create_compile_variables.add_legacy_cxx_options"> - <code>add_legacy_cxx_options</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Unused. - </td> - </tr> - <tr> - <td id="create_compile_variables.variables_extension"> - <code>variables_extension</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>unbound</code><br/> - A dictionary of additional variables used by compile actions. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_library_to_link">create_library_to_link</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/LibraryToLink.html">LibraryToLink</a> cc_common.create_library_to_link(*, actions, feature_configuration=None, cc_toolchain=None, static_library=None, pic_static_library=None, dynamic_library=None, interface_library=None, pic_objects=unbound, objects=unbound, alwayslink=False, dynamic_library_symlink_path='', interface_library_symlink_path='')</pre></p> - - Creates <code>LibraryToLink</code> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_library_to_link.actions"> - <code>actions</code> - </td> - <td> - required<br/> - <code>actions</code> object. - </td> - </tr> - <tr> - <td id="create_library_to_link.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - default is <code>None</code><br/> - <code>feature_configuration</code> to be queried. - </td> - </tr> - <tr> - <td id="create_library_to_link.cc_toolchain"> - <code>cc_toolchain</code> - </td> - <td> - default is <code>None</code><br/> - <code>CcToolchainInfo</code> provider to be used. - </td> - </tr> - <tr> - <td id="create_library_to_link.static_library"> - <code>static_library</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - <code>File</code> of static library to be linked. - </td> - </tr> - <tr> - <td id="create_library_to_link.pic_static_library"> - <code>pic_static_library</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - <code>File</code> of pic static library to be linked. - </td> - </tr> - <tr> - <td id="create_library_to_link.dynamic_library"> - <code>dynamic_library</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - <code>File</code> of dynamic library to be linked. Always used for runtime and used for linking if <code>interface_library</code> is not passed. - </td> - </tr> - <tr> - <td id="create_library_to_link.interface_library"> - <code>interface_library</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - <code>File</code> of interface library to be linked. - </td> - </tr> - <tr> - <td id="create_library_to_link.pic_objects"> - <code>pic_objects</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>unbound</code><br/> - Experimental, do not use - </td> - </tr> - <tr> - <td id="create_library_to_link.objects"> - <code>objects</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>unbound</code><br/> - Experimental, do not use - </td> - </tr> - <tr> - <td id="create_library_to_link.alwayslink"> - <code>alwayslink</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether to link the static library/objects in the --whole_archive block. - </td> - </tr> - <tr> - <td id="create_library_to_link.dynamic_library_symlink_path"> - <code>dynamic_library_symlink_path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Override the default path of the dynamic library link in the solib directory. Empty string to use the default. - </td> - </tr> - <tr> - <td id="create_library_to_link.interface_library_symlink_path"> - <code>interface_library_symlink_path</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>''</code><br/> - Override the default path of the interface library link in the solib directory. Empty string to use the default. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_link_variables">create_link_variables</h2> - <p><pre class="rule-signature">Variables cc_common.create_link_variables(*, cc_toolchain, feature_configuration, library_search_directories=[], runtime_library_search_directories=[], user_link_flags=[], output_file=None, param_file=None, is_using_linker=True, is_linking_dynamic_library=False, must_keep_debug=True, use_test_only_flags=False, is_static_linking_mode=True)</pre></p> - - Returns link variables used for linking actions. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_link_variables.cc_toolchain"> - <code>cc_toolchain</code> - </td> - <td> - Info; - required<br/> - cc_toolchain for which we are creating build variables. - </td> - </tr> - <tr> - <td id="create_link_variables.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - Feature configuration to be queried. - </td> - </tr> - <tr> - <td id="create_link_variables.library_search_directories"> - <code>library_search_directories</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>[]</code><br/> - Depset of directories where linker will look for libraries at link time. - </td> - </tr> - <tr> - <td id="create_link_variables.runtime_library_search_directories"> - <code>runtime_library_search_directories</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>[]</code><br/> - Depset of directories where loader will look for libraries at runtime. - </td> - </tr> - <tr> - <td id="create_link_variables.user_link_flags"> - <code>user_link_flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of additional link flags (linkopts). - </td> - </tr> - <tr> - <td id="create_link_variables.output_file"> - <code>output_file</code> - </td> - <td> - default is <code>None</code><br/> - Optional output file path. - </td> - </tr> - <tr> - <td id="create_link_variables.param_file"> - <code>param_file</code> - </td> - <td> - default is <code>None</code><br/> - Optional param file path. - </td> - </tr> - <tr> - <td id="create_link_variables.is_using_linker"> - <code>is_using_linker</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True when using linker, False when archiver. Caller is responsible for keeping this in sync with action name used (is_using_linker = True for linking executable or dynamic library, is_using_linker = False for archiving static library). - </td> - </tr> - <tr> - <td id="create_link_variables.is_linking_dynamic_library"> - <code>is_linking_dynamic_library</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - True when creating dynamic library, False when executable or static library. Caller is responsible for keeping this in sync with action name used. This field will be removed once b/65151735 is fixed. - </td> - </tr> - <tr> - <td id="create_link_variables.must_keep_debug"> - <code>must_keep_debug</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - When set to False, bazel will expose 'strip_debug_symbols' variable, which is usually used to use the linker to strip debug symbols from the output file. - </td> - </tr> - <tr> - <td id="create_link_variables.use_test_only_flags"> - <code>use_test_only_flags</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - When set to true, 'is_cc_test' variable will be set. - </td> - </tr> - <tr> - <td id="create_link_variables.is_static_linking_mode"> - <code>is_static_linking_mode</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - Unused. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_linker_input">create_linker_input</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/LinkerInput.html">LinkerInput</a> cc_common.create_linker_input(*, owner, libraries=None, user_link_flags=None, additional_inputs=None)</pre></p> - - Creates a <code>LinkerInput</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_linker_input.owner"> - <code>owner</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; - required<br/> - The label of the target that produced all files used in this input. - </td> - </tr> - <tr> - <td id="create_linker_input.libraries"> - <code>libraries</code> - </td> - <td> - <code>None</code>; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>None</code><br/> - List of <code>LibraryToLink</code>. - </td> - </tr> - <tr> - <td id="create_linker_input.user_link_flags"> - <code>user_link_flags</code> - </td> - <td> - <code>None</code>; or <a class="anchor" href="../builtins/depset.html">depset</a> of <a class="anchor" href="../core/string.html">string</a>s; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>None</code><br/> - User link flags passed as strings. Accepts either [String], [[String]] or depset(String). The latter is discouraged as it's only kept for compatibility purposes, the depset is flattened. If you want to propagate user_link_flags via unflattened depsets() wrap them in a LinkerInput so that they are not flattened till the end. - </td> - </tr> - <tr> - <td id="create_linker_input.additional_inputs"> - <code>additional_inputs</code> - </td> - <td> - <code>None</code>; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>None</code><br/> - For additional inputs to the linking action, e.g.: linking scripts. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_linking_context">create_linking_context</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/LinkingContext.html">LinkingContext</a> cc_common.create_linking_context(*, linker_inputs)</pre></p> - - Creates a <code>LinkingContext</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_linking_context.linker_inputs"> - <code>linker_inputs</code> - </td> - <td> - <a class="anchor" href="../builtins/depset.html">depset</a>; - required<br/> - Depset of <code>LinkerInput</code>. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_linking_context_from_compilation_outputs">create_linking_context_from_compilation_outputs</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> cc_common.create_linking_context_from_compilation_outputs(*, actions, name, feature_configuration, cc_toolchain, language='c++', disallow_static_libraries=False, disallow_dynamic_library=False, compilation_outputs, linking_contexts=[], user_link_flags=[], alwayslink=False, additional_inputs=[], variables_extension=unbound)</pre></p> - - Should be used for creating library rules that can propagate information downstream in order to be linked later by a top level rule that does transitive linking to create an executable or a dynamic library. Returns tuple of (<code>CcLinkingContext</code>, <code>CcLinkingOutputs</code>). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_linking_context_from_compilation_outputs.actions"> - <code>actions</code> - </td> - <td> - <a class="anchor" href="../builtins/actions.html">actions</a>; - required<br/> - <code>actions</code> object. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - This is used for naming the output artifacts of actions created by this method. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - <code>feature_configuration</code> to be queried. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.cc_toolchain"> - <code>cc_toolchain</code> - </td> - <td> - Info; - required<br/> - <code>CcToolchainInfo</code> provider to be used. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.language"> - <code>language</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'c++'</code><br/> - Only C++ supported for now. Do not use this parameter. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.disallow_static_libraries"> - <code>disallow_static_libraries</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether static libraries should be created. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.disallow_dynamic_library"> - <code>disallow_dynamic_library</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether a dynamic library should be created. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.compilation_outputs"> - <code>compilation_outputs</code> - </td> - <td> - <a class="anchor" href="../builtins/CcCompilationOutputs.html">CcCompilationOutputs</a>; - required<br/> - Compilation outputs containing object files to link. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.linking_contexts"> - <code>linking_contexts</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Libraries from dependencies. These libraries will be linked into the output artifact of the link() call, be it a binary or a library. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.user_link_flags"> - <code>user_link_flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Additional list of linking options. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.alwayslink"> - <code>alwayslink</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether this library should always be linked. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.additional_inputs"> - <code>additional_inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - For additional inputs to the linking action, e.g.: linking scripts. - </td> - </tr> - <tr> - <td id="create_linking_context_from_compilation_outputs.variables_extension"> - <code>variables_extension</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>unbound</code><br/> - Additional variables to pass to the toolchain configuration when creating link command line. - </td> - </tr> - </tbody> - </table> - - <h2 id="create_lto_compilation_context">create_lto_compilation_context</h2> - <p><pre class="rule-signature">LtoCompilationContext cc_common.create_lto_compilation_context(*, objects={})</pre></p> - - Create LTO compilation context - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="create_lto_compilation_context.objects"> - <code>objects</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - map of full object to index object - </td> - </tr> - </tbody> - </table> - - <h2 id="do_not_use_tools_cpp_compiler_present">do_not_use_tools_cpp_compiler_present</h2> - <p><pre class="rule-signature"><code>None</code> cc_common.do_not_use_tools_cpp_compiler_present</pre></p> - - Do not use this field, its only purpose is to help with migration from config_setting.values{'compiler') to config_settings.flag_values{'@bazel_tools//tools/cpp:compiler'} - - <h2 id="get_environment_variables">get_environment_variables</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/dict.html">dict</a> cc_common.get_environment_variables(*, feature_configuration, action_name, variables)</pre></p> - - Returns environment variables to be set for given action. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="get_environment_variables.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - Feature configuration to be queried. - </td> - </tr> - <tr> - <td id="get_environment_variables.action_name"> - <code>action_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl) - </td> - </tr> - <tr> - <td id="get_environment_variables.variables"> - <code>variables</code> - </td> - <td> - Variables; - required<br/> - Build variables to be used for template expansion. - </td> - </tr> - </tbody> - </table> - - <h2 id="get_execution_requirements">get_execution_requirements</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> cc_common.get_execution_requirements(*, feature_configuration, action_name)</pre></p> - - Returns execution requirements for given action. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="get_execution_requirements.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - Feature configuration to be queried. - </td> - </tr> - <tr> - <td id="get_execution_requirements.action_name"> - <code>action_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl) - </td> - </tr> - </tbody> - </table> - - <h2 id="get_memory_inefficient_command_line">get_memory_inefficient_command_line</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> cc_common.get_memory_inefficient_command_line(*, feature_configuration, action_name, variables)</pre></p> - - Returns flattened command line flags for given action, using given variables for expansion. Flattens nested sets and ideally should not be used, or at least should not outlive analysis. Work on memory efficient function returning Args is ongoing. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="get_memory_inefficient_command_line.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - Feature configuration to be queried. - </td> - </tr> - <tr> - <td id="get_memory_inefficient_command_line.action_name"> - <code>action_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl) - </td> - </tr> - <tr> - <td id="get_memory_inefficient_command_line.variables"> - <code>variables</code> - </td> - <td> - Variables; - required<br/> - Build variables to be used for template expansions. - </td> - </tr> - </tbody> - </table> - - <h2 id="get_tool_for_action">get_tool_for_action</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> cc_common.get_tool_for_action(*, feature_configuration, action_name)</pre></p> - - Returns tool path for given action. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="get_tool_for_action.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - Feature configuration to be queried. - </td> - </tr> - <tr> - <td id="get_tool_for_action.action_name"> - <code>action_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl) - </td> - </tr> - </tbody> - </table> - - <h2 id="is_enabled">is_enabled</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> cc_common.is_enabled(*, feature_configuration, feature_name)</pre></p> - - Returns True if given feature is enabled in the feature configuration. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="is_enabled.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - Feature configuration to be queried. - </td> - </tr> - <tr> - <td id="is_enabled.feature_name"> - <code>feature_name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of the feature. - </td> - </tr> - </tbody> - </table> - - <h2 id="link">link</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/CcLinkingOutputs.html">CcLinkingOutputs</a> cc_common.link(*, actions, name, feature_configuration, cc_toolchain, language='c++', output_type='executable', link_deps_statically=True, compilation_outputs=None, linking_contexts=[], user_link_flags=[], stamp=0, additional_inputs=[], additional_outputs=[], variables_extension={})</pre></p> - - Should be used for C++ transitive linking. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="link.actions"> - <code>actions</code> - </td> - <td> - <a class="anchor" href="../builtins/actions.html">actions</a>; - required<br/> - <code>actions</code> object. - </td> - </tr> - <tr> - <td id="link.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - This is used for naming the output artifacts of actions created by this method. - </td> - </tr> - <tr> - <td id="link.feature_configuration"> - <code>feature_configuration</code> - </td> - <td> - <a class="anchor" href="../builtins/FeatureConfiguration.html">FeatureConfiguration</a>; - required<br/> - <code>feature_configuration</code> to be queried. - </td> - </tr> - <tr> - <td id="link.cc_toolchain"> - <code>cc_toolchain</code> - </td> - <td> - Info; - required<br/> - <code>CcToolchainInfo</code> provider to be used. - </td> - </tr> - <tr> - <td id="link.language"> - <code>language</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'c++'</code><br/> - Only C++ supported for now. Do not use this parameter. - </td> - </tr> - <tr> - <td id="link.output_type"> - <code>output_type</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'executable'</code><br/> - Can be either 'executable' or 'dynamic_library'. - </td> - </tr> - <tr> - <td id="link.link_deps_statically"> - <code>link_deps_statically</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - True to link dependencies statically, False dynamically. - </td> - </tr> - <tr> - <td id="link.compilation_outputs"> - <code>compilation_outputs</code> - </td> - <td> - <a class="anchor" href="../builtins/CcCompilationOutputs.html">CcCompilationOutputs</a>; or <code>None</code>; - default is <code>None</code><br/> - Compilation outputs containing object files to link. - </td> - </tr> - <tr> - <td id="link.linking_contexts"> - <code>linking_contexts</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Linking contexts from dependencies to be linked into the linking context generated by this rule. - </td> - </tr> - <tr> - <td id="link.user_link_flags"> - <code>user_link_flags</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - Additional list of linker options. - </td> - </tr> - <tr> - <td id="link.stamp"> - <code>stamp</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>0</code><br/> - Whether to include build information in the linked executable, if output_type is 'executable'. If 1, build information is always included. If 0 (the default build information is always excluded. If -1, uses the default behavior, which may be overridden by the --[no]stamp flag. This should be unset (or set to 0) when generating the executable output for test rules. - </td> - </tr> - <tr> - <td id="link.additional_inputs"> - <code>additional_inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <a class="anchor" href="../builtins/depset.html">depset</a>; - default is <code>[]</code><br/> - For additional inputs to the linking action, e.g.: linking scripts. - </td> - </tr> - <tr> - <td id="link.additional_outputs"> - <code>additional_outputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - For additional outputs to the linking action, e.g.: map files. - </td> - </tr> - <tr> - <td id="link.variables_extension"> - <code>variables_extension</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - Additional variables to pass to the toolchain configuration when create link command line. - </td> - </tr> - </tbody> - </table> - - <h2 id="merge_cc_infos">merge_cc_infos</h2> - <p><pre class="rule-signature">unknown cc_common.merge_cc_infos(*, direct_cc_infos=[], cc_infos=[])</pre></p> - - Merges multiple <code>CcInfo</code>s into one. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="merge_cc_infos.direct_cc_infos"> - <code>direct_cc_infos</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of <code>CcInfo</code>s to be merged, whose headers will be exported by the direct fields in the returned provider. - </td> - </tr> - <tr> - <td id="merge_cc_infos.cc_infos"> - <code>cc_infos</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of <code>CcInfo</code>s to be merged, whose headers will not be exported by the direct fields in the returned provider. - </td> - </tr> - </tbody> - </table> - - <h2 id="merge_compilation_contexts">merge_compilation_contexts</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/CompilationContext.html">CompilationContext</a> cc_common.merge_compilation_contexts(*, compilation_contexts=[])</pre></p> - - Merges multiple <code>CompilationContexts</code>s into one. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="merge_compilation_contexts.compilation_contexts"> - <code>compilation_contexts</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - List of <code>CompilationContexts</code>s to be merged. The headers of each context will be exported by the direct fields in the returned provider. - </td> - </tr> - </tbody> - </table> - - <h2 id="merge_compilation_outputs">merge_compilation_outputs</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/CcCompilationOutputs.html">CcCompilationOutputs</a> cc_common.merge_compilation_outputs(*, compilation_outputs=[])</pre></p> - - Merge compilation outputs. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="merge_compilation_outputs.compilation_outputs"> - <code>compilation_outputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [action_is_enabled](#action_is_enabled) +- [CcToolchainInfo](#CcToolchainInfo) +- [compile](#compile) +- [configure_features](#configure_features) +- [create_cc_toolchain_config_info](#create_cc_toolchain_config_info) +- [create_compilation_context](#create_compilation_context) +- [create_compilation_outputs](#create_compilation_outputs) +- [create_compile_variables](#create_compile_variables) +- [create_library_to_link](#create_library_to_link) +- [create_link_variables](#create_link_variables) +- [create_linker_input](#create_linker_input) +- [create_linking_context](#create_linking_context) +- [create_linking_context_from_compilation_outputs](#create_linking_context_from_compilation_outputs) +- [create_lto_compilation_context](#create_lto_compilation_context) +- [do_not_use_tools_cpp_compiler_present](#do_not_use_tools_cpp_compiler_present) +- [get_environment_variables](#get_environment_variables) +- [get_execution_requirements](#get_execution_requirements) +- [get_memory_inefficient_command_line](#get_memory_inefficient_command_line) +- [get_tool_for_action](#get_tool_for_action) +- [is_enabled](#is_enabled) +- [link](#link) +- [merge_cc_infos](#merge_cc_infos) +- [merge_compilation_contexts](#merge_compilation_contexts) +- [merge_compilation_outputs](#merge_compilation_outputs) + +## action_is_enabled + +``` rule-signature +bool cc_common.action_is_enabled(*, feature_configuration, action_name) +``` + +Returns True if given action_config is enabled in the feature configuration. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="action_is_enabled.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +Feature configuration to be queried.</td> +</tr> +<tr> +<td id="action_is_enabled.action_name"><code>action_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of the action_config.</td> +</tr> +</tbody> +</table> + +## CcToolchainInfo + +``` rule-signature +Provider cc_common.CcToolchainInfo +``` + +The key used to retrieve the provider that contains information about the C++ toolchain being used + +## compile + +``` rule-signature +tuple cc_common.compile(*, actions, feature_configuration, cc_toolchain, srcs=[], public_hdrs=[], private_hdrs=[], includes=[], quote_includes=[], system_includes=[], framework_includes=[], defines=[], local_defines=[], include_prefix='', strip_include_prefix='', user_compile_flags=[], conly_flags=[], cxx_flags=[], compilation_contexts=[], name, disallow_pic_outputs=False, disallow_nopic_outputs=False, additional_inputs=[], module_interfaces=unbound) +``` + +Should be used for C++ compilation. Returns tuple of (`CompilationContext`, `CcCompilationOutputs`). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="compile.actions"><code>actions</code></td> +<td><a href="../builtins/actions.html" class="anchor">actions</a>; +required<br /> +<code>actions</code> object.</td> +</tr> +<tr> +<td id="compile.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +<code>feature_configuration</code> to be queried.</td> +</tr> +<tr> +<td id="compile.cc_toolchain"><code>cc_toolchain</code></td> +<td>Info; +required<br /> +<code>CcToolchainInfo</code> provider to be used.</td> +</tr> +<tr> +<td id="compile.srcs"><code>srcs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +The list of source files to be compiled.</td> +</tr> +<tr> +<td id="compile.public_hdrs"><code>public_hdrs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of headers needed for compilation of srcs and may be included by dependent rules transitively.</td> +</tr> +<tr> +<td id="compile.private_hdrs"><code>private_hdrs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of headers needed for compilation of srcs and NOT to be included by dependent rules.</td> +</tr> +<tr> +<td id="compile.includes"><code>includes</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>[]</code><br /> +Search paths for header files referenced both by angle bracket and quotes. Usually passed with -I. Propagated to dependents transitively.</td> +</tr> +<tr> +<td id="compile.quote_includes"><code>quote_includes</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Search paths for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. Propagated to dependents transitively.</td> +</tr> +<tr> +<td id="compile.system_includes"><code>system_includes</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Search paths for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. Propagated to dependents transitively.</td> +</tr> +<tr> +<td id="compile.framework_includes"><code>framework_includes</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Search paths for header files from Apple frameworks. They can be either relative to the exec root or absolute. Usually passed with -F. Propagated to dependents transitively.</td> +</tr> +<tr> +<td id="compile.defines"><code>defines</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Set of defines needed to compile this target. Each define is a string. Propagated to dependents transitively.</td> +</tr> +<tr> +<td id="compile.local_defines"><code>local_defines</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Set of defines needed to compile this target. Each define is a string. Not propagated to dependents transitively.</td> +</tr> +<tr> +<td id="compile.include_prefix"><code>include_prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the strip_include_prefix attribute is removed before this prefix is added.</td> +</tr> +<tr> +<td id="compile.strip_include_prefix"><code>strip_include_prefix</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the include_prefix attribute is added after this prefix is stripped.</td> +</tr> +<tr> +<td id="compile.user_compile_flags"><code>user_compile_flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Additional list of compilation options.</td> +</tr> +<tr> +<td id="compile.conly_flags"><code>conly_flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Additional list of compilation options for C compiles.</td> +</tr> +<tr> +<td id="compile.cxx_flags"><code>cxx_flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Additional list of compilation options for C++ compiles.</td> +</tr> +<tr> +<td id="compile.compilation_contexts"><code>compilation_contexts</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Headers from dependencies used for compilation.</td> +</tr> +<tr> +<td id="compile.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +This is used for naming the output artifacts of actions created by this method. See also the `main_output` arg.</td> +</tr> +<tr> +<td id="compile.disallow_pic_outputs"><code>disallow_pic_outputs</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether PIC outputs should be created.</td> +</tr> +<tr> +<td id="compile.disallow_nopic_outputs"><code>disallow_nopic_outputs</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether NOPIC outputs should be created.</td> +</tr> +<tr> +<td id="compile.additional_inputs"><code>additional_inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of additional files needed for compilation of srcs</td> +</tr> +<tr> +<td id="compile.module_interfaces"><code>module_interfaces</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>unbound</code><br /> +The list of module interfaces source files to be compiled. Note: this is an experimental feature, only enabled with --experimental_cpp_modules</td> +</tr> +</tbody> +</table> + +## configure_features + +``` rule-signature +FeatureConfiguration cc_common.configure_features(*, ctx, cc_toolchain, language=None, requested_features=[], unsupported_features=[]) +``` + +Creates a feature_configuration instance. Requires the cpp configuration fragment. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="configure_features.ctx"><code>ctx</code></td> +<td><a href="../builtins/ctx.html" class="anchor">ctx</a>; +required<br /> +The rule context.</td> +</tr> +<tr> +<td id="configure_features.cc_toolchain"><code>cc_toolchain</code></td> +<td>Info; +required<br /> +cc_toolchain for which we configure features.</td> +</tr> +<tr> +<td id="configure_features.language"><code>language</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The language to configure for: either c++ or objc (default c++)</td> +</tr> +<tr> +<td id="configure_features.requested_features"><code>requested_features</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of features to be enabled.</td> +</tr> +<tr> +<td id="configure_features.unsupported_features"><code>unsupported_features</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of features that are unsupported by the current rule.</td> +</tr> +</tbody> +</table> + +## create_cc_toolchain_config_info + +``` rule-signature +None cc_common.create_cc_toolchain_config_info(*, ctx, features=[], action_configs=[], artifact_name_patterns=[], cxx_builtin_include_directories=[], toolchain_identifier, host_system_name=None, target_system_name=None, target_cpu=None, target_libc=None, compiler, abi_version=None, abi_libc_version=None, tool_paths=[], make_variables=[], builtin_sysroot=None) +``` + +Creates a `CcToolchainConfigInfo` provider + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_cc_toolchain_config_info.ctx"><code>ctx</code></td> +<td><a href="../builtins/ctx.html" class="anchor">ctx</a>; +required<br /> +The rule context.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.features"><code>features</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Contains all flag specifications for one feature. +<p>Arguments:</p> +<p><code>name</code>: The feature's name. It is possible to introduce a feature without a change to Bazel by adding a 'feature' section to the toolchain and adding the corresponding string as feature in the <code>BUILD</code> file.</p> +<p><code>enabled</code>: If 'True', this feature is enabled unless a rule type explicitly marks it as unsupported.</p> +<p><code>flag_sets</code>: A FlagSet list. If the given feature is enabled, the flag sets will be applied for the actions are specified for.</p> +<p><code>env_sets</code>: an EnvSet list. If the given feature is enabled, the env sets will be applied for the actions they are specified for.</p> +<p><code>requires</code>: A list of feature sets defining when this feature is supported by the toolchain. The feature is supported if any of the feature sets fully apply, that is, when all features of a feature set are enabled. If <code>requires</code> is omitted, the feature is supported independently of which other features are enabled. Use this for example to filter flags depending on the build mode enabled (opt / fastbuild / dbg).</p> +<p><code>implies</code>: A string list of features or action configs that are automatically enabled when this feature is enabled. If any of the implied features or action configs cannot be enabled, this feature will (silently) not be enabled either.</p> +<p><code>provides</code>: A list of names this feature conflicts with.</p> +A feature cannot be enabled if:- <code>provides</code> contains the name of a different feature or action config that we want to enable.- <code>provides</code> contains the same value as a 'provides' in a different feature or action config that we want to enable. Use this in order to ensure that incompatible features cannot be accidentally activated at the same time, leading to hard to diagnose compiler errors.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.action_configs"><code>action_configs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +An action config corresponds to a Bazel action, and allows selection of a tool based on activated features. Action config activation occurs by the same semantics as features: a feature can 'require' or 'imply' an action config in the same way that it would another feature. +<p>Arguments:</p> +<p><code>action_name</code>: The name of the Bazel action that this config applies to, e.g. 'c-compile' or 'c-module-compile'.</p> +<p><code>enabled</code>: If 'True', this action is enabled unless a rule type explicitly marks it as unsupported.</p> +<p><code>tools</code>: The tool applied to the action will be the first tool with a feature set that matches the feature configuration. An error will be thrown if no tool matches a provided feature configuration - for that reason, it's a good idea to provide a default tool with an empty feature set.</p> +<p><code>flag_sets</code>: If the given action config is enabled, the flag sets will be applied to the corresponding action.</p> +<p><code>implies</code>: A list of features or action configs that are automatically enabled when this action config is enabled. If any of the implied features or action configs cannot be enabled, this action config will (silently) not be enabled either.</p></td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.artifact_name_patterns"><code>artifact_name_patterns</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +The name for an artifact of a given category of input or output artifacts to an action. +<p>Arguments:</p> +<p><code>category_name</code>: The category of artifacts that this selection applies to. This field is compared against a list of categories defined in Bazel. Example categories include "linked_output" or the artifact for this selection. Together with the extension it is used to create an artifact name based on the target name.</p> +<p><code>extension</code>: The extension for creating the artifact for this selection. Together with the prefix it is used to create an artifact name based on the target name.</p></td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.cxx_builtin_include_directories"><code>cxx_builtin_include_directories</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> + <p>Built-in include directories for C++ compilation. These should be the exact paths used by the compiler, and are generally relative to the exec root.</p> +<p>The paths used by the compiler can be determined by 'gcc -E -xc++ - -v'.</p> +<p>We currently use the C++ paths also for C compilation, which is safe as long as there are no name clashes between C++ and C header files.</p> +<p>Relative paths are resolved relative to the configuration file directory.</p> +<p>If the compiler has --sysroot support, then these paths should use %sysroot% rather than the include path, and specify the sysroot attribute in order to give blaze the information necessary to make the correct replacements.</p></td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.toolchain_identifier"><code>toolchain_identifier</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> + <p>The unique identifier of the toolchain within the crosstool release. It must be possible to use this as a directory name in a path.</p> +<p>It has to match the following regex: [a-zA-Z_][\.\- \w]*</p></td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.host_system_name"><code>host_system_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Ignored.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.target_system_name"><code>target_system_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Deprecated. The GNU System Name. The string is exposed to CcToolchainInfo.target_gnu_system_name.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.target_cpu"><code>target_cpu</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Deprecated: Use cpu based constraints instead. If the string is "k8", `target_cpu` will be omitted from the filename of raw FDO profile data.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.target_libc"><code>target_libc</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Deprecated: Use OS based constraints instead. The libc version string (e.g. "glibc-2.2.2"). If the string is "macosx", platform is assumed to be MacOS. Otherwise, Linux. The string is exposed to CcToolchainInfo.libc.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.compiler"><code>compiler</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The compiler string (e.g. "gcc"). The current toolchain's compiler is exposed to `@bazel_tools//tools/cpp:compiler (compiler_flag)` as a flag value. Targets that require compiler-specific flags can use the config_settings in https://github.com/bazelbuild/rules_cc/blob/main/cc/compiler/BUILD in select() statements or create custom config_setting if the existing settings don't suffice.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.abi_version"><code>abi_version</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The abi in use, which is a gcc version. E.g.: "gcc-3.4". The string is set to C++ toolchain variable ABI.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.abi_libc_version"><code>abi_libc_version</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The glibc version used by the abi we're using. The string is set to C++ toolchain variable ABI_LIBC_VERSION.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.tool_paths"><code>tool_paths</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Tool locations. +<p>Arguments:</p> +<p><code>name</code>: Name of the tool.</p> +<p><code>path</code>: Location of the tool; Can be absolute path (in case of non hermetic toolchain), or path relative to the cc_toolchain's package.</p></td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.make_variables"><code>make_variables</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +A make variable that is made accessible to rules.</td> +</tr> +<tr> +<td id="create_cc_toolchain_config_info.builtin_sysroot"><code>builtin_sysroot</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The built-in sysroot. If this attribute is not present, Bazel does not allow using a different sysroot, i.e. through the --grte_top option.</td> +</tr> +</tbody> +</table> + +## create_compilation_context + +``` rule-signature +CompilationContext cc_common.create_compilation_context(*, headers=unbound, system_includes=unbound, includes=unbound, quote_includes=unbound, framework_includes=unbound, defines=unbound, local_defines=unbound) +``` + +Creates a `CompilationContext`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_compilation_context.headers"><code>headers</code></td> +<td>default is <code>unbound</code><br /> +Set of headers needed to compile this target</td> +</tr> +<tr> +<td id="create_compilation_context.system_includes"><code>system_includes</code></td> +<td>default is <code>unbound</code><br /> +Set of search paths for header files referenced by angle brackets, i.e. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem</td> +</tr> +<tr> +<td id="create_compilation_context.includes"><code>includes</code></td> +<td>default is <code>unbound</code><br /> +Set of search paths for header files referenced both by angle bracket and quotes.Usually passed with -I</td> +</tr> +<tr> +<td id="create_compilation_context.quote_includes"><code>quote_includes</code></td> +<td>default is <code>unbound</code><br /> +Set of search paths for header files referenced by quotes, i.e. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote</td> +</tr> +<tr> +<td id="create_compilation_context.framework_includes"><code>framework_includes</code></td> +<td>default is <code>unbound</code><br /> +Set of framework search paths for header files (Apple platform only)</td> +</tr> +<tr> +<td id="create_compilation_context.defines"><code>defines</code></td> +<td>default is <code>unbound</code><br /> +Set of defines needed to compile this target. Each define is a string. Propagated transitively to dependents.</td> +</tr> +<tr> +<td id="create_compilation_context.local_defines"><code>local_defines</code></td> +<td>default is <code>unbound</code><br /> +Set of defines needed to compile this target. Each define is a string. Not propagated transitively to dependents.</td> +</tr> +</tbody> +</table> + +## create_compilation_outputs + +``` rule-signature +CcCompilationOutputs cc_common.create_compilation_outputs(*, objects=None, pic_objects=None) +``` + +Create compilation outputs object. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_compilation_outputs.objects"><code>objects</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +List of object files.</td> +</tr> +<tr> +<td id="create_compilation_outputs.pic_objects"><code>pic_objects</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +List of pic object files.</td> +</tr> +</tbody> +</table> + +## create_compile_variables + +``` rule-signature +Variables cc_common.create_compile_variables(*, cc_toolchain, feature_configuration, source_file=None, output_file=None, user_compile_flags=None, include_directories=None, quote_include_directories=None, system_include_directories=None, framework_include_directories=None, preprocessor_defines=None, thinlto_index=None, thinlto_input_bitcode_file=None, thinlto_output_object_file=None, use_pic=False, add_legacy_cxx_options=False, variables_extension=unbound) +``` + +Returns variables used for compilation actions. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_compile_variables.cc_toolchain"><code>cc_toolchain</code></td> +<td>Info; +required<br /> +cc_toolchain for which we are creating build variables.</td> +</tr> +<tr> +<td id="create_compile_variables.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +Feature configuration to be queried.</td> +</tr> +<tr> +<td id="create_compile_variables.source_file"><code>source_file</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Optional source file path for the compilation. Please prefer passing source_file here over appending it to the end of the command line generated from cc_common.get_memory_inefficient_command_line, as then it's in the power of the toolchain author to properly specify and position compiler flags.</td> +</tr> +<tr> +<td id="create_compile_variables.output_file"><code>output_file</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Optional output file path of the compilation. Please prefer passing output_file here over appending it to the end of the command line generated from cc_common.get_memory_inefficient_command_line, as then it's in the power of the toolchain author to properly specify and position compiler flags.</td> +</tr> +<tr> +<td id="create_compile_variables.user_compile_flags"><code>user_compile_flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +List of additional compilation flags (copts).</td> +</tr> +<tr> +<td id="create_compile_variables.include_directories"><code>include_directories</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +Depset of include directories.</td> +</tr> +<tr> +<td id="create_compile_variables.quote_include_directories"><code>quote_include_directories</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +Depset of quote include directories.</td> +</tr> +<tr> +<td id="create_compile_variables.system_include_directories"><code>system_include_directories</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +Depset of system include directories.</td> +</tr> +<tr> +<td id="create_compile_variables.framework_include_directories"><code>framework_include_directories</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +Depset of framework include directories.</td> +</tr> +<tr> +<td id="create_compile_variables.preprocessor_defines"><code>preprocessor_defines</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; +default is <code>None</code><br /> +Depset of preprocessor defines.</td> +</tr> +<tr> +<td id="create_compile_variables.thinlto_index"><code>thinlto_index</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +LTO index file path.</td> +</tr> +<tr> +<td id="create_compile_variables.thinlto_input_bitcode_file"><code>thinlto_input_bitcode_file</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Bitcode file that is input to LTO backend.</td> +</tr> +<tr> +<td id="create_compile_variables.thinlto_output_object_file"><code>thinlto_output_object_file</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +Object file that is output by LTO backend.</td> +</tr> +<tr> +<td id="create_compile_variables.use_pic"><code>use_pic</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +When true the compilation will generate position independent code.</td> +</tr> +<tr> +<td id="create_compile_variables.add_legacy_cxx_options"><code>add_legacy_cxx_options</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Unused.</td> +</tr> +<tr> +<td id="create_compile_variables.variables_extension"><code>variables_extension</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>unbound</code><br /> +A dictionary of additional variables used by compile actions.</td> +</tr> +</tbody> +</table> + +## create_library_to_link + +``` rule-signature +LibraryToLink cc_common.create_library_to_link(*, actions, feature_configuration=None, cc_toolchain=None, static_library=None, pic_static_library=None, dynamic_library=None, interface_library=None, pic_objects=unbound, objects=unbound, alwayslink=False, dynamic_library_symlink_path='', interface_library_symlink_path='') +``` + +Creates `LibraryToLink` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_library_to_link.actions"><code>actions</code></td> +<td>required<br /> +<code>actions</code> object.</td> +</tr> +<tr> +<td id="create_library_to_link.feature_configuration"><code>feature_configuration</code></td> +<td>default is <code>None</code><br /> +<code>feature_configuration</code> to be queried.</td> +</tr> +<tr> +<td id="create_library_to_link.cc_toolchain"><code>cc_toolchain</code></td> +<td>default is <code>None</code><br /> +<code>CcToolchainInfo</code> provider to be used.</td> +</tr> +<tr> +<td id="create_library_to_link.static_library"><code>static_library</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +<code>File</code> of static library to be linked.</td> +</tr> +<tr> +<td id="create_library_to_link.pic_static_library"><code>pic_static_library</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +<code>File</code> of pic static library to be linked.</td> +</tr> +<tr> +<td id="create_library_to_link.dynamic_library"><code>dynamic_library</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +<code>File</code> of dynamic library to be linked. Always used for runtime and used for linking if <code>interface_library</code> is not passed.</td> +</tr> +<tr> +<td id="create_library_to_link.interface_library"><code>interface_library</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +<code>File</code> of interface library to be linked.</td> +</tr> +<tr> +<td id="create_library_to_link.pic_objects"><code>pic_objects</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>unbound</code><br /> +Experimental, do not use</td> +</tr> +<tr> +<td id="create_library_to_link.objects"><code>objects</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>unbound</code><br /> +Experimental, do not use</td> +</tr> +<tr> +<td id="create_library_to_link.alwayslink"><code>alwayslink</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether to link the static library/objects in the --whole_archive block.</td> +</tr> +<tr> +<td id="create_library_to_link.dynamic_library_symlink_path"><code>dynamic_library_symlink_path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Override the default path of the dynamic library link in the solib directory. Empty string to use the default.</td> +</tr> +<tr> +<td id="create_library_to_link.interface_library_symlink_path"><code>interface_library_symlink_path</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>''</code><br /> +Override the default path of the interface library link in the solib directory. Empty string to use the default.</td> +</tr> +</tbody> +</table> + +## create_link_variables + +``` rule-signature +Variables cc_common.create_link_variables(*, cc_toolchain, feature_configuration, library_search_directories=[], runtime_library_search_directories=[], user_link_flags=[], output_file=None, param_file=None, is_using_linker=True, is_linking_dynamic_library=False, must_keep_debug=True, use_test_only_flags=False, is_static_linking_mode=True) +``` + +Returns link variables used for linking actions. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_link_variables.cc_toolchain"><code>cc_toolchain</code></td> +<td>Info; +required<br /> +cc_toolchain for which we are creating build variables.</td> +</tr> +<tr> +<td id="create_link_variables.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +Feature configuration to be queried.</td> +</tr> +<tr> +<td id="create_link_variables.library_search_directories"><code>library_search_directories</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>[]</code><br /> +Depset of directories where linker will look for libraries at link time.</td> +</tr> +<tr> +<td id="create_link_variables.runtime_library_search_directories"><code>runtime_library_search_directories</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>[]</code><br /> +Depset of directories where loader will look for libraries at runtime.</td> +</tr> +<tr> +<td id="create_link_variables.user_link_flags"><code>user_link_flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of additional link flags (linkopts).</td> +</tr> +<tr> +<td id="create_link_variables.output_file"><code>output_file</code></td> +<td>default is <code>None</code><br /> +Optional output file path.</td> +</tr> +<tr> +<td id="create_link_variables.param_file"><code>param_file</code></td> +<td>default is <code>None</code><br /> +Optional param file path.</td> +</tr> +<tr> +<td id="create_link_variables.is_using_linker"><code>is_using_linker</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True when using linker, False when archiver. Caller is responsible for keeping this in sync with action name used (is_using_linker = True for linking executable or dynamic library, is_using_linker = False for archiving static library).</td> +</tr> +<tr> +<td id="create_link_variables.is_linking_dynamic_library"><code>is_linking_dynamic_library</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +True when creating dynamic library, False when executable or static library. Caller is responsible for keeping this in sync with action name used. This field will be removed once b/65151735 is fixed.</td> +</tr> +<tr> +<td id="create_link_variables.must_keep_debug"><code>must_keep_debug</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +When set to False, bazel will expose 'strip_debug_symbols' variable, which is usually used to use the linker to strip debug symbols from the output file.</td> +</tr> +<tr> +<td id="create_link_variables.use_test_only_flags"><code>use_test_only_flags</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +When set to true, 'is_cc_test' variable will be set.</td> +</tr> +<tr> +<td id="create_link_variables.is_static_linking_mode"><code>is_static_linking_mode</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +Unused.</td> +</tr> +</tbody> +</table> + +## create_linker_input + +``` rule-signature +LinkerInput cc_common.create_linker_input(*, owner, libraries=None, user_link_flags=None, additional_inputs=None) +``` + +Creates a `LinkerInput`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_linker_input.owner"><code>owner</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; +required<br /> +The label of the target that produced all files used in this input.</td> +</tr> +<tr> +<td id="create_linker_input.libraries"><code>libraries</code></td> +<td><code>None</code>; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>None</code><br /> +List of <code>LibraryToLink</code>.</td> +</tr> +<tr> +<td id="create_linker_input.user_link_flags"><code>user_link_flags</code></td> +<td><code>None</code>; or <a href="../builtins/depset.html" class="anchor">depset</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>None</code><br /> +User link flags passed as strings. Accepts either [String], [[String]] or depset(String). The latter is discouraged as it's only kept for compatibility purposes, the depset is flattened. If you want to propagate user_link_flags via unflattened depsets() wrap them in a LinkerInput so that they are not flattened till the end.</td> +</tr> +<tr> +<td id="create_linker_input.additional_inputs"><code>additional_inputs</code></td> +<td><code>None</code>; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>None</code><br /> +For additional inputs to the linking action, e.g.: linking scripts.</td> +</tr> +</tbody> +</table> + +## create_linking_context + +``` rule-signature +LinkingContext cc_common.create_linking_context(*, linker_inputs) +``` + +Creates a `LinkingContext`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_linking_context.linker_inputs"><code>linker_inputs</code></td> +<td><a href="../builtins/depset.html" class="anchor">depset</a>; +required<br /> +Depset of <code>LinkerInput</code>.</td> +</tr> +</tbody> +</table> + +## create_linking_context_from_compilation_outputs + +``` rule-signature +tuple cc_common.create_linking_context_from_compilation_outputs(*, actions, name, feature_configuration, cc_toolchain, language='c++', disallow_static_libraries=False, disallow_dynamic_library=False, compilation_outputs, linking_contexts=[], user_link_flags=[], alwayslink=False, additional_inputs=[], variables_extension=unbound) +``` + +Should be used for creating library rules that can propagate information downstream in order to be linked later by a top level rule that does transitive linking to create an executable or a dynamic library. Returns tuple of (`CcLinkingContext`, `CcLinkingOutputs`). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_linking_context_from_compilation_outputs.actions"><code>actions</code></td> +<td><a href="../builtins/actions.html" class="anchor">actions</a>; +required<br /> +<code>actions</code> object.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +This is used for naming the output artifacts of actions created by this method.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +<code>feature_configuration</code> to be queried.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.cc_toolchain"><code>cc_toolchain</code></td> +<td>Info; +required<br /> +<code>CcToolchainInfo</code> provider to be used.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.language"><code>language</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'c++'</code><br /> +Only C++ supported for now. Do not use this parameter.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.disallow_static_libraries"><code>disallow_static_libraries</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether static libraries should be created.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.disallow_dynamic_library"><code>disallow_dynamic_library</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether a dynamic library should be created.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.compilation_outputs"><code>compilation_outputs</code></td> +<td><a href="../builtins/CcCompilationOutputs.html" class="anchor">CcCompilationOutputs</a>; +required<br /> +Compilation outputs containing object files to link.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.linking_contexts"><code>linking_contexts</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Libraries from dependencies. These libraries will be linked into the output artifact of the link() call, be it a binary or a library.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.user_link_flags"><code>user_link_flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Additional list of linking options.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.alwayslink"><code>alwayslink</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether this library should always be linked.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.additional_inputs"><code>additional_inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +For additional inputs to the linking action, e.g.: linking scripts.</td> +</tr> +<tr> +<td id="create_linking_context_from_compilation_outputs.variables_extension"><code>variables_extension</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>unbound</code><br /> +Additional variables to pass to the toolchain configuration when creating link command line.</td> +</tr> +</tbody> +</table> + +## create_lto_compilation_context + +``` rule-signature +LtoCompilationContext cc_common.create_lto_compilation_context(*, objects={}) +``` + +Create LTO compilation context + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="create_lto_compilation_context.objects"><code>objects</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +map of full object to index object</td> +</tr> +</tbody> +</table> + +## do_not_use_tools_cpp_compiler_present + +``` rule-signature +None cc_common.do_not_use_tools_cpp_compiler_present +``` + +Do not use this field, its only purpose is to help with migration from config_setting.values{'compiler') to config_settings.flag_values{'@bazel_tools//tools/cpp:compiler'} + +## get_environment_variables + +``` rule-signature +dict cc_common.get_environment_variables(*, feature_configuration, action_name, variables) +``` + +Returns environment variables to be set for given action. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="get_environment_variables.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +Feature configuration to be queried.</td> +</tr> +<tr> +<td id="get_environment_variables.action_name"><code>action_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl)</td> +</tr> +<tr> +<td id="get_environment_variables.variables"><code>variables</code></td> +<td>Variables; +required<br /> +Build variables to be used for template expansion.</td> +</tr> +</tbody> +</table> + +## get_execution_requirements + +``` rule-signature +sequence cc_common.get_execution_requirements(*, feature_configuration, action_name) +``` + +Returns execution requirements for given action. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="get_execution_requirements.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +Feature configuration to be queried.</td> +</tr> +<tr> +<td id="get_execution_requirements.action_name"><code>action_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl)</td> +</tr> +</tbody> +</table> + +## get_memory_inefficient_command_line + +``` rule-signature +sequence cc_common.get_memory_inefficient_command_line(*, feature_configuration, action_name, variables) +``` + +Returns flattened command line flags for given action, using given variables for expansion. Flattens nested sets and ideally should not be used, or at least should not outlive analysis. Work on memory efficient function returning Args is ongoing. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="get_memory_inefficient_command_line.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +Feature configuration to be queried.</td> +</tr> +<tr> +<td id="get_memory_inefficient_command_line.action_name"><code>action_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl)</td> +</tr> +<tr> +<td id="get_memory_inefficient_command_line.variables"><code>variables</code></td> +<td>Variables; +required<br /> +Build variables to be used for template expansions.</td> +</tr> +</tbody> +</table> + +## get_tool_for_action + +``` rule-signature +string cc_common.get_tool_for_action(*, feature_configuration, action_name) +``` + +Returns tool path for given action. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="get_tool_for_action.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +Feature configuration to be queried.</td> +</tr> +<tr> +<td id="get_tool_for_action.action_name"><code>action_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl)</td> +</tr> +</tbody> +</table> + +## is_enabled + +``` rule-signature +bool cc_common.is_enabled(*, feature_configuration, feature_name) +``` + +Returns True if given feature is enabled in the feature configuration. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="is_enabled.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +Feature configuration to be queried.</td> +</tr> +<tr> +<td id="is_enabled.feature_name"><code>feature_name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of the feature.</td> +</tr> +</tbody> +</table> + +## link + +``` rule-signature +CcLinkingOutputs cc_common.link(*, actions, name, feature_configuration, cc_toolchain, language='c++', output_type='executable', link_deps_statically=True, compilation_outputs=None, linking_contexts=[], user_link_flags=[], stamp=0, additional_inputs=[], additional_outputs=[], variables_extension={}) +``` + +Should be used for C++ transitive linking. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="link.actions"><code>actions</code></td> +<td><a href="../builtins/actions.html" class="anchor">actions</a>; +required<br /> +<code>actions</code> object.</td> +</tr> +<tr> +<td id="link.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +This is used for naming the output artifacts of actions created by this method.</td> +</tr> +<tr> +<td id="link.feature_configuration"><code>feature_configuration</code></td> +<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; +required<br /> +<code>feature_configuration</code> to be queried.</td> +</tr> +<tr> +<td id="link.cc_toolchain"><code>cc_toolchain</code></td> +<td>Info; +required<br /> +<code>CcToolchainInfo</code> provider to be used.</td> +</tr> +<tr> +<td id="link.language"><code>language</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'c++'</code><br /> +Only C++ supported for now. Do not use this parameter.</td> +</tr> +<tr> +<td id="link.output_type"><code>output_type</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'executable'</code><br /> +Can be either 'executable' or 'dynamic_library'.</td> +</tr> +<tr> +<td id="link.link_deps_statically"><code>link_deps_statically</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +True to link dependencies statically, False dynamically.</td> +</tr> +<tr> +<td id="link.compilation_outputs"><code>compilation_outputs</code></td> +<td><a href="../builtins/CcCompilationOutputs.html" class="anchor">CcCompilationOutputs</a>; or <code>None</code>; +default is <code>None</code><br /> +Compilation outputs containing object files to link.</td> +</tr> +<tr> +<td id="link.linking_contexts"><code>linking_contexts</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Linking contexts from dependencies to be linked into the linking context generated by this rule.</td> +</tr> +<tr> +<td id="link.user_link_flags"><code>user_link_flags</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +Additional list of linker options.</td> +</tr> +<tr> +<td id="link.stamp"><code>stamp</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>0</code><br /> +Whether to include build information in the linked executable, if output_type is 'executable'. If 1, build information is always included. If 0 (the default build information is always excluded. If -1, uses the default behavior, which may be overridden by the --[no]stamp flag. This should be unset (or set to 0) when generating the executable output for test rules.</td> +</tr> +<tr> +<td id="link.additional_inputs"><code>additional_inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; +default is <code>[]</code><br /> +For additional inputs to the linking action, e.g.: linking scripts.</td> +</tr> +<tr> +<td id="link.additional_outputs"><code>additional_outputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +For additional outputs to the linking action, e.g.: map files.</td> +</tr> +<tr> +<td id="link.variables_extension"><code>variables_extension</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +Additional variables to pass to the toolchain configuration when create link command line.</td> +</tr> +</tbody> +</table> + +## merge_cc_infos + +``` rule-signature +unknown cc_common.merge_cc_infos(*, direct_cc_infos=[], cc_infos=[]) +``` + +Merges multiple `CcInfo`s into one. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="merge_cc_infos.direct_cc_infos"><code>direct_cc_infos</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of <code>CcInfo</code>s to be merged, whose headers will be exported by the direct fields in the returned provider.</td> +</tr> +<tr> +<td id="merge_cc_infos.cc_infos"><code>cc_infos</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of <code>CcInfo</code>s to be merged, whose headers will not be exported by the direct fields in the returned provider.</td> +</tr> +</tbody> +</table> + +## merge_compilation_contexts + +``` rule-signature +CompilationContext cc_common.merge_compilation_contexts(*, compilation_contexts=[]) +``` + +Merges multiple `CompilationContexts`s into one. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="merge_compilation_contexts.compilation_contexts"><code>compilation_contexts</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +List of <code>CompilationContexts</code>s to be merged. The headers of each context will be exported by the direct fields in the returned provider.</td> +</tr> +</tbody> +</table> + +## merge_compilation_outputs + +``` rule-signature +CcCompilationOutputs cc_common.merge_compilation_outputs(*, compilation_outputs=[]) +``` + +Merge compilation outputs. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="merge_compilation_outputs.compilation_outputs"><code>compilation_outputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/toplevel/config.mdx b/rules/lib/toplevel/config.mdx index ed66e77..9429803 100644 --- a/rules/lib/toplevel/config.mdx +++ b/rules/lib/toplevel/config.mdx @@ -2,287 +2,227 @@ title: 'config' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.config">config</h1> +# config {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> +{% include "\_buttons.html" %} +This is a top-level module for creating configuration transitions and build setting descriptors which describe what kind of build setting (if any) a rule is. + +ex: the following rule is marked as a build setting by setting the `build_setting` parameter of the `rule()` function. Specifically it is a build setting of type `int` and is a `flag` which means this build setting is callable on the command line. -This is a top-level module for creating configuration transitions and build setting descriptors which describe what kind of build setting (if any) a rule is. <p>ex: the following rule is marked as a build setting by setting the <code>build_setting</code> parameter of the <code>rule()</code> function. Specifically it is a build setting of type <code>int</code> and is a <code>flag</code> which means this build setting is callable on the command line.<br><pre class=language-python> my_rule = rule( +``` python + my_rule = rule( implementation = _impl, build_setting = config.int(flag = True), ... - )</pre> - -<h2>Members</h2> -<ul> - <li> - <a href="#bool">bool</a> - </li> - <li> - <a href="#exec">exec</a> - </li> - <li> - <a href="#int">int</a> - </li> - <li> - <a href="#none">none</a> - </li> - <li> - <a href="#string">string</a> - </li> - <li> - <a href="#string_list">string_list</a> - </li> - <li> - <a href="#string_set">string_set</a> - </li> - <li> - <a href="#target">target</a> - </li> - </ul> - - <h2 id="bool">bool</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.bool(*, flag=False)</pre></p> - - A bool-typed build setting - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="bool.flag"> - <code>flag</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether or not this build setting is callable on the command line. - </td> - </tr> - </tbody> - </table> - - <h2 id="exec">exec</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/ExecTransitionFactory.html">ExecTransitionFactory</a> config.exec(exec_group=None)</pre></p> - - Creates an execution transition. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="exec.exec_group"> - <code>exec_group</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <code>None</code>; - default is <code>None</code><br/> - The name of the exec group whose execution platform this transition will use. If not provided, this exec transition will use the target's default execution platform. - </td> - </tr> - </tbody> - </table> - - <h2 id="int">int</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.int(*, flag=False)</pre></p> - - An integer-typed build setting - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="int.flag"> - <code>flag</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether or not this build setting is callable on the command line. - </td> - </tr> - </tbody> - </table> - - <h2 id="none">none</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> config.none()</pre></p> - - Creates a transition which removes all configuration, unsetting all flags. Intended for the case where a dependency is data-only and contains no code that needs to be built, but should only be analyzed once. - - <h2 id="string">string</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.string(*, flag=False, allow_multiple=False)</pre></p> - - A string-typed build setting - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="string.flag"> - <code>flag</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether or not this build setting is callable on the command line. - </td> - </tr> - <tr> - <td id="string.allow_multiple"> - <code>allow_multiple</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Deprecated, use a <code>string_list</code> setting with <code>repeatable = True</code> instead. If set, this flag is allowed to be set multiple times on the command line. The Value of the flag as accessed in transitions and build setting implementation function will be a list of strings. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. - </td> - </tr> - </tbody> - </table> - - <h2 id="string_list">string_list</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.string_list(*, flag=False, repeatable=False)</pre></p> - - A string list-typed build setting. On the command line pass a list using comma-separated value like <code>--//my/setting=foo,bar</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="string_list.flag"> - <code>flag</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether or not this build setting is callable on the command line. - </td> - </tr> - <tr> - <td id="string_list.repeatable"> - <code>repeatable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the list value. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. - </td> - </tr> - </tbody> - </table> - - <h2 id="string_set">string_set</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/BuildSetting.html">BuildSetting</a> config.string_set(*, flag=False, repeatable=False)</pre></p> - - A string set-typed build setting. The value of this setting will be a <a href='https://bazel.build/rules/lib/core/set'>set</a> of strings in Starlark. On the command line, pass a set using a comma-separated value like <code>--//my/setting=foo,bar</code>.<p>Unlike with a <code>string_list</code>, the order of the elements doesn't matter and only a single instance of each element is maintained. This is recommended over <code>string_list</code> for flags where these properties are not needed as it can improve build performance by avoiding unnecessary configurations forking. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="string_set.flag"> - <code>flag</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether or not this build setting is callable on the command line. - </td> - </tr> - <tr> - <td id="string_set.repeatable"> - <code>repeatable</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the set value. Only a single instance of repeated values is maintained and the insertion order does not matter. - </td> - </tr> - </tbody> - </table> - - <h2 id="target">target</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/transition.html">transition</a> config.target()</pre></p> - - Creates a target transition. This is a no-op transition intended for the case where a transition object is needed, but doesn't want to actually change anything. Equivalent to <code>cfg = "target"</code> in <code>attr.label()</code>. - - -</body> -</html> - -<!-- {% endraw %} --> + ) +``` + +## Members + +- [bool](#bool) +- [exec](#exec) +- [int](#int) +- [none](#none) +- [string](#string) +- [string_list](#string_list) +- [string_set](#string_set) +- [target](#target) + +## bool + +``` rule-signature +BuildSetting config.bool(*, flag=False) +``` + +A bool-typed build setting + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="bool.flag"><code>flag</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether or not this build setting is callable on the command line.</td> +</tr> +</tbody> +</table> + +## exec + +``` rule-signature +ExecTransitionFactory config.exec(exec_group=None) +``` + +Creates an execution transition. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="exec.exec_group"><code>exec_group</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; +default is <code>None</code><br /> +The name of the exec group whose execution platform this transition will use. If not provided, this exec transition will use the target's default execution platform.</td> +</tr> +</tbody> +</table> + +## int + +``` rule-signature +BuildSetting config.int(*, flag=False) +``` + +An integer-typed build setting + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="int.flag"><code>flag</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether or not this build setting is callable on the command line.</td> +</tr> +</tbody> +</table> + +## none + +``` rule-signature +transition config.none() +``` + +Creates a transition which removes all configuration, unsetting all flags. Intended for the case where a dependency is data-only and contains no code that needs to be built, but should only be analyzed once. + +## string + +``` rule-signature +BuildSetting config.string(*, flag=False, allow_multiple=False) +``` + +A string-typed build setting + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="string.flag"><code>flag</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether or not this build setting is callable on the command line.</td> +</tr> +<tr> +<td id="string.allow_multiple"><code>allow_multiple</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Deprecated, use a <code>string_list</code> setting with <code>repeatable = True</code> instead. If set, this flag is allowed to be set multiple times on the command line. The Value of the flag as accessed in transitions and build setting implementation function will be a list of strings. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired.</td> +</tr> +</tbody> +</table> + +## string_list + +``` rule-signature +BuildSetting config.string_list(*, flag=False, repeatable=False) +``` + +A string list-typed build setting. On the command line pass a list using comma-separated value like `--//my/setting=foo,bar`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="string_list.flag"><code>flag</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether or not this build setting is callable on the command line.</td> +</tr> +<tr> +<td id="string_list.repeatable"><code>repeatable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the list value. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired.</td> +</tr> +</tbody> +</table> + +## string_set + +``` rule-signature +BuildSetting config.string_set(*, flag=False, repeatable=False) +``` + +A string set-typed build setting. The value of this setting will be a [set](https://bazel.build/rules/lib/core/set) of strings in Starlark. On the command line, pass a set using a comma-separated value like `--//my/setting=foo,bar`. + +Unlike with a `string_list`, the order of the elements doesn't matter and only a single instance of each element is maintained. This is recommended over `string_list` for flags where these properties are not needed as it can improve build performance by avoiding unnecessary configurations forking. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="string_set.flag"><code>flag</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether or not this build setting is callable on the command line.</td> +</tr> +<tr> +<td id="string_set.repeatable"><code>repeatable</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the set value. Only a single instance of repeated values is maintained and the insertion order does not matter.</td> +</tr> +</tbody> +</table> + +## target + +``` rule-signature +transition config.target() +``` + +Creates a target transition. This is a no-op transition intended for the case where a transition object is needed, but doesn't want to actually change anything. Equivalent to `cfg = "target"` in `attr.label()`. diff --git a/rules/lib/toplevel/config_common.mdx b/rules/lib/toplevel/config_common.mdx index 49cc61a..9d12b24 100644 --- a/rules/lib/toplevel/config_common.mdx +++ b/rules/lib/toplevel/config_common.mdx @@ -2,80 +2,54 @@ title: 'config_common' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.config_common">config_common</h1> +# config_common {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigStarlarkCommonApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Functions for Starlark to interact with Blaze's configurability APIs. -<h2>Members</h2> -<ul> - <li> - <a href="#FeatureFlagInfo">FeatureFlagInfo</a> - </li> - <li> - <a href="#toolchain_type">toolchain_type</a> - </li> - </ul> - - <h2 id="FeatureFlagInfo">FeatureFlagInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> config_common.FeatureFlagInfo</pre></p> - - The key used to retrieve the provider containing config_feature_flag's value. - - <h2 id="toolchain_type">toolchain_type</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/toolchain_type.html">toolchain_type</a> config_common.toolchain_type(name, *, mandatory=True)</pre></p> - - Declare a rule's dependency on a toolchain type. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="toolchain_type.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; - required<br/> - The toolchain type that is required. - </td> - </tr> - <tr> - <td id="toolchain_type.mandatory"> - <code>mandatory</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - Whether the toolchain type is mandatory or optional. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [FeatureFlagInfo](#FeatureFlagInfo) +- [toolchain_type](#toolchain_type) + +## FeatureFlagInfo + +``` rule-signature +Provider config_common.FeatureFlagInfo +``` + +The key used to retrieve the provider containing config_feature_flag's value. + +## toolchain_type + +``` rule-signature +toolchain_type config_common.toolchain_type(name, *, mandatory=True) +``` + +Declare a rule's dependency on a toolchain type. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="toolchain_type.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; +required<br /> +The toolchain type that is required.</td> +</tr> +<tr> +<td id="toolchain_type.mandatory"><code>mandatory</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +Whether the toolchain type is mandatory or optional.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/toplevel/coverage_common.mdx b/rules/lib/toplevel/coverage_common.mdx index b843290..54ed6fa 100644 --- a/rules/lib/toplevel/coverage_common.mdx +++ b/rules/lib/toplevel/coverage_common.mdx @@ -2,112 +2,69 @@ title: 'coverage_common' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.coverage_common">coverage_common</h1> +# coverage_common {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Helper functions to access coverage-related infrastructure. -<h2>Members</h2> -<ul> - <li> - <a href="#instrumented_files_info">instrumented_files_info</a> - </li> - </ul> +## Members - <h2 id="instrumented_files_info">instrumented_files_info</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/InstrumentedFilesInfo.html">InstrumentedFilesInfo</a> coverage_common.instrumented_files_info(ctx, *, source_attributes=[], dependency_attributes=[], extensions=None, metadata_files=[], baseline_coverage_files=None)</pre></p> +- [instrumented_files_info](#instrumented_files_info) - Creates a new <a class="anchor" href="../providers/InstrumentedFilesInfo.html">InstrumentedFilesInfo</a> instance. Use this provider to communicate coverage-related attributes of the current build rule. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="instrumented_files_info.ctx"> - <code>ctx</code> - </td> - <td> - <a class="anchor" href="../builtins/ctx.html">ctx</a>; - required<br/> - The rule context. - </td> - </tr> - <tr> - <td id="instrumented_files_info.source_attributes"> - <code>source_attributes</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - A list of attribute names which contain source files processed by this rule. - </td> - </tr> - <tr> - <td id="instrumented_files_info.dependency_attributes"> - <code>dependency_attributes</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - A list of attribute names which might provide runtime dependencies (either code dependencies or runfiles). - </td> - </tr> - <tr> - <td id="instrumented_files_info.extensions"> - <code>extensions</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - File extensions used to filter files from source_attributes. For example, 'js'. If not provided (or None), then all files from source_attributes will be added to instrumented files, if an empty list is provided, then no files from source attributes will be added. - </td> - </tr> - <tr> - <td id="instrumented_files_info.metadata_files"> - <code>metadata_files</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - Additional files required to generate coverage LCOV files after code execution. e.g. .gcno files for C++. - </td> - </tr> - <tr> - <td id="instrumented_files_info.baseline_coverage_files"> - <code>baseline_coverage_files</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; or <code>None</code>; - default is <code>None</code><br/> +## instrumented_files_info - </td> - </tr> - </tbody> - </table> +``` rule-signature +InstrumentedFilesInfo coverage_common.instrumented_files_info(ctx, *, source_attributes=[], dependency_attributes=[], extensions=None, metadata_files=[], baseline_coverage_files=None) +``` +Creates a new <a href="../providers/InstrumentedFilesInfo.html" class="anchor">InstrumentedFilesInfo</a> instance. Use this provider to communicate coverage-related attributes of the current build rule. -</body> -</html> +### Parameters -<!-- {% endraw %} --> +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="instrumented_files_info.ctx"><code>ctx</code></td> +<td><a href="../builtins/ctx.html" class="anchor">ctx</a>; +required<br /> +The rule context.</td> +</tr> +<tr> +<td id="instrumented_files_info.source_attributes"><code>source_attributes</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +A list of attribute names which contain source files processed by this rule.</td> +</tr> +<tr> +<td id="instrumented_files_info.dependency_attributes"><code>dependency_attributes</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +A list of attribute names which might provide runtime dependencies (either code dependencies or runfiles).</td> +</tr> +<tr> +<td id="instrumented_files_info.extensions"><code>extensions</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +File extensions used to filter files from source_attributes. For example, 'js'. If not provided (or None), then all files from source_attributes will be added to instrumented files, if an empty list is provided, then no files from source attributes will be added.</td> +</tr> +<tr> +<td id="instrumented_files_info.metadata_files"><code>metadata_files</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +Additional files required to generate coverage LCOV files after code execution. e.g. .gcno files for C++.</td> +</tr> +<tr> +<td id="instrumented_files_info.baseline_coverage_files"><code>baseline_coverage_files</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <code>None</code>; +default is <code>None</code><br /> +</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/toplevel/java_common.mdx b/rules/lib/toplevel/java_common.mdx index d3ccc53..2290100 100644 --- a/rules/lib/toplevel/java_common.mdx +++ b/rules/lib/toplevel/java_common.mdx @@ -2,575 +2,393 @@ title: 'java_common' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.java_common">java_common</h1> +# java_common {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Utilities for Java compilation support in Starlark. -<h2>Members</h2> -<ul> - <li> - <a href="#BootClassPathInfo">BootClassPathInfo</a> - </li> - <li> - <a href="#compile">compile</a> - </li> - <li> - <a href="#JavaRuntimeInfo">JavaRuntimeInfo</a> - </li> - <li> - <a href="#JavaToolchainInfo">JavaToolchainInfo</a> - </li> - <li> - <a href="#merge">merge</a> - </li> - <li> - <a href="#pack_sources">pack_sources</a> - </li> - <li> - <a href="#run_ijar">run_ijar</a> - </li> - <li> - <a href="#stamp_jar">stamp_jar</a> - </li> - </ul> - - <h2 id="BootClassPathInfo">BootClassPathInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> java_common.BootClassPathInfo</pre></p> - - The provider used to supply bootclasspath information - - <h2 id="compile">compile</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> java_common.compile(ctx, *, source_jars=[], source_files=[], output, output_source_jar=None, javac_opts=[], deps=[], runtime_deps=[], exports=[], plugins=[], exported_plugins=[], native_libraries=[], annotation_processor_additional_inputs=[], annotation_processor_additional_outputs=[], strict_deps='ERROR', java_toolchain, bootclasspath=None, sourcepath=[], resources=[], resource_jars=[], classpath_resources=[], neverlink=False, enable_annotation_processing=True, enable_compile_jar_action=True, add_exports=[], add_opens=[])</pre></p> - - Compiles Java source files/jars from the implementation of a Starlark rule and returns a provider that represents the results of the compilation and can be added to the set of providers emitted by this rule. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="compile.ctx"> - <code>ctx</code> - </td> - <td> - <a class="anchor" href="../builtins/ctx.html">ctx</a>; - required<br/> - The rule context. - </td> - </tr> - <tr> - <td id="compile.source_jars"> - <code>source_jars</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - A list of the jars to be compiled. At least one of source_jars or source_files should be specified. - </td> - </tr> - <tr> - <td id="compile.source_files"> - <code>source_files</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - A list of the Java source files to be compiled. At least one of source_jars or source_files should be specified. - </td> - </tr> - <tr> - <td id="compile.output"> - <code>output</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - - </td> - </tr> - <tr> - <td id="compile.output_source_jar"> - <code>output_source_jar</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - The output source jar. Defaults to `{output_jar}-src.jar` if unset. - </td> - </tr> - <tr> - <td id="compile.javac_opts"> - <code>javac_opts</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A list of the desired javac options. - </td> - </tr> - <tr> - <td id="compile.deps"> - <code>deps</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; - default is <code>[]</code><br/> - A list of dependencies. - </td> - </tr> - <tr> - <td id="compile.runtime_deps"> - <code>runtime_deps</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; - default is <code>[]</code><br/> - A list of runtime dependencies. - </td> - </tr> - <tr> - <td id="compile.exports"> - <code>exports</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; - default is <code>[]</code><br/> - A list of exports. - </td> - </tr> - <tr> - <td id="compile.plugins"> - <code>plugins</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; - default is <code>[]</code><br/> - A list of plugins. - </td> - </tr> - <tr> - <td id="compile.exported_plugins"> - <code>exported_plugins</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; or <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; - default is <code>[]</code><br/> - A list of exported plugins. - </td> - </tr> - <tr> - <td id="compile.native_libraries"> - <code>native_libraries</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../providers/CcInfo.html">CcInfo</a>s; - default is <code>[]</code><br/> - CC native library dependencies that are needed for this library. - </td> - </tr> - <tr> - <td id="compile.annotation_processor_additional_inputs"> - <code>annotation_processor_additional_inputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - A list of inputs that the Java compilation action will take in addition to the Java sources for annotation processing. - </td> - </tr> - <tr> - <td id="compile.annotation_processor_additional_outputs"> - <code>annotation_processor_additional_outputs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - A list of outputs that the Java compilation action will output in addition to the class jar from annotation processing. - </td> - </tr> - <tr> - <td id="compile.strict_deps"> - <code>strict_deps</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - default is <code>'ERROR'</code><br/> - A string that specifies how to handle strict deps. Possible values: 'OFF', 'ERROR', 'WARN' and 'DEFAULT'. For more details see <a href="/docs/user-manual#flag--strict_java_deps"><code>--strict_java_deps<code> flag</a>. By default 'ERROR'. - </td> - </tr> - <tr> - <td id="compile.java_toolchain"> - <code>java_toolchain</code> - </td> - <td> - Info; - required<br/> - A JavaToolchainInfo to be used for this compilation. Mandatory. - </td> - </tr> - <tr> - <td id="compile.bootclasspath"> - <code>bootclasspath</code> - </td> - <td> - default is <code>None</code><br/> - A BootClassPathInfo to be used for this compilation. If present, overrides the bootclasspath associated with the provided java_toolchain. - </td> - </tr> - <tr> - <td id="compile.sourcepath"> - <code>sourcepath</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - - </td> - </tr> - <tr> - <td id="compile.resources"> - <code>resources</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - - </td> - </tr> - <tr> - <td id="compile.resource_jars"> - <code>resource_jars</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - - </td> - </tr> - <tr> - <td id="compile.classpath_resources"> - <code>classpath_resources</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - - </td> - </tr> - <tr> - <td id="compile.neverlink"> - <code>neverlink</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - - </td> - </tr> - <tr> - <td id="compile.enable_annotation_processing"> - <code>enable_annotation_processing</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - Disables annotation processing in this compilation, causing any annotation processors provided in plugins or in exported_plugins of deps to be ignored. - </td> - </tr> - <tr> - <td id="compile.enable_compile_jar_action"> - <code>enable_compile_jar_action</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>True</code><br/> - Enables header compilation or ijar creation. If set to False, it forces use of the full class jar in the compilation classpaths of any dependants. Doing so is intended for use by non-library targets such as binaries that do not have dependants. - </td> - </tr> - <tr> - <td id="compile.add_exports"> - <code>add_exports</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Allow this library to access the given <module>/<package>. - </td> - </tr> - <tr> - <td id="compile.add_opens"> - <code>add_opens</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Allow this library to reflectively access the given <module>/<package>. - </td> - </tr> - </tbody> - </table> - - <h2 id="JavaRuntimeInfo">JavaRuntimeInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> java_common.JavaRuntimeInfo</pre></p> - - The key used to retrieve the provider that contains information about the Java runtime being used. - - <h2 id="JavaToolchainInfo">JavaToolchainInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> java_common.JavaToolchainInfo</pre></p> - - The key used to retrieve the provider that contains information about the Java toolchain being used. - - <h2 id="merge">merge</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/struct.html">struct</a> java_common.merge(providers)</pre></p> - - Merges the given providers into a single JavaInfo. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="merge.providers"> - <code>providers</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/struct.html">struct</a>s; - required<br/> - The list of providers to merge. - </td> - </tr> - </tbody> - </table> - - <h2 id="pack_sources">pack_sources</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_common.pack_sources(actions, *, output_source_jar=None, sources=[], source_jars=[], java_toolchain)</pre></p> - - Packs sources and source jars into a single source jar file. The return value is typically passed to<p><code><a class="anchor" href="../providers/JavaInfo.html">JavaInfo</a>#source_jar</code></p>.At least one of parameters output_jar or output_source_jar is required. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="pack_sources.actions"> - <code>actions</code> - </td> - <td> - <a class="anchor" href="../builtins/actions.html">actions</a>; - required<br/> - ctx.actions - </td> - </tr> - <tr> - <td id="pack_sources.output_source_jar"> - <code>output_source_jar</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; or <code>None</code>; - default is <code>None</code><br/> - The output source jar. - </td> - </tr> - <tr> - <td id="pack_sources.sources"> - <code>sources</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - A list of Java source files to be packed into the source jar. - </td> - </tr> - <tr> - <td id="pack_sources.source_jars"> - <code>source_jars</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../builtins/File.html">File</a>s; - default is <code>[]</code><br/> - A list of source jars to be packed into the source jar. - </td> - </tr> - <tr> - <td id="pack_sources.java_toolchain"> - <code>java_toolchain</code> - </td> - <td> - Info; - required<br/> - A JavaToolchainInfo to used to find the ijar tool. - </td> - </tr> - </tbody> - </table> - - <h2 id="run_ijar">run_ijar</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_common.run_ijar(actions, *, jar, target_label=None, java_toolchain)</pre></p> - - Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding of dependent jars during any recompiles consisting only of simple changes to method implementations. The return value is typically passed to <code><a class="anchor" href="../providers/JavaInfo.html">JavaInfo</a>#compile_jar</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="run_ijar.actions"> - <code>actions</code> - </td> - <td> - <a class="anchor" href="../builtins/actions.html">actions</a>; - required<br/> - ctx.actions - </td> - </tr> - <tr> - <td id="run_ijar.jar"> - <code>jar</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The jar to run ijar on. - </td> - </tr> - <tr> - <td id="run_ijar.target_label"> - <code>target_label</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; or <code>None</code>; - default is <code>None</code><br/> - A target label to stamp the jar with. Used for <code>add_dep</code> support. Typically, you would pass <code>ctx.label</code> to stamp the jar with the current rule's label. - </td> - </tr> - <tr> - <td id="run_ijar.java_toolchain"> - <code>java_toolchain</code> - </td> - <td> - Info; - required<br/> - A JavaToolchainInfo to used to find the ijar tool. - </td> - </tr> - </tbody> - </table> - - <h2 id="stamp_jar">stamp_jar</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/File.html">File</a> java_common.stamp_jar(actions, *, jar, target_label, java_toolchain)</pre></p> - - Stamps a jar with a target label for <code>add_dep</code> support. The return value is typically passed to <code><a class="anchor" href="../providers/JavaInfo.html">JavaInfo</a>#compile_jar</code>. Prefer to use <code><a class="anchor" href="#run_ijar">run_ijar</a></code> when possible. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="stamp_jar.actions"> - <code>actions</code> - </td> - <td> - <a class="anchor" href="../builtins/actions.html">actions</a>; - required<br/> - ctx.actions - </td> - </tr> - <tr> - <td id="stamp_jar.jar"> - <code>jar</code> - </td> - <td> - <a class="anchor" href="../builtins/File.html">File</a>; - required<br/> - The jar to run stamp_jar on. - </td> - </tr> - <tr> - <td id="stamp_jar.target_label"> - <code>target_label</code> - </td> - <td> - <a class="anchor" href="../builtins/Label.html">Label</a>; - required<br/> - A target label to stamp the jar with. Used for <code>add_dep</code> support. Typically, you would pass <code>ctx.label</code> to stamp the jar with the current rule's label. - </td> - </tr> - <tr> - <td id="stamp_jar.java_toolchain"> - <code>java_toolchain</code> - </td> - <td> - Info; - required<br/> - A JavaToolchainInfo to used to find the stamp_jar tool. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [BootClassPathInfo](#BootClassPathInfo) +- [compile](#compile) +- [JavaRuntimeInfo](#JavaRuntimeInfo) +- [JavaToolchainInfo](#JavaToolchainInfo) +- [merge](#merge) +- [pack_sources](#pack_sources) +- [run_ijar](#run_ijar) +- [stamp_jar](#stamp_jar) + +## BootClassPathInfo + +``` rule-signature +Provider java_common.BootClassPathInfo +``` + +The provider used to supply bootclasspath information + +## compile + +``` rule-signature +struct java_common.compile(ctx, *, source_jars=[], source_files=[], output, output_source_jar=None, javac_opts=[], deps=[], runtime_deps=[], exports=[], plugins=[], exported_plugins=[], native_libraries=[], annotation_processor_additional_inputs=[], annotation_processor_additional_outputs=[], strict_deps='ERROR', java_toolchain, bootclasspath=None, sourcepath=[], resources=[], resource_jars=[], classpath_resources=[], neverlink=False, enable_annotation_processing=True, enable_compile_jar_action=True, add_exports=[], add_opens=[]) +``` + +Compiles Java source files/jars from the implementation of a Starlark rule and returns a provider that represents the results of the compilation and can be added to the set of providers emitted by this rule. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="compile.ctx"><code>ctx</code></td> +<td><a href="../builtins/ctx.html" class="anchor">ctx</a>; +required<br /> +The rule context.</td> +</tr> +<tr> +<td id="compile.source_jars"><code>source_jars</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +A list of the jars to be compiled. At least one of source_jars or source_files should be specified.</td> +</tr> +<tr> +<td id="compile.source_files"><code>source_files</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +A list of the Java source files to be compiled. At least one of source_jars or source_files should be specified.</td> +</tr> +<tr> +<td id="compile.output"><code>output</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +</td> +</tr> +<tr> +<td id="compile.output_source_jar"><code>output_source_jar</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +The output source jar. Defaults to `{output_jar}-src.jar` if unset.</td> +</tr> +<tr> +<td id="compile.javac_opts"><code>javac_opts</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A list of the desired javac options.</td> +</tr> +<tr> +<td id="compile.deps"><code>deps</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; +default is <code>[]</code><br /> +A list of dependencies.</td> +</tr> +<tr> +<td id="compile.runtime_deps"><code>runtime_deps</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; +default is <code>[]</code><br /> +A list of runtime dependencies.</td> +</tr> +<tr> +<td id="compile.exports"><code>exports</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; +default is <code>[]</code><br /> +A list of exports.</td> +</tr> +<tr> +<td id="compile.plugins"><code>plugins</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; +default is <code>[]</code><br /> +A list of plugins.</td> +</tr> +<tr> +<td id="compile.exported_plugins"><code>exported_plugins</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; +default is <code>[]</code><br /> +A list of exported plugins.</td> +</tr> +<tr> +<td id="compile.native_libraries"><code>native_libraries</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../providers/CcInfo.html" class="anchor">CcInfo</a>s; +default is <code>[]</code><br /> +CC native library dependencies that are needed for this library.</td> +</tr> +<tr> +<td id="compile.annotation_processor_additional_inputs"><code>annotation_processor_additional_inputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +A list of inputs that the Java compilation action will take in addition to the Java sources for annotation processing.</td> +</tr> +<tr> +<td id="compile.annotation_processor_additional_outputs"><code>annotation_processor_additional_outputs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +A list of outputs that the Java compilation action will output in addition to the class jar from annotation processing.</td> +</tr> +<tr> +<td id="compile.strict_deps"><code>strict_deps</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +default is <code>'ERROR'</code><br /> +A string that specifies how to handle strict deps. Possible values: 'OFF', 'ERROR', 'WARN' and 'DEFAULT'. For more details see +--strict_java_deps +flag. By default 'ERROR'.</td> +</tr> +<tr> +<td id="compile.java_toolchain"><code>java_toolchain</code></td> +<td>Info; +required<br /> +A JavaToolchainInfo to be used for this compilation. Mandatory.</td> +</tr> +<tr> +<td id="compile.bootclasspath"><code>bootclasspath</code></td> +<td>default is <code>None</code><br /> +A BootClassPathInfo to be used for this compilation. If present, overrides the bootclasspath associated with the provided java_toolchain.</td> +</tr> +<tr> +<td id="compile.sourcepath"><code>sourcepath</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +</td> +</tr> +<tr> +<td id="compile.resources"><code>resources</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +</td> +</tr> +<tr> +<td id="compile.resource_jars"><code>resource_jars</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +</td> +</tr> +<tr> +<td id="compile.classpath_resources"><code>classpath_resources</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +</td> +</tr> +<tr> +<td id="compile.neverlink"><code>neverlink</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +</td> +</tr> +<tr> +<td id="compile.enable_annotation_processing"><code>enable_annotation_processing</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +Disables annotation processing in this compilation, causing any annotation processors provided in plugins or in exported_plugins of deps to be ignored.</td> +</tr> +<tr> +<td id="compile.enable_compile_jar_action"><code>enable_compile_jar_action</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>True</code><br /> +Enables header compilation or ijar creation. If set to False, it forces use of the full class jar in the compilation classpaths of any dependants. Doing so is intended for use by non-library targets such as binaries that do not have dependants.</td> +</tr> +<tr> +<td id="compile.add_exports"><code>add_exports</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Allow this library to access the given /.</td> +</tr> +<tr> +<td id="compile.add_opens"><code>add_opens</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Allow this library to reflectively access the given /.</td> +</tr> +</tbody> +</table> + +## JavaRuntimeInfo + +``` rule-signature +Provider java_common.JavaRuntimeInfo +``` + +The key used to retrieve the provider that contains information about the Java runtime being used. + +## JavaToolchainInfo + +``` rule-signature +Provider java_common.JavaToolchainInfo +``` + +The key used to retrieve the provider that contains information about the Java toolchain being used. + +## merge + +``` rule-signature +struct java_common.merge(providers) +``` + +Merges the given providers into a single JavaInfo. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="merge.providers"><code>providers</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; +required<br /> +The list of providers to merge.</td> +</tr> +</tbody> +</table> + +## pack_sources + +``` rule-signature +File java_common.pack_sources(actions, *, output_source_jar=None, sources=[], source_jars=[], java_toolchain) +``` + +Packs sources and source jars into a single source jar file. The return value is typically passed to + +<a href="../providers/JavaInfo.html" class="anchor"><code>JavaInfo</code></a>`#source_jar` + +.At least one of parameters output_jar or output_source_jar is required. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="pack_sources.actions"><code>actions</code></td> +<td><a href="../builtins/actions.html" class="anchor">actions</a>; +required<br /> +ctx.actions</td> +</tr> +<tr> +<td id="pack_sources.output_source_jar"><code>output_source_jar</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; +default is <code>None</code><br /> +The output source jar.</td> +</tr> +<tr> +<td id="pack_sources.sources"><code>sources</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +A list of Java source files to be packed into the source jar.</td> +</tr> +<tr> +<td id="pack_sources.source_jars"><code>source_jars</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; +default is <code>[]</code><br /> +A list of source jars to be packed into the source jar.</td> +</tr> +<tr> +<td id="pack_sources.java_toolchain"><code>java_toolchain</code></td> +<td>Info; +required<br /> +A JavaToolchainInfo to used to find the ijar tool.</td> +</tr> +</tbody> +</table> + +## run_ijar + +``` rule-signature +File java_common.run_ijar(actions, *, jar, target_label=None, java_toolchain) +``` + +Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding of dependent jars during any recompiles consisting only of simple changes to method implementations. The return value is typically passed to <a href="../providers/JavaInfo.html" class="anchor"><code>JavaInfo</code></a>`#compile_jar`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="run_ijar.actions"><code>actions</code></td> +<td><a href="../builtins/actions.html" class="anchor">actions</a>; +required<br /> +ctx.actions</td> +</tr> +<tr> +<td id="run_ijar.jar"><code>jar</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The jar to run ijar on.</td> +</tr> +<tr> +<td id="run_ijar.target_label"><code>target_label</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <code>None</code>; +default is <code>None</code><br /> +A target label to stamp the jar with. Used for <code>add_dep</code> support. Typically, you would pass <code>ctx.label</code> to stamp the jar with the current rule's label.</td> +</tr> +<tr> +<td id="run_ijar.java_toolchain"><code>java_toolchain</code></td> +<td>Info; +required<br /> +A JavaToolchainInfo to used to find the ijar tool.</td> +</tr> +</tbody> +</table> + +## stamp_jar + +``` rule-signature +File java_common.stamp_jar(actions, *, jar, target_label, java_toolchain) +``` + +Stamps a jar with a target label for `add_dep` support. The return value is typically passed to <a href="../providers/JavaInfo.html" class="anchor"><code>JavaInfo</code></a>`#compile_jar`. Prefer to use <a href="#run_ijar" class="anchor"><code>run_ijar</code></a> when possible. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="stamp_jar.actions"><code>actions</code></td> +<td><a href="../builtins/actions.html" class="anchor">actions</a>; +required<br /> +ctx.actions</td> +</tr> +<tr> +<td id="stamp_jar.jar"><code>jar</code></td> +<td><a href="../builtins/File.html" class="anchor">File</a>; +required<br /> +The jar to run stamp_jar on.</td> +</tr> +<tr> +<td id="stamp_jar.target_label"><code>target_label</code></td> +<td><a href="../builtins/Label.html" class="anchor">Label</a>; +required<br /> +A target label to stamp the jar with. Used for <code>add_dep</code> support. Typically, you would pass <code>ctx.label</code> to stamp the jar with the current rule's label.</td> +</tr> +<tr> +<td id="stamp_jar.java_toolchain"><code>java_toolchain</code></td> +<td>Info; +required<br /> +A JavaToolchainInfo to used to find the stamp_jar tool.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/toplevel/native.mdx b/rules/lib/toplevel/native.mdx index c96a2c2..6ca8dcf 100644 --- a/rules/lib/toplevel/native.mdx +++ b/rules/lib/toplevel/native.mdx @@ -2,387 +2,330 @@ title: 'native' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.native">native</h1> +# native {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - -A built-in module to support native rules and other package helper functions. All native rules appear as functions in this module, e.g. <code>native.cc_library</code>. Note that the native module is only available in the loading phase (i.e. for macros, not for rule implementations). Attributes will ignore <code>None</code> values, and treat them as if the attribute was unset.<br>The following functions are also available: - -<h2>Members</h2> -<ul> - <li> - <a href="#existing_rule">existing_rule</a> - </li> - <li> - <a href="#existing_rules">existing_rules</a> - </li> - <li> - <a href="#exports_files">exports_files</a> - </li> - <li> - <a href="#glob">glob</a> - </li> - <li> - <a href="#module_name">module_name</a> - </li> - <li> - <a href="#module_version">module_version</a> - </li> - <li> - <a href="#package_default_visibility">package_default_visibility</a> - </li> - <li> - <a href="#package_group">package_group</a> - </li> - <li> - <a href="#package_name">package_name</a> - </li> - <li> - <a href="#package_relative_label">package_relative_label</a> - </li> - <li> - <a href="#repo_name">repo_name</a> - </li> - <li> - <a href="#repository_name">repository_name</a> - </li> - <li> - <a href="#subpackages">subpackages</a> - </li> - </ul> - - <h2 id="existing_rule">existing_rule</h2> - <p><pre class="rule-signature">unknown native.existing_rule(name)</pre></p> - - Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or <code>None</code> if no rule instance of that name exists.<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>, <code>x.keys()</code>, and <code>x.values()</code>.<p>The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's <code>name</code> and <code>kind</code> (for example, <code>'cc_binary'</code>).<p>The values of the result represent attribute values as follows:<ul><li>Attributes of type str, int, and bool are represented as is.</li><li>Labels are converted to strings of the form <code>':foo'</code> for targets in the same package or <code>'//pkg:name'</code> for targets in a different package.</li><li>Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion.</li><li><code>select</code> values are returned with their contents transformed as described above.</li><li>Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.).</li></ul><p>If possible, use this function only in <a href="https://bazel.build/extending/macros#finalizers">implementation functions of rule finalizer symbolic macros</a>. Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes <code>BUILD</code> files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by <code>ctx.attr.foo</code>. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="existing_rule.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The name of the target. - </td> - </tr> - </tbody> - </table> - - <h2 id="existing_rules">existing_rules</h2> - <p><pre class="rule-signature">unknown native.existing_rules()</pre></p> - - Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by <code>existing_rule(name)</code>.<p>Here, an <em>immutable dict-like object</em> means a deeply immutable object <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>, <code>x.keys()</code>, and <code>x.values()</code>.<p>If possible, use this function only in <a href="https://bazel.build/extending/macros#finalizers">implementation functions of rule finalizer symbolic macros</a>. Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes <code>BUILD</code> files brittle and order-dependent. - - <h2 id="exports_files">exports_files</h2> - <p><pre class="rule-signature"><code>None</code> native.exports_files(srcs, visibility=None, licenses=None)</pre></p> - - Specifies a list of files belonging to this package that are exported to other packages. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="exports_files.srcs"> - <code>srcs</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The list of files to export. - </td> - </tr> - <tr> - <td id="exports_files.visibility"> - <code>visibility</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; or <code>None</code>; - default is <code>None</code><br/> - A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. - </td> - </tr> - <tr> - <td id="exports_files.licenses"> - <code>licenses</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; or <code>None</code>; - default is <code>None</code><br/> - Licenses to be specified. - </td> - </tr> - </tbody> - </table> - - <h2 id="glob">glob</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> native.glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)</pre></p> - - Glob returns a new, mutable, sorted list of every file in the current package that:<ul> -<li>Matches at least one pattern in <code>include</code>.</li> -<li>Does not match any of the patterns in <code>exclude</code> (default <code>[]</code>).</li></ul> -If the <code>exclude_directories</code> argument is enabled (set to <code>1</code>), files of type directory will be omitted from the results (default <code>1</code>). - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="glob.include"> - <code>include</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - The list of glob patterns to include. - </td> - </tr> - <tr> - <td id="glob.exclude"> - <code>exclude</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - The list of glob patterns to exclude. - </td> - </tr> - <tr> - <td id="glob.exclude_directories"> - <code>exclude_directories</code> - </td> - <td> - <a class="anchor" href="../core/int.html">int</a>; - default is <code>1</code><br/> - A flag whether to exclude directories or not. - </td> - </tr> - <tr> - <td id="glob.allow_empty"> - <code>allow_empty</code> - </td> - <td> - default is <code>unbound</code><br/> - Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). - </td> - </tr> - </tbody> - </table> - - <h2 id="module_name">module_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.module_name()</pre></p> - - The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the <code>module.name</code> field seen in <code>module_ctx.modules</code>. - May return <code>None</code>. - - <h2 id="module_version">module_version</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.module_version()</pre></p> - - The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the <code>module.version</code> field seen in <code>module_ctx.modules</code>. - May return <code>None</code>. - - <h2 id="package_default_visibility">package_default_visibility</h2> - <p><pre class="rule-signature">List native.package_default_visibility()</pre></p> - - Returns the default visibility of the package being evaluated. This is the value of the <code>default_visibility</code> parameter of <code>package()</code>, extended to include the package itself. - - <h2 id="package_group">package_group</h2> - <p><pre class="rule-signature"><code>None</code> native.package_group(*, name, packages=[], includes=[])</pre></p> - - This function defines a set of packages and assigns a label to the group. The label can be referenced in <code>visibility</code> attributes. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="package_group.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - The unique name for this rule. - </td> - </tr> - <tr> - <td id="package_group.packages"> - <code>packages</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A complete enumeration of packages in this group. - </td> - </tr> - <tr> - <td id="package_group.includes"> - <code>includes</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - Other package groups that are included in this one. - </td> - </tr> - </tbody> - </table> - - <h2 id="package_name">package_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.package_name()</pre></p> - - The name of the package being evaluated, without the repository name. For example, in the BUILD file <code>some/package/BUILD</code>, its value will be <code>some/package</code>. If the BUILD file calls a function defined in a .bzl file, <code>package_name()</code> will match the caller BUILD file package. The value will always be an empty string for the root package. - - <h2 id="package_relative_label">package_relative_label</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> native.package_relative_label(input)</pre></p> - - Converts the input string into a <a href='../builtins/Label.html'>Label</a> object, in the context of the package currently being initialized (that is, the <code>BUILD</code> file for which the current macro is executing). If the input is already a <code>Label</code>, it is returned unchanged.<p>This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. <p>The result of this function is the same <code>Label</code> value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file. <p><i>Usage note:</i> The difference between this function and <a href='../builtins/Label.html#Label'>Label()</a></code> is that <code>Label()</code> uses the context of the package of the <code>.bzl</code> file that called it, not the package of the <code>BUILD</code> file. Use <code>Label()</code> when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use <code>package_relative_label()</code> when you need to normalize a label string supplied by the BUILD file to a <code>Label</code> object. (There is no way to convert a string to a <code>Label</code> in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="package_relative_label.input"> - <code>input</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; or <a class="anchor" href="../builtins/Label.html">Label</a>; - required<br/> - The input label string or Label object. If a Label object is passed, it's returned as is. - </td> - </tr> - </tbody> - </table> - - <h2 id="repo_name">repo_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.repo_name()</pre></p> - - The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. - - <h2 id="repository_name">repository_name</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> native.repository_name()</pre></p> - - <b>Experimental</b>. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--+incompatible_enable_deprecated_label_apis</code> <br><strong>Deprecated.</strong> Prefer to use <a href="#repo_name"><code>repo_name</code></a> instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise.<p>The canonical name of the repository containing the package currently being evaluated, with a single at-sign (<code>@</code>) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza <code>local_repository(name='local', path=...)</code> it will be set to <code>@local</code>. In packages in the main repository, it will be set to <code>@</code>. - - <h2 id="subpackages">subpackages</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">sequence</a> native.subpackages(*, include, exclude=[], allow_empty=False)</pre></p> - - Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel_skylib.subpackages module rather than calling this function directly. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="subpackages.include"> - <code>include</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - required<br/> - The list of glob patterns to include in subpackages scan. - </td> - </tr> - <tr> - <td id="subpackages.exclude"> - <code>exclude</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - The list of glob patterns to exclude from subpackages scan. - </td> - </tr> - <tr> - <td id="subpackages.allow_empty"> - <code>allow_empty</code> - </td> - <td> - <a class="anchor" href="../core/bool.html">bool</a>; - default is <code>False</code><br/> - Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +{% include "\_buttons.html" %} +A built-in module to support native rules and other package helper functions. All native rules appear as functions in this module, e.g. `native.cc_library`. Note that the native module is only available in the loading phase (i.e. for macros, not for rule implementations). Attributes will ignore `None` values, and treat them as if the attribute was unset. +The following functions are also available: + +## Members + +- [existing_rule](#existing_rule) +- [existing_rules](#existing_rules) +- [exports_files](#exports_files) +- [glob](#glob) +- [module_name](#module_name) +- [module_version](#module_version) +- [package_default_visibility](#package_default_visibility) +- [package_group](#package_group) +- [package_name](#package_name) +- [package_relative_label](#package_relative_label) +- [repo_name](#repo_name) +- [repository_name](#repository_name) +- [subpackages](#subpackages) + +## existing_rule + +``` rule-signature +unknown native.existing_rule(name) +``` + +Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or `None` if no rule instance of that name exists. + +Here, an *immutable dict-like object* means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. + +The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's `name` and `kind` (for example, `'cc_binary'`). + +The values of the result represent attribute values as follows: + +- Attributes of type str, int, and bool are represented as is. +- Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. +- Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. +- `select` values are returned with their contents transformed as described above. +- Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). + +If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by `ctx.attr.foo`. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="existing_rule.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The name of the target.</td> +</tr> +</tbody> +</table> + +## existing_rules + +``` rule-signature +unknown native.existing_rules() +``` + +Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by `existing_rule(name)`. + +Here, an *immutable dict-like object* means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. + +If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. + +## exports_files + +``` rule-signature +None native.exports_files(srcs, visibility=None, licenses=None) +``` + +Specifies a list of files belonging to this package that are exported to other packages. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="exports_files.srcs"><code>srcs</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The list of files to export.</td> +</tr> +<tr> +<td id="exports_files.visibility"><code>visibility</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; +default is <code>None</code><br /> +A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package.</td> +</tr> +<tr> +<td id="exports_files.licenses"><code>licenses</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; +default is <code>None</code><br /> +Licenses to be specified.</td> +</tr> +</tbody> +</table> + +## glob + +``` rule-signature +sequence native.glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound) +``` + +Glob returns a new, mutable, sorted list of every file in the current package that: + +- Matches at least one pattern in `include`. +- Does not match any of the patterns in `exclude` (default `[]`). + +If the `exclude_directories` argument is enabled (set to `1`), files of type directory will be omitted from the results (default `1`). + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="glob.include"><code>include</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +The list of glob patterns to include.</td> +</tr> +<tr> +<td id="glob.exclude"><code>exclude</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +The list of glob patterns to exclude.</td> +</tr> +<tr> +<td id="glob.exclude_directories"><code>exclude_directories</code></td> +<td><a href="../core/int.html" class="anchor">int</a>; +default is <code>1</code><br /> +A flag whether to exclude directories or not.</td> +</tr> +<tr> +<td id="glob.allow_empty"><code>allow_empty</code></td> +<td>default is <code>unbound</code><br /> +Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded).</td> +</tr> +</tbody> +</table> + +## module_name + +``` rule-signature +string native.module_name() +``` + +The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the `module.name` field seen in `module_ctx.modules`. +May return `None`. + +## module_version + +``` rule-signature +string native.module_version() +``` + +The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the `module.version` field seen in `module_ctx.modules`. +May return `None`. + +## package_default_visibility + +``` rule-signature +List native.package_default_visibility() +``` + +Returns the default visibility of the package being evaluated. This is the value of the `default_visibility` parameter of `package()`, extended to include the package itself. + +## package_group + +``` rule-signature +None native.package_group(*, name, packages=[], includes=[]) +``` + +This function defines a set of packages and assigns a label to the group. The label can be referenced in `visibility` attributes. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="package_group.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +The unique name for this rule.</td> +</tr> +<tr> +<td id="package_group.packages"><code>packages</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A complete enumeration of packages in this group.</td> +</tr> +<tr> +<td id="package_group.includes"><code>includes</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +Other package groups that are included in this one.</td> +</tr> +</tbody> +</table> + +## package_name + +``` rule-signature +string native.package_name() +``` + +The name of the package being evaluated, without the repository name. For example, in the BUILD file `some/package/BUILD`, its value will be `some/package`. If the BUILD file calls a function defined in a .bzl file, `package_name()` will match the caller BUILD file package. The value will always be an empty string for the root package. + +## package_relative_label + +``` rule-signature +Label native.package_relative_label(input) +``` + +Converts the input string into a [Label](../builtins/Label.html) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. + +This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. + +The result of this function is the same `Label` value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file. + +*Usage note:* The difference between this function and [Label()](../builtins/Label.html#Label) is that `Label()` uses the context of the package of the `.bzl` file that called it, not the package of the `BUILD` file. Use `Label()` when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use `package_relative_label()` when you need to normalize a label string supplied by the BUILD file to a `Label` object. (There is no way to convert a string to a `Label` in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="package_relative_label.input"><code>input</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; +required<br /> +The input label string or Label object. If a Label object is passed, it's returned as is.</td> +</tr> +</tbody> +</table> + +## repo_name + +``` rule-signature +string native.repo_name() +``` + +The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. + +## repository_name + +``` rule-signature +string native.repository_name() +``` + +**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` +**Deprecated.** Prefer to use [`repo_name`](#repo_name) instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise. + +The canonical name of the repository containing the package currently being evaluated, with a single at-sign (`@`) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza `local_repository(name='local', path=...)` it will be set to `@local`. In packages in the main repository, it will be set to `@`. + +## subpackages + +``` rule-signature +sequence native.subpackages(*, include, exclude=[], allow_empty=False) +``` + +Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel_skylib.subpackages module rather than calling this function directly. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="subpackages.include"><code>include</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +required<br /> +The list of glob patterns to include in subpackages scan.</td> +</tr> +<tr> +<td id="subpackages.exclude"><code>exclude</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +The list of glob patterns to exclude from subpackages scan.</td> +</tr> +<tr> +<td id="subpackages.allow_empty"><code>allow_empty</code></td> +<td><a href="../core/bool.html" class="anchor">bool</a>; +default is <code>False</code><br /> +Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case.</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/toplevel/platform_common.mdx b/rules/lib/toplevel/platform_common.mdx index 0fe55bc..54478bf 100644 --- a/rules/lib/toplevel/platform_common.mdx +++ b/rules/lib/toplevel/platform_common.mdx @@ -2,67 +2,59 @@ title: 'platform_common' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.platform_common">platform_common</h1> +# platform_common {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Functions for Starlark to interact with the platform APIs. -<h2>Members</h2> -<ul> - <li> - <a href="#ConstraintSettingInfo">ConstraintSettingInfo</a> - </li> - <li> - <a href="#ConstraintValueInfo">ConstraintValueInfo</a> - </li> - <li> - <a href="#PlatformInfo">PlatformInfo</a> - </li> - <li> - <a href="#TemplateVariableInfo">TemplateVariableInfo</a> - </li> - <li> - <a href="#ToolchainInfo">ToolchainInfo</a> - </li> - </ul> +## Members + +- [ConstraintSettingInfo](#ConstraintSettingInfo) +- [ConstraintValueInfo](#ConstraintValueInfo) +- [PlatformInfo](#PlatformInfo) +- [TemplateVariableInfo](#TemplateVariableInfo) +- [ToolchainInfo](#ToolchainInfo) + +## ConstraintSettingInfo + +``` rule-signature +Provider platform_common.ConstraintSettingInfo +``` - <h2 id="ConstraintSettingInfo">ConstraintSettingInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.ConstraintSettingInfo</pre></p> +The constructor/key for the [ConstraintSettingInfo](../providers/ConstraintSettingInfo.html) provider. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* - The constructor/key for the <a href='../providers/ConstraintSettingInfo.html'>ConstraintSettingInfo</a> provider.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> +## ConstraintValueInfo - <h2 id="ConstraintValueInfo">ConstraintValueInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.ConstraintValueInfo</pre></p> +``` rule-signature +Provider platform_common.ConstraintValueInfo +``` - The constructor/key for the <a href='../providers/ConstraintValueInfo.html'>ConstraintValueInfo</a> provider.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> +The constructor/key for the [ConstraintValueInfo](../providers/ConstraintValueInfo.html) provider. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* - <h2 id="PlatformInfo">PlatformInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.PlatformInfo</pre></p> +## PlatformInfo - The constructor/key for the <a href='../providers/PlatformInfo.html'>PlatformInfo</a> provider.<br/><i>Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with <code>--experimental_platforms_api</code></i> +``` rule-signature +Provider platform_common.PlatformInfo +``` - <h2 id="TemplateVariableInfo">TemplateVariableInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.TemplateVariableInfo</pre></p> +The constructor/key for the [PlatformInfo](../providers/PlatformInfo.html) provider. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* - The constructor/key for the <a href='../providers/TemplateVariableInfo.html'>TemplateVariableInfo</a> provider. +## TemplateVariableInfo - <h2 id="ToolchainInfo">ToolchainInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../builtins/Provider.html">Provider</a> platform_common.ToolchainInfo</pre></p> +``` rule-signature +Provider platform_common.TemplateVariableInfo +``` - The constructor/key for the <a href='../providers/ToolchainInfo.html'>ToolchainInfo</a> provider. +The constructor/key for the [TemplateVariableInfo](../providers/TemplateVariableInfo.html) provider. +## ToolchainInfo -</body> -</html> +``` rule-signature +Provider platform_common.ToolchainInfo +``` -<!-- {% endraw %} --> +The constructor/key for the [ToolchainInfo](../providers/ToolchainInfo.html) provider. diff --git a/rules/lib/toplevel/proto.mdx b/rules/lib/toplevel/proto.mdx index 8ff60a7..d293839 100644 --- a/rules/lib/toplevel/proto.mdx +++ b/rules/lib/toplevel/proto.mdx @@ -2,41 +2,38 @@ title: 'proto' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.proto">proto</h1> +# proto {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/packages/Proto.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} A module for protocol message processing. -<h2>Members</h2> -<ul> - <li> - <a href="#encode_text">encode_text</a> - </li> - </ul> +## Members + +- [encode_text](#encode_text) + +## encode_text - <h2 id="encode_text">encode_text</h2> - <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> proto.encode_text(x)</pre></p> +``` rule-signature +string proto.encode_text(x) +``` - Returns the struct argument's encoding as a text-format protocol message. +Returns the struct argument's encoding as a text-format protocol message. The data structure must be recursively composed of strings, ints, floats, or bools, or structs, sequences, and dicts of these types. -<p>A struct is converted to a message. Fields are emitted in name order. + +A struct is converted to a message. Fields are emitted in name order. Each struct field whose value is None is ignored. -<p>A sequence (such as a list or tuple) is converted to a repeated field. + +A sequence (such as a list or tuple) is converted to a repeated field. Its elements must not be sequences or dicts. -<p>A dict is converted to a repeated field of messages with fields named 'key' and 'value'. + +A dict is converted to a repeated field of messages with fields named 'key' and 'value'. Entries are emitted in iteration (insertion) order. The dict's keys must be strings or ints, and its values must not be sequences or dicts. -Examples:<br><pre class=language-python>proto.encode_text(struct(field=123)) +Examples: + +``` python +proto.encode_text(struct(field=123)) # field: 123 proto.encode_text(struct(field=True)) @@ -79,37 +76,23 @@ proto.encode_text(struct(foo={4: 3, 2: 1})) # key: 2 # value: 1 # } -</pre> - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="encode_text.x"> - <code>x</code> - </td> - <td> - structure; or NativeInfo; - required<br/> - - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +``` + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="encode_text.x"><code>x</code></td> +<td>structure; or NativeInfo; +required<br /> +</td> +</tr> +</tbody> +</table> diff --git a/rules/lib/toplevel/testing.mdx b/rules/lib/toplevel/testing.mdx index 17d4e68..a753964 100644 --- a/rules/lib/toplevel/testing.mdx +++ b/rules/lib/toplevel/testing.mdx @@ -2,165 +2,114 @@ title: 'testing' --- -<html devsite> -<head> - <meta name="project_path" value="/_project.yaml"> - <meta name="book_path" value="/_book.yaml"> -</head> -<body> - -<h1 class="page-title" id="modules.testing">testing</h1> +# testing {% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java" %} -{% include "_buttons.html" %} -<!-- {% raw %} --> - +{% include "\_buttons.html" %} Helper methods for Starlark to access testing infrastructure. -<h2>Members</h2> -<ul> - <li> - <a href="#analysis_test">analysis_test</a> - </li> - <li> - <a href="#ExecutionInfo">ExecutionInfo</a> - </li> - <li> - <a href="#TestEnvironment">TestEnvironment</a> - </li> - </ul> - - <h2 id="analysis_test">analysis_test</h2> - <p><pre class="rule-signature"><code>None</code> testing.analysis_test(name, implementation, attrs={}, fragments=[], toolchains=[], attr_values={})</pre></p> - - Creates a new analysis test target. <p>The number of transitive dependencies of the test are limited. The limit is controlled by <code>--analysis_testing_deps_limit</code> flag. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="analysis_test.name"> - <code>name</code> - </td> - <td> - <a class="anchor" href="../core/string.html">string</a>; - required<br/> - Name of the target. It should be a Starlark identifier, matching pattern '[A-Za-z_][A-Za-z0-9_]*'. - </td> - </tr> - <tr> - <td id="analysis_test.implementation"> - <code>implementation</code> - </td> - <td> - <a class="anchor" href="../core/function.html">function</a>; - required<br/> - The Starlark function implementing this analysis test. It must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. The function is called during the analysis phase. It can access the attributes declared by <code>attrs</code> and populated via <code>attr_values</code>. The implementation function may not register actions. Instead, it must register a pass/fail result via providing <a href='../providers/AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>. - </td> - </tr> - <tr> - <td id="analysis_test.attrs"> - <code>attrs</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - default is <code>{}</code><br/> - Dictionary declaring the attributes. See the <a href="../globals/bzl.html#rule">rule</a> call. Attributes are allowed to use configuration transitions defined using <a href="../globals/bzl.html#analysis_test_transition">analysis_test_transition</a>. - </td> - </tr> - <tr> - <td id="analysis_test.fragments"> - <code>fragments</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - List of configuration fragments that are available to the implementation of the analysis test. - </td> - </tr> - <tr> - <td id="analysis_test.toolchains"> - <code>toolchains</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a>; - default is <code>[]</code><br/> - The set of toolchains the test requires. See the <a href="../globals/bzl.html#rule">rule</a> call. - </td> - </tr> - <tr> - <td id="analysis_test.attr_values"> - <code>attr_values</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>{}</code><br/> - Dictionary of attribute values to pass to the implementation. - </td> - </tr> - </tbody> - </table> - - <h2 id="ExecutionInfo">ExecutionInfo</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/ExecutionInfo.html">ExecutionInfo</a> testing.ExecutionInfo</pre></p> - - <a href='../providers/ExecutionInfo.html'>testing.ExecutionInfo</a> provider key/constructor - - <h2 id="TestEnvironment">TestEnvironment</h2> - <p><pre class="rule-signature"><a class="anchor" href="../providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> testing.TestEnvironment(environment, inherited_environment=[])</pre></p> - - <b>Deprecated: Use RunEnvironmentInfo instead.</b> Creates a new test environment provider. Use this provider to specify extra environment variables to be made available during test execution. - <!-- hide-from-toc is a class used by DevSite for the public Bazel site - (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) --> - <h3 class="hide-from-toc">Parameters</h3> - <table class="table table-bordered table-condensed table-params"> - <colgroup> - <col class="col-param"> - <col class="param-description"> - </colgroup> - <thead> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td id="TestEnvironment.environment"> - <code>environment</code> - </td> - <td> - <a class="anchor" href="../core/dict.html">dict</a>; - required<br/> - A map of string keys and values that represent environment variables and their values. These will be made available during the test execution. - </td> - </tr> - <tr> - <td id="TestEnvironment.inherited_environment"> - <code>inherited_environment</code> - </td> - <td> - <a class="anchor" href="../core/list.html">sequence</a> of <a class="anchor" href="../core/string.html">string</a>s; - default is <code>[]</code><br/> - A sequence of names of environment variables. These variables are made available during the test execution with their current value taken from the shell environment. If a variable is contained in both <code>environment</code> and <code>inherited_environment</code>, the value inherited from the shell environment will take precedence if set. - </td> - </tr> - </tbody> - </table> - - -</body> -</html> - -<!-- {% endraw %} --> +## Members + +- [analysis_test](#analysis_test) +- [ExecutionInfo](#ExecutionInfo) +- [TestEnvironment](#TestEnvironment) + +## analysis_test + +``` rule-signature +None testing.analysis_test(name, implementation, attrs={}, fragments=[], toolchains=[], attr_values={}) +``` + +Creates a new analysis test target. + +The number of transitive dependencies of the test are limited. The limit is controlled by `--analysis_testing_deps_limit` flag. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="analysis_test.name"><code>name</code></td> +<td><a href="../core/string.html" class="anchor">string</a>; +required<br /> +Name of the target. It should be a Starlark identifier, matching pattern '[A-Za-z_][A-Za-z0-9_]*'.</td> +</tr> +<tr> +<td id="analysis_test.implementation"><code>implementation</code></td> +<td><a href="../core/function.html" class="anchor">function</a>; +required<br /> +The Starlark function implementing this analysis test. It must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. The function is called during the analysis phase. It can access the attributes declared by <code>attrs</code> and populated via <code>attr_values</code>. The implementation function may not register actions. Instead, it must register a pass/fail result via providing <a href="../providers/AnalysisTestResultInfo.html">AnalysisTestResultInfo</a>.</td> +</tr> +<tr> +<td id="analysis_test.attrs"><code>attrs</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +default is <code>{}</code><br /> +Dictionary declaring the attributes. See the <a href="../globals/bzl.html#rule">rule</a> call. Attributes are allowed to use configuration transitions defined using <a href="../globals/bzl.html#analysis_test_transition">analysis_test_transition</a>.</td> +</tr> +<tr> +<td id="analysis_test.fragments"><code>fragments</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +List of configuration fragments that are available to the implementation of the analysis test.</td> +</tr> +<tr> +<td id="analysis_test.toolchains"><code>toolchains</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a>; +default is <code>[]</code><br /> +The set of toolchains the test requires. See the <a href="../globals/bzl.html#rule">rule</a> call.</td> +</tr> +<tr> +<td id="analysis_test.attr_values"><code>attr_values</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>{}</code><br /> +Dictionary of attribute values to pass to the implementation.</td> +</tr> +</tbody> +</table> + +## ExecutionInfo + +``` rule-signature +ExecutionInfo testing.ExecutionInfo +``` + +[testing.ExecutionInfo](../providers/ExecutionInfo.html) provider key/constructor + +## TestEnvironment + +``` rule-signature +RunEnvironmentInfo testing.TestEnvironment(environment, inherited_environment=[]) +``` + +**Deprecated: Use RunEnvironmentInfo instead.** Creates a new test environment provider. Use this provider to specify extra environment variables to be made available during test execution. + +### Parameters + +<table class="table table-bordered table-condensed table-params"> +<thead> +<tr> +<th>Parameter</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td id="TestEnvironment.environment"><code>environment</code></td> +<td><a href="../core/dict.html" class="anchor">dict</a>; +required<br /> +A map of string keys and values that represent environment variables and their values. These will be made available during the test execution.</td> +</tr> +<tr> +<td id="TestEnvironment.inherited_environment"><code>inherited_environment</code></td> +<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; +default is <code>[]</code><br /> +A sequence of names of environment variables. These variables are made available during the test execution with their current value taken from the shell environment. If a variable is contained in both <code>environment</code> and <code>inherited_environment</code>, the value inherited from the shell environment will take precedence if set.</td> +</tr> +</tbody> +</table> From 63634cf46cb01f6b3c3623bf842b4eb254c31113 Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Thu, 9 Oct 2025 21:04:00 -0700 Subject: [PATCH 06/14] add reference mdx files --- convert_reference_docs.py | 214 + reference/be/be-nav.mdx | 56 +- reference/be/c-cpp.mdx | 1999 +- reference/be/common-definitions.mdx | 701 +- reference/be/extra-actions.mdx | 200 +- reference/be/functions.mdx | 559 +- reference/be/general.mdx | 793 +- reference/be/java.mdx | 1824 +- reference/be/make-variables.mdx | 143 +- reference/be/objective-c.mdx | 382 +- reference/be/overview.mdx | 202 +- reference/be/platforms-and-toolchains.mdx | 362 +- reference/be/protocol-buffer.mdx | 515 +- reference/be/python.mdx | 932 +- reference/be/shell.mdx | 187 +- reference/command-line-reference.mdx | 16292 ++++++++-------- rules/lib/builtins.mdx | 123 +- rules/lib/builtins/Action.mdx | 47 +- rules/lib/builtins/Args.mdx | 326 +- rules/lib/builtins/Aspect.mdx | 5 +- rules/lib/builtins/Attribute.mdx | 5 +- rules/lib/builtins/BuildSetting.mdx | 5 +- rules/lib/builtins/CcCompilationOutputs.mdx | 15 +- rules/lib/builtins/CcLinkingOutputs.mdx | 15 +- rules/lib/builtins/CompilationContext.mdx | 81 +- rules/lib/builtins/DirectoryExpander.mdx | 26 +- rules/lib/builtins/DottedVersion.mdx | 30 +- rules/lib/builtins/ExecGroupCollection.mdx | 5 +- rules/lib/builtins/ExecGroupContext.mdx | 9 +- rules/lib/builtins/ExecTransitionFactory.mdx | 5 +- rules/lib/builtins/ExpandedDirectory.mdx | 13 +- rules/lib/builtins/FeatureConfiguration.mdx | 5 +- rules/lib/builtins/File.mdx | 67 +- rules/lib/builtins/Label.mdx | 136 +- rules/lib/builtins/LateBoundDefault.mdx | 5 +- rules/lib/builtins/LibraryToLink.mdx | 69 +- rules/lib/builtins/License.mdx | 5 +- rules/lib/builtins/LinkerInput.mdx | 27 +- rules/lib/builtins/LinkingContext.mdx | 11 +- rules/lib/builtins/Provider.mdx | 14 +- rules/lib/builtins/Subrule.mdx | 5 +- rules/lib/builtins/SymlinkEntry.mdx | 15 +- rules/lib/builtins/Target.mdx | 15 +- rules/lib/builtins/TemplateDict.mdx | 102 +- rules/lib/builtins/ToolchainContext.mdx | 5 +- rules/lib/builtins/actions.mdx | 747 +- rules/lib/builtins/apple_platform.mdx | 48 +- rules/lib/builtins/bazel_module.mdx | 23 +- rules/lib/builtins/bazel_module_tags.mdx | 5 +- rules/lib/builtins/configuration.mdx | 43 +- rules/lib/builtins/ctx.mdx | 468 +- rules/lib/builtins/depset.mdx | 22 +- rules/lib/builtins/exec_result.mdx | 21 +- rules/lib/builtins/extension_metadata.mdx | 5 +- rules/lib/builtins/fragments.mdx | 5 +- .../builtins/java_annotation_processing.mdx | 45 +- rules/lib/builtins/macro.mdx | 5 +- rules/lib/builtins/mapped_root.mdx | 9 +- rules/lib/builtins/module_ctx.mdx | 622 +- rules/lib/builtins/path.mdx | 79 +- rules/lib/builtins/propagation_ctx.mdx | 13 +- rules/lib/builtins/repo_metadata.mdx | 5 +- rules/lib/builtins/repository_ctx.mdx | 796 +- rules/lib/builtins/repository_os.mdx | 17 +- rules/lib/builtins/repository_rule.mdx | 5 +- rules/lib/builtins/root.mdx | 9 +- rules/lib/builtins/rule.mdx | 5 +- rules/lib/builtins/rule_attributes.mdx | 57 +- rules/lib/builtins/runfiles.mdx | 83 +- rules/lib/builtins/struct.mdx | 27 +- rules/lib/builtins/subrule_ctx.mdx | 21 +- rules/lib/builtins/tag_class.mdx | 5 +- rules/lib/builtins/template_ctx.mdx | 104 +- rules/lib/builtins/toolchain_type.mdx | 15 +- rules/lib/builtins/transition.mdx | 48 +- rules/lib/builtins/wasm_exec_result.mdx | 21 +- rules/lib/builtins/wasm_module.mdx | 9 +- rules/lib/core.mdx | 27 +- rules/lib/core/bool.mdx | 5 +- rules/lib/core/builtin_function_or_method.mdx | 5 +- rules/lib/core/dict.mdx | 192 +- rules/lib/core/float.mdx | 5 +- rules/lib/core/function.mdx | 5 +- rules/lib/core/int.mdx | 7 +- rules/lib/core/json.mdx | 148 +- rules/lib/core/list.mdx | 170 +- rules/lib/core/range.mdx | 11 +- rules/lib/core/set.mdx | 415 +- rules/lib/core/string.mdx | 672 +- rules/lib/core/tuple.mdx | 13 +- rules/lib/fragments.mdx | 29 +- rules/lib/fragments/apple.mdx | 48 +- rules/lib/fragments/bazel_android.mdx | 12 +- rules/lib/fragments/bazel_py.mdx | 20 +- rules/lib/fragments/coverage.mdx | 25 +- rules/lib/fragments/cpp.mdx | 73 +- rules/lib/fragments/j2objc.mdx | 11 +- rules/lib/fragments/java.mdx | 105 +- rules/lib/fragments/objc.mdx | 69 +- rules/lib/fragments/platform.mdx | 15 +- rules/lib/fragments/proto.mdx | 5 +- rules/lib/fragments/py.mdx | 53 +- rules/lib/globals.mdx | 15 +- rules/lib/globals/all.mdx | 787 +- rules/lib/globals/build.mdx | 394 +- rules/lib/globals/bzl.mdx | 1157 +- rules/lib/globals/module.mdx | 706 +- rules/lib/globals/repo.mdx | 50 +- rules/lib/globals/vendor.mdx | 49 +- rules/lib/overview.mdx | 272 +- rules/lib/providers.mdx | 59 +- .../lib/providers/AnalysisTestResultInfo.mdx | 43 +- rules/lib/providers/CcInfo.mdx | 54 +- rules/lib/providers/CcToolchainConfigInfo.mdx | 5 +- rules/lib/providers/CcToolchainInfo.mdx | 187 +- rules/lib/providers/ConstraintCollection.mdx | 7 +- rules/lib/providers/ConstraintSettingInfo.mdx | 13 +- rules/lib/providers/ConstraintValueInfo.mdx | 7 +- rules/lib/providers/DebugPackageInfo.mdx | 79 +- rules/lib/providers/DefaultInfo.mdx | 88 +- rules/lib/providers/ExecutionInfo.mdx | 47 +- rules/lib/providers/FeatureFlagInfo.mdx | 40 +- rules/lib/providers/FilesToRunProvider.mdx | 21 +- .../IncompatiblePlatformProvider.mdx | 5 +- rules/lib/providers/InstrumentedFilesInfo.mdx | 19 +- rules/lib/providers/JavaRuntimeInfo.mdx | 75 +- rules/lib/providers/JavaToolchainInfo.mdx | 63 +- rules/lib/providers/MaterializedDepsInfo.mdx | 9 +- rules/lib/providers/ObjcProvider.mdx | 45 +- rules/lib/providers/OutputGroupInfo.mdx | 33 +- .../providers/PackageSpecificationInfo.mdx | 26 +- rules/lib/providers/PlatformInfo.mdx | 7 +- rules/lib/providers/RunEnvironmentInfo.mdx | 15 +- rules/lib/providers/TemplateVariableInfo.mdx | 11 +- rules/lib/providers/ToolchainInfo.mdx | 5 +- rules/lib/providers/ToolchainTypeInfo.mdx | 13 +- rules/lib/providers/file_provider.mdx | 5 +- rules/lib/providers/java_compilation_info.mdx | 31 +- rules/lib/providers/java_output_jars.mdx | 27 +- rules/lib/toplevel.mdx | 25 +- rules/lib/toplevel/apple_common.mdx | 154 +- rules/lib/toplevel/attr.mdx | 967 +- rules/lib/toplevel/cc_common.mdx | 1518 +- rules/lib/toplevel/config.mdx | 186 +- rules/lib/toplevel/config_common.mdx | 41 +- rules/lib/toplevel/coverage_common.mdx | 65 +- rules/lib/toplevel/java_common.mdx | 402 +- rules/lib/toplevel/native.mdx | 293 +- rules/lib/toplevel/platform_common.mdx | 33 +- rules/lib/toplevel/proto.mdx | 60 +- rules/lib/toplevel/testing.mdx | 101 +- 151 files changed, 13997 insertions(+), 26396 deletions(-) create mode 100644 convert_reference_docs.py diff --git a/convert_reference_docs.py b/convert_reference_docs.py new file mode 100644 index 0000000..e94fad9 --- /dev/null +++ b/convert_reference_docs.py @@ -0,0 +1,214 @@ +#!/usr/bin/env python3 +import sys +import zipfile +import shutil +import re +from pathlib import Path +import markdownify + +def strip_devsite_templates(html_text: str) -> str: + """Remove DevSite template tags `{% … %}` and `{{ … }}` (multiline).""" + html_text = re.sub(r"\{\%.*?\%\}", "", html_text, flags=re.DOTALL) + html_text = re.sub(r"\{\{.*?\}\}", "", html_text) + return html_text + +def html_to_markdown(html_text: str) -> str: + """Convert HTML to Markdown (approximate).""" + return markdownify.markdownify(html_text, heading_style="ATX") + +def sanitize_for_mdx(md_text: str) -> str: + """ + Sanitize Markdown to MDX-safe: + - Drop first heading (to avoid duplicate title) + - Escape bad `{…}` expressions + - Convert `<https://…>` to Markdown links + - Rewrite .html → .mdx + - Fix leading slash links + - Strip styles, normalize IDs + - Escape leftover tags / braces + - Patch problematic sequences like `)><code>…()` in anchors + """ + out_lines = [] + seen_ids = {} + skip_first_heading = True + + for ln in md_text.splitlines(): + # Skip first top-level heading (if any) + if skip_first_heading and re.match(r"^#\s+.+", ln): + skip_first_heading = False + continue + + # Remove leftover template constructs + if "{%" in ln: + ln = re.sub(r"\{\%.*?\%\}", "", ln) + if "{{" in ln: + ln = re.sub(r"\{\{.*?\}\}", "", ln) + + # **FIX: Clean up broken markdown link syntax with embedded HTML** + # Pattern: [text](url>junk..., more text](final-url) + # This happens when anchor tags are nested or malformed in original HTML + # Strategy: If a markdown link URL contains '>' followed by junk and then another '](', + # remove everything from '>' to the next '](' + + # First pass: Remove complex broken link portions with multiple issues + ln = re.sub( + r'\]\(([^)>]+)>[^\]]*\]\(', + r'](\1](', + ln + ) + + # Second pass: Clean up any remaining unescaped HTML tags within markdown links + # This handles cases where <a>, <code>, etc. appear inside ](...) + def fix_markdown_link_html(match): + url = match.group(1) + # If URL contains unescaped < or HTML-like content, truncate at first > + if '>' in url and '<' in url: + url = url.split('>')[0] + # Escape any remaining angle brackets + url = url.replace('<', '\\<').replace('>', '\\>') + return '](' + url + ')' + + ln = re.sub(r'\]\(([^)]+)\)', fix_markdown_link_html, ln) + + # **FIX: Escape problematic HTML sequences EARLY** + # Pattern 1: stuff>\<code\>stuff()\</code\>\</a\>, <a href= + ln = re.sub( + r'>\\\<code\\\>([^<]+)\\\</code\\\>\\\</a\\\>,\s*\<a\s+href=', + lambda m: r'>`' + m.group(1) + r'()`</a>, <a href=', + ln + ) + + # Pattern 2: Any remaining >\<code\> patterns + ln = re.sub(r'>\\\<code\\\>', r'>`<code>', ln) + ln = re.sub(r'\\\</code\\\>\\\</a\\\>', r'</code>`</a>', ln) + + # Pattern 3: Bare href= without quotes (from malformed links) + ln = re.sub(r'<a\s+href=\)', r'<a href="#">', ln) + ln = re.sub(r'href=\s*\)', r'href="#">', ln) + + # Escape `{…}` with colon inside + ln = re.sub( + r"\{([^}]*?:[^}]*)\}", + lambda m: r"\{" + m.group(1) + r"\}", + ln, + ) + + # Escape unescaped `{` or `}` + ln = re.sub(r"(?<!\\)\{", r"\{", ln) + ln = re.sub(r"(?<!\\)\}", r"\}", ln) + + # Rewrite .html links to .mdx + ln = re.sub(r"\(([^)]+)\.html\)", r"(\1.mdx)", ln) + ln = re.sub(r'href="([^"]+)\.html"', r'href="\1.mdx"', ln) + + # Convert raw angle-bracket URLs into Markdown links + ln = re.sub(r"<(https?://[^>]+)>", r"[\1](\1)", ln) + + # **FIX: Escape comparison operators that look like HTML tags** + # Replace <= and >= with HTML entities or escaped versions + # Do this BEFORE other tag escaping to avoid confusion + ln = re.sub(r'<=', r'<=', ln) + ln = re.sub(r'>=', r'>=', ln) + + # **FIX: Escape #include <header.h> patterns** + # Pattern: #include <path/to/file.h> where the angle brackets look like HTML + ln = re.sub(r'#include\s+<([^>]+)>', r'#include <\1>', ln) + + # **FIX: Handle escaped tags more carefully** + # Only escape tags that aren't already in code blocks or properly formed + # Skip escaping if we're in a code context + if not ('`' in ln and ln.count('`') % 2 == 0): + ln = re.sub(r"<([^ >]+)>", r"\<\1\>", ln) + + # Fix leading slash links: [text](/path) → relative + ln = re.sub(r"\[([^\]]+)\]\(/([^)]+)\)", r"[\1](./\2)", ln) + ln = re.sub(r'href="/([^"]+)"', r'href="./\1"', ln) + + # Strip inline style attributes + ln = re.sub(r'style="[^"]*"', "", ln) + + # Normalize id="section-foo" + ln = re.sub(r'id="section-([A-Za-z0-9_-]+)"', r'id="\1"', ln) + + # Escape known custom tags + ln = re.sub(r"<(workspace|symlink_path|attribute_name)([^>]*)>", r"\<\1\2\>", ln) + ln = re.sub(r"</(workspace|symlink_path|attribute_name)>", r"\</\1\>", ln) + + # **FIX: More careful handling of </code> - only escape if not in inline code** + # Count backticks to see if we're in code context + backtick_count = ln.count('`') + if backtick_count % 2 == 1: # Odd number means we're inside code + pass # Don't escape + else: + ln = ln.replace("</code>", r"\</code>") + + # **FIX: Patch problematic `)><code>` sequences inside anchor context** + ln = re.sub( + r"\)\>\<code\>([^<]+)\</code\>", + lambda m: r") `<code>" + m.group(1) + r"</code>`", + ln + ) + # Also patch anchor boundary syntax + ln = re.sub(r"</a>,\s*<a href=", r"\</a\>, \<a href=", ln) + + # **FIX: Clean up malformed href attributes** + # Pattern: href=)/some/path - should be removed or fixed + ln = re.sub(r'href=\)/[^"\s)]+', r'href="#"', ln) + + # Deduplicate heading IDs + m = re.match(r'^(#+)\s*(.*)\s*\{#([A-Za-z0-9_-]+)\}', ln) + if m: + hashes, text, hid = m.groups() + cnt = seen_ids.get(hid, 0) + if cnt > 0: + newhid = f"{hid}-{cnt+1}" + ln = f"{hashes} {text} {{#{newhid}}}" + seen_ids[hid] = cnt + 1 + + out_lines.append(ln) + + return "\n".join(out_lines) + +def make_frontmatter(title: str) -> str: + safe = title.replace("'", "\\'") + return f"---\ntitle: '{safe}'\n---\n\n" + +def convert_html_file(html_path: Path, mdx_path: Path) -> None: + html_text = html_path.read_text(encoding="utf-8", errors="ignore") + cleaned = strip_devsite_templates(html_text) + md = html_to_markdown(cleaned) + sanitized = sanitize_for_mdx(md) + title = html_path.stem + front = make_frontmatter(title) + mdx_path.parent.mkdir(parents=True, exist_ok=True) + mdx_path.write_text(front + sanitized, encoding="utf-8") + print(f"Wrote {mdx_path}") + +def process_zip(zip_path: Path) -> None: + tmp = Path("_tmp_unzip_convert") + if tmp.exists(): + shutil.rmtree(tmp) + tmp.mkdir() + with zipfile.ZipFile(zip_path, "r") as z: + z.extractall(tmp) + + for html_path in tmp.rglob("*.html"): + rel = html_path.relative_to(tmp) + mdx_out = Path(rel).with_suffix(".mdx") + convert_html_file(html_path, mdx_out) + + shutil.rmtree(tmp) + +def main(): + if len(sys.argv) != 2: + print("Usage: python3 converter.py <reference-docs.zip>") + sys.exit(1) + zipf = Path(sys.argv[1]) + if not zipf.is_file(): + print(f"Error: {zipf} not found") + sys.exit(1) + process_zip(zipf) + print("Conversion done.") + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/reference/be/be-nav.mdx b/reference/be/be-nav.mdx index c19b399..4a59290 100644 --- a/reference/be/be-nav.mdx +++ b/reference/be/be-nav.mdx @@ -4,31 +4,31 @@ title: 'be-nav' \*\*Build Encyclopedia\*\* -- [Overview](/reference/be/overview.html) -- <a href="#be-menu" data-toggle="collapse" aria-expanded="false" aria-controls="be-menu">Concepts <span class="caret"></span></a> - - [Common Definitions](/reference/be/common-definitions.html) - - ["Make" variables](/reference/be/make-variables.html) -- <a href="#be-rules" data-toggle="collapse" aria-expanded="false" aria-controls="be-rules">Rules <span class="caret"></span></a> - - [Functions](/reference/be/functions.html) - - [C / C++](/reference/be/c-cpp.html) - - [Java](/reference/be/java.html) - - [Objective-C](/reference/be/objective-c.html) - - [Protocol Buffer](/reference/be/protocol-buffer.html) - - [Python](/reference/be/python.html) - - [Shell](/reference/be/shell.html) - - [Extra Actions](/reference/be/extra-actions.html) - - [General](/reference/be/general.html) - - [Platforms and Toolchains](/reference/be/platforms-and-toolchains.html) - - <a href="https://github.com/bazelbuild/rules_appengine" target="_blank" rel="noopener">AppEngine</a> - - <a href="https://github.com/bazelbuild/rules_apple" target="_blank" rel="noopener">Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)</a> - - <a href="https://github.com/bazelbuild/rules_dotnet" target="_blank" rel="noopener">C#</a> - - <a href="https://github.com/bazelbuild/rules_d" target="_blank" rel="noopener">D</a> - - <a href="https://github.com/bazelbuild/rules_docker" target="_blank" rel="noopener">Docker</a> - - <a href="https://github.com/bazelbuild/rules_groovy" target="_blank" rel="noopener">Groovy</a> - - <a href="https://github.com/bazelbuild/rules_go" target="_blank" rel="noopener">Go</a> - - <a href="https://github.com/bazelbuild/rules_closure" target="_blank" rel="noopener">JavaScript (Closure)</a> - - <a href="https://github.com/bazelbuild/rules_jsonnet" target="_blank" rel="noopener">Jsonnet</a> - - [Packaging](/reference/be/pkg.html) - - <a href="https://github.com/bazelbuild/rules_rust" target="_blank" rel="noopener">Rust</a> - - <a href="https://github.com/bazelbuild/rules_sass" target="_blank" rel="noopener">Sass</a> - - <a href="https://github.com/bazelbuild/rules_scala" target="_blank" rel="noopener">Scala</a> +* [Overview](./reference/be/overview.mdx) +* [Concepts](#be-menu) + + [Common Definitions](./reference/be/common-definitions.mdx) + + ["Make" variables](./reference/be/make-variables.mdx) +* [Rules](#be-rules) + + [Functions](./reference/be/functions.mdx) + + [C / C++](./reference/be/c-cpp.mdx) + + [Java](./reference/be/java.mdx) + + [Objective-C](./reference/be/objective-c.mdx) + + [Protocol Buffer](./reference/be/protocol-buffer.mdx) + + [Python](./reference/be/python.mdx) + + [Shell](./reference/be/shell.mdx) + + [Extra Actions](./reference/be/extra-actions.mdx) + + [General](./reference/be/general.mdx) + + [Platforms and Toolchains](./reference/be/platforms-and-toolchains.mdx) + + [AppEngine](https://github.com/bazelbuild/rules_appengine) + + [Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)](https://github.com/bazelbuild/rules_apple) + + [C#](https://github.com/bazelbuild/rules_dotnet) + + [D](https://github.com/bazelbuild/rules_d) + + [Docker](https://github.com/bazelbuild/rules_docker) + + [Groovy](https://github.com/bazelbuild/rules_groovy) + + [Go](https://github.com/bazelbuild/rules_go) + + [JavaScript (Closure)](https://github.com/bazelbuild/rules_closure) + + [Jsonnet](https://github.com/bazelbuild/rules_jsonnet) + + [Packaging](./reference/be/pkg.mdx) + + [Rust](https://github.com/bazelbuild/rules_rust) + + [Sass](https://github.com/bazelbuild/rules_sass) + + [Scala](https://github.com/bazelbuild/rules_scala) \ No newline at end of file diff --git a/reference/be/c-cpp.mdx b/reference/be/c-cpp.mdx index 9451859..c8e11fd 100644 --- a/reference/be/c-cpp.mdx +++ b/reference/be/c-cpp.mdx @@ -2,30 +2,26 @@ title: 'c-cpp' --- -# C / C++ Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} ## Rules -- [cc_binary](#cc_binary) -- [cc_import](#cc_import) -- [cc_library](#cc_library) -- [cc_shared_library](#cc_shared_library) -- [cc_static_library](#cc_static_library) -- [cc_test](#cc_test) -- [cc_toolchain](#cc_toolchain) -- [fdo_prefetch_hints](#fdo_prefetch_hints) -- [fdo_profile](#fdo_profile) -- [memprof_profile](#memprof_profile) -- [propeller_optimize](#propeller_optimize) +* [cc\_binary](#cc_binary) +* [cc\_import](#cc_import) +* [cc\_library](#cc_library) +* [cc\_shared\_library](#cc_shared_library) +* [cc\_static\_library](#cc_static_library) +* [cc\_test](#cc_test) +* [cc\_toolchain](#cc_toolchain) +* [fdo\_prefetch\_hints](#fdo_prefetch_hints) +* [fdo\_profile](#fdo_profile) +* [memprof\_profile](#memprof_profile) +* [propeller\_optimize](#propeller_optimize) -## cc_binary +## cc\_binary -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_binary.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_binary.bzl) -``` rule-signature +``` cc_binary(name, deps, srcs, data, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local_defines, malloc, module_interfaces, nocopts, output_licenses, package_metadata, reexport_deps, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file) ``` @@ -39,371 +35,58 @@ be `main`. #### Implicit output targets -- `name``.stripped` (only built if explicitly requested): A stripped +* `name.stripped` (only built if explicitly requested): A stripped version of the binary. `strip -g` is run on the binary to remove debug symbols. Additional strip options can be provided on the command line using `--stripopt=-foo`. -- `name``.dwp` (only built if explicitly requested): If +* `name.dwp` (only built if explicitly requested): If [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug information package file suitable for debugging remotely deployed binaries. Else: an empty file. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="cc_binary.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="cc_binary.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries to be linked in to the binary target. -<p>These can be <code>cc_library</code> or <code>objc_library</code> -targets.</p> -It is also allowed to -put linker scripts (.lds) into deps, and reference them in -<a href="#cc_binary.linkopts">linkopts</a>.</td> -</tr> -<tr> -<td id="cc_binary.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of C and C++ files that are processed to create the library target. -These are C/C++ source and header files, either non-generated (normal source -code) or generated. -<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will -be compiled. These might be generated files: if a named file is in -the <code>outs</code> of some other rule, this <code>cc_library</code> -will automatically depend on that other rule.</p> -<p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using -the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler.</p> -<p>A <code>.h</code> file will not be compiled, but will be available for -inclusion by sources in this rule. Both <code>.cc</code> and -<code>.h</code> files can directly include headers listed in -these <code>srcs</code> or in the <code>hdrs</code> of this rule or any -rule listed in the <code>deps</code> argument.</p> -<p>All <code>#include</code>d files must be mentioned in the -<code>hdrs</code> attribute of this or referenced <code>cc_library</code> -rules, or they should be listed in <code>srcs</code> if they are private -to this library. See <a href="#hdrs">"Header inclusion checking"</a> for -a more detailed description.</p> -<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are -pre-compiled files. Your library might have these as -<code>srcs</code> if it uses third-party code for which we don't -have source code.</p> -<p>If the <code>srcs</code> attribute includes the label of another rule, -<code>cc_library</code> will use the output files of that rule as source files to -compile. This is useful for one-off generation of source code (for more than occasional -use, it's better to implement a Starlark rule class and use the <code>cc_common</code> -API)</p> -<p>Permitted <code>srcs</code> file types:</p> -<ul> -<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, -<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> -<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, -<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> -<li>Assembler with C preprocessor: <code>.S</code></li> -<li>Archive: <code>.a</code>, <code>.pic.a</code></li> -<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> -<li>Shared library, versioned or unversioned: <code>.so</code>, -<code>.so.</code><em><code>version</code></em></li> -<li>Object file: <code>.o</code>, <code>.pic.o</code></li> -</ul> -<p>... and any rules that produce those files (e.g. <code>cc_embed_data</code>). -Different extensions denote different programming languages in -accordance with gcc convention.</p></td> -</tr> -<tr> -<td id="cc_binary.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this library at runtime. -See general comments about <code>data</code> -at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. -<p>If a <code>data</code> is the name of a generated file, then this -<code>cc_library</code> rule automatically depends on the generating -rule.</p> -<p>If a <code>data</code> is a rule name, then this -<code>cc_library</code> rule automatically depends on that rule, -and that rule's <code>outs</code> are automatically added to -this <code>cc_library</code>'s data files.</p> -<p>Your C++ code can access these data files like so:</p> -<pre class="lang-starlark"><code> - const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file");</code></pre></td> -</tr> -<tr> -<td id="cc_binary.additional_linker_inputs"><code>additional_linker_inputs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Pass these files to the C++ linker command. -<p>For example, compiled Windows .res files can be provided here to be embedded in -the binary target.</p></td> -</tr> -<tr> -<td id="cc_binary.conlyopts"><code>conlyopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> -</tr> -<tr> -<td id="cc_binary.copts"><code>copts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C/C++ compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -<p>Each string in this attribute is added in the given order to <code>COPTS</code> before -compiling the binary target. The flags take effect only for compiling this target, not -its dependencies, so be careful about header files included elsewhere. -All paths should be relative to the workspace, not to the current package. -This attribute should not be needed outside of <code>third_party</code>.</p> -<p>If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> -<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings -that consist of a single "Make" variable.</p></td> -</tr> -<tr> -<td id="cc_binary.cxxopts"><code>cxxopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C++ compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> -</tr> -<tr> -<td id="cc_binary.defines"><code>defines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of defines to add to the compile line. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -Each string, which must consist of a single Bourne shell token, -is prepended with <code>-D</code> and added to the compile command line to this target, -as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects. When in doubt, add define values to -<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.</td> -</tr> -<tr> -<td id="cc_binary.distribs"><code>distribs</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_binary.dynamic_deps"><code>dynamic_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -These are other <code>cc_shared_library</code> dependencies the current target depends on. -<p>The <code>cc_shared_library</code> implementation will use the list of -<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the -current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in -the transitive <code>deps</code> should not be linked in because they are already provided -by a different <code>cc_shared_library</code>.</p></td> -</tr> -<tr> -<td id="cc_binary.hdrs_check"><code>hdrs_check</code></td> -<td><p>String; default is <code>""</code></p> -Deprecated, no-op.</td> -</tr> -<tr> -<td id="cc_binary.includes"><code>includes</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of include dirs to be added to the compile line. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. -Each string is prepended with the package path and passed to the C++ toolchain for -expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system -with typical feature definitions will produce -<code>-isystem path_to_package/include_entry</code>. -This should only be used for third-party libraries that -do not conform to the Google style of writing #include statements. -Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. -<p>The added <code>include</code> paths will include generated files as well as -files in the source tree.</p></td> -</tr> -<tr> -<td id="cc_binary.link_extra_lib"><code>link_extra_lib</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p> -Control linking of extra libraries. -<p>By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>, -which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>. -Without setting the flag, this library is empty by default. Setting the label flag -allows linking optional dependencies, such as overrides for weak symbols, interceptors -for shared library functions, or special runtime libraries (for malloc replacements, -prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to -<code>None</code> disables this behaviour.</p></td> -</tr> -<tr> -<td id="cc_binary.linkopts"><code>linkopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these flags to the C++ linker command. -Subject to <a href="make-variables.html">"Make" variable</a> substitution, -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a> and -<a href="common-definitions.html#label-expansion">label expansion</a>. -Each string in this attribute is added to <code>LINKOPTS</code> before -linking the binary target. -<p>Each element of this list that does not start with <code>$</code> or <code>-</code> is -assumed to be the label of a target in <code>deps</code>. The -list of files generated by that target is appended to the linker -options. An error is reported if the label is invalid, or is -not declared in <code>deps</code>.</p></td> -</tr> -<tr> -<td id="cc_binary.linkshared"><code>linkshared</code></td> -<td><p>Boolean; default is <code>False</code></p> -Create a shared library. -To enable this attribute, include <code>linkshared=True</code> in your rule. By default -this option is off. -<p>The presence of this flag means that linking occurs with the <code>-shared</code> flag -to <code>gcc</code>, and the resulting shared library is suitable for loading into for -example a Java program. However, for build purposes it will never be linked into the -dependent binary, as it is assumed that shared libraries built with a -<a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so -it should not be considered a substitute for the <a href="#cc_library">cc_library</a> -rule. For sake of scalability we recommend avoiding this approach altogether and -simply letting <code>java_library</code> depend on <code>cc_library</code> rules -instead.</p> -<p>If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>, -you get a single completely self-contained unit. If you specify both -<code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly -self-contained unit.</p></td> -</tr> -<tr> -<td id="cc_binary.linkstatic"><code>linkstatic</code></td> -<td><p>Boolean; default is <code>True</code></p> -For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and -<a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static -mode. For <code>cc_library.link_static</code>: see below. -<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> -<p>If enabled and this is a binary or test, this option tells the build tool to link in -<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. -System libraries such as libc (but <em>not</em> the C/C++ runtime libraries, -see below) are still linked dynamically, as are libraries for which -there is no static library. So the resulting executable will still be dynamically -linked, hence only <em>mostly</em> static.</p> -<p>There are really three different ways to link an executable:</p> -<ul> -<li>STATIC with fully_static_link feature, in which everything is linked statically; -e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br /> -This mode is enabled by specifying <code>fully_static_link</code> in the -<a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> -<li>STATIC, in which all user libraries are linked statically (if a static -version is available), but where system libraries (excluding C/C++ runtime libraries) -are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br /> -This mode is enabled by specifying <code>linkstatic=True</code>.</li> -<li>DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is -available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br /> -This mode is enabled by specifying <code>linkstatic=False</code>.</li> -</ul> -<p>If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in -<code>features</code> is used outside of <code>//third_party</code> -please include a comment near the rule to explain why.</p> -<p>The <code>linkstatic</code> attribute has a different meaning if used on a -<a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. -For a C++ library, <code>linkstatic=True</code> indicates that only -static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does -not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries.</p> -<p>There should be very little code built with <code>linkstatic=False</code> in production. -If <code>linkstatic=False</code>, then the build tool will create symlinks to -depended-upon shared libraries in the <code>*.runfiles</code> area.</p></td> -</tr> -<tr> -<td id="cc_binary.local_defines"><code>local_defines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of defines to add to the compile line. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -Each string, which must consist of a single Bourne shell token, -is prepended with <code>-D</code> and added to the compile command line for this target, -but not to its dependents.</td> -</tr> -<tr> -<td id="cc_binary.malloc"><code>malloc</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p> -Override the default dependency on malloc. -<p>By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>, -which is an empty library so the binary ends up using libc malloc. -This label must refer to a <code>cc_library</code>. If compilation is for a non-C++ -rule, this option has no effect. The value of this attribute is ignored if -<code>linkshared=True</code> is specified.</p></td> -</tr> -<tr> -<td id="cc_binary.module_interfaces"><code>module_interfaces</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files are regarded as C++20 Modules Interface. -<p>C++ Standard has no restriction about module interface file extension</p> -<ul> -<li>Clang use cppm</li> -<li>GCC can use any source file extension</li> -<li>MSVC use ixx</li> -</ul> -<p>The use is guarded by the flag -<code>--experimental_cpp_modules</code>.</p></td> -</tr> -<tr> -<td id="cc_binary.nocopts"><code>nocopts</code></td> -<td><p>String; default is <code>""</code></p> -Remove matching options from the C++ compilation command. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. -The value of this attribute is interpreted as a regular expression. -Any preexisting <code>COPTS</code> that match this regular expression -(including values explicitly specified in the rule's <a href="#cc_binary.copts">copts</a> attribute) -will be removed from <code>COPTS</code> for purposes of compiling this rule. -This attribute should not be needed or used -outside of <code>third_party</code>. The values are not preprocessed -in any way other than the "Make" variable substitution.</td> -</tr> -<tr> -<td id="cc_binary.reexport_deps"><code>reexport_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_binary.stamp"><code>stamp</code></td> -<td><p>Integer; default is <code>-1</code></p> -Whether to encode build information into the binary. Possible values: -<ul> -<li><code>stamp = 1</code>: Always stamp the build information into the binary, even in -<a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <strong>This -setting should be avoided</strong>, since it potentially kills remote caching for the -binary and any downstream actions that depend on it.</li> -<li><code>stamp = 0</code>: Always replace build information by constant values. This -gives good build result caching.</li> -<li><code>stamp = -1</code>: Embedding of build information is controlled by the -<a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.</li> -</ul> -<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p></td> -</tr> -<tr> -<td id="cc_binary.win_def_file"><code>win_def_file</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -The Windows DEF file to be passed to linker. -<p>This attribute should only be used when Windows is the target platform. -It can be used to -<a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">export symbols</a> during linking a shared library.</p></td> -</tr> -</tbody> -</table> - -## cc_import - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_import.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets. It is also allowed to put linker scripts (.lds) into deps, and reference them in [linkopts](#cc_binary.linkopts). | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | +| `additional_linker_inputs` | List of [labels](./concepts/labels); default is `[]` Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target. | +| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | +| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](./reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | +| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | +| `defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | +| `distribs` | List of strings; default is `[]` | +| `dynamic_deps` | List of [labels](./concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | +| `hdrs_check` | String; default is `""` Deprecated, no-op. | +| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](./reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | +| `link_extra_lib` | [Label](./concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` Control linking of extra libraries. By default, C++ binaries are linked against `//tools/cpp:link_extra_lib`, which by default depends on the label flag `//tools/cpp:link_extra_libs`. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer `malloc` or `--custom_malloc`). Setting this attribute to `None` disables this behaviour. | +| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables.mdx) substitution, [Bourne shell tokenization](common-definitions.html#sh-tokenization) and [label expansion](common-definitions.html#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | +| `linkshared` | Boolean; default is `False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. The presence of this flag means that linking occurs with the `-shared` flag to `gcc`, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a [cc\_binary](#cc_binary) rule are only loaded manually by other programs, so it should not be considered a substitute for the [cc\_library](#cc_library) rule. For sake of scalability we recommend avoiding this approach altogether and simply letting `java_library` depend on `cc_library` rules instead. If you specify both `linkopts=['-static']` and `linkshared=True`, you get a single completely self-contained unit. If you specify both `linkstatic=True` and `linkshared=True`, you get a single, mostly self-contained unit. | +| `linkstatic` | Boolean; default is `True` For [`cc_binary`](./reference/be/c-cpp.html#cc_binary) and [`cc_test`](./reference/be/c-cpp.html#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](./reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](./reference/be/c-cpp.html#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | +| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. | +| `malloc` | [Label](./concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` Override the default dependency on malloc. By default, C++ binaries are linked against `//tools/cpp:malloc`, which is an empty library so the binary ends up using libc malloc. This label must refer to a `cc_library`. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if `linkshared=True` is specified. | +| `module_interfaces` | List of [labels](./concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | +| `nocopts` | String; default is `""` Remove matching options from the C++ compilation command. Subject to ["Make" variable](./reference/be/make-variables) substitution. The value of this attribute is interpreted as a regular expression. Any preexisting `COPTS` that match this regular expression (including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) will be removed from `COPTS` for purposes of compiling this rule. This attribute should not be needed or used outside of `third_party`. The values are not preprocessed in any way other than the "Make" variable substitution. | +| `reexport_deps` | List of [labels](./concepts/labels); default is `[]` | +| `stamp` | Integer; default is `-1` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](./docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | +| `win_def_file` | [Label](./concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | + +## cc\_import + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_import.bzl) + +``` cc_import(name, deps, data, hdrs, alwayslink, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, includes, interface_library, linkopts, objects, package_metadata, pic_objects, pic_static_library, restricted_to, shared_library, static_library, strip_include_prefix, system_provided, tags, target_compatible_with, testonly, toolchains, visibility) ``` `cc_import` rules allows users to import precompiled C/C++ libraries. -The following are the typical use cases: +The following are the typical use cases: 1. Linking a static library -``` lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -414,10 +97,9 @@ cc_import( ) ``` -2\. Linking a shared library (Unix) - -``` lang-starlark +2. Linking a shared library (Unix) +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -425,12 +107,11 @@ cc_import( ) ``` -3\. Linking a shared library with interface library +3. Linking a shared library with interface library On Unix: -``` lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -443,8 +124,7 @@ cc_import( On Windows: -``` lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -455,12 +135,11 @@ cc_import( ) ``` -4\. Linking a shared library with `system_provided=True` +4. Linking a shared library with `system_provided=True` On Unix: -``` lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -473,8 +152,7 @@ cc_import( On Windows: -``` lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -486,12 +164,11 @@ cc_import( ) ``` -5\. Linking to static or shared library +5. Linking to static or shared library On Unix: -``` lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -502,8 +179,7 @@ cc_import( On Windows: -``` lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -515,8 +191,7 @@ cc_import( The remaining is the same on Unix and Windows: -``` lang-starlark - +``` # first will link to libmylib.a (or libmylib.lib) cc_binary( name = "first", @@ -536,8 +211,7 @@ cc_binary( `cc_import` supports an include attribute. For example: -``` lang-starlark - +``` cc_import( name = "curl_lib", hdrs = glob(["vendor/curl/include/curl/*.h"]), @@ -548,148 +222,28 @@ cc_import( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="cc_import.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="cc_import.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries that the target depends upon. -See general comments about <code>deps</code> -at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>.</td> -</tr> -<tr> -<td id="cc_import.hdrs"><code>hdrs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of header files published by -this precompiled library to be directly included by sources in dependent rules.</td> -</tr> -<tr> -<td id="cc_import.alwayslink"><code>alwayslink</code></td> -<td><p>Boolean; default is <code>False</code></p> -If 1, any binary that depends (directly or indirectly) on this C++ -precompiled library will link in all the object files archived in the static library, -even if some contain no symbols referenced by the binary. -This is useful if your code isn't explicitly called by code in -the binary, e.g., if your code registers to receive some callback -provided by some service. -<p>If alwayslink doesn't work with VS 2017 on Windows, that is due to a -<a href="https://github.com/bazelbuild/bazel/issues/3949">known issue</a>, -please upgrade your VS 2017 to the latest version.</p></td> -</tr> -<tr> -<td id="cc_import.includes"><code>includes</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of include dirs to be added to the compile line. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. -Each string is prepended with the package path and passed to the C++ toolchain for -expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system -with typical feature definitions will produce -<code>-isystem path_to_package/include_entry</code>. -This should only be used for third-party libraries that -do not conform to the Google style of writing #include statements. -Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. -<p>The default <code>include</code> path doesn't include generated -files. If you need to <code>#include</code> a generated header -file, list it in the <code>srcs</code>.</p></td> -</tr> -<tr> -<td id="cc_import.interface_library"><code>interface_library</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -A single interface library for linking the shared library. -<p>Permitted file types: -<code>.ifso</code>, -<code>.tbd</code>, -<code>.lib</code>, -<code>.so</code> -or <code>.dylib</code></p></td> -</tr> -<tr> -<td id="cc_import.linkopts"><code>linkopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these flags to the C++ linker command. -Subject to <a href="make-variables.html">"Make" variable</a> substitution, -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a> and -<a href="common-definitions.html#label-expansion">label expansion</a>. -Each string in this attribute is added to <code>LINKOPTS</code> before -linking the binary target. -<p>Each element of this list that does not start with <code>$</code> or <code>-</code> is -assumed to be the label of a target in <code>deps</code>. The -list of files generated by that target is appended to the linker -options. An error is reported if the label is invalid, or is -not declared in <code>deps</code>.</p></td> -</tr> -<tr> -<td id="cc_import.objects"><code>objects</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_import.pic_objects"><code>pic_objects</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_import.pic_static_library"><code>pic_static_library</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> -</tr> -<tr> -<td id="cc_import.shared_library"><code>shared_library</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -A single precompiled shared library. Bazel ensures it is available to the -binary that depends on it during runtime. -<p>Permitted file types: -<code>.so</code>, -<code>.dll</code> -or <code>.dylib</code></p></td> -</tr> -<tr> -<td id="cc_import.static_library"><code>static_library</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -A single precompiled static library. -<p>Permitted file types: -<code>.a</code>, -<code>.pic.a</code> -or <code>.lib</code></p></td> -</tr> -<tr> -<td id="cc_import.strip_include_prefix"><code>strip_include_prefix</code></td> -<td><p>String; default is <code>""</code></p> -The prefix to strip from the paths of the headers of this rule. -<p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible -at their path with this prefix cut off.</p> -<p>If it's a relative path, it's taken as a package-relative one. If it's an absolute one, -it's understood as a repository-relative path.</p> -<p>The prefix in the <code>include_prefix</code> attribute is added after this prefix is -stripped.</p> -<p>This attribute is only legal under <code>third_party</code>.</p></td> -</tr> -<tr> -<td id="cc_import.system_provided"><code>system_provided</code></td> -<td><p>Boolean; default is <code>False</code></p> -If 1, it indicates the shared library required at runtime is provided by the system. In -this case, <code>interface_library</code> should be specified and -<code>shared_library</code> should be empty.</td> -</tr> -</tbody> -</table> - -## cc_library - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries that the target depends upon. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). | +| `hdrs` | List of [labels](./concepts/labels); default is `[]` The list of header files published by this precompiled library to be directly included by sources in dependent rules. | +| `alwayslink` | Boolean; default is `False` If 1, any binary that depends (directly or indirectly) on this C++ precompiled library will link in all the object files archived in the static library, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. If alwayslink doesn't work with VS 2017 on Windows, that is due to a [known issue](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version. | +| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](./reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The default `include` path doesn't include generated files. If you need to `#include` a generated header file, list it in the `srcs`. | +| `interface_library` | [Label](./concepts/labels); default is `None` A single interface library for linking the shared library. Permitted file types: `.ifso`, `.tbd`, `.lib`, `.so` or `.dylib` | +| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables.mdx) substitution, [Bourne shell tokenization](common-definitions.html#sh-tokenization) and [label expansion](common-definitions.html#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | +| `objects` | List of [labels](./concepts/labels); default is `[]` | +| `pic_objects` | List of [labels](./concepts/labels); default is `[]` | +| `pic_static_library` | [Label](./concepts/labels); default is `None` | +| `shared_library` | [Label](./concepts/labels); default is `None` A single precompiled shared library. Bazel ensures it is available to the binary that depends on it during runtime. Permitted file types: `.so`, `.dll` or `.dylib` | +| `static_library` | [Label](./concepts/labels); default is `None` A single precompiled static library. Permitted file types: `.a`, `.pic.a` or `.lib` | +| `strip_include_prefix` | String; default is `""` The prefix to strip from the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `include_prefix` attribute is added after this prefix is stripped. This attribute is only legal under `third_party`. | +| `system_provided` | Boolean; default is `False` If 1, it indicates the shared library required at runtime is provided by the system. In this case, `interface_library` should be specified and `shared_library` should be empty. | + +## cc\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_library.bzl) + +``` cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, module_interfaces, package_metadata, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file) ``` @@ -702,7 +256,7 @@ a `cc_library`, the output of a depended-on library rule is the `.a` file. If you specify `alwayslink=True`, you get the `.lo` file. -The actual output file name is `lib`*`foo`*`.so` for +The actual output file name is `libfoo.so` for the shared library, where *foo* is the name of the rule. The other kinds of libraries end with `.lo` and `.a`, respectively. If you need a specific shared library name, for @@ -734,8 +288,7 @@ the `srcs`. To illustrate these rules, look at the following example. -``` lang-starlark - +``` cc_binary( name = "foo", srcs = [ @@ -769,16 +322,16 @@ The allowed direct inclusions in this example are listed in the table below. For example `foo.cc` is allowed to directly include `foo.h` and `bar.h`, but not `baz.h`. -| Including file | Allowed inclusions | -|----------------|------------------------| -| foo.h | bar.h | -| foo.cc | foo.h bar.h | -| bar.h | bar-impl.h baz.h | -| bar-impl.h | bar.h baz.h | -| bar.cc | bar.h bar-impl.h baz.h | -| baz.h | baz-impl.h | -| baz-impl.h | baz.h | -| baz.cc | baz.h baz-impl.h | +| Including file | Allowed inclusions | +| --- | --- | +| foo.h | bar.h | +| foo.cc | foo.h bar.h | +| bar.h | bar-impl.h baz.h | +| bar-impl.h | bar.h baz.h | +| bar.cc | bar.h bar-impl.h baz.h | +| baz.h | baz-impl.h | +| baz-impl.h | baz.h | +| baz.cc | baz.h baz-impl.h | The inclusion checking rules only apply to *direct* inclusions. In the example above `foo.cc` is allowed to @@ -798,7 +351,7 @@ The `layering_check` feature has to be supported by the toolchain and requested explicitly, for example via the `--features=layering_check` command-line flag or the `features` parameter of the -[`package`](/reference/be/functions.html#package) function. The toolchains +[`package`](./reference/be/functions.html#package) function. The toolchains provided by Bazel only support this feature with clang on Unix and macOS. #### Examples @@ -806,8 +359,7 @@ provided by Bazel only support this feature with clang on Unix and macOS. We use the `alwayslink` flag to force the linker to link in this code although the main binary code doesn't reference it. -``` lang-starlark - +``` cc_library( name = "ast_inspector_lib", srcs = ["ast_inspector_lib.cc"], @@ -827,8 +379,7 @@ another, dynamic library), so this rule specifies the `-ldl` link option to link the `dl` library. -``` lang-starlark - +``` cc_library( name = "python2_4_3", linkopts = [ @@ -843,8 +394,7 @@ The following example comes from `third_party/kde/BUILD`. We keep pre-built `.so` files in the depot. The header files live in a subdirectory named `include`. -``` lang-starlark - +``` cc_library( name = "kde", srcs = [ @@ -863,8 +413,7 @@ The following example comes from `third_party/gles/BUILD`. Third-party code often needs some `defines` and `linkopts`. -``` lang-starlark - +``` cc_library( name = "gles", srcs = [ @@ -888,376 +437,59 @@ cc_library( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="cc_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="cc_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries that the library target depends upon. -<p>These can be <code>cc_library</code> or <code>objc_library</code> targets.</p> -<p>See general comments about <code>deps</code> -at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>.</p> -<p>These should be names of C++ library rules. -When you build a binary that links this rule's library, -you will also link the libraries in <code>deps</code>.</p> -<p>Despite the "deps" name, not all of this library's clients -belong here. Run-time data dependencies belong in <code>data</code>. -Source files generated by other rules belong in <code>srcs</code>.</p> -<p>To link in a pre-compiled third-party library, add its name to -the <code>srcs</code> instead.</p> -<p>To depend on something without linking it to this library, add its -name to the <code>data</code> instead.</p></td> -</tr> -<tr> -<td id="cc_library.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of C and C++ files that are processed to create the library target. -These are C/C++ source and header files, either non-generated (normal source -code) or generated. -<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will -be compiled. These might be generated files: if a named file is in -the <code>outs</code> of some other rule, this <code>cc_library</code> -will automatically depend on that other rule.</p> -<p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using -the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler.</p> -<p>A <code>.h</code> file will not be compiled, but will be available for -inclusion by sources in this rule. Both <code>.cc</code> and -<code>.h</code> files can directly include headers listed in -these <code>srcs</code> or in the <code>hdrs</code> of this rule or any -rule listed in the <code>deps</code> argument.</p> -<p>All <code>#include</code>d files must be mentioned in the -<code>hdrs</code> attribute of this or referenced <code>cc_library</code> -rules, or they should be listed in <code>srcs</code> if they are private -to this library. See <a href="#hdrs">"Header inclusion checking"</a> for -a more detailed description.</p> -<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are -pre-compiled files. Your library might have these as -<code>srcs</code> if it uses third-party code for which we don't -have source code.</p> -<p>If the <code>srcs</code> attribute includes the label of another rule, -<code>cc_library</code> will use the output files of that rule as source files to -compile. This is useful for one-off generation of source code (for more than occasional -use, it's better to implement a Starlark rule class and use the <code>cc_common</code> -API)</p> -<p>Permitted <code>srcs</code> file types:</p> -<ul> -<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, -<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> -<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, -<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> -<li>Assembler with C preprocessor: <code>.S</code></li> -<li>Archive: <code>.a</code>, <code>.pic.a</code></li> -<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> -<li>Shared library, versioned or unversioned: <code>.so</code>, -<code>.so.</code><em><code>version</code></em></li> -<li>Object file: <code>.o</code>, <code>.pic.o</code></li> -</ul> -<p>... and any rules that produce those files (e.g. <code>cc_embed_data</code>). -Different extensions denote different programming languages in -accordance with gcc convention.</p></td> -</tr> -<tr> -<td id="cc_library.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this library at runtime. -See general comments about <code>data</code> -at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. -<p>If a <code>data</code> is the name of a generated file, then this -<code>cc_library</code> rule automatically depends on the generating -rule.</p> -<p>If a <code>data</code> is a rule name, then this -<code>cc_library</code> rule automatically depends on that rule, -and that rule's <code>outs</code> are automatically added to -this <code>cc_library</code>'s data files.</p> -<p>Your C++ code can access these data files like so:</p> -<pre class="lang-starlark"><code> - const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file");</code></pre></td> -</tr> -<tr> -<td id="cc_library.hdrs"><code>hdrs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of header files published by -this library to be directly included by sources in dependent rules. -<p>This is the strongly preferred location for declaring header files that -describe the interface for the library. These headers will be made -available for inclusion by sources in this rule or in dependent rules. -Headers not meant to be included by a client of this library should be -listed in the <code>srcs</code> attribute instead, even if they are -included by a published header. See <a href="#hdrs">"Header inclusion -checking"</a> for a more detailed description.</p> -<p>Permitted <code>headers</code> file types: -<code>.h</code>, -<code>.hh</code>, -<code>.hpp</code>, -<code>.hxx</code>.</p></td> -</tr> -<tr> -<td id="cc_library.additional_compiler_inputs"><code>additional_compiler_inputs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Any additional files you might want to pass to the compiler command line, such as sanitizer -ignorelists, for example. Files specified here can then be used in copts with the -$(location) function.</td> -</tr> -<tr> -<td id="cc_library.additional_linker_inputs"><code>additional_linker_inputs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Pass these files to the C++ linker command. -<p>For example, compiled Windows .res files can be provided here to be embedded in -the binary target.</p></td> -</tr> -<tr> -<td id="cc_library.alwayslink"><code>alwayslink</code></td> -<td><p>Boolean; default is <code>False</code></p> -If 1, any binary that depends (directly or indirectly) on this C++ -library will link in all the object files for the files listed in -<code>srcs</code>, even if some contain no symbols referenced by the binary. -This is useful if your code isn't explicitly called by code in -the binary, e.g., if your code registers to receive some callback -provided by some service. -<p>If alwayslink doesn't work with VS 2017 on Windows, that is due to a -<a href="https://github.com/bazelbuild/bazel/issues/3949">known issue</a>, -please upgrade your VS 2017 to the latest version.</p></td> -</tr> -<tr> -<td id="cc_library.conlyopts"><code>conlyopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> -</tr> -<tr> -<td id="cc_library.copts"><code>copts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C/C++ compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -<p>Each string in this attribute is added in the given order to <code>COPTS</code> before -compiling the binary target. The flags take effect only for compiling this target, not -its dependencies, so be careful about header files included elsewhere. -All paths should be relative to the workspace, not to the current package. -This attribute should not be needed outside of <code>third_party</code>.</p> -<p>If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> -<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings -that consist of a single "Make" variable.</p></td> -</tr> -<tr> -<td id="cc_library.cxxopts"><code>cxxopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C++ compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> -</tr> -<tr> -<td id="cc_library.defines"><code>defines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of defines to add to the compile line. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -Each string, which must consist of a single Bourne shell token, -is prepended with <code>-D</code> and added to the compile command line to this target, -as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects. When in doubt, add define values to -<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.</td> -</tr> -<tr> -<td id="cc_library.hdrs_check"><code>hdrs_check</code></td> -<td><p>String; default is <code>""</code></p> -Deprecated, no-op.</td> -</tr> -<tr> -<td id="cc_library.implementation_deps"><code>implementation_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries that the library target depends on. Unlike with -<code>deps</code>, the headers and include paths of these libraries (and all their -transitive deps) are only used for compilation of this library, and not libraries that -depend on it. Libraries specified with <code>implementation_deps</code> are still linked in -binary targets that depend on this library.</td> -</tr> -<tr> -<td id="cc_library.include_prefix"><code>include_prefix</code></td> -<td><p>String; default is <code>""</code></p> -The prefix to add to the paths of the headers of this rule. -<p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible -at is the value of this attribute prepended to their repository-relative path.</p> -<p>The prefix in the <code>strip_include_prefix</code> attribute is removed before this -prefix is added.</p> -<p>This attribute is only legal under <code>third_party</code>.</p></td> -</tr> -<tr> -<td id="cc_library.includes"><code>includes</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of include dirs to be added to the compile line. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. -Each string is prepended with the package path and passed to the C++ toolchain for -expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system -with typical feature definitions will produce -<code>-isystem path_to_package/include_entry</code>. -This should only be used for third-party libraries that -do not conform to the Google style of writing #include statements. -Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. -<p>The added <code>include</code> paths will include generated files as well as -files in the source tree.</p></td> -</tr> -<tr> -<td id="cc_library.linkopts"><code>linkopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -See <a href="/reference/be/c-cpp.html#cc_binary.linkopts"><code>cc_binary.linkopts</code></a>. -The <code>linkopts</code> attribute is also applied to any target that -depends, directly or indirectly, on this library via <code>deps</code> -attributes (or via other attributes that are treated similarly: -the <a href="/reference/be/c-cpp.html#cc_binary.malloc"><code>malloc</code></a> -attribute of <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a>). Dependency -linkopts take precedence over dependent linkopts (i.e. dependency linkopts -appear later in the command line). Linkopts specified in -<a href="../user-manual.html#flag--linkopt"><code>--linkopt</code></a> -take precedence over rule linkopts. -<p>Note that the <code>linkopts</code> attribute only applies -when creating <code>.so</code> files or executables, not -when creating <code>.a</code> or <code>.lo</code> files. -So if the <code>linkstatic=True</code> attribute is set, the -<code>linkopts</code> attribute has no effect on the creation of -this library, only on other targets which depend on this library.</p> -<p>Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" -options are not supported and should never be specified in this attribute.</p> -<p>The <code>.so</code> files produced by <code>cc_library</code> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries that the library target depends upon. These can be `cc_library` or `objc_library` targets. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). These should be names of C++ library rules. When you build a binary that links this rule's library, you will also link the libraries in `deps`. Despite the "deps" name, not all of this library's clients belong here. Run-time data dependencies belong in `data`. Source files generated by other rules belong in `srcs`. To link in a pre-compiled third-party library, add its name to the `srcs` instead. To depend on something without linking it to this library, add its name to the `data` instead. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | +| `hdrs` | List of [labels](./concepts/labels); default is `[]` The list of header files published by this library to be directly included by sources in dependent rules. This is the strongly preferred location for declaring header files that describe the interface for the library. These headers will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the `srcs` attribute instead, even if they are included by a published header. See ["Header inclusion checking"](#hdrs) for a more detailed description. Permitted `headers` file types: `.h`, `.hh`, `.hpp`, `.hxx`. | +| `additional_compiler_inputs` | List of [labels](./concepts/labels); default is `[]` Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function. | +| `additional_linker_inputs` | List of [labels](./concepts/labels); default is `[]` Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target. | +| `alwayslink` | Boolean; default is `False` If 1, any binary that depends (directly or indirectly) on this C++ library will link in all the object files for the files listed in `srcs`, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. If alwayslink doesn't work with VS 2017 on Windows, that is due to a [known issue](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version. | +| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | +| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](./reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | +| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | +| `defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | +| `hdrs_check` | String; default is `""` Deprecated, no-op. | +| `implementation_deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries that the library target depends on. Unlike with `deps`, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with `implementation_deps` are still linked in binary targets that depend on this library. | +| `include_prefix` | String; default is `""` The prefix to add to the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the `strip_include_prefix` attribute is removed before this prefix is added. This attribute is only legal under `third_party`. | +| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](./reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | +| `linkopts` | List of strings; default is `[]` See [`cc_binary.linkopts`](./reference/be/c-cpp.html#cc_binary.linkopts). The `linkopts` attribute is also applied to any target that depends, directly or indirectly, on this library via `deps` attributes (or via other attributes that are treated similarly: the [`malloc`](./reference/be/c-cpp.html#cc_binary.malloc) attribute of [`cc_binary`](./reference/be/c-cpp.html#cc_binary)). Dependency linkopts take precedence over dependent linkopts (i.e. dependency linkopts appear later in the command line). Linkopts specified in [`--linkopt`](../user-manual.html#flag--linkopt) take precedence over rule linkopts. | + +Note that the `linkopts` attribute only applies +when creating `.so` files or executables, not +when creating `.a` or `.lo` files. +So if the `linkstatic=True` attribute is set, the +`linkopts` attribute has no effect on the creation of +this library, only on other targets which depend on this library. + +Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" +options are not supported and should never be specified in this attribute. + +The `.so` files produced by `cc_library` rules are not linked against the libraries that they depend on. If you're trying to create a shared library for use outside of the main repository, e.g. for manual use -with <code>dlopen()</code> or <code>LD_PRELOAD</code>, -it may be better to use a <code>cc_binary</code> rule -with the <code>linkshared=True</code> attribute. -See <a href="/reference/be/c-cpp.html#cc_binary.linkshared"><code>cc_binary.linkshared</code></a>.</p></td> -</tr> -<tr> -<td id="cc_library.linkstamp"><code>linkstamp</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Simultaneously compiles and links the specified C++ source file into the final -binary. This trickery is required to introduce timestamp -information into binaries; if we compiled the source file to an -object file in the usual way, the timestamp would be incorrect. -A linkstamp compilation may not include any particular set of -compiler flags and so should not depend on any particular -header, compiler option, or other build variable. -<em>This option should only be needed in the -<code>base</code> package.</em></td> -</tr> -<tr> -<td id="cc_library.linkstatic"><code>linkstatic</code></td> -<td><p>Boolean; default is <code>False</code></p> -For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and -<a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static -mode. For <code>cc_library.link_static</code>: see below. -<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> -<p>If enabled and this is a binary or test, this option tells the build tool to link in -<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. -System libraries such as libc (but <em>not</em> the C/C++ runtime libraries, -see below) are still linked dynamically, as are libraries for which -there is no static library. So the resulting executable will still be dynamically -linked, hence only <em>mostly</em> static.</p> -<p>There are really three different ways to link an executable:</p> -<ul> -<li>STATIC with fully_static_link feature, in which everything is linked statically; -e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br /> -This mode is enabled by specifying <code>fully_static_link</code> in the -<a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> -<li>STATIC, in which all user libraries are linked statically (if a static -version is available), but where system libraries (excluding C/C++ runtime libraries) -are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br /> -This mode is enabled by specifying <code>linkstatic=True</code>.</li> -<li>DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is -available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br /> -This mode is enabled by specifying <code>linkstatic=False</code>.</li> -</ul> -<p>If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in -<code>features</code> is used outside of <code>//third_party</code> -please include a comment near the rule to explain why.</p> -<p>The <code>linkstatic</code> attribute has a different meaning if used on a -<a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. -For a C++ library, <code>linkstatic=True</code> indicates that only -static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does -not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries.</p> -<p>There should be very little code built with <code>linkstatic=False</code> in production. -If <code>linkstatic=False</code>, then the build tool will create symlinks to -depended-upon shared libraries in the <code>*.runfiles</code> area.</p></td> -</tr> -<tr> -<td id="cc_library.local_defines"><code>local_defines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of defines to add to the compile line. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -Each string, which must consist of a single Bourne shell token, -is prepended with <code>-D</code> and added to the compile command line for this target, -but not to its dependents.</td> -</tr> -<tr> -<td id="cc_library.module_interfaces"><code>module_interfaces</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files are regarded as C++20 Modules Interface. -<p>C++ Standard has no restriction about module interface file extension</p> -<ul> -<li>Clang use cppm</li> -<li>GCC can use any source file extension</li> -<li>MSVC use ixx</li> -</ul> -<p>The use is guarded by the flag -<code>--experimental_cpp_modules</code>.</p></td> -</tr> -<tr> -<td id="cc_library.strip_include_prefix"><code>strip_include_prefix</code></td> -<td><p>String; default is <code>""</code></p> -The prefix to strip from the paths of the headers of this rule. -<p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible -at their path with this prefix cut off.</p> -<p>If it's a relative path, it's taken as a package-relative one. If it's an absolute one, -it's understood as a repository-relative path.</p> -<p>The prefix in the <code>include_prefix</code> attribute is added after this prefix is -stripped.</p> -<p>This attribute is only legal under <code>third_party</code>.</p></td> -</tr> -<tr> -<td id="cc_library.textual_hdrs"><code>textual_hdrs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of header files published by -this library to be textually included by sources in dependent rules. -<p>This is the location for declaring header files that cannot be compiled on their own; -that is, they always need to be textually included by other source files to build valid -code.</p></td> -</tr> -<tr> -<td id="cc_library.win_def_file"><code>win_def_file</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -The Windows DEF file to be passed to linker. -<p>This attribute should only be used when Windows is the target platform. -It can be used to -<a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">export symbols</a> during linking a shared library.</p></td> -</tr> -</tbody> -</table> - -## cc_shared_library - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_shared_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +with `dlopen()` or `LD_PRELOAD`, +it may be better to use a `cc_binary` rule +with the `linkshared=True` attribute. +See [`cc_binary.linkshared`](./reference/be/c-cpp.html#cc_binary.linkshared). + +| `linkstamp` | [Label](./concepts/labels); default is `None` Simultaneously compiles and links the specified C++ source file into the final binary. This trickery is required to introduce timestamp information into binaries; if we compiled the source file to an object file in the usual way, the timestamp would be incorrect. A linkstamp compilation may not include any particular set of compiler flags and so should not depend on any particular header, compiler option, or other build variable. *This option should only be needed in the `base` package.* | +| `linkstatic` | Boolean; default is `False` For [`cc_binary`](./reference/be/c-cpp.html#cc_binary) and [`cc_test`](./reference/be/c-cpp.html#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](./reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](./reference/be/c-cpp.html#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | +| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. | +| `module_interfaces` | List of [labels](./concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | +| `strip_include_prefix` | String; default is `""` The prefix to strip from the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `include_prefix` attribute is added after this prefix is stripped. This attribute is only legal under `third_party`. | +| `textual_hdrs` | List of [labels](./concepts/labels); default is `[]` The list of header files published by this library to be textually included by sources in dependent rules. This is the location for declaring header files that cannot be compiled on their own; that is, they always need to be textually included by other source files to build valid code. | +| `win_def_file` | [Label](./concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | + + +## cc\_shared\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_shared_library.bzl) + +``` cc_shared_library(name, deps, additional_linker_inputs, aspect_hints, compatible_with, deprecation, dynamic_deps, exec_compatible_with, exec_group_compatible_with, exec_properties, experimental_disable_topo_sort_do_not_use_remove_before_7_0, exports_filter, features, package_metadata, restricted_to, roots, shared_lib_name, static_deps, tags, target_compatible_with, testonly, toolchains, user_link_flags, visibility, win_def_file) ``` @@ -1265,8 +497,7 @@ It produces a shared library. #### Example -``` code - +``` cc_shared_library( name = "foo_shared", deps = [ @@ -1367,7 +598,7 @@ exported. The solution is to export it from the `cc_shared_library` dependency or pull out a third `cc_shared_library` that exports it. -##### `Do not place libraries which only contain a precompiled dynamic library in deps. ` +##### `Do not place libraries which only contain a precompiled dynamic library in deps.` If you have a precompiled dynamic library, this doesn't need to and cannot be linked statically into the current `cc_shared_library` target that you are @@ -1386,136 +617,25 @@ dependency or make sure that the `exports_filter` doesn't catch this target. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="cc_shared_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="cc_shared_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Top level libraries that will unconditionally be statically linked into the shared library -after being whole-archived. -<p>Any transitive library dependency of these direct deps will be linked into this shared -library as long as they have not already been linked by a <code>cc_shared_library</code> -in <code>dynamic_deps</code>.</p> -<p>During analysis, the rule implementation will consider any target listed in -<code>deps</code> as being exported by the shared library in order to give errors when -multiple <code>cc_shared_libraries</code> export the same targets. The rule implementation -does not take care of informing the linker about which symbols should be exported by the -shared object. The user should take care of this via linker scripts or visibility -declarations in the source code.</p> -<p>The implementation will also trigger errors whenever the same library is linked statically -into more than one <code>cc_shared_library</code>. This can be avoided by adding -<code>"LINKABLE_MORE_THAN_ONCE"</code> to the <code>cc_library.tags</code> or by listing -the `cc_library` as an export of one of the shared libraries so that one can be made a -<code>dynamic_dep</code> of the other.</p></td> -</tr> -<tr> -<td id="cc_shared_library.additional_linker_inputs"><code>additional_linker_inputs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Any additional files that you may want to pass to the linker, for example, linker scripts. -You have to separately pass any linker flags that the linker needs in order to be aware -of this file. You can do so via the <code>user_link_flags</code> attribute.</td> -</tr> -<tr> -<td id="cc_shared_library.dynamic_deps"><code>dynamic_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -These are other <code>cc_shared_library</code> dependencies the current target depends on. -<p>The <code>cc_shared_library</code> implementation will use the list of -<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the -current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in -the transitive <code>deps</code> should not be linked in because they are already provided -by a different <code>cc_shared_library</code>.</p></td> -</tr> -<tr> -<td id="cc_shared_library.experimental_disable_topo_sort_do_not_use_remove_before_7_0"><code>experimental_disable_topo_sort_do_not_use_remove_before_7_0</code></td> -<td><p>Boolean; default is <code>False</code></p></td> -</tr> -<tr> -<td id="cc_shared_library.exports_filter"><code>exports_filter</code></td> -<td><p>List of strings; default is <code>[]</code></p> -This attribute contains a list of targets that are claimed to be exported by the current -shared library. -<p>Any target <code>deps</code> is already understood to be exported by the shared library. -This attribute should be used to list any targets that are exported by the shared library -but are transitive dependencies of <code>deps</code>.</p> -<p>Note that this attribute is not actually adding a dependency edge to those targets, the -dependency edge should instead be created by <code>deps</code>.The entries in this -attribute are just strings. Keep in mind that when placing a target in this attribute, -this is considered a claim that the shared library exports the symbols from that target. -The <code>cc_shared_library</code> logic doesn't actually handle telling the linker which -symbols should be exported.</p> -<p>The following syntax is allowed:</p> -<p><code>//foo:__pkg__</code> to account for any target in foo/BUILD</p> -<p><code>//foo:__subpackages__</code> to account for any target in foo/BUILD or any other -package below foo/ like foo/bar/BUILD</p></td> -</tr> -<tr> -<td id="cc_shared_library.roots"><code>roots</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_shared_library.shared_lib_name"><code>shared_lib_name</code></td> -<td><p>String; default is <code>""</code></p> -By default cc_shared_library will use a name for the shared library output file based on -the target's name and the platform. This includes an extension and sometimes a prefix. -Sometimes you may not want the default name, for example, when loading C++ shared libraries -for Python the default lib* prefix is often not desired, in which case you can use this -attribute to choose a custom name.</td> -</tr> -<tr> -<td id="cc_shared_library.static_deps"><code>static_deps</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_shared_library.user_link_flags"><code>user_link_flags</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Any additional flags that you may want to pass to the linker. For example, to make the -linker aware of a linker script passed via additional_linker_inputs you can use the -following: -<pre class="lang-starlark"><code> - cc_shared_library( - name = "foo_shared", - additional_linker_inputs = select({ - "//src/conditions:linux": [ - ":foo.lds", - ":additional_script.txt", - ], - "//conditions:default": []}), - user_link_flags = select({ - "//src/conditions:linux": [ - "-Wl,-rpath,kittens", - "-Wl,--version-script=$(location :foo.lds)", - "-Wl,--script=$(location :additional_script.txt)", - ], - "//conditions:default": []}), - ... - )</code></pre></td> -</tr> -<tr> -<td id="cc_shared_library.win_def_file"><code>win_def_file</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -The Windows DEF file to be passed to linker. -<p>This attribute should only be used when Windows is the target platform. -It can be used to -<a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">export symbols</a> during linking a shared library.</p></td> -</tr> -</tbody> -</table> - -## cc_static_library - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_static_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` Top level libraries that will unconditionally be statically linked into the shared library after being whole-archived. Any transitive library dependency of these direct deps will be linked into this shared library as long as they have not already been linked by a `cc_shared_library` in `dynamic_deps`. During analysis, the rule implementation will consider any target listed in `deps` as being exported by the shared library in order to give errors when multiple `cc_shared_libraries` export the same targets. The rule implementation does not take care of informing the linker about which symbols should be exported by the shared object. The user should take care of this via linker scripts or visibility declarations in the source code. The implementation will also trigger errors whenever the same library is linked statically into more than one `cc_shared_library`. This can be avoided by adding `"LINKABLE_MORE_THAN_ONCE"` to the `cc_library.tags` or by listing the `cc\_library` as an export of one of the shared libraries so that one can be made a `dynamic_dep` of the other. | +| `additional_linker_inputs` | List of [labels](./concepts/labels); default is `[]` Any additional files that you may want to pass to the linker, for example, linker scripts. You have to separately pass any linker flags that the linker needs in order to be aware of this file. You can do so via the `user_link_flags` attribute. | +| `dynamic_deps` | List of [labels](./concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | +| `experimental_disable_topo_sort_do_not_use_remove_before_7_0` | Boolean; default is `False` | +| `exports_filter` | List of strings; default is `[]` This attribute contains a list of targets that are claimed to be exported by the current shared library. Any target `deps` is already understood to be exported by the shared library. This attribute should be used to list any targets that are exported by the shared library but are transitive dependencies of `deps`. Note that this attribute is not actually adding a dependency edge to those targets, the dependency edge should instead be created by `deps`.The entries in this attribute are just strings. Keep in mind that when placing a target in this attribute, this is considered a claim that the shared library exports the symbols from that target. The `cc_shared_library` logic doesn't actually handle telling the linker which symbols should be exported. The following syntax is allowed: `//foo:__pkg__` to account for any target in foo/BUILD `//foo:__subpackages__` to account for any target in foo/BUILD or any other package below foo/ like foo/bar/BUILD | +| `roots` | List of [labels](./concepts/labels); default is `[]` | +| `shared_lib_name` | String; default is `""` By default cc\_shared\_library will use a name for the shared library output file based on the target's name and the platform. This includes an extension and sometimes a prefix. Sometimes you may not want the default name, for example, when loading C++ shared libraries for Python the default lib\* prefix is often not desired, in which case you can use this attribute to choose a custom name. | +| `static_deps` | List of strings; default is `[]` | +| `user_link_flags` | List of strings; default is `[]` Any additional flags that you may want to pass to the linker. For example, to make the linker aware of a linker script passed via additional\_linker\_inputs you can use the following: ``` cc_shared_library( name = "foo_shared", additional_linker_inputs = select(\{ "//src/conditions:linux": [ ":foo.lds", ":additional_script.txt", ], "//conditions:default": []\}), user_link_flags = select(\{ "//src/conditions:linux": [ "-Wl,-rpath,kittens", "-Wl,--version-script=$(location :foo.lds)", "-Wl,--script=$(location :additional_script.txt)", ], "//conditions:default": []\}), ... ) ``` | +| `win_def_file` | [Label](./concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | + +## cc\_static\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_static_library.bzl) + +``` cc_static_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` @@ -1555,44 +675,25 @@ The auto-configured C++ toolchains shipped with Bazel support the `symbol_check` feature on all platforms. Custom toolchains can add support for it in one of two ways: -- Implementing the `ACTION_NAMES.validate_static_library` action and +* Implementing the `ACTION_NAMES.validate_static_library` action and enabling it with the `symbol_check` feature. The tool set in the action is invoked with two arguments, the static library to check for duplicate symbols and the path of a file that must be created if the check passes. -- Having the `symbol_check` feature add archiver flags that cause the +* Having the `symbol_check` feature add archiver flags that cause the action creating the static library to fail on duplicate symbols. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="cc_static_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="cc_static_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of targets to combine into a static library, including all their transitive -dependencies. -<p>Dependencies that do not provide any object files are not included in the static -library, but their labels are collected in the file provided by the -<code>linkdeps</code> output group.</p></td> -</tr> -</tbody> -</table> - -## cc_test - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_test.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of targets to combine into a static library, including all their transitive dependencies. Dependencies that do not provide any object files are not included in the static library, but their labels are collected in the file provided by the `linkdeps` output group. | + +## cc\_test + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_test.bzl) + +``` cc_test(name, deps, srcs, data, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local, local_defines, malloc, module_interfaces, nocopts, package_metadata, reexport_deps, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file) ``` @@ -1601,372 +702,59 @@ is a binary wrapper around some testing code. *By default, C++ tests are dynamically linked.* To statically link a unit test, specify -[`linkstatic=True`](/reference/be/c-cpp.html#cc_binary.linkstatic). +[`linkstatic=True`](./reference/be/c-cpp.html#cc_binary.linkstatic). It would probably be good to comment why your test needs `linkstatic`; this is probably not obvious. #### Implicit output targets -- `name``.stripped` (only built if explicitly requested): A stripped +* `name.stripped` (only built if explicitly requested): A stripped version of the binary. `strip -g` is run on the binary to remove debug symbols. Additional strip options can be provided on the command line using `--stripopt=-foo`. -- `name``.dwp` (only built if explicitly requested): If +* `name.dwp` (only built if explicitly requested): If [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug information package file suitable for debugging remotely deployed binaries. Else: an empty file. -See the [cc_binary()](/reference/be/c-cpp.html#cc_binary_args) arguments, except that +See the [cc\_binary()](./reference/be/c-cpp.html#cc_binary_args) arguments, except that the `stamp` argument is set to 0 by default for tests and -that `cc_test` has extra -[attributes common to all test rules (\*\_test)](/reference/be/common-definitions#common-attributes-tests). +that `cc_test` has extra [attributes common to all test rules (\*\_test)](./reference/be/common-definitions#common-attributes-tests). ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="cc_test.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="cc_test.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries to be linked in to the binary target. -<p>These can be <code>cc_library</code> or <code>objc_library</code> -targets.</p> -It is also allowed to -put linker scripts (.lds) into deps, and reference them in -<a href="#cc_binary.linkopts">linkopts</a>.</td> -</tr> -<tr> -<td id="cc_test.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of C and C++ files that are processed to create the library target. -These are C/C++ source and header files, either non-generated (normal source -code) or generated. -<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will -be compiled. These might be generated files: if a named file is in -the <code>outs</code> of some other rule, this <code>cc_library</code> -will automatically depend on that other rule.</p> -<p>Pure assembler files (.s, .asm) are not preprocessed and are typically built using -the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler.</p> -<p>A <code>.h</code> file will not be compiled, but will be available for -inclusion by sources in this rule. Both <code>.cc</code> and -<code>.h</code> files can directly include headers listed in -these <code>srcs</code> or in the <code>hdrs</code> of this rule or any -rule listed in the <code>deps</code> argument.</p> -<p>All <code>#include</code>d files must be mentioned in the -<code>hdrs</code> attribute of this or referenced <code>cc_library</code> -rules, or they should be listed in <code>srcs</code> if they are private -to this library. See <a href="#hdrs">"Header inclusion checking"</a> for -a more detailed description.</p> -<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are -pre-compiled files. Your library might have these as -<code>srcs</code> if it uses third-party code for which we don't -have source code.</p> -<p>If the <code>srcs</code> attribute includes the label of another rule, -<code>cc_library</code> will use the output files of that rule as source files to -compile. This is useful for one-off generation of source code (for more than occasional -use, it's better to implement a Starlark rule class and use the <code>cc_common</code> -API)</p> -<p>Permitted <code>srcs</code> file types:</p> -<ul> -<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>, -<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li> -<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>, -<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li> -<li>Assembler with C preprocessor: <code>.S</code></li> -<li>Archive: <code>.a</code>, <code>.pic.a</code></li> -<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li> -<li>Shared library, versioned or unversioned: <code>.so</code>, -<code>.so.</code><em><code>version</code></em></li> -<li>Object file: <code>.o</code>, <code>.pic.o</code></li> -</ul> -<p>... and any rules that produce those files (e.g. <code>cc_embed_data</code>). -Different extensions denote different programming languages in -accordance with gcc convention.</p></td> -</tr> -<tr> -<td id="cc_test.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this library at runtime. -See general comments about <code>data</code> -at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. -<p>If a <code>data</code> is the name of a generated file, then this -<code>cc_library</code> rule automatically depends on the generating -rule.</p> -<p>If a <code>data</code> is a rule name, then this -<code>cc_library</code> rule automatically depends on that rule, -and that rule's <code>outs</code> are automatically added to -this <code>cc_library</code>'s data files.</p> -<p>Your C++ code can access these data files like so:</p> -<pre class="lang-starlark"><code> - const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file");</code></pre></td> -</tr> -<tr> -<td id="cc_test.additional_linker_inputs"><code>additional_linker_inputs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Pass these files to the C++ linker command. -<p>For example, compiled Windows .res files can be provided here to be embedded in -the binary target.</p></td> -</tr> -<tr> -<td id="cc_test.conlyopts"><code>conlyopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> -</tr> -<tr> -<td id="cc_test.copts"><code>copts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C/C++ compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -<p>Each string in this attribute is added in the given order to <code>COPTS</code> before -compiling the binary target. The flags take effect only for compiling this target, not -its dependencies, so be careful about header files included elsewhere. -All paths should be relative to the workspace, not to the current package. -This attribute should not be needed outside of <code>third_party</code>.</p> -<p>If the package declares the <a href="/reference/be/functions.html#package.features">feature</a> -<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings -that consist of a single "Make" variable.</p></td> -</tr> -<tr> -<td id="cc_test.cxxopts"><code>cxxopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these options to the C++ compilation command. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> -</tr> -<tr> -<td id="cc_test.defines"><code>defines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of defines to add to the compile line. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -Each string, which must consist of a single Bourne shell token, -is prepended with <code>-D</code> and added to the compile command line to this target, -as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects. When in doubt, add define values to -<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.</td> -</tr> -<tr> -<td id="cc_test.distribs"><code>distribs</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_test.dynamic_deps"><code>dynamic_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -These are other <code>cc_shared_library</code> dependencies the current target depends on. -<p>The <code>cc_shared_library</code> implementation will use the list of -<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the -current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in -the transitive <code>deps</code> should not be linked in because they are already provided -by a different <code>cc_shared_library</code>.</p></td> -</tr> -<tr> -<td id="cc_test.hdrs_check"><code>hdrs_check</code></td> -<td><p>String; default is <code>""</code></p> -Deprecated, no-op.</td> -</tr> -<tr> -<td id="cc_test.includes"><code>includes</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of include dirs to be added to the compile line. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution. -Each string is prepended with the package path and passed to the C++ toolchain for -expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system -with typical feature definitions will produce -<code>-isystem path_to_package/include_entry</code>. -This should only be used for third-party libraries that -do not conform to the Google style of writing #include statements. -Unlike <a href="#cc_binary.copts">COPTS</a>, these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-I" flags to <a href="#cc_binary.copts">COPTS</a> instead. -<p>The added <code>include</code> paths will include generated files as well as -files in the source tree.</p></td> -</tr> -<tr> -<td id="cc_test.link_extra_lib"><code>link_extra_lib</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p> -Control linking of extra libraries. -<p>By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>, -which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>. -Without setting the flag, this library is empty by default. Setting the label flag -allows linking optional dependencies, such as overrides for weak symbols, interceptors -for shared library functions, or special runtime libraries (for malloc replacements, -prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to -<code>None</code> disables this behaviour.</p></td> -</tr> -<tr> -<td id="cc_test.linkopts"><code>linkopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Add these flags to the C++ linker command. -Subject to <a href="make-variables.html">"Make" variable</a> substitution, -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a> and -<a href="common-definitions.html#label-expansion">label expansion</a>. -Each string in this attribute is added to <code>LINKOPTS</code> before -linking the binary target. -<p>Each element of this list that does not start with <code>$</code> or <code>-</code> is -assumed to be the label of a target in <code>deps</code>. The -list of files generated by that target is appended to the linker -options. An error is reported if the label is invalid, or is -not declared in <code>deps</code>.</p></td> -</tr> -<tr> -<td id="cc_test.linkshared"><code>linkshared</code></td> -<td><p>Boolean; default is <code>False</code></p> -Create a shared library. -To enable this attribute, include <code>linkshared=True</code> in your rule. By default -this option is off. -<p>The presence of this flag means that linking occurs with the <code>-shared</code> flag -to <code>gcc</code>, and the resulting shared library is suitable for loading into for -example a Java program. However, for build purposes it will never be linked into the -dependent binary, as it is assumed that shared libraries built with a -<a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so -it should not be considered a substitute for the <a href="#cc_library">cc_library</a> -rule. For sake of scalability we recommend avoiding this approach altogether and -simply letting <code>java_library</code> depend on <code>cc_library</code> rules -instead.</p> -<p>If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>, -you get a single completely self-contained unit. If you specify both -<code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly -self-contained unit.</p></td> -</tr> -<tr> -<td id="cc_test.linkstatic"><code>linkstatic</code></td> -<td><p>Boolean; default is <code>False</code></p> -For <a href="/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and -<a href="/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static -mode. For <code>cc_library.link_static</code>: see below. -<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p> -<p>If enabled and this is a binary or test, this option tells the build tool to link in -<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible. -System libraries such as libc (but <em>not</em> the C/C++ runtime libraries, -see below) are still linked dynamically, as are libraries for which -there is no static library. So the resulting executable will still be dynamically -linked, hence only <em>mostly</em> static.</p> -<p>There are really three different ways to link an executable:</p> -<ul> -<li>STATIC with fully_static_link feature, in which everything is linked statically; -e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br /> -This mode is enabled by specifying <code>fully_static_link</code> in the -<a href="/reference/be/common-definitions#features"><code>features</code></a> attribute.</li> -<li>STATIC, in which all user libraries are linked statically (if a static -version is available), but where system libraries (excluding C/C++ runtime libraries) -are linked dynamically, e.g. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br /> -This mode is enabled by specifying <code>linkstatic=True</code>.</li> -<li>DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is -available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br /> -This mode is enabled by specifying <code>linkstatic=False</code>.</li> -</ul> -<p>If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in -<code>features</code> is used outside of <code>//third_party</code> -please include a comment near the rule to explain why.</p> -<p>The <code>linkstatic</code> attribute has a different meaning if used on a -<a href="/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule. -For a C++ library, <code>linkstatic=True</code> indicates that only -static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does -not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries.</p> -<p>There should be very little code built with <code>linkstatic=False</code> in production. -If <code>linkstatic=False</code>, then the build tool will create symlinks to -depended-upon shared libraries in the <code>*.runfiles</code> area.</p></td> -</tr> -<tr> -<td id="cc_test.local_defines"><code>local_defines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of defines to add to the compile line. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -Each string, which must consist of a single Bourne shell token, -is prepended with <code>-D</code> and added to the compile command line for this target, -but not to its dependents.</td> -</tr> -<tr> -<td id="cc_test.malloc"><code>malloc</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p> -Override the default dependency on malloc. -<p>By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>, -which is an empty library so the binary ends up using libc malloc. -This label must refer to a <code>cc_library</code>. If compilation is for a non-C++ -rule, this option has no effect. The value of this attribute is ignored if -<code>linkshared=True</code> is specified.</p></td> -</tr> -<tr> -<td id="cc_test.module_interfaces"><code>module_interfaces</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files are regarded as C++20 Modules Interface. -<p>C++ Standard has no restriction about module interface file extension</p> -<ul> -<li>Clang use cppm</li> -<li>GCC can use any source file extension</li> -<li>MSVC use ixx</li> -</ul> -<p>The use is guarded by the flag -<code>--experimental_cpp_modules</code>.</p></td> -</tr> -<tr> -<td id="cc_test.nocopts"><code>nocopts</code></td> -<td><p>String; default is <code>""</code></p> -Remove matching options from the C++ compilation command. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. -The value of this attribute is interpreted as a regular expression. -Any preexisting <code>COPTS</code> that match this regular expression -(including values explicitly specified in the rule's <a href="#cc_binary.copts">copts</a> attribute) -will be removed from <code>COPTS</code> for purposes of compiling this rule. -This attribute should not be needed or used -outside of <code>third_party</code>. The values are not preprocessed -in any way other than the "Make" variable substitution.</td> -</tr> -<tr> -<td id="cc_test.reexport_deps"><code>reexport_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_test.stamp"><code>stamp</code></td> -<td><p>Integer; default is <code>0</code></p> -Whether to encode build information into the binary. Possible values: -<ul> -<li><code>stamp = 1</code>: Always stamp the build information into the binary, even in -<a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <strong>This -setting should be avoided</strong>, since it potentially kills remote caching for the -binary and any downstream actions that depend on it.</li> -<li><code>stamp = 0</code>: Always replace build information by constant values. This -gives good build result caching.</li> -<li><code>stamp = -1</code>: Embedding of build information is controlled by the -<a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.</li> -</ul> -<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p></td> -</tr> -<tr> -<td id="cc_test.win_def_file"><code>win_def_file</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -The Windows DEF file to be passed to linker. -<p>This attribute should only be used when Windows is the target platform. -It can be used to -<a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">export symbols</a> during linking a shared library.</p></td> -</tr> -</tbody> -</table> - -## cc_toolchain - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_toolchain.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets. It is also allowed to put linker scripts (.lds) into deps, and reference them in [linkopts](#cc_binary.linkopts). | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | +| `additional_linker_inputs` | List of [labels](./concepts/labels); default is `[]` Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target. | +| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | +| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](./reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | +| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | +| `defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | +| `distribs` | List of strings; default is `[]` | +| `dynamic_deps` | List of [labels](./concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | +| `hdrs_check` | String; default is `""` Deprecated, no-op. | +| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](./reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | +| `link_extra_lib` | [Label](./concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` Control linking of extra libraries. By default, C++ binaries are linked against `//tools/cpp:link_extra_lib`, which by default depends on the label flag `//tools/cpp:link_extra_libs`. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer `malloc` or `--custom_malloc`). Setting this attribute to `None` disables this behaviour. | +| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables.mdx) substitution, [Bourne shell tokenization](common-definitions.html#sh-tokenization) and [label expansion](common-definitions.html#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | +| `linkshared` | Boolean; default is `False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. The presence of this flag means that linking occurs with the `-shared` flag to `gcc`, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a [cc\_binary](#cc_binary) rule are only loaded manually by other programs, so it should not be considered a substitute for the [cc\_library](#cc_library) rule. For sake of scalability we recommend avoiding this approach altogether and simply letting `java_library` depend on `cc_library` rules instead. If you specify both `linkopts=['-static']` and `linkshared=True`, you get a single completely self-contained unit. If you specify both `linkstatic=True` and `linkshared=True`, you get a single, mostly self-contained unit. | +| `linkstatic` | Boolean; default is `False` For [`cc_binary`](./reference/be/c-cpp.html#cc_binary) and [`cc_test`](./reference/be/c-cpp.html#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](./reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](./reference/be/c-cpp.html#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | +| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. | +| `malloc` | [Label](./concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` Override the default dependency on malloc. By default, C++ binaries are linked against `//tools/cpp:malloc`, which is an empty library so the binary ends up using libc malloc. This label must refer to a `cc_library`. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if `linkshared=True` is specified. | +| `module_interfaces` | List of [labels](./concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | +| `nocopts` | String; default is `""` Remove matching options from the C++ compilation command. Subject to ["Make" variable](./reference/be/make-variables) substitution. The value of this attribute is interpreted as a regular expression. Any preexisting `COPTS` that match this regular expression (including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) will be removed from `COPTS` for purposes of compiling this rule. This attribute should not be needed or used outside of `third_party`. The values are not preprocessed in any way other than the "Make" variable substitution. | +| `reexport_deps` | List of [labels](./concepts/labels); default is `[]` | +| `stamp` | Integer; default is `0` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](./docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | +| `win_def_file` | [Label](./concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | + +## cc\_toolchain + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_toolchain.bzl) + +``` cc_toolchain(name, all_files, ar_files, as_files, aspect_hints, compatible_with, compiler_files, compiler_files_without_includes, coverage_files, deprecation, dwp_files, dynamic_runtime_lib, exec_compatible_with, exec_group_compatible_with, exec_properties, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, output_licenses, package_metadata, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, toolchains, visibility) ``` @@ -1974,167 +762,58 @@ Represents a C++ toolchain. This rule is responsible for: -- Collecting all artifacts needed for C++ actions to run. This is done by +* Collecting all artifacts needed for C++ actions to run. This is done by attributes such as `all_files`, `compiler_files`, `linker_files`, or other attributes ending with `_files`). These are most commonly filegroups globbing all required files. -- Generating correct command lines for C++ actions. This is done using +* Generating correct command lines for C++ actions. This is done using `CcToolchainConfigInfo` provider (details below). Use `toolchain_config` attribute to configure the C++ toolchain. See also this -[page](https://bazel.build/docs/cc-toolchain-config-reference) -for elaborate C++ toolchain configuration and toolchain selection documentation. +[page](https://bazel.build/docs/cc-toolchain-config-reference) for elaborate C++ toolchain configuration and toolchain selection documentation. Use `tags = ["manual"]` in order to prevent toolchains from being built and configured unnecessarily when invoking `bazel build //...` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="cc_toolchain.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="cc_toolchain.all_files"><code>all_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Collection of all cc_toolchain artifacts. These artifacts will be added as inputs to all -rules_cc related actions (with the exception of actions that are using more precise sets of -artifacts from attributes below). Bazel assumes that <code>all_files</code> is a superset -of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile -and link files, so it takes <code>all_files</code>). -<p>This is what <code>cc_toolchain.files</code> contains, and this is used by all Starlark -rules using C++ toolchain.</p></td> -</tr> -<tr> -<td id="cc_toolchain.ar_files"><code>ar_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Collection of all cc_toolchain artifacts required for archiving actions.</td> -</tr> -<tr> -<td id="cc_toolchain.as_files"><code>as_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Collection of all cc_toolchain artifacts required for assembly actions.</td> -</tr> -<tr> -<td id="cc_toolchain.compiler_files"><code>compiler_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Collection of all cc_toolchain artifacts required for compile actions.</td> -</tr> -<tr> -<td id="cc_toolchain.compiler_files_without_includes"><code>compiler_files_without_includes</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Collection of all cc_toolchain artifacts required for compile actions in case when -input discovery is supported (currently Google-only).</td> -</tr> -<tr> -<td id="cc_toolchain.coverage_files"><code>coverage_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Collection of all cc_toolchain artifacts required for coverage actions. If not specified, -all_files are used.</td> -</tr> -<tr> -<td id="cc_toolchain.dwp_files"><code>dwp_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Collection of all cc_toolchain artifacts required for dwp actions.</td> -</tr> -<tr> -<td id="cc_toolchain.dynamic_runtime_lib"><code>dynamic_runtime_lib</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). -<p>This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking -dependencies dynamically.</p></td> -</tr> -<tr> -<td id="cc_toolchain.exec_transition_for_inputs"><code>exec_transition_for_inputs</code></td> -<td><p>Boolean; default is <code>False</code></p> -Deprecated. No-op.</td> -</tr> -<tr> -<td id="cc_toolchain.libc_top"><code>libc_top</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -A collection of artifacts for libc passed as inputs to compile/linking actions.</td> -</tr> -<tr> -<td id="cc_toolchain.linker_files"><code>linker_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Collection of all cc_toolchain artifacts required for linking actions.</td> -</tr> -<tr> -<td id="cc_toolchain.module_map"><code>module_map</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Module map artifact to be used for modular builds.</td> -</tr> -<tr> -<td id="cc_toolchain.objcopy_files"><code>objcopy_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Collection of all cc_toolchain artifacts required for objcopy actions.</td> -</tr> -<tr> -<td id="cc_toolchain.output_licenses"><code>output_licenses</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="cc_toolchain.static_runtime_lib"><code>static_runtime_lib</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Static library artifact for the C++ runtime library (e.g. libstdc++.a). -<p>This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking -dependencies statically.</p></td> -</tr> -<tr> -<td id="cc_toolchain.strip_files"><code>strip_files</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Collection of all cc_toolchain artifacts required for strip actions.</td> -</tr> -<tr> -<td id="cc_toolchain.supports_header_parsing"><code>supports_header_parsing</code></td> -<td><p>Boolean; default is <code>False</code></p> -Set to True when cc_toolchain supports header parsing actions.</td> -</tr> -<tr> -<td id="cc_toolchain.supports_param_files"><code>supports_param_files</code></td> -<td><p>Boolean; default is <code>True</code></p> -Set to True when cc_toolchain supports using param files for linking actions.</td> -</tr> -<tr> -<td id="cc_toolchain.toolchain_config"><code>toolchain_config</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -The label of the rule providing <code>cc_toolchain_config_info</code>.</td> -</tr> -<tr> -<td id="cc_toolchain.toolchain_identifier"><code>toolchain_identifier</code></td> -<td><p>String; default is <code>""</code></p> -The identifier used to match this cc_toolchain with the corresponding -crosstool_config.toolchain. -<p>Until issue <a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a> is fixed -this is the recommended way of associating <code>cc_toolchain</code> with -<code>CROSSTOOL.toolchain</code>. It will be replaced by the <code>toolchain_config</code> -attribute (<a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a>).</p></td> -</tr> -</tbody> -</table> - -## fdo_prefetch_hints - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_prefetch_hints.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `all_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts. These artifacts will be added as inputs to all rules\_cc related actions (with the exception of actions that are using more precise sets of artifacts from attributes below). Bazel assumes that `all_files` is a superset of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile and link files, so it takes `all_files`). This is what `cc_toolchain.files` contains, and this is used by all Starlark rules using C++ toolchain. | +| `ar_files` | [Label](./concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for archiving actions. | +| `as_files` | [Label](./concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for assembly actions. | +| `compiler_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for compile actions. | +| `compiler_files_without_includes` | [Label](./concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for compile actions in case when input discovery is supported (currently Google-only). | +| `coverage_files` | [Label](./concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for coverage actions. If not specified, all\_files are used. | +| `dwp_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for dwp actions. | +| `dynamic_runtime_lib` | [Label](./concepts/labels); default is `None` Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking dependencies dynamically. | +| `exec_transition_for_inputs` | Boolean; default is `False` Deprecated. No-op. | +| `libc_top` | [Label](./concepts/labels); default is `None` A collection of artifacts for libc passed as inputs to compile/linking actions. | +| `linker_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for linking actions. | +| `module_map` | [Label](./concepts/labels); default is `None` Module map artifact to be used for modular builds. | +| `objcopy_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for objcopy actions. | +| `output_licenses` | List of strings; default is `[]` | +| `static_runtime_lib` | [Label](./concepts/labels); default is `None` Static library artifact for the C++ runtime library (e.g. libstdc++.a). This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking dependencies statically. | +| `strip_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for strip actions. | +| `supports_header_parsing` | Boolean; default is `False` Set to True when cc\_toolchain supports header parsing actions. | +| `supports_param_files` | Boolean; default is `True` Set to True when cc\_toolchain supports using param files for linking actions. | +| `toolchain_config` | [Label](./concepts/labels); required The label of the rule providing `cc_toolchain_config_info`. | +| `toolchain_identifier` | String; default is `""` The identifier used to match this cc\_toolchain with the corresponding crosstool\_config.toolchain. Until issue [#5380](https://github.com/bazelbuild/bazel/issues/5380) is fixed this is the recommended way of associating `cc_toolchain` with `CROSSTOOL.toolchain`. It will be replaced by the `toolchain_config` attribute ([#5380](https://github.com/bazelbuild/bazel/issues/5380)). | + +## fdo\_prefetch\_hints + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_prefetch_hints.bzl) + +``` fdo_prefetch_hints(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` Represents an FDO prefetch hints profile that is either in the workspace. Examples: -``` lang-starlark - +``` fdo_prefetch_hints( name = "hints", profile = "//path/to/hints:profile.afdo", @@ -2143,40 +822,23 @@ fdo_prefetch_hints( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="fdo_prefetch_hints.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="fdo_prefetch_hints.profile"><code>profile</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Label of the hints profile. The hints file has the .afdo extension -The label can also point to an fdo_absolute_path_profile rule.</td> -</tr> -</tbody> -</table> - -## fdo_profile - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_profile.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `profile` | [Label](./concepts/labels); required Label of the hints profile. The hints file has the .afdo extension The label can also point to an fdo\_absolute\_path\_profile rule. | + +## fdo\_profile + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_profile.bzl) + +``` fdo_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, memprof_profile, package_metadata, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` Represents an FDO profile that is in the workspace. Example: -``` lang-starlark - +``` fdo_profile( name = "fdo", profile = "//path/to/fdo:profile.zip", @@ -2185,55 +847,25 @@ fdo_profile( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="fdo_profile.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="fdo_profile.memprof_profile"><code>memprof_profile</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the MemProf profile. The profile is expected to have -either a .profdata extension (for an indexed/symbolized memprof -profile), or a .zip extension for a zipfile containing a memprof.profdata -file.</td> -</tr> -<tr> -<td id="fdo_profile.profile"><code>profile</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Label of the FDO profile or a rule which generates it. The FDO file can have one of the -following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM -profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for -XBinary profile. The label can also point to an fdo_absolute_path_profile rule.</td> -</tr> -<tr> -<td id="fdo_profile.proto_profile"><code>proto_profile</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the protobuf profile.</td> -</tr> -</tbody> -</table> - -## memprof_profile - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/memprof_profile.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `memprof_profile` | [Label](./concepts/labels); default is `None` Label of the MemProf profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file. | +| `profile` | [Label](./concepts/labels); required Label of the FDO profile or a rule which generates it. The FDO file can have one of the following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for XBinary profile. The label can also point to an fdo\_absolute\_path\_profile rule. | +| `proto_profile` | [Label](./concepts/labels); default is `None` Label of the protobuf profile. | + +## memprof\_profile + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/memprof_profile.bzl) + +``` memprof_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` Represents a MEMPROF profile that is in the workspace. Example: -``` lang-starlark - +``` memprof_profile( name = "memprof", profile = "//path/to/memprof:profile.afdo", @@ -2242,43 +874,23 @@ memprof_profile( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="memprof_profile.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="memprof_profile.profile"><code>profile</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Label of the MEMPROF profile. The profile is expected to have -either a .profdata extension (for an indexed/symbolized memprof -profile), or a .zip extension for a zipfile containing a memprof.profdata -file. -The label can also point to an fdo_absolute_path_profile rule.</td> -</tr> -</tbody> -</table> - -## propeller_optimize - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/propeller_optimize.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `profile` | [Label](./concepts/labels); required Label of the MEMPROF profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file. The label can also point to an fdo\_absolute\_path\_profile rule. | + +## propeller\_optimize + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/propeller_optimize.bzl) + +``` propeller_optimize(name, aspect_hints, cc_profile, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, ld_profile, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` Represents a Propeller optimization profile in the workspace. Example: -``` lang-starlark - +``` propeller_optimize( name = "layout", cc_profile = "//path:cc_profile.txt", @@ -2288,29 +900,8 @@ propeller_optimize( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="propeller_optimize.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="propeller_optimize.cc_profile"><code>cc_profile</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Label of the profile passed to the various compile actions. This file has -the .txt extension.</td> -</tr> -<tr> -<td id="propeller_optimize.ld_profile"><code>ld_profile</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -Label of the profile passed to the link action. This file has -the .txt extension.</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `cc_profile` | [Label](./concepts/labels); required Label of the profile passed to the various compile actions. This file has the .txt extension. | +| `ld_profile` | [Label](./concepts/labels); required Label of the profile passed to the link action. This file has the .txt extension. | \ No newline at end of file diff --git a/reference/be/common-definitions.mdx b/reference/be/common-definitions.mdx index 02d2e4a..a035d0a 100644 --- a/reference/be/common-definitions.mdx +++ b/reference/be/common-definitions.mdx @@ -2,24 +2,20 @@ title: 'common-definitions' --- -# Common definitions - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm" %} -{% include "\_buttons.html" %} This section defines various terms and concepts that are common to many functions or build rules. ## Contents -- [Bourne shell tokenization](#sh-tokenization) -- [Label Expansion](#label-expansion) -- [Typical attributes defined by most build rules](#typical-attributes) -- [Attributes common to all build rules](#common-attributes) -- [Attributes common to all test rules (\*\_test)](#common-attributes-tests) -- [Attributes common to all binary rules (\*\_binary)](#common-attributes-binaries) -- [Configurable attributes](#configurable-attributes) -- [Implicit output targets](#implicit-outputs) +* [Bourne shell tokenization](#sh-tokenization) +* [Label Expansion](#label-expansion) +* [Typical attributes defined by most build rules](#typical-attributes) +* [Attributes common to all build rules](#common-attributes) +* [Attributes common to all test rules (\*\_test)](#common-attributes-tests) +* [Attributes common to all binary rules (\*\_binary)](#common-attributes-binaries) +* [Configurable attributes](#configurable-attributes) +* [Implicit output targets](#implicit-outputs) ## Bourne shell tokenization @@ -62,642 +58,59 @@ specifics. This section describes attributes that are defined by many build rules, but not all. -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th>Attribute</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="typical.data"><code>data</code></td> -<td><span id="common.data"></span> -<p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<p>Files needed by this rule at runtime. May list file or rule targets. Generally -allows any target.</p> -<p>The default outputs and runfiles of targets in the <code>data</code> attribute -should appear in the <code>*.runfiles</code> area of any executable which is -output by or has a runtime dependency on this target. This may include data -files or binaries used when this target's -<a href="#typical.srcs"><code>srcs</code></a> are executed. See the -<a href="/concepts/dependencies#data-dependencies">data dependencies</a> -section for more information about how to depend on and use data files.</p> -<p>New rules should define a <code>data</code> attribute if they process -inputs which might use other inputs at runtime. Rules' implementation functions -must also <a href="https://bazel.build/rules/rules#runfiles">populate the target's -runfiles</a> from the outputs and runfiles of any <code>data</code> attribute, -as well as runfiles from any dependency attribute which provides either -source code or runtime dependencies.</p></td> -</tr> -<tr> -<td id="typical.deps"><code>deps</code></td> -<td><span id="common.deps"></span> -<p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<p>Dependencies for this target. Generally should only list rule targets. (Though -some rules permit files to be listed directly in <code>deps</code>, this -should be avoided when possible.)</p> -<p>Language-specific rules generally limit the listed targets to those with -specific <a href="https://bazel.build/extending/rules#providers">providers</a>.</p> -<p>The precise semantics of what it means for a target to depend on another using -<code>deps</code> are specific to the kind of rule, and the rule-specific -documentation goes into more detail. For rules which process source code, -<code>deps</code> generally specifies code dependencies used by the code in -<a href="#typical.srcs"><code>srcs</code></a>.</p> -<p>Most often, a <code>deps</code> dependency is used to allow one module to use -symbols defined in another module written in the same programming language and -separately compiled. Cross-language dependencies are also permitted in many -cases: For example, a <code>java_library</code> target may depend on C++ code -in a <code>cc_library</code> target, by listing the latter in the -<code>deps</code> attribute. See the definition of -<a href="/concepts/build-ref#deps">dependencies</a> -for more information.</p></td> -</tr> -<tr> -<td id="typical.licenses"><code>licenses</code></td> -<td><span id="common.licenses"></span> -<p>List of strings; <a href="#configurable-attributes">nonconfigurable</a>; -default is <code>["none"]</code></p> -<p>A list of license-type strings to be used for this particular target. -This is part of a deprecated licensing API that Bazel no longer uses. Don't -use this.</p></td> -</tr> -<tr> -<td id="typical.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<p>Files processed or included by this rule. Generally lists files directly, but -may list rule targets (like <code>filegroup</code> or <code>genrule</code>) to -include their default outputs.</p> -<p>Language-specific rules often require that the listed files have particular -file extensions.</p></td> -</tr> -</tbody> -</table> +| Attribute | Description | +| --- | --- | +| `data` | List of [labels](./concepts/labels); default is `[]` Files needed by this rule at runtime. May list file or rule targets. Generally allows any target. The default outputs and runfiles of targets in the `data` attribute should appear in the `*.runfiles` area of any executable which is output by or has a runtime dependency on this target. This may include data files or binaries used when this target's [`srcs`](#typical.srcs) are executed. See the [data dependencies](./concepts/dependencies#data-dependencies) section for more information about how to depend on and use data files. New rules should define a `data` attribute if they process inputs which might use other inputs at runtime. Rules' implementation functions must also [populate the target's runfiles](https://bazel.build/rules/rules#runfiles) from the outputs and runfiles of any `data` attribute, as well as runfiles from any dependency attribute which provides either source code or runtime dependencies. | +| `deps` | List of [labels](./concepts/labels); default is `[]` Dependencies for this target. Generally should only list rule targets. (Though some rules permit files to be listed directly in `deps`, this should be avoided when possible.) Language-specific rules generally limit the listed targets to those with specific [providers](https://bazel.build/extending/rules#providers). The precise semantics of what it means for a target to depend on another using `deps` are specific to the kind of rule, and the rule-specific documentation goes into more detail. For rules which process source code, `deps` generally specifies code dependencies used by the code in [`srcs`](#typical.srcs). Most often, a `deps` dependency is used to allow one module to use symbols defined in another module written in the same programming language and separately compiled. Cross-language dependencies are also permitted in many cases: For example, a `java_library` target may depend on C++ code in a `cc_library` target, by listing the latter in the `deps` attribute. See the definition of [dependencies](./concepts/build-ref#deps) for more information. | +| `licenses` | List of strings; [nonconfigurable](#configurable-attributes); default is `["none"]` A list of license-type strings to be used for this particular target. This is part of a deprecated licensing API that Bazel no longer uses. Don't use this. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` Files processed or included by this rule. Generally lists files directly, but may list rule targets (like `filegroup` or `genrule`) to include their default outputs. Language-specific rules often require that the listed files have particular file extensions. | ## Attributes common to all build rules This section describes attributes that are implicitly added to all build rules. -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th>Attribute</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="common.aspect_hints"><code>aspect_hints</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<p>A list of arbitrary labels which is exposed to <a href="/extending/aspects">aspects</a> (in -particular - aspects invoked by this rule's reverse dependencies), but isn't exposed to this rule's -own implementation. Consult documentation for language-specific rule sets for details about what -effect a particular aspect hint would have.</p> -<p>You could think of an aspect hint as a richer alternative to a <a href="#common.tags">tag</a>: -while a tag conveys only a boolean state (the tag is either present or absent in the -<code>tags</code> list), an aspect hint can convey arbitrary structured information in its -<a href="/extending/rules#providers">providers</a>.</p> -<p>In practice, aspect hints are used for interoperability between different language-specific -rule sets. For example, imagine you have a <code>mylang_binary</code> target which needs to depend -on an <code>otherlang_library</code> target. The MyLang-specific logic needs some additional -information about the OtherLang target in order to use it, but <code>otherlang_library</code> -doesn't provide this information because it knows nothing about MyLang. One solution might be for -the MyLang rule set to define a <code>mylang_hint</code> rule which can be used to encode that -additional information; the user can add the hint to their <code>otherlang_library</code>'s -<code>aspect_hints</code>, and <code>mylang_binary</code> can use an aspect to collect the -additional information from a MyLang-specific provider in the <code>mylang_hint</code>.</p> -<p>For a concrete example, see -<a href="https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_interop_hint"><code>swift_interop_hint</code></a> -and <a href="https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_overlay"><code>swift_overlay</code></a> -in <code>rules_swift</code>.</p> -<p>Best practices:</p> -<ul> -<li>Targets listed in <code>aspect_hints</code> should be lightweight and minimal.</li> -<li>Language-specific logic should consider only aspect hints having providers relevant to that -language, and should ignore any other aspect hints.</li> -</ul></td> -</tr> -<tr> -<td id="common.compatible_with"><code>compatible_with</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; -<a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -<p>The list of environments this target can be built for, in addition to -default-supported environments.</p> -<p>This is part of Bazel's constraint system, which lets users declare which -targets can and cannot depend on each other. For example, externally deployable -binaries shouldn't depend on libraries with company-secret code. See -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46">ConstraintSemantics</a> for details.</p></td> -</tr> -<tr> -<td id="common.deprecation"><code>deprecation</code></td> -<td><p>String; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>None</code></p> -<p>An explanatory warning message associated with this target. -Typically this is used to notify users that a target has become obsolete, -or has become superseded by another rule, is private to a package, or is -perhaps considered harmful for some reason. It is a good idea to include -some reference (like a webpage, a bug number or example migration CLs) so -that one can easily find out what changes are required to avoid the message. -If there is a new target that can be used as a drop in replacement, it is a -good idea to just migrate all users of the old target.</p> -<p>This attribute has no effect on the way things are built, but it -may affect a build tool's diagnostic output. The build tool issues a -warning when a rule with a <code>deprecation</code> attribute is -depended upon by a target in another package.</p> -<p>Intra-package dependencies are exempt from this warning, so that, -for example, building the tests of a deprecated rule does not -encounter a warning.</p> -<p>If a deprecated target depends on another deprecated target, no warning -message is issued.</p> -<p>Once people have stopped using it, the target can be removed.</p></td> -</tr> -<tr> -<td id="common.exec_compatible_with"><code>exec_compatible_with</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; -<a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -<p>A list of -<a href="platforms-and-toolchains.html#constraint_value"><code>constraint_values</code></a> -that must be present in the execution platform of this target's default exec -group. This is in addition to any constraints already set by the rule type. -Constraints are used to restrict the list of available execution platforms. -For more details, see -the description of -<a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>. -and -<a href="/extending/exec-groups">exec groups</a></p></td> -</tr> -<tr> -<td id="common.exec_group_compatible_with"><code>exec_group_compatible_with</code></td> -<td><p>Dictionary of strings to lists of <a href="/concepts/labels">labels</a>; -<a href="#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> -<p>A dictionary of exec group names to lists of -<a href="platforms-and-toolchains.html#constraint_value"><code>constraint_values</code></a> -that must be present in the execution platform for the given exec group. This -is in addition to any constraints already set on the exec group's definition. -Constraints are used to restrict the list of available execution platforms. -For more details, see -the description of -<a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>. -and -<a href="/extending/exec-groups">exec groups</a></p></td> -</tr> -<tr> -<td id="common.exec_properties"><code>exec_properties</code></td> -<td><p>Dictionary of strings; default is <code>{}</code></p> -<p>A dictionary of strings that will be added to the <code>exec_properties</code> of a platform selected for this target. See <code>exec_properties</code> of the <a href="platforms-and-toolchains.html#platform">platform</a> rule.</p> -<p>If a key is present in both the platform and target-level properties, the value will be taken from the target.</p> -<p>Keys can be prefixed with the name of an execution group followed by a <code>.</code> to apply them only to that particular exec group.</p></td> -</tr> -<tr> -<td id="common.features"><code>features</code></td> -<td><p>List of <em>feature</em> strings; default is <code>[]</code></p> -<p>A feature is string tag that can be enabled or disabled on a target. The -meaning of a feature depends on the rule itself.</p> -<p>This <code>features</code> attribute is combined with the -<a href="/reference/be/functions.html#package">package</a> level <code>features</code> attribute. For example, if -the features ["a", "b"] are enabled on the package level, and a target's -<code>features</code> attribute contains ["-a", "c"], the features enabled for the -rule will be "b" and "c". -<a href="https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD">See example</a>.</p></td> -</tr> -<tr> -<td id="common.package_metadata"><code>package_metadata</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; -<a href="#configurable-attributes">nonconfigurable</a>; default is the package's -<a href="/reference/be/functions.html#package.default_package_metadata"><code>default_package_metadata</code></a></p> -<p>A list of labels that are associated metadata about this target. -Typically, the labels are simple rules that return a provider of -constant values. Rules and aspects may use these labels to perform some -additional analysis on the build graph.</p> -<p>The canonical use case is that of -<a href="https://github.com/bazelbuild/rules_license">rules_license</a>. -For that use case, <code>package_metadata</code> and -<code>default_package_metadata</code> is used to attach information -about a package's licence or version to targets. An aspect applied -to a top-level binary can be used to gather those and produce -compliance reports.</p></td> -</tr> -<tr> -<td id="common.restricted_to"><code>restricted_to</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; -<a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -<p>The list of environments this target can be built for, <em>instead</em> of -default-supported environments.</p> -<p>This is part of Bazel's constraint system. See -<a href="#common.compatible_with"><code>compatible_with</code></a> -for details.</p></td> -</tr> -<tr> -<td id="common.tags"><code>tags</code></td> -<td><p>List of strings; <a href="#configurable-attributes">nonconfigurable</a>; -default is <code>[]</code></p> -<p><em>Tags</em> can be used on any rule. <em>Tags</em> on test and -<code>test_suite</code> rules are useful for categorizing the tests. -<em>Tags</em> on non-test targets are used to control sandboxed execution of -<code>genrule</code>s and -<a href="/rules/concepts">Starlark</a> -actions, and for parsing by humans and/or external tools.</p> -<p>Bazel modifies the behavior of its sandboxing code if it finds the following -keywords in the <code>tags</code> attribute of any test or <code>genrule</code> -target, or the keys of <code>execution_requirements</code> for any Starlark -action.</p> -<ul> -<li><code>no-sandbox</code> keyword results in the action or test never being -sandboxed; it can still be cached or run remotely - use <code>no-cache</code> -or <code>no-remote</code> to prevent either or both of those.</li> -<li><code>no-cache</code> keyword results in the action or test never being -cached (locally or remotely). Note: for the purposes of this tag, the disk cache -is considered a local cache, whereas the HTTP and gRPC caches are considered -remote. Other caches, such as Skyframe or the persistent action cache, are not -affected.</li> -<li><code>no-remote-cache</code> keyword results in the action or test never being -cached remotely (but it may be cached locally; it may also be executed remotely). -Note: for the purposes of this tag, the disk cache is considered a local cache, -whereas the HTTP and gRPC caches are considered remote. Other caches, such as -Skyframe or the persistent action cache, are not affected. -If a combination of local disk cache and remote cache are used (combined cache), -it's treated as a remote cache and disabled entirely unless <code>--incompatible_remote_results_ignore_disk</code> -is set in which case the local components will be used.</li> -<li><code>no-remote-exec</code> keyword results in the action or test never being -executed remotely (but it may be cached remotely).</li> -<li><code>no-remote</code> keyword prevents the action or test from being executed remotely or -cached remotely. This is equivalent to using both -<code>no-remote-cache</code> and <code>no-remote-exec</code>.</li> -<li><code>no-remote-cache-upload</code> keyword disables upload part of remote caching of a spawn. -it does not disable remote execution.</li> -<li><code>local</code> keyword precludes the action or test from being remotely cached, -remotely executed, or run inside the sandbox. -For genrules and tests, marking the rule with the <code>local = True</code> -attribute has the same effect.</li> -<li><code>requires-network</code> keyword allows access to the external -network from inside the sandbox. This tag only has an effect if sandboxing -is enabled.</li> -<li><code>block-network</code> keyword blocks access to the external -network from inside the sandbox. In this case, only communication -with localhost is allowed. This tag only has an effect if sandboxing is -enabled.</li> -<li><code>requires-fakeroot</code> runs the test or action as uid and gid 0 (i.e., the root -user). This is only supported on Linux. This tag takes precedence over the -<code class="flag">--sandbox_fake_username</code> command-line option.</li> -</ul> -<p><em>Tags</em> on tests are generally used to annotate a test's role in your -debug and release process. Typically, tags are most useful for C++ and Python -tests, which lack any runtime annotation ability. The use of tags and size -elements gives flexibility in assembling suites of tests based around codebase -check-in policy.</p> -<p>Bazel modifies test running behavior if it finds the following keywords in the -<code>tags</code> attribute of the test rule:</p> -<ul> -<li><code>exclusive</code> will force the test to be run in the -"exclusive" mode, ensuring that no other tests are running at the -same time. Such tests will be executed in serial fashion after all build -activity and non-exclusive tests have been completed. Remote execution is -disabled for such tests because Bazel doesn't have control over what's -running on a remote machine.</li> -<li><code>exclusive-if-local</code> will force the test to be run in the -"exclusive" mode if it is executed locally, but will run the test in parallel if it's -executed remotely.</li> -<li><code>manual</code> keyword will exclude the target from expansion of target pattern wildcards -(<code>...</code>, <code>:*</code>, <code>:all</code>, etc.) and <code>test_suite</code> rules -which do not list the test explicitly when computing the set of top-level targets to build/run -for the <code>build</code>, <code>test</code>, and <code>coverage</code> commands. It does not -affect target wildcard or test suite expansion in other contexts, including the -<code>query</code> command. Note that <code>manual</code> does not imply that a target should -not be built/run automatically by continuous build/test systems. For example, it may be -desirable to exclude a target from <code>bazel test ...</code> because it requires specific -Bazel flags, but still have it included in properly-configured presubmit or continuous test -runs.</li> -<li><code>external</code> keyword will force test to be unconditionally -executed (regardless of <code class="flag">--cache_test_results</code> -value).</li> -</ul> -See -<a href="/reference/test-encyclopedia#tag-conventions">Tag Conventions</a> -in the Test Encyclopedia for more conventions on tags attached to test targets.</td> -</tr> -<tr> -<td id="common.target_compatible_with"><code>target_compatible_with</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<p>A list of -<a href="platforms-and-toolchains.html#constraint_value"><code>constraint_value</code></a>s -that must be present in the target platform for this target to be considered -<em>compatible</em>. This is in addition to any constraints already set by the -rule type. If the target platform does not satisfy all listed constraints then -the target is considered <em>incompatible</em>. Incompatible targets are -skipped for building and testing when the target pattern is expanded -(e.g. <code>//...</code>, <code>:all</code>). When explicitly specified on the -command line, incompatible targets cause Bazel to print an error and cause a -build or test failure.</p> -<p>Targets that transitively depend on incompatible targets are themselves -considered incompatible. They are also skipped for building and testing.</p> -<p>An empty list (which is the default) signifies that the target is compatible -with all platforms.</p> -<p>All rules other than <a href="workspace.html">Workspace Rules</a> support this -attribute. -For some rules this attribute has no effect. For example, specifying -<code>target_compatible_with</code> for a -<a href="c-cpp.html#cc_toolchain"><code>cc_toolchain</code></a> is not useful.</p> -<p>See the -<a href="/docs/platforms#skipping-incompatible-targets">Platforms</a> -page for more information about incompatible target skipping.</p></td> -</tr> -<tr> -<td id="common.testonly"><code>testonly</code></td> -<td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>False</code> -except for test and test suite targets</p> -<p>If <code>True</code>, only testonly targets (such as tests) can depend on this target.</p> -<p>Equivalently, a rule that is not <code>testonly</code> is not allowed to -depend on any rule that is <code>testonly</code>.</p> -<p>Tests (<code>*_test</code> rules) -and test suites (<a href="/reference/be/general.html#test_suite">test_suite</a> rules) -are <code>testonly</code> by default.</p> -<p>This attribute is intended to mean that the target should not be -contained in binaries that are released to production.</p> -<p>Because testonly is enforced at build time, not run time, and propagates -virally through the dependency tree, it should be applied judiciously. For -example, stubs and fakes that -are useful for unit tests may also be useful for integration tests -involving the same binaries that will be released to production, and -therefore should probably not be marked testonly. Conversely, rules that -are dangerous to even link in, perhaps because they unconditionally -override normal behavior, should definitely be marked testonly.</p></td> -</tr> -<tr> -<td id="common.toolchains"><code>toolchains</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; -<a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -<p>The set of targets whose <a href="/reference/be/make-variables">Make variables</a> this target is -allowed to access. These targets are either instances of rules that provide -<code>TemplateVariableInfo</code> or special targets for toolchain types built into Bazel. These -include:</p> -<ul> -<li><code>@bazel_tools//tools/cpp:toolchain_type</code></li> -<li><code>@rules_java//toolchains:current_java_runtime</code></li> -</ul> -<p>Note that this is distinct from the concept of -<a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a> -that is used by rule implementations for platform-dependent configuration. You cannot use this -attribute to determine which specific <code>cc_toolchain</code> or <code>java_toolchain</code> a -target will use.</p></td> -</tr> -<tr> -<td id="common.visibility"><code>visibility</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; -<a href="#configurable-attributes">nonconfigurable</a>; -default varies</p> -<p>The <code>visibility</code> attribute controls whether the target can be -depended on by targets in other locations. See the documentation for -<a href="/concepts/visibility">visibility</a>.</p> -<p>For targets declared directly in a BUILD file or in legacy macros called from -a BUILD file, the default value is the package's -<a href="/reference/be/functions.html#package.default_visibility"><code>default_visibility</code></a> -if specified, or else <code>["//visibility:private"]</code>. For targets -declared in one or more symbolic macros, the default value is always just -<code>["//visibility:private"]</code> (which makes it useable only within the -package containing the macro's code).</p></td> -</tr> -</tbody> -</table> +| Attribute | Description | +| --- | --- | +| `aspect_hints` | List of [labels](./concepts/labels); default is `[]` A list of arbitrary labels which is exposed to [aspects](./extending/aspects) (in particular - aspects invoked by this rule's reverse dependencies), but isn't exposed to this rule's own implementation. Consult documentation for language-specific rule sets for details about what effect a particular aspect hint would have. You could think of an aspect hint as a richer alternative to a [tag](#common.tags): while a tag conveys only a boolean state (the tag is either present or absent in the `tags` list), an aspect hint can convey arbitrary structured information in its [providers](./extending/rules#providers). In practice, aspect hints are used for interoperability between different language-specific rule sets. For example, imagine you have a `mylang_binary` target which needs to depend on an `otherlang_library` target. The MyLang-specific logic needs some additional information about the OtherLang target in order to use it, but `otherlang_library` doesn't provide this information because it knows nothing about MyLang. One solution might be for the MyLang rule set to define a `mylang_hint` rule which can be used to encode that additional information; the user can add the hint to their `otherlang_library`'s `aspect_hints`, and `mylang_binary` can use an aspect to collect the additional information from a MyLang-specific provider in the `mylang_hint`. For a concrete example, see [`swift_interop_hint`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_interop_hint) and [`swift_overlay`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_overlay) in `rules_swift`. Best practices: * Targets listed in `aspect_hints` should be lightweight and minimal. * Language-specific logic should consider only aspect hints having providers relevant to that language, and should ignore any other aspect hints. | +| `compatible_with` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The list of environments this target can be built for, in addition to default-supported environments. This is part of Bazel's constraint system, which lets users declare which targets can and cannot depend on each other. For example, externally deployable binaries shouldn't depend on libraries with company-secret code. See [ConstraintSemantics](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46) for details. | +| `deprecation` | String; [nonconfigurable](#configurable-attributes); default is `None` An explanatory warning message associated with this target. Typically this is used to notify users that a target has become obsolete, or has become superseded by another rule, is private to a package, or is perhaps considered harmful for some reason. It is a good idea to include some reference (like a webpage, a bug number or example migration CLs) so that one can easily find out what changes are required to avoid the message. If there is a new target that can be used as a drop in replacement, it is a good idea to just migrate all users of the old target. This attribute has no effect on the way things are built, but it may affect a build tool's diagnostic output. The build tool issues a warning when a rule with a `deprecation` attribute is depended upon by a target in another package. Intra-package dependencies are exempt from this warning, so that, for example, building the tests of a deprecated rule does not encounter a warning. If a deprecated target depends on another deprecated target, no warning message is issued. Once people have stopped using it, the target can be removed. | +| `exec_compatible_with` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` A list of `constraint_values` that must be present in the execution platform of this target's default exec group. This is in addition to any constraints already set by the rule type. Constraints are used to restrict the list of available execution platforms. For more details, see the description of [toolchain resolution](./docs/toolchains#toolchain-resolution). and [exec groups](./extending/exec-groups) | +| `exec_group_compatible_with` | Dictionary of strings to lists of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `\{\}` A dictionary of exec group names to lists of `constraint_values` that must be present in the execution platform for the given exec group. This is in addition to any constraints already set on the exec group's definition. Constraints are used to restrict the list of available execution platforms. For more details, see the description of [toolchain resolution](./docs/toolchains#toolchain-resolution). and [exec groups](./extending/exec-groups) | +| `exec_properties` | Dictionary of strings; default is `\{\}` A dictionary of strings that will be added to the `exec_properties` of a platform selected for this target. See `exec_properties` of the [platform](platforms-and-toolchains.html#platform) rule. If a key is present in both the platform and target-level properties, the value will be taken from the target. Keys can be prefixed with the name of an execution group followed by a `.` to apply them only to that particular exec group. | +| `features` | List of *feature* strings; default is `[]` A feature is string tag that can be enabled or disabled on a target. The meaning of a feature depends on the rule itself. This `features` attribute is combined with the [package](./reference/be/functions.html#package) level `features` attribute. For example, if the features ["a", "b"] are enabled on the package level, and a target's `features` attribute contains ["-a", "c"], the features enabled for the rule will be "b" and "c". [See example](https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD). | +| `package_metadata` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is the package's `default_package_metadata` A list of labels that are associated metadata about this target. Typically, the labels are simple rules that return a provider of constant values. Rules and aspects may use these labels to perform some additional analysis on the build graph. The canonical use case is that of [rules\_license](https://github.com/bazelbuild/rules_license). For that use case, `package_metadata` and `default_package_metadata` is used to attach information about a package's licence or version to targets. An aspect applied to a top-level binary can be used to gather those and produce compliance reports. | +| `restricted_to` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The list of environments this target can be built for, *instead* of default-supported environments. This is part of Bazel's constraint system. See `compatible_with` for details. | +| `tags` | List of strings; [nonconfigurable](#configurable-attributes); default is `[]` *Tags* can be used on any rule. *Tags* on test and `test_suite` rules are useful for categorizing the tests. *Tags* on non-test targets are used to control sandboxed execution of `genrule`s and [Starlark](./rules/concepts) actions, and for parsing by humans and/or external tools. Bazel modifies the behavior of its sandboxing code if it finds the following keywords in the `tags` attribute of any test or `genrule` target, or the keys of `execution_requirements` for any Starlark action. * `no-sandbox` keyword results in the action or test never being sandboxed; it can still be cached or run remotely - use `no-cache` or `no-remote` to prevent either or both of those. * `no-cache` keyword results in the action or test never being cached (locally or remotely). Note: for the purposes of this tag, the disk cache is considered a local cache, whereas the HTTP and gRPC caches are considered remote. Other caches, such as Skyframe or the persistent action cache, are not affected. * `no-remote-cache` keyword results in the action or test never being cached remotely (but it may be cached locally; it may also be executed remotely). Note: for the purposes of this tag, the disk cache is considered a local cache, whereas the HTTP and gRPC caches are considered remote. Other caches, such as Skyframe or the persistent action cache, are not affected. If a combination of local disk cache and remote cache are used (combined cache), it's treated as a remote cache and disabled entirely unless `--incompatible_remote_results_ignore_disk` is set in which case the local components will be used. * `no-remote-exec` keyword results in the action or test never being executed remotely (but it may be cached remotely). * `no-remote` keyword prevents the action or test from being executed remotely or cached remotely. This is equivalent to using both `no-remote-cache` and `no-remote-exec`. * `no-remote-cache-upload` keyword disables upload part of remote caching of a spawn. it does not disable remote execution. * `local` keyword precludes the action or test from being remotely cached, remotely executed, or run inside the sandbox. For genrules and tests, marking the rule with the `local = True` attribute has the same effect. * `requires-network` keyword allows access to the external network from inside the sandbox. This tag only has an effect if sandboxing is enabled. * `block-network` keyword blocks access to the external network from inside the sandbox. In this case, only communication with localhost is allowed. This tag only has an effect if sandboxing is enabled. * `requires-fakeroot` runs the test or action as uid and gid 0 (i.e., the root user). This is only supported on Linux. This tag takes precedence over the `--sandbox_fake_username` command-line option. *Tags* on tests are generally used to annotate a test's role in your debug and release process. Typically, tags are most useful for C++ and Python tests, which lack any runtime annotation ability. The use of tags and size elements gives flexibility in assembling suites of tests based around codebase check-in policy. Bazel modifies test running behavior if it finds the following keywords in the `tags` attribute of the test rule: * `exclusive` will force the test to be run in the "exclusive" mode, ensuring that no other tests are running at the same time. Such tests will be executed in serial fashion after all build activity and non-exclusive tests have been completed. Remote execution is disabled for such tests because Bazel doesn't have control over what's running on a remote machine. * `exclusive-if-local` will force the test to be run in the "exclusive" mode if it is executed locally, but will run the test in parallel if it's executed remotely. * `manual` keyword will exclude the target from expansion of target pattern wildcards (`...`, `:*`, `:all`, etc.) and `test_suite` rules which do not list the test explicitly when computing the set of top-level targets to build/run for the `build`, `test`, and `coverage` commands. It does not affect target wildcard or test suite expansion in other contexts, including the `query` command. Note that `manual` does not imply that a target should not be built/run automatically by continuous build/test systems. For example, it may be desirable to exclude a target from `bazel test ...` because it requires specific Bazel flags, but still have it included in properly-configured presubmit or continuous test runs. * `external` keyword will force test to be unconditionally executed (regardless of `--cache_test_results` value). See [Tag Conventions](./reference/test-encyclopedia#tag-conventions) in the Test Encyclopedia for more conventions on tags attached to test targets. | +| `target_compatible_with` | List of [labels](./concepts/labels); default is `[]` A list of `constraint_value`s that must be present in the target platform for this target to be considered *compatible*. This is in addition to any constraints already set by the rule type. If the target platform does not satisfy all listed constraints then the target is considered *incompatible*. Incompatible targets are skipped for building and testing when the target pattern is expanded (e.g. `//...`, `:all`). When explicitly specified on the command line, incompatible targets cause Bazel to print an error and cause a build or test failure. Targets that transitively depend on incompatible targets are themselves considered incompatible. They are also skipped for building and testing. An empty list (which is the default) signifies that the target is compatible with all platforms. All rules other than [Workspace Rules](workspace.mdx) support this attribute. For some rules this attribute has no effect. For example, specifying `target_compatible_with` for a `cc_toolchain` is not useful. See the [Platforms](./docs/platforms#skipping-incompatible-targets) page for more information about incompatible target skipping. | +| `testonly` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` except for test and test suite targets If `True`, only testonly targets (such as tests) can depend on this target. Equivalently, a rule that is not `testonly` is not allowed to depend on any rule that is `testonly`. Tests (`*_test` rules) and test suites ([test\_suite](./reference/be/general.html#test_suite) rules) are `testonly` by default. This attribute is intended to mean that the target should not be contained in binaries that are released to production. Because testonly is enforced at build time, not run time, and propagates virally through the dependency tree, it should be applied judiciously. For example, stubs and fakes that are useful for unit tests may also be useful for integration tests involving the same binaries that will be released to production, and therefore should probably not be marked testonly. Conversely, rules that are dangerous to even link in, perhaps because they unconditionally override normal behavior, should definitely be marked testonly. | +| `toolchains` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The set of targets whose [Make variables](./reference/be/make-variables) this target is allowed to access. These targets are either instances of rules that provide `TemplateVariableInfo` or special targets for toolchain types built into Bazel. These include: * `@bazel_tools//tools/cpp:toolchain_type`* `@rules_java//toolchains:current_java_runtime` Note that this is distinct from the concept of [toolchain resolution](./docs/toolchains#toolchain-resolution) that is used by rule implementations for platform-dependent configuration. You cannot use this attribute to determine which specific `cc_toolchain` or `java_toolchain` a target will use. | +| `visibility` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default varies The `visibility` attribute controls whether the target can be depended on by targets in other locations. See the documentation for [visibility](./concepts/visibility). For targets declared directly in a BUILD file or in legacy macros called from a BUILD file, the default value is the package's `default_visibility` if specified, or else `["//visibility:private"]`. For targets declared in one or more symbolic macros, the default value is always just `["//visibility:private"]` (which makes it useable only within the package containing the macro's code). | ## Attributes common to all test rules (\*\_test) This section describes attributes that are common to all test rules. -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th>Attribute</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="test.args"><code>args</code></td> -<td><p>List of strings; subject to -<a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and -<a href="/reference/be/make-variables">"Make variable"</a> substitution, and -<a href="#sh-tokenization">Bourne shell tokenization</a>; default is <code>[]</code></p> -<p>Command line arguments that Bazel passes to the target when it is -executed with <code>bazel test</code>.</p> -<p>These arguments are passed before any <code>--test_arg</code> values -specified on the <code>bazel test</code> command line.</p></td> -</tr> -<tr> -<td id="test.env"><code>env</code></td> -<td><p>Dictionary of strings; values are subject to -<a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and -<a href="/reference/be/make-variables">"Make variable"</a> substitution; default is <code>{}</code></p> -<p>Specifies additional environment variables to set when the test is executed by -<code>bazel test</code>.</p> -<p>This attribute only applies to native rules, like <code>cc_test</code>, -<code>py_test</code>, and <code>sh_test</code>. It does not apply to -Starlark-defined test rules. For your own Starlark rules, you can add an "env" -attribute and use it to populate a -<a href="/rules/lib/providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> -Provider.</p> -<a href="/rules/lib/toplevel/testing#TestEnvironment">TestEnvironment</a> -Provider.</td> -</tr> -<tr> -<td id="test.env_inherit"><code>env_inherit</code></td> -<td><p>List of strings; default is <code>[]</code></p> -<p>Specifies additional environment variables to inherit from the -external environment when the test is executed by <code>bazel test</code>.</p> -<p>This attribute only applies to native rules, like <code>cc_test</code>, <code>py_test</code>, -and <code>sh_test</code>. It does not apply to Starlark-defined test rules.</p></td> -</tr> -<tr> -<td id="test.size"><code>size</code></td> -<td><p>String <code>"enormous"</code>, <code>"large"</code>, <code>"medium"</code>, or -<code>"small"</code>; <a href="#configurable-attributes">nonconfigurable</a>; -default is <code>"medium"</code></p> -<p>Specifies a test target's "heaviness": how much time/resources it needs to run.</p> -<p>Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or -"enormous". Bazel uses the size to determine a default timeout, which can be overridden using the -<code>timeout</code> attribute. The timeout is for all tests in the BUILD target, not for each -individual test. When the test is run locally, the <code>size</code> is additionally used for -scheduling purposes: Bazel tries to respect <code>--local_{ram,cpu}_resources</code> and not -overwhelm the local machine by running lots of heavy tests at the same time.</p> -<p>Test sizes correspond to the following default timeouts and assumed peak local resource -usages:</p> -<table style="width: 100%"> -<thead> -<tr> -<th>Size</th> -<th>RAM (in MB)</th> -<th>CPU (in CPU cores)</th> -<th>Default timeout</th> -</tr> -</thead> -<tbody> -<tr> -<td>small</td> -<td>20</td> -<td>1</td> -<td>short (1 minute)</td> -</tr> -<tr> -<td>medium</td> -<td>100</td> -<td>1</td> -<td>moderate (5 minutes)</td> -</tr> -<tr> -<td>large</td> -<td>300</td> -<td>1</td> -<td>long (15 minutes)</td> -</tr> -<tr> -<td>enormous</td> -<td>800</td> -<td>1</td> -<td>eternal (60 minutes)</td> -</tr> -</tbody> -</table> -<p>The environment variable -<a href="/reference/test-encyclopedia#initial-conditions"><code>TEST_SIZE</code></a> will be set to -the value of this attribute when spawning the test.</p></td> -</tr> -<tr> -<td id="test.timeout"><code>timeout</code></td> -<td><p>String <code>"short"</code>, <code>"moderate"</code>, <code>"long"</code>, or -<code>"eternal"</code>; <a href="#configurable-attributes">nonconfigurable</a>; default is derived -from the test's <code>size</code> attribute</p> -<p>How long the test is expected to run before returning.</p> -<p>While a test's size attribute controls resource estimation, a test's -timeout may be set independently. If not explicitly specified, the -timeout is based on the <a href="#test.size">test's size</a>. The test -timeout can be overridden with the <code>--test_timeout</code> flag, e.g. for -running under certain conditions which are known to be slow. Test timeout values -correspond to the following time periods:</p> -<table style="width: 100%"> -<thead> -<tr> -<th>Timeout Value</th> -<th>Time Period</th> -</tr> -</thead> -<tbody> -<tr> -<td>short</td> -<td>1 minute</td> -</tr> -<tr> -<td>moderate</td> -<td>5 minutes</td> -</tr> -<tr> -<td>long</td> -<td>15 minutes</td> -</tr> -<tr> -<td>eternal</td> -<td>60 minutes</td> -</tr> -</tbody> -</table> -<p>For times other than the above, the test timeout can be overridden with the -<code>--test_timeout</code> bazel flag, e.g. for manually running under -conditions which are known to be slow. The <code>--test_timeout</code> values -are in seconds. For example <code>--test_timeout=120</code> will set the test -timeout to two minutes.</p> -<p>The environment variable -<a href="/reference/test-encyclopedia#initial-conditions"><code>TEST_TIMEOUT</code></a> will be set -to the test timeout (in seconds) when spawning the test.</p></td> -</tr> -<tr> -<td id="test.flaky"><code>flaky</code></td> -<td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; -default is <code>False</code></p> -<p>Marks test as flaky.</p> -<p>If set, executes the test up to three times, marking it as failed only if it -fails each time. By default, this attribute is set to False and the test is -executed only once. Note, that use of this attribute is generally discouraged - -tests should pass reliably when their assertions are upheld.</p></td> -</tr> -<tr> -<td id="test.shard_count"><code>shard_count</code></td> -<td><p>Non-negative integer less than or equal to 50; default is <code>-1</code></p> -<p>Specifies the number of parallel shards -to use to run the test.</p> -<p>If set, this value will override any heuristics used to determine the number of -parallel shards with which to run the test. Note that for some test -rules, this parameter may be required to enable sharding -in the first place. Also see <code>--test_sharding_strategy</code>.</p> -<p>If test sharding is enabled, the environment variable <code> </code><a href="/reference/test-encyclopedia#initial-conditions"><code>TEST_TOTAL_SHARDS</code></a><code> </code> will be set to this value when spawning the test.</p> -<p>Sharding requires the test runner to support the test sharding protocol. -If it does not, then it will most likely run every test in every shard, which -is not what you want.</p> -<p>See -<a href="/reference/test-encyclopedia#test-sharding">Test Sharding</a> -in the Test Encyclopedia for details on sharding.</p></td> -</tr> -<tr> -<td id="test.local"><code>local</code></td> -<td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; -default is <code>False</code></p> -<p>Forces the test to be run locally, without sandboxing.</p> -<p>Setting this to True is equivalent to providing "local" as a tag -(<code>tags=["local"]</code>).</p></td> -</tr> -</tbody> -</table> +| Attribute | Description | +| --- | --- | +| `args` | List of strings; subject to [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make variable"](./reference/be/make-variables) substitution, and [Bourne shell tokenization](#sh-tokenization); default is `[]` Command line arguments that Bazel passes to the target when it is executed with `bazel test`. These arguments are passed before any `--test_arg` values specified on the `bazel test` command line. | +| `env` | Dictionary of strings; values are subject to [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make variable"](./reference/be/make-variables) substitution; default is `\{\}` Specifies additional environment variables to set when the test is executed by `bazel test`. This attribute only applies to native rules, like `cc_test`, `py_test`, and `sh_test`. It does not apply to Starlark-defined test rules. For your own Starlark rules, you can add an "env" attribute and use it to populate a [RunEnvironmentInfo](./rules/lib/providers/RunEnvironmentInfo.mdx) Provider. [TestEnvironment](./rules/lib/toplevel/testing#TestEnvironment) Provider. | +| `env_inherit` | List of strings; default is `[]` Specifies additional environment variables to inherit from the external environment when the test is executed by `bazel test`. This attribute only applies to native rules, like `cc_test`, `py_test`, and `sh_test`. It does not apply to Starlark-defined test rules. | +| `size` | String `"enormous"`, `"large"`, `"medium"`, or `"small"`; [nonconfigurable](#configurable-attributes); default is `"medium"` Specifies a test target's "heaviness": how much time/resources it needs to run. Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or "enormous". Bazel uses the size to determine a default timeout, which can be overridden using the `timeout` attribute. The timeout is for all tests in the BUILD target, not for each individual test. When the test is run locally, the `size` is additionally used for scheduling purposes: Bazel tries to respect `--local_\{ram,cpu\}_resources` and not overwhelm the local machine by running lots of heavy tests at the same time. Test sizes correspond to the following default timeouts and assumed peak local resource usages: | Size | RAM (in MB) | CPU (in CPU cores) | Default timeout | | --- | --- | --- | --- | | small | 20 | 1 | short (1 minute) | | medium | 100 | 1 | moderate (5 minutes) | | large | 300 | 1 | long (15 minutes) | | enormous | 800 | 1 | eternal (60 minutes) | The environment variable `TEST_SIZE` will be set to the value of this attribute when spawning the test. | +| `timeout` | String `"short"`, `"moderate"`, `"long"`, or `"eternal"`; [nonconfigurable](#configurable-attributes); default is derived from the test's `size` attribute How long the test is expected to run before returning. While a test's size attribute controls resource estimation, a test's timeout may be set independently. If not explicitly specified, the timeout is based on the [test's size](#test.size). The test timeout can be overridden with the `--test_timeout` flag, e.g. for running under certain conditions which are known to be slow. Test timeout values correspond to the following time periods: | Timeout Value | Time Period | | --- | --- | | short | 1 minute | | moderate | 5 minutes | | long | 15 minutes | | eternal | 60 minutes | For times other than the above, the test timeout can be overridden with the `--test_timeout` bazel flag, e.g. for manually running under conditions which are known to be slow. The `--test_timeout` values are in seconds. For example `--test_timeout=120` will set the test timeout to two minutes. The environment variable `TEST_TIMEOUT` will be set to the test timeout (in seconds) when spawning the test. | +| `flaky` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` Marks test as flaky. If set, executes the test up to three times, marking it as failed only if it fails each time. By default, this attribute is set to False and the test is executed only once. Note, that use of this attribute is generally discouraged - tests should pass reliably when their assertions are upheld. | +| `shard_count` | Non-negative integer less than or equal to 50; default is `-1` Specifies the number of parallel shards to use to run the test. If set, this value will override any heuristics used to determine the number of parallel shards with which to run the test. Note that for some test rules, this parameter may be required to enable sharding in the first place. Also see `--test_sharding_strategy`. If test sharding is enabled, the environment variable `TEST_TOTAL_SHARDS` will be set to this value when spawning the test. Sharding requires the test runner to support the test sharding protocol. If it does not, then it will most likely run every test in every shard, which is not what you want. See [Test Sharding](./reference/test-encyclopedia#test-sharding) in the Test Encyclopedia for details on sharding. | +| `local` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` Forces the test to be run locally, without sandboxing. Setting this to True is equivalent to providing "local" as a tag (`tags=["local"]`). | ## Attributes common to all binary rules (\*\_binary) This section describes attributes that are common to all binary rules. -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th>Attribute</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="binary.args"><code>args</code></td> -<td><p>List of strings; subject to -<a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and -<a href="/reference/be/make-variables">"Make variable"</a> substitution, and -<a href="#sh-tokenization">Bourne shell tokenization</a>; -<a href="#configurable-attributes">nonconfigurable</a>; -default is <code>[]</code></p> -<p>Command line arguments that Bazel will pass to the target when it is executed -either by the <code>run</code> command or as a test. These arguments are -passed before the ones that are specified on the <code>bazel run</code> or -<code>bazel test</code> command line.</p> -<p><em>NOTE: The arguments are not passed when you run the target -outside of Bazel (for example, by manually executing the binary in -<code>bazel-bin/</code>).</em></p></td> -</tr> -<tr> -<td id="binary.env"><code>env</code></td> -<td><p>Dictionary of strings; values are subject to -<a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and -<a href="/reference/be/make-variables">"Make variable"</a> substitution; default is <code>{}</code></p> -<p>Specifies additional environment variables to set when the target is -executed by <code>bazel run</code>.</p> -<p>This attribute only applies to native rules, like <code>cc_binary</code>, <code>py_binary</code>, -and <code>sh_binary</code>. It does not apply to Starlark-defined executable rules. For your own -Starlark rules, you can add an "env" attribute and use it to populate a -<a href="/rules/lib/providers/RunEnvironmentInfo.html">RunEnvironmentInfo</a> -Provider.</p> -<p><em>NOTE: The environment variables are not set when you run the target -outside of Bazel (for example, by manually executing the binary in -<code>bazel-bin/</code>).</em></p></td> -</tr> -<tr> -<td id="binary.output_licenses"><code>output_licenses</code></td> -<td><p>List of strings; default is <code>[]</code></p> -<p>The licenses of the output files that this binary generates. -This is part of a deprecated licensing API that Bazel no longer uses. Don't -use this.</p></td> -</tr> -</tbody> -</table> +| Attribute | Description | +| --- | --- | +| `args` | List of strings; subject to [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make variable"](./reference/be/make-variables) substitution, and [Bourne shell tokenization](#sh-tokenization); [nonconfigurable](#configurable-attributes); default is `[]` Command line arguments that Bazel will pass to the target when it is executed either by the `run` command or as a test. These arguments are passed before the ones that are specified on the `bazel run` or `bazel test` command line. *NOTE: The arguments are not passed when you run the target outside of Bazel (for example, by manually executing the binary in `bazel-bin/`).* | +| `env` | Dictionary of strings; values are subject to [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make variable"](./reference/be/make-variables) substitution; default is `\{\}` Specifies additional environment variables to set when the target is executed by `bazel run`. This attribute only applies to native rules, like `cc_binary`, `py_binary`, and `sh_binary`. It does not apply to Starlark-defined executable rules. For your own Starlark rules, you can add an "env" attribute and use it to populate a [RunEnvironmentInfo](./rules/lib/providers/RunEnvironmentInfo.mdx) Provider. *NOTE: The environment variables are not set when you run the target outside of Bazel (for example, by manually executing the binary in `bazel-bin/`).* | +| `output_licenses` | List of strings; default is `[]` The licenses of the output files that this binary generates. This is part of a deprecated licensing API that Bazel no longer uses. Don't use this. | ## Configurable attributes @@ -712,29 +125,28 @@ architectures. Running `bazel build :multiplatform_lib --cpu x86` will build the target using `x86_impl.cc`, while substituting `--cpu arm` will instead cause it to use `arm_impl.cc`. -``` code - +``` cc_library( name = "multiplatform_lib", - srcs = select({ + srcs = select(\{ ":x86_mode": ["x86_impl.cc"], ":arm_mode": ["arm_impl.cc"] - }) + \}) ) config_setting( name = "x86_mode", - values = { "cpu": "x86" } + values = \{ "cpu": "x86" \} ) config_setting( name = "arm_mode", - values = { "cpu": "arm" } + values = \{ "cpu": "arm" \} ) ``` -The [`select()`](/reference/be/functions.html#select) function +The [`select()`](./reference/be/functions.html#select) function chooses among different alternative values for a configurable attribute based -on which [`config_setting`](/reference/be/general.html#config_setting) -or [`constraint_value`](/reference/be/platforms-and-toolchains.html#constraint_value) +on which [`config_setting`](./reference/be/general.html#config_setting) +or [`constraint_value`](./reference/be/platforms-and-toolchains.html#constraint_value) criteria the target's configuration satisfies. Bazel evaluates configurable attributes after processing macros and before @@ -752,8 +164,7 @@ use this feature. Usually an attribute is nonconfigurable because Bazel internally needs to know its value before it can determine how to resolve a `select()`. -See -[Configurable Build Attributes](https://bazel.build/docs/configurable-attributes) for a detailed overview. +See [Configurable Build Attributes](https://bazel.build/docs/configurable-attributes) for a detailed overview. ## Implicit output targets @@ -785,7 +196,7 @@ outputs entailed by a declaration of that kind of rule. An important but somewhat subtle distinction between the two namespaces used by the build system: -[labels](/concepts/labels) identify *targets*, +[labels](./concepts/labels) identify *targets*, which may be rules or files, and file targets may be divided into either source (or input) file targets and derived (or output) file targets. These are the things you can mention in BUILD files, @@ -798,4 +209,4 @@ example, `.o` object files produced during C++ compilation cannot be referenced from within BUILD files or from the command line. In this way, the build tool may hide certain implementation details of how it does its job. This is explained more fully in -the [BUILD Concept Reference](/concepts/build-ref). +the [BUILD Concept Reference](./concepts/build-ref). \ No newline at end of file diff --git a/reference/be/extra-actions.mdx b/reference/be/extra-actions.mdx index e432ad5..89ea49f 100644 --- a/reference/be/extra-actions.mdx +++ b/reference/be/extra-actions.mdx @@ -2,21 +2,17 @@ title: 'extra-actions' --- -# Extra Actions Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} ## Rules -- [action_listener](#action_listener) -- [extra_action](#extra_action) +* [action\_listener](#action_listener) +* [extra\_action](#extra_action) -## action_listener +## action\_listener -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java) -``` rule-signature +``` action_listener(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, extra_actions, features, licenses, mnemonics, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) ``` @@ -26,81 +22,56 @@ instead. An `action_listener` rule doesn't produce any output itself. Instead, it allows tool developers to insert -[`extra_action`](/reference/be/extra-actions.html#extra_action)s into the build system, -by providing a mapping from action to [`extra_action`](/reference/be/extra-actions.html#extra_action) -. +[`extra_action`](./reference/be/extra-actions.html#extra_action)s into the build system, +by providing a mapping from action to [`extra_action`](./reference/be/extra-actions.html#extra_action). This rule's arguments map action mnemonics to -[`extra_action`](/reference/be/extra-actions.html#extra_action) rules. +[`extra_action`](./reference/be/extra-actions.html#extra_action) rules. -By specifying the option -[`--experimental_action_listener=<label>`](/docs/user-manual#flag--experimental_action_listener), +By specifying the option [`--experimental_action_listener=<label>`](./docs/user-manual#flag--experimental_action_listener), the build will use the specified `action_listener` to insert -[`extra_action`](/reference/be/extra-actions.html#extra_action)s into the build graph. +[`extra_action`](./reference/be/extra-actions.html#extra_action)s into the build graph. #### Example - - action_listener( - name = "index_all_languages", - mnemonics = [ - "Javac", - "CppCompile", - "Python", - ], - extra_actions = [":indexer"], - ) - - action_listener( - name = "index_java", - mnemonics = ["Javac"], - extra_actions = [":indexer"], - ) - - extra_action( - name = "indexer", - tools = ["//my/tools:indexer"], - cmd = "$(location //my/tools:indexer)" + - "--extra_action_file=$(EXTRA_ACTION_FILE)", - ) +``` +action_listener( + name = "index_all_languages", + mnemonics = [ + "Javac", + "CppCompile", + "Python", + ], + extra_actions = [":indexer"], +) + +action_listener( + name = "index_java", + mnemonics = ["Javac"], + extra_actions = [":indexer"], +) + +extra_action( + name = "indexer", + tools = ["//my/tools:indexer"], + cmd = "$(location //my/tools:indexer)" + + "--extra_action_file=$(EXTRA_ACTION_FILE)", +) +``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="action_listener.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="action_listener.extra_actions"><code>extra_actions</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; required</p> -A list of <a href="/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a> targets -this <code>action_listener</code> should add to the build graph. -E.g. <code>[ "//my/tools:analyzer" ]</code>.</td> -</tr> -<tr> -<td id="action_listener.mnemonics"><code>mnemonics</code></td> -<td><p>List of strings; required</p> -A list of action mnemonics this <code>action_listener</code> should listen -for, e.g. <code>[ "Javac" ]</code>. -<p>Mnemonics are not a public interface. -There's no guarantee that the mnemonics and their actions don't change.</p></td> -</tr> -</tbody> -</table> - -## extra_action - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ExtraActionRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `extra_actions` | List of [labels](./concepts/labels); required A list of `extra_action` targets this `action_listener` should add to the build graph. E.g. `[ "//my/tools:analyzer" ]`. | +| `mnemonics` | List of strings; required A list of action mnemonics this `action_listener` should listen for, e.g. `[ "Javac" ]`. Mnemonics are not a public interface. There's no guarantee that the mnemonics and their actions don't change. | + +## extra\_action + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ExtraActionRule.java) + +``` extra_action(name, data, aspect_hints, cmd, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, out_templates, package_metadata, requires_action_output, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility) ``` @@ -112,14 +83,14 @@ An `extra_action` rule doesn't produce any meaningful output when specified as a regular build target. Instead, it allows tool developers to insert additional actions into the build graph that shadow existing actions. -See [`action_listener`](/reference/be/extra-actions.html#action_listener) for details +See [`action_listener`](./reference/be/extra-actions.html#action_listener) for details on how to enable `extra_action`s. The `extra_action`s run as a command-line. The command-line tool gets -access to a file containing a protocol buffer as \$(EXTRA_ACTION_FILE) +access to a file containing a protocol buffer as $(EXTRA\_ACTION\_FILE) with detailed information on the original action it is shadowing. It also has access to all the input files the original action has access to. -See `extra_actions_base.proto` +See extra\_actions\_base.proto for details on the data stored inside the protocol buffer. Each proto file contains an ExtraActionInfo message. @@ -127,71 +98,10 @@ Just like all other actions, extra actions are sandboxed, and should be designed ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="extra_action.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p> -You may refer to this rule by <code>label</code> in the <code>extra_actions</code> argument -of <a href="/reference/be/extra-actions.html#action_listener"><code> action_listener</code></a> rules.</td> -</tr> -<tr> -<td id="extra_action.cmd"><code>cmd</code></td> -<td><p>String; required</p> -The command to run. -<p>Like <a href="/reference/be/general.html#genrule.cmd">genrule cmd attribute</a> with the following -differences:</p> -<ol> -<li><p>No heuristic label expansion. Only labels using $(location ...) are expanded.</p></li> -<li><p>An additional pass is applied to the string to replace all -occurrences of the outputs created from the <code>out_templates</code> -attribute. All occurrences of <code>$(output </code><em><code>out_template</code></em><code>)</code> -are replaced with the path to the file denoted by <code>label</code>.</p> -<p>E.g. out_template <code>$(ACTION_ID).analysis</code> -can be matched with <code>$(output $(ACTION_ID).analysis)</code>.</p> -<p>In effect, this is the same substitution as <code>$(location)</code> -but with a different scope.</p></li> -</ol></td> -</tr> -<tr> -<td id="extra_action.out_templates"><code>out_templates</code></td> -<td><p>List of strings; default is <code>[]</code></p> -A list of templates for files generated by the <code>extra_action</code> command. -<p>The template can use the following variables:</p> -<ul> -<li>$(ACTION_ID), an id uniquely identifying this <code>extra_action</code>. -Used to generate a unique output file.</li> -</ul></td> -</tr> -<tr> -<td id="extra_action.requires_action_output"><code>requires_action_output</code></td> -<td><p>Boolean; default is <code>False</code></p> -Indicates this <code>extra_action</code> requires the output of the -original action to be present as input to this <code>extra_action</code>. -<p>When true (default false), the extra_action can assume that the -original action outputs are available as part of its inputs.</p></td> -</tr> -<tr> -<td id="extra_action.tools"><code>tools</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of <code>tool</code> dependencies for this rule. -<p>See the definition of <a href="/concepts/build-ref#deps">dependencies</a> for more -information.</p> -<p>The build system ensures these prerequisites are built before running the -<code>extra_action</code> command; they are built using the -<a href="/docs/user-manual#configurations"><code>exec</code>configuration</a>, -since they must run as a tool during the build itself. The path of an individual -<code>tools</code> target <code>//x:y</code> can be obtained using -<code>$(location //x:y)</code>.</p> -<p>All tools and their data dependencies are consolidated into a single tree -within which the command can use relative paths. The working directory will -be the root of that unified tree.</p></td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. You may refer to this rule by `label` in the `extra_actions` argument of [`action_listener`](./reference/be/extra-actions.html#action_listener) rules. | +| `cmd` | String; required The command to run. Like [genrule cmd attribute](./reference/be/general.html#genrule.cmd) with the following differences: 1. No heuristic label expansion. Only labels using $(location ...) are expanded. 2. An additional pass is applied to the string to replace all occurrences of the outputs created from the `out_templates` attribute. All occurrences of `$(output out_template)` are replaced with the path to the file denoted by `label`. E.g. out\_template `$(ACTION_ID).analysis` can be matched with `$(output $(ACTION_ID).analysis)`. In effect, this is the same substitution as `$(location)` but with a different scope. | +| `out_templates` | List of strings; default is `[]` A list of templates for files generated by the `extra_action` command. The template can use the following variables: * $(ACTION\_ID), an id uniquely identifying this `extra_action`. Used to generate a unique output file. | +| `requires_action_output` | Boolean; default is `False` Indicates this `extra_action` requires the output of the original action to be present as input to this `extra_action`. When true (default false), the extra\_action can assume that the original action outputs are available as part of its inputs. | +| `tools` | List of [labels](./concepts/labels); default is `[]` A list of `tool` dependencies for this rule. See the definition of [dependencies](./concepts/build-ref#deps) for more information. The build system ensures these prerequisites are built before running the `extra_action` command; they are built using the [`exec`configuration](./docs/user-manual#configurations), since they must run as a tool during the build itself. The path of an individual `tools` target `//x:y` can be obtained using `$(location //x:y)`. All tools and their data dependencies are consolidated into a single tree within which the command can use relative paths. The working directory will be the root of that unified tree. | \ No newline at end of file diff --git a/reference/be/functions.mdx b/reference/be/functions.mdx index 086fd42..f7162c1 100644 --- a/reference/be/functions.mdx +++ b/reference/be/functions.mdx @@ -2,31 +2,28 @@ title: 'functions' --- -# Functions - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm" %} -{% include "\_buttons.html" %} ## Contents -- [package](#package) -- [package_group](#package_group) -- [exports_files](#exports_files) -- [glob](#glob) -- [select](#select) -- [subpackages](#subpackages) +* [package](#package) +* [package\_group](#package_group) +* [exports\_files](#exports_files) +* [glob](#glob) +* [select](#select) +* [subpackages](#subpackages) ## package - - package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features) +``` +package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features) +``` This function declares metadata that applies to every rule in the package. It is used at most once within a package (BUILD file). For the counterpart that declares metadata applying to every rule in the whole *repository*, use the `repo()` function in the -[`REPO.bazel` file](/external/overview#repo.bazel) at the root of your repo. +[`REPO.bazel` file](./external/overview#repo.bazel) at the root of your repo. The `repo()` function takes exactly the same arguments as `package()`. The package() function should be called right after all the load() statements at the top of the @@ -34,61 +31,14 @@ file, before any rule. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th>Attribute</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="package.default_applicable_licenses"><code>default_applicable_licenses</code></td> -<td><p>Alias for <a href="#package.default_package_metadata"><code>default_package_metadata</code></a>.</p></td> -</tr> -<tr> -<td id="package.default_visibility"><code>default_visibility</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<p>The default visibility of the top-level rule targets and symbolic -macros in this package — that is, the targets and symbolic macros -that are not themselves declared inside a symbolic macro. This attribute -is ignored if the target or macro specifies a <code>visibility</code> -value.</p> -<p>For detailed information about the syntax of this attribute, see the -documentation of -<a href="/concepts/visibility">visibility</a>. The package default visibility does not apply to -<a href="#exports_files">exports_files</a>, which is public by default.</p></td> -</tr> -<tr> -<td id="package.default_deprecation"><code>default_deprecation</code></td> -<td><p>String; default is <code>""</code></p> -<p>Sets the default -<a href="common-definitions.html#common.deprecation"><code>deprecation</code></a> message for all rules in this package.</p></td> -</tr> -<tr> -<td id="package.default_package_metadata"><code>default_package_metadata</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<p>Sets a default list of metadata targets which apply to all other targets in the package. -These are typically targets related to OSS package and license declarations. -See <a href="https://github.com/bazelbuild/rules_license">rules_license</a> for examples.</p></td> -</tr> -<tr> -<td id="package.default_testonly"><code>default_testonly</code></td> -<td><p>Boolean; default is <code>False</code> except as noted</p> -<p>Sets the default -<a href="common-definitions.html#common.testonly"><code>testonly</code></a> property for all rules in this package.</p> -<p>In packages under <code>javatests</code> the default value is <code>True</code>.</p></td> -</tr> -<tr> -<td id="package.features"><code>features</code></td> -<td><p>List strings; default is <code>[]</code></p> -<p>Sets various flags that affect the semantics of this BUILD file.</p> -<p>This feature is mainly used by the people working on the build system to -tag packages that need some kind of special handling. Do not use this unless -explicitly requested by someone working on the build system.</p></td> -</tr> -</tbody> -</table> +| Attribute | Description | +| --- | --- | +| `default_applicable_licenses` | Alias for [`default_package_metadata`](#package.default_package_metadata). | +| `default_visibility` | List of [labels](./concepts/labels); default is `[]` The default visibility of the top-level rule targets and symbolic macros in this package — that is, the targets and symbolic macros that are not themselves declared inside a symbolic macro. This attribute is ignored if the target or macro specifies a `visibility` value. For detailed information about the syntax of this attribute, see the documentation of [visibility](./concepts/visibility). The package default visibility does not apply to [exports\_files](#exports_files), which is public by default. | +| `default_deprecation` | String; default is `""` Sets the default [`deprecation`](common-definitions.html#common.deprecation) message for all rules in this package. | +| `default_package_metadata` | List of [labels](./concepts/labels); default is `[]` Sets a default list of metadata targets which apply to all other targets in the package. These are typically targets related to OSS package and license declarations. See [rules\_license](https://github.com/bazelbuild/rules_license) for examples. | +| `default_testonly` | Boolean; default is `False` except as noted Sets the default [`testonly`](common-definitions.html#common.testonly) property for all rules in this package. In packages under `javatests` the default value is `True`. | +| `features` | List strings; default is `[]` Sets various flags that affect the semantics of this BUILD file. This feature is mainly used by the people working on the build system to tag packages that need some kind of special handling. Do not use this unless explicitly requested by someone working on the build system. | ### Examples @@ -97,16 +47,17 @@ visible only to members of package group `//foo:target`. Individual visibility declarations on a rule, if present, override this specification. -``` code - +``` package(default_visibility = ["//foo:target"]) ``` -## package_group +## package\_group - package_group(name, packages, includes) +``` +package_group(name, packages, includes) +``` -This function defines a set of [packages](/concepts/build-ref#packages) +This function defines a set of [packages](./concepts/build-ref#packages) and associates a label with the set. The label can be referenced in `visibility` attributes. @@ -128,90 +79,18 @@ not themselves have any visibility protection. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th>Attribute</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="package_group.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="package_group.packages"><code>packages</code></td> -<td><p>List of strings; default is <code>[]</code></p> -<p>A list of zero or more package specifications.</p> -<p>Each package specification string can have one of the following -forms:</p> -<ol> -<li>The full name of a package, without its repository, starting with a -double slash. For example, <code>//foo/bar</code> specifies the package -having that name and which lives in the same repository as the package -group.</li> -<li>As above, but with a trailing <code>/...</code>. For example, <code> //foo/...</code> specifies the set of <code>//foo</code> and all its -subpackages. <code>//...</code> specifies all packages in the current -repository.</li> -<li>The strings <code>public</code> or <code>private</code>, which -respectively specify every package or no package. (This form requires -the flag <code>--incompatible_package_group_has_public_syntax</code> to -be set.)</li> -</ol> -<p>In addition, the first two kinds of package specifications may also -be prefixed with <code>-</code> to indicate that they are negated.</p> -<p>The package group contains any package that matches at least one of -its positive specifications and none of its negative specifications -For instance, the value <code>[//foo/..., -//foo/tests/...]</code> -includes all subpackages of <code>//foo</code> that are not also -subpackages of <code>//foo/tests</code>. (<code>//foo</code> itself is -included while //foo/tests itself is not.)</p> -<p>Aside from public visibility, there is no way to directly specify -packages outside the current repository.</p> -<p>If this attribute is missing, it is the same as setting it to an -empty list, which is also the same as setting it to a list containing -only <code>private</code>.</p> -<p><em>Note:</em> Prior to Bazel 6.0, the specification <code>//...</code> -had a legacy behavior of being the same as <code>public</code>. This -behavior is fixed when -<code>--incompatible_fix_package_group_reporoot_syntax</code> is -enabled, which is the default after Bazel 6.0.</p> -<p><em>Note:</em> Prior to Bazel 6.0, when this attribute is serialized as -part of <code>bazel query --output=proto</code> (or -<code>--output=xml</code>), the leading slashes are omitted. For -instance, <code>//pkg/foo/...</code> will output as -<code>\"pkg/foo/...\"</code>. This behavior is fixed when -<code>--incompatible_package_group_includes_double_slash</code> is -enabled, which is the default after Bazel 6.0.</p></td> -</tr> -<tr> -<td id="package_group.includes"><code>includes</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<p>Other package groups that are included in this one.</p> -<p>The labels in this attribute must refer to other package groups. -Packages in referenced package groups are taken to be part of this -package group. This is transitive — if package group -<code>a</code> includes package group <code>b</code>, and <code>b</code> -includes package group <code>c</code>, then every package in -<code>c</code> will also be a member of <code>a</code>.</p> -<p>When used together with negated package specifications, note that the -set of packages for each group is first computed independently and the -results are then unioned together. This means that negated -specifications in one group have no effect on the specifications in -another group.</p></td> -</tr> -</tbody> -</table> +| Attribute | Description | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `packages` | List of strings; default is `[]` A list of zero or more package specifications. Each package specification string can have one of the following forms: 1. The full name of a package, without its repository, starting with a double slash. For example, `//foo/bar` specifies the package having that name and which lives in the same repository as the package group.- As above, but with a trailing `/...`. For example, `//foo/...` specifies the set of `//foo` and all its subpackages. `//...` specifies all packages in the current repository.- The strings `public` or `private`, which respectively specify every package or no package. (This form requires the flag `--incompatible_package_group_has_public_syntax` to be set.) In addition, the first two kinds of package specifications may also be prefixed with `-` to indicate that they are negated. The package group contains any package that matches at least one of its positive specifications and none of its negative specifications For instance, the value `[//foo/..., -//foo/tests/...]` includes all subpackages of `//foo` that are not also subpackages of `//foo/tests`. (`//foo` itself is included while //foo/tests itself is not.) Aside from public visibility, there is no way to directly specify packages outside the current repository. If this attribute is missing, it is the same as setting it to an empty list, which is also the same as setting it to a list containing only `private`. *Note:* Prior to Bazel 6.0, the specification `//...` had a legacy behavior of being the same as `public`. This behavior is fixed when `--incompatible_fix_package_group_reporoot_syntax` is enabled, which is the default after Bazel 6.0. *Note:* Prior to Bazel 6.0, when this attribute is serialized as part of `bazel query --output=proto` (or `--output=xml`), the leading slashes are omitted. For instance, `//pkg/foo/...` will output as `\"pkg/foo/...\"`. This behavior is fixed when `--incompatible_package_group_includes_double_slash` is enabled, which is the default after Bazel 6.0. | +| `includes` | List of [labels](./concepts/labels); default is `[]` Other package groups that are included in this one. The labels in this attribute must refer to other package groups. Packages in referenced package groups are taken to be part of this package group. This is transitive — if package group `a` includes package group `b`, and `b` includes package group `c`, then every package in `c` will also be a member of `a`. When used together with negated package specifications, note that the set of packages for each group is first computed independently and the results are then unioned together. This means that negated specifications in one group have no effect on the specifications in another group. | ### Examples The following `package_group` declaration specifies a package group called "tropical" that contains tropical fruits. -``` code - +``` package_group( name = "tropical", packages = [ @@ -225,8 +104,7 @@ package_group( The following declarations specify the package groups of a fictional application: -``` code - +``` package_group( name = "fooapp", includes = [ @@ -255,9 +133,11 @@ package_group( ) ``` -## exports_files +## exports\_files - exports_files([label, ...], visibility, licenses) +``` +exports_files([label, ...], visibility, licenses) +``` `exports_files()` specifies a list of files belonging to this package that are exported to other packages. @@ -265,7 +145,7 @@ this package that are exported to other packages. The BUILD file for a package may only refer directly to source files belonging to another package if they are explicitly exported with an `exports_files()` statement. Read more about -[visibility of files](/concepts/visibility#source-file-target-visibility). +[visibility of files](./concepts/visibility#source-file-target-visibility). As a legacy behaviour, also files mentioned as input to a rule are exported with the default visibility until the flag @@ -279,7 +159,7 @@ The argument is a list of names of files within the current package. A visibility declaration can also be specified; in this case, the files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package, even if a package default visibility was -specified in the [`package`](functions.html#package) +specified in the `package` function. The [licenses](common-definitions.html#common.licenses) can also be specified. @@ -290,8 +170,7 @@ text file from the `test_data` package, so that other packages may use it, for example, in the `data` attribute of tests. -``` code - +``` # from //test_data/BUILD exports_files(["golden.txt"]) @@ -299,7 +178,9 @@ exports_files(["golden.txt"]) ## glob - glob(include, exclude=[], exclude_directories=1, allow_empty=True) +``` +glob(include, exclude=[], exclude_directories=1, allow_empty=True) +``` Glob is a helper function that finds all files that match certain path patterns, and returns a new, mutable, sorted list of their paths. Glob only searches files @@ -323,37 +204,37 @@ path segment. Examples: -- `foo/bar.txt` matches exactly the `foo/bar.txt` file +* `foo/bar.txt` matches exactly the `foo/bar.txt` file in this package (unless `foo/` is a subpackage) -- `foo/*.txt` matches every file in the `foo/` directory +* `foo/*.txt` matches every file in the `foo/` directory if the file ends with `.txt` (unless `foo/` is a subpackage) -- `foo/a*.htm*` matches every file in the `foo/` +* `foo/a*.htm*` matches every file in the `foo/` directory that starts with `a`, then has an arbitrary string (could be empty), then has `.htm`, and ends with another arbitrary string (unless `foo/` is a subpackage); such as `foo/axx.htm` and `foo/a.html` or `foo/axxx.html` -- `foo/*` matches every file in the `foo/` directory, +* `foo/*` matches every file in the `foo/` directory, (unless `foo/` is a subpackage); it does not match `foo` directory itself even if `exclude_directories` is set to 0 -- `foo/**` matches every file in every non-subpackage subdirectory +* `foo/**` matches every file in every non-subpackage subdirectory under package's first level subdirectory `foo/`; if `exclude_directories` is set to 0, `foo` directory itself also matches the pattern; in this case, `**` is considered to match zero path segments -- `**/a.txt` matches `a.txt` files in this package's +* `**/a.txt` matches `a.txt` files in this package's directory plus non-subpackage subdirectories. -- `**/bar/**/*.txt` matches every `.txt` file in every +* `**/bar/**/*.txt` matches every `.txt` file in every non-subpackage subdirectory of this package, if at least one directory on the resulting path is called `bar`, such as `xxx/bar/yyy/zzz/a.txt` or `bar/a.txt` (remember that `**` also matches zero segments) or `bar/zzz/a.txt` -- `**` matches every file in every non-subpackage subdirectory of +* `**` matches every file in every non-subpackage subdirectory of this package -- `foo**/a.txt` is an invalid pattern, because `**` must +* `foo**/a.txt` is an invalid pattern, because `**` must stand on its own as a segment -- `foo/` is an invalid pattern, because the second segment defined +* `foo/` is an invalid pattern, because the second segment defined after `/` is an empty string If the `exclude_directories` argument is enabled (set to 1), files of @@ -365,65 +246,59 @@ empty list. There are several important limitations and caveats: -1. Since `glob()` runs during BUILD file evaluation, - `glob()` matches files only in your source tree, never - generated files. If you are building a target that requires both - source and generated files, you must append an explicit list of generated - files to the glob. See the [example](#glob_example) - below with `:mylib` and `:gen_java_srcs`. - -2. If a rule has the same name as a matched source file, the rule will - "shadow" the file. - - To understand this, remember that `glob()` returns a list of - paths, so using `glob()` in other rules' attribute (e.g. - `srcs = glob(["*.cc"])`) has the same effect as listing the - matched paths explicitly. If for example `glob()` yields - `["Foo.java", "bar/Baz.java"]` but there's also a rule in the - package called "Foo.java" (which is allowed, though Bazel warns about it), - then the consumer of the `glob()` will use the "Foo.java" rule - (its outputs) instead of the "Foo.java" file. See - [GitHub - issue \#10395](https://github.com/bazelbuild/bazel/issues/10395#issuecomment-583714657) for more details. - -3. Globs may match files in subdirectories. And subdirectory names - may be wildcarded. However... - -4. Labels are not allowed to cross the package boundary and glob does - not match files in subpackages. - - For example, the glob expression `**/*.cc` in package - `x` does not include `x/y/z.cc` if - `x/y` exists as a package (either as - `x/y/BUILD`, or somewhere else on the package-path). This - means that the result of the glob expression actually depends on the - existence of BUILD files — that is, the same glob expression would - include `x/y/z.cc` if there was no package called - `x/y` or it was marked as deleted using the - [--deleted_packages](/docs/user-manual#flag--deleted_packages) - flag. - -5. The restriction above applies to all glob expressions, - no matter which wildcards they use. - -6. A hidden file with filename starting with `.` is completely matched by - both the `**` and the `*` wildcards. If you want to match a hidden file - with a compound pattern, your pattern needs to begin with a `.`. For example, - `*` and `.*.txt` will match `.foo.txt`, but `*.txt` - will not. - Hidden directories are also matched in the same manner. Hidden directories - may include files that are not required as inputs, and can increase the - number of unnecessarily globbed files and memory consumption. To exclude - hidden directories, add them to the "exclude" list argument. - -7. The "\*\*" wildcard has one corner case: the pattern - `"**"` doesn't match the package's directory path. That is to - say, `glob(["**"], exclude_directories = False)` matches all files - and directories transitively strictly under the current package's directory - (but of course not going into directories of subpackages - see the previous - note about that). - -In general, you should **try to provide an appropriate extension (e.g. \*.html) +1. Since `glob()` runs during BUILD file evaluation, + `glob()` matches files only in your source tree, never + generated files. If you are building a target that requires both + source and generated files, you must append an explicit list of generated + files to the glob. See the [example](#glob_example) + below with `:mylib` and `:gen_java_srcs`. +2. If a rule has the same name as a matched source file, the rule will + "shadow" the file. + + To understand this, remember that `glob()` returns a list of + paths, so using `glob()` in other rules' attribute (e.g. + `srcs = glob(["*.cc"])`) has the same effect as listing the + matched paths explicitly. If for example `glob()` yields + `["Foo.java", "bar/Baz.java"]` but there's also a rule in the + package called "Foo.java" (which is allowed, though Bazel warns about it), + then the consumer of the `glob()` will use the "Foo.java" rule + (its outputs) instead of the "Foo.java" file. See + [GitHub + issue #10395](https://github.com/bazelbuild/bazel/issues/10395#issuecomment-583714657) for more details. +3. Globs may match files in subdirectories. And subdirectory names + may be wildcarded. However... +4. Labels are not allowed to cross the package boundary and glob does + not match files in subpackages. + + For example, the glob expression `**/*.cc` in package + `x` does not include `x/y/z.cc` if + `x/y` exists as a package (either as + `x/y/BUILD`, or somewhere else on the package-path). This + means that the result of the glob expression actually depends on the + existence of BUILD files — that is, the same glob expression would + include `x/y/z.cc` if there was no package called + `x/y` or it was marked as deleted using the + [--deleted\_packages](./docs/user-manual#flag--deleted_packages) + flag. +5. The restriction above applies to all glob expressions, + no matter which wildcards they use. +6. A hidden file with filename starting with `.` is completely matched by + both the `**` and the `*` wildcards. If you want to match a hidden file + with a compound pattern, your pattern needs to begin with a `.`. For example, + `*` and `.*.txt` will match `.foo.txt`, but `*.txt` + will not. + Hidden directories are also matched in the same manner. Hidden directories + may include files that are not required as inputs, and can increase the + number of unnecessarily globbed files and memory consumption. To exclude + hidden directories, add them to the "exclude" list argument. +7. The "\*\*" wildcard has one corner case: the pattern + `"**"` doesn't match the package's directory path. That is to + say, `glob(["**"], exclude_directories = False)` matches all files + and directories transitively strictly under the current package's directory + (but of course not going into directories of subpackages - see the previous + note about that). + +In general, you should **try to provide an appropriate extension (e.g. \*.mdx) instead of using a bare '\*'** for a glob pattern. The more explicit name is both self documenting and ensures that you don't accidentally match backup files, or emacs/vi/... auto-save files. @@ -437,8 +312,7 @@ enables generating individual rules for every input, for example. See the Create a Java library built from all java files in this directory, and all files generated by the `:gen_java_srcs` rule. -``` code - +``` java_library( name = "mylib", srcs = glob(["*.java"]) + [":gen_java_srcs"], @@ -459,8 +333,7 @@ Include all txt files in directory testdata except experimental.txt. Note that files in subdirectories of testdata will not be included. If you want those files to be included, use a recursive glob (\*\*). -``` code - +``` sh_test( name = "mytest", srcs = ["mytest.sh"], @@ -478,8 +351,7 @@ of its subdirectories (and their subdirectories, and so on). Subdirectories containing a BUILD file are ignored. (See limitations and caveats above.) -``` code - +``` sh_test( name = "mytest", srcs = ["mytest.sh"], @@ -492,8 +364,7 @@ subdirectories except those whose path includes a directory named testing. **This pattern should be avoided if possible, as it can reduce build incrementality and therefore increase build times.** -``` code - +``` java_library( name = "mylib", srcs = glob( @@ -508,8 +379,7 @@ java_library( Create an individual genrule for \*\_test.cc in the current directory that counts the number of lines in the file. -``` code - +``` # Conveniently, the build language supports list comprehensions. [genrule( name = "count_lines_" + f[:-3], # strip ".cc" @@ -520,22 +390,24 @@ that counts the number of lines in the file. ``` If the BUILD file above is in package //foo and the package contains three -matching files, a_test.cc, b_test.cc and c_test.cc then running +matching files, a\_test.cc, b\_test.cc and c\_test.cc then running `bazel query '//foo:all'` will list all rules that were generated: - - $ bazel query '//foo:all' | sort - //foo:count_lines_a_test - //foo:count_lines_b_test - //foo:count_lines_c_test +``` +$ bazel query '//foo:all' | sort +//foo:count_lines_a_test +//foo:count_lines_b_test +//foo:count_lines_c_test +``` ## select - - select( - {conditionA: valuesA, conditionB: valuesB, ...}, - no_match_error = "custom message" - ) +``` +select( + \{conditionA: valuesA, conditionB: valuesB, ...\}, + no_match_error = "custom message" +) +``` `select()` is the helper function that makes a rule attribute [configurable](common-definitions.html#configurable-attributes). @@ -548,15 +420,14 @@ vs. "release" mode. Basic use is as follows: -``` code - +``` sh_binary( name = "mytarget", - srcs = select({ + srcs = select(\{ ":conditionA": ["mytarget_a.sh"], ":conditionB": ["mytarget_b.sh"], "//conditions:default": ["mytarget_default.sh"] - }) + \}) ) ``` @@ -565,100 +436,98 @@ a `sh_binary` configurable by replacing its normal label list assignment with a `select` call that maps configuration conditions to matching values. Each condition is a label reference to -a [`config_setting`](general.html#config_setting) or -[`constraint_value`](platforms-and-toolchains.html#constraint_value), +a `config_setting` or +`constraint_value`, which "matches" if the target's configuration matches an expected set of values. The value of `mytarget#srcs` then becomes whichever label list matches the current invocation. Notes: -Exactly one condition is selected on any invocation. - -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 and constraint -values as A plus some additional flags or constraint values. This also -means that specialization resolution is not designed to create an ordering as -demonstrated in Example 2 below. - -If multiple conditions match and one is not a specialization of all the -others, Bazel fails with an error, unless all conditions resolve to the same value. - -The special pseudo-label `//conditions:default` is -considered to match if no other condition matches. If this condition -is left out, some other rule must match to avoid an error. - -`select` can be embedded *inside* a larger -attribute assignment. So `srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...})` and ` srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]})` are valid expressions. - -`select` works with most, but not all, attributes. Incompatible -attributes are marked `nonconfigurable` in their documentation. - -## subpackages - - subpackages(include, exclude=[], allow_empty=True) - -`subpackages()` is a helper function, similar to `glob()` -that lists subpackages instead of files and directories. It uses the same -path patterns as `glob()` and can match any subpackage that is a -direct descendant of the currently loading BUILD file. See [glob](#glob) for a detailed explanation and examples of include and -exclude patterns. - -The resulting list of subpackages returned is in sorted order and contains -paths relative to the current loading package that match the given patterns in -`include` and not those in `exclude`. - -### Example - -The following example lists all the direct subpackages for the package `foo/BUILD` - -``` code - -# The following BUILD files exist: -# foo/BUILD -# foo/bar/baz/BUILD -# foo/bar/but/bad/BUILD -# foo/sub/BUILD -# foo/sub/deeper/BUILD -# -# In foo/BUILD a call to -subs1 = subpackages(include = ["**"]) - -# results in subs1 == ["sub", "bar/baz", "bar/but/bad"] -# -# 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of -# 'foo' - -subs2 = subpackages(include = ["bar/*"]) -# results in subs2 = ["bar/baz"] -# -# Since 'bar' is not a subpackage itself, this looks for any subpackages under -# all first level subdirectories of 'bar'. - -subs3 = subpackages(include = ["bar/**"]) -# results in subs3 = ["bar/baz", "bar/but/bad"] -# -# Since bar is not a subpackage itself, this looks for any subpackages which are -# (1) under all subdirectories of 'bar' which can be at any level, (2) not a -# subpackage of another subpackages. - -subs4 = subpackages(include = ["sub"]) -subs5 = subpackages(include = ["sub/*"]) -subs6 = subpackages(include = ["sub/**"]) -# results in subs4 and subs6 being ["sub"] -# results in subs5 = []. -# -# In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a -# subpackage of 'foo'). -# In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since -# 'foo/sub' is already a subpackage itself, the subdirectories will not be -# traversed anymore. -# In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it -# is returned. But the subdirectories of 'foo/sub' will not be traversed -# anymore. -``` - -In general it is preferred that instead of calling this function directly -that users use the 'subpackages' module of -[skylib](https://github.com/bazelbuild/bazel-skylib). +* Exactly one condition is selected on any invocation. +* 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 and constraint + values as A plus some additional flags or constraint values. This also + means that specialization resolution is not designed to create an ordering as + demonstrated in Example 2 below. +* If multiple conditions match and one is not a specialization of all the + others, Bazel fails with an error, unless all conditions resolve to the same value. +* The special pseudo-label `//conditions:default` is + considered to match if no other condition matches. If this condition + is left out, some other rule must match to avoid an error. +* `select` can be embedded *inside* a larger + attribute assignment. So `srcs = ["common.sh"] + + select(\{ ":conditionA": ["myrule_a.sh"], ...\})` and `srcs = select(\{ ":conditionA": ["a.sh"]\}) + select(\{ ":conditionB": + ["b.sh"]\})` are valid expressions. +* `select` works with most, but not all, attributes. Incompatible + attributes are marked `nonconfigurable` in their documentation. + + ## subpackages + + ``` + subpackages(include, exclude=[], allow_empty=True) + ``` + + `subpackages()` is a helper function, similar to `glob()` + that lists subpackages instead of files and directories. It uses the same + path patterns as `glob()` and can match any subpackage that is a + direct descendant of the currently loading BUILD file. See [glob](#glob) for a detailed explanation and examples of include and + exclude patterns. + + The resulting list of subpackages returned is in sorted order and contains + paths relative to the current loading package that match the given patterns in + `include` and not those in `exclude`. + + ### Example + + The following example lists all the direct subpackages for the package `foo/BUILD` + + ``` + # The following BUILD files exist: + # foo/BUILD + # foo/bar/baz/BUILD + # foo/bar/but/bad/BUILD + # foo/sub/BUILD + # foo/sub/deeper/BUILD + # + # In foo/BUILD a call to + subs1 = subpackages(include = ["**"]) + + # results in subs1 == ["sub", "bar/baz", "bar/but/bad"] + # + # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of + # 'foo' + + subs2 = subpackages(include = ["bar/*"]) + # results in subs2 = ["bar/baz"] + # + # Since 'bar' is not a subpackage itself, this looks for any subpackages under + # all first level subdirectories of 'bar'. + + subs3 = subpackages(include = ["bar/**"]) + # results in subs3 = ["bar/baz", "bar/but/bad"] + # + # Since bar is not a subpackage itself, this looks for any subpackages which are + # (1) under all subdirectories of 'bar' which can be at any level, (2) not a + # subpackage of another subpackages. + + subs4 = subpackages(include = ["sub"]) + subs5 = subpackages(include = ["sub/*"]) + subs6 = subpackages(include = ["sub/**"]) + # results in subs4 and subs6 being ["sub"] + # results in subs5 = []. + # + # In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a + # subpackage of 'foo'). + # In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since + # 'foo/sub' is already a subpackage itself, the subdirectories will not be + # traversed anymore. + # In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it + # is returned. But the subdirectories of 'foo/sub' will not be traversed + # anymore. + ``` + + In general it is preferred that instead of calling this function directly + that users use the 'subpackages' module of + [skylib](https://github.com/bazelbuild/bazel-skylib). \ No newline at end of file diff --git a/reference/be/general.mdx b/reference/be/general.mdx index a510f80..608dcff 100644 --- a/reference/be/general.mdx +++ b/reference/be/general.mdx @@ -2,26 +2,22 @@ title: 'general' --- -# General Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} ## Rules -- [alias](#alias) -- [config_setting](#config_setting) -- [filegroup](#filegroup) -- [genquery](#genquery) -- [genrule](#genrule) -- [starlark_doc_extract](#starlark_doc_extract) -- [test_suite](#test_suite) +* [alias](#alias) +* [config\_setting](#config_setting) +* [filegroup](#filegroup) +* [genquery](#genquery) +* [genrule](#genrule) +* [starlark\_doc\_extract](#starlark_doc_extract) +* [test\_suite](#test_suite) ## alias -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/Alias.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/Alias.java) -``` rule-signature +``` alias(name, actual, aspect_hints, compatible_with, deprecation, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) ``` @@ -32,25 +28,24 @@ and `test_suite` cannot be aliased. Aliasing may be of help in large repositories where renaming a target would require making changes to lots of files. You can also use alias rule to store a -[select](/reference/be/functions.html#select) function call if you want to reuse that logic for +[select](./reference/be/functions.html#select) function call if you want to reuse that logic for multiple targets. The alias rule has its own visibility declaration. In all other respects, it behaves like the rule it references (e.g. testonly *on the alias* is ignored; the testonly-ness of the referenced rule is used instead) with some minor exceptions: -- Tests are not run if their alias is mentioned on the command line. To define an alias +* Tests are not run if their alias is mentioned on the command line. To define an alias that runs the referenced test, use a [`test_suite`](#test_suite) rule with a single target in its [`tests`](#test_suite.tests) attribute. -- When defining environment groups, the aliases to `environment` rules are not +* When defining environment groups, the aliases to `environment` rules are not supported. They are not supported in the `--target_environment` command line option, either. #### Examples -``` code - +``` filegroup( name = "data", srcs = ["data.txt"], @@ -64,67 +59,46 @@ alias( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="alias.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="alias.actual"><code>actual</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -The target this alias refers to. It does not need to be a rule, it can also be an input -file.</td> -</tr> -</tbody> -</table> - -## config_setting - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `actual` | [Label](./concepts/labels); required The target this alias refers to. It does not need to be a rule, it can also be an input file. | + +## config\_setting + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java) + +``` config_setting(name, aspect_hints, constraint_values, define_values, deprecation, features, flag_values, licenses, package_metadata, tags, testonly, values, visibility) ``` Matches an expected configuration state (expressed as build flags or platform constraints) for -the purpose of triggering configurable attributes. See [select](/reference/be/functions.html#select) for -how to consume this rule and -[Configurable attributes](/reference/be/common-definitions#configurable-attributes) for an overview of the general feature. +the purpose of triggering configurable attributes. See [select](./reference/be/functions.html#select) for +how to consume this rule and [Configurable attributes](./reference/be/common-definitions#configurable-attributes) for an overview of the general feature. #### Examples The following matches any build that sets `--compilation_mode=opt` or `-c opt` (either explicitly at the command line or implicitly from .bazelrc files): -``` code - +``` config_setting( name = "simple", - values = {"compilation_mode": "opt"} + values = \{"compilation_mode": "opt"\} ) - ``` The following matches any build that targets ARM and applies the custom define `FOO=bar` (for instance, `bazel build --cpu=arm --define FOO=bar ...`): -``` code - +``` config_setting( name = "two_conditions", - values = { + values = \{ "cpu": "arm", "define": "FOO=bar" - } + \} ) - ``` The following matches any build that sets @@ -132,22 +106,19 @@ The following matches any build that sets `--//custom_flags:foo=1` (either explicitly at the command line or implicitly from .bazelrc files): -``` code - +``` config_setting( name = "my_custom_flag_is_set", - flag_values = { "//custom_flags:foo": "1" }, + flag_values = \{ "//custom_flags:foo": "1" \}, ) - ``` -The following matches any build that targets a platform with an x86_64 architecture and glibc +The following matches any build that targets a platform with an x86\_64 architecture and glibc version 2.25, assuming the existence of a `constraint_value` with label `//example:glibc_2_25`. Note that a platform still matches if it defines additional constraint values beyond these two. -``` code - +``` config_setting( name = "64bit_glibc_2_25", constraint_values = [ @@ -155,7 +126,6 @@ constraint values beyond these two. "//example:glibc_2_25", ] ) - ``` In all these cases, it's possible for the configuration to change within the build, for example if @@ -165,35 +135,31 @@ some build targets. #### Notes -- See [select](/reference/be/functions.html#select) for what happens when multiple +* See [select](./reference/be/functions.html#select) for what happens when multiple `config_setting`s match the current configuration state. - -- For flags that support shorthand forms (e.g. `--compilation_mode` vs. +* For flags that support shorthand forms (e.g. `--compilation_mode` vs. `-c`), `values` definitions must use the full form. These automatically match invocations using either form. - -- If a flag takes multiple values (like `--copt=-Da --copt=-Db` or a list-typed - [Starlark flag](https://bazel.build/rules/config#user-defined-build-settings)), `values = { "flag": "a" }` matches if `"a"` is +* If a flag takes multiple values (like `--copt=-Da --copt=-Db` or a list-typed + [Starlark flag](https://bazel.build/rules/config#user-defined-build-settings)), `values = \{ "flag": "a" \}` matches if `"a"` is present *anywhere* in the actual list. - `values = { "myflag": "a,b" }` works the same way: this matches + `values = \{ "myflag": "a,b" \}` works the same way: this matches `--myflag=a --myflag=b`, `--myflag=a --myflag=b --myflag=c`, `--myflag=a,b`, and `--myflag=c,b,a`. Exact semantics vary between flags. For example, `--copt` doesn't support multiple values *in the same - instance*: `--copt=a,b` produces `["a,b"]` while `--copt=a --copt=b` produces `["a", "b"]` (so `values = { "copt": "a,b" }` + instance*: `--copt=a,b` produces `["a,b"]` while `--copt=a + --copt=b` produces `["a", "b"]` (so `values = \{ "copt": "a,b" \}` matches the former but not the latter). But `--ios_multi_cpus` (for Apple rules) - *does*: `-ios_multi_cpus=a,b` and `ios_multi_cpus=a --ios_multi_cpus=b ` both produce `["a", "b"]`. Check flag definitions and test your + *does*: `-ios_multi_cpus=a,b` and `ios_multi_cpus=a --ios_multi_cpus=b` both produce `["a", "b"]`. Check flag definitions and test your conditions carefully to verify exact expectations. - -- If you need to define conditions that aren't modeled by built-in build flags, use +* If you need to define conditions that aren't modeled by built-in build flags, use [Starlark-defined flags](https://bazel.build/rules/config#user-defined-build-settings). You can also use `--define`, but this offers weaker support and is not recommended. See - [here](/reference/be/common-definitions#configurable-attributes) for more discussion. - -- Avoid repeating identical `config_setting` definitions in different packages. + [here](./reference/be/common-definitions#configurable-attributes) for more discussion. +* Avoid repeating identical `config_setting` definitions in different packages. Instead, reference a common `config_setting` that defined in a canonical package. - -- [`values`](general.html#config_setting.values), +* [`values`](general.html#config_setting.values), [`define_values`](general.html#config_setting.define_values), and [`constraint_values`](general.html#config_setting.constraint_values) can be used in any combination in the same `config_setting` but at least one must @@ -201,105 +167,19 @@ some build targets. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="config_setting.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="config_setting.constraint_values"><code>constraint_values</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -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://bazel.build/docs/configurable-attributes#platforms">Configurable Build Attributes</a> for details. -<p>If two <code>config_setting</code>s match in the same <code>select</code> and one has -all the same flags and <code>constraint_setting</code>s as the other plus additional ones, -the one with more settings is chosen. This is known as "specialization". For example, -a <code>config_setting</code> matching <code>x86</code> and <code>Linux</code> specializes -a <code>config_setting</code> matching <code>x86</code>.</p> -<p>If two <code>config_setting</code>s match and both have <code>constraint_value</code>s -not present in the other, this is an error.</p></td> -</tr> -<tr> -<td id="config_setting.define_values"><code>define_values</code></td> -<td><p>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> -The same as <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> but -specifically for the <code>--define</code> flag. -<p><code>--define</code> is special because its syntax (<code>--define KEY=VAL</code>) -means <code>KEY=VAL</code> is a <em>value</em> from a Bazel flag perspective.</p> -<p>That means:</p> -<pre class="code"><code> - config_setting( - name = "a_and_b", - values = { - "define": "a=1", - "define": "b=2", - }) - </code></pre> -<p>doesn't work because the same key (<code>define</code>) appears twice in the -dictionary. This attribute solves that problem:</p> -<pre class="code"><code> - config_setting( - name = "a_and_b", - define_values = { - "a": "1", - "b": "2", - }) - </code></pre> -<p>correctly matches <code>bazel build //foo --define a=1 --define b=2</code>.</p> -<p><code>--define</code> can still appear in -<a href="/reference/be/general.html#config_setting.values"><code>values</code></a> with normal flag syntax, -and can be mixed freely with this attribute as long as dictionary keys remain distinct.</p></td> -</tr> -<tr> -<td id="config_setting.flag_values"><code>flag_values</code></td> -<td><p>Dictionary: <a href="/concepts/labels">label</a> -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> -The same as <a href="/reference/be/general.html#config_setting.values"><code>values</code></a> but -for -<a href="https://bazel.build/rules/config#user-defined-build-settings">user-defined build flags</a>. -<p>This is a distinct attribute because user-defined flags are referenced as labels while -built-in flags are referenced as arbitrary strings.</p></td> -</tr> -<tr> -<td id="config_setting.values"><code>values</code></td> -<td><p>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</code></p> -The set of configuration values that match this rule (expressed as build flags) -<p>This rule inherits the configuration of the configured target that -references it in a <code>select</code> statement. It is considered to -"match" a Bazel invocation if, for every entry in the dictionary, its -configuration matches the entry's expected value. For example -<code>values = {"compilation_mode": "opt"}</code> matches the invocations -<code>bazel build --compilation_mode=opt ...</code> and -<code>bazel build -c opt ...</code> on target-configured rules.</p> -<p>For convenience's sake, configuration values are specified as build flags (without -the preceding <code>"--"</code>). But keep in mind that the two are not the same. This -is because targets can be built in multiple configurations within the same -build. For example, an exec configuration's "cpu" matches the value of -<code>--host_cpu</code>, not <code>--cpu</code>. So different instances of the -same <code>config_setting</code> may match the same invocation differently -depending on the configuration of the rule using them.</p> -<p>If a flag is not explicitly set at the command line, its default value is used. -If a key appears multiple times in the dictionary, only the last instance is used. -If a key references a flag that can be set multiple times on the command line (e.g. -<code>bazel build --copt=foo --copt=bar --copt=baz ...</code>), a match occurs if -<em>any</em> of those settings match.</p></td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `constraint_values` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` The minimum set of `constraint_values` that the target platform must specify in order to match this `config_setting`. (The execution platform is not considered here.) Any additional constraint values that the platform has are ignored. See [Configurable Build Attributes](https://bazel.build/docs/configurable-attributes#platforms) for details. If two `config_setting`s match in the same `select` and one has all the same flags and `constraint_setting`s as the other plus additional ones, the one with more settings is chosen. This is known as "specialization". For example, a `config_setting` matching `x86` and `Linux` specializes a `config_setting` matching `x86`. If two `config_setting`s match and both have `constraint_value`s not present in the other, this is an error. | +| `define_values` | Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `\{\}` The same as [`values`](./reference/be/general.html#config_setting.values) but specifically for the `--define` flag. `--define` is special because its syntax (`--define KEY=VAL`) means `KEY=VAL` is a *value* from a Bazel flag perspective. That means: ``` config_setting( name = "a_and_b", values = \{ "define": "a=1", "define": "b=2", \}) ``` doesn't work because the same key (`define`) appears twice in the dictionary. This attribute solves that problem: ``` config_setting( name = "a_and_b", define_values = \{ "a": "1", "b": "2", \}) ``` correctly matches `bazel build //foo --define a=1 --define b=2`. `--define` can still appear in [`values`](./reference/be/general.html#config_setting.values) with normal flag syntax, and can be mixed freely with this attribute as long as dictionary keys remain distinct. | +| `flag_values` | Dictionary: [label](./concepts/labels) -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `\{\}` The same as [`values`](./reference/be/general.html#config_setting.values) but for [user-defined build flags](https://bazel.build/rules/config#user-defined-build-settings). This is a distinct attribute because user-defined flags are referenced as labels while built-in flags are referenced as arbitrary strings. | +| `values` | Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `\{\}` The set of configuration values that match this rule (expressed as build flags) This rule inherits the configuration of the configured target that references it in a `select` statement. It is considered to "match" a Bazel invocation if, for every entry in the dictionary, its configuration matches the entry's expected value. For example `values = \{"compilation_mode": "opt"\}` matches the invocations `bazel build --compilation_mode=opt ...` and `bazel build -c opt ...` on target-configured rules. For convenience's sake, configuration values are specified as build flags (without the preceding `"--"`). But keep in mind that the two are not the same. This is because targets can be built in multiple configurations within the same build. For example, an exec configuration's "cpu" matches the value of `--host_cpu`, not `--cpu`. So different instances of the same `config_setting` may match the same invocation differently depending on the configuration of the rule using them. If a flag is not explicitly set at the command line, its default value is used. If a key appears multiple times in the dictionary, only the last instance is used. If a key references a flag that can be set multiple times on the command line (e.g. `bazel build --copt=foo --copt=bar --copt=baz ...`), a match occurs if *any* of those settings match. | ## filegroup -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/filegroup/FilegroupRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/filegroup/FilegroupRule.java) -``` rule-signature +``` filegroup(name, srcs, data, aspect_hints, compatible_with, deprecation, features, licenses, output_group, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) ``` @@ -315,15 +195,14 @@ the `data` attribute of a \*\_binary rule. Using `filegroup` is encouraged instead of referencing directories directly. Directly referencing directories is discouraged because the build system does not have full knowledge of all files below the directory, so it may not rebuild when these files change. -When combined with [glob](/reference/be/functions.html#glob), `filegroup` can ensure that all +When combined with [glob](./reference/be/functions.html#glob), `filegroup` can ensure that all files are explicitly known to the build system. #### Examples To create a `filegroup` consisting of two source files, do -``` code - +``` filegroup( name = "mygroup", srcs = [ @@ -336,8 +215,7 @@ filegroup( Or, use a `glob` to fully crawl a testdata directory: -``` code - +``` filegroup( name = "exported_testdata", srcs = glob([ @@ -349,8 +227,7 @@ filegroup( To make use of these definitions, reference the `filegroup` with a label from any rule: -``` code - +``` cc_library( name = "my_library", srcs = ["foo.cc"], @@ -363,59 +240,23 @@ cc_library( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="filegroup.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="filegroup.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of targets that are members of the file group. -<p>It is common to use the result of a <a href="/reference/be/functions.html#glob">glob</a> expression for -the value of the <code>srcs</code> attribute.</p></td> -</tr> -<tr> -<td id="filegroup.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this rule at runtime. -<p>Targets named in the <code>data</code> attribute will be added to the -<code>runfiles</code> of this <code>filegroup</code> rule. When the -<code>filegroup</code> is referenced in the <code>data</code> attribute of -another rule its <code>runfiles</code> will be added to the <code>runfiles</code> -of the depending rule. See the <a href="/concepts/dependencies#data-dependencies">data dependencies</a> -section and <a href="/reference/be/common-definitions#common.data">general documentation of -<code>data</code></a> for more information about how to depend on and use data files.</p></td> -</tr> -<tr> -<td id="filegroup.output_group"><code>output_group</code></td> -<td><p>String; default is <code>""</code></p> -The output group from which to gather artifacts from sources. If this attribute is -specified, artifacts from the specified output group of the dependencies will be exported -instead of the default output group. -<p>An "output group" is a category of output artifacts of a target, specified in that -rule's implementation.</p></td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of targets that are members of the file group. It is common to use the result of a [glob](./reference/be/functions.html#glob) expression for the value of the `srcs` attribute. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this rule at runtime. Targets named in the `data` attribute will be added to the `runfiles` of this `filegroup` rule. When the `filegroup` is referenced in the `data` attribute of another rule its `runfiles` will be added to the `runfiles` of the depending rule. See the [data dependencies](./concepts/dependencies#data-dependencies) section and [general documentation of `data`](./reference/be/common-definitions#common.data) for more information about how to depend on and use data files. | +| `output_group` | String; default is `""` The output group from which to gather artifacts from sources. If this attribute is specified, artifacts from the specified output group of the dependencies will be exported instead of the default output group. An "output group" is a category of output artifacts of a target, specified in that rule's implementation. | ## genquery -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java) -``` rule-signature +``` genquery(name, deps, data, aspect_hints, compatible_with, compressed_output, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, expression, features, licenses, opts, package_metadata, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility) ``` `genquery()` runs a query specified in the -[Bazel query language](/reference/query) and dumps the result +[Bazel query language](./reference/query) and dumps the result into a file. In order to keep the build consistent, the query is allowed only to visit @@ -446,8 +287,7 @@ The name of the output file is the name of the rule. This example writes the list of the labels in the transitive closure of the specified target to a file. -``` code - +``` genquery( name = "kiwi-deps", expression = "deps(//kiwi:kiwi_lib)", @@ -457,66 +297,20 @@ genquery( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="genquery.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="genquery.compressed_output"><code>compressed_output</code></td> -<td><p>Boolean; default is <code>False</code></p> -If <code>True</code>, query output is written in GZIP file format. This setting can be used -to avoid spikes in Bazel's memory use when the query output is expected to be large. Bazel -already internally compresses query outputs greater than 2<sup>20</sup> bytes regardless of -the value of this setting, so setting this to <code>True</code> may not reduce retained -heap. However, it allows Bazel to skip <em>decompression</em> when writing the output file, -which can be memory-intensive.</td> -</tr> -<tr> -<td id="genquery.expression"><code>expression</code></td> -<td><p>String; required</p> -The query to be executed. In contrast to the command line and other places in BUILD files, -labels here are resolved relative to the root directory of the workspace. For example, the -label <code>:b</code> in this attribute in the file <code>a/BUILD</code> will refer to the -target <code>//:b</code>.</td> -</tr> -<tr> -<td id="genquery.opts"><code>opts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -The options that are passed to the query engine. These correspond to the command line -options that can be passed to <code>bazel query</code>. Some query options are not allowed -here: <code>--keep_going</code>, <code>--query_file</code>, <code>--universe_scope</code>, -<code>--order_results</code> and <code>--order_output</code>. Options not specified here -will have their default values just like on the command line of <code>bazel query</code>.</td> -</tr> -<tr> -<td id="genquery.scope"><code>scope</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; required</p> -The scope of the query. The query is not allowed to touch targets outside the transitive -closure of these targets.</td> -</tr> -<tr> -<td id="genquery.strict"><code>strict</code></td> -<td><p>Boolean; default is <code>True</code></p> -If true, targets whose queries escape the transitive closure of their scopes will fail to -build. If false, Bazel will print a warning and skip whatever query path led it outside of -the scope, while completing the rest of the query.</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `compressed_output` | Boolean; default is `False` If `True`, query output is written in GZIP file format. This setting can be used to avoid spikes in Bazel's memory use when the query output is expected to be large. Bazel already internally compresses query outputs greater than 220 bytes regardless of the value of this setting, so setting this to `True` may not reduce retained heap. However, it allows Bazel to skip *decompression* when writing the output file, which can be memory-intensive. | +| `expression` | String; required The query to be executed. In contrast to the command line and other places in BUILD files, labels here are resolved relative to the root directory of the workspace. For example, the label `:b` in this attribute in the file `a/BUILD` will refer to the target `//:b`. | +| `opts` | List of strings; default is `[]` The options that are passed to the query engine. These correspond to the command line options that can be passed to `bazel query`. Some query options are not allowed here: `--keep_going`, `--query_file`, `--universe_scope`, `--order_results` and `--order_output`. Options not specified here will have their default values just like on the command line of `bazel query`. | +| `scope` | List of [labels](./concepts/labels); required The scope of the query. The query is not allowed to touch targets outside the transitive closure of these targets. | +| `strict` | Boolean; default is `True` If true, targets whose queries escape the transitive closure of their scopes will fail to build. If false, Bazel will print a warning and skip whatever query path led it outside of the scope, while completing the rest of the query. | ## genrule -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java) -``` rule-signature +``` genrule(name, srcs, outs, aspect_hints, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility) ``` @@ -531,7 +325,7 @@ Note that genrule requires a shell to interpret the command argument. It is also easy to reference arbitrary programs available on the PATH, however this makes the command non-hermetic and may not be reproducible. If you only need to run a single tool, consider using -[run_binary](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/run_binary_doc.md) +[run\_binary](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/run_binary_doc.md) instead. Like every other action, the action created by genrules should not assume anything about their @@ -545,11 +339,11 @@ Do not use a genrule for running tests. There are special dispensations for test results, including caching policies and environment variables. Tests generally need to be run after the build is complete and on the target architecture, whereas genrules are executed during the build and on the exec architecture (the two may be different). If you need a general purpose -testing rule, use [`sh_test`](/reference/be/shell.html#sh_test). +testing rule, use [`sh_test`](./reference/be/shell.html#sh_test). #### Cross-compilation Considerations -*See [the user manual](/docs/user-manual#configurations) for more info about +*See [the user manual](./docs/user-manual#configurations) for more info about cross-compilation.* While genrules run during a build, their outputs are often used after the build, for deployment or @@ -566,8 +360,7 @@ corresponding files into separate directories to avoid conflicts. For genrules, the build system ensures that dependencies are built appropriately: `srcs` are built (if necessary) for the *target* configuration, `tools` are built for the *exec* configuration, and the output is considered to -be for the *target* configuration. It also provides -["Make" variables](/reference/be/make-variables) that genrule commands can pass to the corresponding tools. +be for the *target* configuration. It also provides ["Make" variables](./reference/be/make-variables) that genrule commands can pass to the corresponding tools. It is intentional that genrule defines no `deps` attribute: other built-in rules use language-dependent meta information passed between the rules to automatically determine how to @@ -582,11 +375,11 @@ which is subsequently used by another genrule, the first one has to produce its exec configuration, because that's where the compiler will run in the other genrule. In this case, the build system does the right thing automatically: it builds the `srcs` and `outs` of the first genrule for the exec configuration instead of the target -configuration. See [the user manual](/docs/user-manual#configurations) for more +configuration. See [the user manual](./docs/user-manual#configurations) for more info. *JDK & C++ Tooling*: to use a tool from the JDK or the C++ compiler suite, the build system -provides a set of variables to use. See ["Make" variable](/reference/be/make-variables) for +provides a set of variables to use. See ["Make" variable](./reference/be/make-variables) for details. #### Genrule Environment @@ -611,27 +404,27 @@ directories before it runs a genrule. It also removes any output files in case o #### General Advice -- Do ensure that tools run by a genrule are deterministic and hermetic. They should not write +* Do ensure that tools run by a genrule are deterministic and hermetic. They should not write timestamps to their output, and they should use stable ordering for sets and maps, as well as write only relative file paths to the output, no absolute paths. Not following this rule will lead to unexpected build behavior (Bazel not rebuilding a genrule you thought it would) and degrade cache performance. -- Do use `$(location)` extensively, for outputs, tools and sources. Due to the +* Do use `$(location)` extensively, for outputs, tools and sources. Due to the segregation of output files for different configurations, genrules cannot rely on hard-coded and/or absolute paths. -- Do write a common Starlark macro in case the same or very similar genrules are used in +* Do write a common Starlark macro in case the same or very similar genrules are used in multiple places. If the genrule is complex, consider implementing it in a script or as a Starlark rule. This improves readability as well as testability. -- Do make sure that the exit code correctly indicates success or failure of the genrule. -- Do not write informational messages to stdout or stderr. While useful for debugging, this can +* Do make sure that the exit code correctly indicates success or failure of the genrule. +* Do not write informational messages to stdout or stderr. While useful for debugging, this can easily become noise; a successful genrule should be silent. On the other hand, a failing genrule should emit good error messages. -- `$$` evaluates to a `$`, a literal dollar-sign, so in order to invoke a +* `$$` evaluates to a `$`, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as `ls $(dirname $x)`, one must escape it thus: `ls $$(dirname $$x)`. -- Avoid creating symlinks and directories. Bazel doesn't copy over the directory/symlink +* Avoid creating symlinks and directories. Bazel doesn't copy over the directory/symlink structure created by genrules and its dependency checking of directories is unsound. -- When referencing the genrule in other rules, you can use either the genrule's label or the +* When referencing the genrule in other rules, you can use either the genrule's label or the labels of individual output files. Sometimes the one approach is more readable, sometimes the other: referencing outputs by name in a consuming rule's `srcs` will avoid unintentionally picking up other outputs of the genrule, but can be tedious if the genrule @@ -642,8 +435,7 @@ directories before it runs a genrule. It also removes any output files in case o This example generates `foo.h`. There are no sources, because the command doesn't take any input. The "binary" run by the command is a perl script in the same package as the genrule. -``` code - +``` genrule( name = "foo", srcs = [], @@ -653,13 +445,11 @@ genrule( ) ``` -The following example shows how to use a [`filegroup`](/reference/be/general.html#filegroup) -and the outputs of another `genrule`. Note that using `$(SRCS)` instead +The following example shows how to use a [`filegroup`](./reference/be/general.html#filegroup) and the outputs of another `genrule`. Note that using `$(SRCS)` instead of explicit `$(location)` directives would also work; this example uses the latter for sake of demonstration. -``` code - +``` genrule( name = "concat_all_files", srcs = [ @@ -673,193 +463,35 @@ genrule( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="genrule.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p> -<br /> -You may refer to this rule by name in the -<code>srcs</code> or <code>deps</code> section of other <code>BUILD</code> -rules. If the rule generates source files, you should use the -<code>srcs</code> attribute.</td> -</tr> -<tr> -<td id="genrule.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of inputs for this rule, such as source files to process. -<p><em>This attributes is not suitable to list tools executed by the <code>cmd</code>; use -the <a href="/reference/be/general.html#genrule.tools"><code>tools</code></a> attribute for them instead.</em></p> -<p>The build system ensures these prerequisites are built before running the genrule -command; they are built using the same configuration as the original build request. The -names of the files of these prerequisites are available to the command as a -space-separated list in <code>$(SRCS)</code>; alternatively the path of an individual -<code>srcs</code> target <code>//x:y</code> can be obtained using <code>$(location //x:y)</code>, or using <code>$<</code> provided it's the only entry in -<code>srcs</code>.</p></td> -</tr> -<tr> -<td id="genrule.outs"><code>outs</code></td> -<td><p>List of <a href="/concepts/build-ref#filename">filenames</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; required</p> -A list of files generated by this rule. -<p>Output files must not cross package boundaries. -Output filenames are interpreted as relative to the package.</p> -<p>If the <code>executable</code> flag is set, <code>outs</code> must contain exactly one -label.</p> -<p>The genrule command is expected to create each output file at a predetermined location. -The location is available in <code>cmd</code> using <a href="/reference/be/make-variables#predefined_genrule_variables">genrule-specific "Make" -variables</a> (<code>$@</code>, <code>$(OUTS)</code>, <code>$(@D)</code> or <code> $(RULEDIR)</code>) or using -<a href="/reference/be/make-variables#predefined_label_variables"><code>$(location)</code></a> substitution.</p></td> -</tr> -<tr> -<td id="genrule.cmd"><code>cmd</code></td> -<td><p>String; default is <code>""</code></p> -The command to run. -Subject to <a href="/reference/be/make-variables#predefined_label_variables"><code>$(location) </code></a> and <a href="/reference/be/make-variables">"Make" variable</a> substitution. -<ol> -<li>First <a href="/reference/be/make-variables#predefined_label_variables"><code>$(location) </code></a> substitution is applied, replacing all occurrences of <code>$(location </code><em><code>label</code></em><code>)</code> and of <code>$(locations </code><em><code>label</code></em><code>)</code> (and similar -constructions using related variables <code>execpath</code>, <code>execpaths</code>, -<code>rootpath</code> and <code>rootpaths</code>).</li> -<li>Next, <a href="/reference/be/make-variables">"Make" variables</a> are expanded. Note that -predefined variables <code>$(JAVA)</code>, <code>$(JAVAC)</code> and -<code>$(JAVABASE)</code> expand under the <em>exec</em> configuration, so Java invocations -that run as part of a build step can correctly load shared libraries and other -dependencies.</li> -<li>Finally, the resulting command is executed using the Bash shell. If its exit code is -non-zero the command is considered to have failed.</li> -</ol> -This is the fallback of <code>cmd_bash</code>, <code>cmd_ps</code> and <code>cmd_bat</code>, -if none of them are applicable. -<p>If the command line length exceeds the platform limit (64K on Linux/macOS, 8K on Windows), +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. You may refer to this rule by name in the `srcs` or `deps` section of other `BUILD` rules. If the rule generates source files, you should use the `srcs` attribute. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` A list of inputs for this rule, such as source files to process. *This attributes is not suitable to list tools executed by the `cmd`; use the [`tools`](./reference/be/general.html#genrule.tools) attribute for them instead.* The build system ensures these prerequisites are built before running the genrule command; they are built using the same configuration as the original build request. The names of the files of these prerequisites are available to the command as a space-separated list in `$(SRCS)`; alternatively the path of an individual `srcs` target `//x:y` can be obtained using `$(location //x:y)`, or using `$<` provided it's the only entry in `srcs`. | +| `outs` | List of [filenames](./concepts/build-ref#filename); [nonconfigurable](common-definitions.html#configurable-attributes); required A list of files generated by this rule. Output files must not cross package boundaries. Output filenames are interpreted as relative to the package. If the `executable` flag is set, `outs` must contain exactly one label. The genrule command is expected to create each output file at a predetermined location. The location is available in `cmd` using [genrule-specific "Make" variables](./reference/be/make-variables#predefined_genrule_variables) (`$@`, `$(OUTS)`, `$(@D)` or `$(RULEDIR)`) or using [`$(location)`](./reference/be/make-variables#predefined_label_variables) substitution. | +| `cmd` | String; default is `""` The command to run. Subject to [`$(location)`](./reference/be/make-variables#predefined_label_variables) and ["Make" variable](./reference/be/make-variables) substitution. 1. First [`$(location)`](./reference/be/make-variables#predefined_label_variables) substitution is applied, replacing all occurrences of `$(location label)` and of `$(locations label)` (and similar constructions using related variables `execpath`, `execpaths`, `rootpath` and `rootpaths`). 2. Next, ["Make" variables](./reference/be/make-variables) are expanded. Note that predefined variables `$(JAVA)`, `$(JAVAC)` and `$(JAVABASE)` expand under the *exec* configuration, so Java invocations that run as part of a build step can correctly load shared libraries and other dependencies. 3. Finally, the resulting command is executed using the Bash shell. If its exit code is non-zero the command is considered to have failed. This is the fallback of `cmd_bash`, `cmd_ps` and `cmd_bat`, if none of them are applicable. | + +If the command line length exceeds the platform limit (64K on Linux/macOS, 8K on Windows), then genrule will write the command to a script and execute that script to work around. This -applies to all cmd attributes (<code>cmd</code>, <code>cmd_bash</code>, <code>cmd_ps</code>, -<code>cmd_bat</code>).</p></td> -</tr> -<tr> -<td id="genrule.cmd_bash"><code>cmd_bash</code></td> -<td><p>String; default is <code>""</code></p> -The Bash command to run. -<p>This attribute has higher priority than <code>cmd</code>. The command is expanded and -runs in the exact same way as the <code>cmd</code> attribute.</p></td> -</tr> -<tr> -<td id="genrule.cmd_bat"><code>cmd_bat</code></td> -<td><p>String; default is <code>""</code></p> -The Batch command to run on Windows. -<p>This attribute has higher priority than <code>cmd</code> and <code>cmd_bash</code>. -The command runs in the similar way as the <code>cmd</code> attribute, with the -following differences:</p> -<ul> -<li>This attribute only applies on Windows.</li> -<li>The command runs with <code>cmd.exe /c</code> with the following default arguments: -<ul> -<li><code>/S</code> - strip first and last quotes and execute everything else as is.</li> -<li><code>/E:ON</code> - enable extended command set.</li> -<li><code>/V:ON</code> - enable delayed variable expansion</li> -<li><code>/D</code> - ignore AutoRun registry entries.</li> -</ul></li> -<li>After <a href="/reference/be/make-variables#predefined_label_variables">$(location)</a> and -<a href="/reference/be/make-variables">"Make" variable</a> substitution, the paths will be -expanded to Windows style paths (with backslash).</li> -</ul></td> -</tr> -<tr> -<td id="genrule.cmd_ps"><code>cmd_ps</code></td> -<td><p>String; default is <code>""</code></p> -The Powershell command to run on Windows. -<p>This attribute has higher priority than <code>cmd</code>, <code>cmd_bash</code> and -<code>cmd_bat</code>. The command runs in the similar way as the <code>cmd</code> -attribute, with the following differences:</p> -<ul> -<li>This attribute only applies on Windows.</li> -<li>The command runs with <code>powershell.exe /c</code>.</li> -</ul> -<p>To make Powershell easier to use and less error-prone, we run the following -commands to set up the environment before executing Powershell command in genrule.</p> -<ul> -<li><code>Set-ExecutionPolicy -Scope CurrentUser RemoteSigned</code> - allow running -unsigned scripts.</li> -<li><code>$errorActionPreference='Stop'</code> - In case there are multiple commands -separated by <code>;</code>, the action exits immediately if a Powershell CmdLet fails, -but this does <strong>NOT</strong> work for external command.</li> -<li><code>$PSDefaultParameterValues['*:Encoding'] = 'utf8'</code> - change the default -encoding from utf-16 to utf-8.</li> -</ul></td> -</tr> -<tr> -<td id="genrule.executable"><code>executable</code></td> -<td><p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> -Declare output to be executable. -<p>Setting this flag to True means the output is an executable file and can be run using the -<code>run</code> command. The genrule must produce exactly one output in this case. -If this attribute is set, <code>run</code> will try executing the file regardless of -its content.</p> -<p>Declaring data dependencies for the generated executable is not supported.</p></td> -</tr> -<tr> -<td id="genrule.local"><code>local</code></td> -<td><p>Boolean; default is <code>False</code></p> -<p>If set to True, this option forces this <code>genrule</code> to run using the "local" -strategy, which means no remote execution, no sandboxing, no persistent workers.</p> -<p>This is equivalent to providing 'local' as a tag (<code>tags=["local"]</code>).</p></td> -</tr> -<tr> -<td id="genrule.message"><code>message</code></td> -<td><p>String; default is <code>""</code></p> -A progress message. -<p>A progress message that will be printed as this build step is executed. By default, the -message is "Generating <em>output</em>" (or something equally bland) but you may provide a -more specific one. Use this attribute instead of <code>echo</code> or other print -statements in your <code>cmd</code> command, as this allows the build tool to control -whether such progress messages are printed or not.</p></td> -</tr> -<tr> -<td id="genrule.output_licenses"><code>output_licenses</code></td> -<td><p>List of strings; default is <code>[]</code></p> -See <a href="/reference/be/common-definitions#binary.output_licenses"><code>common attributes </code></a></td> -</tr> -<tr> -<td id="genrule.output_to_bindir"><code>output_to_bindir</code></td> -<td><p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> -<p>If set to True, this option causes output files to be written into the <code>bin</code> -directory instead of the <code>genfiles</code> directory.</p></td> -</tr> -<tr> -<td id="genrule.toolchains"><code>toolchains</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -<p>The set of targets whose <a href="/reference/be/make-variables">Make variables</a> this genrule -is allowed to access, or the <a href="/docs/toolchains"><code>toolchain_type</code></a> -targets that this genrule will access.</p> -<p>Toolchains accessed via <code>toolchain_type</code> must also provide a -<code>TemplateVariableInfo</code> provider, which the target can use to access toolchain -details.</p></td> -</tr> -<tr> -<td id="genrule.tools"><code>tools</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of <em>tool</em> dependencies for this rule. See the definition of -<a href="/concepts/build-ref#deps">dependencies</a> for more information.<br /> - <p>The build system ensures these prerequisites are built before running the genrule command; -they are built using the <a href="/contribute/guide#configurations"><em>exec</em> -configuration</a>, since these tools are executed as part of the build. The path of an -individual <code>tools</code> target <code>//x:y</code> can be obtained using -<code>$(location //x:y)</code>.</p> -<p>Any <code>*_binary</code> or tool to be executed by <code>cmd</code> must appear in this -list, not in <code>srcs</code>, to ensure they are built in the correct configuration.</p></td> -</tr> -</tbody> -</table> - -## starlark_doc_extract - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/starlarkdocextract/StarlarkDocExtractRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +applies to all cmd attributes (`cmd`, `cmd_bash`, `cmd_ps`, +`cmd_bat`). + +| `cmd_bash` | String; default is `""` The Bash command to run. This attribute has higher priority than `cmd`. The command is expanded and runs in the exact same way as the `cmd` attribute. | +| `cmd_bat` | String; default is `""` The Batch command to run on Windows. This attribute has higher priority than `cmd` and `cmd_bash`. The command runs in the similar way as the `cmd` attribute, with the following differences: * This attribute only applies on Windows. * The command runs with `cmd.exe /c` with the following default arguments: + `/S` - strip first and last quotes and execute everything else as is. + `/E:ON` - enable extended command set. + `/V:ON` - enable delayed variable expansion + `/D` - ignore AutoRun registry entries. * After [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make" variable](./reference/be/make-variables) substitution, the paths will be expanded to Windows style paths (with backslash). | +| `cmd_ps` | String; default is `""` The Powershell command to run on Windows. This attribute has higher priority than `cmd`, `cmd_bash` and `cmd_bat`. The command runs in the similar way as the `cmd` attribute, with the following differences: * This attribute only applies on Windows. * The command runs with `powershell.exe /c`. To make Powershell easier to use and less error-prone, we run the following commands to set up the environment before executing Powershell command in genrule. * `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` - allow running unsigned scripts. * `$errorActionPreference='Stop'` - In case there are multiple commands separated by `;`, the action exits immediately if a Powershell CmdLet fails, but this does **NOT** work for external command. * `$PSDefaultParameterValues['*:Encoding'] = 'utf8'` - change the default encoding from utf-16 to utf-8. | +| `executable` | Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` Declare output to be executable. Setting this flag to True means the output is an executable file and can be run using the `run` command. The genrule must produce exactly one output in this case. If this attribute is set, `run` will try executing the file regardless of its content. Declaring data dependencies for the generated executable is not supported. | +| `local` | Boolean; default is `False` If set to True, this option forces this `genrule` to run using the "local" strategy, which means no remote execution, no sandboxing, no persistent workers. This is equivalent to providing 'local' as a tag (`tags=["local"]`). | +| `message` | String; default is `""` A progress message. A progress message that will be printed as this build step is executed. By default, the message is "Generating *output*" (or something equally bland) but you may provide a more specific one. Use this attribute instead of `echo` or other print statements in your `cmd` command, as this allows the build tool to control whether such progress messages are printed or not. | +| `output_licenses` | List of strings; default is `[]` See [`common attributes`](./reference/be/common-definitions#binary.output_licenses) | +| `output_to_bindir` | Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` If set to True, this option causes output files to be written into the `bin` directory instead of the `genfiles` directory. | +| `toolchains` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` The set of targets whose [Make variables](./reference/be/make-variables) this genrule is allowed to access, or the [`toolchain_type`](./docs/toolchains) targets that this genrule will access. Toolchains accessed via `toolchain_type` must also provide a `TemplateVariableInfo` provider, which the target can use to access toolchain details. | +| `tools` | List of [labels](./concepts/labels); default is `[]` A list of *tool* dependencies for this rule. See the definition of [dependencies](./concepts/build-ref#deps) for more information. The build system ensures these prerequisites are built before running the genrule command; they are built using the [*exec* configuration](./contribute/guide#configurations), since these tools are executed as part of the build. The path of an individual `tools` target `//x:y` can be obtained using `$(location //x:y)`. Any `*_binary` or tool to be executed by `cmd` must appear in this list, not in `srcs`, to ensure they are built in the correct configuration. | + + +## starlark\_doc\_extract + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/starlarkdocextract/StarlarkDocExtractRule.java) + +``` starlark_doc_extract(name, deps, src, data, allow_unused_doc_comments, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility) ``` @@ -867,101 +499,35 @@ starlark_doc_extract(name, deps, src, data, allow_unused_doc_comments, aspect_hi macros), aspects, and providers defined or re-exported in a given `.bzl` or `.scl` file. The output of this rule is a `ModuleInfo` binary proto as defined in -[stardoc_output.proto](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto) +[stardoc\_output.proto](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto) in the Bazel source tree. #### Implicit output targets -- `name``.binaryproto` (the default output): A +* `name.binaryproto` (the default output): A `ModuleInfo` binary proto. -- `name``.textproto` (only built if explicitly requested): the text - proto version of `name``.binaryproto`. +* `name.textproto` (only built if explicitly requested): the text + proto version of `name.binaryproto`. Warning: the output format of this rule is not guaranteed to be stable. It is intended mainly for internal use by [Stardoc](https://github.com/bazelbuild/stardoc). ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="starlark_doc_extract.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="starlark_doc_extract.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of targets wrapping the Starlark files which are <code>load()</code>-ed by -<code>src</code>. These targets <em>should</em> under normal usage be -<a href="https://github.com/bazelbuild/bazel-skylib/blob/main/bzl_library.bzl"><code>bzl_library</code></a> -targets, but the <code>starlark_doc_extract</code> rule does not enforce that, and accepts -any target which provides Starlark files in its <code>DefaultInfo</code>. -<p>Note that the wrapped Starlark files must be files in the source tree; Bazel cannot -<code>load()</code> generated files.</p></td> -</tr> -<tr> -<td id="starlark_doc_extract.src"><code>src</code></td> -<td><p><a href="/concepts/labels">Label</a>; required</p> -A Starlark file from which to extract documentation. -<p>Note that this must be a file in the source tree; Bazel cannot <code>load()</code> -generated files.</p></td> -</tr> -<tr> -<td id="starlark_doc_extract.allow_unused_doc_comments"><code>allow_unused_doc_comments</code></td> -<td><p>Boolean; default is <code>False</code></p> -If true, allow and silently ignore doc comments (comments starting with <code>#:</code>) -which are not attached to any global variable, or which are attached to a variable whose -value's documentation should be provided in a different way (for example, in a docstring for -a function, or via <code>rule(doc = ...)</code> for a rule).</td> -</tr> -<tr> -<td id="starlark_doc_extract.render_main_repo_name"><code>render_main_repo_name</code></td> -<td><p>Boolean; default is <code>False</code></p> -If true, render labels in the main repository in emitted documentation with a repo component -(in other words, <code>//foo:bar.bzl</code> will be emitted as -<code>@main_repo_name//foo:bar.bzl</code>). -<p>The name to use for the main repository is obtained from <code>module(name = ...)</code> -in the main repository's <code>MODULE.bazel</code> file (if Bzlmod is enabled), or from -<code>workspace(name = ...)</code> in the main repository's <code>WORKSPACE</code> file.</p> -<p>This attribute should be set to <code>False</code> when generating documentation for -Starlark files which are intended to be used only within the same repository, and to -<code>True</code> when generating documentation for Starlark files which are intended to be -used from other repositories.</p></td> -</tr> -<tr> -<td id="starlark_doc_extract.symbol_names"><code>symbol_names</code></td> -<td><p>List of strings; default is <code>[]</code></p> -An optional list of qualified names of exported functions, rules, providers, or aspects (or -structs in which they are nested) for which to extract documentation. Here, a <em>qualified -name</em> means the name under which an entity is made available to a user of the module, -including any structs in which the entity is nested for namespacing. -<p><code>starlark_doc_extract</code> emits documentation for an entity if and only if</p> -<ol> -<li>each component of the entity's qualified name is public (in other words, the first -character of each component of the qualified name is alphabetic, not <code>"_"</code>); -<em>and</em></li> -<li><ol> -<li><em>either</em> the <code>symbol_names</code> list is empty (which is the default -case), <em>or</em></li> -<li>the entity's qualified name, or the qualified name of a struct in which the entity -is nested, is in the <code>symbol_names</code> list.</li> -</ol></li> -</ol></td> -</tr> -</tbody> -</table> - -## test_suite - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` A list of targets wrapping the Starlark files which are `load()`-ed by `src`. These targets *should* under normal usage be [`bzl_library`](https://github.com/bazelbuild/bazel-skylib/blob/main/bzl_library.bzl) targets, but the `starlark_doc_extract` rule does not enforce that, and accepts any target which provides Starlark files in its `DefaultInfo`. Note that the wrapped Starlark files must be files in the source tree; Bazel cannot `load()` generated files. | +| `src` | [Label](./concepts/labels); required A Starlark file from which to extract documentation. Note that this must be a file in the source tree; Bazel cannot `load()` generated files. | +| `allow_unused_doc_comments` | Boolean; default is `False` If true, allow and silently ignore doc comments (comments starting with `#:`) which are not attached to any global variable, or which are attached to a variable whose value's documentation should be provided in a different way (for example, in a docstring for a function, or via `rule(doc = ...)` for a rule). | +| `render_main_repo_name` | Boolean; default is `False` If true, render labels in the main repository in emitted documentation with a repo component (in other words, `//foo:bar.bzl` will be emitted as `@main_repo_name//foo:bar.bzl`). The name to use for the main repository is obtained from `module(name = ...)` in the main repository's `MODULE.bazel` file (if Bzlmod is enabled), or from `workspace(name = ...)` in the main repository's `WORKSPACE` file. This attribute should be set to `False` when generating documentation for Starlark files which are intended to be used only within the same repository, and to `True` when generating documentation for Starlark files which are intended to be used from other repositories. | +| `symbol_names` | List of strings; default is `[]` An optional list of qualified names of exported functions, rules, providers, or aspects (or structs in which they are nested) for which to extract documentation. Here, a *qualified name* means the name under which an entity is made available to a user of the module, including any structs in which the entity is nested for namespacing. `starlark_doc_extract` emits documentation for an entity if and only if 1. each component of the entity's qualified name is public (in other words, the first character of each component of the qualified name is alphabetic, not `"_"`); *and* 2. 1. *either* the `symbol_names` list is empty (which is the default case), *or* 2. the entity's qualified name, or the qualified name of a struct in which the entity is nested, is in the `symbol_names` list. | + +## test\_suite + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java) + +``` test_suite(name, aspect_hints, compatible_with, deprecation, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, tests, visibility) ``` @@ -970,14 +536,13 @@ allows projects to define sets of tests, such as "tests you must run before chec project's stress tests" or "all small tests." The `bazel test` command respects this sort of organization: For an invocation like `bazel test //some/test:suite`, Bazel first enumerates all test targets transitively included by the `//some/test:suite` target (we -call this "test_suite expansion"), then Bazel builds and tests those targets. +call this "test\_suite expansion"), then Bazel builds and tests those targets. #### Examples A test suite to run all of the small tests in the current package. -``` code - +``` test_suite( name = "small_tests", tags = ["small"], @@ -986,8 +551,7 @@ test_suite( A test suite that runs a specified set of tests: -``` code - +``` test_suite( name = "smoke_tests", tests = [ @@ -999,8 +563,7 @@ test_suite( A test suite to run all tests in the current package which are not flaky. -``` code - +``` test_suite( name = "non_flaky_test", tags = ["-flaky"], @@ -1009,62 +572,8 @@ test_suite( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="test_suite.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="test_suite.tags"><code>tags</code></td> -<td><p>List of strings; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -List of text tags such as "small" or "database" or "-flaky". Tags may be any valid string. -<p>Tags which begin with a "-" character are considered negative tags. The -preceding "-" character is not considered part of the tag, so a suite tag -of "-small" matches a test's "small" size. All other tags are considered -positive tags.</p> -<p>Optionally, to make positive tags more explicit, tags may also begin with the -"+" character, which will not be evaluated as part of the text of the tag. It -merely makes the positive and negative distinction easier to read.</p> -<p>Only test rules that match <strong>all</strong> of the positive tags and <strong>none</strong> of the negative -tags will be included in the test suite. Note that this does not mean that error checking -for dependencies on tests that are filtered out is skipped; the dependencies on skipped -tests still need to be legal (e.g. not blocked by visibility constraints).</p> -<p>The <code>manual</code> tag keyword is treated differently than the above by the -"test_suite expansion" performed by the <code>bazel test</code> command on invocations -involving wildcard -<a href="https://bazel.build/docs/build#specifying-build-targets">target patterns</a>. -There, <code>test_suite</code> targets tagged "manual" are filtered out (and thus not -expanded). This behavior is consistent with how <code>bazel build</code> and -<code>bazel test</code> handle wildcard target patterns in general. Note that this is -explicitly different from how <code>bazel query 'tests(E)'</code> behaves, as suites are -always expanded by the <code>tests</code> query function, regardless of the -<code>manual</code> tag.</p> -<p>Note that a test's <code>size</code> is considered a tag for the purpose of filtering.</p> -<p>If you need a <code>test_suite</code> that contains tests with mutually exclusive tags -(e.g. all small and medium tests), you'll have to create three <code>test_suite</code> -rules: one for all small tests, one for all medium tests, and one that includes the -previous two.</p></td> -</tr> -<tr> -<td id="test_suite.tests"><code>tests</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -A list of test suites and test targets of any language. -<p>Any <code>*_test</code> is accepted here, independent of the language. No -<code>*_binary</code> targets are accepted however, even if they happen to run a test. -Filtering by the specified <code>tags</code> is only done for tests listed directly in -this attribute. If this attribute contains <code>test_suite</code>s, the tests inside -those will not be filtered by this <code>test_suite</code> (they are considered to be -filtered already).</p> -<p>If the <code>tests</code> attribute is unspecified or empty, the rule will default to -including all test rules in the current BUILD file that are not tagged as -<code>manual</code>. These rules are still subject to <code>tag</code> filtering.</p></td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `tags` | List of strings; [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` List of text tags such as "small" or "database" or "-flaky". Tags may be any valid string. Tags which begin with a "-" character are considered negative tags. The preceding "-" character is not considered part of the tag, so a suite tag of "-small" matches a test's "small" size. All other tags are considered positive tags. Optionally, to make positive tags more explicit, tags may also begin with the "+" character, which will not be evaluated as part of the text of the tag. It merely makes the positive and negative distinction easier to read. Only test rules that match **all** of the positive tags and **none** of the negative tags will be included in the test suite. Note that this does not mean that error checking for dependencies on tests that are filtered out is skipped; the dependencies on skipped tests still need to be legal (e.g. not blocked by visibility constraints). The `manual` tag keyword is treated differently than the above by the "test\_suite expansion" performed by the `bazel test` command on invocations involving wildcard [target patterns](https://bazel.build/docs/build#specifying-build-targets). There, `test_suite` targets tagged "manual" are filtered out (and thus not expanded). This behavior is consistent with how `bazel build` and `bazel test` handle wildcard target patterns in general. Note that this is explicitly different from how `bazel query 'tests(E)'` behaves, as suites are always expanded by the `tests` query function, regardless of the `manual` tag. Note that a test's `size` is considered a tag for the purpose of filtering. If you need a `test_suite` that contains tests with mutually exclusive tags (e.g. all small and medium tests), you'll have to create three `test_suite` rules: one for all small tests, one for all medium tests, and one that includes the previous two. | +| `tests` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` A list of test suites and test targets of any language. Any `*_test` is accepted here, independent of the language. No `*_binary` targets are accepted however, even if they happen to run a test. Filtering by the specified `tags` is only done for tests listed directly in this attribute. If this attribute contains `test_suite`s, the tests inside those will not be filtered by this `test_suite` (they are considered to be filtered already). If the `tests` attribute is unspecified or empty, the rule will default to including all test rules in the current BUILD file that are not tagged as `manual`. These rules are still subject to `tag` filtering. | \ No newline at end of file diff --git a/reference/be/java.mdx b/reference/be/java.mdx index 1f3d1a4..ec9893e 100644 --- a/reference/be/java.mdx +++ b/reference/be/java.mdx @@ -2,28 +2,24 @@ title: 'java' --- -# Java Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} ## Rules -- [java_binary](#java_binary) -- [java_import](#java_import) -- [java_library](#java_library) -- [java_test](#java_test) -- [java_package_configuration](#java_package_configuration) -- [java_plugin](#java_plugin) -- [java_runtime](#java_runtime) -- [java_single_jar](#java_single_jar) -- [java_toolchain](#java_toolchain) +* [java\_binary](#java_binary) +* [java\_import](#java_import) +* [java\_library](#java_library) +* [java\_test](#java_test) +* [java\_package\_configuration](#java_package_configuration) +* [java\_plugin](#java_plugin) +* [java\_runtime](#java_runtime) +* [java\_single\_jar](#java_single_jar) +* [java\_toolchain](#java_toolchain) -## java_binary +## java\_binary -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_binary.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_binary.bzl) -``` rule-signature +``` java_binary(name, deps, srcs, data, resources, add_exports, add_opens, args, aspect_hints, bootclasspath, classpath_resources, compatible_with, create_executable, deploy_env, deploy_manifest_lines, deprecation, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, javacopts, jvm_flags, launcher, licenses, main_class, neverlink, output_licenses, package_metadata, plugins, resource_strip_prefix, restricted_to, runtime_deps, stamp, tags, target_compatible_with, testonly, toolchains, use_launcher, use_testrunner, visibility) ``` @@ -39,16 +35,14 @@ for a list of configurable flags and environment variables accepted by the wrapp #### Implicit output targets -- `name``.jar`: A Java archive, containing the class files and other +* `name.jar`: A Java archive, containing the class files and other resources corresponding to the binary's direct dependencies. - -- `name``-src.jar`: An archive containing the sources ("source +* `name-src.jar`: An archive containing the sources ("source jar"). - -- `name``_deploy.jar`: A Java archive suitable for deployment (only +* `name_deploy.jar`: A Java archive suitable for deployment (only built if explicitly requested). - Building the `<``name``>_deploy.jar` target for your rule + Building the `<name>_deploy.jar` target for your rule creates a self-contained jar file with a manifest that allows it to be run with the `java -jar` command or with the wrapper script's `--singlejar` option. Using the wrapper script is preferred to `java -jar` because it @@ -67,8 +61,7 @@ for a list of configurable flags and environment variables accepted by the wrapp appended to that native binary, creating a single binary blob containing both the executable and the Java code. You can execute the resulting jar file directly like you would execute any native binary. - -- `name``_deploy-src.jar`: An archive containing the sources +* `name_deploy-src.jar`: An archive containing the sources collected from the transitive closure of the target. These will match the classes in the `deploy.jar` except where jars have no matching source jar. @@ -83,9 +76,7 @@ A `deps` attribute is not allowed in a `java_binary` rule without The following code snippet illustrates a common mistake: -``` code - - +``` java_binary( name = "DontDoThis", srcs = [ @@ -98,9 +89,7 @@ java_binary( Do this instead: -``` code - - +``` java_binary( name = "DoThisInstead", srcs = [ @@ -112,286 +101,47 @@ java_binary( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_binary.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_binary.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries to be linked in to the target. -See general comments about <code>deps</code> at -<a href="common-definitions.html#typical-attributes">Typical attributes defined by -most build rules</a>.</td> -</tr> -<tr> -<td id="java_binary.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of source files that are processed to create the target. -This attribute is almost always required; see exceptions below. -<p>Source files of type <code>.java</code> are compiled. In case of generated -<code>.java</code> files it is generally advisable to put the generating rule's name -here instead of the name of the file itself. This not only improves readability but -makes the rule more resilient to future changes: if the generating rule generates -different files in the future, you only need to fix one place: the <code>outs</code> of -the generating rule. You should not list the generating rule in <code>deps</code> -because it is a no-op.</p> -<p>Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if -you need to generate a set of <code>.java</code> files with a genrule.)</p> -<p>Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates -any of the files listed above, they will be used the same way as described for source -files.</p> -<p>This argument is almost always required, except if a -<a href="#java_binary.main_class"><code>main_class</code></a> attribute specifies a -class on the runtime classpath or you specify the <code>runtime_deps</code> argument.</p></td> -</tr> -<tr> -<td id="java_binary.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this library at runtime. -See general comments about <code>data</code> -at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>.</td> -</tr> -<tr> -<td id="java_binary.resources"><code>resources</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of data files to include in a Java jar. -<p>Resources may be source files or generated files.</p> -<p>If resources are specified, they will be bundled in the jar along with the usual -<code>.class</code> files produced by compilation. The location of the resources inside -of the jar file is determined by the project structure. Bazel first looks for Maven's -<a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, -(a "src" directory followed by a "resources" directory grandchild). If that is not -found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for -example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the -path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, -however, the <code>resource_strip_prefix</code> attribute can be used to specify a -specific alternative directory for resource files.</p></td> -</tr> -<tr> -<td id="java_binary.add_exports"><code>add_exports</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to access the given <code>module</code> or <code>package</code>. -<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> -</tr> -<tr> -<td id="java_binary.add_opens"><code>add_opens</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to reflectively access the given <code>module</code> or -<code>package</code>. -<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> -</tr> -<tr> -<td id="java_binary.bootclasspath"><code>bootclasspath</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Restricted API, do not use!</td> -</tr> -<tr> -<td id="java_binary.classpath_resources"><code>classpath_resources</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<em>DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)</em> -<p>A list of resources that must be located at the root of the java tree. This attribute's -only purpose is to support third-party libraries that require that their resources be -found on the classpath as exactly <code>"myconfig.xml"</code>. It is only allowed on -binaries and not libraries, due to the danger of namespace conflicts.</p></td> -</tr> -<tr> -<td id="java_binary.create_executable"><code>create_executable</code></td> -<td><p>Boolean; default is <code>True</code></p> -Deprecated, use <code>java_single_jar</code> instead.</td> -</tr> -<tr> -<td id="java_binary.deploy_env"><code>deploy_env</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of other <code>java_binary</code> targets which represent the deployment -environment for this binary. -Set this attribute when building a plugin which will be loaded by another -<code>java_binary</code>.<br /> -Setting this attribute excludes all dependencies from -the runtime classpath (and the deploy jar) of this binary that are shared between this -binary and the targets specified in <code>deploy_env</code>.</td> -</tr> -<tr> -<td id="java_binary.deploy_manifest_lines"><code>deploy_manifest_lines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -A list of lines to add to the <code>META-INF/manifest.mf</code> file generated for the -<code>*_deploy.jar</code> target. The contents of this attribute are <em>not</em> subject -to <a href="make-variables.html">"Make variable"</a> substitution.</td> -</tr> -<tr> -<td id="java_binary.javacopts"><code>javacopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra compiler options for this binary. -Subject to <a href="make-variables.html">"Make variable"</a> substitution and -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>These compiler options are passed to javac after the global compiler options.</p></td> -</tr> -<tr> -<td id="java_binary.jvm_flags"><code>jvm_flags</code></td> -<td><p>List of strings; default is <code>[]</code></p> -A list of flags to embed in the wrapper script generated for running this binary. -Subject to <a href="/reference/be/make-variables#location">$(location)</a> and -<a href="make-variables.html">"Make variable"</a> substitution, and -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>The wrapper script for a Java binary includes a CLASSPATH definition -(to find all the dependent jars) and invokes the right Java interpreter. -The command line generated by the wrapper script includes the name of -the main class followed by a <code>"$@"</code> so you can pass along other -arguments after the classname. However, arguments intended for parsing -by the JVM must be specified <em>before</em> the classname on the command -line. The contents of <code>jvm_flags</code> are added to the wrapper -script before the classname is listed.</p> -<p>Note that this attribute has <em>no effect</em> on <code>*_deploy.jar</code> -outputs.</p></td> -</tr> -<tr> -<td id="java_binary.launcher"><code>launcher</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Specify a binary that will be used to run your Java program instead of the -normal <code>bin/java</code> program included with the JDK. -The target must be a <code>cc_binary</code>. Any <code>cc_binary</code> that -implements the -<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html">Java Invocation API</a> can be specified as a value for this attribute. -<p>By default, Bazel will use the normal JDK launcher (bin/java or java.exe).</p> -<p>The related <a href="/docs/user-manual#flag--java_launcher"><code> --java_launcher</code></a> Bazel flag affects only those -<code>java_binary</code> and <code>java_test</code> targets that have -<em>not</em> specified a <code>launcher</code> attribute.</p> -<p>Note that your native (C++, SWIG, JNI) dependencies will be built differently -depending on whether you are using the JDK launcher or another launcher:</p> -<ul> -<li>If you are using the normal JDK launcher (the default), native dependencies are -built as a shared library named <code>{name}_nativedeps.so</code>, where -<code>{name}</code> is the <code>name</code> attribute of this java_binary rule. -Unused code is <em>not</em> removed by the linker in this configuration.</li> -<li>If you are using any other launcher, native (C++) dependencies are statically -linked into a binary named <code>{name}_nativedeps</code>, where <code>{name}</code> -is the <code>name</code> attribute of this java_binary rule. In this case, -the linker will remove any code it thinks is unused from the resulting binary, -which means any C++ code accessed only via JNI may not be linked in unless -that <code>cc_library</code> target specifies <code>alwayslink = True</code>.</li> -</ul> -<p>When using any launcher other than the default JDK launcher, the format -of the <code>*_deploy.jar</code> output changes. See the main -<a href="#java_binary">java_binary</a> docs for details.</p></td> -</tr> -<tr> -<td id="java_binary.main_class"><code>main_class</code></td> -<td><p>String; default is <code>""</code></p> -Name of class with <code>main()</code> method to use as entry point. -If a rule uses this option, it does not need a <code>srcs=[...]</code> list. -Thus, with this attribute one can make an executable from a Java library that already -contains one or more <code>main()</code> methods. -<p>The value of this attribute is a class name, not a source file. The class must be -available at runtime: it may be compiled by this rule (from <code>srcs</code>) or -provided by direct or transitive dependencies (through <code>runtime_deps</code> or -<code>deps</code>). If the class is unavailable, the binary will fail at runtime; there -is no build-time check.</p></td> -</tr> -<tr> -<td id="java_binary.neverlink"><code>neverlink</code></td> -<td><p>Boolean; default is <code>False</code></p></td> -</tr> -<tr> -<td id="java_binary.plugins"><code>plugins</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Java compiler plugins to run at compile-time. -Every <code>java_plugin</code> specified in this attribute will be run whenever this rule -is built. A library may also inherit plugins from dependencies that use -<a href="#java_library.exported_plugins"><code>exported_plugins</code></a>. Resources -generated by the plugin will be included in the resulting jar of this rule.</td> -</tr> -<tr> -<td id="java_binary.resource_strip_prefix"><code>resource_strip_prefix</code></td> -<td><p>String; default is <code>""</code></p> -The path prefix to strip from Java resources. -<p>If specified, this path prefix is stripped from every file in the <code>resources</code> -attribute. It is an error for a resource file not to be under this directory. If not -specified (the default), the path of resource file is determined according to the same -logic as the Java package of source files. For example, a source file at -<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.</p></td> -</tr> -<tr> -<td id="java_binary.runtime_deps"><code>runtime_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Libraries to make available to the final binary or test at runtime only. -Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike -them, not on the compile-time classpath. Dependencies needed only at runtime should be -listed here. Dependency-analysis tools should ignore targets that appear in both -<code>runtime_deps</code> and <code>deps</code>.</td> -</tr> -<tr> -<td id="java_binary.stamp"><code>stamp</code></td> -<td><p>Integer; default is <code>-1</code></p> -Whether to encode build information into the binary. Possible values: -<ul> -<li><code>stamp = 1</code>: Always stamp the build information into the binary, even in -<a href="/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <strong>This -setting should be avoided</strong>, since it potentially kills remote caching for the -binary and any downstream actions that depend on it.</li> -<li><code>stamp = 0</code>: Always replace build information by constant values. This -gives good build result caching.</li> -<li><code>stamp = -1</code>: Embedding of build information is controlled by the -<a href="/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.</li> -</ul> -<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p></td> -</tr> -<tr> -<td id="java_binary.use_launcher"><code>use_launcher</code></td> -<td><p>Boolean; default is <code>True</code></p> -Whether the binary should use a custom launcher. -<p>If this attribute is set to false, the -<a href="/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related -<a href="/docs/user-manual#flag--java_launcher"><code>--java_launcher</code></a> flag -will be ignored for this target.</p></td> -</tr> -<tr> -<td id="java_binary.use_testrunner"><code>use_testrunner</code></td> -<td><p>Boolean; default is <code>False</code></p> -Use the test runner (by default -<code>com.google.testing.junit.runner.BazelTestRunner</code>) class as the -main entry point for a Java program, and provide the test class -to the test runner as a value of <code>bazel.test_suite</code> -system property.<br /> -You can use this to override the default -behavior, which is to use test runner for -<code>java_test</code> rules, -and not use it for <code>java_binary</code> rules. It is unlikely -you will want to do this. One use is for <code>AllTest</code> -rules that are invoked by another rule (to set up a database -before running the tests, for example). The <code>AllTest</code> -rule must be declared as a <code>java_binary</code>, but should -still use the test runner as its main entry point. -The name of a test runner class can be overridden with <code>main_class</code> attribute.</td> -</tr> -</tbody> -</table> - -## java_import - -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_import.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the target. See general comments about `deps` at [Typical attributes defined by most build rules](common-definitions.html#typical-attributes). | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. Source files of type `.java` are compiled. In case of generated `.java` files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the `outs` of the generating rule. You should not list the generating rule in `deps` because it is a no-op. Source files of type `.srcjar` are unpacked and compiled. (This is useful if you need to generate a set of `.java` files with a genrule.) Rules: if the rule (typically `genrule` or `filegroup`) generates any of the files listed above, they will be used the same way as described for source files. This argument is almost always required, except if a [`main_class`](#java_binary.main_class) attribute specifies a class on the runtime classpath or you specify the `runtime_deps` argument. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). | +| `resources` | List of [labels](./concepts/labels); default is `[]` A list of data files to include in a Java jar. Resources may be source files or generated files. If resources are specified, they will be bundled in the jar along with the usual `.class` files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's [standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.mdx), (a "src" directory followed by a "resources" directory grandchild). If that is not found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for example, if a resource is at `\<workspace root\>/x/java/y/java/z`, the path of the resource will be `y/java/z`. This heuristic cannot be overridden, however, the `resource_strip_prefix` attribute can be used to specify a specific alternative directory for resource files. | +| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | +| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | +| `bootclasspath` | [Label](./concepts/labels); default is `None` Restricted API, do not use! | +| `classpath_resources` | List of [labels](./concepts/labels); default is `[]` *DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)* A list of resources that must be located at the root of the java tree. This attribute's only purpose is to support third-party libraries that require that their resources be found on the classpath as exactly `"myconfig.xml"`. It is only allowed on binaries and not libraries, due to the danger of namespace conflicts. | +| `create_executable` | Boolean; default is `True` Deprecated, use `java_single_jar` instead. | +| `deploy_env` | List of [labels](./concepts/labels); default is `[]` A list of other `java_binary` targets which represent the deployment environment for this binary. Set this attribute when building a plugin which will be loaded by another `java_binary`. Setting this attribute excludes all dependencies from the runtime classpath (and the deploy jar) of this binary that are shared between this binary and the targets specified in `deploy_env`. | +| `deploy_manifest_lines` | List of strings; default is `[]` A list of lines to add to the `META-INF/manifest.mf` file generated for the `*_deploy.jar` target. The contents of this attribute are *not* subject to ["Make variable"](make-variables.mdx) substitution. | +| `javacopts` | List of strings; default is `[]` Extra compiler options for this binary. Subject to ["Make variable"](make-variables.mdx) substitution and [Bourne shell tokenization](common-definitions.html#sh-tokenization). These compiler options are passed to javac after the global compiler options. | +| `jvm_flags` | List of strings; default is `[]` A list of flags to embed in the wrapper script generated for running this binary. Subject to [$(location)](./reference/be/make-variables#location) and ["Make variable"](make-variables.mdx) substitution, and [Bourne shell tokenization](common-definitions.html#sh-tokenization). The wrapper script for a Java binary includes a CLASSPATH definition (to find all the dependent jars) and invokes the right Java interpreter. The command line generated by the wrapper script includes the name of the main class followed by a `"$@"` so you can pass along other arguments after the classname. However, arguments intended for parsing by the JVM must be specified *before* the classname on the command line. The contents of `jvm_flags` are added to the wrapper script before the classname is listed. Note that this attribute has *no effect* on `*_deploy.jar` outputs. | +| `launcher` | [Label](./concepts/labels); default is `None` Specify a binary that will be used to run your Java program instead of the normal `bin/java` program included with the JDK. The target must be a `cc_binary`. Any `cc_binary` that implements the [Java Invocation API](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.mdx) can be specified as a value for this attribute. By default, Bazel will use the normal JDK launcher (bin/java or java.exe). The related [`--java_launcher`](./docs/user-manual#flag--java_launcher) Bazel flag affects only those `java_binary` and `java_test` targets that have *not* specified a `launcher` attribute. Note that your native (C++, SWIG, JNI) dependencies will be built differently depending on whether you are using the JDK launcher or another launcher: * If you are using the normal JDK launcher (the default), native dependencies are built as a shared library named `\{name\}_nativedeps.so`, where `\{name\}` is the `name` attribute of this java\_binary rule. Unused code is *not* removed by the linker in this configuration. * If you are using any other launcher, native (C++) dependencies are statically linked into a binary named `\{name\}_nativedeps`, where `\{name\}` is the `name` attribute of this java\_binary rule. In this case, the linker will remove any code it thinks is unused from the resulting binary, which means any C++ code accessed only via JNI may not be linked in unless that `cc_library` target specifies `alwayslink = True`. When using any launcher other than the default JDK launcher, the format of the `*_deploy.jar` output changes. See the main [java\_binary](#java_binary) docs for details. | +| `main_class` | String; default is `""` Name of class with `main()` method to use as entry point. If a rule uses this option, it does not need a `srcs=[...]` list. Thus, with this attribute one can make an executable from a Java library that already contains one or more `main()` methods. The value of this attribute is a class name, not a source file. The class must be available at runtime: it may be compiled by this rule (from `srcs`) or provided by direct or transitive dependencies (through `runtime_deps` or `deps`). If the class is unavailable, the binary will fail at runtime; there is no build-time check. | +| `neverlink` | Boolean; default is `False` | +| `plugins` | List of [labels](./concepts/labels); default is `[]` Java compiler plugins to run at compile-time. Every `java_plugin` specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use `exported_plugins`. Resources generated by the plugin will be included in the resulting jar of this rule. | +| `resource_strip_prefix` | String; default is `""` The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at `stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. | +| `runtime_deps` | List of [labels](./concepts/labels); default is `[]` Libraries to make available to the final binary or test at runtime only. Like ordinary `deps`, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both `runtime_deps` and `deps`. | +| `stamp` | Integer; default is `-1` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](./docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | +| `use_launcher` | Boolean; default is `True` Whether the binary should use a custom launcher. If this attribute is set to false, the [launcher](./reference/be/java.html#java_binary.launcher) attribute and the related [`--java_launcher`](./docs/user-manual#flag--java_launcher) flag will be ignored for this target. | +| `use_testrunner` | Boolean; default is `False` Use the test runner (by default `com.google.testing.junit.runner.BazelTestRunner`) class as the main entry point for a Java program, and provide the test class to the test runner as a value of `bazel.test_suite` system property. You can use this to override the default behavior, which is to use test runner for `java_test` rules, and not use it for `java_binary` rules. It is unlikely you will want to do this. One use is for `AllTest` rules that are invoked by another rule (to set up a database before running the tests, for example). The `AllTest` rule must be declared as a `java_binary`, but should still use the test runner as its main entry point. The name of a test runner class can be overridden with `main_class` attribute. | + +## java\_import + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_import.bzl) + +``` java_import(name, deps, data, add_exports, add_opens, aspect_hints, compatible_with, constraints, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exports, features, jars, licenses, neverlink, package_metadata, proguard_specs, restricted_to, runtime_deps, srcjar, tags, target_compatible_with, testonly, toolchains, visibility) ``` This rule allows the use of precompiled `.jar` files as -libraries for [`java_library`](#java_library) and +libraries for `java_library` and `java_binary` rules. #### Examples -``` code - - +``` java_import( name = "maven_model", jars = [ @@ -404,96 +154,26 @@ libraries for [`java_library`](#java_library) and ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_import.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_import.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries to be linked in to the target. -See <a href="/reference/be/java.html#java_library.deps">java_library.deps</a>.</td> -</tr> -<tr> -<td id="java_import.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this rule at runtime.</td> -</tr> -<tr> -<td id="java_import.add_exports"><code>add_exports</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to access the given <code>module</code> or <code>package</code>. -<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> -</tr> -<tr> -<td id="java_import.add_opens"><code>add_opens</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to reflectively access the given <code>module</code> or -<code>package</code>. -<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> -</tr> -<tr> -<td id="java_import.constraints"><code>constraints</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra constraints imposed on this rule as a Java library.</td> -</tr> -<tr> -<td id="java_import.exports"><code>exports</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Targets to make available to users of this rule. -See <a href="/reference/be/java.html#java_library.exports">java_library.exports</a>.</td> -</tr> -<tr> -<td id="java_import.jars"><code>jars</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; required</p> -The list of JAR files provided to Java targets that depend on this target.</td> -</tr> -<tr> -<td id="java_import.neverlink"><code>neverlink</code></td> -<td><p>Boolean; default is <code>False</code></p> -Only use this library for compilation and not at runtime. -Useful if the library will be provided by the runtime environment -during execution. Examples of libraries like this are IDE APIs -for IDE plug-ins or <code>tools.jar</code> for anything running on -a standard JDK.</td> -</tr> -<tr> -<td id="java_import.proguard_specs"><code>proguard_specs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Files to be used as Proguard specification. -These will describe the set of specifications to be used by Proguard. If specified, -they will be added to any <code>android_binary</code> target depending on this library. -The files included here must only have idempotent rules, namely -dontnote, -dontwarn, -assumenosideeffects, and rules that start with -keep. Other options can only appear in -<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges.</td> -</tr> -<tr> -<td id="java_import.runtime_deps"><code>runtime_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Libraries to make available to the final binary or test at runtime only. -See <a href="/reference/be/java.html#java_library.runtime_deps">java_library.runtime_deps</a>.</td> -</tr> -<tr> -<td id="java_import.srcjar"><code>srcjar</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -A JAR file that contains source code for the compiled JAR files.</td> -</tr> -</tbody> -</table> - -## java_library - -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the target. See [java\_library.deps](./reference/be/java.html#java_library.deps). | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this rule at runtime. | +| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | +| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | +| `constraints` | List of strings; default is `[]` Extra constraints imposed on this rule as a Java library. | +| `exports` | List of [labels](./concepts/labels); default is `[]` Targets to make available to users of this rule. See [java\_library.exports](./reference/be/java.html#java_library.exports). | +| `jars` | List of [labels](./concepts/labels); required The list of JAR files provided to Java targets that depend on this target. | +| `neverlink` | Boolean; default is `False` Only use this library for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of libraries like this are IDE APIs for IDE plug-ins or `tools.jar` for anything running on a standard JDK. | +| `proguard_specs` | List of [labels](./concepts/labels); default is `[]` Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any `android_binary` target depending on this library. The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in `android_binary`'s proguard\_specs, to ensure non-tautological merges. | +| `runtime_deps` | List of [labels](./concepts/labels); default is `[]` Libraries to make available to the final binary or test at runtime only. See [java\_library.runtime\_deps](./reference/be/java.html#java_library.runtime_deps). | +| `srcjar` | [Label](./concepts/labels); default is `None` A JAR file that contains source code for the compiled JAR files. | + +## java\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_library.bzl) + +``` java_library(name, deps, srcs, data, resources, add_exports, add_opens, aspect_hints, bootclasspath, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exported_plugins, exports, features, javabuilder_jvm_flags, javacopts, licenses, neverlink, package_metadata, plugins, proguard_specs, resource_strip_prefix, restricted_to, runtime_deps, tags, target_compatible_with, testonly, toolchains, visibility) ``` @@ -501,213 +181,37 @@ This rule compiles and links sources into a `.jar` file. #### Implicit outputs -- `lib``name``.jar`: A Java archive containing the class files. -- `lib``name``-src.jar`: An archive containing the sources ("source +* `libname.jar`: A Java archive containing the class files. +* `libname-src.jar`: An archive containing the sources ("source jar"). ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of libraries to link into this library. -See general comments about <code>deps</code> at -<a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. -<p>The jars built by <code>java_library</code> rules listed in <code>deps</code> will be on -the compile-time classpath of this rule. Furthermore the transitive closure of their -<code>deps</code>, <code>runtime_deps</code> and <code>exports</code> will be on the -runtime classpath.</p> -<p>By contrast, targets in the <code>data</code> attribute are included in the runfiles but -on neither the compile-time nor runtime classpath.</p></td> -</tr> -<tr> -<td id="java_library.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of source files that are processed to create the target. -This attribute is almost always required; see exceptions below. -<p>Source files of type <code>.java</code> are compiled. In case of generated -<code>.java</code> files it is generally advisable to put the generating rule's name -here instead of the name of the file itself. This not only improves readability but -makes the rule more resilient to future changes: if the generating rule generates -different files in the future, you only need to fix one place: the <code>outs</code> of -the generating rule. You should not list the generating rule in <code>deps</code> -because it is a no-op.</p> -<p>Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if -you need to generate a set of <code>.java</code> files with a genrule.)</p> -<p>Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates -any of the files listed above, they will be used the same way as described for source -files.</p> -<p>Source files of type <code>.properties</code> are treated as resources.</p> -<p>All other files are ignored, as long as there is at least one file of a -file type described above. Otherwise an error is raised.</p> -<p>This argument is almost always required, except if you specify the <code>runtime_deps</code> argument.</p></td> -</tr> -<tr> -<td id="java_library.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this library at runtime. -See general comments about <code>data</code> at -<a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. -<p>When building a <code>java_library</code>, Bazel doesn't put these files anywhere; if the -<code>data</code> files are generated files then Bazel generates them. When building a -test that depends on this <code>java_library</code> Bazel copies or links the -<code>data</code> files into the runfiles area.</p></td> -</tr> -<tr> -<td id="java_library.resources"><code>resources</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of data files to include in a Java jar. -<p>Resources may be source files or generated files.</p> -<p>If resources are specified, they will be bundled in the jar along with the usual -<code>.class</code> files produced by compilation. The location of the resources inside -of the jar file is determined by the project structure. Bazel first looks for Maven's -<a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, -(a "src" directory followed by a "resources" directory grandchild). If that is not -found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for -example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the -path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, -however, the <code>resource_strip_prefix</code> attribute can be used to specify a -specific alternative directory for resource files.</p></td> -</tr> -<tr> -<td id="java_library.add_exports"><code>add_exports</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to access the given <code>module</code> or <code>package</code>. -<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> -</tr> -<tr> -<td id="java_library.add_opens"><code>add_opens</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to reflectively access the given <code>module</code> or -<code>package</code>. -<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> -</tr> -<tr> -<td id="java_library.bootclasspath"><code>bootclasspath</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Restricted API, do not use!</td> -</tr> -<tr> -<td id="java_library.exported_plugins"><code>exported_plugins</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of <a href="#/reference/be/java.html#java_plugin"><code>java_plugin</code></a>s (e.g. annotation -processors) to export to libraries that directly depend on this library. -<p>The specified list of <code>java_plugin</code>s will be applied to any library which -directly depends on this library, just as if that library had explicitly declared these -labels in <a href="/reference/be/java.html#java_library.plugins"><code>plugins</code></a>.</p></td> -</tr> -<tr> -<td id="java_library.exports"><code>exports</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Exported libraries. -<p>Listing rules here will make them available to parent rules, as if the parents explicitly -depended on these rules. This is not true for regular (non-exported) <code>deps</code>.</p> -<p>Summary: a rule <em>X</em> can access the code in <em>Y</em> if there exists a dependency -path between them that begins with a <code>deps</code> edge followed by zero or more -<code>exports</code> edges. Let's see some examples to illustrate this.</p> -<p>Assume <em>A</em> depends on <em>B</em> and <em>B</em> depends on <em>C</em>. In this case -C is a <em>transitive</em> dependency of A, so changing C's sources and rebuilding A will -correctly rebuild everything. However A will not be able to use classes in C. To allow -that, either A has to declare C in its <code>deps</code>, or B can make it easier for A -(and anything that may depend on A) by declaring C in its (B's) <code>exports</code> -attribute.</p> -<p>The closure of exported libraries is available to all direct parent rules. Take a slightly -different example: A depends on B, B depends on C and D, and also exports C but not D. -Now A has access to C but not to D. Now, if C and D exported some libraries, C' and D' -respectively, A could only access C' but not D'.</p> -<p>Important: an exported rule is not a regular dependency. Sticking to the previous example, -if B exports C and wants to also use C, it has to also list it in its own -<code>deps</code>.</p></td> -</tr> -<tr> -<td id="java_library.javabuilder_jvm_flags"><code>javabuilder_jvm_flags</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Restricted API, do not use!</td> -</tr> -<tr> -<td id="java_library.javacopts"><code>javacopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra compiler options for this library. -Subject to <a href="make-variables.html">"Make variable"</a> substitution and -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>These compiler options are passed to javac after the global compiler options.</p></td> -</tr> -<tr> -<td id="java_library.neverlink"><code>neverlink</code></td> -<td><p>Boolean; default is <code>False</code></p> -Whether this library should only be used for compilation and not at runtime. -Useful if the library will be provided by the runtime environment during execution. Examples -of such libraries are the IDE APIs for IDE plug-ins or <code>tools.jar</code> for anything -running on a standard JDK. -<p>Note that <code>neverlink = True</code> does not prevent the compiler from inlining material -from this library into compilation targets that depend on it, as permitted by the Java -Language Specification (e.g., <code>static final</code> constants of <code>String</code> -or of primitive types). The preferred use case is therefore when the runtime library is -identical to the compilation library.</p> -<p>If the runtime library differs from the compilation library then you must ensure that it -differs only in places that the JLS forbids compilers to inline (and that must hold for -all future versions of the JLS).</p></td> -</tr> -<tr> -<td id="java_library.plugins"><code>plugins</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Java compiler plugins to run at compile-time. -Every <code>java_plugin</code> specified in this attribute will be run whenever this rule -is built. A library may also inherit plugins from dependencies that use -<a href="#java_library.exported_plugins"><code>exported_plugins</code></a>. Resources -generated by the plugin will be included in the resulting jar of this rule.</td> -</tr> -<tr> -<td id="java_library.proguard_specs"><code>proguard_specs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Files to be used as Proguard specification. -These will describe the set of specifications to be used by Proguard. If specified, -they will be added to any <code>android_binary</code> target depending on this library. -The files included here must only have idempotent rules, namely -dontnote, -dontwarn, -assumenosideeffects, and rules that start with -keep. Other options can only appear in -<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges.</td> -</tr> -<tr> -<td id="java_library.resource_strip_prefix"><code>resource_strip_prefix</code></td> -<td><p>String; default is <code>""</code></p> -The path prefix to strip from Java resources. -<p>If specified, this path prefix is stripped from every file in the <code>resources</code> -attribute. It is an error for a resource file not to be under this directory. If not -specified (the default), the path of resource file is determined according to the same -logic as the Java package of source files. For example, a source file at -<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.</p></td> -</tr> -<tr> -<td id="java_library.runtime_deps"><code>runtime_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Libraries to make available to the final binary or test at runtime only. -Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike -them, not on the compile-time classpath. Dependencies needed only at runtime should be -listed here. Dependency-analysis tools should ignore targets that appear in both -<code>runtime_deps</code> and <code>deps</code>.</td> -</tr> -</tbody> -</table> - -## java_test - -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_test.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of libraries to link into this library. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). The jars built by `java_library` rules listed in `deps` will be on the compile-time classpath of this rule. Furthermore the transitive closure of their `deps`, `runtime_deps` and `exports` will be on the runtime classpath. By contrast, targets in the `data` attribute are included in the runfiles but on neither the compile-time nor runtime classpath. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. Source files of type `.java` are compiled. In case of generated `.java` files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the `outs` of the generating rule. You should not list the generating rule in `deps` because it is a no-op. Source files of type `.srcjar` are unpacked and compiled. (This is useful if you need to generate a set of `.java` files with a genrule.) Rules: if the rule (typically `genrule` or `filegroup`) generates any of the files listed above, they will be used the same way as described for source files. Source files of type `.properties` are treated as resources. All other files are ignored, as long as there is at least one file of a file type described above. Otherwise an error is raised. This argument is almost always required, except if you specify the `runtime_deps` argument. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). When building a `java_library`, Bazel doesn't put these files anywhere; if the `data` files are generated files then Bazel generates them. When building a test that depends on this `java_library` Bazel copies or links the `data` files into the runfiles area. | +| `resources` | List of [labels](./concepts/labels); default is `[]` A list of data files to include in a Java jar. Resources may be source files or generated files. If resources are specified, they will be bundled in the jar along with the usual `.class` files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's [standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.mdx), (a "src" directory followed by a "resources" directory grandchild). If that is not found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for example, if a resource is at `\<workspace root\>/x/java/y/java/z`, the path of the resource will be `y/java/z`. This heuristic cannot be overridden, however, the `resource_strip_prefix` attribute can be used to specify a specific alternative directory for resource files. | +| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | +| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | +| `bootclasspath` | [Label](./concepts/labels); default is `None` Restricted API, do not use! | +| `exported_plugins` | List of [labels](./concepts/labels); default is `[]` The list of `java_plugin`s (e.g. annotation processors) to export to libraries that directly depend on this library. The specified list of `java_plugin`s will be applied to any library which directly depends on this library, just as if that library had explicitly declared these labels in `plugins`. | +| `exports` | List of [labels](./concepts/labels); default is `[]` Exported libraries. Listing rules here will make them available to parent rules, as if the parents explicitly depended on these rules. This is not true for regular (non-exported) `deps`. Summary: a rule *X* can access the code in *Y* if there exists a dependency path between them that begins with a `deps` edge followed by zero or more `exports` edges. Let's see some examples to illustrate this. Assume *A* depends on *B* and *B* depends on *C*. In this case C is a *transitive* dependency of A, so changing C's sources and rebuilding A will correctly rebuild everything. However A will not be able to use classes in C. To allow that, either A has to declare C in its `deps`, or B can make it easier for A (and anything that may depend on A) by declaring C in its (B's) `exports` attribute. The closure of exported libraries is available to all direct parent rules. Take a slightly different example: A depends on B, B depends on C and D, and also exports C but not D. Now A has access to C but not to D. Now, if C and D exported some libraries, C' and D' respectively, A could only access C' but not D'. Important: an exported rule is not a regular dependency. Sticking to the previous example, if B exports C and wants to also use C, it has to also list it in its own `deps`. | +| `javabuilder_jvm_flags` | List of strings; default is `[]` Restricted API, do not use! | +| `javacopts` | List of strings; default is `[]` Extra compiler options for this library. Subject to ["Make variable"](make-variables.mdx) substitution and [Bourne shell tokenization](common-definitions.html#sh-tokenization). These compiler options are passed to javac after the global compiler options. | +| `neverlink` | Boolean; default is `False` Whether this library should only be used for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of such libraries are the IDE APIs for IDE plug-ins or `tools.jar` for anything running on a standard JDK. Note that `neverlink = True` does not prevent the compiler from inlining material from this library into compilation targets that depend on it, as permitted by the Java Language Specification (e.g., `static final` constants of `String` or of primitive types). The preferred use case is therefore when the runtime library is identical to the compilation library. If the runtime library differs from the compilation library then you must ensure that it differs only in places that the JLS forbids compilers to inline (and that must hold for all future versions of the JLS). | +| `plugins` | List of [labels](./concepts/labels); default is `[]` Java compiler plugins to run at compile-time. Every `java_plugin` specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use `exported_plugins`. Resources generated by the plugin will be included in the resulting jar of this rule. | +| `proguard_specs` | List of [labels](./concepts/labels); default is `[]` Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any `android_binary` target depending on this library. The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in `android_binary`'s proguard\_specs, to ensure non-tautological merges. | +| `resource_strip_prefix` | String; default is `""` The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at `stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. | +| `runtime_deps` | List of [labels](./concepts/labels); default is `[]` Libraries to make available to the final binary or test at runtime only. Like ordinary `deps`, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both `runtime_deps` and `deps`. | + +## java\_test + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_test.bzl) + +``` java_test(name, deps, srcs, data, resources, add_exports, add_opens, args, aspect_hints, bootclasspath, classpath_resources, compatible_with, create_executable, deploy_manifest_lines, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, javacopts, jvm_flags, launcher, licenses, local, main_class, neverlink, package_metadata, plugins, resource_strip_prefix, restricted_to, runtime_deps, shard_count, size, stamp, tags, target_compatible_with, test_class, testonly, timeout, toolchains, use_launcher, use_testrunner, visibility) ``` @@ -716,11 +220,11 @@ test code. The test runner's main method is invoked instead of the main class be #### Implicit output targets -- `name``.jar`: A Java archive. -- `name``_deploy.jar`: A Java archive suitable +* `name.jar`: A Java archive. +* `name_deploy.jar`: A Java archive suitable for deployment. (Only built if explicitly requested.) See the description of the - `name``_deploy.jar` output from - [java_binary](#java_binary) for more details. + `name_deploy.jar` output from + [java\_binary](#java_binary) for more details. See the section on `java_binary()` arguments. This rule also supports all [attributes common @@ -728,10 +232,7 @@ to all test rules (\*\_test)](https://bazel.build/reference/be/common-definition #### Examples -``` code - - - +``` java_library( name = "tests", srcs = glob(["*.java"]), @@ -753,302 +254,47 @@ java_test( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_test.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_test.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries to be linked in to the target. -See general comments about <code>deps</code> at -<a href="common-definitions.html#typical-attributes">Typical attributes defined by -most build rules</a>.</td> -</tr> -<tr> -<td id="java_test.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of source files that are processed to create the target. -This attribute is almost always required; see exceptions below. -<p>Source files of type <code>.java</code> are compiled. In case of generated -<code>.java</code> files it is generally advisable to put the generating rule's name -here instead of the name of the file itself. This not only improves readability but -makes the rule more resilient to future changes: if the generating rule generates -different files in the future, you only need to fix one place: the <code>outs</code> of -the generating rule. You should not list the generating rule in <code>deps</code> -because it is a no-op.</p> -<p>Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if -you need to generate a set of <code>.java</code> files with a genrule.)</p> -<p>Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates -any of the files listed above, they will be used the same way as described for source -files.</p> -<p>This argument is almost always required, except if a -<a href="#java_binary.main_class"><code>main_class</code></a> attribute specifies a -class on the runtime classpath or you specify the <code>runtime_deps</code> argument.</p></td> -</tr> -<tr> -<td id="java_test.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this library at runtime. -See general comments about <code>data</code> -at <a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>.</td> -</tr> -<tr> -<td id="java_test.resources"><code>resources</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of data files to include in a Java jar. -<p>Resources may be source files or generated files.</p> -<p>If resources are specified, they will be bundled in the jar along with the usual -<code>.class</code> files produced by compilation. The location of the resources inside -of the jar file is determined by the project structure. Bazel first looks for Maven's -<a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, -(a "src" directory followed by a "resources" directory grandchild). If that is not -found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for -example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the -path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, -however, the <code>resource_strip_prefix</code> attribute can be used to specify a -specific alternative directory for resource files.</p></td> -</tr> -<tr> -<td id="java_test.add_exports"><code>add_exports</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to access the given <code>module</code> or <code>package</code>. -<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> -</tr> -<tr> -<td id="java_test.add_opens"><code>add_opens</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to reflectively access the given <code>module</code> or -<code>package</code>. -<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> -</tr> -<tr> -<td id="java_test.bootclasspath"><code>bootclasspath</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Restricted API, do not use!</td> -</tr> -<tr> -<td id="java_test.classpath_resources"><code>classpath_resources</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -<em>DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)</em> -<p>A list of resources that must be located at the root of the java tree. This attribute's -only purpose is to support third-party libraries that require that their resources be -found on the classpath as exactly <code>"myconfig.xml"</code>. It is only allowed on -binaries and not libraries, due to the danger of namespace conflicts.</p></td> -</tr> -<tr> -<td id="java_test.create_executable"><code>create_executable</code></td> -<td><p>Boolean; default is <code>True</code></p> -Deprecated, use <code>java_single_jar</code> instead.</td> -</tr> -<tr> -<td id="java_test.deploy_manifest_lines"><code>deploy_manifest_lines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -A list of lines to add to the <code>META-INF/manifest.mf</code> file generated for the -<code>*_deploy.jar</code> target. The contents of this attribute are <em>not</em> subject -to <a href="make-variables.html">"Make variable"</a> substitution.</td> -</tr> -<tr> -<td id="java_test.javacopts"><code>javacopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra compiler options for this binary. -Subject to <a href="make-variables.html">"Make variable"</a> substitution and -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>These compiler options are passed to javac after the global compiler options.</p></td> -</tr> -<tr> -<td id="java_test.jvm_flags"><code>jvm_flags</code></td> -<td><p>List of strings; default is <code>[]</code></p> -A list of flags to embed in the wrapper script generated for running this binary. -Subject to <a href="/reference/be/make-variables#location">$(location)</a> and -<a href="make-variables.html">"Make variable"</a> substitution, and -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>The wrapper script for a Java binary includes a CLASSPATH definition -(to find all the dependent jars) and invokes the right Java interpreter. -The command line generated by the wrapper script includes the name of -the main class followed by a <code>"$@"</code> so you can pass along other -arguments after the classname. However, arguments intended for parsing -by the JVM must be specified <em>before</em> the classname on the command -line. The contents of <code>jvm_flags</code> are added to the wrapper -script before the classname is listed.</p> -<p>Note that this attribute has <em>no effect</em> on <code>*_deploy.jar</code> -outputs.</p></td> -</tr> -<tr> -<td id="java_test.launcher"><code>launcher</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Specify a binary that will be used to run your Java program instead of the -normal <code>bin/java</code> program included with the JDK. -The target must be a <code>cc_binary</code>. Any <code>cc_binary</code> that -implements the -<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html">Java Invocation API</a> can be specified as a value for this attribute. -<p>By default, Bazel will use the normal JDK launcher (bin/java or java.exe).</p> -<p>The related <a href="/docs/user-manual#flag--java_launcher"><code> --java_launcher</code></a> Bazel flag affects only those -<code>java_binary</code> and <code>java_test</code> targets that have -<em>not</em> specified a <code>launcher</code> attribute.</p> -<p>Note that your native (C++, SWIG, JNI) dependencies will be built differently -depending on whether you are using the JDK launcher or another launcher:</p> -<ul> -<li>If you are using the normal JDK launcher (the default), native dependencies are -built as a shared library named <code>{name}_nativedeps.so</code>, where -<code>{name}</code> is the <code>name</code> attribute of this java_binary rule. -Unused code is <em>not</em> removed by the linker in this configuration.</li> -<li>If you are using any other launcher, native (C++) dependencies are statically -linked into a binary named <code>{name}_nativedeps</code>, where <code>{name}</code> -is the <code>name</code> attribute of this java_binary rule. In this case, -the linker will remove any code it thinks is unused from the resulting binary, -which means any C++ code accessed only via JNI may not be linked in unless -that <code>cc_library</code> target specifies <code>alwayslink = True</code>.</li> -</ul> -<p>When using any launcher other than the default JDK launcher, the format -of the <code>*_deploy.jar</code> output changes. See the main -<a href="#java_binary">java_binary</a> docs for details.</p></td> -</tr> -<tr> -<td id="java_test.main_class"><code>main_class</code></td> -<td><p>String; default is <code>""</code></p> -Name of class with <code>main()</code> method to use as entry point. -If a rule uses this option, it does not need a <code>srcs=[...]</code> list. -Thus, with this attribute one can make an executable from a Java library that already -contains one or more <code>main()</code> methods. -<p>The value of this attribute is a class name, not a source file. The class must be -available at runtime: it may be compiled by this rule (from <code>srcs</code>) or -provided by direct or transitive dependencies (through <code>runtime_deps</code> or -<code>deps</code>). If the class is unavailable, the binary will fail at runtime; there -is no build-time check.</p></td> -</tr> -<tr> -<td id="java_test.neverlink"><code>neverlink</code></td> -<td><p>Boolean; default is <code>False</code></p></td> -</tr> -<tr> -<td id="java_test.plugins"><code>plugins</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Java compiler plugins to run at compile-time. -Every <code>java_plugin</code> specified in this attribute will be run whenever this rule -is built. A library may also inherit plugins from dependencies that use -<a href="#java_library.exported_plugins"><code>exported_plugins</code></a>. Resources -generated by the plugin will be included in the resulting jar of this rule.</td> -</tr> -<tr> -<td id="java_test.resource_strip_prefix"><code>resource_strip_prefix</code></td> -<td><p>String; default is <code>""</code></p> -The path prefix to strip from Java resources. -<p>If specified, this path prefix is stripped from every file in the <code>resources</code> -attribute. It is an error for a resource file not to be under this directory. If not -specified (the default), the path of resource file is determined according to the same -logic as the Java package of source files. For example, a source file at -<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.</p></td> -</tr> -<tr> -<td id="java_test.runtime_deps"><code>runtime_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Libraries to make available to the final binary or test at runtime only. -Like ordinary <code>deps</code>, these will appear on the runtime classpath, but unlike -them, not on the compile-time classpath. Dependencies needed only at runtime should be -listed here. Dependency-analysis tools should ignore targets that appear in both -<code>runtime_deps</code> and <code>deps</code>.</td> -</tr> -<tr> -<td id="java_test.stamp"><code>stamp</code></td> -<td><p>Integer; default is <code>0</code></p> -Whether to encode build information into the binary. Possible values: -<ul> -<li><code>stamp = 1</code>: Always stamp the build information into the binary, even in -<a href="https://bazel.build/docs/user-manual#stamp"><code>--nostamp</code></a> builds. <strong>This -setting should be avoided</strong>, since it potentially kills remote caching for the -binary and any downstream actions that depend on it.</li> -<li><code>stamp = 0</code>: Always replace build information by constant values. This -gives good build result caching.</li> -<li><code>stamp = -1</code>: Embedding of build information is controlled by the -<a href="https://bazel.build/docs/user-manual#stamp"><code>--[no]stamp</code></a> flag.</li> -</ul> -<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p></td> -</tr> -<tr> -<td id="java_test.test_class"><code>test_class</code></td> -<td><p>String; default is <code>""</code></p> -The Java class to be loaded by the test runner.<br /> - <p>By default, if this argument is not defined then the legacy mode is used and the -test arguments are used instead. Set the <code>--nolegacy_bazel_java_test</code> flag -to not fallback on the first argument.</p> -<p>This attribute specifies the name of a Java class to be run by -this test. It is rare to need to set this. If this argument is omitted, -it will be inferred using the target's <code>name</code> and its -source-root-relative path. If the test is located outside a known -source root, Bazel will report an error if <code>test_class</code> -is unset.</p> -<p>For JUnit3, the test class needs to either be a subclass of -<code>junit.framework.TestCase</code> or it needs to have a public -static <code>suite()</code> method that returns a -<code>junit.framework.Test</code> (or a subclass of <code>Test</code>).</p> -<p>This attribute allows several <code>java_test</code> rules to -share the same <code>Test</code> -(<code>TestCase</code>, <code>TestSuite</code>, ...). Typically -additional information is passed to it -(e.g. via <code>jvm_flags=['-Dkey=value']</code>) so that its -behavior differs in each case, such as running a different -subset of the tests. This attribute also enables the use of -Java tests outside the <code>javatests</code> tree.</p></td> -</tr> -<tr> -<td id="java_test.use_launcher"><code>use_launcher</code></td> -<td><p>Boolean; default is <code>True</code></p> -Whether the binary should use a custom launcher. -<p>If this attribute is set to false, the -<a href="/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related -<a href="/docs/user-manual#flag--java_launcher"><code>--java_launcher</code></a> flag -will be ignored for this target.</p></td> -</tr> -<tr> -<td id="java_test.use_testrunner"><code>use_testrunner</code></td> -<td><p>Boolean; default is <code>True</code></p> -Use the test runner (by default -<code>com.google.testing.junit.runner.BazelTestRunner</code>) class as the -main entry point for a Java program, and provide the test class -to the test runner as a value of <code>bazel.test_suite</code> -system property.<br /> -You can use this to override the default -behavior, which is to use test runner for -<code>java_test</code> rules, -and not use it for <code>java_binary</code> rules. It is unlikely -you will want to do this. One use is for <code>AllTest</code> -rules that are invoked by another rule (to set up a database -before running the tests, for example). The <code>AllTest</code> -rule must be declared as a <code>java_binary</code>, but should -still use the test runner as its main entry point. -The name of a test runner class can be overridden with <code>main_class</code> attribute.</td> -</tr> -</tbody> -</table> - -## java_package_configuration - -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_package_configuration.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the target. See general comments about `deps` at [Typical attributes defined by most build rules](common-definitions.html#typical-attributes). | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. Source files of type `.java` are compiled. In case of generated `.java` files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the `outs` of the generating rule. You should not list the generating rule in `deps` because it is a no-op. Source files of type `.srcjar` are unpacked and compiled. (This is useful if you need to generate a set of `.java` files with a genrule.) Rules: if the rule (typically `genrule` or `filegroup`) generates any of the files listed above, they will be used the same way as described for source files. This argument is almost always required, except if a [`main_class`](#java_binary.main_class) attribute specifies a class on the runtime classpath or you specify the `runtime_deps` argument. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). | +| `resources` | List of [labels](./concepts/labels); default is `[]` A list of data files to include in a Java jar. Resources may be source files or generated files. If resources are specified, they will be bundled in the jar along with the usual `.class` files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's [standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.mdx), (a "src" directory followed by a "resources" directory grandchild). If that is not found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for example, if a resource is at `\<workspace root\>/x/java/y/java/z`, the path of the resource will be `y/java/z`. This heuristic cannot be overridden, however, the `resource_strip_prefix` attribute can be used to specify a specific alternative directory for resource files. | +| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | +| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | +| `bootclasspath` | [Label](./concepts/labels); default is `None` Restricted API, do not use! | +| `classpath_resources` | List of [labels](./concepts/labels); default is `[]` *DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)* A list of resources that must be located at the root of the java tree. This attribute's only purpose is to support third-party libraries that require that their resources be found on the classpath as exactly `"myconfig.xml"`. It is only allowed on binaries and not libraries, due to the danger of namespace conflicts. | +| `create_executable` | Boolean; default is `True` Deprecated, use `java_single_jar` instead. | +| `deploy_manifest_lines` | List of strings; default is `[]` A list of lines to add to the `META-INF/manifest.mf` file generated for the `*_deploy.jar` target. The contents of this attribute are *not* subject to ["Make variable"](make-variables.mdx) substitution. | +| `javacopts` | List of strings; default is `[]` Extra compiler options for this binary. Subject to ["Make variable"](make-variables.mdx) substitution and [Bourne shell tokenization](common-definitions.html#sh-tokenization). These compiler options are passed to javac after the global compiler options. | +| `jvm_flags` | List of strings; default is `[]` A list of flags to embed in the wrapper script generated for running this binary. Subject to [$(location)](./reference/be/make-variables#location) and ["Make variable"](make-variables.mdx) substitution, and [Bourne shell tokenization](common-definitions.html#sh-tokenization). The wrapper script for a Java binary includes a CLASSPATH definition (to find all the dependent jars) and invokes the right Java interpreter. The command line generated by the wrapper script includes the name of the main class followed by a `"$@"` so you can pass along other arguments after the classname. However, arguments intended for parsing by the JVM must be specified *before* the classname on the command line. The contents of `jvm_flags` are added to the wrapper script before the classname is listed. Note that this attribute has *no effect* on `*_deploy.jar` outputs. | +| `launcher` | [Label](./concepts/labels); default is `None` Specify a binary that will be used to run your Java program instead of the normal `bin/java` program included with the JDK. The target must be a `cc_binary`. Any `cc_binary` that implements the [Java Invocation API](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.mdx) can be specified as a value for this attribute. By default, Bazel will use the normal JDK launcher (bin/java or java.exe). The related [`--java_launcher`](./docs/user-manual#flag--java_launcher) Bazel flag affects only those `java_binary` and `java_test` targets that have *not* specified a `launcher` attribute. Note that your native (C++, SWIG, JNI) dependencies will be built differently depending on whether you are using the JDK launcher or another launcher: * If you are using the normal JDK launcher (the default), native dependencies are built as a shared library named `\{name\}_nativedeps.so`, where `\{name\}` is the `name` attribute of this java\_binary rule. Unused code is *not* removed by the linker in this configuration. * If you are using any other launcher, native (C++) dependencies are statically linked into a binary named `\{name\}_nativedeps`, where `\{name\}` is the `name` attribute of this java\_binary rule. In this case, the linker will remove any code it thinks is unused from the resulting binary, which means any C++ code accessed only via JNI may not be linked in unless that `cc_library` target specifies `alwayslink = True`. When using any launcher other than the default JDK launcher, the format of the `*_deploy.jar` output changes. See the main [java\_binary](#java_binary) docs for details. | +| `main_class` | String; default is `""` Name of class with `main()` method to use as entry point. If a rule uses this option, it does not need a `srcs=[...]` list. Thus, with this attribute one can make an executable from a Java library that already contains one or more `main()` methods. The value of this attribute is a class name, not a source file. The class must be available at runtime: it may be compiled by this rule (from `srcs`) or provided by direct or transitive dependencies (through `runtime_deps` or `deps`). If the class is unavailable, the binary will fail at runtime; there is no build-time check. | +| `neverlink` | Boolean; default is `False` | +| `plugins` | List of [labels](./concepts/labels); default is `[]` Java compiler plugins to run at compile-time. Every `java_plugin` specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use `exported_plugins`. Resources generated by the plugin will be included in the resulting jar of this rule. | +| `resource_strip_prefix` | String; default is `""` The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at `stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. | +| `runtime_deps` | List of [labels](./concepts/labels); default is `[]` Libraries to make available to the final binary or test at runtime only. Like ordinary `deps`, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both `runtime_deps` and `deps`. | +| `stamp` | Integer; default is `0` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](https://bazel.build/docs/user-manual#stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](https://bazel.build/docs/user-manual#stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | +| `test_class` | String; default is `""` The Java class to be loaded by the test runner. By default, if this argument is not defined then the legacy mode is used and the test arguments are used instead. Set the `--nolegacy_bazel_java_test` flag to not fallback on the first argument. This attribute specifies the name of a Java class to be run by this test. It is rare to need to set this. If this argument is omitted, it will be inferred using the target's `name` and its source-root-relative path. If the test is located outside a known source root, Bazel will report an error if `test_class` is unset. For JUnit3, the test class needs to either be a subclass of `junit.framework.TestCase` or it needs to have a public static `suite()` method that returns a `junit.framework.Test` (or a subclass of `Test`). This attribute allows several `java_test` rules to share the same `Test` (`TestCase`, `TestSuite`, ...). Typically additional information is passed to it (e.g. via `jvm_flags=['-Dkey=value']`) so that its behavior differs in each case, such as running a different subset of the tests. This attribute also enables the use of Java tests outside the `javatests` tree. | +| `use_launcher` | Boolean; default is `True` Whether the binary should use a custom launcher. If this attribute is set to false, the [launcher](./reference/be/java.html#java_binary.launcher) attribute and the related [`--java_launcher`](./docs/user-manual#flag--java_launcher) flag will be ignored for this target. | +| `use_testrunner` | Boolean; default is `True` Use the test runner (by default `com.google.testing.junit.runner.BazelTestRunner`) class as the main entry point for a Java program, and provide the test class to the test runner as a value of `bazel.test_suite` system property. You can use this to override the default behavior, which is to use test runner for `java_test` rules, and not use it for `java_binary` rules. It is unlikely you will want to do this. One use is for `AllTest` rules that are invoked by another rule (to set up a database before running the tests, for example). The `AllTest` rule must be declared as a `java_binary`, but should still use the test runner as its main entry point. The name of a test runner class can be overridden with `main_class` attribute. | + +## java\_package\_configuration + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_package_configuration.bzl) + +``` java_package_configuration(name, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, javacopts, output_licenses, package_metadata, packages, restricted_to, system, tags, target_compatible_with, testonly, toolchains, visibility) ``` Configuration to apply to a set of packages. Configurations can be added to -[`java_toolchain.javacopts`](/reference/be/java.html#java_toolchain.javacopts)s. +`java_toolchain.javacopts`s. #### Example: -``` code - - - +``` java_package_configuration( name = "my_configuration", packages = [":my_packages"], @@ -1069,56 +315,24 @@ java_toolchain( ":my_configuration", ] ) - ``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_package_configuration.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_package_configuration.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this configuration at runtime.</td> -</tr> -<tr> -<td id="java_package_configuration.javacopts"><code>javacopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Java compiler flags.</td> -</tr> -<tr> -<td id="java_package_configuration.output_licenses"><code>output_licenses</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="java_package_configuration.packages"><code>packages</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The set of <a href="/reference/be/functions.html#package_group"><code>package_group</code></a>s -the configuration should be applied to.</td> -</tr> -<tr> -<td id="java_package_configuration.system"><code>system</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Corresponds to javac's --system flag.</td> -</tr> -</tbody> -</table> - -## java_plugin - -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_plugin.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this configuration at runtime. | +| `javacopts` | List of strings; default is `[]` Java compiler flags. | +| `output_licenses` | List of strings; default is `[]` | +| `packages` | List of [labels](./concepts/labels); default is `[]` The set of `package_group`s the configuration should be applied to. | +| `system` | [Label](./concepts/labels); default is `None` Corresponds to javac's --system flag. | + +## java\_plugin + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_plugin.bzl) + +``` java_plugin(name, deps, srcs, data, resources, add_exports, add_opens, aspect_hints, bootclasspath, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, generates_api, javabuilder_jvm_flags, javacopts, licenses, neverlink, output_licenses, package_metadata, plugins, processor_class, proguard_specs, resource_strip_prefix, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` @@ -1127,207 +341,44 @@ only supported kind of plugins are annotation processors. A `java_library` or `java_binary` rule can run plugins by depending on them via the `plugins` attribute. A `java_library` can also automatically export plugins to libraries that directly depend on it using -[`exported_plugins`](#java_library-exported_plugins). +`exported_plugins`. #### Implicit output targets -- `libname``.jar`: A Java archive. +* `libname.jar`: A Java archive. Arguments are a subset of (and with identical semantics to) those of -[java_library()](/reference/be/java.html#java_library), +[java\_library()](./reference/be/java.html#java_library), except for the addition of the `processor_class` and `generates_api` arguments. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_plugin.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_plugin.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of libraries to link into this library. -See general comments about <code>deps</code> at -<a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. -<p>The jars built by <code>java_library</code> rules listed in <code>deps</code> will be on -the compile-time classpath of this rule. Furthermore the transitive closure of their -<code>deps</code>, <code>runtime_deps</code> and <code>exports</code> will be on the -runtime classpath.</p> -<p>By contrast, targets in the <code>data</code> attribute are included in the runfiles but -on neither the compile-time nor runtime classpath.</p></td> -</tr> -<tr> -<td id="java_plugin.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of source files that are processed to create the target. -This attribute is almost always required; see exceptions below. -<p>Source files of type <code>.java</code> are compiled. In case of generated -<code>.java</code> files it is generally advisable to put the generating rule's name -here instead of the name of the file itself. This not only improves readability but -makes the rule more resilient to future changes: if the generating rule generates -different files in the future, you only need to fix one place: the <code>outs</code> of -the generating rule. You should not list the generating rule in <code>deps</code> -because it is a no-op.</p> -<p>Source files of type <code>.srcjar</code> are unpacked and compiled. (This is useful if -you need to generate a set of <code>.java</code> files with a genrule.)</p> -<p>Rules: if the rule (typically <code>genrule</code> or <code>filegroup</code>) generates -any of the files listed above, they will be used the same way as described for source -files.</p> -<p>Source files of type <code>.properties</code> are treated as resources.</p> -<p>All other files are ignored, as long as there is at least one file of a -file type described above. Otherwise an error is raised.</p> -<p>This argument is almost always required, except if you specify the <code>runtime_deps</code> argument.</p></td> -</tr> -<tr> -<td id="java_plugin.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files needed by this library at runtime. -See general comments about <code>data</code> at -<a href="/reference/be/common-definitions#typical-attributes">Typical attributes defined by -most build rules</a>. -<p>When building a <code>java_library</code>, Bazel doesn't put these files anywhere; if the -<code>data</code> files are generated files then Bazel generates them. When building a -test that depends on this <code>java_library</code> Bazel copies or links the -<code>data</code> files into the runfiles area.</p></td> -</tr> -<tr> -<td id="java_plugin.resources"><code>resources</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of data files to include in a Java jar. -<p>Resources may be source files or generated files.</p> -<p>If resources are specified, they will be bundled in the jar along with the usual -<code>.class</code> files produced by compilation. The location of the resources inside -of the jar file is determined by the project structure. Bazel first looks for Maven's -<a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">standard directory layout</a>, -(a "src" directory followed by a "resources" directory grandchild). If that is not -found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for -example, if a resource is at <code><workspace root>/x/java/y/java/z</code>, the -path of the resource will be <code>y/java/z</code>. This heuristic cannot be overridden, -however, the <code>resource_strip_prefix</code> attribute can be used to specify a -specific alternative directory for resource files.</p></td> -</tr> -<tr> -<td id="java_plugin.add_exports"><code>add_exports</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to access the given <code>module</code> or <code>package</code>. -<p>This corresponds to the javac and JVM --add-exports= flags.</p></td> -</tr> -<tr> -<td id="java_plugin.add_opens"><code>add_opens</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Allow this library to reflectively access the given <code>module</code> or -<code>package</code>. -<p>This corresponds to the javac and JVM --add-opens= flags.</p></td> -</tr> -<tr> -<td id="java_plugin.bootclasspath"><code>bootclasspath</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Restricted API, do not use!</td> -</tr> -<tr> -<td id="java_plugin.generates_api"><code>generates_api</code></td> -<td><p>Boolean; default is <code>False</code></p> -This attribute marks annotation processors that generate API code. -<p>If a rule uses an API-generating annotation processor, other rules -depending on it can refer to the generated code only if their -compilation actions are scheduled after the generating rule. This -attribute instructs Bazel to introduce scheduling constraints when ---java_header_compilation is enabled.</p> -<p><em>WARNING: This attribute affects build -performance, use it only if necessary.</em></p></td> -</tr> -<tr> -<td id="java_plugin.javabuilder_jvm_flags"><code>javabuilder_jvm_flags</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Restricted API, do not use!</td> -</tr> -<tr> -<td id="java_plugin.javacopts"><code>javacopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra compiler options for this library. -Subject to <a href="make-variables.html">"Make variable"</a> substitution and -<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>. -<p>These compiler options are passed to javac after the global compiler options.</p></td> -</tr> -<tr> -<td id="java_plugin.neverlink"><code>neverlink</code></td> -<td><p>Boolean; default is <code>False</code></p> -Whether this library should only be used for compilation and not at runtime. -Useful if the library will be provided by the runtime environment during execution. Examples -of such libraries are the IDE APIs for IDE plug-ins or <code>tools.jar</code> for anything -running on a standard JDK. -<p>Note that <code>neverlink = True</code> does not prevent the compiler from inlining material -from this library into compilation targets that depend on it, as permitted by the Java -Language Specification (e.g., <code>static final</code> constants of <code>String</code> -or of primitive types). The preferred use case is therefore when the runtime library is -identical to the compilation library.</p> -<p>If the runtime library differs from the compilation library then you must ensure that it -differs only in places that the JLS forbids compilers to inline (and that must hold for -all future versions of the JLS).</p></td> -</tr> -<tr> -<td id="java_plugin.output_licenses"><code>output_licenses</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="java_plugin.plugins"><code>plugins</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Java compiler plugins to run at compile-time. -Every <code>java_plugin</code> specified in this attribute will be run whenever this rule -is built. A library may also inherit plugins from dependencies that use -<a href="#java_library.exported_plugins"><code>exported_plugins</code></a>. Resources -generated by the plugin will be included in the resulting jar of this rule.</td> -</tr> -<tr> -<td id="java_plugin.processor_class"><code>processor_class</code></td> -<td><p>String; default is <code>""</code></p> -The processor class is the fully qualified type of the class that the Java compiler should -use as entry point to the annotation processor. If not specified, this rule will not -contribute an annotation processor to the Java compiler's annotation processing, but its -runtime classpath will still be included on the compiler's annotation processor path. (This -is primarily intended for use by -<a href="https://errorprone.info/docs/plugins">Error Prone plugins</a>, which are loaded -from the annotation processor path using -<a href="https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html">java.util.ServiceLoader</a>.)</td> -</tr> -<tr> -<td id="java_plugin.proguard_specs"><code>proguard_specs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Files to be used as Proguard specification. -These will describe the set of specifications to be used by Proguard. If specified, -they will be added to any <code>android_binary</code> target depending on this library. -The files included here must only have idempotent rules, namely -dontnote, -dontwarn, -assumenosideeffects, and rules that start with -keep. Other options can only appear in -<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges.</td> -</tr> -<tr> -<td id="java_plugin.resource_strip_prefix"><code>resource_strip_prefix</code></td> -<td><p>String; default is <code>""</code></p> -The path prefix to strip from Java resources. -<p>If specified, this path prefix is stripped from every file in the <code>resources</code> -attribute. It is an error for a resource file not to be under this directory. If not -specified (the default), the path of resource file is determined according to the same -logic as the Java package of source files. For example, a source file at -<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.</p></td> -</tr> -</tbody> -</table> - -## java_runtime - -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_runtime.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of libraries to link into this library. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). The jars built by `java_library` rules listed in `deps` will be on the compile-time classpath of this rule. Furthermore the transitive closure of their `deps`, `runtime_deps` and `exports` will be on the runtime classpath. By contrast, targets in the `data` attribute are included in the runfiles but on neither the compile-time nor runtime classpath. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. Source files of type `.java` are compiled. In case of generated `.java` files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the `outs` of the generating rule. You should not list the generating rule in `deps` because it is a no-op. Source files of type `.srcjar` are unpacked and compiled. (This is useful if you need to generate a set of `.java` files with a genrule.) Rules: if the rule (typically `genrule` or `filegroup`) generates any of the files listed above, they will be used the same way as described for source files. Source files of type `.properties` are treated as resources. All other files are ignored, as long as there is at least one file of a file type described above. Otherwise an error is raised. This argument is almost always required, except if you specify the `runtime_deps` argument. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). When building a `java_library`, Bazel doesn't put these files anywhere; if the `data` files are generated files then Bazel generates them. When building a test that depends on this `java_library` Bazel copies or links the `data` files into the runfiles area. | +| `resources` | List of [labels](./concepts/labels); default is `[]` A list of data files to include in a Java jar. Resources may be source files or generated files. If resources are specified, they will be bundled in the jar along with the usual `.class` files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's [standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.mdx), (a "src" directory followed by a "resources" directory grandchild). If that is not found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for example, if a resource is at `\<workspace root\>/x/java/y/java/z`, the path of the resource will be `y/java/z`. This heuristic cannot be overridden, however, the `resource_strip_prefix` attribute can be used to specify a specific alternative directory for resource files. | +| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | +| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | +| `bootclasspath` | [Label](./concepts/labels); default is `None` Restricted API, do not use! | +| `generates_api` | Boolean; default is `False` This attribute marks annotation processors that generate API code. If a rule uses an API-generating annotation processor, other rules depending on it can refer to the generated code only if their compilation actions are scheduled after the generating rule. This attribute instructs Bazel to introduce scheduling constraints when --java\_header\_compilation is enabled. *WARNING: This attribute affects build performance, use it only if necessary.* | +| `javabuilder_jvm_flags` | List of strings; default is `[]` Restricted API, do not use! | +| `javacopts` | List of strings; default is `[]` Extra compiler options for this library. Subject to ["Make variable"](make-variables.mdx) substitution and [Bourne shell tokenization](common-definitions.html#sh-tokenization). These compiler options are passed to javac after the global compiler options. | +| `neverlink` | Boolean; default is `False` Whether this library should only be used for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of such libraries are the IDE APIs for IDE plug-ins or `tools.jar` for anything running on a standard JDK. Note that `neverlink = True` does not prevent the compiler from inlining material from this library into compilation targets that depend on it, as permitted by the Java Language Specification (e.g., `static final` constants of `String` or of primitive types). The preferred use case is therefore when the runtime library is identical to the compilation library. If the runtime library differs from the compilation library then you must ensure that it differs only in places that the JLS forbids compilers to inline (and that must hold for all future versions of the JLS). | +| `output_licenses` | List of strings; default is `[]` | +| `plugins` | List of [labels](./concepts/labels); default is `[]` Java compiler plugins to run at compile-time. Every `java_plugin` specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use `exported_plugins`. Resources generated by the plugin will be included in the resulting jar of this rule. | +| `processor_class` | String; default is `""` The processor class is the fully qualified type of the class that the Java compiler should use as entry point to the annotation processor. If not specified, this rule will not contribute an annotation processor to the Java compiler's annotation processing, but its runtime classpath will still be included on the compiler's annotation processor path. (This is primarily intended for use by [Error Prone plugins](https://errorprone.info/docs/plugins), which are loaded from the annotation processor path using [java.util.ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.mdx).) | +| `proguard_specs` | List of [labels](./concepts/labels); default is `[]` Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any `android_binary` target depending on this library. The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in `android_binary`'s proguard\_specs, to ensure non-tautological merges. | +| `resource_strip_prefix` | String; default is `""` The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at `stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. | + +## java\_runtime + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_runtime.bzl) + +``` java_runtime(name, srcs, aspect_hints, compatible_with, default_cds, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hermetic_srcs, hermetic_static_libs, java, java_home, lib_ct_sym, lib_modules, output_licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, version, visibility) ``` @@ -1335,195 +386,85 @@ Specifies the configuration for a Java runtime. #### Example: -``` code - - - +``` java_runtime( name = "jdk-9-ea+153", srcs = glob(["jdk9-ea+153/**"]), java_home = "jdk9-ea+153", ) - ``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_runtime.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_runtime.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -All files in the runtime.</td> -</tr> -<tr> -<td id="java_runtime.default_cds"><code>default_cds</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Default CDS archive for hermetic <code>java_runtime</code>. When hermetic -is enabled for a <code>java_binary</code> target the <code>java_runtime</code> -default CDS is packaged in the hermetic deploy JAR.</td> -</tr> -<tr> -<td id="java_runtime.hermetic_srcs"><code>hermetic_srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Files in the runtime needed for hermetic deployments.</td> -</tr> -<tr> -<td id="java_runtime.hermetic_static_libs"><code>hermetic_static_libs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The libraries that are statically linked with the launcher for hermetic deployments</td> -</tr> -<tr> -<td id="java_runtime.java"><code>java</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -The path to the java executable.</td> -</tr> -<tr> -<td id="java_runtime.java_home"><code>java_home</code></td> -<td><p>String; default is <code>""</code></p> -The path to the root of the runtime. -Subject to <a href="/reference/be/make-variables">"Make" variable</a> substitution. -If this path is absolute, the rule denotes a non-hermetic Java runtime with a well-known -path. In that case, the <code>srcs</code> and <code>java</code> attributes must be empty.</td> -</tr> -<tr> -<td id="java_runtime.lib_ct_sym"><code>lib_ct_sym</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -The lib/ct.sym file needed for compilation with <code>--release</code>. If not specified and -there is exactly one file in <code>srcs</code> whose path ends with -<code>/lib/ct.sym</code>, that file is used.</td> -</tr> -<tr> -<td id="java_runtime.lib_modules"><code>lib_modules</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -The lib/modules file needed for hermetic deployments.</td> -</tr> -<tr> -<td id="java_runtime.output_licenses"><code>output_licenses</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="java_runtime.version"><code>version</code></td> -<td><p>Integer; default is <code>0</code></p> -The feature version of the Java runtime. I.e., the integer returned by -<code>Runtime.version().feature()</code>.</td> -</tr> -</tbody> -</table> - -## java_single_jar - -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/java_single_jar.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` All files in the runtime. | +| `default_cds` | [Label](./concepts/labels); default is `None` Default CDS archive for hermetic `java_runtime`. When hermetic is enabled for a `java_binary` target the `java_runtime` default CDS is packaged in the hermetic deploy JAR. | +| `hermetic_srcs` | List of [labels](./concepts/labels); default is `[]` Files in the runtime needed for hermetic deployments. | +| `hermetic_static_libs` | List of [labels](./concepts/labels); default is `[]` The libraries that are statically linked with the launcher for hermetic deployments | +| `java` | [Label](./concepts/labels); default is `None` The path to the java executable. | +| `java_home` | String; default is `""` The path to the root of the runtime. Subject to ["Make" variable](./reference/be/make-variables) substitution. If this path is absolute, the rule denotes a non-hermetic Java runtime with a well-known path. In that case, the `srcs` and `java` attributes must be empty. | +| `lib_ct_sym` | [Label](./concepts/labels); default is `None` The lib/ct.sym file needed for compilation with `--release`. If not specified and there is exactly one file in `srcs` whose path ends with `/lib/ct.sym`, that file is used. | +| `lib_modules` | [Label](./concepts/labels); default is `None` The lib/modules file needed for hermetic deployments. | +| `output_licenses` | List of strings; default is `[]` | +| `version` | Integer; default is `0` The feature version of the Java runtime. I.e., the integer returned by `Runtime.version().feature()`. | + +## java\_single\_jar + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/java_single_jar.bzl) + +``` java_single_jar(name, deps, aspect_hints, compatible_with, compress, deploy_env, deploy_manifest_lines, deprecation, exclude_build_data, exec_compatible_with, exec_group_compatible_with, exec_properties, features, multi_release, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` Collects Java dependencies and jar files into a single jar -\`java_single_jar\` collects Java dependencies and jar files into a single jar. -This is similar to java_binary with everything related to executables disabled, -and provides an alternative to the java_binary "deploy jar hack". -\## Example -\`\`\`skylark -load("//tools/build_defs/java_single_jar:java_single_jar.bzl", "java_single_jar") -java_single_jar( -name = "my_single_jar", -deps = \[ +`java\_single\_jar` collects Java dependencies and jar files into a single jar. +This is similar to java\_binary with everything related to executables disabled, +and provides an alternative to the java\_binary "deploy jar hack". +## Example +```skylark +load("//tools/build\_defs/java\_single\_jar:java\_single\_jar.bzl", "java\_single\_jar") +java\_single\_jar( +name = "my\_single\_jar", +deps = [ "//java/com/google/foo", "//java/com/google/bar", -\], +], ) -\`\`\` +``` Outputs: -{name}.jar: A single jar containing all of the inputs. +\{name\}.jar: A single jar containing all of the inputs. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_single_jar.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_single_jar.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The Java targets (including java_import and java_library) to collect -transitive dependencies from. Runtime dependencies are collected via -deps, exports, and runtime_deps. Resources are also collected. -Native cc_library or java_wrap_cc dependencies are not.</td> -</tr> -<tr> -<td id="java_single_jar.compress"><code>compress</code></td> -<td><p>String; default is <code>"preserve"</code></p> -Whether to always deflate ("yes"), always store ("no"), or pass -through unmodified ("preserve"). The default is "preserve", and is the -most efficient option -- no extra work is done to inflate or deflate.</td> -</tr> -<tr> -<td id="java_single_jar.deploy_env"><code>deploy_env</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -A list of `java_binary` or `java_single_jar` targets which represent -the deployment environment for this binary. -Set this attribute when building a plugin which will be loaded by another -`java_binary`. -`deploy_env` dependencies are excluded from the jar built by this rule.</td> -</tr> -<tr> -<td id="java_single_jar.deploy_manifest_lines"><code>deploy_manifest_lines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -A list of lines to add to the <code>META-INF/manifest.mf</code> file.</td> -</tr> -<tr> -<td id="java_single_jar.exclude_build_data"><code>exclude_build_data</code></td> -<td><p>Boolean; default is <code>True</code></p> -Whether to omit the build-data.properties file generated -by default.</td> -</tr> -<tr> -<td id="java_single_jar.multi_release"><code>multi_release</code></td> -<td><p>Boolean; default is <code>True</code></p> -Whether to enable Multi-Release output jars.</td> -</tr> -</tbody> -</table> - -## java_toolchain - -<a href="https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_toolchain.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The Java targets (including java\_import and java\_library) to collect transitive dependencies from. Runtime dependencies are collected via deps, exports, and runtime\_deps. Resources are also collected. Native cc\_library or java\_wrap\_cc dependencies are not. | +| `compress` | String; default is `"preserve"` Whether to always deflate ("yes"), always store ("no"), or pass through unmodified ("preserve"). The default is "preserve", and is the most efficient option -- no extra work is done to inflate or deflate. | +| `deploy_env` | List of [labels](./concepts/labels); default is `[]` A list of `java\_binary` or `java\_single\_jar` targets which represent the deployment environment for this binary. Set this attribute when building a plugin which will be loaded by another `java\_binary`. `deploy\_env` dependencies are excluded from the jar built by this rule. | +| `deploy_manifest_lines` | List of strings; default is `[]` A list of lines to add to the `META-INF/manifest.mf` file. | +| `exclude_build_data` | Boolean; default is `True` Whether to omit the build-data.properties file generated by default. | +| `multi_release` | Boolean; default is `True` Whether to enable Multi-Release output jars. | + +## java\_toolchain + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_toolchain.bzl) + +``` java_toolchain(name, android_lint_data, android_lint_jvm_opts, android_lint_opts, android_lint_package_configuration, android_lint_runner, aspect_hints, bootclasspath, compatible_javacopts, compatible_with, deprecation, deps_checker, exec_compatible_with, exec_group_compatible_with, exec_properties, features, forcibly_disable_header_compilation, genclass, header_compiler, header_compiler_builtin_processors, header_compiler_direct, ijar, jacocorunner, java_runtime, javabuilder, javabuilder_data, javabuilder_jvm_opts, javac_supports_multiplex_workers, javac_supports_worker_cancellation, javac_supports_worker_multiplex_sandboxing, javac_supports_workers, javacopts, jspecify_implicit_deps, jspecify_javacopts, jspecify_packages, jspecify_processor, jspecify_processor_class, jspecify_stubs, jvm_opts, licenses, misc, oneversion, oneversion_allowlist, oneversion_allowlist_for_tests, oneversion_whitelist, package_configuration, package_metadata, proguard_allowlister, reduced_classpath_incompatible_processors, restricted_to, singlejar, source_version, tags, target_compatible_with, target_version, testonly, timezone_data, toolchains, tools, turbine_data, turbine_jvm_opts, visibility, xlint) ``` Specifies the configuration for the Java compiler. Which toolchain to be used can be changed through -the --java_toolchain argument. Normally you should not write those kind of rules unless you want to +the --java\_toolchain argument. Normally you should not write those kind of rules unless you want to tune your Java compiler. #### Examples A simple example would be: -``` code - - - +``` java_toolchain( name = "toolchain", source_version = "7", @@ -1537,262 +478,53 @@ java_toolchain( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_toolchain.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_toolchain.android_lint_data"><code>android_lint_data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Labels of tools available for label-expansion in android_lint_jvm_opts.</td> -</tr> -<tr> -<td id="java_toolchain.android_lint_jvm_opts"><code>android_lint_jvm_opts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -The list of arguments for the JVM when invoking Android Lint.</td> -</tr> -<tr> -<td id="java_toolchain.android_lint_opts"><code>android_lint_opts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -The list of Android Lint arguments.</td> -</tr> -<tr> -<td id="java_toolchain.android_lint_package_configuration"><code>android_lint_package_configuration</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Android Lint Configuration that should be applied to the specified package groups.</td> -</tr> -<tr> -<td id="java_toolchain.android_lint_runner"><code>android_lint_runner</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the Android Lint runner, if any.</td> -</tr> -<tr> -<td id="java_toolchain.bootclasspath"><code>bootclasspath</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag.</td> -</tr> -<tr> -<td id="java_toolchain.compatible_javacopts"><code>compatible_javacopts</code></td> -<td><p>null; default is <code>{}</code></p> -Internal API, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.deps_checker"><code>deps_checker</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the ImportDepsChecker deploy jar.</td> -</tr> -<tr> -<td id="java_toolchain.forcibly_disable_header_compilation"><code>forcibly_disable_header_compilation</code></td> -<td><p>Boolean; default is <code>False</code></p> -Overrides --java_header_compilation to disable header compilation on platforms that do not -support it, e.g. JDK 7 Bazel.</td> -</tr> -<tr> -<td id="java_toolchain.genclass"><code>genclass</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the GenClass deploy jar.</td> -</tr> -<tr> -<td id="java_toolchain.header_compiler"><code>header_compiler</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the header compiler. Required if --java_header_compilation is enabled.</td> -</tr> -<tr> -<td id="java_toolchain.header_compiler_builtin_processors"><code>header_compiler_builtin_processors</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Internal API, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.header_compiler_direct"><code>header_compiler_direct</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Optional label of the header compiler to use for direct classpath actions that do not -include any API-generating annotation processors. -<p>This tool does not support annotation processing.</p></td> -</tr> -<tr> -<td id="java_toolchain.ijar"><code>ijar</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the ijar executable.</td> -</tr> -<tr> -<td id="java_toolchain.jacocorunner"><code>jacocorunner</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the JacocoCoverageRunner deploy jar.</td> -</tr> -<tr> -<td id="java_toolchain.java_runtime"><code>java_runtime</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -The java_runtime to use with this toolchain. It defaults to java_runtime -in execution configuration.</td> -</tr> -<tr> -<td id="java_toolchain.javabuilder"><code>javabuilder</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the JavaBuilder deploy jar.</td> -</tr> -<tr> -<td id="java_toolchain.javabuilder_data"><code>javabuilder_data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Labels of data available for label-expansion in javabuilder_jvm_opts.</td> -</tr> -<tr> -<td id="java_toolchain.javabuilder_jvm_opts"><code>javabuilder_jvm_opts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -The list of arguments for the JVM when invoking JavaBuilder.</td> -</tr> -<tr> -<td id="java_toolchain.javac_supports_multiplex_workers"><code>javac_supports_multiplex_workers</code></td> -<td><p>Boolean; default is <code>True</code></p> -True if JavaBuilder supports running as a multiplex persistent worker, false if it doesn't.</td> -</tr> -<tr> -<td id="java_toolchain.javac_supports_worker_cancellation"><code>javac_supports_worker_cancellation</code></td> -<td><p>Boolean; default is <code>True</code></p> -True if JavaBuilder supports cancellation of persistent workers, false if it doesn't.</td> -</tr> -<tr> -<td id="java_toolchain.javac_supports_worker_multiplex_sandboxing"><code>javac_supports_worker_multiplex_sandboxing</code></td> -<td><p>Boolean; default is <code>False</code></p> -True if JavaBuilder supports running as a multiplex persistent worker with sandboxing, false if it doesn't.</td> -</tr> -<tr> -<td id="java_toolchain.javac_supports_workers"><code>javac_supports_workers</code></td> -<td><p>Boolean; default is <code>True</code></p> -True if JavaBuilder supports running as a persistent worker, false if it doesn't.</td> -</tr> -<tr> -<td id="java_toolchain.javacopts"><code>javacopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -The list of extra arguments for the Java compiler. Please refer to the Java compiler -documentation for the extensive list of possible Java compiler flags.</td> -</tr> -<tr> -<td id="java_toolchain.jspecify_implicit_deps"><code>jspecify_implicit_deps</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Experimental, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.jspecify_javacopts"><code>jspecify_javacopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Experimental, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.jspecify_packages"><code>jspecify_packages</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Experimental, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.jspecify_processor"><code>jspecify_processor</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Experimental, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.jspecify_processor_class"><code>jspecify_processor_class</code></td> -<td><p>String; default is <code>""</code></p> -Experimental, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.jspecify_stubs"><code>jspecify_stubs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Experimental, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.jvm_opts"><code>jvm_opts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -The list of arguments for the JVM when invoking the Java compiler. Please refer to the Java -virtual machine documentation for the extensive list of possible flags for this option.</td> -</tr> -<tr> -<td id="java_toolchain.misc" class="deprecated"><code>misc</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Deprecated: use javacopts instead</td> -</tr> -<tr> -<td id="java_toolchain.oneversion"><code>oneversion</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the one-version enforcement binary.</td> -</tr> -<tr> -<td id="java_toolchain.oneversion_allowlist"><code>oneversion_allowlist</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the one-version allowlist.</td> -</tr> -<tr> -<td id="java_toolchain.oneversion_allowlist_for_tests"><code>oneversion_allowlist_for_tests</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the one-version allowlist for tests.</td> -</tr> -<tr> -<td id="java_toolchain.oneversion_whitelist" class="deprecated"><code>oneversion_whitelist</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Deprecated: use oneversion_allowlist instead</td> -</tr> -<tr> -<td id="java_toolchain.package_configuration"><code>package_configuration</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Configuration that should be applied to the specified package groups.</td> -</tr> -<tr> -<td id="java_toolchain.proguard_allowlister"><code>proguard_allowlister</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/jdk:proguard_whitelister"</code></p> -Label of the Proguard allowlister.</td> -</tr> -<tr> -<td id="java_toolchain.reduced_classpath_incompatible_processors"><code>reduced_classpath_incompatible_processors</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Internal API, do not use!</td> -</tr> -<tr> -<td id="java_toolchain.singlejar"><code>singlejar</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of the SingleJar deploy jar.</td> -</tr> -<tr> -<td id="java_toolchain.source_version"><code>source_version</code></td> -<td><p>String; default is <code>""</code></p> -The Java source version (e.g., '6' or '7'). It specifies which set of code structures -are allowed in the Java source code.</td> -</tr> -<tr> -<td id="java_toolchain.target_version"><code>target_version</code></td> -<td><p>String; default is <code>""</code></p> -The Java target version (e.g., '6' or '7'). It specifies for which Java runtime the class -should be build.</td> -</tr> -<tr> -<td id="java_toolchain.timezone_data"><code>timezone_data</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Label of a resource jar containing timezone data. If set, the timezone data is added as an -implicitly runtime dependency of all java_binary rules.</td> -</tr> -<tr> -<td id="java_toolchain.tools"><code>tools</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Labels of tools available for label-expansion in jvm_opts.</td> -</tr> -<tr> -<td id="java_toolchain.turbine_data"><code>turbine_data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Labels of data available for label-expansion in turbine_jvm_opts.</td> -</tr> -<tr> -<td id="java_toolchain.turbine_jvm_opts"><code>turbine_jvm_opts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -The list of arguments for the JVM when invoking turbine.</td> -</tr> -<tr> -<td id="java_toolchain.xlint"><code>xlint</code></td> -<td><p>List of strings; default is <code>[]</code></p> -The list of warning to add or removes from default list. Precedes it with a dash to -removes it. Please see the Javac documentation on the -Xlint options for more information.</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `android_lint_data` | List of [labels](./concepts/labels); default is `[]` Labels of tools available for label-expansion in android\_lint\_jvm\_opts. | +| `android_lint_jvm_opts` | List of strings; default is `[]` The list of arguments for the JVM when invoking Android Lint. | +| `android_lint_opts` | List of strings; default is `[]` The list of Android Lint arguments. | +| `android_lint_package_configuration` | List of [labels](./concepts/labels); default is `[]` Android Lint Configuration that should be applied to the specified package groups. | +| `android_lint_runner` | [Label](./concepts/labels); default is `None` Label of the Android Lint runner, if any. | +| `bootclasspath` | List of [labels](./concepts/labels); default is `[]` The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. | +| `compatible_javacopts` | null; default is `\{\}` Internal API, do not use! | +| `deps_checker` | [Label](./concepts/labels); default is `None` Label of the ImportDepsChecker deploy jar. | +| `forcibly_disable_header_compilation` | Boolean; default is `False` Overrides --java\_header\_compilation to disable header compilation on platforms that do not support it, e.g. JDK 7 Bazel. | +| `genclass` | [Label](./concepts/labels); default is `None` Label of the GenClass deploy jar. | +| `header_compiler` | [Label](./concepts/labels); default is `None` Label of the header compiler. Required if --java\_header\_compilation is enabled. | +| `header_compiler_builtin_processors` | List of strings; default is `[]` Internal API, do not use! | +| `header_compiler_direct` | [Label](./concepts/labels); default is `None` Optional label of the header compiler to use for direct classpath actions that do not include any API-generating annotation processors. This tool does not support annotation processing. | +| `ijar` | [Label](./concepts/labels); default is `None` Label of the ijar executable. | +| `jacocorunner` | [Label](./concepts/labels); default is `None` Label of the JacocoCoverageRunner deploy jar. | +| `java_runtime` | [Label](./concepts/labels); default is `None` The java\_runtime to use with this toolchain. It defaults to java\_runtime in execution configuration. | +| `javabuilder` | [Label](./concepts/labels); default is `None` Label of the JavaBuilder deploy jar. | +| `javabuilder_data` | List of [labels](./concepts/labels); default is `[]` Labels of data available for label-expansion in javabuilder\_jvm\_opts. | +| `javabuilder_jvm_opts` | List of strings; default is `[]` The list of arguments for the JVM when invoking JavaBuilder. | +| `javac_supports_multiplex_workers` | Boolean; default is `True` True if JavaBuilder supports running as a multiplex persistent worker, false if it doesn't. | +| `javac_supports_worker_cancellation` | Boolean; default is `True` True if JavaBuilder supports cancellation of persistent workers, false if it doesn't. | +| `javac_supports_worker_multiplex_sandboxing` | Boolean; default is `False` True if JavaBuilder supports running as a multiplex persistent worker with sandboxing, false if it doesn't. | +| `javac_supports_workers` | Boolean; default is `True` True if JavaBuilder supports running as a persistent worker, false if it doesn't. | +| `javacopts` | List of strings; default is `[]` The list of extra arguments for the Java compiler. Please refer to the Java compiler documentation for the extensive list of possible Java compiler flags. | +| `jspecify_implicit_deps` | [Label](./concepts/labels); default is `None` Experimental, do not use! | +| `jspecify_javacopts` | List of strings; default is `[]` Experimental, do not use! | +| `jspecify_packages` | List of [labels](./concepts/labels); default is `[]` Experimental, do not use! | +| `jspecify_processor` | [Label](./concepts/labels); default is `None` Experimental, do not use! | +| `jspecify_processor_class` | String; default is `""` Experimental, do not use! | +| `jspecify_stubs` | List of [labels](./concepts/labels); default is `[]` Experimental, do not use! | +| `jvm_opts` | List of strings; default is `[]` The list of arguments for the JVM when invoking the Java compiler. Please refer to the Java virtual machine documentation for the extensive list of possible flags for this option. | +| `misc` | List of strings; default is `[]` Deprecated: use javacopts instead | +| `oneversion` | [Label](./concepts/labels); default is `None` Label of the one-version enforcement binary. | +| `oneversion_allowlist` | [Label](./concepts/labels); default is `None` Label of the one-version allowlist. | +| `oneversion_allowlist_for_tests` | [Label](./concepts/labels); default is `None` Label of the one-version allowlist for tests. | +| `oneversion_whitelist` | [Label](./concepts/labels); default is `None` Deprecated: use oneversion\_allowlist instead | +| `package_configuration` | List of [labels](./concepts/labels); default is `[]` Configuration that should be applied to the specified package groups. | +| `proguard_allowlister` | [Label](./concepts/labels); default is `"@bazel_tools//tools/jdk:proguard_whitelister"` Label of the Proguard allowlister. | +| `reduced_classpath_incompatible_processors` | List of strings; default is `[]` Internal API, do not use! | +| `singlejar` | [Label](./concepts/labels); default is `None` Label of the SingleJar deploy jar. | +| `source_version` | String; default is `""` The Java source version (e.g., '6' or '7'). It specifies which set of code structures are allowed in the Java source code. | +| `target_version` | String; default is `""` The Java target version (e.g., '6' or '7'). It specifies for which Java runtime the class should be build. | +| `timezone_data` | [Label](./concepts/labels); default is `None` Label of a resource jar containing timezone data. If set, the timezone data is added as an implicitly runtime dependency of all java\_binary rules. | +| `tools` | List of [labels](./concepts/labels); default is `[]` Labels of tools available for label-expansion in jvm\_opts. | +| `turbine_data` | List of [labels](./concepts/labels); default is `[]` Labels of data available for label-expansion in turbine\_jvm\_opts. | +| `turbine_jvm_opts` | List of strings; default is `[]` The list of arguments for the JVM when invoking turbine. | +| `xlint` | List of strings; default is `[]` The list of warning to add or removes from default list. Precedes it with a dash to removes it. Please see the Javac documentation on the -Xlint options for more information. | \ No newline at end of file diff --git a/reference/be/make-variables.mdx b/reference/be/make-variables.mdx index 81f2d25..098a8d6 100644 --- a/reference/be/make-variables.mdx +++ b/reference/be/make-variables.mdx @@ -2,16 +2,12 @@ title: 'make-variables' --- -# Make Variables -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm" %} -{% include "\_buttons.html" %} - -- [Use](#use) -- [Predefined variables](#predefined_variables) -- [Predefined genrule variables](#predefined_genrule_variables) -- [Predefined source/output path variables](#predefined_label_variables) -- [Custom variables](#custom_variables) +* [Use](#use) +* [Predefined variables](#predefined_variables) +* [Predefined genrule variables](#predefined_genrule_variables) +* [Predefined source/output path variables](#predefined_label_variables) +* [Custom variables](#custom_variables) "Make" variables are a special class of expandable string variables available to attributes marked as *"Subject to 'Make variable' substitution"*. @@ -25,7 +21,7 @@ and only available to targets that depend on them. The reason for the term "Make" is historical: the syntax and semantics of these variables were originally intended to match [GNU -Make](https://www.gnu.org/software/make/manual/html_node/Using-Variables.html). +Make](https://www.gnu.org/software/make/manual/html_node/Using-Variables.mdx). ## Use @@ -68,61 +64,55 @@ and look at the top output lines with capital letters. **Toolchain option variables** -- `COMPILATION_MODE`: +* `COMPILATION_MODE`: `fastbuild`, `dbg`, or `opt`. ([more details](https://bazel.build/docs/user-manual#flag--compilation_mode)) **Path variables** -- `BINDIR`: The base of the generated binary tree for the target +* `BINDIR`: The base of the generated binary tree for the target architecture. Note that a different tree may be used for programs that run during the build on the host architecture, to support cross-compiling. If you want to run a tool from within a `genrule`, the - recommended way to get its path is `$(`[`execpath`](#predefined_label_variables)` toolname)`, + recommended way to get its path is `$(execpath toolname)`, where *toolname* must be listed in the `genrule`'s - [`tools`](/reference/be/general.html#genrule.tools) attribute. - -- `GENDIR`: + `tools` attribute. +* `GENDIR`: The base of the generated code tree for the target architecture. **Machine architecture variables** -- `TARGET_CPU`: +* `TARGET_CPU`: The target architecture's CPU, e.g. `k8`. ## Predefined genrule variables The following are specially available to `genrule`'s -[`cmd`](/reference/be/general.html#genrule.cmd) attribute and are +`cmd` attribute and are generally important for making that attribute work. [See an example of predefined genrule variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-genrule-variables). -- `OUTS`: The `genrule`'s [`outs`](/reference/be/general.html#genrule.outs) list. If you have +* `OUTS`: The `genrule`'s `outs` list. If you have only one output file, you can also use `$@`. - -- `SRCS`: The `genrule`'s [`srcs`](/reference/be/general.html#genrule.srcs) list (or more +* `SRCS`: The `genrule`'s `srcs` list (or more precisely: the path names of the files corresponding to labels in the - [`srcs`](/reference/be/general.html#genrule.srcs) list). + `srcs` list). If you have only one source file, you can also use `$<`. - -- `<`: `SRCS`, if it is a single file. Else triggers +* `<`: `SRCS`, if it is a single file. Else triggers a build error. - -- `@`: `OUTS`, if it is a single file. Else triggers a +* `@`: `OUTS`, if it is a single file. Else triggers a build error. - -- `RULEDIR`: The output directory of the target, that is, the +* `RULEDIR`: The output directory of the target, that is, the directory corresponding to the name of the package containing the target under the `genfiles` or `bin` tree. For `//my/pkg:my_genrule` this always ends in `my/pkg`, even if `//my/pkg:my_genrule`'s outputs are in subdirectories. - -- `@D`: The output directory. If - [outs](/reference/be/general.html#genrule.outs) has one entry, +* `@D`: The output directory. If + [outs](./reference/be/general.html#genrule.outs) has one entry, this expands to the directory containing that file. If it has multiple entries, this expands to the package's root directory in the `genfiles` tree, *even if all output files are in the same @@ -145,16 +135,18 @@ filenames contain spaces, `'`, or other special characters (or your genrule is part of a Starlark macro which downstream users may invoke on such files), then `$(SRCS)` and `$(OUTS)` are not suitable for interpolation into a command line, as they do not have the semantics that -`"${@}"` would in Bash. +`"$\{@\}"` would in Bash. One workaround is to convert to a Bash array, with - mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion' - $(SRC) - genrule_srcs_expansion - ) +``` +mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion' +$(SRC) +genrule_srcs_expansion +) +``` -and then use `"$$\{SRCS[@]}"` in subsequent command lines in place +and then use `"$$\{SRCS[@]\}"` in subsequent command lines in place of `$(SRCS)`. A more robust option is to write a Starlark rule instead. @@ -162,7 +154,8 @@ instead. The predefined variables `execpath`, `execpaths`, `rootpath`, `rootpaths`, `location`, and -`locations` take label parameters (e.g. `$(execpath //foo:bar)`) and substitute the file paths denoted by that label. +`locations` take label parameters (e.g. `$(execpath +//foo:bar)`) and substitute the file paths denoted by that label. For source files, this is the path relative to your workspace root. For files that are outputs of rules, this is the file's *output path* @@ -170,8 +163,8 @@ For files that are outputs of rules, this is the file's *output path* [See an example of predefined path variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-path-variables). -- `execpath`: Denotes the path beneath the - [execroot](/docs/output_directories) +* `execpath`: Denotes the path beneath the + [execroot](./docs/output_directories) where Bazel runs build actions. In the above example, Bazel runs all build actions in the directory linked @@ -185,10 +178,10 @@ For files that are outputs of rules, this is the file's *output path* `bazel-out/cpu-compilation_mode/bin` (or for the outputs of tools: `bazel-out/cpu-opt-exec-hash/bin`). In the above example, `//testapp:app` is a tool because it appears in - `show_app_output`'s [`tools`](/reference/be/general.html#genrule.tools) attribute. + `show_app_output`'s `tools` attribute. So its output file `app` is written to `bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app`. - The exec path is thus ` bazel-out/cpu-opt-exec-hash/bin/testapp/app`. This extra prefix + The exec path is thus `bazel-out/cpu-opt-exec-hash/bin/testapp/app`. This extra prefix makes it possible to build the same target for, say, two different CPUs in the same build without the results clobbering each other. @@ -196,12 +189,10 @@ For files that are outputs of rules, this is the file's *output path* labels representing source files, this is automatically true. For labels representing rules, the rule must generate exactly one output. If this is false or the label is malformed, the build fails with an error. - -- `rootpath`: Denotes the path that a built binary can use to +* `rootpath`: Denotes the path that a built binary can use to find a dependency at runtime relative to the subdirectory of its runfiles directory corresponding to the main repository. - **Note:** This only works if - [`--enable_runfiles`](/reference/command-line-reference#flag--enable_runfiles) is enabled, which is not the case on + **Note:** This only works if [`--enable_runfiles`](./reference/command-line-reference#flag--enable_runfiles) is enabled, which is not the case on Windows by default. Use `rlocationpath` instead for cross-platform support. @@ -215,15 +206,14 @@ For files that are outputs of rules, this is the file's *output path* repository-relative path. This has the same "one output only" requirements as `execpath`. - -- `rlocationpath`: The path a built binary can pass to the ` Rlocation` function of a runfiles library to find a dependency at +* `rlocationpath`: The path a built binary can pass to the `Rlocation` function of a runfiles library to find a dependency at runtime, either in the runfiles directory (if available) or using the runfiles manifest. This is similar to `rootpath` in that it does not contain configuration prefixes, but differs in that it always starts with the - name of the repository. In the example from above this means that ` empty.source` and `app` result in the following - paths: `myproject/testapp/empty.source` and ` myproject/testapp/app`. + name of the repository. In the example from above this means that `empty.source` and `app` result in the following + paths: `myproject/testapp/empty.source` and `myproject/testapp/app`. The `rlocationpath` of a file in an external repository `repo` will start with `repo/`, followed by the @@ -236,11 +226,10 @@ For files that are outputs of rules, this is the file's *output path* available. This has the same "one output only" requirements as `execpath`. - -- `location`: A synonym for either `execpath` or +* `location`: A synonym for either `execpath` or `rootpath`, depending on the attribute being expanded. This is legacy pre-Starlark behavior and not recommended unless you really know what - it does for a particular rule. See [\#2475](https://github.com/bazelbuild/bazel/issues/2475#issuecomment-339318016) + it does for a particular rule. See [#2475](https://github.com/bazelbuild/bazel/issues/2475#issuecomment-339318016) for details. `execpaths`, `rootpaths`, `rlocationpaths`, @@ -252,7 +241,7 @@ labels produce build errors. All referenced labels must appear in the consuming target's `srcs`, output files, or `deps`. Otherwise the build fails. C++ targets can -also reference labels in [`data`](/reference/be/c-cpp.html#cc_binary.data). +also reference labels in `data`. Labels don't have to be in canonical form: `foo`, `:foo` and `//somepkg:foo` are all fine. @@ -271,8 +260,9 @@ not care about. **C++ toolchain variables** The following are defined in C++ toolchain rules and available to any rule -that sets `toolchains = ["@bazel_tools//tools/cpp:toolchain_type"]` -Some rules, like [`java_binary`](/reference/be/java.html#java_binary), implicitly +that sets `toolchains = +["@bazel_tools//tools/cpp:toolchain_type"]` +Some rules, like `java_binary`, implicitly include the C++ toolchain in their rule definition. They inherit these variables automatically. @@ -286,38 +276,31 @@ on each of potentially multiple internally generated actions. These variables are a fallback mechanism to be used by language experts in rare cases. If you are tempted to use them, please [contact the Bazel devs](https://bazel.build/help) first. -- `ABI`: The C++ ABI version. - -- `AR`: The "ar" command from crosstool. - -- `C_COMPILER`: +* `ABI`: The C++ ABI version. +* `AR`: The "ar" command from crosstool. +* `C_COMPILER`: The C/C++ compiler identifier, e.g. `llvm`. - -- `CC`: The C and C++ compiler command. +* `CC`: The C and C++ compiler command. We strongly recommended always using `CC_FLAGS` in combination with `CC`. Fail to do so at your own risk. - -- `CC_FLAGS`: A minimal set of flags for the C/C++ +* `CC_FLAGS`: A minimal set of flags for the C/C++ compiler to be usable by genrules. In particular, this contains flags to select the correct architecture if `CC` supports multiple architectures. - -- `DUMPBIN`: Microsoft COFF Binary File Dumper (dumpbin.exe) from +* `DUMPBIN`: Microsoft COFF Binary File Dumper (dumpbin.exe) from from Microsoft Visual Studio. - -- `NM`: The "nm" command from crosstool. - -- `OBJCOPY`: The objcopy command from the same suite as the C/C++ +* `NM`: The "nm" command from crosstool. +* `OBJCOPY`: The objcopy command from the same suite as the C/C++ compiler. - -- `STRIP`: The strip command from the same suite as the C/C++ +* `STRIP`: The strip command from the same suite as the C/C++ compiler. **Java toolchain variables** The following are defined in Java toolchain rules and available to any rule -that sets `toolchains = ["@rules_java//toolchains:current_java_runtime"]` (or +that sets `toolchains = +["@rules_java//toolchains:current_java_runtime"]` (or `"@rules_java//toolchains:current_host_java_runtime"` for the host toolchain equivalent). @@ -329,21 +312,21 @@ Jars, and highly optimized Jar packaging and merging implementations. These variables are a fallback mechanism to be used by language experts in rare cases. If you are tempted to use them, please [contact the Bazel devs](https://bazel.build/help) first. -- `JAVA`: The "java" command (a Java virtual - machine). Avoid this, and use a [`java_binary`](/reference/be/java.html#java_binary) rule +* `JAVA`: The "java" command (a Java virtual + machine). Avoid this, and use a `java_binary` rule instead where possible. May be a relative path. If you must change directories before invoking `java`, you need to capture the working directory before changing it. -- `JAVABASE`: The base directory containing the +* `JAVABASE`: The base directory containing the Java utilities. May be a relative path. It will have a "bin" subdirectory. **Starlark-defined variables** -Rule and [toolchain](/docs/toolchains) writers can define +Rule and [toolchain](./docs/toolchains) writers can define completely custom variables by returning a -[TemplateVariableInfo](/rules/lib/TemplateVariableInfo) +[TemplateVariableInfo](./rules/lib/TemplateVariableInfo) provider. Any rules depending on these through the `toolchains` attribute can then read their values: -[See an example of Starlark-defined variables](https://github.com/bazelbuild/examples/tree/main/make-variables#custom-starlark-defined-variables). +[See an example of Starlark-defined variables](https://github.com/bazelbuild/examples/tree/main/make-variables#custom-starlark-defined-variables). \ No newline at end of file diff --git a/reference/be/objective-c.mdx b/reference/be/objective-c.mdx index 72afbd3..32b38c1 100644 --- a/reference/be/objective-c.mdx +++ b/reference/be/objective-c.mdx @@ -2,21 +2,17 @@ title: 'objective-c' --- -# Objective-C Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} ## Rules -- [objc_import](#objc_import) -- [objc_library](#objc_library) +* [objc\_import](#objc_import) +* [objc\_library](#objc_library) -## objc_import +## objc\_import -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_import.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_import.bzl) -``` rule-signature +``` objc_import(name, deps, hdrs, alwayslink, archives, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, includes, package_metadata, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) ``` @@ -26,117 +22,25 @@ attributes supported by `objc_library`. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="objc_import.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="objc_import.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of targets that this target depend on.</td> -</tr> -<tr> -<td id="objc_import.hdrs"><code>hdrs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of C, C++, Objective-C, and Objective-C++ header files published -by this library to be included by sources in dependent rules. -<p>These headers describe the public interface for the library and will be -made available for inclusion by sources in this rule or in dependent -rules. Headers not meant to be included by a client of this library -should be listed in the srcs attribute instead.</p> -<p>These will be compiled separately from the source if modules are enabled.</p></td> -</tr> -<tr> -<td id="objc_import.alwayslink"><code>alwayslink</code></td> -<td><p>Boolean; default is <code>False</code></p> -If 1, any bundle or binary that depends (directly or indirectly) on this -library will link in all the object files for the files listed in -<code>srcs</code> and <code>non_arc_srcs</code>, even if some contain no -symbols referenced by the binary. -This is useful if your code isn't explicitly called by code in -the binary, e.g., if your code registers to receive some callback -provided by some service.</td> -</tr> -<tr> -<td id="objc_import.archives"><code>archives</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; required</p> -The list of <code>.a</code> files provided to Objective-C targets that -depend on this target.</td> -</tr> -<tr> -<td id="objc_import.includes"><code>includes</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of <code>#include/#import</code> search paths to add to this target -and all depending targets. -This is to support third party and open-sourced libraries that do not -specify the entire workspace path in their -<code>#import/#include</code> statements. -<p>The paths are interpreted relative to the package directory, and the -genfiles and bin roots (e.g. <code>blaze-genfiles/pkg/includedir</code> -and <code>blaze-out/pkg/includedir</code>) are included in addition to the -actual client root.</p> -<p>Unlike <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a>, these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-iquote" flags to <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead.</p></td> -</tr> -<tr> -<td id="objc_import.sdk_dylibs"><code>sdk_dylibs</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Names of SDK .dylib libraries to link with. For instance, "libz" or -"libarchive". -"libc++" is included automatically if the binary has any C++ or -Objective-C++ sources in its dependency tree. When linking a binary, -all libraries named in that binary's transitive dependency graph are -used.</td> -</tr> -<tr> -<td id="objc_import.sdk_frameworks"><code>sdk_frameworks</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). -<p>When linking a top level Apple binary, all SDK frameworks listed in that binary's -transitive dependency graph are linked.</p></td> -</tr> -<tr> -<td id="objc_import.sdk_includes"><code>sdk_includes</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of <code>#include/#import</code> search paths to add to this target -and all depending targets, where each path is relative to -<code>$(SDKROOT)/usr/include</code>.</td> -</tr> -<tr> -<td id="objc_import.textual_hdrs"><code>textual_hdrs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of C, C++, Objective-C, and Objective-C++ files that are -included as headers by source files in this rule or by users of this -library. Unlike hdrs, these will not be compiled separately from the -sources.</td> -</tr> -<tr> -<td id="objc_import.weak_sdk_frameworks"><code>weak_sdk_frameworks</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Names of SDK frameworks to weakly link with. For instance, -"MediaAccessibility". -In difference to regularly linked SDK frameworks, symbols -from weakly linked frameworks do not cause an error if they -are not present at runtime.</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of targets that this target depend on. | +| `hdrs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ header files published by this library to be included by sources in dependent rules. These headers describe the public interface for the library and will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the srcs attribute instead. These will be compiled separately from the source if modules are enabled. | +| `alwayslink` | Boolean; default is `False` If 1, any bundle or binary that depends (directly or indirectly) on this library will link in all the object files for the files listed in `srcs` and `non_arc_srcs`, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. | +| `archives` | List of [labels](./concepts/labels); required The list of `.a` files provided to Objective-C targets that depend on this target. | +| `includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets. This is to support third party and open-sourced libraries that do not specify the entire workspace path in their `#import/#include` statements. The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. `blaze-genfiles/pkg/includedir` and `blaze-out/pkg/includedir`) are included in addition to the actual client root. Unlike [COPTS](./reference/be/objective-c.html#objc_library.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-iquote" flags to [COPTS](./reference/be/objective-c.html#objc_library.copts) instead. | +| `sdk_dylibs` | List of strings; default is `[]` Names of SDK .dylib libraries to link with. For instance, "libz" or "libarchive". "libc++" is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are used. | +| `sdk_frameworks` | List of strings; default is `[]` Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). When linking a top level Apple binary, all SDK frameworks listed in that binary's transitive dependency graph are linked. | +| `sdk_includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets, where each path is relative to `$(SDKROOT)/usr/include`. | +| `textual_hdrs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ files that are included as headers by source files in this rule or by users of this library. Unlike hdrs, these will not be compiled separately from the sources. | +| `weak_sdk_frameworks` | List of strings; default is `[]` Names of SDK frameworks to weakly link with. For instance, "MediaAccessibility". In difference to regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause an error if they are not present at runtime. | -## objc_library +## objc\_library -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_library.bzl) -``` rule-signature +``` objc_library(name, deps, srcs, data, hdrs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, enable_modules, exec_compatible_with, exec_group_compatible_with, exec_properties, features, implementation_deps, includes, linkopts, module_map, module_name, non_arc_srcs, package_metadata, pch, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, stamp, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) ``` @@ -144,222 +48,28 @@ This rule produces a static library from the given Objective-C source files. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="objc_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="objc_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of targets that this target depend on.</td> -</tr> -<tr> -<td id="objc_library.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of C, C++, Objective-C, and Objective-C++ source and header -files, and/or (`.s`, `.S`, or `.asm`) assembly source files, that are processed to create -the library target. -These are your checked-in files, plus any generated files. -Source files are compiled into .o files with Clang. Header files -may be included/imported by any source or header in the srcs attribute -of this target, but not by headers in hdrs or any targets that depend -on this rule. -Additionally, precompiled .o files may be given as srcs. Be careful to -ensure consistency in the architecture of provided .o files and that of the -build to avoid missing symbol linker errors.</td> -</tr> -<tr> -<td id="objc_library.hdrs"><code>hdrs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of C, C++, Objective-C, and Objective-C++ header files published -by this library to be included by sources in dependent rules. -<p>These headers describe the public interface for the library and will be -made available for inclusion by sources in this rule or in dependent -rules. Headers not meant to be included by a client of this library -should be listed in the srcs attribute instead.</p> -<p>These will be compiled separately from the source if modules are enabled.</p></td> -</tr> -<tr> -<td id="objc_library.alwayslink"><code>alwayslink</code></td> -<td><p>Boolean; default is <code>False</code></p> -If 1, any bundle or binary that depends (directly or indirectly) on this -library will link in all the object files for the files listed in -<code>srcs</code> and <code>non_arc_srcs</code>, even if some contain no -symbols referenced by the binary. -This is useful if your code isn't explicitly called by code in -the binary, e.g., if your code registers to receive some callback -provided by some service.</td> -</tr> -<tr> -<td id="objc_library.conlyopts"><code>conlyopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra flags to pass to the compiler for C files. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -These flags will only apply to this target, and not those upon which -it depends, or those which depend on it. -<p>Note that for the generated Xcode project, directory paths specified using "-I" flags in -copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and -added to the header search paths for the associated Xcode target.</p></td> -</tr> -<tr> -<td id="objc_library.copts"><code>copts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra flags to pass to the compiler. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -These flags will only apply to this target, and not those upon which -it depends, or those which depend on it. -<p>Note that for the generated Xcode project, directory paths specified using "-I" flags in -copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and -added to the header search paths for the associated Xcode target.</p></td> -</tr> -<tr> -<td id="objc_library.cxxopts"><code>cxxopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra flags to pass to the compiler for Objective-C++ and C++ files. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>. -These flags will only apply to this target, and not those upon which -it depends, or those which depend on it. -<p>Note that for the generated Xcode project, directory paths specified using "-I" flags in -copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and -added to the header search paths for the associated Xcode target.</p></td> -</tr> -<tr> -<td id="objc_library.defines"><code>defines</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra <code>-D</code> flags to pass to the compiler. They should be in -the form <code>KEY=VALUE</code> or simply <code>KEY</code> and are -passed not only to the compiler for this target (as <code>copts</code> -are) but also to all <code>objc_</code> dependers of this target. -Subject to <a href="/reference/be/make-variables">"Make variable"</a> substitution and -<a href="/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.</td> -</tr> -<tr> -<td id="objc_library.enable_modules"><code>enable_modules</code></td> -<td><p>Boolean; default is <code>False</code></p> -Enables clang module support (via -fmodules). -Setting this to 1 will allow you to @import system headers and other targets: -@import UIKit; -@import path_to_package_target;</td> -</tr> -<tr> -<td id="objc_library.implementation_deps"><code>implementation_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other libraries that the library target depends on. Unlike with -<code>deps</code>, the headers and include paths of these libraries (and all their -transitive deps) are only used for compilation of this library, and not libraries that -depend on it. Libraries specified with <code>implementation_deps</code> are still linked -in binary targets that depend on this library.</td> -</tr> -<tr> -<td id="objc_library.includes"><code>includes</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of <code>#include/#import</code> search paths to add to this target -and all depending targets. -This is to support third party and open-sourced libraries that do not -specify the entire workspace path in their -<code>#import/#include</code> statements. -<p>The paths are interpreted relative to the package directory, and the -genfiles and bin roots (e.g. <code>blaze-genfiles/pkg/includedir</code> -and <code>blaze-out/pkg/includedir</code>) are included in addition to the -actual client root.</p> -<p>Unlike <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a>, these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-iquote" flags to <a href="/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead.</p></td> -</tr> -<tr> -<td id="objc_library.linkopts"><code>linkopts</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Extra flags to pass to the linker.</td> -</tr> -<tr> -<td id="objc_library.module_map"><code>module_map</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -custom Clang module map for this target. Use of a custom module map is discouraged. Most -users should use module maps generated by Bazel. -If specified, Bazel will not generate a module map for this target, but will pass the -provided module map to the compiler.</td> -</tr> -<tr> -<td id="objc_library.module_name"><code>module_name</code></td> -<td><p>String; default is <code>""</code></p> -Sets the module name for this target. By default the module name is the target path with -all special symbols replaced by _, e.g. //foo/baz:bar can be imported as foo_baz_bar.</td> -</tr> -<tr> -<td id="objc_library.non_arc_srcs"><code>non_arc_srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of Objective-C files that are processed to create the -library target that DO NOT use ARC. -The files in this attribute are treated very similar to those in the -srcs attribute, but are compiled without ARC enabled.</td> -</tr> -<tr> -<td id="objc_library.pch"><code>pch</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Header file to prepend to every source file being compiled (both arc -and non-arc). -Use of pch files is actively discouraged in BUILD files, and this should be -considered deprecated. Since pch files are not actually precompiled this is not -a build-speed enhancement, and instead is just a global dependency. From a build -efficiency point of view you are actually better including what you need directly -in your sources where you need it.</td> -</tr> -<tr> -<td id="objc_library.sdk_dylibs"><code>sdk_dylibs</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Names of SDK .dylib libraries to link with. For instance, "libz" or -"libarchive". -"libc++" is included automatically if the binary has any C++ or -Objective-C++ sources in its dependency tree. When linking a binary, -all libraries named in that binary's transitive dependency graph are -used.</td> -</tr> -<tr> -<td id="objc_library.sdk_frameworks"><code>sdk_frameworks</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). -<p>When linking a top level Apple binary, all SDK frameworks listed in that binary's -transitive dependency graph are linked.</p></td> -</tr> -<tr> -<td id="objc_library.sdk_includes"><code>sdk_includes</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of <code>#include/#import</code> search paths to add to this target -and all depending targets, where each path is relative to -<code>$(SDKROOT)/usr/include</code>.</td> -</tr> -<tr> -<td id="objc_library.stamp"><code>stamp</code></td> -<td><p>Boolean; default is <code>False</code></p></td> -</tr> -<tr> -<td id="objc_library.textual_hdrs"><code>textual_hdrs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of C, C++, Objective-C, and Objective-C++ files that are -included as headers by source files in this rule or by users of this -library. Unlike hdrs, these will not be compiled separately from the -sources.</td> -</tr> -<tr> -<td id="objc_library.weak_sdk_frameworks"><code>weak_sdk_frameworks</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Names of SDK frameworks to weakly link with. For instance, -"MediaAccessibility". -In difference to regularly linked SDK frameworks, symbols -from weakly linked frameworks do not cause an error if they -are not present at runtime.</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of targets that this target depend on. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ source and header files, and/or (`.s`, `.S`, or `.asm`) assembly source files, that are processed to create the library target. These are your checked-in files, plus any generated files. Source files are compiled into .o files with Clang. Header files may be included/imported by any source or header in the srcs attribute of this target, but not by headers in hdrs or any targets that depend on this rule. Additionally, precompiled .o files may be given as srcs. Be careful to ensure consistency in the architecture of provided .o files and that of the build to avoid missing symbol linker errors. | +| `hdrs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ header files published by this library to be included by sources in dependent rules. These headers describe the public interface for the library and will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the srcs attribute instead. These will be compiled separately from the source if modules are enabled. | +| `alwayslink` | Boolean; default is `False` If 1, any bundle or binary that depends (directly or indirectly) on this library will link in all the object files for the files listed in `srcs` and `non_arc_srcs`, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. | +| `conlyopts` | List of strings; default is `[]` Extra flags to pass to the compiler for C files. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). These flags will only apply to this target, and not those upon which it depends, or those which depend on it. Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and added to the header search paths for the associated Xcode target. | +| `copts` | List of strings; default is `[]` Extra flags to pass to the compiler. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). These flags will only apply to this target, and not those upon which it depends, or those which depend on it. Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and added to the header search paths for the associated Xcode target. | +| `cxxopts` | List of strings; default is `[]` Extra flags to pass to the compiler for Objective-C++ and C++ files. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). These flags will only apply to this target, and not those upon which it depends, or those which depend on it. Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and added to the header search paths for the associated Xcode target. | +| `defines` | List of strings; default is `[]` Extra `-D` flags to pass to the compiler. They should be in the form `KEY=VALUE` or simply `KEY` and are passed not only to the compiler for this target (as `copts` are) but also to all `objc_` dependers of this target. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | +| `enable_modules` | Boolean; default is `False` Enables clang module support (via -fmodules). Setting this to 1 will allow you to @import system headers and other targets: @import UIKit; @import path\_to\_package\_target; | +| `implementation_deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries that the library target depends on. Unlike with `deps`, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with `implementation_deps` are still linked in binary targets that depend on this library. | +| `includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets. This is to support third party and open-sourced libraries that do not specify the entire workspace path in their `#import/#include` statements. The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. `blaze-genfiles/pkg/includedir` and `blaze-out/pkg/includedir`) are included in addition to the actual client root. Unlike [COPTS](./reference/be/objective-c.html#objc_library.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-iquote" flags to [COPTS](./reference/be/objective-c.html#objc_library.copts) instead. | +| `linkopts` | List of strings; default is `[]` Extra flags to pass to the linker. | +| `module_map` | [Label](./concepts/labels); default is `None` custom Clang module map for this target. Use of a custom module map is discouraged. Most users should use module maps generated by Bazel. If specified, Bazel will not generate a module map for this target, but will pass the provided module map to the compiler. | +| `module_name` | String; default is `""` Sets the module name for this target. By default the module name is the target path with all special symbols replaced by \_, e.g. //foo/baz:bar can be imported as foo\_baz\_bar. | +| `non_arc_srcs` | List of [labels](./concepts/labels); default is `[]` The list of Objective-C files that are processed to create the library target that DO NOT use ARC. The files in this attribute are treated very similar to those in the srcs attribute, but are compiled without ARC enabled. | +| `pch` | [Label](./concepts/labels); default is `None` Header file to prepend to every source file being compiled (both arc and non-arc). Use of pch files is actively discouraged in BUILD files, and this should be considered deprecated. Since pch files are not actually precompiled this is not a build-speed enhancement, and instead is just a global dependency. From a build efficiency point of view you are actually better including what you need directly in your sources where you need it. | +| `sdk_dylibs` | List of strings; default is `[]` Names of SDK .dylib libraries to link with. For instance, "libz" or "libarchive". "libc++" is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are used. | +| `sdk_frameworks` | List of strings; default is `[]` Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). When linking a top level Apple binary, all SDK frameworks listed in that binary's transitive dependency graph are linked. | +| `sdk_includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets, where each path is relative to `$(SDKROOT)/usr/include`. | +| `stamp` | Boolean; default is `False` | +| `textual_hdrs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ files that are included as headers by source files in this rule or by users of this library. Unlike hdrs, these will not be compiled separately from the sources. | +| `weak_sdk_frameworks` | List of strings; default is `[]` Names of SDK frameworks to weakly link with. For instance, "MediaAccessibility". In difference to regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause an error if they are not present at runtime. | \ No newline at end of file diff --git a/reference/be/overview.mdx b/reference/be/overview.mdx index e72f5b2..1e07111 100644 --- a/reference/be/overview.mdx +++ b/reference/be/overview.mdx @@ -2,33 +2,29 @@ title: 'overview' --- -# Bazel BUILD Encyclopedia of Functions - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm" %} -{% include "\_buttons.html" %} ## Concepts and terminology -- [Common definitions](/reference/be/common-definitions) - - [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization) - - [Label expansion](/reference/be/common-definitions#label-expansion) - - [Typical attributes for most rules](/reference/be/common-definitions#typical-attributes) - - [Common attributes for all rules](/reference/be/common-definitions#common-attributes) - - [Common attributes for tests](/reference/be/common-definitions#common-attributes-tests) - - [Common attributes for binaries](/reference/be/common-definitions#common-attributes-binaries) - - [Configurable attributes](/reference/be/common-definitions#configurable-attributes) - - [Implicit output targets](/reference/be/common-definitions#implicit-outputs) -- ["Make" variables](/reference/be/make-variables) - - [Use](/reference/be/make-variables#use) +* [Common definitions](./reference/be/common-definitions) + + [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization) + + [Label expansion](./reference/be/common-definitions#label-expansion) + + [Typical attributes for most rules](./reference/be/common-definitions#typical-attributes) + + [Common attributes for all rules](./reference/be/common-definitions#common-attributes) + + [Common attributes for tests](./reference/be/common-definitions#common-attributes-tests) + + [Common attributes for binaries](./reference/be/common-definitions#common-attributes-binaries) + + [Configurable attributes](./reference/be/common-definitions#configurable-attributes) + + [Implicit output targets](./reference/be/common-definitions#implicit-outputs) +* ["Make" variables](./reference/be/make-variables) + + [Use](./reference/be/make-variables#use) ## Functions -- [package](/reference/be/functions.html#package) -- [package_group](/reference/be/functions.html#package_group) -- [exports_files](/reference/be/functions.html#exports_files) -- [glob](/reference/be/functions.html#glob) -- [select](/reference/be/functions.html#select) -- [workspace](/rules/lib/globals/workspace#workspace) +* [package](./reference/be/functions.html#package) +* [package\_group](./reference/be/functions.html#package_group) +* [exports\_files](./reference/be/functions.html#exports_files) +* [glob](./reference/be/functions.html#glob) +* [select](./reference/be/functions.html#select) +* [workspace](./rules/lib/globals/workspace#workspace) ## Rules @@ -36,159 +32,23 @@ Native rules ship with the Bazel binary and do not require a `load` statement. Native rules are available globally in BUILD files. In .bzl files, you can find them in the `native` module. For non-native Starlark rules that ship separately from Bazel, see the list of -[recommended rules](/rules/rules#recommended-rules). +[recommended rules](./rules/rules#recommended-rules). ### Language-specific native rules -<table class="table table-condensed table-striped" style="width:100%;" data-summary="Table of rules sorted by language"> -<colgroup> -<col style="width: 16%" /> -<col style="width: 16%" /> -<col style="width: 16%" /> -<col style="width: 16%" /> -<col style="width: 16%" /> -<col style="width: 16%" /> -</colgroup> -<thead> -<tr> -<th>Language</th> -<th>Flags</th> -<th>Binary rules</th> -<th>Library rules</th> -<th>Test rules</th> -<th>Other rules</th> -</tr> -</thead> -<tbody> -<tr> -<td class="lang">C / C++</td> -<td></td> -<td><a href="c-cpp.html#cc_binary">cc_binary</a><br /> -</td> -<td><a href="c-cpp.html#cc_import">cc_import</a><br /> -<a href="c-cpp.html#cc_library">cc_library</a><br /> -<a href="c-cpp.html#cc_shared_library">cc_shared_library</a><br /> -<a href="c-cpp.html#cc_static_library">cc_static_library</a><br /> -</td> -<td><a href="c-cpp.html#cc_test">cc_test</a><br /> -</td> -<td><a href="c-cpp.html#cc_toolchain">cc_toolchain</a><br /> -<a href="c-cpp.html#fdo_prefetch_hints">fdo_prefetch_hints</a><br /> -<a href="c-cpp.html#fdo_profile">fdo_profile</a><br /> -<a href="c-cpp.html#memprof_profile">memprof_profile</a><br /> -<a href="c-cpp.html#propeller_optimize">propeller_optimize</a><br /> -</td> -</tr> -<tr> -<td class="lang">Java</td> -<td></td> -<td><a href="java.html#java_binary">java_binary</a><br /> -</td> -<td><a href="java.html#java_import">java_import</a><br /> -<a href="java.html#java_library">java_library</a><br /> -</td> -<td><a href="java.html#java_test">java_test</a><br /> -</td> -<td><a href="java.html#java_package_configuration">java_package_configuration</a><br /> -<a href="java.html#java_plugin">java_plugin</a><br /> -<a href="java.html#java_runtime">java_runtime</a><br /> -<a href="java.html#java_single_jar">java_single_jar</a><br /> -<a href="java.html#java_toolchain">java_toolchain</a><br /> -</td> -</tr> -<tr> -<td class="lang">Objective-C</td> -<td></td> -<td></td> -<td><a href="objective-c.html#objc_import">objc_import</a><br /> -<a href="objective-c.html#objc_library">objc_library</a><br /> -</td> -<td></td> -<td></td> -</tr> -<tr> -<td class="lang">Protocol Buffer</td> -<td></td> -<td></td> -<td><a href="protocol-buffer.html#cc_proto_library">cc_proto_library</a><br /> -<a href="protocol-buffer.html#java_lite_proto_library">java_lite_proto_library</a><br /> -<a href="protocol-buffer.html#java_proto_library">java_proto_library</a><br /> -<a href="protocol-buffer.html#proto_library">proto_library</a><br /> -<a href="protocol-buffer.html#py_proto_library">py_proto_library</a><br /> -</td> -<td></td> -<td><a href="protocol-buffer.html#proto_lang_toolchain">proto_lang_toolchain</a><br /> -<a href="protocol-buffer.html#proto_toolchain">proto_toolchain</a><br /> -</td> -</tr> -<tr> -<td class="lang">Python</td> -<td></td> -<td><a href="python.html#py_binary">py_binary</a><br /> -</td> -<td><a href="python.html#py_library">py_library</a><br /> -</td> -<td><a href="python.html#py_test">py_test</a><br /> -</td> -<td><a href="python.html#py_runtime">py_runtime</a><br /> -</td> -</tr> -<tr> -<td class="lang">Shell</td> -<td></td> -<td><a href="shell.html#sh_binary">sh_binary</a><br /> -</td> -<td><a href="shell.html#sh_library">sh_library</a><br /> -</td> -<td><a href="shell.html#sh_test">sh_test</a><br /> -</td> -<td></td> -</tr> -</tbody> -</table> +| Language | Flags | Binary rules | Library rules | Test rules | Other rules | +| --- | --- | --- | --- | --- | --- | +| C / C++ | | [cc\_binary](c-cpp.html#cc_binary) | [cc\_import](c-cpp.html#cc_import) [cc\_library](c-cpp.html#cc_library) [cc\_shared\_library](c-cpp.html#cc_shared_library) [cc\_static\_library](c-cpp.html#cc_static_library) | [cc\_test](c-cpp.html#cc_test) | [cc\_toolchain](c-cpp.html#cc_toolchain) [fdo\_prefetch\_hints](c-cpp.html#fdo_prefetch_hints) [fdo\_profile](c-cpp.html#fdo_profile) [memprof\_profile](c-cpp.html#memprof_profile) [propeller\_optimize](c-cpp.html#propeller_optimize) | +| Java | | [java\_binary](java.html#java_binary) | [java\_import](java.html#java_import) [java\_library](java.html#java_library) | [java\_test](java.html#java_test) | [java\_package\_configuration](java.html#java_package_configuration) [java\_plugin](java.html#java_plugin) [java\_runtime](java.html#java_runtime) [java\_single\_jar](java.html#java_single_jar) [java\_toolchain](java.html#java_toolchain) | +| Objective-C | | | [objc\_import](objective-c.html#objc_import) [objc\_library](objective-c.html#objc_library) | | | +| Protocol Buffer | | | [cc\_proto\_library](protocol-buffer.html#cc_proto_library) [java\_lite\_proto\_library](protocol-buffer.html#java_lite_proto_library) [java\_proto\_library](protocol-buffer.html#java_proto_library) [proto\_library](protocol-buffer.html#proto_library) [py\_proto\_library](protocol-buffer.html#py_proto_library) | | [proto\_lang\_toolchain](protocol-buffer.html#proto_lang_toolchain) [proto\_toolchain](protocol-buffer.html#proto_toolchain) | +| Python | | [py\_binary](python.html#py_binary) | [py\_library](python.html#py_library) | [py\_test](python.html#py_test) | [py\_runtime](python.html#py_runtime) | +| Shell | | [sh\_binary](shell.html#sh_binary) | [sh\_library](shell.html#sh_library) | [sh\_test](shell.html#sh_test) | | ### Language-agnostic native rules -<table class="table table-condensed table-striped" data-summary="Table of rules not specific to a programming language"> -<colgroup> -<col style="width: 50%" /> -<col style="width: 50%" /> -</colgroup> -<thead> -<tr> -<th>Family</th> -<th>Rules</th> -</tr> -</thead> -<tbody> -<tr> -<td class="lang">Extra Actions</td> -<td><ul> -<li><a href="extra-actions.html#action_listener">action_listener</a></li> -<li><a href="extra-actions.html#extra_action">extra_action</a></li> -</ul></td> -</tr> -<tr> -<td class="lang">General</td> -<td><ul> -<li><a href="general.html#alias">alias</a></li> -<li><a href="general.html#config_setting">config_setting</a></li> -<li><a href="general.html#filegroup">filegroup</a></li> -<li><a href="general.html#genquery">genquery</a></li> -<li><a href="general.html#genrule">genrule</a></li> -<li><a href="general.html#starlark_doc_extract">starlark_doc_extract</a></li> -<li><a href="general.html#test_suite">test_suite</a></li> -</ul></td> -</tr> -<tr> -<td class="lang">Platforms and Toolchains</td> -<td><ul> -<li><a href="platforms-and-toolchains.html#constraint_setting">constraint_setting</a></li> -<li><a href="platforms-and-toolchains.html#constraint_value">constraint_value</a></li> -<li><a href="platforms-and-toolchains.html#platform">platform</a></li> -<li><a href="platforms-and-toolchains.html#toolchain">toolchain</a></li> -<li><a href="platforms-and-toolchains.html#toolchain_type">toolchain_type</a></li> -</ul></td> -</tr> -</tbody> -</table> +| Family | Rules | +| --- | --- | +| Extra Actions | * [action\_listener](extra-actions.html#action_listener)* [extra\_action](extra-actions.html#extra_action) | +| General | * [alias](general.html#alias)* [config\_setting](general.html#config_setting)* [filegroup](general.html#filegroup)* [genquery](general.html#genquery)* [genrule](general.html#genrule)* [starlark\_doc\_extract](general.html#starlark_doc_extract)* [test\_suite](general.html#test_suite) | +| Platforms and Toolchains | * [constraint\_setting](platforms-and-toolchains.html#constraint_setting)* [constraint\_value](platforms-and-toolchains.html#constraint_value)* [platform](platforms-and-toolchains.html#platform)* [toolchain](platforms-and-toolchains.html#toolchain)* [toolchain\_type](platforms-and-toolchains.html#toolchain_type) | \ No newline at end of file diff --git a/reference/be/platforms-and-toolchains.mdx b/reference/be/platforms-and-toolchains.mdx index 4aae3b8..f6a7b70 100644 --- a/reference/be/platforms-and-toolchains.mdx +++ b/reference/be/platforms-and-toolchains.mdx @@ -2,33 +2,29 @@ title: 'platforms-and-toolchains' --- -# Platforms and Toolchains Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} 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 [here](/extending/platforms). +The user should be familiar with the concepts explained [here](./extending/platforms). ## Rules -- [constraint_setting](#constraint_setting) -- [constraint_value](#constraint_value) -- [platform](#platform) -- [toolchain](#toolchain) -- [toolchain_type](#toolchain_type) +* [constraint\_setting](#constraint_setting) +* [constraint\_value](#constraint_value) +* [platform](#platform) +* [toolchain](#toolchain) +* [toolchain\_type](#toolchain_type) -## constraint_setting +## constraint\_setting -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintSettingRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintSettingRule.java) -``` rule-signature +``` constraint_setting(name, aspect_hints, default_constraint_value, deprecation, features, licenses, tags, testonly, visibility) ``` This rule is used to introduce a new constraint type for which a platform may specify a value. -For instance, you might define a `constraint_setting` named "glibc_version" to represent +For instance, you might define a `constraint_setting` named "glibc\_version" to represent the capability for platforms to have different versions of the glibc library installed. For more details, see the [Platforms](https://bazel.build/docs/platforms) page. @@ -41,39 +37,16 @@ define a platform targeting an obscure cpu architecture. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="constraint_setting.name"><code>name</code></td> -<td><p><a href="/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="/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.</p></td> -</tr> -</tbody> -</table> - -## constraint_value - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintValueRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `default_constraint_value` | [Name](./concepts/labels#target-names); [nonconfigurable](common-definitions.html#configurable-attributes); default is `None` The label of the default value for this setting, to be used if no value is given. If this attribute is present, the `constraint_value` it points to must be defined in the same package as this `constraint_setting`. 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 `config_setting`) that requires a particular value for that setting. | + +## constraint\_value + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintValueRule.java) + +``` constraint_value(name, aspect_hints, constraint_setting, deprecation, features, licenses, tags, testonly, visibility) ``` @@ -86,8 +59,7 @@ For more details, see the The following creates a new possible value for the predefined `constraint_value` representing cpu architecture. -``` code - +``` constraint_value( name = "mips", constraint_setting = "@platforms//cpu:cpu", @@ -99,46 +71,29 @@ Platforms can then declare that they have the `mips` architecture as an alternat ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="constraint_value.name"><code>name</code></td> -<td><p><a href="/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="/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> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `constraint_setting` | [Label](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); required The `constraint_setting` for which this `constraint_value` is a possible choice. | ## platform -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformRule.java) -``` rule-signature +``` platform(name, aspect_hints, constraint_values, deprecation, exec_properties, features, flags, licenses, missing_toolchain_error, parents, remote_execution_properties, required_settings, tags, testonly, visibility) ``` 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 [Platforms](/extending/platforms) page. +For more details, see the [Platforms](./extending/platforms) page. #### Example This defines a platform that describes any environment running Linux on ARM. -``` code - +``` platform( name = "linux_arm", constraint_values = [ @@ -159,8 +114,7 @@ value for that flag, from the command line, rc file, or transition. #### Example -``` code - +``` platform( name = "foo", flags = [ @@ -184,12 +138,12 @@ Some flags will accumulate values when they are repeated, such as `--features`, These flags are not compatible with setting the flags from the platform: instead, all previous values will be removed and overwritten with the values from the platform. -As an example, given the following platform, the invocation `build --platforms=//:repeat_demo --features feature_a --features feature_b` will end up with the value of the +As an example, given the following platform, the invocation `build --platforms=//:repeat_demo +--features feature_a --features feature_b` will end up with the value of the `--feature` flag being `["feature_c", "feature_d"]`, removing the features set on the command line. -``` code - +``` platform( name = "repeat_demo", flags = [ @@ -226,13 +180,13 @@ in the future. The logic for setting the `remote_execution_platform` is as follows when there is a parent platform: -1. If `remote_execution_property` is not set on the child platform, the parent's - `remote_execution_properties` will be used. -2. If `remote_execution_property` is set on the child platform, and contains the - literal string {PARENT_REMOTE_EXECUTION_PROPERTIES}, that macro will be - replaced with the contents of the parent's `remote_execution_property` attribute. -3. If `remote_execution_property` is set on the child platform, and does not contain - the macro, the child's `remote_execution_property` will be used unchanged. +1. If `remote_execution_property` is not set on the child platform, the parent's + `remote_execution_properties` will be used. +2. If `remote_execution_property` is set on the child platform, and contains the + literal string \{PARENT\_REMOTE\_EXECUTION\_PROPERTIES\}, that macro will be + replaced with the contents of the parent's `remote_execution_property` attribute. +3. If `remote_execution_property` is set on the child platform, and does not contain + the macro, the child's `remote_execution_property` will be used unchanged. *Since `remote_execution_properties` is deprecated and will be phased out, mixing `remote_execution_properties` and `exec_properties` in the same @@ -242,8 +196,7 @@ Prefer to use `exec_properties` over the deprecated #### Example: Constraint Values -``` code - +``` platform( name = "parent", constraint_values = [ @@ -266,21 +219,20 @@ platform( In this example, the child platforms have the following properties: -- `child_a` has the constraint values `@platforms//os:linux` (inherited +* `child_a` has the constraint values `@platforms//os:linux` (inherited from the parent) and `@platforms//cpu:x86_64` (set directly on the platform). -- `child_b` inherits all constraint values from the parent, and doesn't set any of +* `child_b` inherits all constraint values from the parent, and doesn't set any of its own. #### Example: Execution properties -``` code - +``` platform( name = "parent", - exec_properties = { + exec_properties = \{ "k1": "v1", "k2": "v2", - }, + \}, ) platform( name = "child_a", @@ -289,121 +241,57 @@ platform( platform( name = "child_b", parents = [":parent"], - exec_properties = { + exec_properties = \{ "k1": "child" - } + \} ) platform( name = "child_c", parents = [":parent"], - exec_properties = { + exec_properties = \{ "k1": "" - } + \} ) platform( name = "child_d", parents = [":parent"], - exec_properties = { + exec_properties = \{ "k3": "v3" - } + \} ) ``` In this example, the child platforms have the following properties: -- `child_a` inherits the "exec_properties" of the parent and does not set its own. -- `child_b` inherits the parent's `exec_properties` and overrides the +* `child_a` inherits the "exec\_properties" of the parent and does not set its own. +* `child_b` inherits the parent's `exec_properties` and overrides the value of `k1`. Its `exec_properties` will be: - `{ "k1": "child", "k2": "v2" }`. -- `child_c` inherits the parent's `exec_properties` and unsets + `\{ "k1": "child", "k2": "v2" \}`. +* `child_c` inherits the parent's `exec_properties` and unsets `k1`. Its `exec_properties` will be: - `{ "k2": "v2" }`. -- `child_d` inherits the parent's `exec_properties` and adds a new + `\{ "k2": "v2" \}`. +* `child_d` inherits the parent's `exec_properties` and adds a new property. Its `exec_properties` will be: - `{ "k1": "v1", "k2": "v2", "k3": "v3" }`. + `\{ "k1": "v1", "k2": "v2", "k3": "v3" \}`. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="platform.name"><code>name</code></td> -<td><p><a href="/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="/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>.</p></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.flags"><code>flags</code></td> -<td><p>List of strings; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> -A list of flags that will be enabled when this platform is used as the target platform in -a configuration. Only flags that are part of the configuration can be set, such as those -that can be used in transitions, or the <code>--define</code> flag.</td> -</tr> -<tr> -<td id="platform.missing_toolchain_error"><code>missing_toolchain_error</code></td> -<td><p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>"For more information on platforms or toolchains see https://bazel.build/concepts/platforms-intro."</code></p> -A custom error message that is displayed when a mandatory toolchain requirement cannot be satisfied for this target platform. Intended to point to relevant documentation users can read to understand why their toolchains are misconfigured. -Not inherited from parent platforms.</td> -</tr> -<tr> -<td id="platform.parents"><code>parents</code></td> -<td><p>List of <a href="/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> -<tr> -<td id="platform.required_settings"><code>required_settings</code></td> -<td><p>List of <a href="/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 platform to be used as an execution platform during toolchain resolution. -Required settings are not inherited from parent platforms.</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `constraint_values` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` 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. Each `constraint_value` in this list must be for a different `constraint_setting`. For example, you cannot define a platform that requires the cpu architecture to be both `@platforms//cpu:x86_64` and `@platforms//cpu:arm`. | +| `exec_properties` | Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `\{\}` 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 [remote execution protocol](https://github.com/bazelbuild/remote-apis). This includes any data from the parent platform's `exec_properties` 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 `remote_execution_properties`. | +| `flags` | List of strings; [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` A list of flags that will be enabled when this platform is used as the target platform in a configuration. Only flags that are part of the configuration can be set, such as those that can be used in transitions, or the `--define` flag. | +| `missing_toolchain_error` | String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `"For more information on platforms or toolchains see https://bazel.build/concepts/platforms-intro."` A custom error message that is displayed when a mandatory toolchain requirement cannot be satisfied for this target platform. Intended to point to relevant documentation users can read to understand why their toolchains are misconfigured. Not inherited from parent platforms. | +| `parents` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` The label of a `platform` 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 [Platform Inheritance](#platform_inheritance) for details. | +| `remote_execution_properties` | String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `""` 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 [Platform Inheritance](#platform_inheritance) for details. | +| `required_settings` | List of [labels](./concepts/labels); default is `[]` A list of `config_setting`s that must be satisfied by the target configuration in order for this platform to be used as an execution platform during toolchain resolution. Required settings are not inherited from parent platforms. | ## toolchain -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ToolchainRule.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ToolchainRule.java) -``` rule-signature +``` toolchain(name, aspect_hints, deprecation, exec_compatible_with, features, licenses, package_metadata, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, use_target_platform_constraints, visibility) ``` @@ -414,78 +302,34 @@ details. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="toolchain.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</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>List of <a href="/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="/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="/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="/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="/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> -<tr> -<td id="toolchain.use_target_platform_constraints"><code>use_target_platform_constraints</code></td> -<td><p>Boolean; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>False</code></p> -If <code>True</code>, this toolchain behaves as if its <code>exec_compatible_with</code> and -<code>target_compatible_with</code> constraints are set to those of the current target -platform. <code>exec_compatible_with</code> and <code>target_compatible_with</code> must not -be set in that case.</td> -</tr> -</tbody> -</table> - -## toolchain_type - -<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/ToolchainType.java" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `exec_compatible_with` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` A list of `constraint_value`s that must be satisfied by an execution platform in order for this toolchain to be selected for a target building on that platform. | +| `target_compatible_with` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` A list of `constraint_value`s that must be satisfied by the target platform in order for this toolchain to be selected for a target building for that platform. | +| `target_settings` | List of [labels](./concepts/labels); default is `[]` A list of `config_setting`s that must be satisfied by the target configuration in order for this toolchain to be selected during toolchain resolution. | +| `toolchain` | [Name](./concepts/labels#target-names); required The target representing the actual tool or tool suite that is made available when this toolchain is selected. | +| `toolchain_type` | [Label](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); required The label of a `toolchain_type` target that represents the role that this toolchain serves. | +| `use_target_platform_constraints` | Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` If `True`, this toolchain behaves as if its `exec_compatible_with` and `target_compatible_with` constraints are set to those of the current target platform. `exec_compatible_with` and `target_compatible_with` must not be set in that case. | + +## toolchain\_type + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/ToolchainType.java) + +``` toolchain_type(name, aspect_hints, compatible_with, deprecation, features, no_match_error, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) ``` 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. -See the [Toolchains](/docs/toolchains) page for more details. +See the [Toolchains](./docs/toolchains) page for more details. #### Example This defines a toolchain type for a custom rule. -``` code - +``` toolchain_type( name = "bar_toolchain_type", ) @@ -493,37 +337,21 @@ toolchain_type( This can be used in a bzl file. -``` code - +``` bar_binary = rule( implementation = _bar_binary_impl, - attrs = { + attrs = \{ "srcs": attr.label_list(allow_files = True), ... # No `_compiler` attribute anymore. - }, + \}, toolchains = ["//bar_tools:toolchain_type"] ) ``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="toolchain_type.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="toolchain_type.no_match_error"><code>no_match_error</code></td> -<td><p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>""</code></p> -A custom error message to display when no matching toolchain is found for this type.</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `no_match_error` | String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `""` A custom error message to display when no matching toolchain is found for this type. | \ No newline at end of file diff --git a/reference/be/protocol-buffer.mdx b/reference/be/protocol-buffer.mdx index e195cb8..48095d3 100644 --- a/reference/be/protocol-buffer.mdx +++ b/reference/be/protocol-buffer.mdx @@ -2,91 +2,69 @@ title: 'protocol-buffer' --- -# Protocol Buffer Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} ## Rules -- [cc_proto_library](#cc_proto_library) -- [java_lite_proto_library](#java_lite_proto_library) -- [java_proto_library](#java_proto_library) -- [proto_library](#proto_library) -- [py_proto_library](#py_proto_library) -- [proto_lang_toolchain](#proto_lang_toolchain) -- [proto_toolchain](#proto_toolchain) +* [cc\_proto\_library](#cc_proto_library) +* [java\_lite\_proto\_library](#java_lite_proto_library) +* [java\_proto\_library](#java_proto_library) +* [proto\_library](#proto_library) +* [py\_proto\_library](#py_proto_library) +* [proto\_lang\_toolchain](#proto_lang_toolchain) +* [proto\_toolchain](#proto_toolchain) -## cc_proto_library +## cc\_proto\_library -<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_cc_proto_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_cc_proto_library.bzl) -``` rule-signature +``` cc_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` `cc_proto_library` generates C++ code from `.proto` files. -`deps` must point to [`proto_library `](protocol-buffer.html#proto_library) rules. +`deps` must point to [`proto_library`](protocol-buffer.html#proto_library) rules. Example: +``` +cc_library( + name = "lib", + deps = [":foo_cc_proto"], +) +cc_proto_library( + name = "foo_cc_proto", + deps = [":foo_proto"], +) + +proto_library( + name = "foo_proto", +) +``` - cc_library( - name = "lib", - deps = [":foo_cc_proto"], - ) +### Arguments - cc_proto_library( - name = "foo_cc_proto", - deps = [":foo_proto"], - ) +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of [`proto_library`](protocol-buffer.html#proto_library) rules to generate C++ code for. | - proto_library( - name = "foo_proto", - ) +## java\_lite\_proto\_library -### Arguments +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/java_lite_proto_library.bzl) -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="cc_proto_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="cc_proto_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> -rules to generate C++ code for.</td> -</tr> -</tbody> -</table> - -## java_lite_proto_library - -<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/java_lite_proto_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +``` java_lite_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` `java_lite_proto_library` generates Java code from `.proto` files. -`deps` must point to [`proto_library `](protocol-buffer.html#proto_library) rules. +`deps` must point to [`proto_library`](protocol-buffer.html#proto_library) rules. Example: -``` code - - +``` java_library( name = "lib", runtime_deps = [":foo"], @@ -104,44 +82,26 @@ proto_library( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_lite_proto_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_lite_proto_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> -rules to generate Java code for.</td> -</tr> -</tbody> -</table> - -## java_proto_library - -<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_java_proto_library_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of [`proto_library`](protocol-buffer.html#proto_library) rules to generate Java code for. | + +## java\_proto\_library + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_java_proto_library_rule.bzl) + +``` java_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` `java_proto_library` generates Java code from `.proto` files. -`deps` must point to [`proto_library `](protocol-buffer.html#proto_library) rules. +`deps` must point to [`proto_library`](protocol-buffer.html#proto_library) rules. Example: -``` code - - +``` java_library( name = "lib", runtime_deps = [":foo_java_proto"], @@ -159,32 +119,16 @@ proto_library( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="java_proto_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="java_proto_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of <a href="protocol-buffer.html#proto_library"><code>proto_library</code></a> -rules to generate Java code for.</td> -</tr> -</tbody> -</table> - -## proto_library - -<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_library_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of [`proto_library`](protocol-buffer.html#proto_library) rules to generate Java code for. | + +## proto\_library + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_library_rule.bzl) + +``` proto_library(name, deps, srcs, data, allow_exports, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exports, features, import_prefix, licenses, option_deps, package_metadata, restricted_to, strip_import_prefix, tags, target_compatible_with, testonly, toolchains, visibility) ``` @@ -197,7 +141,7 @@ When compiled on the command-line, a `proto_library` creates a file named `foo-descriptor-set.proto.bin`, which is the descriptor set for the messages the rule srcs. The file is a serialized `FileDescriptorSet`, which is described in -<https://developers.google.com/protocol-buffers/docs/techniques#self-description>. +[https://developers.google.com/protocol-buffers/docs/techniques#self-description](https://developers.google.com/protocol-buffers/docs/techniques#self-description). It only contains information about the `.proto` files directly mentioned by a `proto_library` rule; the collection of transitive @@ -207,172 +151,88 @@ See documentation in `proto_info.bzl`. Recommended code organization: -- One `proto_library` rule per `.proto` file. -- A file named `foo.proto` will be in a rule named `foo_proto`, - which is located in the same package. -- A `[language]_proto_library` that wraps a `proto_library` - named `foo_proto` should be called `foo_[language]_proto`, - and be located in the same package. +* One `proto_library` rule per `.proto` file.* A file named `foo.proto` will be in a rule named `foo_proto`, + which is located in the same package.* A `[language]_proto_library` that wraps a `proto_library` + named `foo_proto` should be called `foo_[language]_proto`, + and be located in the same package. ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="proto_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="proto_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other <code>proto_library</code> rules that the target depends upon. -A <code>proto_library</code> may only depend on other <code>proto_library</code> -targets. It may not depend on language-specific libraries.</td> -</tr> -<tr> -<td id="proto_library.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of <code>.proto</code> and <code>.protodevel</code> files that are -processed to create the target. This is usually a non empty list. One usecase -where <code>srcs</code> can be empty is an <em>alias-library</em>. This is a -proto_library rule having one or more other proto_library in <code>deps</code>. -This pattern can be used to e.g. export a public api under a persistent name.</td> -</tr> -<tr> -<td id="proto_library.allow_exports"><code>allow_exports</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -An optional allowlist that prevents proto library to be reexported or used in -lang_proto_library that is not in one of the listed packages.</td> -</tr> -<tr> -<td id="proto_library.exports"><code>exports</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -List of proto_library targets that can be referenced via "import public" in the -proto source. -It's an error if you use "import public" but do not list the corresponding library -in the exports attribute. -Note that you have list the library both in deps and exports since not all -lang_proto_library implementations have been changed yet.</td> -</tr> -<tr> -<td id="proto_library.import_prefix"><code>import_prefix</code></td> -<td><p>String; default is <code>""</code></p> -The prefix to add to the paths of the .proto files in this rule. -<p>When set, the .proto source files in the <code>srcs</code> attribute of this rule are -accessible at is the value of this attribute prepended to their repository-relative path.</p> -<p>The prefix in the <code>strip_import_prefix</code> attribute is removed before this -prefix is added.</p></td> -</tr> -<tr> -<td id="proto_library.option_deps"><code>option_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of other <code>proto_library</code> rules that the target depends upon for options only. -A <code>proto_library</code> may only depend on other <code>proto_library</code> -targets. It may not depend on language-specific libraries.</td> -</tr> -<tr> -<td id="proto_library.strip_import_prefix"><code>strip_import_prefix</code></td> -<td><p>String; default is <code>"/"</code></p> -The prefix to strip from the paths of the .proto files in this rule. -<p>When set, .proto source files in the <code>srcs</code> attribute of this rule are -accessible at their path with this prefix cut off.</p> -<p>If it's a relative path (not starting with a slash), it's taken as a package-relative -one. If it's an absolute one, it's understood as a repository-relative path.</p> -<p>The prefix in the <code>import_prefix</code> attribute is added after this prefix is -stripped.</p></td> -</tr> -</tbody> -</table> - -## py_proto_library - -<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/py_proto_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other `proto_library` rules that the target depends upon. A `proto_library` may only depend on other `proto_library` targets. It may not depend on language-specific libraries. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of `.proto` and `.protodevel` files that are processed to create the target. This is usually a non empty list. One usecase where `srcs` can be empty is an *alias-library*. This is a proto\_library rule having one or more other proto\_library in `deps`. This pattern can be used to e.g. export a public api under a persistent name. | +| `allow_exports` | [Label](./concepts/labels); default is `None` An optional allowlist that prevents proto library to be reexported or used in lang\_proto\_library that is not in one of the listed packages. | +| `exports` | List of [labels](./concepts/labels); default is `[]` List of proto\_library targets that can be referenced via "import public" in the proto source. It's an error if you use "import public" but do not list the corresponding library in the exports attribute. Note that you have list the library both in deps and exports since not all lang\_proto\_library implementations have been changed yet. | +| `import_prefix` | String; default is `""` The prefix to add to the paths of the .proto files in this rule. When set, the .proto source files in the `srcs` attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the `strip_import_prefix` attribute is removed before this prefix is added. | +| `option_deps` | List of [labels](./concepts/labels); default is `[]` The list of other `proto_library` rules that the target depends upon for options only. A `proto_library` may only depend on other `proto_library` targets. It may not depend on language-specific libraries. | +| `strip_import_prefix` | String; default is `"/"` The prefix to strip from the paths of the .proto files in this rule. When set, .proto source files in the `srcs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path (not starting with a slash), it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `import_prefix` attribute is added after this prefix is stripped. | + +## py\_proto\_library + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/py_proto_library.bzl) + +``` py_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` -Use \`py_proto_library\` to generate Python libraries from \`.proto\` files. -The convention is to name the \`py_proto_library\` rule \`foo_py_pb2\`, -when it is wrapping \`proto_library\` rule \`foo_proto\`. -\`deps\` must point to a \`proto_library\` rule. +Use `py\_proto\_library` to generate Python libraries from `.proto` files. +The convention is to name the `py\_proto\_library` rule `foo\_py\_pb2`, +when it is wrapping `proto\_library` rule `foo\_proto`. +`deps` must point to a `proto\_library` rule. Example: -\`\`\`starlark -py_library( +```starlark +py\_library( name = "lib", -deps = \[":foo_py_pb2"\], +deps = [":foo\_py\_pb2"], ) -py_proto_library( -name = "foo_py_pb2", -deps = \[":foo_proto"\], +py\_proto\_library( +name = "foo\_py\_pb2", +deps = [":foo\_proto"], ) -proto_library( -name = "foo_proto", -srcs = \["foo.proto"\], +proto\_library( +name = "foo\_proto", +srcs = ["foo.proto"], ) -\`\`\` +``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="py_proto_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="py_proto_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of `proto_library` rules to generate Python libraries for. -Usually this is just the one target: the proto library of interest. -It can be any target providing `ProtoInfo`.</td> -</tr> -</tbody> -</table> - -## proto_lang_toolchain - -<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_lang_toolchain_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of `proto\_library` rules to generate Python libraries for. Usually this is just the one target: the proto library of interest. It can be any target providing `ProtoInfo`. | + +## proto\_lang\_toolchain + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_lang_toolchain_rule.bzl) + +``` proto_lang_toolchain(name, allowlist_different_package, aspect_hints, blacklisted_protos, command_line, compatible_with, denylisted_protos, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, mnemonic, output_files, package_metadata, plugin, plugin_format_flag, progress_message, protoc_minimal_do_not_use, restricted_to, runtime, tags, target_compatible_with, testonly, toolchain_type, toolchains, visibility) ``` -If using Bazel, please load the rule from -<https://github.com/bazelbuild/rules_proto>. +If using Bazel, please load the rule from [https://github.com/bazelbuild/rules_proto](https://github.com/bazelbuild/rules_proto). -Specifies how a LANG_proto_library rule (e.g., `java_proto_library`) should invoke the +Specifies how a LANG\_proto\_library rule (e.g., `java_proto_library`) should invoke the proto-compiler. -Some LANG_proto_library rules allow specifying which toolchain to use using command-line flags; +Some LANG\_proto\_library rules allow specifying which toolchain to use using command-line flags; consult their documentation. Normally you should not write those kind of rules unless you want to tune your Java compiler. -There's no compiler. The proto-compiler is taken from the proto_library rule we attach to. It is +There's no compiler. The proto-compiler is taken from the proto\_library rule we attach to. It is passed as a command-line flag to Blaze. -Several features require a proto-compiler to be invoked on the proto_library rule itself. -It's beneficial to enforce the compiler that LANG_proto_library uses is the same as the one +Several features require a proto-compiler to be invoked on the proto\_library rule itself. +It's beneficial to enforce the compiler that LANG\_proto\_library uses is the same as the one `proto_library` does. #### Examples A simple example would be: -``` lang-starlark - +``` proto_lang_toolchain( name = "javalite_toolchain", command_line = "--javalite_out=shared,immutable:$(OUT)", @@ -383,136 +243,37 @@ proto_lang_toolchain( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="proto_lang_toolchain.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="proto_lang_toolchain.allowlist_different_package"><code>allowlist_different_package</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> -</tr> -<tr> -<td id="proto_lang_toolchain.blacklisted_protos"><code>blacklisted_protos</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Deprecated. Alias for <code>denylisted_protos</code>. Will be removed in a future release.</td> -</tr> -<tr> -<td id="proto_lang_toolchain.command_line"><code>command_line</code></td> -<td><p>String; required</p> -This value will be passed to proto-compiler to generate the code. Only include the parts -specific to this code-generator/plugin (e.g., do not include -I parameters) -<ul> -<li><code>$(OUT)</code> is LANG_proto_library-specific. The rules are expected to define -how they interpret this variable. For Java, for example, $(OUT) will be replaced with -the src-jar filename to create.</li> -</ul></td> -</tr> -<tr> -<td id="proto_lang_toolchain.denylisted_protos"><code>denylisted_protos</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -No code will be generated for files in the <code>srcs</code> attribute of -<code>denylisted_protos</code>. -This is used for .proto files that are already linked into proto runtimes, such as -<code>any.proto</code>.</td> -</tr> -<tr> -<td id="proto_lang_toolchain.mnemonic"><code>mnemonic</code></td> -<td><p>String; default is <code>"GenProto"</code></p> -This value will be set as the mnemonic on protoc action.</td> -</tr> -<tr> -<td id="proto_lang_toolchain.output_files"><code>output_files</code></td> -<td><p>String; default is <code>"legacy"</code></p> -Controls how <code>$(OUT)</code> in <code>command_line</code> is formatted, either by -a path to a single file or output directory in case of multiple files. -Possible values are: "single", "multiple".</td> -</tr> -<tr> -<td id="proto_lang_toolchain.plugin"><code>plugin</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -If provided, will be made available to the action that calls the proto-compiler, and will be -passed to the proto-compiler: -<code>--plugin=protoc-gen-PLUGIN=<executable>.</code></td> -</tr> -<tr> -<td id="proto_lang_toolchain.plugin_format_flag"><code>plugin_format_flag</code></td> -<td><p>String; default is <code>""</code></p> -If provided, this value will be passed to proto-compiler to use the plugin. -The value must contain a single %s which is replaced with plugin executable. -<code>--plugin=protoc-gen-PLUGIN=<executable>.</code></td> -</tr> -<tr> -<td id="proto_lang_toolchain.progress_message"><code>progress_message</code></td> -<td><p>String; default is <code>"Generating proto_library %{label}"</code></p> -This value will be set as the progress message on protoc action.</td> -</tr> -<tr> -<td id="proto_lang_toolchain.protoc_minimal_do_not_use"><code>protoc_minimal_do_not_use</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> -</tr> -<tr> -<td id="proto_lang_toolchain.runtime"><code>runtime</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -A language-specific library that the generated code is compiled against. -The exact behavior is LANG_proto_library-specific. -Java, for example, should compile against the runtime.</td> -</tr> -<tr> -<td id="proto_lang_toolchain.toolchain_type"><code>toolchain_type</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> -</tr> -</tbody> -</table> - -## proto_toolchain - -<a href="https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_toolchain_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `allowlist_different_package` | [Label](./concepts/labels); default is `None` | +| `blacklisted_protos` | List of [labels](./concepts/labels); default is `[]` Deprecated. Alias for `denylisted_protos`. Will be removed in a future release. | +| `command_line` | String; required This value will be passed to proto-compiler to generate the code. Only include the parts specific to this code-generator/plugin (e.g., do not include -I parameters) * `$(OUT)` is LANG\_proto\_library-specific. The rules are expected to define how they interpret this variable. For Java, for example, $(OUT) will be replaced with the src-jar filename to create. | +| `denylisted_protos` | List of [labels](./concepts/labels); default is `[]` No code will be generated for files in the `srcs` attribute of `denylisted_protos`. This is used for .proto files that are already linked into proto runtimes, such as `any.proto`. | +| `mnemonic` | String; default is `"GenProto"` This value will be set as the mnemonic on protoc action. | +| `output_files` | String; default is `"legacy"` Controls how `$(OUT)` in `command_line` is formatted, either by a path to a single file or output directory in case of multiple files. Possible values are: "single", "multiple". | +| `plugin` | [Label](./concepts/labels); default is `None` If provided, will be made available to the action that calls the proto-compiler, and will be passed to the proto-compiler: `--plugin=protoc-gen-PLUGIN=<executable>.` | +| `plugin_format_flag` | String; default is `""` If provided, this value will be passed to proto-compiler to use the plugin. The value must contain a single %s which is replaced with plugin executable. `--plugin=protoc-gen-PLUGIN=<executable>.` | +| `progress_message` | String; default is `"Generating proto_library %\{label\}"` This value will be set as the progress message on protoc action. | +| `protoc_minimal_do_not_use` | [Label](./concepts/labels); default is `None` | +| `runtime` | [Label](./concepts/labels); default is `None` A language-specific library that the generated code is compiled against. The exact behavior is LANG\_proto\_library-specific. Java, for example, should compile against the runtime. | +| `toolchain_type` | [Label](./concepts/labels); default is `None` | + +## proto\_toolchain + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_toolchain_rule.bzl) + +``` proto_toolchain(name, aspect_hints, command_line, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, mnemonic, output_files, package_metadata, progress_message, proto_compiler, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="proto_toolchain.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="proto_toolchain.command_line"><code>command_line</code></td> -<td><p>String; default is <code>"--descriptor_set_out=%s"</code></p></td> -</tr> -<tr> -<td id="proto_toolchain.mnemonic"><code>mnemonic</code></td> -<td><p>String; default is <code>"GenProtoDescriptorSet"</code></p></td> -</tr> -<tr> -<td id="proto_toolchain.output_files"><code>output_files</code></td> -<td><p>String; default is <code>"single"</code></p></td> -</tr> -<tr> -<td id="proto_toolchain.progress_message"><code>progress_message</code></td> -<td><p>String; default is <code>"Generating Descriptor Set proto_library %{label}"</code></p></td> -</tr> -<tr> -<td id="proto_toolchain.proto_compiler"><code>proto_compiler</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p></td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `command_line` | String; default is `"--descriptor_set_out=%s"` | +| `mnemonic` | String; default is `"GenProtoDescriptorSet"` | +| `output_files` | String; default is `"single"` | +| `progress_message` | String; default is `"Generating Descriptor Set proto_library %\{label\}"` | +| `proto_compiler` | [Label](./concepts/labels); default is `None` | \ No newline at end of file diff --git a/reference/be/python.mdx b/reference/be/python.mdx index 44fd237..47b4a30 100644 --- a/reference/be/python.mdx +++ b/reference/be/python.mdx @@ -2,266 +2,52 @@ title: 'python' --- -# Python Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} ## Rules -- [py_binary](#py_binary) -- [py_library](#py_library) -- [py_test](#py_test) -- [py_runtime](#py_runtime) +* [py\_binary](#py_binary) +* [py\_library](#py_library) +* [py\_test](#py_test) +* [py\_runtime](#py_runtime) -## py_binary +## py\_binary -<a href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_binary_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_binary_rule.bzl) -``` rule-signature +``` py_binary(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, distribs, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, imports, interpreter_args, legacy_create_init, licenses, main, main_module, output_licenses, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, pyi_deps, pyi_srcs, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility) ``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="py_binary.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="py_binary.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -List of additional libraries to be linked in to the target. -See comments about -the [`deps` attribute typically defined by -rules](https://bazel.build/reference/be/common-definitions#typical-attributes). -These are typically `py_library` rules. -Targets that only provide data files used at runtime belong in the `data` -attribute. -:::{note} -The order of this list can matter because it affects the order that information -from dependencies is merged in, which can be relevant depending on the ordering -mode of depsets that are merged. -* {obj}`PyInfo.site_packages_symlinks` uses topological ordering. -See {obj}`PyInfo` for more information about the ordering of its depsets and -how its fields are merged. -:::</td> -</tr> -<tr> -<td id="py_binary.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of Python source files that are processed to create the target. This -includes all your checked-in code and may include generated source files. The -`.py` files belong in `srcs` and library targets belong in `deps`. Other binary -files that may be needed at run time belong in `data`.</td> -</tr> -<tr> -<td id="py_binary.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files need by this library at runtime. See comments about -the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). -There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. -This is because Python has a concept of runtime resources.</td> -</tr> -<tr> -<td id="py_binary.distribs"><code>distribs</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="py_binary.imports"><code>imports</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of import directories to be added to the PYTHONPATH. -Subject to "Make variable" substitution. These import directories will be added -for this rule and all rules that depend on it (note: not the rules this rule -depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules -that depend on this rule. The strings are repo-runfiles-root relative, -Absolute paths (paths that start with `/`) and paths that references a path -above the execution root are not allowed and will result in an error.</td> -</tr> -<tr> -<td id="py_binary.interpreter_args"><code>interpreter_args</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Arguments that are only applicable to the interpreter. -The args an interpreter supports are specific to the interpreter. For -CPython, see https://docs.python.org/3/using/cmdline.html. -:::{note} -Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise. -::: -:::{seealso} -The {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable -::: -:::{versionadded} 1.3.0 -:::</td> -</tr> -<tr> -<td id="py_binary.legacy_create_init"><code>legacy_create_init</code></td> -<td><p>Integer; default is <code>-1</code></p> -Whether to implicitly create empty `__init__.py` files in the runfiles tree. -These are created in every directory containing Python source code or shared -libraries, and every parent directory of those directories, excluding the repo -root directory. The default, `-1` (auto), means true unless -`--incompatible_default_to_explicit_init_py` is used. If false, the user is -responsible for creating (possibly empty) `__init__.py` files and adding them to -the `srcs` of Python targets as required.</td> -</tr> -<tr> -<td id="py_binary.main"><code>main</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Optional; the name of the source file that is the main entry point of the -application. This file must also be listed in `srcs`. If left unspecified, -`name`, with `.py` appended, is used instead. If `name` does not match any -filename in `srcs`, `main` must be specified. -This is mutually exclusive with {obj}`main_module`.</td> -</tr> -<tr> -<td id="py_binary.main_module"><code>main_module</code></td> -<td><p>String; default is <code>""</code></p> -Module name to execute as the main program. -When set, `srcs` is not required, and it is assumed the module is -provided by a dependency. -See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more -information about running modules as the main program. -This is mutually exclusive with {obj}`main`. -:::{versionadded} 1.3.0 -:::</td> -</tr> -<tr> -<td id="py_binary.precompile"><code>precompile</code></td> -<td><p>String; default is <code>"inherit"</code></p> -Whether py source files **for this target** should be precompiled. -Values: -* `inherit`: Allow the downstream binary decide if precompiled files are used. -* `enabled`: Compile Python source files at build time. -* `disabled`: Don't compile Python source files at build time. -:::{seealso} -* The {flag}`--precompile` flag, which can override this attribute in some cases -and will affect all targets when building. -* The {obj}`pyc_collection` attribute for transitively enabling precompiling on -a per-target basis. -* The [Precompiling](precompiling) docs for a guide about using precompiling. -:::</td> -</tr> -<tr> -<td id="py_binary.precompile_invalidation_mode"><code>precompile_invalidation_mode</code></td> -<td><p>String; default is <code>"auto"</code></p> -How precompiled files should be verified to be up-to-date with their associated -source files. Possible values are: -* `auto`: The effective value will be automatically determined by other build -settings. -* `checked_hash`: Use the pyc file if the hash of the source file matches the hash -recorded in the pyc file. This is most useful when working with code that -you may modify. -* `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against -the source file. This is most useful when the code won't be modified. -For more information on pyc invalidation modes, see -https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode</td> -</tr> -<tr> -<td id="py_binary.precompile_optimize_level"><code>precompile_optimize_level</code></td> -<td><p>Integer; default is <code>0</code></p> -The optimization level for precompiled files. -For more information about optimization levels, see the `compile()` function's -`optimize` arg docs at https://docs.python.org/3/library/functions.html#compile -NOTE: The value `-1` means "current interpreter", which will be the interpreter -used _at build time when pycs are generated_, not the interpreter used at -runtime when the code actually runs.</td> -</tr> -<tr> -<td id="py_binary.precompile_source_retention"><code>precompile_source_retention</code></td> -<td><p>String; default is <code>"inherit"</code></p> -Determines, when a source file is compiled, if the source file is kept -in the resulting output or not. Valid values are: -* `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. -* `keep_source`: Include the original Python source. -* `omit_source`: Don't include the original py source.</td> -</tr> -<tr> -<td id="py_binary.pyc_collection"><code>pyc_collection</code></td> -<td><p>String; default is <code>"inherit"</code></p> -Determines whether pyc files from dependencies should be manually included. -Valid values are: -* `inherit`: Inherit the value from {flag}`--precompile`. -* `include_pyc`: Add implicitly generated pyc files from dependencies. i.e. -pyc files for targets that specify {attr}`precompile="inherit"`. -* `disabled`: Don't add implicitly generated pyc files. Note that -pyc files may still come from dependencies that enable precompiling at the -target level.</td> -</tr> -<tr> -<td id="py_binary.pyi_deps"><code>pyi_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Dependencies providing type definitions the library needs. -These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. -These are build-time only dependencies and not included as part of a runnable -program (packaging rules may include them, however). -:::{versionadded} 1.1.0 -:::</td> -</tr> -<tr> -<td id="py_binary.pyi_srcs"><code>pyi_srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Type definition files for the library. -These are typically `.pyi` files, but other file types for type-checker specific -formats are allowed. These files are build-time only dependencies and not included -as part of a runnable program (packaging rules may include them, however). -:::{versionadded} 1.1.0 -:::</td> -</tr> -<tr> -<td id="py_binary.python_version"><code>python_version</code></td> -<td><p>String; default is <code>""</code></p> -The Python version this target should use. -The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or -unspecified, the incoming configuration's {obj}`--python_version` flag is -inherited. For backwards compatibility, the values `PY2` and `PY3` are -accepted, but treated as an empty/unspecified value. -:::{note} -In order for the requested version to be used, there must be a -toolchain configured to match the Python version. If there isn't, then it -may be silently ignored, or an error may occur, depending on the toolchain -configuration. -::: -:::{versionchanged} 1.1.0 -This attribute was changed from only accepting `PY2` and `PY3` values to -accepting arbitrary Python versions. -:::</td> -</tr> -<tr> -<td id="py_binary.srcs_version"><code>srcs_version</code></td> -<td><p>String; default is <code>""</code></p> -Defunct, unused, does nothing.</td> -</tr> -<tr> -<td id="py_binary.stamp"><code>stamp</code></td> -<td><p>Integer; default is <code>-1</code></p> -Whether to encode build information into the binary. Possible values: -* `stamp = 1`: Always stamp the build information into the binary, even in -`--nostamp` builds. **This setting should be avoided**, since it potentially kills -remote caching for the binary and any downstream actions that depend on it. -* `stamp = 0`: Always replace build information by constant values. This gives -good build result caching. -* `stamp = -1`: Embedding of build information is controlled by the -`--[no]stamp` flag. -Stamped binaries are not rebuilt unless their dependencies change. -WARNING: Stamping can harm build performance by reducing cache hits and should -be avoided if possible.</td> -</tr> -</tbody> -</table> - -## py_library +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py\_library` rules. Targets that only provide data files used at runtime belong in the `data` attribute. :::\{note\} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. \* \{obj\}`PyInfo.site\_packages\_symlinks` uses topological ordering. See \{obj\}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. ::: | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of Python source files that are processed to create the target. This includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary files that may be needed at run time belong in `data`. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). There is no `py\_embed\_data` like there is `cc\_embed\_data` and `go\_embed\_data`. This is because Python has a concept of runtime resources. | +| `distribs` | List of strings; default is `[]` | +| `imports` | List of strings; default is `[]` List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py\_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, Absolute paths (paths that start with `/`) and paths that references a path above the execution root are not allowed and will result in an error. | +| `interpreter_args` | List of strings; default is `[]` Arguments that are only applicable to the interpreter. The args an interpreter supports are specific to the interpreter. For CPython, see https://docs.python.org/3/using/cmdline.html. :::\{note\} Only supported for \{obj\}`--bootstrap\_impl=script`. Ignored otherwise. ::: :::\{seealso\} The \{any\}`RULES\_PYTHON\_ADDITIONAL\_INTERPRETER\_ARGS` environment variable ::: :::\{versionadded\} 1.3.0 ::: | +| `legacy_create_init` | Integer; default is `-1` Whether to implicitly create empty `\_\_init\_\_.py` files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default, `-1` (auto), means true unless `--incompatible\_default\_to\_explicit\_init\_py` is used. If false, the user is responsible for creating (possibly empty) `\_\_init\_\_.py` files and adding them to the `srcs` of Python targets as required. | +| `main` | [Label](./concepts/labels); default is `None` Optional; the name of the source file that is the main entry point of the application. This file must also be listed in `srcs`. If left unspecified, `name`, with `.py` appended, is used instead. If `name` does not match any filename in `srcs`, `main` must be specified. This is mutually exclusive with \{obj\}`main\_module`. | +| `main_module` | String; default is `""` Module name to execute as the main program. When set, `srcs` is not required, and it is assumed the module is provided by a dependency. See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more information about running modules as the main program. This is mutually exclusive with \{obj\}`main`. :::\{versionadded\} 1.3.0 ::: | +| `precompile` | String; default is `"inherit"` Whether py source files \*\*for this target\*\* should be precompiled. Values: \* `inherit`: Allow the downstream binary decide if precompiled files are used. \* `enabled`: Compile Python source files at build time. \* `disabled`: Don't compile Python source files at build time. :::\{seealso\} \* The \{flag\}`--precompile` flag, which can override this attribute in some cases and will affect all targets when building. \* The \{obj\}`pyc\_collection` attribute for transitively enabling precompiling on a per-target basis. \* The [Precompiling](precompiling) docs for a guide about using precompiling. ::: | +| `precompile_invalidation_mode` | String; default is `"auto"` How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: \* `auto`: The effective value will be automatically determined by other build settings. \* `checked\_hash`: Use the pyc file if the hash of the source file matches the hash recorded in the pyc file. This is most useful when working with code that you may modify. \* `unchecked\_hash`: Always use the pyc file; don't check the pyc's hash against the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode | +| `precompile_optimize_level` | Integer; default is `0` The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile NOTE: The value `-1` means "current interpreter", which will be the interpreter used \_at build time when pycs are generated\_, not the interpreter used at runtime when the code actually runs. | +| `precompile_source_retention` | String; default is `"inherit"` Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: \* `inherit`: Inherit the value from the \{flag\}`--precompile\_source\_retention` flag. \* `keep\_source`: Include the original Python source. \* `omit\_source`: Don't include the original py source. | +| `pyc_collection` | String; default is `"inherit"` Determines whether pyc files from dependencies should be manually included. Valid values are: \* `inherit`: Inherit the value from \{flag\}`--precompile`. \* `include\_pyc`: Add implicitly generated pyc files from dependencies. i.e. pyc files for targets that specify \{attr\}`precompile="inherit"`. \* `disabled`: Don't add implicitly generated pyc files. Note that pyc files may still come from dependencies that enable precompiling at the target level. | +| `pyi_deps` | List of [labels](./concepts/labels); default is `[]` Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE\_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | +| `pyi_srcs` | List of [labels](./concepts/labels); default is `[]` Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | +| `python_version` | String; default is `""` The Python version this target should use. The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or unspecified, the incoming configuration's \{obj\}`--python\_version` flag is inherited. For backwards compatibility, the values `PY2` and `PY3` are accepted, but treated as an empty/unspecified value. :::\{note\} In order for the requested version to be used, there must be a toolchain configured to match the Python version. If there isn't, then it may be silently ignored, or an error may occur, depending on the toolchain configuration. ::: :::\{versionchanged\} 1.1.0 This attribute was changed from only accepting `PY2` and `PY3` values to accepting arbitrary Python versions. ::: | +| `srcs_version` | String; default is `""` Defunct, unused, does nothing. | +| `stamp` | Integer; default is `-1` Whether to encode build information into the binary. Possible values: \* `stamp = 1`: Always stamp the build information into the binary, even in `--nostamp` builds. \*\*This setting should be avoided\*\*, since it potentially kills remote caching for the binary and any downstream actions that depend on it. \* `stamp = 0`: Always replace build information by constant values. This gives good build result caching. \* `stamp = -1`: Embedding of build information is controlled by the `--[no]stamp` flag. Stamped binaries are not rebuilt unless their dependencies change. WARNING: Stamping can harm build performance by reducing cache hits and should be avoided if possible. | + +## py\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_library_rule.bzl) -<a href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_library_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +``` py_library(name, deps, srcs, data, aspect_hints, compatible_with, deprecation, distribs, exec_compatible_with, exec_group_compatible_with, exec_properties, experimental_venvs_site_packages, features, imports, licenses, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyi_deps, pyi_srcs, restricted_to, srcs_version, tags, target_compatible_with, testonly, toolchains, visibility) ``` @@ -272,438 +58,72 @@ Default outputs: NOTE: Precompilation affects which of the default outputs are included in the resulting runfiles. See the precompile-related attributes and flags for more information. -:::{versionchanged} 0.37.0 +:::\{versionchanged\} 0.37.0 Source files are no longer added to the runfiles directly. ::: ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="py_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="py_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -List of additional libraries to be linked in to the target. -See comments about -the [`deps` attribute typically defined by -rules](https://bazel.build/reference/be/common-definitions#typical-attributes). -These are typically `py_library` rules. -Targets that only provide data files used at runtime belong in the `data` -attribute. -:::{note} -The order of this list can matter because it affects the order that information -from dependencies is merged in, which can be relevant depending on the ordering -mode of depsets that are merged. -* {obj}`PyInfo.site_packages_symlinks` uses topological ordering. -See {obj}`PyInfo` for more information about the ordering of its depsets and -how its fields are merged. -:::</td> -</tr> -<tr> -<td id="py_library.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of Python source files that are processed to create the target. This -includes all your checked-in code and may include generated source files. The -`.py` files belong in `srcs` and library targets belong in `deps`. Other binary -files that may be needed at run time belong in `data`.</td> -</tr> -<tr> -<td id="py_library.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files need by this library at runtime. See comments about -the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). -There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. -This is because Python has a concept of runtime resources.</td> -</tr> -<tr> -<td id="py_library.distribs"><code>distribs</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="py_library.experimental_venvs_site_packages"><code>experimental_venvs_site_packages</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -**INTERNAL ATTRIBUTE. SHOULD ONLY BE SET BY rules_python-INTERNAL CODE.** -:::{include} /_includes/experimental_api.md -::: -A flag that decides whether the library should treat its sources as a -site-packages layout. -When the flag is `yes`, then the `srcs` files are treated as a site-packages -layout that is relative to the `imports` attribute. The `imports` attribute -can have only a single element. It is a repo-relative runfiles path. -For example, in the `my/pkg/BUILD.bazel` file, given -`srcs=["site-packages/foo/bar.py"]`, specifying -`imports=["my/pkg/site-packages"]` means `foo/bar.py` is the file path -under the binary's venv site-packages directory that should be made available (i.e. -`import foo.bar` will work). -`__init__.py` files are treated specially to provide basic support for [implicit -namespace packages]( -https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages). -However, the *content* of the files cannot be taken into account, merely their -presence or absense. Stated another way: [pkgutil-style namespace packages]( -https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages) -won't be understood as namespace packages; they'll be seen as regular packages. This will -likely lead to conflicts with other targets that contribute to the namespace. -:::{tip} -This attributes populates {obj}`PyInfo.site_packages_symlinks`, which is -a topologically ordered depset. This means dependencies closer and earlier -to a consumer have precedence. See {obj}`PyInfo.site_packages_symlinks` for -more information. -::: -:::{versionadded} 1.4.0 -:::</td> -</tr> -<tr> -<td id="py_library.imports"><code>imports</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of import directories to be added to the PYTHONPATH. -Subject to "Make variable" substitution. These import directories will be added -for this rule and all rules that depend on it (note: not the rules this rule -depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules -that depend on this rule. The strings are repo-runfiles-root relative, -Absolute paths (paths that start with `/`) and paths that references a path -above the execution root are not allowed and will result in an error.</td> -</tr> -<tr> -<td id="py_library.precompile"><code>precompile</code></td> -<td><p>String; default is <code>"inherit"</code></p> -Whether py source files **for this target** should be precompiled. -Values: -* `inherit`: Allow the downstream binary decide if precompiled files are used. -* `enabled`: Compile Python source files at build time. -* `disabled`: Don't compile Python source files at build time. -:::{seealso} -* The {flag}`--precompile` flag, which can override this attribute in some cases -and will affect all targets when building. -* The {obj}`pyc_collection` attribute for transitively enabling precompiling on -a per-target basis. -* The [Precompiling](precompiling) docs for a guide about using precompiling. -:::</td> -</tr> -<tr> -<td id="py_library.precompile_invalidation_mode"><code>precompile_invalidation_mode</code></td> -<td><p>String; default is <code>"auto"</code></p> -How precompiled files should be verified to be up-to-date with their associated -source files. Possible values are: -* `auto`: The effective value will be automatically determined by other build -settings. -* `checked_hash`: Use the pyc file if the hash of the source file matches the hash -recorded in the pyc file. This is most useful when working with code that -you may modify. -* `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against -the source file. This is most useful when the code won't be modified. -For more information on pyc invalidation modes, see -https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode</td> -</tr> -<tr> -<td id="py_library.precompile_optimize_level"><code>precompile_optimize_level</code></td> -<td><p>Integer; default is <code>0</code></p> -The optimization level for precompiled files. -For more information about optimization levels, see the `compile()` function's -`optimize` arg docs at https://docs.python.org/3/library/functions.html#compile -NOTE: The value `-1` means "current interpreter", which will be the interpreter -used _at build time when pycs are generated_, not the interpreter used at -runtime when the code actually runs.</td> -</tr> -<tr> -<td id="py_library.precompile_source_retention"><code>precompile_source_retention</code></td> -<td><p>String; default is <code>"inherit"</code></p> -Determines, when a source file is compiled, if the source file is kept -in the resulting output or not. Valid values are: -* `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. -* `keep_source`: Include the original Python source. -* `omit_source`: Don't include the original py source.</td> -</tr> -<tr> -<td id="py_library.pyi_deps"><code>pyi_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Dependencies providing type definitions the library needs. -These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. -These are build-time only dependencies and not included as part of a runnable -program (packaging rules may include them, however). -:::{versionadded} 1.1.0 -:::</td> -</tr> -<tr> -<td id="py_library.pyi_srcs"><code>pyi_srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Type definition files for the library. -These are typically `.pyi` files, but other file types for type-checker specific -formats are allowed. These files are build-time only dependencies and not included -as part of a runnable program (packaging rules may include them, however). -:::{versionadded} 1.1.0 -:::</td> -</tr> -<tr> -<td id="py_library.srcs_version"><code>srcs_version</code></td> -<td><p>String; default is <code>""</code></p> -Defunct, unused, does nothing.</td> -</tr> -</tbody> -</table> - -## py_test - -<a href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_test_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py\_library` rules. Targets that only provide data files used at runtime belong in the `data` attribute. :::\{note\} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. \* \{obj\}`PyInfo.site\_packages\_symlinks` uses topological ordering. See \{obj\}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. ::: | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of Python source files that are processed to create the target. This includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary files that may be needed at run time belong in `data`. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). There is no `py\_embed\_data` like there is `cc\_embed\_data` and `go\_embed\_data`. This is because Python has a concept of runtime resources. | +| `distribs` | List of strings; default is `[]` | +| `experimental_venvs_site_packages` | [Label](./concepts/labels); default is `None` \*\*INTERNAL ATTRIBUTE. SHOULD ONLY BE SET BY rules\_python-INTERNAL CODE.\*\* :::\{include\} /\_includes/experimental\_api.md ::: A flag that decides whether the library should treat its sources as a site-packages layout. When the flag is `yes`, then the `srcs` files are treated as a site-packages layout that is relative to the `imports` attribute. The `imports` attribute can have only a single element. It is a repo-relative runfiles path. For example, in the `my/pkg/BUILD.bazel` file, given `srcs=["site-packages/foo/bar.py"]`, specifying `imports=["my/pkg/site-packages"]` means `foo/bar.py` is the file path under the binary's venv site-packages directory that should be made available (i.e. `import foo.bar` will work). `\_\_init\_\_.py` files are treated specially to provide basic support for [implicit namespace packages]( https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages). However, the \*content\* of the files cannot be taken into account, merely their presence or absense. Stated another way: [pkgutil-style namespace packages]( https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages) won't be understood as namespace packages; they'll be seen as regular packages. This will likely lead to conflicts with other targets that contribute to the namespace. :::\{tip\} This attributes populates \{obj\}`PyInfo.site\_packages\_symlinks`, which is a topologically ordered depset. This means dependencies closer and earlier to a consumer have precedence. See \{obj\}`PyInfo.site\_packages\_symlinks` for more information. ::: :::\{versionadded\} 1.4.0 ::: | +| `imports` | List of strings; default is `[]` List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py\_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, Absolute paths (paths that start with `/`) and paths that references a path above the execution root are not allowed and will result in an error. | +| `precompile` | String; default is `"inherit"` Whether py source files \*\*for this target\*\* should be precompiled. Values: \* `inherit`: Allow the downstream binary decide if precompiled files are used. \* `enabled`: Compile Python source files at build time. \* `disabled`: Don't compile Python source files at build time. :::\{seealso\} \* The \{flag\}`--precompile` flag, which can override this attribute in some cases and will affect all targets when building. \* The \{obj\}`pyc\_collection` attribute for transitively enabling precompiling on a per-target basis. \* The [Precompiling](precompiling) docs for a guide about using precompiling. ::: | +| `precompile_invalidation_mode` | String; default is `"auto"` How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: \* `auto`: The effective value will be automatically determined by other build settings. \* `checked\_hash`: Use the pyc file if the hash of the source file matches the hash recorded in the pyc file. This is most useful when working with code that you may modify. \* `unchecked\_hash`: Always use the pyc file; don't check the pyc's hash against the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode | +| `precompile_optimize_level` | Integer; default is `0` The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile NOTE: The value `-1` means "current interpreter", which will be the interpreter used \_at build time when pycs are generated\_, not the interpreter used at runtime when the code actually runs. | +| `precompile_source_retention` | String; default is `"inherit"` Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: \* `inherit`: Inherit the value from the \{flag\}`--precompile\_source\_retention` flag. \* `keep\_source`: Include the original Python source. \* `omit\_source`: Don't include the original py source. | +| `pyi_deps` | List of [labels](./concepts/labels); default is `[]` Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE\_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | +| `pyi_srcs` | List of [labels](./concepts/labels); default is `[]` Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | +| `srcs_version` | String; default is `""` Defunct, unused, does nothing. | + +## py\_test + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_test_rule.bzl) -``` rule-signature +``` py_test(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, imports, interpreter_args, legacy_create_init, licenses, local, main, main_module, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, pyi_deps, pyi_srcs, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility) ``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="py_test.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="py_test.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -List of additional libraries to be linked in to the target. -See comments about -the [`deps` attribute typically defined by -rules](https://bazel.build/reference/be/common-definitions#typical-attributes). -These are typically `py_library` rules. -Targets that only provide data files used at runtime belong in the `data` -attribute. -:::{note} -The order of this list can matter because it affects the order that information -from dependencies is merged in, which can be relevant depending on the ordering -mode of depsets that are merged. -* {obj}`PyInfo.site_packages_symlinks` uses topological ordering. -See {obj}`PyInfo` for more information about the ordering of its depsets and -how its fields are merged. -:::</td> -</tr> -<tr> -<td id="py_test.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of Python source files that are processed to create the target. This -includes all your checked-in code and may include generated source files. The -`.py` files belong in `srcs` and library targets belong in `deps`. Other binary -files that may be needed at run time belong in `data`.</td> -</tr> -<tr> -<td id="py_test.data"><code>data</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of files need by this library at runtime. See comments about -the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). -There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. -This is because Python has a concept of runtime resources.</td> -</tr> -<tr> -<td id="py_test.distribs"><code>distribs</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="py_test.imports"><code>imports</code></td> -<td><p>List of strings; default is <code>[]</code></p> -List of import directories to be added to the PYTHONPATH. -Subject to "Make variable" substitution. These import directories will be added -for this rule and all rules that depend on it (note: not the rules this rule -depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules -that depend on this rule. The strings are repo-runfiles-root relative, -Absolute paths (paths that start with `/`) and paths that references a path -above the execution root are not allowed and will result in an error.</td> -</tr> -<tr> -<td id="py_test.interpreter_args"><code>interpreter_args</code></td> -<td><p>List of strings; default is <code>[]</code></p> -Arguments that are only applicable to the interpreter. -The args an interpreter supports are specific to the interpreter. For -CPython, see https://docs.python.org/3/using/cmdline.html. -:::{note} -Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise. -::: -:::{seealso} -The {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable -::: -:::{versionadded} 1.3.0 -:::</td> -</tr> -<tr> -<td id="py_test.legacy_create_init"><code>legacy_create_init</code></td> -<td><p>Integer; default is <code>-1</code></p> -Whether to implicitly create empty `__init__.py` files in the runfiles tree. -These are created in every directory containing Python source code or shared -libraries, and every parent directory of those directories, excluding the repo -root directory. The default, `-1` (auto), means true unless -`--incompatible_default_to_explicit_init_py` is used. If false, the user is -responsible for creating (possibly empty) `__init__.py` files and adding them to -the `srcs` of Python targets as required.</td> -</tr> -<tr> -<td id="py_test.main"><code>main</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -Optional; the name of the source file that is the main entry point of the -application. This file must also be listed in `srcs`. If left unspecified, -`name`, with `.py` appended, is used instead. If `name` does not match any -filename in `srcs`, `main` must be specified. -This is mutually exclusive with {obj}`main_module`.</td> -</tr> -<tr> -<td id="py_test.main_module"><code>main_module</code></td> -<td><p>String; default is <code>""</code></p> -Module name to execute as the main program. -When set, `srcs` is not required, and it is assumed the module is -provided by a dependency. -See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more -information about running modules as the main program. -This is mutually exclusive with {obj}`main`. -:::{versionadded} 1.3.0 -:::</td> -</tr> -<tr> -<td id="py_test.precompile"><code>precompile</code></td> -<td><p>String; default is <code>"inherit"</code></p> -Whether py source files **for this target** should be precompiled. -Values: -* `inherit`: Allow the downstream binary decide if precompiled files are used. -* `enabled`: Compile Python source files at build time. -* `disabled`: Don't compile Python source files at build time. -:::{seealso} -* The {flag}`--precompile` flag, which can override this attribute in some cases -and will affect all targets when building. -* The {obj}`pyc_collection` attribute for transitively enabling precompiling on -a per-target basis. -* The [Precompiling](precompiling) docs for a guide about using precompiling. -:::</td> -</tr> -<tr> -<td id="py_test.precompile_invalidation_mode"><code>precompile_invalidation_mode</code></td> -<td><p>String; default is <code>"auto"</code></p> -How precompiled files should be verified to be up-to-date with their associated -source files. Possible values are: -* `auto`: The effective value will be automatically determined by other build -settings. -* `checked_hash`: Use the pyc file if the hash of the source file matches the hash -recorded in the pyc file. This is most useful when working with code that -you may modify. -* `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against -the source file. This is most useful when the code won't be modified. -For more information on pyc invalidation modes, see -https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode</td> -</tr> -<tr> -<td id="py_test.precompile_optimize_level"><code>precompile_optimize_level</code></td> -<td><p>Integer; default is <code>0</code></p> -The optimization level for precompiled files. -For more information about optimization levels, see the `compile()` function's -`optimize` arg docs at https://docs.python.org/3/library/functions.html#compile -NOTE: The value `-1` means "current interpreter", which will be the interpreter -used _at build time when pycs are generated_, not the interpreter used at -runtime when the code actually runs.</td> -</tr> -<tr> -<td id="py_test.precompile_source_retention"><code>precompile_source_retention</code></td> -<td><p>String; default is <code>"inherit"</code></p> -Determines, when a source file is compiled, if the source file is kept -in the resulting output or not. Valid values are: -* `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. -* `keep_source`: Include the original Python source. -* `omit_source`: Don't include the original py source.</td> -</tr> -<tr> -<td id="py_test.pyc_collection"><code>pyc_collection</code></td> -<td><p>String; default is <code>"inherit"</code></p> -Determines whether pyc files from dependencies should be manually included. -Valid values are: -* `inherit`: Inherit the value from {flag}`--precompile`. -* `include_pyc`: Add implicitly generated pyc files from dependencies. i.e. -pyc files for targets that specify {attr}`precompile="inherit"`. -* `disabled`: Don't add implicitly generated pyc files. Note that -pyc files may still come from dependencies that enable precompiling at the -target level.</td> -</tr> -<tr> -<td id="py_test.pyi_deps"><code>pyi_deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Dependencies providing type definitions the library needs. -These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`. -These are build-time only dependencies and not included as part of a runnable -program (packaging rules may include them, however). -:::{versionadded} 1.1.0 -:::</td> -</tr> -<tr> -<td id="py_test.pyi_srcs"><code>pyi_srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -Type definition files for the library. -These are typically `.pyi` files, but other file types for type-checker specific -formats are allowed. These files are build-time only dependencies and not included -as part of a runnable program (packaging rules may include them, however). -:::{versionadded} 1.1.0 -:::</td> -</tr> -<tr> -<td id="py_test.python_version"><code>python_version</code></td> -<td><p>String; default is <code>""</code></p> -The Python version this target should use. -The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or -unspecified, the incoming configuration's {obj}`--python_version` flag is -inherited. For backwards compatibility, the values `PY2` and `PY3` are -accepted, but treated as an empty/unspecified value. -:::{note} -In order for the requested version to be used, there must be a -toolchain configured to match the Python version. If there isn't, then it -may be silently ignored, or an error may occur, depending on the toolchain -configuration. -::: -:::{versionchanged} 1.1.0 -This attribute was changed from only accepting `PY2` and `PY3` values to -accepting arbitrary Python versions. -:::</td> -</tr> -<tr> -<td id="py_test.srcs_version"><code>srcs_version</code></td> -<td><p>String; default is <code>""</code></p> -Defunct, unused, does nothing.</td> -</tr> -<tr> -<td id="py_test.stamp"><code>stamp</code></td> -<td><p>Integer; default is <code>0</code></p> -Whether to encode build information into the binary. Possible values: -* `stamp = 1`: Always stamp the build information into the binary, even in -`--nostamp` builds. **This setting should be avoided**, since it potentially kills -remote caching for the binary and any downstream actions that depend on it. -* `stamp = 0`: Always replace build information by constant values. This gives -good build result caching. -* `stamp = -1`: Embedding of build information is controlled by the -`--[no]stamp` flag. -Stamped binaries are not rebuilt unless their dependencies change. -WARNING: Stamping can harm build performance by reducing cache hits and should -be avoided if possible.</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py\_library` rules. Targets that only provide data files used at runtime belong in the `data` attribute. :::\{note\} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. \* \{obj\}`PyInfo.site\_packages\_symlinks` uses topological ordering. See \{obj\}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. ::: | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of Python source files that are processed to create the target. This includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary files that may be needed at run time belong in `data`. | +| `data` | List of [labels](./concepts/labels); default is `[]` The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). There is no `py\_embed\_data` like there is `cc\_embed\_data` and `go\_embed\_data`. This is because Python has a concept of runtime resources. | +| `distribs` | List of strings; default is `[]` | +| `imports` | List of strings; default is `[]` List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py\_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, Absolute paths (paths that start with `/`) and paths that references a path above the execution root are not allowed and will result in an error. | +| `interpreter_args` | List of strings; default is `[]` Arguments that are only applicable to the interpreter. The args an interpreter supports are specific to the interpreter. For CPython, see https://docs.python.org/3/using/cmdline.html. :::\{note\} Only supported for \{obj\}`--bootstrap\_impl=script`. Ignored otherwise. ::: :::\{seealso\} The \{any\}`RULES\_PYTHON\_ADDITIONAL\_INTERPRETER\_ARGS` environment variable ::: :::\{versionadded\} 1.3.0 ::: | +| `legacy_create_init` | Integer; default is `-1` Whether to implicitly create empty `\_\_init\_\_.py` files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default, `-1` (auto), means true unless `--incompatible\_default\_to\_explicit\_init\_py` is used. If false, the user is responsible for creating (possibly empty) `\_\_init\_\_.py` files and adding them to the `srcs` of Python targets as required. | +| `main` | [Label](./concepts/labels); default is `None` Optional; the name of the source file that is the main entry point of the application. This file must also be listed in `srcs`. If left unspecified, `name`, with `.py` appended, is used instead. If `name` does not match any filename in `srcs`, `main` must be specified. This is mutually exclusive with \{obj\}`main\_module`. | +| `main_module` | String; default is `""` Module name to execute as the main program. When set, `srcs` is not required, and it is assumed the module is provided by a dependency. See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more information about running modules as the main program. This is mutually exclusive with \{obj\}`main`. :::\{versionadded\} 1.3.0 ::: | +| `precompile` | String; default is `"inherit"` Whether py source files \*\*for this target\*\* should be precompiled. Values: \* `inherit`: Allow the downstream binary decide if precompiled files are used. \* `enabled`: Compile Python source files at build time. \* `disabled`: Don't compile Python source files at build time. :::\{seealso\} \* The \{flag\}`--precompile` flag, which can override this attribute in some cases and will affect all targets when building. \* The \{obj\}`pyc\_collection` attribute for transitively enabling precompiling on a per-target basis. \* The [Precompiling](precompiling) docs for a guide about using precompiling. ::: | +| `precompile_invalidation_mode` | String; default is `"auto"` How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: \* `auto`: The effective value will be automatically determined by other build settings. \* `checked\_hash`: Use the pyc file if the hash of the source file matches the hash recorded in the pyc file. This is most useful when working with code that you may modify. \* `unchecked\_hash`: Always use the pyc file; don't check the pyc's hash against the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode | +| `precompile_optimize_level` | Integer; default is `0` The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile NOTE: The value `-1` means "current interpreter", which will be the interpreter used \_at build time when pycs are generated\_, not the interpreter used at runtime when the code actually runs. | +| `precompile_source_retention` | String; default is `"inherit"` Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: \* `inherit`: Inherit the value from the \{flag\}`--precompile\_source\_retention` flag. \* `keep\_source`: Include the original Python source. \* `omit\_source`: Don't include the original py source. | +| `pyc_collection` | String; default is `"inherit"` Determines whether pyc files from dependencies should be manually included. Valid values are: \* `inherit`: Inherit the value from \{flag\}`--precompile`. \* `include\_pyc`: Add implicitly generated pyc files from dependencies. i.e. pyc files for targets that specify \{attr\}`precompile="inherit"`. \* `disabled`: Don't add implicitly generated pyc files. Note that pyc files may still come from dependencies that enable precompiling at the target level. | +| `pyi_deps` | List of [labels](./concepts/labels); default is `[]` Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE\_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | +| `pyi_srcs` | List of [labels](./concepts/labels); default is `[]` Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | +| `python_version` | String; default is `""` The Python version this target should use. The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or unspecified, the incoming configuration's \{obj\}`--python\_version` flag is inherited. For backwards compatibility, the values `PY2` and `PY3` are accepted, but treated as an empty/unspecified value. :::\{note\} In order for the requested version to be used, there must be a toolchain configured to match the Python version. If there isn't, then it may be silently ignored, or an error may occur, depending on the toolchain configuration. ::: :::\{versionchanged\} 1.1.0 This attribute was changed from only accepting `PY2` and `PY3` values to accepting arbitrary Python versions. ::: | +| `srcs_version` | String; default is `""` Defunct, unused, does nothing. | +| `stamp` | Integer; default is `0` Whether to encode build information into the binary. Possible values: \* `stamp = 1`: Always stamp the build information into the binary, even in `--nostamp` builds. \*\*This setting should be avoided\*\*, since it potentially kills remote caching for the binary and any downstream actions that depend on it. \* `stamp = 0`: Always replace build information by constant values. This gives good build result caching. \* `stamp = -1`: Embedding of build information is controlled by the `--[no]stamp` flag. Stamped binaries are not rebuilt unless their dependencies change. WARNING: Stamping can harm build performance by reducing cache hits and should be avoided if possible. | + +## py\_runtime + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_runtime_rule.bzl) -## py_runtime - -<a href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_runtime_rule.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +``` py_runtime(name, abi_flags, aspect_hints, bootstrap_template, compatible_with, coverage_tool, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, files, implementation_name, interpreter, interpreter_path, interpreter_version_info, package_metadata, pyc_tag, python_version, restricted_to, site_init_template, stage2_bootstrap_template, stub_shebang, tags, target_compatible_with, testonly, toolchains, visibility, zip_main_template) ``` Represents a Python runtime used to execute Python code. -A \`py_runtime\` target can represent either a \*platform runtime\* or an \*in-build +A `py\_runtime` target can represent either a \*platform runtime\* or an \*in-build runtime\*. A platform runtime accesses a system-installed interpreter at a known path, whereas an in-build runtime points to an executable target that acts as the interpreter. In both cases, an "interpreter" means any executable binary or @@ -715,171 +135,35 @@ in-build runtime may or may not be hermetic, depending on whether it points to a checked-in interpreter or a wrapper script that accesses the system interpreter. Example -\`\`\` -load("@rules_python//python:py_runtime.bzl", "py_runtime") -py_runtime( +``` +load("@rules\_python//python:py\_runtime.bzl", "py\_runtime") +py\_runtime( name = "python-2.7.12", -files = glob(\["python-2.7.12/\*\*"\]), +files = glob(["python-2.7.12/\*\*"]), interpreter = "python-2.7.12/bin/python", ) -py_runtime( +py\_runtime( name = "python-3.6.0", -interpreter_path = "/opt/pyenv/versions/3.6.0/bin/python", +interpreter\_path = "/opt/pyenv/versions/3.6.0/bin/python", ) -\`\`\` +``` ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="py_runtime.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="py_runtime.abi_flags"><code>abi_flags</code></td> -<td><p>String; default is <code>""</code></p> -The runtime's ABI flags, i.e. `sys.abiflags`. -If not set, then it will be set based on flags.</td> -</tr> -<tr> -<td id="py_runtime.bootstrap_template"><code>bootstrap_template</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:bootstrap_template"</code></p> -The bootstrap script template file to use. Should have %python_binary%, -%workspace_name%, %main%, and %imports%. -This template, after expansion, becomes the executable file used to start the -process, so it is responsible for initial bootstrapping actions such as finding -the Python interpreter, runfiles, and constructing an environment to run the -intended Python application. -While this attribute is currently optional, it will become required when the -Python rules are moved out of Bazel itself. -The exact variable names expanded is an unstable API and is subject to change. -The API will become more stable when the Python rules are moved out of Bazel -itself. -See @bazel_tools//tools/python:python_bootstrap_template.txt for more variables.</td> -</tr> -<tr> -<td id="py_runtime.coverage_tool"><code>coverage_tool</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -This is a target to use for collecting code coverage information from -{rule}`py_binary` and {rule}`py_test` targets. -If set, the target must either produce a single file or be an executable target. -The path to the single file, or the executable if the target is executable, -determines the entry point for the python coverage tool. The target and its -runfiles will be added to the runfiles when coverage is enabled. -The entry point for the tool must be loadable by a Python interpreter (e.g. a -`.py` or `.pyc` file). It must accept the command line arguments -of [`coverage.py`](https://coverage.readthedocs.io), at least including -the `run` and `lcov` subcommands.</td> -</tr> -<tr> -<td id="py_runtime.files"><code>files</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -For an in-build runtime, this is the set of files comprising this runtime. -These files will be added to the runfiles of Python binaries that use this -runtime. For a platform runtime this attribute must not be set.</td> -</tr> -<tr> -<td id="py_runtime.implementation_name"><code>implementation_name</code></td> -<td><p>String; default is <code>"cpython"</code></p> -The Python implementation name (`sys.implementation.name`)</td> -</tr> -<tr> -<td id="py_runtime.interpreter"><code>interpreter</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>None</code></p> -For an in-build runtime, this is the target to invoke as the interpreter. It -can be either of: -* A single file, which will be the interpreter binary. It's assumed such -interpreters are either self-contained single-file executables or any -supporting files are specified in `files`. -* An executable target. The target's executable will be the interpreter binary. -Any other default outputs (`target.files`) and plain files runfiles -(`runfiles.files`) will be automatically included as if specified in the -`files` attribute. -NOTE: the runfiles of the target may not yet be properly respected/propagated -to consumers of the toolchain/interpreter, see -bazel-contrib/rules_python/issues/1612 -For a platform runtime (i.e. `interpreter_path` being set) this attribute must -not be set.</td> -</tr> -<tr> -<td id="py_runtime.interpreter_path"><code>interpreter_path</code></td> -<td><p>String; default is <code>""</code></p> -For a platform runtime, this is the absolute path of a Python interpreter on -the target platform. For an in-build runtime this attribute must not be set.</td> -</tr> -<tr> -<td id="py_runtime.interpreter_version_info"><code>interpreter_version_info</code></td> -<td><p>Dictionary: String -> String; default is <code>{}</code></p> -Version information about the interpreter this runtime provides. -If not specified, uses {obj}`--python_version` -The supported keys match the names for `sys.version_info`. While the input -values are strings, most are converted to ints. The supported keys are: -* major: int, the major version number -* minor: int, the minor version number -* micro: optional int, the micro version number -* releaselevel: optional str, the release level -* serial: optional int, the serial number of the release -:::{versionchanged} 0.36.0 -{obj}`--python_version` determines the default value. -:::</td> -</tr> -<tr> -<td id="py_runtime.pyc_tag"><code>pyc_tag</code></td> -<td><p>String; default is <code>""</code></p> -Optional string; the tag portion of a pyc filename, e.g. the `cpython-39` infix -of `foo.cpython-39.pyc`. See PEP 3147. If not specified, it will be computed -from `implementation_name` and `interpreter_version_info`. If no pyc_tag is -available, then only source-less pyc generation will function correctly.</td> -</tr> -<tr> -<td id="py_runtime.python_version"><code>python_version</code></td> -<td><p>String; default is <code>"PY3"</code></p> -Whether this runtime is for Python major version 2 or 3. Valid values are `"PY2"` -and `"PY3"`. -The default value is controlled by the `--incompatible_py3_is_default` flag. -However, in the future this attribute will be mandatory and have no default -value.</td> -</tr> -<tr> -<td id="py_runtime.site_init_template"><code>site_init_template</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:site_init_template"</code></p> -The template to use for the binary-specific site-init hook run by the -interpreter at startup. -:::{versionadded} 0.41.0 -:::</td> -</tr> -<tr> -<td id="py_runtime.stage2_bootstrap_template"><code>stage2_bootstrap_template</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:stage2_bootstrap_template"</code></p> -The template to use when two stage bootstrapping is enabled -:::{seealso} -{obj}`PyRuntimeInfo.stage2_bootstrap_template` and {obj}`--bootstrap_impl` -:::</td> -</tr> -<tr> -<td id="py_runtime.stub_shebang"><code>stub_shebang</code></td> -<td><p>String; default is <code>"#!/usr/bin/env python3"</code></p> -"Shebang" expression prepended to the bootstrapping Python stub script -used when executing {rule}`py_binary` targets. -See https://github.com/bazelbuild/bazel/issues/8685 for -motivation. -Does not apply to Windows.</td> -</tr> -<tr> -<td id="py_runtime.zip_main_template"><code>zip_main_template</code></td> -<td><p><a href="/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:zip_main_template"</code></p> -The template to use for a zip's top-level `__main__.py` file. -This becomes the entry point executed when `python foo.zip` is run. -:::{seealso} -The {obj}`PyRuntimeInfo.zip_main_template` field. -:::</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `abi_flags` | String; default is `""` The runtime's ABI flags, i.e. `sys.abiflags`. If not set, then it will be set based on flags. | +| `bootstrap_template` | [Label](./concepts/labels); default is `"@rules_python//python/private:bootstrap_template"` The bootstrap script template file to use. Should have %python\_binary%, %workspace\_name%, %main%, and %imports%. This template, after expansion, becomes the executable file used to start the process, so it is responsible for initial bootstrapping actions such as finding the Python interpreter, runfiles, and constructing an environment to run the intended Python application. While this attribute is currently optional, it will become required when the Python rules are moved out of Bazel itself. The exact variable names expanded is an unstable API and is subject to change. The API will become more stable when the Python rules are moved out of Bazel itself. See @bazel\_tools//tools/python:python\_bootstrap\_template.txt for more variables. | +| `coverage_tool` | [Label](./concepts/labels); default is `None` This is a target to use for collecting code coverage information from \{rule\}`py\_binary` and \{rule\}`py\_test` targets. If set, the target must either produce a single file or be an executable target. The path to the single file, or the executable if the target is executable, determines the entry point for the python coverage tool. The target and its runfiles will be added to the runfiles when coverage is enabled. The entry point for the tool must be loadable by a Python interpreter (e.g. a `.py` or `.pyc` file). It must accept the command line arguments of [`coverage.py`](https://coverage.readthedocs.io), at least including the `run` and `lcov` subcommands. | +| `files` | List of [labels](./concepts/labels); default is `[]` For an in-build runtime, this is the set of files comprising this runtime. These files will be added to the runfiles of Python binaries that use this runtime. For a platform runtime this attribute must not be set. | +| `implementation_name` | String; default is `"cpython"` The Python implementation name (`sys.implementation.name`) | +| `interpreter` | [Label](./concepts/labels); default is `None` For an in-build runtime, this is the target to invoke as the interpreter. It can be either of: \* A single file, which will be the interpreter binary. It's assumed such interpreters are either self-contained single-file executables or any supporting files are specified in `files`. \* An executable target. The target's executable will be the interpreter binary. Any other default outputs (`target.files`) and plain files runfiles (`runfiles.files`) will be automatically included as if specified in the `files` attribute. NOTE: the runfiles of the target may not yet be properly respected/propagated to consumers of the toolchain/interpreter, see bazel-contrib/rules\_python/issues/1612 For a platform runtime (i.e. `interpreter\_path` being set) this attribute must not be set. | +| `interpreter_path` | String; default is `""` For a platform runtime, this is the absolute path of a Python interpreter on the target platform. For an in-build runtime this attribute must not be set. | +| `interpreter_version_info` | Dictionary: String -> String; default is `\{\}` Version information about the interpreter this runtime provides. If not specified, uses \{obj\}`--python\_version` The supported keys match the names for `sys.version\_info`. While the input values are strings, most are converted to ints. The supported keys are: \* major: int, the major version number \* minor: int, the minor version number \* micro: optional int, the micro version number \* releaselevel: optional str, the release level \* serial: optional int, the serial number of the release :::\{versionchanged\} 0.36.0 \{obj\}`--python\_version` determines the default value. ::: | +| `pyc_tag` | String; default is `""` Optional string; the tag portion of a pyc filename, e.g. the `cpython-39` infix of `foo.cpython-39.pyc`. See PEP 3147. If not specified, it will be computed from `implementation\_name` and `interpreter\_version\_info`. If no pyc\_tag is available, then only source-less pyc generation will function correctly. | +| `python_version` | String; default is `"PY3"` Whether this runtime is for Python major version 2 or 3. Valid values are `"PY2"` and `"PY3"`. The default value is controlled by the `--incompatible\_py3\_is\_default` flag. However, in the future this attribute will be mandatory and have no default value. | +| `site_init_template` | [Label](./concepts/labels); default is `"@rules_python//python/private:site_init_template"` The template to use for the binary-specific site-init hook run by the interpreter at startup. :::\{versionadded\} 0.41.0 ::: | +| `stage2_bootstrap_template` | [Label](./concepts/labels); default is `"@rules_python//python/private:stage2_bootstrap_template"` The template to use when two stage bootstrapping is enabled :::\{seealso\} \{obj\}`PyRuntimeInfo.stage2\_bootstrap\_template` and \{obj\}`--bootstrap\_impl` ::: | +| `stub_shebang` | String; default is `"#!/usr/bin/env python3"` "Shebang" expression prepended to the bootstrapping Python stub script used when executing \{rule\}`py\_binary` targets. See https://github.com/bazelbuild/bazel/issues/8685 for motivation. Does not apply to Windows. | +| `zip_main_template` | [Label](./concepts/labels); default is `"@rules_python//python/private:zip_main_template"` The template to use for a zip's top-level `\_\_main\_\_.py` file. This becomes the entry point executed when `python foo.zip` is run. :::\{seealso\} The \{obj\}`PyRuntimeInfo.zip\_main\_template` field. ::: | \ No newline at end of file diff --git a/reference/be/shell.mdx b/reference/be/shell.mdx index 0f096dd..5818423 100644 --- a/reference/be/shell.mdx +++ b/reference/be/shell.mdx @@ -2,22 +2,18 @@ title: 'shell' --- -# Shell Rules - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} -{% include "\_buttons.html" %} ## Rules -- [sh_binary](#sh_binary) -- [sh_library](#sh_library) -- [sh_test](#sh_test) +* [sh\_binary](#sh_binary) +* [sh\_library](#sh_library) +* [sh\_test](#sh_test) -## sh_binary +## sh\_binary -<a href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_binary.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_binary.bzl) -``` rule-signature +``` sh_binary(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, output_licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, use_bash_launcher, visibility) ``` @@ -33,8 +29,7 @@ the extension (e.g. `.sh`); the rule name and the file name must be distinct. For a simple shell script with no dependencies and some data files: -``` code - +``` sh_binary( name = "foo", srcs = ["foo.sh"], @@ -44,55 +39,19 @@ sh_binary( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="sh_binary.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="sh_binary.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of "library" targets to be aggregated into this target. -See general comments about <code>deps</code> -at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by -most build rules</a>. -<p>This attribute should be used to list other <code>sh_library</code> rules that provide -interpreted program source code depended on by the code in <code>srcs</code>. The files -provided by these rules will be present among the <code>runfiles</code> of this target.</p></td> -</tr> -<tr> -<td id="sh_binary.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The file containing the shell script. -<p>This attribute must be a singleton list, whose element is the shell script. -This script must be executable, and may be a source file or a generated file. -All other files required at runtime (whether scripts or data) belong in the -<code>data</code> attribute.</p></td> -</tr> -<tr> -<td id="sh_binary.env_inherit"><code>env_inherit</code></td> -<td><p>List of strings; default is <code>[]</code></p></td> -</tr> -<tr> -<td id="sh_binary.use_bash_launcher"><code>use_bash_launcher</code></td> -<td><p>Boolean; default is <code>False</code></p> -Use a bash launcher initializing the runfiles library</td> -</tr> -</tbody> -</table> - -## sh_library - -<a href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_library.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of "library" targets to be aggregated into this target. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical.deps). This attribute should be used to list other `sh_library` rules that provide interpreted program source code depended on by the code in `srcs`. The files provided by these rules will be present among the `runfiles` of this target. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The file containing the shell script. This attribute must be a singleton list, whose element is the shell script. This script must be executable, and may be a source file or a generated file. All other files required at runtime (whether scripts or data) belong in the `data` attribute. | +| `env_inherit` | List of strings; default is `[]` | +| `use_bash_launcher` | Boolean; default is `False` Use a bash launcher initializing the runfiles library | + +## sh\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_library.bzl) + +``` sh_library(name, deps, srcs, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` @@ -104,7 +63,7 @@ run-time. Such "libraries" can then be used from the `data` attribute of one or more `sh_binary` rules. -You can use the [`filegroup`](/reference/be/general.html#filegroup) rule to aggregate data +You can use the [`filegroup`](./reference/be/general.html#filegroup) rule to aggregate data files. In interpreted programming languages, there's not always a clear @@ -118,8 +77,7 @@ It is however good practice to use the attributes for their usual purpose (as wi #### Examples -``` code - +``` sh_library( name = "foo", data = [ @@ -131,57 +89,27 @@ sh_library( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="sh_library.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="sh_library.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of "library" targets to be aggregated into this target. -See general comments about <code>deps</code> -at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by -most build rules</a>. -<p>This attribute should be used to list other <code>sh_library</code> rules that provide -interpreted program source code depended on by the code in <code>srcs</code>. The files -provided by these rules will be present among the <code>runfiles</code> of this target.</p></td> -</tr> -<tr> -<td id="sh_library.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of input files. -<p>This attribute should be used to list shell script source files that belong to -this library. Scripts can load other scripts using the shell's <code>source</code> -or <code>.</code> command.</p></td> -</tr> -</tbody> -</table> - -## sh_test - -<a href="https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_test.bzl" class="button button-with-icon" target="_blank">View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span></a> - -``` rule-signature +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of "library" targets to be aggregated into this target. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical.deps). This attribute should be used to list other `sh_library` rules that provide interpreted program source code depended on by the code in `srcs`. The files provided by these rules will be present among the `runfiles` of this target. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of input files. This attribute should be used to list shell script source files that belong to this library. Scripts can load other scripts using the shell's `source` or `.` command. | + +## sh\_test + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_test.bzl) + +``` sh_test(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, local, package_metadata, restricted_to, shard_count, size, tags, target_compatible_with, testonly, timeout, toolchains, use_bash_launcher, visibility) ``` A `sh_test()` rule creates a test written as a Bourne shell script. -See the -[attributes common to all test rules (\*\_test)](/reference/be/common-definitions#common-attributes-tests). +See the [attributes common to all test rules (\*\_test)](./reference/be/common-definitions#common-attributes-tests). #### Examples -``` code - +``` sh_test( name = "foo_integration_test", size = "small", @@ -193,42 +121,9 @@ sh_test( ### Arguments -<table class="table table-condensed table-bordered table-params"> -<thead> -<tr> -<th colspan="2">Attributes</th> -</tr> -</thead> -<tbody> -<tr> -<td id="sh_test.name"><code>name</code></td> -<td><p><a href="/concepts/labels#target-names">Name</a>; required</p> -<p>A unique name for this target.</p></td> -</tr> -<tr> -<td id="sh_test.deps"><code>deps</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The list of "library" targets to be aggregated into this target. -See general comments about <code>deps</code> -at <a href="/reference/be/common-definitions#typical.deps">Typical attributes defined by -most build rules</a>. -<p>This attribute should be used to list other <code>sh_library</code> rules that provide -interpreted program source code depended on by the code in <code>srcs</code>. The files -provided by these rules will be present among the <code>runfiles</code> of this target.</p></td> -</tr> -<tr> -<td id="sh_test.srcs"><code>srcs</code></td> -<td><p>List of <a href="/concepts/labels">labels</a>; default is <code>[]</code></p> -The file containing the shell script. -<p>This attribute must be a singleton list, whose element is the shell script. -This script must be executable, and may be a source file or a generated file. -All other files required at runtime (whether scripts or data) belong in the -<code>data</code> attribute.</p></td> -</tr> -<tr> -<td id="sh_test.use_bash_launcher"><code>use_bash_launcher</code></td> -<td><p>Boolean; default is <code>False</code></p> -Use a bash launcher initializing the runfiles library</td> -</tr> -</tbody> -</table> +| Attributes | | +| --- | --- | +| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](./concepts/labels); default is `[]` The list of "library" targets to be aggregated into this target. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical.deps). This attribute should be used to list other `sh_library` rules that provide interpreted program source code depended on by the code in `srcs`. The files provided by these rules will be present among the `runfiles` of this target. | +| `srcs` | List of [labels](./concepts/labels); default is `[]` The file containing the shell script. This attribute must be a singleton list, whose element is the shell script. This script must be executable, and may be a source file or a generated file. All other files required at runtime (whether scripts or data) belong in the `data` attribute. | +| `use_bash_launcher` | Boolean; default is `False` Use a bash launcher initializing the runfiles library | \ No newline at end of file diff --git a/reference/command-line-reference.mdx b/reference/command-line-reference.mdx index 9aff8c2..8a6bb76 100644 --- a/reference/command-line-reference.mdx +++ b/reference/command-line-reference.mdx @@ -2,20 +2,18 @@ title: 'command-line-reference' --- -# Command-Line Reference -{% dynamic setvar source_file "site/command-line-reference-prefix.html" %} -{% include "\_buttons.html" %} - - - bazel [<startup options>] <command> [<args>] +``` +bazel [<startup options>] \<command\> [\<args\>] +``` or +``` +bazel [<startup options>] \<command\> [\<args\>] -- [<target patterns>] +``` - bazel [<startup options>] <command> [<args>] -- [<target patterns>] - -See the [User's Guide](/docs/build#specifying-build-targets) for the +See the [User's Guide](./docs/build#specifying-build-targets) for the target patterns syntax. ## Option Syntax @@ -23,44 +21,50 @@ target patterns syntax. Options can be passed to Bazel in different ways. Options that require a value can be passed with either an equals sign or a space: - - --<option>=<value> - --<option> <value> +``` +--\<option>=<value\> +--\<option\> \<value\> +``` Some options have a single character short form; in that case, the short form has to be passed with a single dash and a space. - - -<short_form> <value> +``` +-\<short_form\> \<value\> +``` Boolean options can be enabled as follows: - - --<option> - --<option>=[true|yes|1] +``` +--\<option\> +--<option>=[true|yes|1] +``` and disabled as follows: - - --no<option> - --<option>=[false|no|0] +``` +--no\<option\> +--<option>=[false|no|0] +``` Tristate options are usually set to automatic by default, and can be force-enabled as follows: - - --<option>=[true|yes|1] +``` +--<option>=[true|yes|1] +``` or force-disabled as follows: - - --no<option> - --<option>=[false|no|0] +``` +--no\<option\> +--<option>=[false|no|0] +``` ## Commands | | | -|----|----| +| --- | --- | | [`aquery`](#aquery) | Analyzes the given targets and queries the action graph. | | [`build`](#build) | Builds the specified targets. | | [`canonicalize-flags`](#canonicalize-flags) | Canonicalizes a list of bazel options. | @@ -79,11767 +83,12051 @@ or force-disabled as follows: | [`run`](#run) | Runs the specified target. | | [`shutdown`](#shutdown) | Stops the bazel server. | | [`test`](#test) | Builds and runs the specified test targets. | -| [`vendor`](#vendor) | Fetches external repositories into a folder specified by the flag --vendor_dir. | +| [`vendor`](#vendor) | Fetches external repositories into a folder specified by the flag --vendor\_dir. | | [`version`](#version) | Prints version information for bazel. | ## Startup Options -[`--[no]autodetect_server_javabase`](#startup_options-flag--autodetect_server_javabase) default: "true" -When --noautodetect_server_javabase is passed, Bazel does not fall back to the local JDK for running the bazel server and instead exits. - -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -[`--[no]batch`](#startup_options-flag--batch) default: "false" -If set, Bazel will be run as just a client process without a server, instead of in the standard client/server mode. This is deprecated and will be removed, please prefer shutting down the server explicitly if you wish to avoid lingering servers. - -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`deprecated`](#metadata_tag_DEPRECATED) - -[`--[no]batch_cpu_scheduling`](#startup_options-flag--batch_cpu_scheduling) default: "false" -Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched_setscheduler'. If false, then Bazel does not perform a system call. - -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -[`--bazelrc`](#startup_options-flag--bazelrc)`=<path>` multiple uses are accumulated -The location of the user .bazelrc file containing default values of Bazel options. /dev/null indicates that all further `--bazelrc`s will be ignored, which is useful to disable the search for a user rc file, e.g. in release builds. -This option can also be specified multiple times. -E.g. with `--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc`, - -1. x.rc and y.rc are read. -2. z.rc is ignored due to the prior /dev/null. - If unspecified, Bazel uses the first .bazelrc file it finds in the following two locations: the workspace directory, then the user's home directory. - Note: command line options will always supersede any option in bazelrc. - -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +Options that appear before the command and are parsed by the client: -[`--[no]block_for_lock`](#startup_options-flag--block_for_lock) default: "true" -When --noblock_for_lock is passed, Bazel does not wait for a running command to complete, but instead exits immediately. +`--[no]autodetect_server_javabase` default: "true" +: When --noautodetect\_server\_javabase is passed, Bazel does not fall back to the local JDK for running the bazel server and instead exits. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]client_debug`](#startup_options-flag--client_debug) default: "false" -If true, log debug information from the client to stderr. Changing this option will not cause the server to restart. +`--[no]batch` default: "false" +: If set, Bazel will be run as just a client process without a server, instead of in the standard client/server mode. This is deprecated and will be removed, please prefer shutting down the server explicitly if you wish to avoid lingering servers. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`deprecated`](#metadata_tag_DEPRECATED) -[`--connect_timeout_secs`](#startup_options-flag--connect_timeout_secs)`=<an integer>` default: "30" -The amount of time the client waits for each attempt to connect to the server +`--[no]batch_cpu_scheduling` default: "false" +: Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched\_setscheduler'. If false, then Bazel does not perform a system call. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--digest_function`](#startup_options-flag--digest_function)`=<hash function>` default: see description -The hash function to use when computing file digests. +`--bazelrc=<path>` multiple uses are accumulated +: The location of the user .bazelrc file containing default values of Bazel options. /dev/null indicates that all further `--bazelrc`s will be ignored, which is useful to disable the search for a user rc file, e.g. in release builds. + This option can also be specified multiple times. + E.g. with `--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc`, -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + 1. x.rc and y.rc are read. + 2. z.rc is ignored due to the prior /dev/null. + If unspecified, Bazel uses the first .bazelrc file it finds in the following two locations: the workspace directory, then the user's home directory. + Note: command line options will always supersede any option in bazelrc. -[`--experimental_cgroup_parent`](#startup_options-flag--experimental_cgroup_parent)`=<path>` default: see description -The cgroup where to start the bazel server as an absolute path. The server process will be started in the specified cgroup for each supported controller. For example, if the value of this flag is /build/bazel and the cpu and memory controllers are mounted respectively on /sys/fs/cgroup/cpu and /sys/fs/cgroup/memory, the server will be started in the cgroups /sys/fs/cgroup/cpu/build/bazel and /sys/fs/cgroup/memory/build/bazel.It is not an error if the specified cgroup is not writable for one or more of the controllers. This options does not have any effect on platforms that do not support cgroups. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) +`--[no]block_for_lock` default: "true" +: When --noblock\_for\_lock is passed, Bazel does not wait for a running command to complete, but instead exits immediately. -[`--[no]experimental_run_in_user_cgroup`](#startup_options-flag--experimental_run_in_user_cgroup) default: "false" -If true, the Bazel server will be run with systemd-run, and the user will own the cgroup. This flag only takes effect on Linux. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) +`--[no]client_debug` default: "false" +: If true, log debug information from the client to stderr. Changing this option will not cause the server to restart. -[`--failure_detail_out`](#startup_options-flag--failure_detail_out)`=<path>` default: see description -If set, specifies a location to write a failure_detail protobuf message if the server experiences a failure and cannot report it via gRPC, as normal. Otherwise, the location will be \${OUTPUT_BASE}/failure_detail.rawproto. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--connect_timeout_secs=<an integer>` default: "30" +: The amount of time the client waits for each attempt to connect to the server -[`--[no]home_rc`](#startup_options-flag--home_rc) default: "true" -Whether or not to look for the home bazelrc file at \$HOME/.bazelrc + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--digest_function=<hash function>` default: see description +: The hash function to use when computing file digests. -[`--[no]idle_server_tasks`](#startup_options-flag--idle_server_tasks) default: "true" -Run System.gc() when the server is idle + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--experimental_cgroup_parent=<path>` default: see description +: The cgroup where to start the bazel server as an absolute path. The server process will be started in the specified cgroup for each supported controller. For example, if the value of this flag is /build/bazel and the cpu and memory controllers are mounted respectively on /sys/fs/cgroup/cpu and /sys/fs/cgroup/memory, the server will be started in the cgroups /sys/fs/cgroup/cpu/build/bazel and /sys/fs/cgroup/memory/build/bazel.It is not an error if the specified cgroup is not writable for one or more of the controllers. This options does not have any effect on platforms that do not support cgroups. -[`--[no]ignore_all_rc_files`](#startup_options-flag--ignore_all_rc_files) default: "false" -Disables all rc files, regardless of the values of other rc-modifying flags, even if these flags come later in the list of startup options. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--[no]experimental_run_in_user_cgroup` default: "false" +: If true, the Bazel server will be run with systemd-run, and the user will own the cgroup. This flag only takes effect on Linux. -[`--io_nice_level`](#startup_options-flag--io_nice_level)`={-1,0,1,2,3,4,5,6,7}` default: "-1" -Only on Linux; set a level from 0-7 for best-effort IO scheduling using the sys_ioprio_set system call. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. If set to a negative value, then Bazel does not perform a system call. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--failure_detail_out=<path>` default: see description +: If set, specifies a location to write a failure\_detail protobuf message if the server experiences a failure and cannot report it via gRPC, as normal. Otherwise, the location will be $\{OUTPUT\_BASE\}/failure\_detail.rawproto. -[`--local_startup_timeout_secs`](#startup_options-flag--local_startup_timeout_secs)`=<an integer>` default: "120" -The maximum amount of time the client waits to connect to the server + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +`--[no]home_rc` default: "true" +: Whether or not to look for the home bazelrc file at $HOME/.bazelrc -[`--macos_qos_class`](#startup_options-flag--macos_qos_class)`=<a string>` default: "default" -Sets the QoS service class of the bazel server when running on macOS. This flag has no effect on all other platforms but is supported to ensure rc files can be shared among them without changes. Possible values are: user-interactive, user-initiated, default, utility, and background. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--[no]idle_server_tasks` default: "true" +: Run System.gc() when the server is idle -[`--max_idle_secs`](#startup_options-flag--max_idle_secs)`=<integer>` default: "10800" -The number of seconds the build server will wait idling before shutting down. Zero means that the server will never shutdown. This is only read on server-startup, changing this option will not cause the server to restart. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]ignore_all_rc_files` default: "false" +: Disables all rc files, regardless of the values of other rc-modifying flags, even if these flags come later in the list of startup options. -[`--output_base`](#startup_options-flag--output_base)`=<path>` default: see description -If set, specifies the output location to which all build output will be written. Otherwise, the location will be \${OUTPUT_ROOT}/*blaze*\${USER}/\${MD5_OF_WORKSPACE_ROOT}. Note: If you specify a different option from one to the next Bazel invocation for this value, you'll likely start up a new, additional Bazel server. Bazel starts exactly one server per specified output base. Typically there is one output base per workspace - however, with this option you may have multiple output bases per workspace and thereby run multiple builds for the same client on the same machine concurrently. See 'bazel help shutdown' on how to shutdown a Bazel server. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--io_nice_level=\{-1,0,1,2,3,4,5,6,7\}` default: "-1" +: Only on Linux; set a level from 0-7 for best-effort IO scheduling using the sys\_ioprio\_set system call. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. If set to a negative value, then Bazel does not perform a system call. -[`--output_user_root`](#startup_options-flag--output_user_root)`=<path>` default: see description -The user-specific directory beneath which all build outputs are written; by default, this is a function of \$USER, but by specifying a constant, build outputs can be shared between collaborating users. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--local_startup_timeout_secs=<an integer>` default: "120" +: The maximum amount of time the client waits to connect to the server -[`--[no]preemptible`](#startup_options-flag--preemptible) default: "false" -If true, the command can be preempted if another command is started. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--macos_qos_class=<a string>` default: "default" +: Sets the QoS service class of the bazel server when running on macOS. This flag has no effect on all other platforms but is supported to ensure rc files can be shared among them without changes. Possible values are: user-interactive, user-initiated, default, utility, and background. -[`--[no]quiet`](#startup_options-flag--quiet) default: "false" -If true, no informational messages are emitted on the console, only errors. Changing this option will not cause the server to restart. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--max_idle_secs=<integer>` default: "10800" +: The number of seconds the build server will wait idling before shutting down. Zero means that the server will never shutdown. This is only read on server-startup, changing this option will not cause the server to restart. -[`--server_jvm_out`](#startup_options-flag--server_jvm_out)`=<path>` default: see description -The location to write the server's JVM's output. If unset then defaults to a location in output_base. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--output_base=<path>` default: see description +: If set, specifies the output location to which all build output will be written. Otherwise, the location will be $\{OUTPUT\_ROOT\}/*blaze*$\{USER\}/$\{MD5\_OF\_WORKSPACE\_ROOT\}. Note: If you specify a different option from one to the next Bazel invocation for this value, you'll likely start up a new, additional Bazel server. Bazel starts exactly one server per specified output base. Typically there is one output base per workspace - however, with this option you may have multiple output bases per workspace and thereby run multiple builds for the same client on the same machine concurrently. See 'bazel help shutdown' on how to shutdown a Bazel server. -[`--[no]shutdown_on_low_sys_mem`](#startup_options-flag--shutdown_on_low_sys_mem) default: "false" -If max_idle_secs is set and the build server has been idle for a while, shut down the server when the system is low on free RAM. Linux and MacOS only. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--output_user_root=<path>` default: see description +: The user-specific directory beneath which all build outputs are written; by default, this is a function of $USER, but by specifying a constant, build outputs can be shared between collaborating users. -[`--[no]system_rc`](#startup_options-flag--system_rc) default: "true" -Whether or not to look for the system-wide bazelrc. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--[no]preemptible` default: "false" +: If true, the command can be preempted if another command is started. -[`--[no]unlimit_coredumps`](#startup_options-flag--unlimit_coredumps) default: "false" -Raises the soft coredump limit to the hard limit to make coredumps of the server (including the JVM) and the client possible under common conditions. Stick this flag in your bazelrc once and forget about it so that you get coredumps when you actually encounter a condition that triggers them. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +`--[no]quiet` default: "false" +: If true, no informational messages are emitted on the console, only errors. Changing this option will not cause the server to restart. -[`--[no]windows_enable_symlinks`](#startup_options-flag--windows_enable_symlinks) default: "false" -If true, real symbolic links will be created on Windows instead of file copying. Requires Windows developer mode to be enabled and Windows 10 version 1703 or greater. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +`--server_jvm_out=<path>` default: see description +: The location to write the server's JVM's output. If unset then defaults to a location in output\_base. -[`--[no]workspace_rc`](#startup_options-flag--workspace_rc) default: "true" -Whether or not to look for the workspace bazelrc file at \$workspace/.bazelrc + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--[no]shutdown_on_low_sys_mem` default: "false" +: If max\_idle\_secs is set and the build server has been idle for a while, shut down the server when the system is low on free RAM. Linux and MacOS only. -<!-- --> + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--host_jvm_args`](#startup_options-flag--host_jvm_args)`=<jvm_arg>` multiple uses are accumulated -Flags to pass to the JVM executing Blaze. +`--[no]system_rc` default: "true" +: Whether or not to look for the system-wide bazelrc. -[`--host_jvm_debug`](#startup_options-flag--host_jvm_debug) -Convenience option to add some additional JVM startup flags, which cause the JVM to wait during startup until you connect from a JDWP-compliant debugger (like Eclipse) to port 5005. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Expands to: -  [`--host_jvm_args=-agentlib:jdwp=transport=dt_socket,server=y,address=5005`](#flag--host_jvm_args) +`--[no]unlimit_coredumps` default: "false" +: Raises the soft coredump limit to the hard limit to make coredumps of the server (including the JVM) and the client possible under common conditions. Stick this flag in your bazelrc once and forget about it so that you get coredumps when you actually encounter a condition that triggers them. -[`--server_javabase`](#startup_options-flag--server_javabase)`=<jvm path>` default: "" -Path to the JVM used to execute Bazel itself. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -## <span id="common_options">Options Common to all Commands</span> +`--[no]windows_enable_symlinks` default: "false" +: If true, real symbolic links will be created on Windows instead of file copying. Requires Windows developer mode to be enabled and Windows 10 version 1703 or greater. -[`--distdir`](#common_options-flag--distdir)`=<a path>` multiple uses are accumulated -Additional places to search for archives before accessing the network to download them. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +`--[no]workspace_rc` default: "true" +: Whether or not to look for the workspace bazelrc file at $workspace/.bazelrc -[`--[no]experimental_repository_cache_hardlinks`](#common_options-flag--experimental_repository_cache_hardlinks) default: "false" -If set, the repository cache will hardlink the file in case of a cache hit, rather than copying. This is intended to save disk space. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +Miscellaneous options, not otherwise categorized.: -[`--experimental_repository_downloader_retries`](#common_options-flag--experimental_repository_downloader_retries)`=<an integer>` default: "5" -The maximum number of attempts to retry a download error. If set to 0, retries are disabled. +`--host_jvm_args=<jvm_arg>` multiple uses are accumulated +: Flags to pass to the JVM executing Blaze. -Tags: -[`experimental`](#metadata_tag_EXPERIMENTAL) +`--host_jvm_debug` +: Convenience option to add some additional JVM startup flags, which cause the JVM to wait during startup until you connect from a JDWP-compliant debugger (like Eclipse) to port 5005. -[`--experimental_scale_timeouts`](#common_options-flag--experimental_scale_timeouts)`=<a double>` default: "1.0" -Scale all timeouts in Starlark repository rules by this factor. In this way, external repositories can be made working on machines that are slower than the rule author expected, without changing the source code + Expands to: + +   `--host_jvm_args=-agentlib:jdwp=transport=dt_socket,server=y,address=5005` -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--server_javabase=<jvm path>` default: "" +: Path to the JVM used to execute Bazel itself. -[`--http_connector_attempts`](#common_options-flag--http_connector_attempts)`=<an integer>` default: "8" -The maximum number of attempts for http downloads. +## Options Common to all Commands -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +Options that appear before the command and are parsed by the client: -[`--http_connector_retry_max_timeout`](#common_options-flag--http_connector_retry_max_timeout)`=<An immutable length of time.>` default: "0s" -The maximum timeout for http download retries. With a value of 0, no timeout maximum is defined. +`--distdir=<a path>` multiple uses are accumulated +: Additional places to search for archives before accessing the network to download them. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--http_max_parallel_downloads`](#common_options-flag--http_max_parallel_downloads)`=<an integer>` default: "8" -The maximum number parallel http downloads. +`--[no]experimental_repository_cache_hardlinks` default: "false" +: If set, the repository cache will hardlink the file in case of a cache hit, rather than copying. This is intended to save disk space. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--http_timeout_scaling`](#common_options-flag--http_timeout_scaling)`=<a double>` default: "1.0" -Scale all timeouts related to http downloads by the given factor +`--experimental_repository_downloader_retries=<an integer>` default: "5" +: The maximum number of attempts to retry a download error. If set to 0, retries are disabled. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--repo_contents_cache`](#common_options-flag--repo_contents_cache)`=<a path>` default: see description -Specifies the location of the repo contents cache, which contains fetched repo directories shareable across workspaces. An empty string as argument requests the repo contents cache to be disabled, otherwise the default of '\<--repository_cache\>/contents' is used. Note that this means setting '--repository_cache=' would by default disable the repo contents cache as well, unless '--repo_contents_cache=\<some_path\>' is also set. +`--experimental_scale_timeouts=<a double>` default: "1.0" +: Scale all timeouts in Starlark repository rules by this factor. In this way, external repositories can be made working on machines that are slower than the rule author expected, without changing the source code -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--repo_contents_cache_gc_idle_delay`](#common_options-flag--repo_contents_cache_gc_idle_delay)`=<An immutable length of time.>` default: "5m" -Specifies the amount of time the server must remain idle before garbage collection happens -to the repo contents cache. +`--http_connector_attempts=<an integer>` default: "8" +: The maximum number of attempts for http downloads. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--repo_contents_cache_gc_max_age`](#common_options-flag--repo_contents_cache_gc_max_age)`=<An immutable length of time.>` default: "14d" -Specifies the amount of time an entry in the repo contents cache can stay unused before it's garbage collected. If set to zero, only duplicate entries will be garbage collected. +`--http_connector_retry_max_timeout=<An immutable length of time.>` default: "0s" +: The maximum timeout for http download retries. With a value of 0, no timeout maximum is defined. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--repository_cache`](#common_options-flag--repository_cache)`=<a path>` default: see description -Specifies the cache location of the downloaded values obtained during the fetching of external repositories. An empty string as argument requests the cache to be disabled, otherwise the default of '\<--output_user_root\>/cache/repos/v1' is used +`--http_max_parallel_downloads=<an integer>` default: "8" +: The maximum number parallel http downloads. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--[no]repository_disable_download`](#common_options-flag--repository_disable_download) default: "false" -If set, downloading using ctx.download{,\_and_extract} is not allowed during repository fetching. Note that network access is not completely disabled; ctx.execute could still run an arbitrary executable that accesses the Internet. +`--http_timeout_scaling=<a double>` default: "1.0" +: Scale all timeouts related to http downloads by the given factor -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -<!-- --> +`--repo_contents_cache=<a path>` default: see description +: Specifies the location of the repo contents cache, which contains fetched repo directories shareable across workspaces. An empty string as argument requests the repo contents cache to be disabled, otherwise the default of '\<--repository\_cache\>/contents' is used. Note that this means setting '--repository\_cache=' would by default disable the repo contents cache as well, unless '--repo\_contents\_cache=\<some\_path\>' is also set. -[`--experimental_ui_max_stdouterr_bytes`](#common_options-flag--experimental_ui_max_stdouterr_bytes)`=<an integer in (-1)-1073741819 range>` default: "1048576" -The maximum size of the stdout / stderr files that will be printed to the console. -1 implies no limit. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--repo_contents_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" +: Specifies the amount of time the server must remain idle before garbage collection happens + to the repo contents cache. -[`--gc_churning_threshold`](#common_options-flag--gc_churning_threshold)`=<an integer in 0-100 range>` default: "100" -At any point after an invocation has been running for at least one minute, if Blaze has spent at least this percentage of the invocation's wall time doing full GCs, Blaze will give up and fail with an OOM. A value of 100 effectively means to never give up for this reason. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--repo_contents_cache_gc_max_age=<An immutable length of time.>` default: "14d" +: Specifies the amount of time an entry in the repo contents cache can stay unused before it's garbage collected. If set to zero, only duplicate entries will be garbage collected. -[`--gc_churning_threshold_if_multiple_top_level_targets`](#common_options-flag--gc_churning_threshold_if_multiple_top_level_targets)`=<an integer>` default: "-1" -If set to a value in \[0, 100\] and this is a command that takes top-level targets (e.g. build but not query) and there are multiple such top-level targets, overrides --gc_churning_threshold. Useful to configure more aggressive OOMing behavior (i.e. a lower value than --gc_churning_threshold) when they are multiple top-level targets so that the invoker of Bazel can split and retry while still having less aggressive behavior when there is a single top-level target. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--repository_cache=<a path>` default: see description +: Specifies the cache location of the downloaded values obtained during the fetching of external repositories. An empty string as argument requests the cache to be disabled, otherwise the default of '\<--output\_user\_root\>/cache/repos/v1' is used -[`--gc_thrashing_threshold`](#common_options-flag--gc_thrashing_threshold)`=<an integer in 0-100 range>` default: "100" -The percent of tenured space occupied (0-100) above which GcThrashingDetector considers memory pressure events against its limits (--gc_thrashing_limits). If set to 100, GcThrashingDetector is disabled. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--[no]repository_disable_download` default: "false" +: If set, downloading using ctx.download\{,\_and\_extract\} is not allowed during repository fetching. Note that network access is not completely disabled; ctx.execute could still run an arbitrary executable that accesses the Internet. -<!-- --> + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--[no]incompatible_enable_proto_toolchain_resolution`](#common_options-flag--incompatible_enable_proto_toolchain_resolution) default: "false" -If true, proto lang rules define toolchains from protobuf repository. +Options that control build execution: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--experimental_ui_max_stdouterr_bytes=<an integer in (-1)-1073741819 range>` default: "1048576" +: The maximum size of the stdout / stderr files that will be printed to the console. -1 implies no limit. -<!-- --> + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--bep_maximum_open_remote_upload_files`](#common_options-flag--bep_maximum_open_remote_upload_files)`=<an integer>` default: "-1" -Maximum number of open files allowed during BEP artifact upload. +`--gc_churning_threshold=<an integer in 0-100 range>` default: "100" +: At any point after an invocation has been running for at least one minute, if Blaze has spent at least this percentage of the invocation's wall time doing full GCs, Blaze will give up and fail with an OOM. A value of 100 effectively means to never give up for this reason. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--remote_download_all`](#common_options-flag--remote_download_all) -Downloads all remote outputs to the local machine. This flag is an alias for --remote_download_outputs=all. +`--gc_churning_threshold_if_multiple_top_level_targets=<an integer>` default: "-1" +: If set to a value in [0, 100] and this is a command that takes top-level targets (e.g. build but not query) and there are multiple such top-level targets, overrides --gc\_churning\_threshold. Useful to configure more aggressive OOMing behavior (i.e. a lower value than --gc\_churning\_threshold) when they are multiple top-level targets so that the invoker of Bazel can split and retry while still having less aggressive behavior when there is a single top-level target. -Expands to: -  [`--remote_download_outputs=all`](#flag--remote_download_outputs) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--gc_thrashing_threshold=<an integer in 0-100 range>` default: "100" +: The percent of tenured space occupied (0-100) above which GcThrashingDetector considers memory pressure events against its limits (--gc\_thrashing\_limits). If set to 100, GcThrashingDetector is disabled. -[`--remote_download_minimal`](#common_options-flag--remote_download_minimal) -Does not download any remote build outputs to the local machine. This flag is an alias for --remote_download_outputs=minimal. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Expands to: -  [`--remote_download_outputs=minimal`](#flag--remote_download_outputs) +Options that configure the toolchain used for action execution: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_enable_proto_toolchain_resolution` default: "false" +: If true, proto lang rules define toolchains from protobuf repository. -[`--remote_download_outputs`](#common_options-flag--remote_download_outputs)`=<all, minimal or toplevel>` default: "toplevel" -If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -[`--remote_download_symlink_template`](#common_options-flag--remote_download_symlink_template)`=<a string>` default: "" -Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. +`--bep_maximum_open_remote_upload_files=<an integer>` default: "-1" +: Maximum number of open files allowed during BEP artifact upload. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--remote_download_toplevel`](#common_options-flag--remote_download_toplevel) -Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote_download_outputs=toplevel. +`--remote_download_all` +: Downloads all remote outputs to the local machine. This flag is an alias for --remote\_download\_outputs=all. -Expands to: -  [`--remote_download_outputs=toplevel`](#flag--remote_download_outputs) + Expands to: + +   `--remote_download_outputs=all` -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--repo_env`](#common_options-flag--repo_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies additional environment variables to be available only for repository rules. Note that repository rules see the full environment anyway, but in this way variables can be set via command-line flags and \<code\>.bazelrc\</code\> entries. The special syntax \<code\>=NAME\</code\> can be used to explicitly unset a variable. +`--remote_download_minimal` +: Does not download any remote build outputs to the local machine. This flag is an alias for --remote\_download\_outputs=minimal. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Expands to: + +   `--remote_download_outputs=minimal` -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]allow_experimental_loads`](#common_options-flag--allow_experimental_loads) default: "false" -If enabled, issue only a warning instead of an error for loads of experimental .bzls. +`--remote_download_outputs=<all, minimal or toplevel>` default: "toplevel" +: If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]check_bzl_visibility`](#common_options-flag--check_bzl_visibility) default: "true" -If disabled, .bzl load visibility errors are demoted to warnings. +`--remote_download_symlink_template=<a string>` default: "" +: Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain \{hash\} and \{size\_bytes\} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_enforce_starlark_utf8`](#common_options-flag--incompatible_enforce_starlark_utf8) default: "warning" -If enabled (or set to 'error'), fail if Starlark files are not UTF-8 encoded. If set to 'warning', emit a warning instead. If set to 'off', Bazel assumes that Starlark files are UTF-8 encoded but does not verify this assumption. Note that Starlark files which are not UTF-8 encoded can cause Bazel to behave inconsistently. +`--remote_download_toplevel` +: Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote\_download\_outputs=toplevel. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Expands to: + +   `--remote_download_outputs=toplevel` -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_bzl_visibility`](#common_options-flag--experimental_bzl_visibility) default: "true" -If enabled, adds a `visibility()` function that .bzl files may call during top-level evaluation to set their visibility for the purpose of load() statements. +`--repo_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies additional environment variables to be available only for repository rules. Note that repository rules see the full environment anyway, but in this way variables can be set via command-line flags and \<code\>.bazelrc\</code\> entries. The special syntax \<code>=NAME</code\> can be used to explicitly unset a variable. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]experimental_cc_shared_library`](#common_options-flag--experimental_cc_shared_library) default: "false" -If set to true, rule attributes and Starlark API methods needed for the rule cc_shared_library will be available +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]allow_experimental_loads` default: "false" +: If enabled, issue only a warning instead of an error for loads of experimental .bzls. -[`--[no]experimental_disable_external_package`](#common_options-flag--experimental_disable_external_package) default: "false" -If set to true, the auto-generated //external package will not be available anymore. Bazel will still be unable to parse the file 'external/BUILD', but globs reaching into external/ from the unnamed package will work. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]check_bzl_visibility` default: "true" +: If disabled, .bzl load visibility errors are demoted to warnings. -[`--[no]experimental_dormant_deps`](#common_options-flag--experimental_dormant_deps) default: "false" -If set to true, attr.label(materializer=), attr(for_dependency_resolution=), attr.dormant_label(), attr.dormant_label_list() and rule(for_dependency_resolution=) are allowed. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]incompatible_enforce_starlark_utf8` default: "warning" +: If enabled (or set to 'error'), fail if Starlark files are not UTF-8 encoded. If set to 'warning', emit a warning instead. If set to 'off', Bazel assumes that Starlark files are UTF-8 encoded but does not verify this assumption. Note that Starlark files which are not UTF-8 encoded can cause Bazel to behave inconsistently. -[`--[no]experimental_enable_android_migration_apis`](#common_options-flag--experimental_enable_android_migration_apis) default: "false" -If set to true, enables the APIs required to support the Android Starlark migration. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -[`--[no]experimental_enable_first_class_macros`](#common_options-flag--experimental_enable_first_class_macros) default: "true" -If set to true, enables the `macro()` construct for defining symbolic macros. +`--[no]experimental_bzl_visibility` default: "true" +: If enabled, adds a `visibility()` function that .bzl files may call during top-level evaluation to set their visibility for the purpose of load() statements. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_enable_scl_dialect`](#common_options-flag--experimental_enable_scl_dialect) default: "true" -If set to true, .scl files may be used in load() statements. +`--[no]experimental_cc_shared_library` default: "false" +: If set to true, rule attributes and Starlark API methods needed for the rule cc\_shared\_library will be available -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_enable_starlark_set`](#common_options-flag--experimental_enable_starlark_set) default: "true" -If true, enable the set data type and set() constructor in Starlark. +`--[no]experimental_disable_external_package` default: "false" +: If set to true, the auto-generated //external package will not be available anymore. Bazel will still be unable to parse the file 'external/BUILD', but globs reaching into external/ from the unnamed package will work. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_google_legacy_api`](#common_options-flag--experimental_google_legacy_api) default: "false" -If set to true, exposes a number of experimental pieces of Starlark build API pertaining to Google legacy code. +`--[no]experimental_dormant_deps` default: "false" +: If set to true, attr.label(materializer=), attr(for\_dependency\_resolution=), attr.dormant\_label(), attr.dormant\_label\_list() and rule(for\_dependency\_resolution=) are allowed. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_isolated_extension_usages`](#common_options-flag--experimental_isolated_extension_usages) default: "false" -If true, enables the \<code\>isolate\</code\> parameter in the \<a href="https://bazel.build/rules/lib/globals/module#use_extension"\>\<code\>use_extension\</code\>\</a\> function. +`--[no]experimental_enable_android_migration_apis` default: "false" +: If set to true, enables the APIs required to support the Android Starlark migration. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--[no]experimental_platforms_api`](#common_options-flag--experimental_platforms_api) default: "false" -If set to true, enables a number of platform-related Starlark APIs useful for debugging. +`--[no]experimental_enable_first_class_macros` default: "true" +: If set to true, enables the `macro()` construct for defining symbolic macros. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--[no]experimental_repo_remote_exec`](#common_options-flag--experimental_repo_remote_exec) default: "false" -If set to true, repository_rule gains some remote execution capabilities. +`--[no]experimental_enable_scl_dialect` default: "true" +: If set to true, .scl files may be used in load() statements. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--[no]experimental_repository_ctx_execute_wasm`](#common_options-flag--experimental_repository_ctx_execute_wasm) default: "false" -If true enables the repository_ctx `load_wasm` and `execute_wasm` methods. +`--[no]experimental_enable_starlark_set` default: "true" +: If true, enable the set data type and set() constructor in Starlark. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_sibling_repository_layout`](#common_options-flag--experimental_sibling_repository_layout) default: "false" -If set to true, non-main repositories are planted as symlinks to the main repository in the execution root. That is, all repositories are direct children of the \$output_base/execution_root directory. This has the side effect of freeing up \$output_base/execution_root/**main**/external for the real top-level 'external' directory. +`--[no]experimental_google_legacy_api` default: "false" +: If set to true, exposes a number of experimental pieces of Starlark build API pertaining to Google legacy code. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_single_package_toolchain_binding`](#common_options-flag--experimental_single_package_toolchain_binding) default: "false" -If enabled, the register_toolchain function may not include target patterns which may refer to more than one package. +`--[no]experimental_isolated_extension_usages` default: "false" +: If true, enables the \<code\>isolate\</code\> parameter in the <a href="https://bazel.build/rules/lib/globals/module#use\_extension">\<code\>use\_extension\</code\>\</a\> function. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]experimental_starlark_types`](#common_options-flag--experimental_starlark_types) default: "false" -Enables type annotations and type checking. Locations where the annotations are allowed is further controlled by `--experimental_starlark_types_allowed_paths`. +`--[no]experimental_platforms_api` default: "false" +: If set to true, enables a number of platform-related Starlark APIs useful for debugging. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--experimental_starlark_types_allowed_paths`](#common_options-flag--experimental_starlark_types_allowed_paths)`=<comma-separated list of options>` default: "" -List of canonical Label prefixes under which Starlark type annotations are allowed. +`--[no]experimental_repo_remote_exec` default: "false" +: If set to true, repository\_rule gains some remote execution capabilities. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_allow_tags_propagation`](#common_options-flag--incompatible_allow_tags_propagation) default: "true" -If set to true, tags will be propagated from a target to the actions' execution requirements; otherwise tags are not propagated. See https://github.com/bazelbuild/bazel/issues/8830 for details. +`--[no]experimental_repository_ctx_execute_wasm` default: "false" +: If true enables the repository\_ctx `load_wasm` and `execute_wasm` methods. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_always_check_depset_elements`](#common_options-flag--incompatible_always_check_depset_elements) default: "true" -Check the validity of elements added to depsets, in all constructors. Elements must be immutable, but historically the depset(direct=...) constructor forgot to check. Use tuples instead of lists in depset elements. See https://github.com/bazelbuild/bazel/issues/10313 for details. +`--[no]experimental_sibling_repository_layout` default: "false" +: If set to true, non-main repositories are planted as symlinks to the main repository in the execution root. That is, all repositories are direct children of the $output\_base/execution\_root directory. This has the side effect of freeing up $output\_base/execution\_root/**main**/external for the real top-level 'external' directory. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--incompatible_autoload_externally`](#common_options-flag--incompatible_autoload_externally)`=<comma-separated set of options>` default: "+@rules_cc" -A comma-separated list of rules (or other symbols) that were previously part of Bazel and which are now to be retrieved from their respective external repositories. This flag is intended to be used to facilitate migration of rules out of Bazel. See also https://github.com/bazelbuild/bazel/issues/23043. -A symbol that is autoloaded within a file behaves as if its built-into-Bazel definition were replaced by its canonical new definition in an external repository. For a BUILD file, this essentially means implicitly adding a load() statement. For a .bzl file, it's either a load() statement or a change to a field of the `native` object, depending on whether the autoloaded symbol is a rule. -Bazel maintains a hardcoded list of all symbols that may be autoloaded; only those symbols may appear in this flag. For each symbol, Bazel knows the new definition location in an external repository, as well as a set of special-cased repositories that must not autoload it to avoid creating cycles. -A list item of "+foo" in this flag causes symbol foo to be autoloaded, except in foo's exempt repositories, within which the Bazel-defined version of foo is still available. -A list item of "foo" triggers autoloading as above, but the Bazel-defined version of foo is not made available to the excluded repositories. This ensures that foo's external repository does not depend on the old Bazel implementation of foo -A list item of "-foo" does not trigger any autoloading, but makes the Bazel-defined version of foo inaccessible throughout the workspace. This is used to validate that the workspace is ready for foo's definition to be deleted from Bazel. -If a symbol is not named in this flag then it continues to work as normal -- no autoloading is done, nor is the Bazel-defined version suppressed. For configuration see https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/packages/AutoloadSymbols.java As a shortcut also whole repository may be used, for example +@rules_python will autoload all Python rules. +`--[no]experimental_single_package_toolchain_binding` default: "false" +: If enabled, the register\_toolchain function may not include target patterns which may refer to more than one package. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_disable_autoloads_in_main_repo`](#common_options-flag--incompatible_disable_autoloads_in_main_repo) default: "true" -Controls if the autoloads (set by --incompatible_autoload_externally) are enabled in themain repository. When enabled the rules (or other symbols) that were previously part of Bazel need to have load statements. Use buildifier to add them. +`--[no]experimental_starlark_types` default: "false" +: Enables type annotations and type checking. Locations where the annotations are allowed is further controlled by `--experimental_starlark_types_allowed_paths`. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_disable_objc_library_transition`](#common_options-flag--incompatible_disable_objc_library_transition) default: "true" -Disable objc_library's custom transition and inherit from the top level target instead (No-op in Bazel) +`--experimental_starlark_types_allowed_paths=<comma-separated list of options>` default: "" +: List of canonical Label prefixes under which Starlark type annotations are allowed. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_disable_starlark_host_transitions`](#common_options-flag--incompatible_disable_starlark_host_transitions) default: "false" -If set to true, rule attributes cannot set 'cfg = "host"'. Rules should set 'cfg = "exec"' instead. +`--[no]incompatible_allow_tags_propagation` default: "true" +: If set to true, tags will be propagated from a target to the actions' execution requirements; otherwise tags are not propagated. See https://github.com/bazelbuild/bazel/issues/8830 for details. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_disable_target_default_provider_fields`](#common_options-flag--incompatible_disable_target_default_provider_fields) default: "false" -If set to true, disable the ability to utilize the default provider via field syntax. Use provider-key syntax instead. For example, instead of using `ctx.attr.dep.files` to access `files`, utilize \`ctx.attr.dep\[DefaultInfo\].files See https://github.com/bazelbuild/bazel/issues/9014 for details. +`--[no]incompatible_always_check_depset_elements` default: "true" +: Check the validity of elements added to depsets, in all constructors. Elements must be immutable, but historically the depset(direct=...) constructor forgot to check. Use tuples instead of lists in depset elements. See https://github.com/bazelbuild/bazel/issues/10313 for details. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--incompatible_disable_transitions_on`](#common_options-flag--incompatible_disable_transitions_on)`=<comma-separated set of options>` default: "" -A comma-separated list of flags that cannot be used in transitions inputs or outputs. +`--incompatible_autoload_externally=<comma-separated set of options>` default: "+@rules\_cc" +: A comma-separated list of rules (or other symbols) that were previously part of Bazel and which are now to be retrieved from their respective external repositories. This flag is intended to be used to facilitate migration of rules out of Bazel. See also https://github.com/bazelbuild/bazel/issues/23043. + A symbol that is autoloaded within a file behaves as if its built-into-Bazel definition were replaced by its canonical new definition in an external repository. For a BUILD file, this essentially means implicitly adding a load() statement. For a .bzl file, it's either a load() statement or a change to a field of the `native` object, depending on whether the autoloaded symbol is a rule. + Bazel maintains a hardcoded list of all symbols that may be autoloaded; only those symbols may appear in this flag. For each symbol, Bazel knows the new definition location in an external repository, as well as a set of special-cased repositories that must not autoload it to avoid creating cycles. + A list item of "+foo" in this flag causes symbol foo to be autoloaded, except in foo's exempt repositories, within which the Bazel-defined version of foo is still available. + A list item of "foo" triggers autoloading as above, but the Bazel-defined version of foo is not made available to the excluded repositories. This ensures that foo's external repository does not depend on the old Bazel implementation of foo + A list item of "-foo" does not trigger any autoloading, but makes the Bazel-defined version of foo inaccessible throughout the workspace. This is used to validate that the workspace is ready for foo's definition to be deleted from Bazel. + If a symbol is not named in this flag then it continues to work as normal -- no autoloading is done, nor is the Bazel-defined version suppressed. For configuration see https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/packages/AutoloadSymbols.java As a shortcut also whole repository may be used, for example +@rules\_python will autoload all Python rules. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_disallow_ctx_resolve_tools`](#common_options-flag--incompatible_disallow_ctx_resolve_tools) default: "true" -If set to true, calling the deprecated ctx.resolve_tools API always fails. Uses of this API should be replaced by an executable or tools argument to ctx.actions.run or ctx.actions.run_shell. +`--[no]incompatible_disable_autoloads_in_main_repo` default: "true" +: Controls if the autoloads (set by --incompatible\_autoload\_externally) are enabled in themain repository. When enabled the rules (or other symbols) that were previously part of Bazel need to have load statements. Use buildifier to add them. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_disallow_empty_glob`](#common_options-flag--incompatible_disallow_empty_glob) default: "true" -If set to true, the default value of the `allow_empty` argument of glob() is False. +`--[no]incompatible_disable_objc_library_transition` default: "true" +: Disable objc\_library's custom transition and inherit from the top level target instead (No-op in Bazel) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_enable_deprecated_label_apis`](#common_options-flag--incompatible_enable_deprecated_label_apis) default: "true" -If enabled, certain deprecated APIs (native.repository_name, Label.workspace_name, Label.relative) can be used. +`--[no]incompatible_disable_starlark_host_transitions` default: "false" +: If set to true, rule attributes cannot set 'cfg = "host"'. Rules should set 'cfg = "exec"' instead. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_fail_on_unknown_attributes`](#common_options-flag--incompatible_fail_on_unknown_attributes) default: "true" -If enabled, targets that have unknown attributes set to None fail. +`--[no]incompatible_disable_target_default_provider_fields` default: "false" +: If set to true, disable the ability to utilize the default provider via field syntax. Use provider-key syntax instead. For example, instead of using `ctx.attr.dep.files` to access `files`, utilize `ctx.attr.dep[DefaultInfo].files See https://github.com/bazelbuild/bazel/issues/9014 for details. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_fix_package_group_reporoot_syntax`](#common_options-flag--incompatible_fix_package_group_reporoot_syntax) default: "true" -In package_group's `packages` attribute, changes the meaning of the value "//..." to refer to all packages in the current repository instead of all packages in any repository. You can use the special value "public" in place of "//..." to obtain the old behavior. This flag requires that --incompatible_package_group_has_public_syntax also be enabled. +`--incompatible_disable_transitions_on=<comma-separated set of options>` default: "" +: A comma-separated list of flags that cannot be used in transitions inputs or outputs. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]incompatible_locations_prefers_executable`](#common_options-flag--incompatible_locations_prefers_executable) default: "true" -Whether a target that provides an executable expands to the executable rather than the files in \<code\>DefaultInfo.files\</code\> under \$(locations ...) expansion if the number of files is not 1. +`--[no]incompatible_disallow_ctx_resolve_tools` default: "true" +: If set to true, calling the deprecated ctx.resolve\_tools API always fails. Uses of this API should be replaced by an executable or tools argument to ctx.actions.run or ctx.actions.run\_shell. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_no_attr_license`](#common_options-flag--incompatible_no_attr_license) default: "true" -If set to true, disables the function `attr.license`. +`--[no]incompatible_disallow_empty_glob` default: "true" +: If set to true, the default value of the `allow_empty` argument of glob() is False. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_no_implicit_file_export`](#common_options-flag--incompatible_no_implicit_file_export) default: "false" -If set, (used) source files are package private unless exported explicitly. See https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md +`--[no]incompatible_enable_deprecated_label_apis` default: "true" +: If enabled, certain deprecated APIs (native.repository\_name, Label.workspace\_name, Label.relative) can be used. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_no_implicit_watch_label`](#common_options-flag--incompatible_no_implicit_watch_label) default: "true" -If true, then methods on \<code\>repository_ctx\</code\> that are passed a Label will no longer automatically watch the file under that label for changes even if \<code\>watch = "no"\</code\>, and \<code\>repository_ctx.path\</code\> no longer causes the returned path to be watched. Use \<code\>repository_ctx.watch\</code\> instead. +`--[no]incompatible_fail_on_unknown_attributes` default: "true" +: If enabled, targets that have unknown attributes set to None fail. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_no_rule_outputs_param`](#common_options-flag--incompatible_no_rule_outputs_param) default: "false" -If set to true, disables the `outputs` parameter of the `rule()` Starlark function. +`--[no]incompatible_fix_package_group_reporoot_syntax` default: "true" +: In package\_group's `packages` attribute, changes the meaning of the value "//..." to refer to all packages in the current repository instead of all packages in any repository. You can use the special value "public" in place of "//..." to obtain the old behavior. This flag requires that --incompatible\_package\_group\_has\_public\_syntax also be enabled. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_package_group_has_public_syntax`](#common_options-flag--incompatible_package_group_has_public_syntax) default: "true" -In package_group's `packages` attribute, allows writing "public" or "private" to refer to all packages or no packages respectively. +`--[no]incompatible_locations_prefers_executable` default: "true" +: Whether a target that provides an executable expands to the executable rather than the files in \<code\>DefaultInfo.files\</code\> under $(locations ...) expansion if the number of files is not 1. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_resolve_select_keys_eagerly`](#common_options-flag--incompatible_resolve_select_keys_eagerly) default: "false" -If enabled, string keys in dicts passed to select() in .bzl files are immediately resolved to Labels relative to the file instead of being interpreted relative to the BUILD file they are ultimately loaded from. +`--[no]incompatible_no_attr_license` default: "true" +: If set to true, disables the function `attr.license`. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_run_shell_command_string`](#common_options-flag--incompatible_run_shell_command_string) default: "true" -If set to true, the command parameter of actions.run_shell will only accept string +`--[no]incompatible_no_implicit_file_export` default: "false" +: If set, (used) source files are package private unless exported explicitly. See https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_simplify_unconditional_selects_in_rule_attrs`](#common_options-flag--incompatible_simplify_unconditional_selects_in_rule_attrs) default: "true" -If true, simplify configurable rule attributes which contain only unconditional selects; for example, if \["a"\] + select("//conditions:default", \["b"\]) is assigned to a rule attribute, it is stored as \["a", "b"\]. This option does not affect attributes of symbolic macros or attribute default values. +`--[no]incompatible_no_implicit_watch_label` default: "true" +: If true, then methods on \<code\>repository\_ctx\</code\> that are passed a Label will no longer automatically watch the file under that label for changes even if \<code\>watch = "no"\</code\>, and \<code\>repository\_ctx.path\</code\> no longer causes the returned path to be watched. Use \<code\>repository\_ctx.watch\</code\> instead. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_stop_exporting_build_file_path`](#common_options-flag--incompatible_stop_exporting_build_file_path) default: "false" -If set to true, deprecated ctx.build_file_path will not be available. ctx.label.package + '/BUILD' can be used instead. +`--[no]incompatible_no_rule_outputs_param` default: "false" +: If set to true, disables the `outputs` parameter of the `rule()` Starlark function. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_stop_exporting_language_modules`](#common_options-flag--incompatible_stop_exporting_language_modules) default: "false" -If enabled, certain language-specific modules (such as `cc_common`) are unavailable in user .bzl files and may only be called from their respective rules repositories. +`--[no]incompatible_package_group_has_public_syntax` default: "true" +: In package\_group's `packages` attribute, allows writing "public" or "private" to refer to all packages or no packages respectively. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_unambiguous_label_stringification`](#common_options-flag--incompatible_unambiguous_label_stringification) default: "true" -When true, Bazel will stringify the label @//foo:bar to @//foo:bar, instead of //foo:bar. This only affects the behavior of str(), the % operator, and so on; the behavior of repr() is unchanged. See https://github.com/bazelbuild/bazel/issues/15916 for more information. +`--[no]incompatible_resolve_select_keys_eagerly` default: "false" +: If enabled, string keys in dicts passed to select() in .bzl files are immediately resolved to Labels relative to the file instead of being interpreted relative to the BUILD file they are ultimately loaded from. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_use_cc_configure_from_rules_cc`](#common_options-flag--incompatible_use_cc_configure_from_rules_cc) default: "false" -When true, Bazel will no longer allow using cc_configure from @bazel_tools. Please see https://github.com/bazelbuild/bazel/issues/10134 for details and migration instructions. +`--[no]incompatible_run_shell_command_string` default: "true" +: If set to true, the command parameter of actions.run\_shell will only accept string -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--max_computation_steps`](#common_options-flag--max_computation_steps)`=<a long integer>` default: "0" -The maximum number of Starlark computation steps that may be executed by a BUILD file (zero means no limit). +`--[no]incompatible_simplify_unconditional_selects_in_rule_attrs` default: "true" +: If true, simplify configurable rule attributes which contain only unconditional selects; for example, if ["a"] + select("//conditions:default", ["b"]) is assigned to a rule attribute, it is stored as ["a", "b"]. This option does not affect attributes of symbolic macros or attribute default values. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--nested_set_depth_limit`](#common_options-flag--nested_set_depth_limit)`=<an integer>` default: "3500" -The maximum depth of the graph internal to a depset (also known as NestedSet), above which the depset() constructor will fail. +`--[no]incompatible_stop_exporting_build_file_path` default: "false" +: If set to true, deprecated ctx.build\_file\_path will not be available. ctx.label.package + '/BUILD' can be used instead. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--repositories_without_autoloads`](#common_options-flag--repositories_without_autoloads)`=<comma-separated set of options>` default: "" -A list of additional repositories (beyond the hardcoded ones Bazel knows about) where autoloads are not to be added. This should typically contain repositories that are transitively depended on by a repository that may be loaded automatically (and which can therefore potentially create a cycle). +`--[no]incompatible_stop_exporting_language_modules` default: "false" +: If enabled, certain language-specific modules (such as `cc_common`) are unavailable in user .bzl files and may only be called from their respective rules repositories. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +`--[no]incompatible_unambiguous_label_stringification` default: "true" +: When true, Bazel will stringify the label @//foo:bar to @//foo:bar, instead of //foo:bar. This only affects the behavior of str(), the % operator, and so on; the behavior of repr() is unchanged. See https://github.com/bazelbuild/bazel/issues/15916 for more information. -[`--allow_yanked_versions`](#common_options-flag--allow_yanked_versions)`=<a string>` multiple uses are accumulated -Specified the module versions in the form of `<module1>@<version1>,<module2>@<version2>` that will be allowed in the resolved dependency graph even if they are declared yanked in the registry where they come from (if they are not coming from a NonRegistryOverride). Otherwise, yanked versions will cause the resolution to fail. You can also define allowed yanked version with the `BZLMOD_ALLOW_YANKED_VERSIONS` environment variable. You can disable this check by using the keyword 'all' (not recommended). + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_use_cc_configure_from_rules_cc` default: "false" +: When true, Bazel will no longer allow using cc\_configure from @bazel\_tools. Please see https://github.com/bazelbuild/bazel/issues/10134 for details and migration instructions. -[`--check_bazel_compatibility`](#common_options-flag--check_bazel_compatibility)`=<error, warning or off>` default: "error" -Check bazel version compatibility of Bazel modules. Valid values are `error` to escalate it to a resolution failure, `off` to disable the check, or `warning` to print a warning when mismatch detected. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--max_computation_steps=<a long integer>` default: "0" +: The maximum number of Starlark computation steps that may be executed by a BUILD file (zero means no limit). -[`--check_direct_dependencies`](#common_options-flag--check_direct_dependencies)`=<off, warning or error>` default: "warning" -Check if the direct `bazel_dep` dependencies declared in the root module are the same versions you get in the resolved dependency graph. Valid values are `off` to disable the check, `warning` to print a warning when mismatch detected or `error` to escalate it to a resolution failure. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--nested_set_depth_limit=<an integer>` default: "3500" +: The maximum depth of the graph internal to a depset (also known as NestedSet), above which the depset() constructor will fail. -[`--[no]ignore_dev_dependency`](#common_options-flag--ignore_dev_dependency) default: "false" -If true, Bazel ignores `bazel_dep` and `use_extension` declared as `dev_dependency` in the MODULE.bazel of the root module. Note that, those dev dependencies are always ignored in the MODULE.bazel if it's not the root module regardless of the value of this flag. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--repositories_without_autoloads=<comma-separated set of options>` default: "" +: A list of additional repositories (beyond the hardcoded ones Bazel knows about) where autoloads are not to be added. This should typically contain repositories that are transitively depended on by a repository that may be loaded automatically (and which can therefore potentially create a cycle). -[`--lockfile_mode`](#common_options-flag--lockfile_mode)`=<off, update, refresh or error>` default: "update" -Specifies how and whether or not to use the lockfile. Valid values are `update` to use the lockfile and update it if there are changes, `refresh` to additionally refresh mutable information (yanked versions and previously missing modules) from remote registries from time to time, `error` to use the lockfile but throw an error if it's not up-to-date, or `off` to neither read from or write to the lockfile. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +Options relating to Bzlmod output and semantics: -[`--module_mirrors`](#common_options-flag--module_mirrors)`=<comma-separated list of options>` default: see description -A comma-separated list of URLs under which the source URLs of Bazel modules can be found, -in addition to and taking precedence over any registry-provided mirror URLs. Set this to -an empty value to disable the use of any mirrors not specified by the registries. The -default set of mirrors may change over time, but all downloads from mirrors are verified -by hashes stored in the registry (and thus pinned by the lockfile). +`--allow_yanked_versions=<a string>` multiple uses are accumulated +: Specified the module versions in the form of `<module1>@<version1>,<module2>@<version2>` that will be allowed in the resolved dependency graph even if they are declared yanked in the registry where they come from (if they are not coming from a NonRegistryOverride). Otherwise, yanked versions will cause the resolution to fail. You can also define allowed yanked version with the `BZLMOD_ALLOW_YANKED_VERSIONS` environment variable. You can disable this check by using the keyword 'all' (not recommended). -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--override_module`](#common_options-flag--override_module)`=<an equals-separated mapping of module name to path>` multiple uses are accumulated -Override a module with a local path in the form of \<module name\>=\<path\>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. +`--check_bazel_compatibility=<error, warning or off>` default: "error" +: Check bazel version compatibility of Bazel modules. Valid values are `error` to escalate it to a resolution failure, `off` to disable the check, or `warning` to print a warning when mismatch detected. -[`--registry`](#common_options-flag--registry)`=<a string>` multiple uses are accumulated -Specifies the registries to use to locate Bazel module dependencies. The order is important: modules will be looked up in earlier registries first, and only fall back to later registries when they're missing from the earlier ones. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--check_direct_dependencies=<off, warning or error>` default: "warning" +: Check if the direct `bazel_dep` dependencies declared in the root module are the same versions you get in the resolved dependency graph. Valid values are `off` to disable the check, `warning` to print a warning when mismatch detected or `error` to escalate it to a resolution failure. -[`--vendor_dir`](#common_options-flag--vendor_dir)`=<a path>` default: see description -Specifies the directory that should hold the external repositories in vendor mode, whether for the purpose of fetching them into it or using them while building. The path can be specified as either an absolute path or a path relative to the workspace directory. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]ignore_dev_dependency` default: "false" +: If true, Bazel ignores `bazel_dep` and `use_extension` declared as `dev_dependency` in the MODULE.bazel of the root module. Note that, those dev dependencies are always ignored in the MODULE.bazel if it's not the root module regardless of the value of this flag. -<!-- --> + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--gc_thrashing_limits`](#common_options-flag--gc_thrashing_limits)`=<comma separated pairs of <period>:<count>>` default: "1s:2,20s:3,1m:5" -Limits which, if reached, cause GcThrashingDetector to crash Bazel with an OOM. Each limit is specified as \<period\>:\<count\> where period is a duration and count is a positive integer. If more than --gc_thrashing_threshold percent of tenured space (old gen heap) remains occupied after \<count\> consecutive full GCs within \<period\>, an OOM is triggered. Multiple limits can be specified separated by commas. +`--lockfile_mode=<off, update, refresh or error>` default: "update" +: Specifies how and whether or not to use the lockfile. Valid values are `update` to use the lockfile and update it if there are changes, `refresh` to additionally refresh mutable information (yanked versions and previously missing modules) from remote registries from time to time, `error` to use the lockfile but throw an error if it's not up-to-date, or `off` to neither read from or write to the lockfile. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]heuristically_drop_nodes`](#common_options-flag--heuristically_drop_nodes) default: "false" -If true, Blaze will remove FileState and DirectoryListingState nodes after related File and DirectoryListing node is done to save memory. We expect that it is less likely that these nodes will be needed again. If so, the program will re-evaluate them. +`--module_mirrors=<comma-separated list of options>` default: see description +: A comma-separated list of URLs under which the source URLs of Bazel modules can be found, + in addition to and taking precedence over any registry-provided mirror URLs. Set this to + an empty value to disable the use of any mirrors not specified by the registries. The + default set of mirrors may change over time, but all downloads from mirrors are verified + by hashes stored in the registry (and thus pinned by the lockfile). -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_do_not_split_linking_cmdline`](#common_options-flag--incompatible_do_not_split_linking_cmdline) default: "true" -When true, Bazel no longer modifies command line flags used for linking, and also doesn't selectively decide which flags go to the param file and which don't. See https://github.com/bazelbuild/bazel/issues/7670 for details. +`--override_module=<an equals-separated mapping of module name to path>` multiple uses are accumulated +: Override a module with a local path in the form of <module name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--registry=<a string>` multiple uses are accumulated +: Specifies the registries to use to locate Bazel module dependencies. The order is important: modules will be looked up in earlier registries first, and only fall back to later registries when they're missing from the earlier ones. -[`--[no]keep_state_after_build`](#common_options-flag--keep_state_after_build) default: "true" -If false, Blaze will discard the inmemory state from this build when the build finishes. Subsequent builds will not have any incrementality with respect to this one. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--vendor_dir=<a path>` default: see description +: Specifies the directory that should hold the external repositories in vendor mode, whether for the purpose of fetching them into it or using them while building. The path can be specified as either an absolute path or a path relative to the workspace directory. -[`--skyframe_high_water_mark_full_gc_drops_per_invocation`](#common_options-flag--skyframe_high_water_mark_full_gc_drops_per_invocation)`=<an integer, >= 0>` default: "10" -Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe_high_water_mark_threshold, when a full GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that full GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a full GC event occurs and that retained heap percentage threshold is exceeded. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +Options that trigger optimizations of the build time: -[`--skyframe_high_water_mark_minor_gc_drops_per_invocation`](#common_options-flag--skyframe_high_water_mark_minor_gc_drops_per_invocation)`=<an integer, >= 0>` default: "10" -Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe_high_water_mark_threshold, when a minor GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that minor GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a minor GC event occurs and that retained heap percentage threshold is exceeded. +`--gc_thrashing_limits=<comma separated pairs of <period>:<count>>` default: "1s:2,20s:3,1m:5" +: Limits which, if reached, cause GcThrashingDetector to crash Bazel with an OOM. Each limit is specified as \<period\>:\<count\> where period is a duration and count is a positive integer. If more than --gc\_thrashing\_threshold percent of tenured space (old gen heap) remains occupied after \<count\> consecutive full GCs within \<period\>, an OOM is triggered. Multiple limits can be specified separated by commas. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--skyframe_high_water_mark_threshold`](#common_options-flag--skyframe_high_water_mark_threshold)`=<an integer>` default: "85" -Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage is at least this threshold, it will drop unnecessary temporary Skyframe state. Tweaking this may let you mitigate wall time impact of GC thrashing, when the GC thrashing is (i) caused by the memory usage of this temporary state and (ii) more costly than reconstituting the state when it is needed. +`--[no]heuristically_drop_nodes` default: "false" +: If true, Blaze will remove FileState and DirectoryListingState nodes after related File and DirectoryListing node is done to save memory. We expect that it is less likely that these nodes will be needed again. If so, the program will re-evaluate them. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]track_incremental_state`](#common_options-flag--track_incremental_state) default: "true" -If false, Blaze will not persist data that allows for invalidation and re-evaluation on incremental builds in order to save memory on this build. Subsequent builds will not have any incrementality with respect to this one. Usually you will want to specify --batch when setting this to false. +`--[no]incompatible_do_not_split_linking_cmdline` default: "true" +: When true, Bazel no longer modifies command line flags used for linking, and also doesn't selectively decide which flags go to the param file and which don't. See https://github.com/bazelbuild/bazel/issues/7670 for details. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +`--[no]keep_state_after_build` default: "true" +: If false, Blaze will discard the inmemory state from this build when the build finishes. Subsequent builds will not have any incrementality with respect to this one. -[`--[no]announce_rc`](#common_options-flag--announce_rc) default: "false" -Whether to announce rc options. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--skyframe_high_water_mark_full_gc_drops_per_invocation=<an integer, >= 0>` default: "10" +: Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe\_high\_water\_mark\_threshold, when a full GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that full GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a full GC event occurs and that retained heap percentage threshold is exceeded. -[`--[no]attempt_to_print_relative_paths`](#common_options-flag--attempt_to_print_relative_paths) default: "false" -When printing the location part of messages, attempt to use a path relative to the workspace directory or one of the directories specified by --package_path. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--skyframe_high_water_mark_minor_gc_drops_per_invocation=<an integer, >= 0>` default: "10" +: Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe\_high\_water\_mark\_threshold, when a minor GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that minor GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a minor GC event occurs and that retained heap percentage threshold is exceeded. -[`--bes_backend`](#common_options-flag--bes_backend)`=<a string>` default: "" -Specifies the build event service (BES) backend endpoint in the form \[SCHEME://\]HOST\[:PORT\]. The default is to disable BES uploads. Supported schemes are grpc and grpcs (grpc with TLS enabled). If no scheme is provided, Bazel assumes grpcs. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--skyframe_high_water_mark_threshold=<an integer>` default: "85" +: Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage is at least this threshold, it will drop unnecessary temporary Skyframe state. Tweaking this may let you mitigate wall time impact of GC thrashing, when the GC thrashing is (i) caused by the memory usage of this temporary state and (ii) more costly than reconstituting the state when it is needed. -[`--[no]bes_check_preceding_lifecycle_events`](#common_options-flag--bes_check_preceding_lifecycle_events) default: "false" -Sets the field check_preceding_lifecycle_events_present on PublishBuildToolEventStreamRequest which tells BES to check whether it previously received InvocationAttemptStarted and BuildEnqueued events matching the current tool event. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]track_incremental_state` default: "true" +: If false, Blaze will not persist data that allows for invalidation and re-evaluation on incremental builds in order to save memory on this build. Subsequent builds will not have any incrementality with respect to this one. Usually you will want to specify --batch when setting this to false. -[`--bes_header`](#common_options-flag--bes_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header in NAME=VALUE form that will be included in BES requests. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that affect the verbosity, format or location of logging: -[`--bes_instance_name`](#common_options-flag--bes_instance_name)`=<a string>` default: see description -Specifies the instance name under which the BES will persist uploaded BEP. Defaults to null. +`--[no]announce_rc` default: "false" +: Whether to announce rc options. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--bes_keywords`](#common_options-flag--bes_keywords)`=<comma-separated list of options>` multiple uses are accumulated -Specifies a list of notification keywords to be added the default set of keywords published to BES ("command_name=\<command_name\> ", "protocol_name=BEP"). Defaults to none. +`--[no]attempt_to_print_relative_paths` default: "false" +: When printing the location part of messages, attempt to use a path relative to the workspace directory or one of the directories specified by --package\_path. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]bes_lifecycle_events`](#common_options-flag--bes_lifecycle_events) default: "true" -Specifies whether to publish BES lifecycle events. (defaults to 'true'). +`--bes_backend=<a string>` default: "" +: Specifies the build event service (BES) backend endpoint in the form [SCHEME://]HOST[:PORT]. The default is to disable BES uploads. Supported schemes are grpc and grpcs (grpc with TLS enabled). If no scheme is provided, Bazel assumes grpcs. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--bes_oom_finish_upload_timeout`](#common_options-flag--bes_oom_finish_upload_timeout)`=<An immutable length of time.>` default: "10m" -Specifies how long bazel should wait for the BES/BEP upload to complete while OOMing. This flag ensures termination when the JVM is severely GC thrashing and cannot make progress on any user thread. +`--[no]bes_check_preceding_lifecycle_events` default: "false" +: Sets the field check\_preceding\_lifecycle\_events\_present on PublishBuildToolEventStreamRequest which tells BES to check whether it previously received InvocationAttemptStarted and BuildEnqueued events matching the current tool event. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--bes_outerr_buffer_size`](#common_options-flag--bes_outerr_buffer_size)`=<an integer>` default: "10240" -Specifies the maximal size of stdout or stderr to be buffered in BEP, before it is reported as a progress event. Individual writes are still reported in a single event, even if larger than the specified value up to --bes_outerr_chunk_size. +`--bes_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header in NAME=VALUE form that will be included in BES requests. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--bes_outerr_chunk_size`](#common_options-flag--bes_outerr_chunk_size)`=<an integer>` default: "1048576" -Specifies the maximal size of stdout or stderr to be sent to BEP in a single message. +`--bes_instance_name=<a string>` default: see description +: Specifies the instance name under which the BES will persist uploaded BEP. Defaults to null. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--bes_proxy`](#common_options-flag--bes_proxy)`=<a string>` default: see description -Connect to the Build Event Service through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). +`--bes_keywords=<comma-separated list of options>` multiple uses are accumulated +: Specifies a list of notification keywords to be added the default set of keywords published to BES ("command\_name=\<command\_name\> ", "protocol\_name=BEP"). Defaults to none. -[`--bes_results_url`](#common_options-flag--bes_results_url)`=<a string>` default: "" -Specifies the base URL where a user can view the information streamed to the BES backend. Bazel will output the URL appended by the invocation id to the terminal. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]bes_lifecycle_events` default: "true" +: Specifies whether to publish BES lifecycle events. (defaults to 'true'). -[`--bes_system_keywords`](#common_options-flag--bes_system_keywords)`=<comma-separated list of options>` multiple uses are accumulated -Specifies a list of notification keywords to be included directly, without the "user_keyword=" prefix included for keywords supplied via --bes_keywords. Intended for Build service operators that set --bes_lifecycle_events=false and include keywords when calling PublishLifecycleEvent. Build service operators using this flag should prevent users from overriding the flag value. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--bes_oom_finish_upload_timeout=<An immutable length of time.>` default: "10m" +: Specifies how long bazel should wait for the BES/BEP upload to complete while OOMing. This flag ensures termination when the JVM is severely GC thrashing and cannot make progress on any user thread. -[`--bes_timeout`](#common_options-flag--bes_timeout)`=<An immutable length of time.>` default: "0s" -Specifies how long bazel should wait for the BES/BEP upload to complete after the build and tests have finished. A valid timeout is a natural number followed by a unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The default value is '0' which means that there is no timeout. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--bes_outerr_buffer_size=<an integer>` default: "10240" +: Specifies the maximal size of stdout or stderr to be buffered in BEP, before it is reported as a progress event. Individual writes are still reported in a single event, even if larger than the specified value up to --bes\_outerr\_chunk\_size. -[`--bes_upload_mode`](#common_options-flag--bes_upload_mode)`=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait_for_upload_complete" -Specifies whether the Build Event Service upload should block the build completion or should end the invocation immediately and finish the upload in the background. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -- `wait_for_upload_complete`: blocks at the end of the current invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. -- `nowait_for_upload_complete`: blocks at the beginning of the next invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. -- `fully_async`: blocks at the beginning of the next invocation until all events are uploaded but does not wait for acknowledgements. Events may be lost in case of (transient) failures and backends may report streams as incomplete in this mode. There is no guarantee that `FinishInvocationAttempt` or `FinishBuild` lifecycle events are sent. +`--bes_outerr_chunk_size=<an integer>` default: "1048576" +: Specifies the maximal size of stdout or stderr to be sent to BEP in a single message. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--build_event_binary_file`](#common_options-flag--build_event_binary_file)`=<a string>` default: "" -If non-empty, write a varint delimited binary representation of representation of the build event protocol to that file. This option implies --bes_upload_mode=wait_for_upload_complete. +`--bes_proxy=<a string>` default: see description +: Connect to the Build Event Service through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--bes_results_url=<a string>` default: "" +: Specifies the base URL where a user can view the information streamed to the BES backend. Bazel will output the URL appended by the invocation id to the terminal. -[`--[no]build_event_binary_file_path_conversion`](#common_options-flag--build_event_binary_file_path_conversion) default: "true" -Convert paths in the binary file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--bes_system_keywords=<comma-separated list of options>` multiple uses are accumulated +: Specifies a list of notification keywords to be included directly, without the "user\_keyword=" prefix included for keywords supplied via --bes\_keywords. Intended for Build service operators that set --bes\_lifecycle\_events=false and include keywords when calling PublishLifecycleEvent. Build service operators using this flag should prevent users from overriding the flag value. -[`--build_event_binary_file_upload_mode`](#common_options-flag--build_event_binary_file_upload_mode)`=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait_for_upload_complete" -Specifies whether the Build Event Service upload for --build_event_binary_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--bes_timeout=<An immutable length of time.>` default: "0s" +: Specifies how long bazel should wait for the BES/BEP upload to complete after the build and tests have finished. A valid timeout is a natural number followed by a unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The default value is '0' which means that there is no timeout. -[`--build_event_json_file`](#common_options-flag--build_event_json_file)`=<a string>` default: "" -If non-empty, write a JSON serialisation of the build event protocol to that file. This option implies --bes_upload_mode=wait_for_upload_complete. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--bes_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" +: Specifies whether the Build Event Service upload should block the build completion or should end the invocation immediately and finish the upload in the background. -[`--[no]build_event_json_file_path_conversion`](#common_options-flag--build_event_json_file_path_conversion) default: "true" -Convert paths in the json file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used + * `wait_for_upload_complete`: blocks at the end of the current invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. + * `nowait_for_upload_complete`: blocks at the beginning of the next invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. + * `fully_async`: blocks at the beginning of the next invocation until all events are uploaded but does not wait for acknowledgements. Events may be lost in case of (transient) failures and backends may report streams as incomplete in this mode. There is no guarantee that `FinishInvocationAttempt` or `FinishBuild` lifecycle events are sent. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--build_event_json_file_upload_mode`](#common_options-flag--build_event_json_file_upload_mode)`=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait_for_upload_complete" -Specifies whether the Build Event Service upload for --build_event_json_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'. +`--build_event_binary_file=<a string>` default: "" +: If non-empty, write a varint delimited binary representation of representation of the build event protocol to that file. This option implies --bes\_upload\_mode=wait\_for\_upload\_complete. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--build_event_max_named_set_of_file_entries`](#common_options-flag--build_event_max_named_set_of_file_entries)`=<an integer>` default: "5000" -The maximum number of entries for a single named_set_of_files event; values smaller than 2 are ignored and no event splitting is performed. This is intended for limiting the maximum event size in the build event protocol, although it does not directly control event size. The total event size is a function of the structure of the set as well as the file and uri lengths, which may in turn depend on the hash function. +`--[no]build_event_binary_file_path_conversion` default: "true" +: Convert paths in the binary file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]build_event_publish_all_actions`](#common_options-flag--build_event_publish_all_actions) default: "false" -Whether all actions should be published. +`--build_event_binary_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" +: Specifies whether the Build Event Service upload for --build\_event\_binary\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--build_event_text_file`](#common_options-flag--build_event_text_file)`=<a string>` default: "" -If non-empty, write a textual representation of the build event protocol to that file +`--build_event_json_file=<a string>` default: "" +: If non-empty, write a JSON serialisation of the build event protocol to that file. This option implies --bes\_upload\_mode=wait\_for\_upload\_complete. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]build_event_text_file_path_conversion`](#common_options-flag--build_event_text_file_path_conversion) default: "true" -Convert paths in the text file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used +`--[no]build_event_json_file_path_conversion` default: "true" +: Convert paths in the json file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--build_event_text_file_upload_mode`](#common_options-flag--build_event_text_file_upload_mode)`=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait_for_upload_complete" -Specifies whether the Build Event Service upload for --build_event_text_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait_for_upload_complete' (default), 'nowait_for_upload_complete', or 'fully_async'. +`--build_event_json_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" +: Specifies whether the Build Event Service upload for --build\_event\_json\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--build_event_upload_max_retries`](#common_options-flag--build_event_upload_max_retries)`=<an integer>` default: "4" -The maximum number of times Bazel should retry uploading a build event. +`--build_event_max_named_set_of_file_entries=<an integer>` default: "5000" +: The maximum number of entries for a single named\_set\_of\_files event; values smaller than 2 are ignored and no event splitting is performed. This is intended for limiting the maximum event size in the build event protocol, although it does not directly control event size. The total event size is a function of the structure of the set as well as the file and uri lengths, which may in turn depend on the hash function. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_bep_target_summary`](#common_options-flag--experimental_bep_target_summary) default: "false" -Whether to publish TargetSummary events. +`--[no]build_event_publish_all_actions` default: "false" +: Whether all actions should be published. -[`--[no]experimental_build_event_expand_filesets`](#common_options-flag--experimental_build_event_expand_filesets) default: "false" -If true, expand Filesets in the BEP when presenting output files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--build_event_text_file=<a string>` default: "" +: If non-empty, write a textual representation of the build event protocol to that file -[`--experimental_build_event_output_group_mode`](#common_options-flag--experimental_build_event_output_group_mode)`=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated -Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED_SET_OF_FILES_ONLY', 'INLINE_ONLY', or 'BOTH'. The default value is 'NAMED_SET_OF_FILES_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental_build_event_output_group_mode=baseline.lcov=both + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]build_event_text_file_path_conversion` default: "true" +: Convert paths in the text file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used -[`--experimental_build_event_upload_retry_minimum_delay`](#common_options-flag--experimental_build_event_upload_retry_minimum_delay)`=<An immutable length of time.>` default: "1s" -Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +`--build_event_text_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" +: Specifies whether the Build Event Service upload for --build\_event\_text\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. -[`--experimental_build_event_upload_strategy`](#common_options-flag--experimental_build_event_upload_strategy)`=<a string>` default: see description -Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--build_event_upload_max_retries=<an integer>` default: "4" +: The maximum number of times Bazel should retry uploading a build event. -[`--[no]experimental_collect_load_average_in_profiler`](#common_options-flag--experimental_collect_load_average_in_profiler) default: "true" -If enabled, the profiler collects the system's overall load average. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]experimental_bep_target_summary` default: "false" +: Whether to publish TargetSummary events. -[`--[no]experimental_collect_pressure_stall_indicators`](#common_options-flag--experimental_collect_pressure_stall_indicators) default: "false" -If enabled, the profiler collects the Linux PSI data. +`--[no]experimental_build_event_expand_filesets` default: "false" +: If true, expand Filesets in the BEP when presenting output files. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_collect_resource_estimation`](#common_options-flag--experimental_collect_resource_estimation) default: "false" -If enabled, the profiler collects CPU and memory usage estimation for local actions. +`--experimental_build_event_output_group_mode=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated +: Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED\_SET\_OF\_FILES\_ONLY', 'INLINE\_ONLY', or 'BOTH'. The default value is 'NAMED\_SET\_OF\_FILES\_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental\_build\_event\_output\_group\_mode=baseline.lcov=both -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_collect_skyframe_counts_in_profiler`](#common_options-flag--experimental_collect_skyframe_counts_in_profiler) default: "false" -If enabled, the profiler collects SkyFunction counts in the Skyframe graph over time for key function types, like configured targets and action executions. May have a performance hit as this visits the ENTIRE Skyframe graph at every profiling time unit. Do not use this flag with performance-critical measurements. +`--experimental_build_event_upload_retry_minimum_delay=<An immutable length of time.>` default: "1s" +: Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--[no]experimental_collect_system_network_usage`](#common_options-flag--experimental_collect_system_network_usage) default: "true" -If enabled, the profiler collects the system's network usage. +`--experimental_build_event_upload_strategy=<a string>` default: see description +: Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_collect_worker_data_in_profiler`](#common_options-flag--experimental_collect_worker_data_in_profiler) default: "true" -If enabled, the profiler collects worker's aggregated resource data. +`--[no]experimental_collect_load_average_in_profiler` default: "true" +: If enabled, the profiler collects the system's overall load average. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--experimental_command_profile`](#common_options-flag--experimental_command_profile)`=<cpu, wall, alloc or lock>` default: see description -Records a Java Flight Recorder profile for the duration of the command. One of the supported profiling event types (cpu, wall, alloc or lock) must be given as an argument. The profile is written to a file named after the event type under the output base directory. The syntax and semantics of this flag might change in the future to support additional profile types or output formats; use at your own risk. +`--[no]experimental_collect_pressure_stall_indicators` default: "false" +: If enabled, the profiler collects the Linux PSI data. -[`--experimental_profile_additional_tasks`](#common_options-flag--experimental_profile_additional_tasks)`=<phase, action, discover_inputs, action_check, action_lock, action_update, action_complete, action_rewinding, bzlmod, info, create_package, remote_execution, local_execution, scanner, local_parse, upload_time, remote_process_time, remote_queue, remote_setup, fetch, local_process_time, vfs_stat, vfs_dir, vfs_readlink, vfs_md5, vfs_xattr, vfs_delete, vfs_open, vfs_read, vfs_write, vfs_glob, vfs_vmfs_stat, vfs_vmfs_dir, vfs_vmfs_read, wait, thread_name, thread_sort_index, skyframe_eval, skyfunction, critical_path, critical_path_component, handle_gc_notification, local_action_counts, starlark_parser, starlark_user_fn, starlark_builtin_fn, starlark_user_compiled_fn, starlark_repository_fn, action_fs_staging, remote_cache_check, remote_download, remote_network, filesystem_traversal, worker_execution, worker_setup, worker_borrow, worker_working, worker_copying_outputs, credential_helper, conflict_check, dynamic_lock, repository_fetch, repository_vendor, repo_cache_gc_wait, spawn_log, rpc, skycache, wasm_load, wasm_exec or unknown>` multiple uses are accumulated -Specifies additional profile tasks to be included in the profile. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]experimental_collect_resource_estimation` default: "false" +: If enabled, the profiler collects CPU and memory usage estimation for local actions. -[`--[no]experimental_profile_include_primary_output`](#common_options-flag--experimental_profile_include_primary_output) default: "false" -Includes the extra "out" attribute in action events that contains the exec path to the action's primary output. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]experimental_collect_skyframe_counts_in_profiler` default: "false" +: If enabled, the profiler collects SkyFunction counts in the Skyframe graph over time for key function types, like configured targets and action executions. May have a performance hit as this visits the ENTIRE Skyframe graph at every profiling time unit. Do not use this flag with performance-critical measurements. -[`--[no]experimental_profile_include_target_configuration`](#common_options-flag--experimental_profile_include_target_configuration) default: "false" -Includes target configuration hash in action events' JSON profile data. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]experimental_collect_system_network_usage` default: "true" +: If enabled, the profiler collects the system's network usage. -[`--[no]experimental_profile_include_target_label`](#common_options-flag--experimental_profile_include_target_label) default: "false" -Includes target label in action events' JSON profile data. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]experimental_collect_worker_data_in_profiler` default: "true" +: If enabled, the profiler collects worker's aggregated resource data. -[`--[no]experimental_record_metrics_for_all_mnemonics`](#common_options-flag--experimental_record_metrics_for_all_mnemonics) default: "false" -Controls the output of BEP ActionSummary and BuildGraphMetrics, limiting the number of mnemonics in ActionData and number of entries reported in BuildGraphMetrics.AspectCount/RuleClassCount. By default the number of types is limited to the top 20, by number of executed actions for ActionData, and instances for RuleClass and Asepcts. Setting this option will write statistics for all mnemonics, rule classes and aspects. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]experimental_record_skyframe_metrics`](#common_options-flag--experimental_record_skyframe_metrics) default: "false" -Controls the output of BEP BuildGraphMetrics, including expensiveto compute skyframe metrics about Skykeys, RuleClasses and Aspects.With this flag set to false BuildGraphMetrics.rule_count and aspectfields will not be populated in the BEP. +`--experimental_command_profile=<cpu, wall, alloc or lock>` default: see description +: Records a Java Flight Recorder profile for the duration of the command. One of the supported profiling event types (cpu, wall, alloc or lock) must be given as an argument. The profile is written to a file named after the event type under the output base directory. The syntax and semantics of this flag might change in the future to support additional profile types or output formats; use at your own risk. -[`--[no]experimental_run_bep_event_include_residue`](#common_options-flag--experimental_run_bep_event_include_residue) default: "false" -Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. +`--experimental_profile_additional_tasks=<phase, action, discover_inputs, action_check, action_lock, action_update, action_complete, action_rewinding, bzlmod, info, create_package, remote_execution, local_execution, scanner, local_parse, upload_time, remote_process_time, remote_queue, remote_setup, fetch, local_process_time, vfs_stat, vfs_dir, vfs_readlink, vfs_md5, vfs_xattr, vfs_delete, vfs_open, vfs_read, vfs_write, vfs_glob, vfs_vmfs_stat, vfs_vmfs_dir, vfs_vmfs_read, wait, thread_name, thread_sort_index, skyframe_eval, skyfunction, critical_path, critical_path_component, handle_gc_notification, local_action_counts, starlark_parser, starlark_user_fn, starlark_builtin_fn, starlark_user_compiled_fn, starlark_repository_fn, action_fs_staging, remote_cache_check, remote_download, remote_network, filesystem_traversal, worker_execution, worker_setup, worker_borrow, worker_working, worker_copying_outputs, credential_helper, conflict_check, dynamic_lock, repository_fetch, repository_vendor, repo_cache_gc_wait, spawn_log, rpc, skycache, wasm_load, wasm_exec or unknown>` multiple uses are accumulated +: Specifies additional profile tasks to be included in the profile. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]experimental_stream_log_file_uploads`](#common_options-flag--experimental_stream_log_file_uploads) default: "false" -Stream log file uploads directly to the remote storage rather than writing them to disk. +`--[no]experimental_profile_include_primary_output` default: "false" +: Includes the extra "out" attribute in action events that contains the exec path to the action's primary output. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--experimental_workspace_rules_log_file`](#common_options-flag--experimental_workspace_rules_log_file)`=<a path>` default: see description -Log certain Workspace Rules events into this file as delimited WorkspaceEvent protos. +`--[no]experimental_profile_include_target_configuration` default: "false" +: Includes target configuration hash in action events' JSON profile data. -[`--[no]generate_json_trace_profile`](#common_options-flag--generate_json_trace_profile) default: "auto" -If enabled, Bazel profiles the build and writes a JSON-format profile into a file in the output base. View profile by loading into chrome://tracing. By default Bazel writes the profile for all build-like commands and query. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]experimental_profile_include_target_label` default: "false" +: Includes target label in action events' JSON profile data. -[`--[no]heap_dump_on_oom`](#common_options-flag--heap_dump_on_oom) default: "false" -Whether to manually output a heap dump if an OOM is thrown (including manual OOMs due to reaching --gc_thrashing_limits). The dump will be written to \<output_base\>/\<invocation_id\>.heapdump.hprof. This option effectively replaces -XX:+HeapDumpOnOutOfMemoryError, which has no effect for manual OOMs. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]experimental_record_metrics_for_all_mnemonics` default: "false" +: Controls the output of BEP ActionSummary and BuildGraphMetrics, limiting the number of mnemonics in ActionData and number of entries reported in BuildGraphMetrics.AspectCount/RuleClassCount. By default the number of types is limited to the top 20, by number of executed actions for ActionData, and instances for RuleClass and Asepcts. Setting this option will write statistics for all mnemonics, rule classes and aspects. -[`--jvm_heap_histogram_internal_object_pattern`](#common_options-flag--jvm_heap_histogram_internal_object_pattern)`=<a valid Java regular expression>` default: "jdk\\internal\\vm\\Filler.+" -Regex for overriding the matching logic for JDK21+ JVM heap memory collection. We are relying on volatile internal G1 GC implemenation details to get a clean memory metric, this option allows us to adapt to changes in that internal implementation without having to wait for a binary release. Passed to JDK Matcher.find() +`--[no]experimental_record_skyframe_metrics` default: "false" +: Controls the output of BEP BuildGraphMetrics, including expensiveto compute skyframe metrics about Skykeys, RuleClasses and Aspects.With this flag set to false BuildGraphMetrics.rule\_count and aspectfields will not be populated in the BEP. -[`--[no]legacy_important_outputs`](#common_options-flag--legacy_important_outputs) default: "false" -Use this to suppress generation of the legacy important_outputs field in the TargetComplete event. important_outputs are required for Bazel to ResultStore/BTX integration. +`--[no]experimental_run_bep_event_include_residue` default: "false" +: Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--logging`](#common_options-flag--logging)`=<0 <= an integer <= 6>` default: "3" -The logging level. +`--[no]experimental_stream_log_file_uploads` default: "false" +: Stream log file uploads directly to the remote storage rather than writing them to disk. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--memory_profile`](#common_options-flag--memory_profile)`=<a path>` default: see description -If set, write memory usage data to the specified file at phase ends and stable heap to master log at end of build. +`--experimental_workspace_rules_log_file=<a path>` default: see description +: Log certain Workspace Rules events into this file as delimited WorkspaceEvent protos. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]generate_json_trace_profile` default: "auto" +: If enabled, Bazel profiles the build and writes a JSON-format profile into a file in the output base. View profile by loading into chrome://tracing. By default Bazel writes the profile for all build-like commands and query. -[`--memory_profile_stable_heap_parameters`](#common_options-flag--memory_profile_stable_heap_parameters)`=<integers, separated by a comma expected in pairs>` default: "1,0" -Tune memory profile's computation of stable heap at end of build. Should be and even number of integers separated by commas. In each pair the first integer is the number of GCs to perform. The second integer in each pair is the number of seconds to wait between GCs. Ex: 2,4,4,0 would 2 GCs with a 4sec pause, followed by 4 GCs with zero second pause + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--[no]heap_dump_on_oom` default: "false" +: Whether to manually output a heap dump if an OOM is thrown (including manual OOMs due to reaching --gc\_thrashing\_limits). The dump will be written to \<output\_base\>/\<invocation\_id\>.heapdump.hprof. This option effectively replaces -XX:+HeapDumpOnOutOfMemoryError, which has no effect for manual OOMs. -[`--profile`](#common_options-flag--profile)`=<a path>` default: see description -If set, profile Bazel and write data to the specified file. See https://bazel.build/advanced/performance/json-trace-profile for more information. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--jvm_heap_histogram_internal_object_pattern=<a valid Java regular expression>` default: "jdk\.internal\.vm\.Filler.+" +: Regex for overriding the matching logic for JDK21+ JVM heap memory collection. We are relying on volatile internal G1 GC implemenation details to get a clean memory metric, this option allows us to adapt to changes in that internal implementation without having to wait for a binary release. Passed to JDK Matcher.find() -[`--profiles_to_retain`](#common_options-flag--profiles_to_retain)`=<an integer>` default: "5" -Number of profiles to retain in the output base. If there are more than this number of profiles in the output base, the oldest are deleted until the total is under the limit. +`--[no]legacy_important_outputs` default: "false" +: Use this to suppress generation of the legacy important\_outputs field in the TargetComplete event. important\_outputs are required for Bazel to ResultStore/BTX integration. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]record_full_profiler_data`](#common_options-flag--record_full_profiler_data) default: "false" -By default, Bazel profiler will record only aggregated data for fast but numerous events (such as statting the file). If this option is enabled, profiler will record each event - resulting in more precise profiling data but LARGE performance hit. Option only has effect if --profile used as well. +`--logging=<0 <= an integer <= 6>` default: "3" +: The logging level. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]redirect_local_instrumentation_output_writes`](#common_options-flag--redirect_local_instrumentation_output_writes) default: "false" -If true and supported, instrumentation output is redirected to be written locally on a different machine than where bazel is running on. +`--memory_profile=<a path>` default: see description +: If set, write memory usage data to the specified file at phase ends and stable heap to master log at end of build. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--remote_print_execution_messages`](#common_options-flag--remote_print_execution_messages)`=<failure, success or all>` default: "failure" -Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. +`--memory_profile_stable_heap_parameters=<integers, separated by a comma expected in pairs>` default: "1,0" +: Tune memory profile's computation of stable heap at end of build. Should be and even number of integers separated by commas. In each pair the first integer is the number of GCs to perform. The second integer in each pair is the number of seconds to wait between GCs. Ex: 2,4,4,0 would 2 GCs with a 4sec pause, followed by 4 GCs with zero second pause -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]slim_profile`](#common_options-flag--slim_profile) default: "true" -Slims down the size of the JSON profile by merging events if the profile gets too large. +`--profile=<a path>` default: see description +: If set, profile Bazel and write data to the specified file. See https://bazel.build/advanced/performance/json-trace-profile for more information. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--starlark_cpu_profile`](#common_options-flag--starlark_cpu_profile)`=<a string>` default: "" -Writes into the specified file a pprof profile of CPU usage by all Starlark threads. +`--profiles_to_retain=<an integer>` default: "5" +: Number of profiles to retain in the output base. If there are more than this number of profiles in the output base, the oldest are deleted until the total is under the limit. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--tool_tag`](#common_options-flag--tool_tag)`=<a string>` default: "" -A tool name to attribute this Bazel invocation to. +`--[no]record_full_profiler_data` default: "false" +: By default, Bazel profiler will record only aggregated data for fast but numerous events (such as statting the file). If this option is enabled, profiler will record each event - resulting in more precise profiling data but LARGE performance hit. Option only has effect if --profile used as well. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--ui_event_filters`](#common_options-flag--ui_event_filters)`=<Convert list of comma separated event kind to list of filters>` multiple uses are accumulated -Specifies which events to show in the UI. It is possible to add or remove events to the default ones using leading +/-, or override the default set completely with direct assignment. The set of supported event kinds include INFO, DEBUG, ERROR and more. +`--[no]redirect_local_instrumentation_output_writes` default: "false" +: If true and supported, instrumentation output is redirected to be written locally on a different machine than where bazel is running on. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]write_command_log`](#common_options-flag--write_command_log) default: "false" -Whether or not to write the command.log file +`--remote_print_execution_messages=<failure, success or all>` default: "failure" +: Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -<!-- --> +`--[no]slim_profile` default: "true" +: Slims down the size of the JSON profile by merging events if the profile gets too large. -[`--downloader_config`](#common_options-flag--downloader_config)`=<a path>` default: see description -Specify a file to configure the remote downloader with. This file consists of lines, each of which starts with a directive (`allow`, `block` or `rewrite`) followed by either a host name (for `allow` and `block`) or two patterns, one to match against, and one to use as a substitute URL, with back-references starting from `$1`. It is possible for multiple `rewrite` directives for the same URL to be given, and in this case multiple URLs will be returned. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--experimental_circuit_breaker_strategy`](#common_options-flag--experimental_circuit_breaker_strategy)`=<failure>` default: see description -Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. +`--starlark_cpu_profile=<a string>` default: "" +: Writes into the specified file a pprof profile of CPU usage by all Starlark threads. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--experimental_remote_cache_compression_threshold`](#common_options-flag--experimental_remote_cache_compression_threshold)`=<an integer>` default: "100" -The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote_cache_compression is set. +`--tool_tag=<a string>` default: "" +: A tool name to attribute this Bazel invocation to. -[`--[no]experimental_remote_cache_lease_extension`](#common_options-flag--experimental_remote_cache_lease_extension) default: "false" -If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--experimental_remote_cache_ttl`](#common_options-flag--experimental_remote_cache_ttl)`=<An immutable length of time.>` default: "3h" -The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. +`--ui_event_filters=<Convert list of comma separated event kind to list of filters>` multiple uses are accumulated +: Specifies which events to show in the UI. It is possible to add or remove events to the default ones using leading +/-, or override the default set completely with direct assignment. The set of supported event kinds include INFO, DEBUG, ERROR and more. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--experimental_remote_capture_corrupted_outputs`](#common_options-flag--experimental_remote_capture_corrupted_outputs)`=<a path>` default: see description -A path to a directory where the corrupted outputs will be captured to. +`--[no]write_command_log` default: "false" +: Whether or not to write the command.log file -[`--[no]experimental_remote_discard_merkle_trees`](#common_options-flag--experimental_remote_discard_merkle_trees) default: "true" -If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--experimental_remote_downloader`](#common_options-flag--experimental_remote_downloader)`=<a string>` default: see description -A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote_asset.proto +Remote caching and execution options: -[`--[no]experimental_remote_downloader_local_fallback`](#common_options-flag--experimental_remote_downloader_local_fallback) default: "false" -Whether to fall back to the local downloader if remote downloader fails. +`--downloader_config=<a path>` default: see description +: Specify a file to configure the remote downloader with. This file consists of lines, each of which starts with a directive (`allow`, `block` or `rewrite`) followed by either a host name (for `allow` and `block`) or two patterns, one to match against, and one to use as a substitute URL, with back-references starting from `$1`. It is possible for multiple `rewrite` directives for the same URL to be given, and in this case multiple URLs will be returned. -[`--[no]experimental_remote_downloader_propagate_credentials`](#common_options-flag--experimental_remote_downloader_propagate_credentials) default: "false" -Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. +`--experimental_circuit_breaker_strategy=<failure>` default: see description +: Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. -[`--[no]experimental_remote_execution_keepalive`](#common_options-flag--experimental_remote_execution_keepalive) default: "false" -Whether to use keepalive for remote execution calls. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_remote_failure_rate_threshold`](#common_options-flag--experimental_remote_failure_rate_threshold)`=<an integer in 0-100 range>` default: "10" -Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. +`--experimental_remote_cache_compression_threshold=<an integer>` default: "100" +: The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote\_cache\_compression is set. -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]experimental_remote_cache_lease_extension` default: "false" +: If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. -[`--experimental_remote_failure_window_interval`](#common_options-flag--experimental_remote_failure_window_interval)`=<An immutable length of time.>` default: "60s" -The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. +`--experimental_remote_cache_ttl=<An immutable length of time.>` default: "3h" +: The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_remote_mark_tool_inputs`](#common_options-flag--experimental_remote_mark_tool_inputs) default: "false" -If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. +`--experimental_remote_capture_corrupted_outputs=<a path>` default: see description +: A path to a directory where the corrupted outputs will be captured to. -[`--[no]experimental_remote_merkle_tree_cache`](#common_options-flag--experimental_remote_merkle_tree_cache) default: "false" -If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental_remote_merkle_tree_cache_size. +`--[no]experimental_remote_discard_merkle_trees` default: "true" +: If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. -[`--experimental_remote_merkle_tree_cache_size`](#common_options-flag--experimental_remote_merkle_tree_cache_size)`=<a long integer>` default: "1000" -The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. +`--experimental_remote_downloader=<a string>` default: see description +: A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote\_asset.proto -[`--experimental_remote_output_service`](#common_options-flag--experimental_remote_output_service)`=<a string>` default: see description -HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. +`--[no]experimental_remote_downloader_local_fallback` default: "false" +: Whether to fall back to the local downloader if remote downloader fails. -[`--experimental_remote_output_service_output_path_prefix`](#common_options-flag--experimental_remote_output_service_output_path_prefix)`=<a string>` default: "" -The path under which the contents of output directories managed by the --experimental_remote_output_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. +`--[no]experimental_remote_downloader_propagate_credentials` default: "false" +: Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. -[`--[no]experimental_remote_require_cached`](#common_options-flag--experimental_remote_require_cached) default: "false" -If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. +`--[no]experimental_remote_execution_keepalive` default: "false" +: Whether to use keepalive for remote execution calls. -[`--experimental_remote_scrubbing_config`](#common_options-flag--experimental_remote_scrubbing_config)`=<Converts to a Scrubber>` default: see description -Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote_scrubbing.proto). +`--experimental_remote_failure_rate_threshold=<an integer in 0-100 range>` default: "10" +: Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. -This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. + Tags: + [`execution`](#effect_tag_EXECUTION) -Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. +`--experimental_remote_failure_window_interval=<An immutable length of time.>` default: "60s" +: The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. -Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. + Tags: + [`execution`](#effect_tag_EXECUTION) -In order to successfully use this feature, you likely want to set a custom --host_platform together with --experimental_platform_in_output_dir (to normalize output prefixes) and --incompatible_strict_action_env (to normalize environment variables). +`--[no]experimental_remote_mark_tool_inputs` default: "false" +: If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. -[`--[no]guard_against_concurrent_changes`](#common_options-flag--guard_against_concurrent_changes) default: "lite" -Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. +`--[no]experimental_remote_merkle_tree_cache` default: "false" +: If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental\_remote\_merkle\_tree\_cache\_size. -Tags: -[`execution`](#effect_tag_EXECUTION) +`--experimental_remote_merkle_tree_cache_size=<a long integer>` default: "1000" +: The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. -[`--[no]remote_accept_cached`](#common_options-flag--remote_accept_cached) default: "true" -Whether to accept remotely cached action results. +`--experimental_remote_output_service=<a string>` default: see description +: HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. -[`--remote_build_event_upload`](#common_options-flag--remote_build_event_upload)`=<all or minimal>` default: "minimal" -If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. -If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. -Default to 'minimal'. +`--experimental_remote_output_service_output_path_prefix=<a string>` default: "" +: The path under which the contents of output directories managed by the --experimental\_remote\_output\_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. -[`--remote_bytestream_uri_prefix`](#common_options-flag--remote_bytestream_uri_prefix)`=<a string>` default: see description -The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote_executor and --remote_instance_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "\${hostname}/\${instance_name}". +`--[no]experimental_remote_require_cached` default: "false" +: If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. -[`--remote_cache`](#common_options-flag--remote_cache)`=<a string>` default: see description -A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching +`--experimental_remote_scrubbing_config=<Converts to a Scrubber>` default: see description +: Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote\_scrubbing.proto). -[`--[no]remote_cache_async`](#common_options-flag--remote_cache_async) default: "true" -If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. + This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. -[`--[no]remote_cache_compression`](#common_options-flag--remote_cache_compression) default: "false" -If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental_remote_cache_compression_threshold. + Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. -[`--remote_cache_header`](#common_options-flag--remote_cache_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header that will be included in cache requests: --remote_cache_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. -[`--remote_default_exec_properties`](#common_options-flag--remote_default_exec_properties)`=<a 'name=value' assignment>` multiple uses are accumulated -Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec_properties. + In order to successfully use this feature, you likely want to set a custom --host\_platform together with --experimental\_platform\_in\_output\_dir (to normalize output prefixes) and --incompatible\_strict\_action\_env (to normalize environment variables). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]guard_against_concurrent_changes` default: "lite" +: Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. -[`--remote_default_platform_properties`](#common_options-flag--remote_default_platform_properties)`=<a string>` default: "" -Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote_execution_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--remote_download_regex`](#common_options-flag--remote_download_regex)`=<a valid Java regular expression>` multiple uses are accumulated -Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote_download_outputs. Multiple patterns may be specified by repeating this flag. +`--[no]remote_accept_cached` default: "true" +: Whether to accept remotely cached action results. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--remote_build_event_upload=<all or minimal>` default: "minimal" +: If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. + If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. + Default to 'minimal'. -[`--remote_downloader_header`](#common_options-flag--remote_downloader_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header that will be included in remote downloader requests: --remote_downloader_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. +`--remote_bytestream_uri_prefix=<a string>` default: see description +: The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote\_executor and --remote\_instance\_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "$\{hostname\}/$\{instance\_name\}". -[`--remote_exec_header`](#common_options-flag--remote_exec_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header that will be included in execution requests: --remote_exec_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. +`--remote_cache=<a string>` default: see description +: A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching -[`--remote_execution_priority`](#common_options-flag--remote_execution_priority)`=<an integer>` default: "0" -The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. +`--[no]remote_cache_async` default: "true" +: If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. -[`--remote_executor`](#common_options-flag--remote_executor)`=<a string>` default: see description -HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. +`--[no]remote_cache_compression` default: "false" +: If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental\_remote\_cache\_compression\_threshold. -[`--remote_grpc_log`](#common_options-flag--remote_grpc_log)`=<a path>` default: see description -If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). +`--remote_cache_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header that will be included in cache requests: --remote\_cache\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -[`--remote_header`](#common_options-flag--remote_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header that will be included in requests: --remote_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. +`--remote_default_exec_properties=<a 'name=value' assignment>` multiple uses are accumulated +: Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec\_properties. -[`--remote_instance_name`](#common_options-flag--remote_instance_name)`=<a string>` default: "" -Value to pass as instance_name in the remote execution API. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]remote_local_fallback`](#common_options-flag--remote_local_fallback) default: "false" -Whether to fall back to standalone local execution strategy if remote execution fails. +`--remote_default_platform_properties=<a string>` default: "" +: Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote\_execution\_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. -[`--remote_local_fallback_strategy`](#common_options-flag--remote_local_fallback_strategy)`=<a string>` default: "local" -Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. +`--remote_download_regex=<a valid Java regular expression>` multiple uses are accumulated +: Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote\_download\_outputs. Multiple patterns may be specified by repeating this flag. -[`--remote_max_connections`](#common_options-flag--remote_max_connections)`=<an integer>` default: "100" -Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. -For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote_max_connections concurrent requests. -For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--remote_downloader_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header that will be included in remote downloader requests: --remote\_downloader\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -[`--remote_proxy`](#common_options-flag--remote_proxy)`=<a string>` default: see description -Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). +`--remote_exec_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header that will be included in execution requests: --remote\_exec\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -[`--remote_result_cache_priority`](#common_options-flag--remote_result_cache_priority)`=<an integer>` default: "0" -The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. +`--remote_execution_priority=<an integer>` default: "0" +: The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. -[`--remote_retries`](#common_options-flag--remote_retries)`=<an integer>` default: "5" -The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. +`--remote_executor=<a string>` default: see description +: HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. -[`--remote_retry_max_delay`](#common_options-flag--remote_retry_max_delay)`=<An immutable length of time.>` default: "5s" -The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. +`--remote_grpc_log=<a path>` default: see description +: If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). -[`--remote_timeout`](#common_options-flag--remote_timeout)`=<An immutable length of time.>` default: "60s" -The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. +`--remote_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header that will be included in requests: --remote\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -[`--[no]remote_upload_local_results`](#common_options-flag--remote_upload_local_results) default: "true" -Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. +`--remote_instance_name=<a string>` default: "" +: Value to pass as instance\_name in the remote execution API. -[`--[no]remote_verify_downloads`](#common_options-flag--remote_verify_downloads) default: "true" -If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. +`--[no]remote_local_fallback` default: "false" +: Whether to fall back to standalone local execution strategy if remote execution fails. -<!-- --> +`--remote_local_fallback_strategy=<a string>` default: "local" +: Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. -[`--build_metadata`](#common_options-flag--build_metadata)`=<a 'name=value' assignment>` multiple uses are accumulated -Custom key-value string pairs to supply in a build event. +`--remote_max_connections=<an integer>` default: "100" +: Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. + For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote\_max\_connections concurrent requests. + For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--color`](#common_options-flag--color)`=<yes, no or auto>` default: "auto" -Use terminal controls to colorize output. +`--remote_proxy=<a string>` default: see description +: Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). -[`--config`](#common_options-flag--config)`=<a string>` multiple uses are accumulated -Selects additional config sections from the rc files; for every \<command\>, it also pulls in the options from \<command\>:\<config\> if such a section exists; if this section doesn't exist in any .rc file, Blaze fails with an error. The config sections and flag combinations they are equivalent to are located in the tools/\*.blazerc config files. +`--remote_result_cache_priority=<an integer>` default: "0" +: The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. -[`--credential_helper`](#common_options-flag--credential_helper)`=<Path to a credential helper. It may be absolute, relative to the PATH environment variable, or %workspace%-relative. The path be optionally prefixed by a scope followed by an '='. The scope is a domain name, optionally with a single leading '*' wildcard component. A helper applies to URIs matching its scope, with more specific scopes preferred. If a helper has no scope, it applies to every URI.>` multiple uses are accumulated -Configures a credential helper conforming to the \<a href="https://github.com/EngFlow/credential-helper-spec"\>Credential Helper Specification\</a\> to use for retrieving authorization credentials for repository fetching, remote caching and execution, and the build event service. +`--remote_retries=<an integer>` default: "5" +: The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. -Credentials supplied by a helper take precedence over credentials supplied by `--google_default_credentials`, `--google_credentials`, a `.netrc` file, or the auth parameter to `repository_ctx.download()` and `repository_ctx.download_and_extract()`. +`--remote_retry_max_delay=<An immutable length of time.>` default: "5s" +: The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. -May be specified multiple times to set up multiple helpers. +`--remote_timeout=<An immutable length of time.>` default: "60s" +: The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. -See https://blog.engflow.com/2023/10/09/configuring-bazels-credential-helper/ for instructions. +`--[no]remote_upload_local_results` default: "true" +: Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. -[`--credential_helper_cache_duration`](#common_options-flag--credential_helper_cache_duration)`=<An immutable length of time.>` default: "30m" -How long to cache credentials for if the credential helper doesn't return an expiration time. Changing the value of this flag clears the cache. +`--[no]remote_verify_downloads` default: "true" +: If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. -[`--credential_helper_timeout`](#common_options-flag--credential_helper_timeout)`=<An immutable length of time.>` default: "10s" -Configures the timeout for a credential helper. +Miscellaneous options, not otherwise categorized.: -Credential helpers failing to respond within this timeout will fail the invocation. +`--build_metadata=<a 'name=value' assignment>` multiple uses are accumulated +: Custom key-value string pairs to supply in a build event. -[`--curses`](#common_options-flag--curses)`=<yes, no or auto>` default: "auto" -Use terminal cursor controls to minimize scrolling output. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--disk_cache`](#common_options-flag--disk_cache)`=<a path>` default: see description -A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. +`--color=<yes, no or auto>` default: "auto" +: Use terminal controls to colorize output. -[`--[no]enable_platform_specific_config`](#common_options-flag--enable_platform_specific_config) default: "true" -If true, Bazel picks up host-OS-specific config lines from bazelrc files. For example, if the host OS is Linux and you run bazel build, Bazel picks up lines starting with build:linux. Supported OS identifiers are linux, macos, windows, freebsd, and openbsd. Enabling this flag is equivalent to using --config=linux on Linux, --config=windows on Windows, etc. +`--config=<a string>` multiple uses are accumulated +: Selects additional config sections from the rc files; for every \<command\>, it also pulls in the options from \<command\>:\<config\> if such a section exists; if this section doesn't exist in any .rc file, Blaze fails with an error. The config sections and flag combinations they are equivalent to are located in the tools/\*.blazerc config files. -[`--experimental_action_cache_gc_idle_delay`](#common_options-flag--experimental_action_cache_gc_idle_delay)`=<An immutable length of time.>` default: "5m" -How long the server must remain idle before a garbage collection of the action cache is attempted. Ineffectual unless --experimental_action_cache_gc_max_age is nonzero. +`--credential_helper=<Path to a credential helper. It may be absolute, relative to the PATH environment variable, or %workspace%-relative. The path be optionally prefixed by a scope followed by an '='. The scope is a domain name, optionally with a single leading '*' wildcard component. A helper applies to URIs matching its scope, with more specific scopes preferred. If a helper has no scope, it applies to every URI.>` multiple uses are accumulated +: Configures a credential helper conforming to the <a href="https://github.com/EngFlow/credential-helper-spec">Credential Helper Specification\</a\> to use for retrieving authorization credentials for repository fetching, remote caching and execution, and the build event service. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Credentials supplied by a helper take precedence over credentials supplied by `--google_default_credentials`, `--google_credentials`, a `.netrc` file, or the auth parameter to `repository_ctx.download()` and `repository_ctx.download_and_extract()`. -[`--experimental_action_cache_gc_max_age`](#common_options-flag--experimental_action_cache_gc_max_age)`=<An immutable length of time.>` default: "0" -If set to a nonzero value, the action cache will be periodically garbage collected to remove entries older than this age. Garbage collection occurs in the background once the server has become idle, as determined by the --experimental_action_cache_gc_idle_delay and --experimental_action_cache_gc_threshold flags. + May be specified multiple times to set up multiple helpers. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + See https://blog.engflow.com/2023/10/09/configuring-bazels-credential-helper/ for instructions. -[`--experimental_action_cache_gc_threshold`](#common_options-flag--experimental_action_cache_gc_threshold)`=<an integer in 0-100 range>` default: "10" -The percentage of stale action cache entries required for garbage collection to be triggered. Ineffectual unless --experimental_action_cache_gc_max_age is nonzero. +`--credential_helper_cache_duration=<An immutable length of time.>` default: "30m" +: How long to cache credentials for if the credential helper doesn't return an expiration time. Changing the value of this flag clears the cache. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--credential_helper_timeout=<An immutable length of time.>` default: "10s" +: Configures the timeout for a credential helper. -[`--experimental_disk_cache_gc_idle_delay`](#common_options-flag--experimental_disk_cache_gc_idle_delay)`=<An immutable length of time.>` default: "5m" -How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental_disk_cache_gc_max_size and/or --experimental_disk_cache_gc_max_age. + Credential helpers failing to respond within this timeout will fail the invocation. -[`--experimental_disk_cache_gc_max_age`](#common_options-flag--experimental_disk_cache_gc_max_age)`=<An immutable length of time.>` default: "0" -If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental_disk_cache_gc_max_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag. +`--curses=<yes, no or auto>` default: "auto" +: Use terminal cursor controls to minimize scrolling output. -[`--experimental_disk_cache_gc_max_size`](#common_options-flag--experimental_disk_cache_gc_max_size)`=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" -If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental_disk_cache_gc_max_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag. +`--disk_cache=<a path>` default: see description +: A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. -[`--[no]experimental_enable_thread_dump`](#common_options-flag--experimental_enable_thread_dump) default: "false" -Whether to enable thread dumps. If true, Bazel will dump the state of all threads (including virtual threads) to a file every --experimental_thread_dump_interval, or after action execution being inactive for --experimental_thread_dump_action_execution_inactivity_duration. The dumps will be written to the \<output_base\>/server/thread_dumps/ directory. +`--[no]enable_platform_specific_config` default: "true" +: If true, Bazel picks up host-OS-specific config lines from bazelrc files. For example, if the host OS is Linux and you run bazel build, Bazel picks up lines starting with build:linux. Supported OS identifiers are linux, macos, windows, freebsd, and openbsd. Enabling this flag is equivalent to using --config=linux on Linux, --config=windows on Windows, etc. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--experimental_action_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" +: How long the server must remain idle before a garbage collection of the action cache is attempted. Ineffectual unless --experimental\_action\_cache\_gc\_max\_age is nonzero. -[`--experimental_install_base_gc_max_age`](#common_options-flag--experimental_install_base_gc_max_age)`=<An immutable length of time.>` default: "30d" -How long an install base must go unused before it's eligible for garbage collection. If nonzero, the server will attempt to garbage collect other install bases when idle. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--experimental_action_cache_gc_max_age=<An immutable length of time.>` default: "0" +: If set to a nonzero value, the action cache will be periodically garbage collected to remove entries older than this age. Garbage collection occurs in the background once the server has become idle, as determined by the --experimental\_action\_cache\_gc\_idle\_delay and --experimental\_action\_cache\_gc\_threshold flags. -[`--[no]experimental_rule_extension_api`](#common_options-flag--experimental_rule_extension_api) default: "true" -Enable experimental rule extension API and subrule APIs + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_action_cache_gc_threshold=<an integer in 0-100 range>` default: "10" +: The percentage of stale action cache entries required for garbage collection to be triggered. Ineffectual unless --experimental\_action\_cache\_gc\_max\_age is nonzero. -[`--experimental_thread_dump_action_execution_inactivity_duration`](#common_options-flag--experimental_thread_dump_action_execution_inactivity_duration)`=<An immutable length of time.>` default: "0" -Dump the threads when action execution being inactive for this duration. If zero, no thread dumps are written for action execution being inactive. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--experimental_disk_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" +: How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental\_disk\_cache\_gc\_max\_size and/or --experimental\_disk\_cache\_gc\_max\_age. -[`--experimental_thread_dump_interval`](#common_options-flag--experimental_thread_dump_interval)`=<An immutable length of time.>` default: "0" -How often to dump the threads periodically. If zero, no thread dumps are written periodically. +`--experimental_disk_cache_gc_max_age=<An immutable length of time.>` default: "0" +: If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--experimental_disk_cache_gc_max_size=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" +: If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. -[`--[no]experimental_windows_watchfs`](#common_options-flag--experimental_windows_watchfs) default: "false" -If true, experimental Windows support for --watchfs is enabled. Otherwise --watchfsis a non-op on Windows. Make sure to also enable --watchfs. +`--[no]experimental_enable_thread_dump` default: "false" +: Whether to enable thread dumps. If true, Bazel will dump the state of all threads (including virtual threads) to a file every --experimental\_thread\_dump\_interval, or after action execution being inactive for --experimental\_thread\_dump\_action\_execution\_inactivity\_duration. The dumps will be written to the \<output\_base\>/server/thread\_dumps/ directory. -[`--google_auth_scopes`](#common_options-flag--google_auth_scopes)`=<comma-separated list of options>` default: "https://www.googleapis.com/auth/cloud-platform" -A comma-separated list of Google Cloud authentication scopes. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--google_credentials`](#common_options-flag--google_credentials)`=<a string>` default: see description -Specifies the file to get authentication credentials from. See https://cloud.google.com/docs/authentication for details. +`--experimental_install_base_gc_max_age=<An immutable length of time.>` default: "30d" +: How long an install base must go unused before it's eligible for garbage collection. If nonzero, the server will attempt to garbage collect other install bases when idle. -[`--[no]google_default_credentials`](#common_options-flag--google_default_credentials) default: "false" -Whether to use 'Google Application Default Credentials' for authentication. See https://cloud.google.com/docs/authentication for details. Disabled by default. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--grpc_keepalive_time`](#common_options-flag--grpc_keepalive_time)`=<An immutable length of time.>` default: see description -Configures keep-alive pings for outgoing gRPC connections. If this is set, then Bazel sends pings after this much time of no read operations on the connection, but only if there is at least one pending gRPC call. Times are treated as second granularity; it is an error to set a value less than one second. By default, keep-alive pings are disabled. You should coordinate with the service owner before enabling this setting. For example to set a value of 30 seconds to this flag, it should be done as this --grpc_keepalive_time=30s +`--[no]experimental_rule_extension_api` default: "true" +: Enable experimental rule extension API and subrule APIs -[`--grpc_keepalive_timeout`](#common_options-flag--grpc_keepalive_timeout)`=<An immutable length of time.>` default: "20s" -Configures a keep-alive timeout for outgoing gRPC connections. If keep-alive pings are enabled with --grpc_keepalive_time, then Bazel times out a connection if it does not receive a ping reply after this much time. Times are treated as second granularity; it is an error to set a value less than one second. If keep-alive pings are disabled, then this setting is ignored. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_disable_non_executable_java_binary`](#common_options-flag--incompatible_disable_non_executable_java_binary) default: "false" -If true, java_binary is always executable. create_executable attribute is removed. +`--experimental_thread_dump_action_execution_inactivity_duration=<An immutable length of time.>` default: "0" +: Dump the threads when action execution being inactive for this duration. If zero, no thread dumps are written for action execution being inactive. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]incompatible_repo_env_ignores_action_env`](#common_options-flag--incompatible_repo_env_ignores_action_env) default: "true" -If true, \<code\>--action_env=NAME=VALUE\</code\> will no longer affect repository rule and module extension environments. +`--experimental_thread_dump_interval=<An immutable length of time.>` default: "0" +: How often to dump the threads periodically. If zero, no thread dumps are written periodically. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--inject_repository`](#common_options-flag--inject_repository)`=<an equals-separated mapping of repository name to path>` multiple uses are accumulated -Adds a new repository with a local path in the form of \<repository name\>=\<path\>. This only takes effect with --enable_bzlmod and is equivalent to adding a corresponding `local_repository` to the root module's MODULE.bazel file via `use_repo_rule`. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%', it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous injections. - -[`--invocation_id`](#common_options-flag--invocation_id)`=<a UUID>` default: "" -Unique identifier, in UUID format, for the command being run. If explicitly specified uniqueness must be ensured by the caller. The UUID is printed to stderr, the BEP and remote execution protocol. - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -[`--override_repository`](#common_options-flag--override_repository)`=<an equals-separated mapping of repository name to path>` multiple uses are accumulated -Override a repository with a local path in the form of \<repository name\>=\<path\>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. - -[`--[no]progress_in_terminal_title`](#common_options-flag--progress_in_terminal_title) default: "false" -Show the command progress in the terminal title. Useful to see what bazel is doing when having multiple terminal tabs. - -[`--[no]show_progress`](#common_options-flag--show_progress) default: "true" -Display progress messages during a build. - -[`--show_progress_rate_limit`](#common_options-flag--show_progress_rate_limit)`=<a double>` default: "0.2" -Minimum number of seconds between progress messages in the output. - -[`--[no]show_timestamps`](#common_options-flag--show_timestamps) default: "false" -Include timestamps in messages - -[`--tls_certificate`](#common_options-flag--tls_certificate)`=<a string>` default: see description -Specify a path to a TLS certificate that is trusted to sign server certificates. - -[`--tls_client_certificate`](#common_options-flag--tls_client_certificate)`=<a string>` default: see description -Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication. - -[`--tls_client_key`](#common_options-flag--tls_client_key)`=<a string>` default: see description -Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication. - -[`--ui_actions_shown`](#common_options-flag--ui_actions_shown)`=<an integer>` default: "8" -Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1. - -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -[`--[no]watchfs`](#common_options-flag--watchfs) default: "false" -On Linux/macOS: If true, bazel tries to use the operating system's file watch service for local changes instead of scanning every file for a change. On Windows: this flag currently is a non-op but can be enabled in conjunction with --experimental_windows_watchfs. On any OS: The behavior is undefined if your workspace is on a network file system, and files are edited on a remote machine. - -## <span id="aquery">Aquery Options</span> - -Inherits all options from [build](#build). +`--[no]experimental_windows_watchfs` default: "false" +: If true, experimental Windows support for --watchfs is enabled. Otherwise --watchfsis a non-op on Windows. Make sure to also enable --watchfs. -[`--aspect_deps`](#aquery-flag--aspect_deps)`=<off, conservative or precise>` default: "conservative" -How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. +`--google_auth_scopes=<comma-separated list of options>` default: "https://www.googleapis.com/auth/cloud-platform" +: A comma-separated list of Google Cloud authentication scopes. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--google_credentials=<a string>` default: see description +: Specifies the file to get authentication credentials from. See https://cloud.google.com/docs/authentication for details. -[`--[no]consistent_labels`](#aquery-flag--consistent_labels) default: "false" -If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. +`--[no]google_default_credentials` default: "false" +: Whether to use 'Google Application Default Credentials' for authentication. See https://cloud.google.com/docs/authentication for details. Disabled by default. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--grpc_keepalive_time=<An immutable length of time.>` default: see description +: Configures keep-alive pings for outgoing gRPC connections. If this is set, then Bazel sends pings after this much time of no read operations on the connection, but only if there is at least one pending gRPC call. Times are treated as second granularity; it is an error to set a value less than one second. By default, keep-alive pings are disabled. You should coordinate with the service owner before enabling this setting. For example to set a value of 30 seconds to this flag, it should be done as this --grpc\_keepalive\_time=30s -[`--[no]experimental_explicit_aspects`](#aquery-flag--experimental_explicit_aspects) default: "false" -aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). +`--grpc_keepalive_timeout=<An immutable length of time.>` default: "20s" +: Configures a keep-alive timeout for outgoing gRPC connections. If keep-alive pings are enabled with --grpc\_keepalive\_time, then Bazel times out a connection if it does not receive a ping reply after this much time. Times are treated as second granularity; it is an error to set a value less than one second. If keep-alive pings are disabled, then this setting is ignored. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]incompatible_disable_non_executable_java_binary` default: "false" +: If true, java\_binary is always executable. create\_executable attribute is removed. -[`--[no]graph:factored`](#aquery-flag--graph:factored) default: "true" -If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]incompatible_repo_env_ignores_action_env` default: "true" +: If true, \<code\>--action\_env=NAME=VALUE\</code\> will no longer affect repository rule and module extension environments. -[`--graph:node_limit`](#aquery-flag--graph:node_limit)`=<an integer>` default: "512" -The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--inject_repository=<an equals-separated mapping of repository name to path>` multiple uses are accumulated +: Adds a new repository with a local path in the form of <repository name>=<path>. This only takes effect with --enable\_bzlmod and is equivalent to adding a corresponding `local_repository` to the root module's MODULE.bazel file via `use_repo_rule`. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%', it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous injections. -[`--[no]implicit_deps`](#aquery-flag--implicit_deps) default: "true" -If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. +`--invocation_id=<a UUID>` default: "" +: Unique identifier, in UUID format, for the command being run. If explicitly specified uniqueness must be ensured by the caller. The UUID is printed to stderr, the BEP and remote execution protocol. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--[no]include_artifacts`](#aquery-flag--include_artifacts) default: "true" -Includes names of the action inputs and outputs in the output (potentially large). +`--override_repository=<an equals-separated mapping of repository name to path>` multiple uses are accumulated +: Override a repository with a local path in the form of <repository name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]progress_in_terminal_title` default: "false" +: Show the command progress in the terminal title. Useful to see what bazel is doing when having multiple terminal tabs. -[`--[no]include_aspects`](#aquery-flag--include_aspects) default: "true" -aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). +`--[no]show_progress` default: "true" +: Display progress messages during a build. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--show_progress_rate_limit=<a double>` default: "0.2" +: Minimum number of seconds between progress messages in the output. -[`--[no]include_commandline`](#aquery-flag--include_commandline) default: "true" -Includes the content of the action command lines in the output (potentially large). +`--[no]show_timestamps` default: "false" +: Include timestamps in messages -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--tls_certificate=<a string>` default: see description +: Specify a path to a TLS certificate that is trusted to sign server certificates. -[`--[no]include_file_write_contents`](#aquery-flag--include_file_write_contents) default: "false" -Include the file contents for the FileWrite, SourceSymlinkManifest, and RepoMappingManifest actions (potentially large). +`--tls_client_certificate=<a string>` default: see description +: Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--tls_client_key=<a string>` default: see description +: Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication. -[`--[no]include_param_files`](#aquery-flag--include_param_files) default: "false" -Include the content of the param files used in the command (potentially large). Note: Enabling this flag will automatically enable the --include_commandline flag. +`--ui_actions_shown=<an integer>` default: "8" +: Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]include_pruned_inputs`](#aquery-flag--include_pruned_inputs) default: "true" -Includes action inputs that were pruned during action execution. Only affects actions that discover inputs and have been executed in a previous invocation. Only takes effect if --include_artifacts is also set. +`--[no]watchfs` default: "false" +: On Linux/macOS: If true, bazel tries to use the operating system's file watch service for local changes instead of scanning every file for a change. On Windows: this flag currently is a non-op but can be enabled in conjunction with --experimental\_windows\_watchfs. On any OS: The behavior is undefined if your workspace is on a network file system, and files are edited on a remote machine. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +## Aquery Options -[`--[no]incompatible_package_group_includes_double_slash`](#aquery-flag--incompatible_package_group_includes_double_slash) default: "true" -If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted. - -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -[`--[no]infer_universe_scope`](#aquery-flag--infer_universe_scope) default: "false" -If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). - -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +Inherits all options from [build](#build). -[`--[no]line_terminator_null`](#aquery-flag--line_terminator_null) default: "false" -Whether each format is terminated with \0 instead of newline. +Options relating to query output and semantics: -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--aspect_deps=<off, conservative or precise>` default: "conservative" +: How to resolve aspect dependencies when the output format is one of \{xml,proto,record\}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. -[`--[no]nodep_deps`](#aquery-flag--nodep_deps) default: "true" -If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--[no]consistent_labels` default: "false" +: If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. -[`--output`](#aquery-flag--output)`=<a string>` default: "text" -The format in which the aquery results should be printed. Allowed values for aquery are: text, textproto, proto, streamed_proto, jsonproto. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]experimental_explicit_aspects` default: "false" +: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). -[`--output_file`](#aquery-flag--output_file)`=<a string>` default: "" -When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]graph:factored` default: "true" +: If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. -[`--[no]proto:default_values`](#aquery-flag--proto:default_values) default: "true" -If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--graph:node_limit=<an integer>` default: "512" +: The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. -[`--[no]proto:definition_stack`](#aquery-flag--proto:definition_stack) default: "false" -Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]implicit_deps` default: "true" +: If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. -[`--[no]proto:flatten_selects`](#aquery-flag--proto:flatten_selects) default: "true" -If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--[no]include_artifacts` default: "true" +: Includes names of the action inputs and outputs in the output (potentially large). -[`--[no]proto:include_attribute_source_aspects`](#aquery-flag--proto:include_attribute_source_aspects) default: "false" -Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]include_aspects` default: "true" +: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). -[`--[no]proto:include_starlark_rule_env`](#aquery-flag--proto:include_starlark_rule_env) default: "true" -Use the starlark environment in the value of the generated \$internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]include_commandline` default: "true" +: Includes the content of the action command lines in the output (potentially large). -[`--[no]proto:include_synthetic_attribute_hash`](#aquery-flag--proto:include_synthetic_attribute_hash) default: "false" -Whether or not to calculate and populate the \$internal_attr_hash attribute. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]include_file_write_contents` default: "false" +: Include the file contents for the FileWrite, SourceSymlinkManifest, and RepoMappingManifest actions (potentially large). -[`--[no]proto:instantiation_stack`](#aquery-flag--proto:instantiation_stack) default: "false" -Populate the instantiation call stack of each rule. Note that this requires the stack to be present + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]include_param_files` default: "false" +: Include the content of the param files used in the command (potentially large). Note: Enabling this flag will automatically enable the --include\_commandline flag. -[`--[no]proto:locations`](#aquery-flag--proto:locations) default: "true" -Whether to output location information in proto output at all. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]include_pruned_inputs` default: "true" +: Includes action inputs that were pruned during action execution. Only affects actions that discover inputs and have been executed in a previous invocation. Only takes effect if --include\_artifacts is also set. -[`--proto:output_rule_attrs`](#aquery-flag--proto:output_rule_attrs)`=<comma-separated list of options>` default: "all" -Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]incompatible_package_group_includes_double_slash` default: "true" +: If enabled, when outputting package\_group's `packages` attribute, the leading `//` will not be omitted. -[`--[no]proto:rule_classes`](#aquery-flag--proto:rule_classes) default: "false" -Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]infer_universe_scope` default: "false" +: If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). -[`--[no]proto:rule_inputs_and_outputs`](#aquery-flag--proto:rule_inputs_and_outputs) default: "true" -Whether or not to populate the rule_input and rule_output fields. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]line_terminator_null` default: "false" +: Whether each format is terminated with \0 instead of newline. -[`--query_file`](#aquery-flag--query_file)`=<a string>` default: "" -If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--[no]nodep_deps` default: "true" +: If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. -[`--[no]relative_locations`](#aquery-flag--relative_locations) default: "false" -If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--output=<a string>` default: "text" +: The format in which the aquery results should be printed. Allowed values for aquery are: text, textproto, proto, streamed\_proto, jsonproto. -[`--[no]skyframe_state`](#aquery-flag--skyframe_state) default: "false" -Without performing extra analysis, dump the current Action Graph from Skyframe. Note: Specifying a target with --skyframe_state is currently not supported. This flag is only available with --output=proto or --output=textproto. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--output_file=<a string>` default: "" +: When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. -[`--[no]tool_deps`](#aquery-flag--tool_deps) default: "true" -Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. -Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--[no]proto:default_values` default: "true" +: If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto -[`--universe_scope`](#aquery-flag--universe_scope)`=<comma-separated list of options>` default: "" -A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. -For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]proto:definition_stack` default: "false" +: Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. -<!-- --> + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" -Enable persistent aar extractor by using workers. +`--[no]proto:flatten_selects` default: "true" +: If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" -Whether to make source manifest actions remotable +`--[no]proto:include_attribute_source_aspects` default: "false" +: Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" -If true, then Bazel will run coverage postprocessing for test in a new spawn. +`--[no]proto:include_starlark_rule_env` default: "true" +: Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" -If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. +`--[no]proto:include_synthetic_attribute_hash` default: "false" +: Whether or not to calculate and populate the $internal\_attr\_hash attribute. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" -When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. +`--[no]proto:instantiation_stack` default: "false" +: Populate the instantiation call stack of each rule. Note that this requires the stack to be present -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. +`--[no]proto:locations` default: "true" +: Whether to output location information in proto output at all. -Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Examples: -'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. +`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" +: Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -Enable persistent Android dex and desugar actions by using workers. +`--[no]proto:rule_classes` default: "false" +: Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. -Expands to: -  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) -  [`--strategy=Desugar=worker`](#flag--strategy) -  [`--strategy=DexBuilder=worker`](#flag--strategy) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--[no]proto:rule_inputs_and_outputs` default: "true" +: Whether or not to populate the rule\_input and rule\_output fields. -[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -Enable persistent Android resource processor by using workers. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Expands to: -  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) -  [`--strategy=AaptPackage=worker`](#flag--strategy) -  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) -  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) -  [`--strategy=RClassGenerator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) -  [`--strategy=AndroidAapt2=worker`](#flag--strategy) -  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) -  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) -  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) -  [`--strategy=ManifestMerger=worker`](#flag--strategy) -  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) -  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) -  [`--strategy=AARGenerator=worker`](#flag--strategy) -  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) -  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) +`--query_file=<a string>` default: "" +: If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) -Enable persistent multiplexed Android dex and desugar actions by using workers. +`--[no]relative_locations` default: "false" +: If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. -Expands to: -  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--[no]skyframe_state` default: "false" +: Without performing extra analysis, dump the current Action Graph from Skyframe. Note: Specifying a target with --skyframe\_state is currently not supported. This flag is only available with --output=proto or --output=textproto. -[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -Enable persistent multiplexed Android resource processor by using workers. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Expands to: -  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) +`--[no]tool_deps` default: "true" +: Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. + Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) -Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). +`--universe_scope=<comma-separated list of options>` default: "" +: A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. + For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. -Expands to: -  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) -  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +Options that control build execution: -[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" -If true, use the target platform for running tests rather than the test exec group. +`--[no]experimental_persistent_aar_extractor` default: "false" +: Enable persistent aar extractor by using workers. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -<!-- --> +`--[no]experimental_remotable_source_manifests` default: "false" +: Whether to make source manifest actions remotable -[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description -The Android target compiler. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]experimental_split_coverage_postprocessing` default: "false" +: If true, then Bazel will run coverage postprocessing for test in a new spawn. -[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" -Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]experimental_strict_fileset_output` default: "false" +: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. -[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" -Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]incompatible_modify_execution_info_additive` default: "true" +: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + + Syntax: "regex=[+-]key,regex=[+-]key,...". + + Examples: + '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. + 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. + '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` +: Enable persistent Android dex and desugar actions by using workers. + + Expands to: + +   `--internal_persistent_android_dex_desugar` + +   `--strategy=Desugar=worker` + +   `--strategy=DexBuilder=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` +: Enable persistent Android resource processor by using workers. + + Expands to: + +   `--internal_persistent_busybox_tools` + +   `--strategy=AaptPackage=worker` + +   `--strategy=AndroidResourceParser=worker` + +   `--strategy=AndroidResourceValidator=worker` + +   `--strategy=AndroidResourceCompiler=worker` + +   `--strategy=RClassGenerator=worker` + +   `--strategy=AndroidResourceLink=worker` + +   `--strategy=AndroidAapt2=worker` + +   `--strategy=AndroidAssetMerger=worker` + +   `--strategy=AndroidResourceMerger=worker` + +   `--strategy=AndroidCompiledResourceMerger=worker` + +   `--strategy=ManifestMerger=worker` + +   `--strategy=AndroidManifestMerger=worker` + +   `--strategy=Aapt2Optimize=worker` + +   `--strategy=AARGenerator=worker` + +   `--strategy=ProcessDatabinding=worker` + +   `--strategy=GenerateDataBindingBaseClasses=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` +: Enable persistent multiplexed Android dex and desugar actions by using workers. + + Expands to: + +   `--persistent_android_dex_desugar` + +   `--internal_persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` +: Enable persistent multiplexed Android resource processor by using workers. + + Expands to: + +   `--persistent_android_resource_processor` + +   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` +: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + + Expands to: + +   `--internal_persistent_multiplex_busybox_tools` + +   `--persistent_multiplex_android_resource_processor` + +   `--persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" +: If true, use the target platform for running tests rather than the test exec group. + + Tags: + [`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: + +`--android_compiler=<a string>` default: see description +: The Android target compiler. + + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" +: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. -[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" -Specifies a suffix to be added to the configuration directory. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--android_platforms=<a build target label>` default: "" +: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. -[`--compiler`](#flag--compiler)`=<a string>` default: see description -The C++ compiler to use for compiling the target. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) +`--cc_output_directory_tag=<a string>` default: "" +: Specifies a suffix to be added to the configuration directory. -[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" -Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--compiler=<a string>` default: see description +: The C++ compiler to use for compiling the target. -[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" -Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" +: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. -[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" -Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" +: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. -[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description -Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" +: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. -[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" -If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--custom_malloc=<a build target label>` default: see description +: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. -[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" -If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_include_xcode_execution_requirements` default: "false" +: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. -[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" -The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]experimental_prefer_mutual_xcode` default: "true" +: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. -[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated -The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--extra_execution_platforms=<comma-separated list of options>` default: "" +: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. -[`--grte_top`](#flag--grte_top)`=<a label>` default: see description -A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated +: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). -[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description -No-op flag. Will be removed in a future release. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) +`--grte_top=<a label>` default: see description +: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. -[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description -If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_compiler=<a string>` default: see description +: No-op flag. Will be removed in a future release. -[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" -The label of a platform rule that describes the host system. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--host_grte_top=<a label>` default: see description +: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. -[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" -If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" +: The label of a platform rule that describes the host system. -[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" -Whether to emit a strip action as part of objc linking. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_bazel_test_exec_run_under` default: "true" +: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. -[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" -If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_builtin_objc_strip_action` default: "true" +: Whether to emit a strip action as part of objc linking. -[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" -Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" +: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). -[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" -If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" +: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) -[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" -If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_remove_legacy_whole_archive` default: "true" +: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). -[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" -Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_strip_executable_safely` default: "false" +: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. -[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]interface_shared_objects` default: "true" +: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. -[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. -[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description -The minimum OS version which your compilation targets. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. -[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" -The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--minimum_os_version=<a string>` default: see description +: The minimum OS version which your compilation targets. -[`--platforms`](#flag--platforms)`=<a build target label>` default: "" -The labels of the platform rules describing the target platforms for the current command. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--platform_mappings=<a main workspace-relative path>` default: "" +: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). -[`--python_path`](#flag--python_path)`=<a string>` default: see description -The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--platforms=<a build target label>` default: "" +: The labels of the platform rules describing the target platforms for the current command. -[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--python_path=<a string>` default: see description +: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. -[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" -Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. -[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. -[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description -If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. -[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" -The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--xcode_version=<a string>` default: see description +: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. -<!-- --> + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" -Whether to generate debug symbol(.dSYM) file(s). +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" +: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" -If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. +Options that control the output of the command: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]apple_generate_dsym` default: "false" +: Whether to generate debug symbol(.dSYM) file(s). -[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" -If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]build_runfile_links` default: "true" +: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. -[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" -If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]build_runfile_manifests` default: "true" +: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. -[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" -Sets the suffixes of header files that a cc_proto_library creates. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]build_test_dwp` default: "false" +: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. -[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" -Sets the suffixes of source files that a cc_proto_library creates. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" +: Sets the suffixes of header files that a cc\_proto\_library creates. -[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" -Run extra actions for alternative Java api versions in a proto_library. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" +: Sets the suffixes of source files that a cc\_proto\_library creates. -[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" -Save the state of enabled and requested feautres as an output of compilation. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" +: Run extra actions for alternative Java api versions in a proto\_library. -[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" -Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_save_feature_state` default: "false" +: Save the state of enabled and requested feautres as an output of compilation. -[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" -If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--fission=<a set of compilation modes>` default: "no" +: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. -[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" -If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_always_include_files_in_data` default: "true" +: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). -[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" -List of flags for which the use in select() is disabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" +: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. -[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" -If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" +: List of flags for which the use in select() is disabled. -[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" -Specifies whether to generate a linkmap file. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" +: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. -[`--[no]save_temps`](#flag--save_temps) default: "false" -If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]objc_generate_linkmap` default: "false" +: Specifies whether to generate a linkmap file. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case -the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -\<br\> -Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. +`--[no]save_temps` default: "false" +: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" -Allowed values for the --cpu flag. +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case + the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + \<br\> + Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. -[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" -Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--allowed_cpu_values=<comma-separated set of options>` default: "" +: Allowed values for the --cpu flag. -[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" -Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]android_databinding_use_androidx` default: "true" +: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. -[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" -Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]android_databinding_use_v3_4_args` default: "true" +: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. -[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) +`--android_dynamic_mode=<off, default or fully>` default: "off" +: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. -[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" -Build python executable zip; on on Windows, off on other platforms + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple Catalyst binaries. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]build_python_zip` default: "auto" +: Build python executable zip; on on Windows, off on other platforms -[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" -If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple Catalyst binaries. -[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" -Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]collect_code_coverage` default: "false" +: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. -[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C source files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" +: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. -[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C source files. -[`--cpu`](#flag--cpu)`=<a string>` default: "" -Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--copt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc. -[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description -Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cpu=<a string>` default: "" +: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. -[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description -Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cs_fdo_absolute_path=<a string>` default: see description +: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. -[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description -The cs_fdo_profile representing the context sensitive profile to be used for optimization. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cs_fdo_instrument=<a string>` default: see description +: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C++ source files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cs_fdo_profile=<a build target label>` default: see description +: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. -[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated -Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cxxopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C++ source files. -[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" -Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--define=<a 'name=value' assignment>` multiple uses are accumulated +: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. -[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" -If set, any use of absolute paths for propeller optimize will raise an error. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--dynamic_mode=<off, default or fully>` default: "default" +: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" -If set, any use of absolute paths for FDO will raise an error. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]enable_propeller_optimize_absolute_paths` default: "true" +: If set, any use of absolute paths for propeller optimize will raise an error. -[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" -Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]enable_remaining_fdo_absolute_paths` default: "true" +: If set, any use of absolute paths for FDO will raise an error. -[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]enable_runfiles` default: "auto" +: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. -[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated -Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. -[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" -Compress Java resources in APKs + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_action_listener=<a build target label>` multiple uses are accumulated +: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. -[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" -Use android databinding v2. This flag is a no-op. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_android_compress_java_resources` default: "false" +: Compress Java resources in APKs -[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_android_databinding_v2` default: "true" +: Use android databinding v2. This flag is a no-op. -[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" -use rex tool to rewrite dex files + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" -If specified, Bazel will also generate collect coverage information for generated files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" +: use rex tool to rewrite dex files -[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -Uses these strings as objc fastbuild compiler options. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" +: If specified, Bazel will also generate collect coverage information for generated files. -[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" -If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +: Uses these strings as objc fastbuild compiler options. -[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" -Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) +`--[no]experimental_omitfp` default: "false" +: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. -[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated -Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_output_paths=<off or strip>` default: "off" +: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. -[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" -If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated +: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. -[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" -py_binary targets include their label even when stamping is disabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_platform_in_output_dir` default: "false" +: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. -[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" -If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_py_binaries_include_label` default: "false" +: py\_binary targets include their label even when stamping is disabled. -[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" -Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_use_llvm_covmap` default: "false" +: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. -[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description -Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" +: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. -[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description -Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--fdo_instrument=<a string>` default: see description +: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description -Use cache prefetch hints. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--fdo_optimize=<a string>` default: see description +: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. -[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description -The fdo_profile representing the profile to be used for optimization. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--fdo_prefetch_hints=<a build target label>` default: see description +: Use cache prefetch hints. -[`--features`](#flag--features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--fdo_profile=<a build target label>` default: see description +: The fdo\_profile representing the profile to be used for optimization. -[`--[no]force_pic`](#flag--force_pic) default: "false" -If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features -[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]force_pic` default: "false" +: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). -[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" -Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" +: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. -[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated -Additional options to pass to the C compiler for tools built in the exec configurations. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. -[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" -The host CPU. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_copt=<a string>` multiple uses are accumulated +: Additional options to pass to the C compiler for tools built in the exec configurations. -[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated -Additional options to pass to C++ compiler for tools built in the exec configurations. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_cpu=<a string>` default: "" +: The host CPU. -[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_cxxopt=<a string>` multiple uses are accumulated +: Additional options to pass to C++ compiler for tools built in the exec configurations. -[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to linker when linking tools in the exec configurations. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. -[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--host_linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to linker when linking tools in the exec configurations. -[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. -[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" -When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" -If true, the genfiles directory is folded into the bin directory. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_auto_exec_groups` default: "false" +: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. -[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" -If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_merge_genfiles_directory` default: "true" +: If true, the genfiles directory is folded into the bin directory. -[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" -When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_target_cpu_from_platform` default: "true" +: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. -[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" -When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]instrument_test_targets` default: "false" +: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. -[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" +: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. -[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. -[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" -Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. -[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when linking. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]legacy_whole_archive` default: "true" +: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. -[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO backend step (under --features=thin_lto). + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when linking. -[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO indexing step (under --features=thin_lto). + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ltobackendopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO backend step (under --features=thin\_lto). -[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple macOS binaries. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--ltoindexopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO indexing step (under --features=thin\_lto). -[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple macOS binaries. -[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description -Use memprof profile. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. -[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" -If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--memprof_profile=<a build target label>` default: see description +: Use memprof profile. -[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" -Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]objc_debug_with_GLIBCXX` default: "false" +: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. -[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc when compiling Objective-C/C++ source files. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]objc_enable_binary_stripping` default: "false" +: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. -[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--objccopt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc when compiling Objective-C/C++ source files. -[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description -Specifies a suffix to be added to the configuration directory. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. -[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description -Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--platform_suffix=<a string>` default: see description +: Specifies a suffix to be added to the configuration directory. -[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description -Absolute path name of cc_profile file for Propeller Optimized builds. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--propeller_optimize=<a build target label>` default: see description +: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile -[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description -Absolute path name of ld_profile file for Propeller Optimized builds. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description +: Absolute path name of cc\_profile file for Propeller Optimized builds. -[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description -Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description +: Absolute path name of ld\_profile file for Propeller Optimized builds. -[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" -If true, native libraries that contain identical functionality will be shared among different targets + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--run_under=<a prefix in front of command>` default: see description +: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. -[`--[no]stamp`](#flag--stamp) default: "false" -Stamp binaries with the date, username, hostname, workspace information, etc. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]share_native_deps` default: "true" +: If true, native libraries that contain identical functionality will be shared among different targets -[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" -Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]stamp` default: "false" +: Stamp binaries with the date, username, hostname, workspace information, etc. -[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated -Additional options to pass to strip when generating a '\<name\>.stripped' binary. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--strip=<always, sometimes or never>` default: "sometimes" +: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. -[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple tvOS binaries. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--stripopt=<a string>` multiple uses are accumulated +: Additional options to pass to strip when generating a '\<name\>.stripped' binary. -[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple tvOS binaries. -[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple visionOS binaries. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. -[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple watchOS binaries. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple visionOS binaries. -[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple watchOS binaries. -[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description -Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. -<!-- --> + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]check_visibility`](#flag--check_visibility) default: "true" -If disabled, visibility errors in target dependencies are demoted to warnings. +`--xbinary_fdo=<a build target label>` default: see description +: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" -Whether to desugar Java 8 bytecode before dexing. +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]check_visibility` default: "true" +: If disabled, visibility errors in target dependencies are demoted to warnings. -[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" -Whether to include supported Java 8 libraries in apps for legacy devices. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]desugar_for_android` default: "true" +: Whether to desugar Java 8 bytecode before dexing. -[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" -Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--[no]desugar_java8_libs` default: "false" +: Whether to include supported Java 8 libraries in apps for legacy devices. -[`--[no]experimental_check_desugar_deps`](#flag--experimental_check_desugar_deps) default: "true" -Whether to double-check correct desugaring at Android binary level. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]enforce_constraints` default: "true" +: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments -[`--[no]experimental_enforce_transitive_visibility`](#flag--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. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_check_desugar_deps` default: "true" +: Whether to double-check correct desugaring at Android binary level. -[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" -When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[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. -[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" -If true, checks that a Java target explicitly declares all directly used targets as dependencies. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" +: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. -[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" -If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" +: If true, checks that a Java target explicitly declares all directly used targets as dependencies. -[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" -If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_check_testonly_for_output_files` default: "false" +: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. -[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" -No-op. Kept here for backwards compatibility. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_disable_native_android_rules` default: "false" +: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android -[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" -When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" +: No-op. Kept here for backwards compatibility. -[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description -An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]one_version_enforcement_on_java_tests` default: "true" +: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. -[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" -If this option is enabled, filesets crossing package boundaries are reported as errors. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--python_native_rules_allowlist=<a build target label>` default: see description +: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. -[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" -Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]strict_filesets` default: "false" +: If this option is enabled, filesets crossing package boundaries are reported as errors. -[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" -Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" +: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. -[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" -If true, headers found through system include paths (-isystem) are also required to be declared. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" +: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. -[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated -Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--[no]strict_system_includes` default: "false" +: If true, headers found through system include paths (-isystem) are also required to be declared. -<!-- --> + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" -Implementation to use to sign APKs +`--target_environment=<a build target label>` multiple uses are accumulated +: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" -If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. +Options that affect the signing outputs of a build: -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" +: Implementation to use to sign APKs -[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description -Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]device_debug_entitlements` default: "true" +: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. -<!-- --> + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" -If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. +`--ios_signing_cert_name=<a string>` default: see description +: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" -If true, make the default value true for alwayslink attributes in objc_library and objc_import. +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" +: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. -[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" -When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_objc_alwayslink_by_default` default: "false" +: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. -<!-- --> + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" -If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. +`--[no]incompatible_python_disallow_native_rules` default: "false" +: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" -Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. +Options that govern the behavior of the test environment or test runner: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]allow_analysis_failures` default: "false" +: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. -[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" -If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--analysis_testing_deps_limit=<an integer>` default: "2000" +: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. -[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" -Use dex2oat in parallel to possibly speed up android_test. +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" +: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" -Enable checking for memory leaks in ios_test targets. +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]experimental_android_use_parallel_dex2oat` default: "false" +: Use dex2oat in parallel to possibly speed up android\_test. -[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description -The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--[no]ios_memleaks` default: "false" +: Enable checking for memory leaks in ios\_test targets. -[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--ios_simulator_device=<a string>` default: see description +: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. -[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" -Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. -[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" -If true, undeclared test outputs will be archived in a zip file. +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -<!-- --> +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" +: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. -[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" -Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. +`--[no]zip_undeclared_test_outputs` default: "false" +: If true, undeclared test outputs will be archived in a zip file. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" -If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. +Options that trigger optimizations of the build time: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" +: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. -[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" -If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_inmemory_dotd_files` default: "true" +: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. -[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" -When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_inmemory_jdeps_files` default: "true" +: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. -[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" -Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" +: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. -[`--[no]incremental_dexing`](#flag--incremental_dexing) default: "true" -Does most of the work for dexing separately for each Jar file. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" +: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. -[`--[no]objc_use_dotd_pruning`](#flag--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. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incremental_dexing` default: "true" +: Does most of the work for dexing separately for each Jar file. -[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" -When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[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. -[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" -When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]process_headers_in_dependencies` default: "false" +: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). -<!-- --> + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. +`--[no]trim_test_configuration` default: "true" +: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" -If enabled, visibility errors include additional diagnostic information. +Options that affect the verbosity, format or location of logging: -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. -<!-- --> + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated -Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. +`--[no]verbose_visibility_errors` default: "false" +: If enabled, visibility errors include additional diagnostic information. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" -This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated +: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. -<!-- --> + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" -If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. +`--[no]incompatible_default_to_explicit_init_py` default: "false" +: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. -[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" -If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +Miscellaneous options, not otherwise categorized.: -[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" -If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. +`--[no]cache_test_results` [`-t`] default: "auto" +: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_cancel_concurrent_tests` default: "never" +: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. -[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" -If true, coverage for clang will generate an LCOV report. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_fetch_all_coverage_outputs` default: "false" +: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. -[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -Enables reduced classpaths for Java compilations. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" -Whether to validate java\_\* sources. +`--[no]experimental_generate_llvm_lcov` default: "false" +: If true, coverage for clang will generate an LCOV report. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]explicit_java_test_deps`](#flag--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. +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +: Enables reduced classpaths for Java compilations. -[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description -The Java launcher used by tools that are executed during a build. +`--[no]experimental_run_android_lint_on_java_rules` default: "false" +: Whether to validate java\_\* sources. -[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac when building tools that are executed during a build. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. +`--[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. -[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" -If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. +`--host_java_launcher=<a build target label>` default: see description +: The Java launcher used by tools that are executed during a build. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--host_javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac when building tools that are executed during a build. -[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" -If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally +`--host_jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_check_sharding_support` default: "true" +: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. -[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" -If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_exclusive_test_sandboxed` default: "true" +: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally -[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated -Additional options to pass to the J2ObjC tool. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--java_debug`](#flag--java_debug) -Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. +`--[no]incompatible_strict_action_env` default: "false" +: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. -Expands to: -  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) -  [`--test_output=streamed`](#flag--test_output) -  [`--test_strategy=exclusive`](#flag--test_strategy) -  [`--test_timeout=9999`](#flag--test_timeout) -  [`--nocache_test_results`](#flag--nocache_test_results) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]java_deps`](#flag--java_deps) default: "true" -Generate dependency information (for now, compile-time classpath) per Java target. +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. -[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" -Compile ijars directly from source. +`--java_debug` +: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. -[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" -The Java language version + Expands to: + +   `--test_arg=--wrapper_script_flag=--debug` + +   `--test_output=streamed` + +   `--test_strategy=exclusive` + +   `--test_timeout=9999` + +   `--nocache_test_results` -[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description -The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. +`--[no]java_deps` default: "true" +: Generate dependency information (for now, compile-time classpath) per Java target. -[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" -The Java runtime version +`--[no]java_header_compilation` default: "true" +: Compile ijars directly from source. -[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac. +`--java_language_version=<a string>` default: "" +: The Java language version -[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. +`--java_launcher=<a build target label>` default: see description +: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. -[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description -Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. +`--java_runtime_version=<a string>` default: "local\_jdk" +: The Java runtime version -[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description -Specifies a binary to use to do dexing without sharding. +`--javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac. -[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated -Plugins to use in the build. Currently works with java_plugin. +`--jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. -[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description -Specifies which version of ProGuard to use for code removal when building a Java binary. +`--legacy_main_dex_list_generator=<a build target label>` default: see description +: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. -[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" -The label of the proto-compiler. +`--optimizing_dexer=<a build target label>` default: see description +: Specifies a binary to use to do dexing without sharding. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--plugin=<a build target label>` multiple uses are accumulated +: Plugins to use in the build. Currently works with java\_plugin. -[`--[no]proto_profile`](#flag--proto_profile) default: "true" -Whether to pass profile_path to the proto compiler. +`--proguard_top=<a build target label>` default: see description +: Specifies which version of ProGuard to use for code removal when building a Java binary. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" +: The label of the proto-compiler. -[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description -The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]proto_profile` default: "true" +: Whether to pass profile\_path to the proto compiler. -[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" -Label of proto_lang_toolchain() which describes how to compile C++ protos + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_profile_path=<a build target label>` default: see description +: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. -[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" -Label of proto_lang_toolchain() which describes how to compile j2objc protos + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile C++ protos -[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" -Label of proto_lang_toolchain() which describes how to compile Java protos + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos -[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" -Label of proto_lang_toolchain() which describes how to compile JavaLite protos + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile Java protos -[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the protobuf compiler. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos -[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" -If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description -Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. +`--protocopt=<a string>` multiple uses are accumulated +: Additional options to pass to the protobuf compiler. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated -Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. +`--[no]runs_per_test_detects_flakes` default: "false" +: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. -[`--test_filter`](#flag--test_filter)`=<a string>` default: see description -Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. +`--shell_executable=<a path>` default: see description +: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. -[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" -This option is deprecated and has no effect. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" -Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. +`--test_arg=<a string>` multiple uses are accumulated +: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. -[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. +`--test_filter=<a string>` default: see description +: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. -[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" -The Java language version used to execute the tools that are needed during a build +`--test_result_expiration=<an integer>` default: "-1" +: This option is deprecated and has no effect. -[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" -The Java runtime version used to execute tools during the build +`--[no]test_runner_fail_fast` default: "false" +: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. -[`--[no]use_ijars`](#flag--use_ijars) default: "true" -If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. -## <span id="build">Build Options</span> +`--tool_java_language_version=<a string>` default: "" +: The Java language version used to execute the tools that are needed during a build -[`--[no]allow_one_action_on_resource_unavailable`](#build-flag--allow_one_action_on_resource_unavailable) default: "true" -If set, allow at least one action to run even if the resource is not enough or unavailable. +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" +: The Java runtime version used to execute tools during the build -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]use_ijars` default: "true" +: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. -[`--[no]check_up_to_date`](#build-flag--check_up_to_date) default: "false" -Don't perform the build, just check if it is up-to-date. If all targets are up-to-date, the build completes successfully. If any step needs to be executed an error is reported and the build fails. +## Build Options -Tags: -[`execution`](#effect_tag_EXECUTION) +Options that control build execution: -[`--dynamic_local_execution_delay`](#build-flag--dynamic_local_execution_delay)`=<an integer>` default: "1000" -How many milliseconds should local execution be delayed, if remote execution was faster during a build at least once? +`--[no]allow_one_action_on_resource_unavailable` default: "true" +: If set, allow at least one action to run even if the resource is not enough or unavailable. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--dynamic_local_strategy`](#build-flag--dynamic_local_strategy)`=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated -The local strategies, in order, to use for the given mnemonic - the first applicable strategy is used. For example, `worker,sandboxed` runs actions that support persistent workers using the worker strategy, and all others using the sandboxed strategy. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `worker,sandboxed`, or`worker,sandboxed,standalone` if `experimental_local_lockfree_output` is set. Takes \[mnemonic=\]local_strategy\[,local_strategy,...\] +`--[no]check_up_to_date` default: "false" +: Don't perform the build, just check if it is up-to-date. If all targets are up-to-date, the build completes successfully. If any step needs to be executed an error is reported and the build fails. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--dynamic_remote_strategy`](#build-flag--dynamic_remote_strategy)`=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated -The remote strategies, in order, to use for the given mnemonic - the first applicable strategy is used. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `remote`, so this flag usually does not need to be set explicitly. Takes \[mnemonic=\]remote_strategy\[,remote_strategy,...\] +`--dynamic_local_execution_delay=<an integer>` default: "1000" +: How many milliseconds should local execution be delayed, if remote execution was faster during a build at least once? -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]experimental_async_execution`](#build-flag--experimental_async_execution) default: "false" -If set to true, Bazel is allowed to run action in a virtual thread. The number of actions in flight is still capped with --jobs. +`--dynamic_local_strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated +: The local strategies, in order, to use for the given mnemonic - the first applicable strategy is used. For example, `worker,sandboxed` runs actions that support persistent workers using the worker strategy, and all others using the sandboxed strategy. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `worker,sandboxed`, or`worker,sandboxed,standalone` if `experimental_local_lockfree_output` is set. Takes [mnemonic=]local\_strategy[,local\_strategy,...] -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--experimental_async_execution_max_concurrent_actions`](#build-flag--experimental_async_execution_max_concurrent_actions)`=<an integer>` default: "5000" -The number of maximum concurrent actions to run with async execution. If the value is less than --jobs, it is clamped to --jobs. +`--dynamic_remote_strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated +: The remote strategies, in order, to use for the given mnemonic - the first applicable strategy is used. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `remote`, so this flag usually does not need to be set explicitly. Takes [mnemonic=]remote\_strategy[,remote\_strategy,...] -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--experimental_docker_image`](#build-flag--experimental_docker_image)`=<a string>` default: "" -Specify a Docker image name (e.g. "ubuntu:latest") that should be used to execute a sandboxed action when using the docker strategy and the action itself doesn't already have a container-image attribute in its remote_execution_properties in the platform description. The value of this flag is passed verbatim to 'docker run', so it supports the same syntax and mechanisms as Docker itself. +`--[no]experimental_async_execution` default: "false" +: If set to true, Bazel is allowed to run action in a virtual thread. The number of actions in flight is still capped with --jobs. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_docker_use_customized_images`](#build-flag--experimental_docker_use_customized_images) default: "true" -If enabled, injects the uid and gid of the current user into the Docker image before using it. This is required if your build / tests depend on the user having a name and home directory inside the container. This is on by default, but you can disable it in case the automatic image customization feature doesn't work in your case or you know that you don't need it. +`--experimental_async_execution_max_concurrent_actions=<an integer>` default: "5000" +: The number of maximum concurrent actions to run with async execution. If the value is less than --jobs, it is clamped to --jobs. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_dynamic_exclude_tools`](#build-flag--experimental_dynamic_exclude_tools) default: "true" -When set, targets that are build "for tool" are not subject to dynamic execution. Such targets are extremely unlikely to be built incrementally and thus not worth spending local cycles on. +`--experimental_docker_image=<a string>` default: "" +: Specify a Docker image name (e.g. "ubuntu:latest") that should be used to execute a sandboxed action when using the docker strategy and the action itself doesn't already have a container-image attribute in its remote\_execution\_properties in the platform description. The value of this flag is passed verbatim to 'docker run', so it supports the same syntax and mechanisms as Docker itself. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_dynamic_local_load_factor`](#build-flag--experimental_dynamic_local_load_factor)`=<a double>` default: "0" -Controls how much load from dynamic execution to put on the local machine. This flag adjusts how many actions in dynamic execution we will schedule concurrently. It is based on the number of CPUs Blaze thinks is available, which can be controlled with the --local_resources=cpu= flag. -If this flag is 0, all actions are scheduled locally immediately. If \> 0, the amount of actions scheduled locally is limited by the number of CPUs available. If \< 1, the load factor is used to reduce the number of locally scheduled actions when the number of actions waiting to schedule is high. This lessens the load on the local machine in the clean build case, where the local machine does not contribute much. +`--[no]experimental_docker_use_customized_images` default: "true" +: If enabled, injects the uid and gid of the current user into the Docker image before using it. This is required if your build / tests depend on the user having a name and home directory inside the container. This is on by default, but you can disable it in case the automatic image customization feature doesn't work in your case or you know that you don't need it. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_dynamic_slow_remote_time`](#build-flag--experimental_dynamic_slow_remote_time)`=<An immutable length of time.>` default: "0" -If \>0, the time a dynamically run action must run remote-only before we prioritize its local execution to avoid remote timeouts. This may hide some problems on the remote execution system. Do not turn this on without monitoring of remote execution issues. +`--[no]experimental_dynamic_exclude_tools` default: "true" +: When set, targets that are build "for tool" are not subject to dynamic execution. Such targets are extremely unlikely to be built incrementally and thus not worth spending local cycles on. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]experimental_enable_docker_sandbox`](#build-flag--experimental_enable_docker_sandbox) default: "false" -Enable Docker-based sandboxing. This option has no effect if Docker is not installed. +`--experimental_dynamic_local_load_factor=<a double>` default: "0" +: Controls how much load from dynamic execution to put on the local machine. This flag adjusts how many actions in dynamic execution we will schedule concurrently. It is based on the number of CPUs Blaze thinks is available, which can be controlled with the --local\_resources=cpu= flag. + If this flag is 0, all actions are scheduled locally immediately. If > 0, the amount of actions scheduled locally is limited by the number of CPUs available. If < 1, the load factor is used to reduce the number of locally scheduled actions when the number of actions waiting to schedule is high. This lessens the load on the local machine in the clean build case, where the local machine does not contribute much. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]experimental_inmemory_sandbox_stashes`](#build-flag--experimental_inmemory_sandbox_stashes) default: "false" -If set to true, the contents of stashed sandboxes for reuse_sandbox_directories will be tracked in memory. This reduces the amount of I/O needed during reuse. Depending on the build this flag may improve wall time. Depending on the build as well this flag may use a significant amount of additional memory. +`--experimental_dynamic_slow_remote_time=<An immutable length of time.>` default: "0" +: If >0, the time a dynamically run action must run remote-only before we prioritize its local execution to avoid remote timeouts. This may hide some problems on the remote execution system. Do not turn this on without monitoring of remote execution issues. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--experimental_sandbox_async_tree_delete_idle_threads`](#build-flag--experimental_sandbox_async_tree_delete_idle_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "4" -If 0, sandboxes are deleted as soon as actions finish, blocking action completion. If greater than 0, sandboxes are deleted asynchronously in the background without blocking action completion. Asynchronous deletion uses a single thread while a command is running, but ramps up to as many threads as the value of this flag once the server becomes idle. Set to `auto` to use as many threads as the number of CPUs. A server shutdown blocks on any pending asynchronous deletions. +`--[no]experimental_enable_docker_sandbox` default: "false" +: Enable Docker-based sandboxing. This option has no effect if Docker is not installed. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_sandbox_enforce_resources_regexp`](#build-flag--experimental_sandbox_enforce_resources_regexp)`=<a valid Java regular expression>` default: "" -If true, actions whose mnemonic matches the input regex will have their resources request enforced as limits, overriding the value of --experimental_sandbox_limits, if the resource type supports it. For example a test that declares cpu:3 and resources:memory:10, will run with at most 3 cpus and 10 megabytes of memory. +`--[no]experimental_inmemory_sandbox_stashes` default: "false" +: If set to true, the contents of stashed sandboxes for reuse\_sandbox\_directories will be tracked in memory. This reduces the amount of I/O needed during reuse. Depending on the build this flag may improve wall time. Depending on the build as well this flag may use a significant amount of additional memory. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) -[`--experimental_sandbox_limits`](#build-flag--experimental_sandbox_limits)`=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated -If \> 0, each Linux sandbox will be limited to the given amount for the specified resource. Requires --incompatible_use_new_cgroup_implementation and overrides --experimental_sandbox_memory_limit_mb. Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. +`--experimental_sandbox_async_tree_delete_idle_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "4" +: If 0, sandboxes are deleted as soon as actions finish, blocking action completion. If greater than 0, sandboxes are deleted asynchronously in the background without blocking action completion. Asynchronous deletion uses a single thread while a command is running, but ramps up to as many threads as the value of this flag once the server becomes idle. Set to `auto` to use as many threads as the number of CPUs. A server shutdown blocks on any pending asynchronous deletions. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) -[`--experimental_sandbox_memory_limit_mb`](#build-flag--experimental_sandbox_memory_limit_mb)`=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" -If \> 0, each Linux sandbox will be limited to the given amount of memory (in MB). Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. +`--experimental_sandbox_enforce_resources_regexp=<a valid Java regular expression>` default: "" +: If true, actions whose mnemonic matches the input regex will have their resources request enforced as limits, overriding the value of --experimental\_sandbox\_limits, if the resource type supports it. For example a test that declares cpu:3 and resources:memory:10, will run with at most 3 cpus and 10 megabytes of memory. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_shrink_worker_pool`](#build-flag--experimental_shrink_worker_pool) default: "false" -If enabled, could shrink worker pool if worker memory pressure is high. This flag works only when flag experimental_total_worker_memory_limit_mb is enabled. +`--experimental_sandbox_limits=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated +: If > 0, each Linux sandbox will be limited to the given amount for the specified resource. Requires --incompatible\_use\_new\_cgroup\_implementation and overrides --experimental\_sandbox\_memory\_limit\_mb. Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_total_worker_memory_limit_mb`](#build-flag--experimental_total_worker_memory_limit_mb)`=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" -If this limit is greater than zero idle workers might be killed if the total memory usage of all workers exceed the limit. +`--experimental_sandbox_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" +: If > 0, each Linux sandbox will be limited to the given amount of memory (in MB). Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_use_hermetic_linux_sandbox`](#build-flag--experimental_use_hermetic_linux_sandbox) default: "false" -If set to true, do not mount root, only mount whats provided with sandbox_add_mount_pair. Input files will be hardlinked to the sandbox instead of symlinked to from the sandbox. If action input files are located on a filesystem different from the sandbox, then the input files will be copied instead. +`--[no]experimental_shrink_worker_pool` default: "false" +: If enabled, could shrink worker pool if worker memory pressure is high. This flag works only when flag experimental\_total\_worker\_memory\_limit\_mb is enabled. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]experimental_use_windows_sandbox`](#build-flag--experimental_use_windows_sandbox) default: "false" -Use Windows sandbox to run actions. If "yes", the binary provided by --experimental_windows_sandbox_path must be valid and correspond to a supported version of sandboxfs. If "auto", the binary may be missing or not compatible. +`--experimental_total_worker_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" +: If this limit is greater than zero idle workers might be killed if the total memory usage of all workers exceed the limit. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--experimental_windows_sandbox_path`](#build-flag--experimental_windows_sandbox_path)`=<a string>` default: "BazelSandbox.exe" -Path to the Windows sandbox binary to use when --experimental_use_windows_sandbox is true. If a bare name, use the first binary of that name found in the PATH. +`--[no]experimental_use_hermetic_linux_sandbox` default: "false" +: If set to true, do not mount root, only mount whats provided with sandbox\_add\_mount\_pair. Input files will be hardlinked to the sandbox instead of symlinked to from the sandbox. If action input files are located on a filesystem different from the sandbox, then the input files will be copied instead. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_worker_allowlist`](#build-flag--experimental_worker_allowlist)`=<comma-separated set of options>` default: see description -If non-empty, only allow using persistent workers with the given worker key mnemonic. +`--[no]experimental_use_windows_sandbox` default: "false" +: Use Windows sandbox to run actions. If "yes", the binary provided by --experimental\_windows\_sandbox\_path must be valid and correspond to a supported version of sandboxfs. If "auto", the binary may be missing or not compatible. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_worker_cancellation`](#build-flag--experimental_worker_cancellation) default: "false" -If enabled, Bazel may send cancellation requests to workers that support them. +`--experimental_windows_sandbox_path=<a string>` default: "BazelSandbox.exe" +: Path to the Windows sandbox binary to use when --experimental\_use\_windows\_sandbox is true. If a bare name, use the first binary of that name found in the PATH. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_worker_memory_limit_mb`](#build-flag--experimental_worker_memory_limit_mb)`=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" -If this limit is greater than zero, workers might be killed if the memory usage of the worker exceeds the limit. If not used together with dynamic execution and `--experimental_dynamic_ignore_local_signals=9`, this may crash your build. +`--experimental_worker_allowlist=<comma-separated set of options>` default: see description +: If non-empty, only allow using persistent workers with the given worker key mnemonic. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--experimental_worker_metrics_poll_interval`](#build-flag--experimental_worker_metrics_poll_interval)`=<An immutable length of time.>` default: "5s" -The interval between collecting worker metrics and possibly attempting evictions. Cannot effectively be less than 1s for performance reasons. +`--[no]experimental_worker_cancellation` default: "false" +: If enabled, Bazel may send cancellation requests to workers that support them. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_worker_multiplex_sandboxing`](#build-flag--experimental_worker_multiplex_sandboxing) default: "false" -If enabled, multiplex workers with a 'supports-multiplex-sandboxing' execution requirement will run in a sandboxed environment, using a separate sandbox directory per work request. Multiplex workers with the execution requirement are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. +`--experimental_worker_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" +: If this limit is greater than zero, workers might be killed if the memory usage of the worker exceeds the limit. If not used together with dynamic execution and `--experimental_dynamic_ignore_local_signals=9`, this may crash your build. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]experimental_worker_sandbox_hardening`](#build-flag--experimental_worker_sandbox_hardening) default: "false" -If enabled, workers are run in a hardened sandbox, if the implementation allows it. If hardening is enabled then tmp directories are distinct for different workers. +`--experimental_worker_metrics_poll_interval=<An immutable length of time.>` default: "5s" +: The interval between collecting worker metrics and possibly attempting evictions. Cannot effectively be less than 1s for performance reasons. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--experimental_worker_sandbox_inmemory_tracking`](#build-flag--experimental_worker_sandbox_inmemory_tracking)`=<a string>` multiple uses are accumulated -A worker key mnemonic for which the contents of the sandbox directory are tracked in memory. This may improve build performance at the cost of additional memory usage. Only affects sandboxed workers. May be specified multiple times for different mnemonics. +`--[no]experimental_worker_multiplex_sandboxing` default: "false" +: If enabled, multiplex workers with a 'supports-multiplex-sandboxing' execution requirement will run in a sandboxed environment, using a separate sandbox directory per work request. Multiplex workers with the execution requirement are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_worker_strict_flagfiles`](#build-flag--experimental_worker_strict_flagfiles) default: "false" -If enabled, actions arguments for workers that do not follow the worker specification will cause an error. Worker arguments must have exactly one @flagfile argument as the last of its list of arguments. +`--[no]experimental_worker_sandbox_hardening` default: "false" +: If enabled, workers are run in a hardened sandbox, if the implementation allows it. If hardening is enabled then tmp directories are distinct for different workers. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--genrule_strategy`](#build-flag--genrule_strategy)`=<comma-separated list of options>` default: "" -Specify how to execute genrules. This flag will be phased out. Instead, use --spawn_strategy=\<value\> to control all actions or --strategy=Genrule=\<value\> to control genrules only. +`--experimental_worker_sandbox_inmemory_tracking=<a string>` multiple uses are accumulated +: A worker key mnemonic for which the contents of the sandbox directory are tracked in memory. This may improve build performance at the cost of additional memory usage. Only affects sandboxed workers. May be specified multiple times for different mnemonics. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]incompatible_use_new_cgroup_implementation`](#build-flag--incompatible_use_new_cgroup_implementation) default: "true" -If true, use the new implementation for cgroups. The old implementation only supports the memory controller and ignores the value of --experimental_sandbox_limits. +`--[no]experimental_worker_strict_flagfiles` default: "false" +: If enabled, actions arguments for workers that do not follow the worker specification will cause an error. Worker arguments must have exactly one @flagfile argument as the last of its list of arguments. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]internal_spawn_scheduler`](#build-flag--internal_spawn_scheduler) default: "true" -Placeholder option so that we can tell in Blaze whether the spawn scheduler was enabled. +`--genrule_strategy=<comma-separated list of options>` default: "" +: Specify how to execute genrules. This flag will be phased out. Instead, use --spawn\_strategy=\<value\> to control all actions or --strategy=Genrule=\<value\> to control genrules only. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--jobs`](#build-flag--jobs)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` \[`-j`\] default: "auto" -The number of concurrent jobs to run. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". Values must be between 1 and 5000. Values above 2500 may cause memory issues. "auto" calculates a reasonable default based on host resources. +`--[no]incompatible_use_new_cgroup_implementation` default: "true" +: If true, use the new implementation for cgroups. The old implementation only supports the memory controller and ignores the value of --experimental\_sandbox\_limits. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]keep_going`](#build-flag--keep_going) \[`-k`\] default: "false" -Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. +`--[no]internal_spawn_scheduler` default: "true" +: Placeholder option so that we can tell in Blaze whether the spawn scheduler was enabled. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--loading_phase_threads`](#build-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. +`--jobs=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` [`-j`] default: "auto" +: The number of concurrent jobs to run. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". Values must be between 1 and 5000. Values above 2500 may cause memory issues. "auto" calculates a reasonable default based on host resources. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) -[`--[no]reuse_sandbox_directories`](#build-flag--reuse_sandbox_directories) default: "true" -If set to true, directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs. +`--[no]keep_going` [`-k`] default: "false" +: Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--sandbox_base`](#build-flag--sandbox_base)`=<a string>` default: "" -Lets the sandbox create its sandbox directories underneath this path. Specify a path on tmpfs (like /run/shm) to possibly improve performance a lot when your build / tests have many input files. Note: You need enough RAM and free space on the tmpfs to hold output and intermediate files generated by running actions. +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--[no]sandbox_enable_loopback_device`](#build-flag--sandbox_enable_loopback_device) default: "true" -If true, a loopback device will be set up in the linux-sandbox network namespace for local actions. +`--[no]reuse_sandbox_directories` default: "true" +: If set to true, directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) -[`--[no]sandbox_explicit_pseudoterminal`](#build-flag--sandbox_explicit_pseudoterminal) default: "false" -Explicitly enable the creation of pseudoterminals for sandboxed actions. Some linux distributions require setting the group id of the process to 'tty' inside the sandbox in order for pseudoterminals to function. If this is causing issues, this flag can be disabled to enable other groups to be used. +`--sandbox_base=<a string>` default: "" +: Lets the sandbox create its sandbox directories underneath this path. Specify a path on tmpfs (like /run/shm) to possibly improve performance a lot when your build / tests have many input files. Note: You need enough RAM and free space on the tmpfs to hold output and intermediate files generated by running actions. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) -[`--sandbox_tmpfs_path`](#build-flag--sandbox_tmpfs_path)`=<an absolute path>` multiple uses are accumulated -For sandboxed actions, mount an empty, writable directory at this absolute path (if supported by the sandboxing implementation, ignored otherwise). +`--[no]sandbox_enable_loopback_device` default: "true" +: If true, a loopback device will be set up in the linux-sandbox network namespace for local actions. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]skip_incompatible_explicit_targets`](#build-flag--skip_incompatible_explicit_targets) default: "false" -Skip incompatible targets that are explicitly listed on the command line. By default, building such targets results in an error but they are silently skipped when this option is enabled. See: https://bazel.build/extending/platforms#skipping-incompatible-targets +`--[no]sandbox_explicit_pseudoterminal` default: "false" +: Explicitly enable the creation of pseudoterminals for sandboxed actions. Some linux distributions require setting the group id of the process to 'tty' inside the sandbox in order for pseudoterminals to function. If this is causing issues, this flag can be disabled to enable other groups to be used. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--spawn_strategy`](#build-flag--spawn_strategy)`=<comma-separated list of options>` default: "" -Specify how spawn actions are executed by default. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". See https://blog.bazel.build/2019/06/19/list-strategy.html for details. +`--sandbox_tmpfs_path=<an absolute path>` multiple uses are accumulated +: For sandboxed actions, mount an empty, writable directory at this absolute path (if supported by the sandboxing implementation, ignored otherwise). -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) -[`--strategy`](#build-flag--strategy)`=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated -Specify how to distribute compilation of other spawn actions. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". This flag overrides the values set by --spawn_strategy (and --genrule_strategy if used with mnemonic Genrule). See https://blog.bazel.build/2019/06/19/list-strategy.html for details. +`--[no]skip_incompatible_explicit_targets` default: "false" +: Skip incompatible targets that are explicitly listed on the command line. By default, building such targets results in an error but they are silently skipped when this option is enabled. See: https://bazel.build/extending/platforms#skipping-incompatible-targets -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--strategy_regexp`](#build-flag--strategy_regexp)`=<a '<RegexFilter>=value[,value]' assignment>` multiple uses are accumulated -Override which spawn strategy should be used to execute spawn actions that have descriptions matching a certain regex_filter. See --per_file_copt for details onregex_filter matching. The last regex_filter that matches the description is used. This option overrides other flags for specifying strategy. Example: --strategy_regexp=//foo.*.cc,-//foo/bar=local means to run actions using local strategy if their descriptions match //foo.*.cc but not //foo/bar. Example: --strategy_regexp='Compiling.\*/bar=local --strategy_regexp=Compiling=sandboxed will run 'Compiling //foo/bar/baz' with the 'local' strategy, but reversing the order would run it with 'sandboxed'. +`--spawn_strategy=<comma-separated list of options>` default: "" +: Specify how spawn actions are executed by default. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". See https://blog.bazel.build/2019/06/19/list-strategy.html for details. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--worker_extra_flag`](#build-flag--worker_extra_flag)`=<a 'name=value' assignment>` multiple uses are accumulated -Extra command-flags that will be passed to worker processes in addition to --persistent_worker, keyed by mnemonic (e.g. --worker_extra_flag=Javac=--debug. +`--strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated +: Specify how to distribute compilation of other spawn actions. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". This flag overrides the values set by --spawn\_strategy (and --genrule\_strategy if used with mnemonic Genrule). See https://blog.bazel.build/2019/06/19/list-strategy.html for details. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--worker_max_instances`](#build-flag--worker_max_instances)`=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated -How many instances of each kind of persistent worker may be launched if you use the 'worker' strategy. May be specified as \[name=value\] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. +`--strategy_regexp=<a '<RegexFilter>=value[,value]' assignment>` multiple uses are accumulated +: Override which spawn strategy should be used to execute spawn actions that have descriptions matching a certain regex\_filter. See --per\_file\_copt for details onregex\_filter matching. The last regex\_filter that matches the description is used. This option overrides other flags for specifying strategy. Example: --strategy\_regexp=//foo.*.cc,-//foo/bar=local means to run actions using local strategy if their descriptions match //foo.*.cc but not //foo/bar. Example: --strategy\_regexp='Compiling.\*/bar=local --strategy\_regexp=Compiling=sandboxed will run 'Compiling //foo/bar/baz' with the 'local' strategy, but reversing the order would run it with 'sandboxed'. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--worker_max_multiplex_instances`](#build-flag--worker_max_multiplex_instances)`=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated -How many WorkRequests a multiplex worker process may receive in parallel if you use the 'worker' strategy with --worker_multiplex. May be specified as \[name=value\] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. +`--worker_extra_flag=<a 'name=value' assignment>` multiple uses are accumulated +: Extra command-flags that will be passed to worker processes in addition to --persistent\_worker, keyed by mnemonic (e.g. --worker\_extra\_flag=Javac=--debug. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]worker_multiplex`](#build-flag--worker_multiplex) default: "true" -If enabled, workers will use multiplexing if they support it. +`--worker_max_instances=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated +: How many instances of each kind of persistent worker may be launched if you use the 'worker' strategy. May be specified as [name=value] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]worker_quit_after_build`](#build-flag--worker_quit_after_build) default: "false" -If enabled, all workers quit after a build is done. +`--worker_max_multiplex_instances=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated +: How many WorkRequests a multiplex worker process may receive in parallel if you use the 'worker' strategy with --worker\_multiplex. May be specified as [name=value] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. -Tags: -[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]worker_sandboxing`](#build-flag--worker_sandboxing) default: "false" -If enabled, singleplex workers will run in a sandboxed environment. Singleplex workers are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. +`--[no]worker_multiplex` default: "true" +: If enabled, workers will use multiplexing if they support it. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]worker_verbose`](#build-flag--worker_verbose) default: "false" -If enabled, prints verbose messages when workers are started, shutdown, ... +`--[no]worker_quit_after_build` default: "false" +: If enabled, all workers quit after a build is done. -<!-- --> + Tags: + [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]build`](#build-flag--build) default: "true" -Execute the build; this is the usual behaviour. Specifying --nobuild causes the build to stop before executing the build actions, returning zero iff the package loading and analysis phases completed successfully; this mode is useful for testing those phases. +`--[no]worker_sandboxing` default: "false" +: If enabled, singleplex workers will run in a sandboxed environment. Singleplex workers are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_use_validation_aspect`](#build-flag--experimental_use_validation_aspect) default: "false" -Whether to run validation actions using aspect (for parallelism with tests). +`--[no]worker_verbose` default: "false" +: If enabled, prints verbose messages when workers are started, shutdown, ... -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that control the output of the command: -[`--output_groups`](#build-flag--output_groups)`=<comma-separated list of options>` multiple uses are accumulated -A list of comma-separated output group names, each of which optionally prefixed by a + or a -. A group prefixed by + is added to the default set of output groups, while a group prefixed by - is removed from the default set. If at least one group is not prefixed, the default set of output groups is omitted. For example, --output_groups=+foo,+bar builds the union of the default set, foo, and bar, while --output_groups=foo,bar overrides the default set such that only foo and bar are built. +`--[no]build` default: "true" +: Execute the build; this is the usual behaviour. Specifying --nobuild causes the build to stop before executing the build actions, returning zero iff the package loading and analysis phases completed successfully; this mode is useful for testing those phases. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]run_validations`](#build-flag--run_validations) default: "true" -Whether to run validation actions as part of the build. See https://bazel.build/extending/rules#validation_actions +`--[no]experimental_use_validation_aspect` default: "false" +: Whether to run validation actions using aspect (for parallelism with tests). -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--serialized_frontier_profile`](#build-flag--serialized_frontier_profile)`=<a string>` default: "" -Dump a profile of serialized frontier bytes. Specifies the output path. +`--output_groups=<comma-separated list of options>` multiple uses are accumulated +: A list of comma-separated output group names, each of which optionally prefixed by a + or a -. A group prefixed by + is added to the default set of output groups, while a group prefixed by - is removed from the default set. If at least one group is not prefixed, the default set of output groups is omitted. For example, --output\_groups=+foo,+bar builds the union of the default set, foo, and bar, while --output\_groups=foo,bar overrides the default set such that only foo and bar are built. -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -<!-- --> +`--[no]run_validations` default: "true" +: Whether to run validation actions as part of the build. See https://bazel.build/extending/rules#validation\_actions -[`--aspects`](#build-flag--aspects)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of aspects to be applied to top-level targets. In the list, if aspect some_aspect specifies required aspect providers via required_aspect_providers, some_aspect will run after every aspect that was mentioned before it in the aspects list whose advertised providers satisfy some_aspect required aspect providers. Moreover, some_aspect will run after all its required aspects specified by requires attribute. some_aspect will then have access to the values of those aspects' providers. \<bzl-file-label\>%\<aspect_name\>, for example '//tools:my_def.bzl%my_aspect', where 'my_aspect' is a top-level value from a file tools/my_def.bzl + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--bep_maximum_open_remote_upload_files`](#build-flag--bep_maximum_open_remote_upload_files)`=<an integer>` default: "-1" -Maximum number of open files allowed during BEP artifact upload. +`--serialized_frontier_profile=<a string>` default: "" +: Dump a profile of serialized frontier bytes. Specifies the output path. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]experimental_convenience_symlinks`](#build-flag--experimental_convenience_symlinks) default: "normal" -This flag controls how the convenience symlinks (the symlinks that appear in the workspace after the build) will be managed. Possible values: -normal (default): Each kind of convenience symlink will be created or deleted, as determined by the build. -clean: All symlinks will be unconditionally deleted. -ignore: Symlinks will not be created or cleaned up. -log_only: Generate log messages as if 'normal' were passed, but don't actually perform any filesystem operations (useful for tools). -Note that only symlinks whose names are generated by the current value of --symlink_prefix can be affected; if the prefix changes, any pre-existing symlinks will be left alone. +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--aspects=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of aspects to be applied to top-level targets. In the list, if aspect some\_aspect specifies required aspect providers via required\_aspect\_providers, some\_aspect will run after every aspect that was mentioned before it in the aspects list whose advertised providers satisfy some\_aspect required aspect providers. Moreover, some\_aspect will run after all its required aspects specified by requires attribute. some\_aspect will then have access to the values of those aspects' providers. \<bzl-file-label\>%\<aspect\_name\>, for example '//tools:my\_def.bzl%my\_aspect', where 'my\_aspect' is a top-level value from a file tools/my\_def.bzl -[`--[no]experimental_convenience_symlinks_bep_event`](#build-flag--experimental_convenience_symlinks_bep_event) default: "true" -This flag controls whether or not we will post the build eventConvenienceSymlinksIdentified to the BuildEventProtocol. If the value is true, the BuildEventProtocol will have an entry for convenienceSymlinksIdentified, listing all of the convenience symlinks created in your workspace. If false, then the convenienceSymlinksIdentified entry in the BuildEventProtocol will be empty. +`--bep_maximum_open_remote_upload_files=<an integer>` default: "-1" +: Maximum number of open files allowed during BEP artifact upload. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--remote_download_all`](#build-flag--remote_download_all) -Downloads all remote outputs to the local machine. This flag is an alias for --remote_download_outputs=all. +`--[no]experimental_convenience_symlinks` default: "normal" +: This flag controls how the convenience symlinks (the symlinks that appear in the workspace after the build) will be managed. Possible values: + normal (default): Each kind of convenience symlink will be created or deleted, as determined by the build. + clean: All symlinks will be unconditionally deleted. + ignore: Symlinks will not be created or cleaned up. + log\_only: Generate log messages as if 'normal' were passed, but don't actually perform any filesystem operations (useful for tools). + Note that only symlinks whose names are generated by the current value of --symlink\_prefix can be affected; if the prefix changes, any pre-existing symlinks will be left alone. -Expands to: -  [`--remote_download_outputs=all`](#flag--remote_download_outputs) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_convenience_symlinks_bep_event` default: "true" +: This flag controls whether or not we will post the build eventConvenienceSymlinksIdentified to the BuildEventProtocol. If the value is true, the BuildEventProtocol will have an entry for convenienceSymlinksIdentified, listing all of the convenience symlinks created in your workspace. If false, then the convenienceSymlinksIdentified entry in the BuildEventProtocol will be empty. -[`--remote_download_minimal`](#build-flag--remote_download_minimal) -Does not download any remote build outputs to the local machine. This flag is an alias for --remote_download_outputs=minimal. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Expands to: -  [`--remote_download_outputs=minimal`](#flag--remote_download_outputs) +`--remote_download_all` +: Downloads all remote outputs to the local machine. This flag is an alias for --remote\_download\_outputs=all. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Expands to: + +   `--remote_download_outputs=all` -[`--remote_download_outputs`](#build-flag--remote_download_outputs)`=<all, minimal or toplevel>` default: "toplevel" -If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--remote_download_minimal` +: Does not download any remote build outputs to the local machine. This flag is an alias for --remote\_download\_outputs=minimal. -[`--remote_download_symlink_template`](#build-flag--remote_download_symlink_template)`=<a string>` default: "" -Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. + Expands to: + +   `--remote_download_outputs=minimal` -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--remote_download_toplevel`](#build-flag--remote_download_toplevel) -Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote_download_outputs=toplevel. +`--remote_download_outputs=<all, minimal or toplevel>` default: "toplevel" +: If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. -Expands to: -  [`--remote_download_outputs=toplevel`](#flag--remote_download_outputs) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--remote_download_symlink_template=<a string>` default: "" +: Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain \{hash\} and \{size\_bytes\} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. -[`--symlink_prefix`](#build-flag--symlink_prefix)`=<a string>` default: see description -The prefix that is prepended to any of the convenience symlinks that are created after a build. If omitted, the default value is the name of the build tool followed by a hyphen. If '/' is passed, then no symlinks are created and no warning is emitted. Warning: the special functionality for '/' will be deprecated soon; use --experimental_convenience_symlinks=ignore instead. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--remote_download_toplevel` +: Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote\_download\_outputs=toplevel. -<!-- --> + Expands to: + +   `--remote_download_outputs=toplevel` -[`--[no]experimental_docker_privileged`](#build-flag--experimental_docker_privileged) default: "false" -If enabled, Bazel will pass the --privileged flag to 'docker run' when running actions. This might be required by your build, but it might also result in reduced hermeticity. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--symlink_prefix=<a string>` default: see description +: The prefix that is prepended to any of the convenience symlinks that are created after a build. If omitted, the default value is the name of the build tool followed by a hyphen. If '/' is passed, then no symlinks are created and no warning is emitted. Warning: the special functionality for '/' will be deprecated soon; use --experimental\_convenience\_symlinks=ignore instead. -[`--[no]experimental_sandboxfs_map_symlink_targets`](#build-flag--experimental_sandboxfs_map_symlink_targets) default: "false" -No-op + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -[`--sandbox_add_mount_pair`](#build-flag--sandbox_add_mount_pair)`=<a single path or a 'source:target' pair>` multiple uses are accumulated -Add additional path pair to mount in sandbox. +`--[no]experimental_docker_privileged` default: "false" +: If enabled, Bazel will pass the --privileged flag to 'docker run' when running actions. This might be required by your build, but it might also result in reduced hermeticity. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--sandbox_block_path`](#build-flag--sandbox_block_path)`=<a string>` multiple uses are accumulated -For sandboxed actions, disallow access to this path. +`--[no]experimental_sandboxfs_map_symlink_targets` default: "false" +: No-op -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) -[`--[no]sandbox_default_allow_network`](#build-flag--sandbox_default_allow_network) default: "true" -Allow network access by default for actions; this may not work with all sandboxing implementations. +`--sandbox_add_mount_pair=<a single path or a 'source:target' pair>` multiple uses are accumulated +: Add additional path pair to mount in sandbox. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]sandbox_fake_hostname`](#build-flag--sandbox_fake_hostname) default: "false" -Change the current hostname to 'localhost' for sandboxed actions. +`--sandbox_block_path=<a string>` multiple uses are accumulated +: For sandboxed actions, disallow access to this path. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]sandbox_fake_username`](#build-flag--sandbox_fake_username) default: "false" -Change the current username to 'nobody' for sandboxed actions. +`--[no]sandbox_default_allow_network` default: "true" +: Allow network access by default for actions; this may not work with all sandboxing implementations. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--sandbox_writable_path`](#build-flag--sandbox_writable_path)`=<a string>` multiple uses are accumulated -For sandboxed actions, make an existing directory writable in the sandbox (if supported by the sandboxing implementation, ignored otherwise). +`--[no]sandbox_fake_hostname` default: "false" +: Change the current hostname to 'localhost' for sandboxed actions. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -<!-- --> +`--[no]sandbox_fake_username` default: "false" +: Change the current username to 'nobody' for sandboxed actions. -[`--[no]incompatible_config_setting_private_default_visibility`](#build-flag--incompatible_config_setting_private_default_visibility) default: "false" -If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--sandbox_writable_path=<a string>` multiple uses are accumulated +: For sandboxed actions, make an existing directory writable in the sandbox (if supported by the sandboxing implementation, ignored otherwise). -[`--[no]incompatible_enforce_config_setting_visibility`](#build-flag--incompatible_enforce_config_setting_visibility) default: "true" -If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<!-- --> +`--[no]incompatible_config_setting_private_default_visibility` default: "false" +: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. -[`--[no]check_tests_up_to_date`](#build-flag--check_tests_up_to_date) default: "false" -Don't run tests, just check if they are up-to-date. If all tests results are up-to-date, the testing completes successfully. If any test needs to be built or executed, an error is reported and the testing fails. This option implies --check_up_to_date behavior. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]incompatible_enforce_config_setting_visibility` default: "true" +: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. -[`--flaky_test_attempts`](#build-flag--flaky_test_attempts)`=<a positive integer, the string "default", or test_regex@attempts. This flag may be passed more than once>` multiple uses are accumulated -Each test will be retried up to the specified number of times in case of any test failure. Tests that required more than one attempt to pass are marked as 'FLAKY' in the test summary. Normally the value specified is just an integer or the string 'default'. If an integer, then all tests will be run up to N times. If 'default', then only a single test attempt will be made for regular tests and three for tests marked explicitly as flaky by their rule (flaky=1 attribute). Alternate syntax: regex_filter@flaky_test_attempts. Where flaky_test_attempts is as above and regex_filter stands for a list of include and exclude regular expression patterns (Also see --runs_per_test). Example: --flaky_test_attempts=//foo/.*,-//foo/bar/.*@3 deflakes all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, behavior is as if 'default' above. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`execution`](#effect_tag_EXECUTION) +Options that govern the behavior of the test environment or test runner: -[`--local_test_jobs`](#build-flag--local_test_jobs)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -The max number of local test jobs to run concurrently. Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". 0 means local resources will limit the number of local test jobs to run concurrently instead. Setting this greater than the value for --jobs is ineffectual. +`--[no]check_tests_up_to_date` default: "false" +: Don't run tests, just check if they are up-to-date. If all tests results are up-to-date, the testing completes successfully. If any test needs to be built or executed, an error is reported and the testing fails. This option implies --check\_up\_to\_date behavior. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]test_keep_going`](#build-flag--test_keep_going) default: "true" -When disabled, any non-passing test will cause the entire build to stop. By default all tests are run, even if some do not pass. +`--flaky_test_attempts=<a positive integer, the string "default", or test_regex@attempts. This flag may be passed more than once>` multiple uses are accumulated +: Each test will be retried up to the specified number of times in case of any test failure. Tests that required more than one attempt to pass are marked as 'FLAKY' in the test summary. Normally the value specified is just an integer or the string 'default'. If an integer, then all tests will be run up to N times. If 'default', then only a single test attempt will be made for regular tests and three for tests marked explicitly as flaky by their rule (flaky=1 attribute). Alternate syntax: regex\_filter@flaky\_test\_attempts. Where flaky\_test\_attempts is as above and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --runs\_per\_test). Example: --flaky\_test\_attempts=//foo/.*,-//foo/bar/.*@3 deflakes all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, behavior is as if 'default' above. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--test_strategy`](#build-flag--test_strategy)`=<a string>` default: "" -Specifies which strategy to use when running tests. +`--local_test_jobs=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +: The max number of local test jobs to run concurrently. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". 0 means local resources will limit the number of local test jobs to run concurrently instead. Setting this greater than the value for --jobs is ineffectual. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--test_tmpdir`](#build-flag--test_tmpdir)`=<a path>` default: see description -Specifies the base temporary directory for 'bazel test' to use. +`--[no]test_keep_going` default: "true" +: When disabled, any non-passing test will cause the entire build to stop. By default all tests are run, even if some do not pass. -<!-- --> + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--cache_computed_file_digests`](#build-flag--cache_computed_file_digests)`=<a long integer>` default: "50000" -If greater than 0, configures Bazel to cache file digests in memory based on their metadata instead of recomputing the digests from disk every time they are needed. Setting this to 0 ensures correctness because not all file changes can be noted from file metadata. When not 0, the number indicates the size of the cache as the number of file digests to be cached. +`--test_strategy=<a string>` default: "" +: Specifies which strategy to use when running tests. -[`--experimental_active_directories`](#build-flag--experimental_active_directories)`=<comma-separated list of options>` default: "" -Active directories for Skyfocus and remote analysis caching. Specify as comma-separated workspace root-relative paths. This is a stateful flag. Defining one persists it for subsequent invocations, until it is redefined with a new set. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--test_tmpdir=<a path>` default: see description +: Specifies the base temporary directory for 'bazel test' to use. -[`--[no]experimental_cpu_load_scheduling`](#build-flag--experimental_cpu_load_scheduling) default: "false" -Enables the experimental local execution scheduling based on CPU load, not estimation of actions one by one. Experimental scheduling have showed the large benefit on a large local builds on a powerful machines with the large number of cores. Reccommended to use with --local_resources=cpu=HOST_CPUS +Options that trigger optimizations of the build time: -Tags: -[`execution`](#effect_tag_EXECUTION) +`--cache_computed_file_digests=<a long integer>` default: "50000" +: If greater than 0, configures Bazel to cache file digests in memory based on their metadata instead of recomputing the digests from disk every time they are needed. Setting this to 0 ensures correctness because not all file changes can be noted from file metadata. When not 0, the number indicates the size of the cache as the number of file digests to be cached. -[`--experimental_dynamic_ignore_local_signals`](#build-flag--experimental_dynamic_ignore_local_signals)`=<a comma-separated list of signal numbers>` default: see description -Takes a list of OS signal numbers. If a local branch of dynamic execution gets killed with any of these signals, the remote branch will be allowed to finish instead. For persistent workers, this only affects signals that kill the worker process. +`--experimental_active_directories=<comma-separated list of options>` default: "" +: Active directories for Skyfocus and remote analysis caching. Specify as comma-separated workspace root-relative paths. This is a stateful flag. Defining one persists it for subsequent invocations, until it is redefined with a new set. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]experimental_enable_skyfocus`](#build-flag--experimental_enable_skyfocus) default: "false" -If true, enable the use of --experimental_active_directories to reduce Bazel's memory footprint for incremental builds. This feature is known as Skyfocus. +`--[no]experimental_cpu_load_scheduling` default: "false" +: Enables the experimental local execution scheduling based on CPU load, not estimation of actions one by one. Experimental scheduling have showed the large benefit on a large local builds on a powerful machines with the large number of cores. Reccommended to use with --local\_resources=cpu=HOST\_CPUS -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--local_cpu_resources`](#build-flag--local_cpu_resources)`=<an integer, or "HOST_CPUS", optionally followed by [-|*]<float>.>` default: "HOST_CPUS" -Explicitly set the total number of local CPU cores available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST_CPUS", optionally followed by \[-\|*\]\<float\> (eg. HOST_CPUS*.5 to use half the available CPU cores). By default, ("HOST_CPUS"), Bazel will query system configuration to estimate the number of CPU cores available. +`--experimental_dynamic_ignore_local_signals=<a comma-separated list of signal numbers>` default: see description +: Takes a list of OS signal numbers. If a local branch of dynamic execution gets killed with any of these signals, the remote branch will be allowed to finish instead. For persistent workers, this only affects signals that kill the worker process. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--local_extra_resources`](#build-flag--local_extra_resources)`=<a named float, 'name=value'>` multiple uses are accumulated -Set the number of extra resources available to Bazel. Takes in a string-float pair. Can be used multiple times to specify multiple types of extra resources. Bazel will limit concurrently running actions based on the available extra resources and the extra resources required. Tests can declare the amount of extra resources they need by using a tag of the "resources:\<resoucename\>:\<amount\>" format. Available CPU, RAM and resources cannot be set with this flag. +`--[no]experimental_enable_skyfocus` default: "false" +: If true, enable the use of --experimental\_active\_directories to reduce Bazel's memory footprint for incremental builds. This feature is known as Skyfocus. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--local_ram_resources`](#build-flag--local_ram_resources)`=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "HOST_RAM\*.67" -Explicitly set the total amount of local host RAM (in MB) available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST_RAM", optionally followed by \[-\|*\]\<float\> (eg. HOST_RAM*.5 to use half the available RAM). By default, ("HOST_RAM\*.67"), Bazel will query system configuration to estimate the amount of RAM available and will use 67% of it. +`--local_cpu_resources=<an integer, or "HOST_CPUS", optionally followed by [-|*]<float>.>` default: "HOST\_CPUS" +: Explicitly set the total number of local CPU cores available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST\_CPUS", optionally followed by [-|*]\<float\> (eg. HOST\_CPUS*.5 to use half the available CPU cores). By default, ("HOST\_CPUS"), Bazel will query system configuration to estimate the number of CPU cores available. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--local_resources`](#build-flag--local_resources)`=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated -Set the number of resources available to Bazel. Takes in an assignment to a float or HOST_RAM/HOST_CPUS, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.5 to use half the available RAM). Can be used multiple times to specify multiple types of resources. Bazel will limit concurrently running actions based on the available resources and the resources required. Tests can declare the amount of resources they need by using a tag of the "resources:\<resource name\>:\<amount\>" format. Overrides resources specified by --local\_{cpu\|ram\|extra}\_resources. +`--local_extra_resources=<a named float, 'name=value'>` multiple uses are accumulated +: Set the number of extra resources available to Bazel. Takes in a string-float pair. Can be used multiple times to specify multiple types of extra resources. Bazel will limit concurrently running actions based on the available extra resources and the extra resources required. Tests can declare the amount of extra resources they need by using a tag of the "resources:\<resoucename\>:\<amount\>" format. Available CPU, RAM and resources cannot be set with this flag. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -<!-- --> +`--local_ram_resources=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "HOST\_RAM\*.67" +: Explicitly set the total amount of local host RAM (in MB) available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST\_RAM", optionally followed by [-|*]\<float\> (eg. HOST\_RAM*.5 to use half the available RAM). By default, ("HOST\_RAM\*.67"), Bazel will query system configuration to estimate the amount of RAM available and will use 67% of it. -[`--build_event_upload_max_retries`](#build-flag--build_event_upload_max_retries)`=<an integer>` default: "4" -The maximum number of times Bazel should retry uploading a build event. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +`--local_resources=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated +: Set the number of resources available to Bazel. Takes in an assignment to a float or HOST\_RAM/HOST\_CPUS, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.5 to use half the available RAM). Can be used multiple times to specify multiple types of resources. Bazel will limit concurrently running actions based on the available resources and the resources required. Tests can declare the amount of resources they need by using a tag of the "resources:<resource name>:\<amount\>" format. Overrides resources specified by --local\_\{cpu|ram|extra\}\_resources. -[`--[no]debug_spawn_scheduler`](#build-flag--debug_spawn_scheduler) default: "false" + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]experimental_bep_target_summary`](#build-flag--experimental_bep_target_summary) default: "false" -Whether to publish TargetSummary events. +Options that affect the verbosity, format or location of logging: -[`--[no]experimental_build_event_expand_filesets`](#build-flag--experimental_build_event_expand_filesets) default: "false" -If true, expand Filesets in the BEP when presenting output files. +`--build_event_upload_max_retries=<an integer>` default: "4" +: The maximum number of times Bazel should retry uploading a build event. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--experimental_build_event_output_group_mode`](#build-flag--experimental_build_event_output_group_mode)`=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated -Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED_SET_OF_FILES_ONLY', 'INLINE_ONLY', or 'BOTH'. The default value is 'NAMED_SET_OF_FILES_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental_build_event_output_group_mode=baseline.lcov=both +`--[no]debug_spawn_scheduler` default: "false" -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--experimental_build_event_upload_retry_minimum_delay`](#build-flag--experimental_build_event_upload_retry_minimum_delay)`=<An immutable length of time.>` default: "1s" -Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) +`--[no]experimental_bep_target_summary` default: "false" +: Whether to publish TargetSummary events. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +`--[no]experimental_build_event_expand_filesets` default: "false" +: If true, expand Filesets in the BEP when presenting output files. -[`--experimental_build_event_upload_strategy`](#build-flag--experimental_build_event_upload_strategy)`=<a string>` default: see description -Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--experimental_build_event_output_group_mode=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated +: Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED\_SET\_OF\_FILES\_ONLY', 'INLINE\_ONLY', or 'BOTH'. The default value is 'NAMED\_SET\_OF\_FILES\_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental\_build\_event\_output\_group\_mode=baseline.lcov=both -[`--[no]experimental_docker_verbose`](#build-flag--experimental_docker_verbose) default: "false" -If enabled, Bazel will print more verbose messages about the Docker sandbox strategy. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--experimental_build_event_upload_retry_minimum_delay=<An immutable length of time.>` default: "1s" +: Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) -[`--experimental_frontier_violation_check`](#build-flag--experimental_frontier_violation_check)`=<strict, warn or disabled_for_testing>` default: "strict" -Strategies to handle potential incorrectness from changes beyond the frontier (i.e. outside the active directories) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--experimental_build_event_upload_strategy=<a string>` default: see description +: Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. -[`--[no]experimental_frontier_violation_verbose`](#build-flag--experimental_frontier_violation_verbose) default: "false" -If true, Bazel will print instructions for fixing Skycache violations + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]experimental_docker_verbose` default: "false" +: If enabled, Bazel will print more verbose messages about the Docker sandbox strategy. -[`--[no]experimental_materialize_param_files_directly`](#build-flag--experimental_materialize_param_files_directly) default: "false" -If materializing param files, do so with direct writes to disk. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--experimental_frontier_violation_check=<strict, warn or disabled_for_testing>` default: "strict" +: Strategies to handle potential incorrectness from changes beyond the frontier (i.e. outside the active directories) -[`--[no]experimental_run_bep_event_include_residue`](#build-flag--experimental_run_bep_event_include_residue) default: "false" -Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_frontier_violation_verbose` default: "false" +: If true, Bazel will print instructions for fixing Skycache violations -[`--experimental_skyfocus_dump_keys`](#build-flag--experimental_skyfocus_dump_keys)`=<none, count or verbose>` default: "none" -For debugging Skyfocus. Dump the focused SkyKeys (roots, leafs, focused deps, focused rdeps). + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]experimental_materialize_param_files_directly` default: "false" +: If materializing param files, do so with direct writes to disk. -[`--[no]experimental_skyfocus_dump_post_gc_stats`](#build-flag--experimental_skyfocus_dump_post_gc_stats) default: "false" -For debugging Skyfocus. If enabled, trigger manual GC before/after focusing to report heap sizes reductions. This will increase the Skyfocus latency. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]experimental_run_bep_event_include_residue` default: "false" +: Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. -[`--[no]experimental_stream_log_file_uploads`](#build-flag--experimental_stream_log_file_uploads) default: "false" -Stream log file uploads directly to the remote storage rather than writing them to disk. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--experimental_skyfocus_dump_keys=<none, count or verbose>` default: "none" +: For debugging Skyfocus. Dump the focused SkyKeys (roots, leafs, focused deps, focused rdeps). -[`--explain`](#build-flag--explain)`=<a path>` default: see description -Causes the build system to explain each executed step of the build. The explanation is written to the specified log file. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_skyfocus_dump_post_gc_stats` default: "false" +: For debugging Skyfocus. If enabled, trigger manual GC before/after focusing to report heap sizes reductions. This will increase the Skyfocus latency. -[`--[no]ignore_unsupported_sandboxing`](#build-flag--ignore_unsupported_sandboxing) default: "false" -Do not print a warning when sandboxed execution is not supported on this system. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]experimental_stream_log_file_uploads` default: "false" +: Stream log file uploads directly to the remote storage rather than writing them to disk. -[`--[no]legacy_important_outputs`](#build-flag--legacy_important_outputs) default: "false" -Use this to suppress generation of the legacy important_outputs field in the TargetComplete event. important_outputs are required for Bazel to ResultStore/BTX integration. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--explain=<a path>` default: see description +: Causes the build system to explain each executed step of the build. The explanation is written to the specified log file. -[`--[no]materialize_param_files`](#build-flag--materialize_param_files) default: "false" -Writes intermediate parameter files to output tree even when using remote action execution or caching. Useful when debugging actions. This is implied by --subcommands and --verbose_failures. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]ignore_unsupported_sandboxing` default: "false" +: Do not print a warning when sandboxed execution is not supported on this system. -[`--max_config_changes_to_show`](#build-flag--max_config_changes_to_show)`=<an integer>` default: "3" -When discarding the analysis cache due to a change in the build options, displays up to the given number of changed option names. If the number given is -1, all changed options will be displayed. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]legacy_important_outputs` default: "false" +: Use this to suppress generation of the legacy important\_outputs field in the TargetComplete event. important\_outputs are required for Bazel to ResultStore/BTX integration. -[`--max_test_output_bytes`](#build-flag--max_test_output_bytes)`=<an integer>` default: "-1" -Specifies maximum per-test-log size that can be emitted when --test_output is 'errors' or 'all'. Useful for avoiding overwhelming the output with excessively noisy test output. The test header is included in the log size. Negative values imply no limit. Output is all or nothing. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) +`--[no]materialize_param_files` default: "false" +: Writes intermediate parameter files to output tree even when using remote action execution or caching. Useful when debugging actions. This is implied by --subcommands and --verbose\_failures. -[`--output_filter`](#build-flag--output_filter)`=<a valid Java regular expression>` default: see description -Only shows warnings and action outputs for rules with a name matching the provided regular expression. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--max_config_changes_to_show=<an integer>` default: "3" +: When discarding the analysis cache due to a change in the build options, displays up to the given number of changed option names. If the number given is -1, all changed options will be displayed. -[`--progress_report_interval`](#build-flag--progress_report_interval)`=<an integer in 0-3600 range>` default: "0" -The number of seconds to wait between reports on still running jobs. The default value 0 means the first report will be printed after 10 seconds, then 30 seconds and after that progress is reported once every minute. When --curses is enabled, progress is reported every second. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--max_test_output_bytes=<an integer>` default: "-1" +: Specifies maximum per-test-log size that can be emitted when --test\_output is 'errors' or 'all'. Useful for avoiding overwhelming the output with excessively noisy test output. The test header is included in the log size. Negative values imply no limit. Output is all or nothing. -[`--remote_analysis_json_log`](#build-flag--remote_analysis_json_log)`=<a string>` default: see description -If set, a JSON file is written to this location that contains a detailed log of the behavior of remote analysis caching. It's interpreted as a path relative to the current working directory. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +`--output_filter=<a valid Java regular expression>` default: see description +: Only shows warnings and action outputs for rules with a name matching the provided regular expression. -[`--remote_print_execution_messages`](#build-flag--remote_print_execution_messages)`=<failure, success or all>` default: "failure" -Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--progress_report_interval=<an integer in 0-3600 range>` default: "0" +: The number of seconds to wait between reports on still running jobs. The default value 0 means the first report will be printed after 10 seconds, then 30 seconds and after that progress is reported once every minute. When --curses is enabled, progress is reported every second. -[`--[no]sandbox_debug`](#build-flag--sandbox_debug) default: "false" -Enables debugging features for the sandboxing feature. This includes two things: first, the sandbox root contents are left untouched after a build; and second, prints extra debugging information on execution. This can help developers of Bazel or Starlark rules with debugging failures due to missing input files, etc. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--remote_analysis_json_log=<a string>` default: see description +: If set, a JSON file is written to this location that contains a detailed log of the behavior of remote analysis caching. It's interpreted as a path relative to the current working directory. -[`--show_result`](#build-flag--show_result)`=<an integer>` default: "1" -Show the results of the build. For each target, state whether or not it was brought up-to-date, and if so, a list of output files that were built. The printed files are convenient strings for copy+pasting to the shell, to execute them. -This option requires an integer argument, which is the threshold number of targets above which result information is not printed. Thus zero causes suppression of the message and MAX_INT causes printing of the result to occur always. The default is one. -If nothing was built for a target its results may be omitted to keep the output under the threshold. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--remote_print_execution_messages=<failure, success or all>` default: "failure" +: Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. -[`--[no]subcommands`](#build-flag--subcommands) \[`-s`\] default: "false" -Display the subcommands executed during a build. Related flags: --execution_log_json_file, --execution_log_binary_file (for logging subcommands to a file in a tool-friendly format). + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]sandbox_debug` default: "false" +: Enables debugging features for the sandboxing feature. This includes two things: first, the sandbox root contents are left untouched after a build; and second, prints extra debugging information on execution. This can help developers of Bazel or Starlark rules with debugging failures due to missing input files, etc. -[`--test_output`](#build-flag--test_output)`=<summary, errors, all or streamed>` default: "summary" -Specifies desired output mode. Valid values are 'summary' to output only test status summary, 'errors' to also print test logs for failed tests, 'all' to print logs for all tests and 'streamed' to output logs for all tests in real time (this will force tests to be executed locally one at a time regardless of --test_strategy value). + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) +`--show_result=<an integer>` default: "1" +: Show the results of the build. For each target, state whether or not it was brought up-to-date, and if so, a list of output files that were built. The printed files are convenient strings for copy+pasting to the shell, to execute them. + This option requires an integer argument, which is the threshold number of targets above which result information is not printed. Thus zero causes suppression of the message and MAX\_INT causes printing of the result to occur always. The default is one. + If nothing was built for a target its results may be omitted to keep the output under the threshold. -[`--test_summary`](#build-flag--test_summary)`=<short, terse, detailed, none or testcase>` default: "short" -Specifies the desired format of the test summary. Valid values are 'short' to print information only about tests executed, 'terse', to print information only about unsuccessful tests that were run, 'detailed' to print detailed information about failed test cases, 'testcase' to print summary in test case resolution, do not print detailed information about failed test cases and 'none' to omit the summary. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]subcommands` [`-s`] default: "false" +: Display the subcommands executed during a build. Related flags: --execution\_log\_json\_file, --execution\_log\_binary\_file (for logging subcommands to a file in a tool-friendly format). -[`--[no]verbose_failures`](#build-flag--verbose_failures) default: "false" -If a command fails, print out the full command line. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--test_output=<summary, errors, all or streamed>` default: "summary" +: Specifies desired output mode. Valid values are 'summary' to output only test status summary, 'errors' to also print test logs for failed tests, 'all' to print logs for all tests and 'streamed' to output logs for all tests in real time (this will force tests to be executed locally one at a time regardless of --test\_strategy value). -<!-- --> + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) -[`--aspects_parameters`](#build-flag--aspects_parameters)`=<a 'name=value' assignment>` multiple uses are accumulated -Specifies the values of the command-line aspects parameters. Each parameter value is specified via \<param_name\>=\<param_value\>, for example 'my_param=my_val' where 'my_param' is a parameter of some aspect in --aspects list or required by an aspect in the list. This option can be used multiple times. However, it is not allowed to assign values to the same parameter more than once. +`--test_summary=<short, terse, detailed, none or testcase>` default: "short" +: Specifies the desired format of the test summary. Valid values are 'short' to print information only about tests executed, 'terse', to print information only about unsuccessful tests that were run, 'detailed' to print detailed information about failed test cases, 'testcase' to print summary in test case resolution, do not print detailed information about failed test cases and 'none' to omit the summary. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--target_pattern_file`](#build-flag--target_pattern_file)`=<a string>` default: "" -If set, build will read patterns from the file named here, rather than on the command line. It is an error to specify a file here as well as command-line patterns. +`--[no]verbose_failures` default: "false" +: If a command fails, print out the full command line. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -<!-- --> +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -[`--experimental_circuit_breaker_strategy`](#build-flag--experimental_circuit_breaker_strategy)`=<failure>` default: see description -Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. +`--aspects_parameters=<a 'name=value' assignment>` multiple uses are accumulated +: Specifies the values of the command-line aspects parameters. Each parameter value is specified via \<param\_name>=<param\_value\>, for example 'my\_param=my\_val' where 'my\_param' is a parameter of some aspect in --aspects list or required by an aspect in the list. This option can be used multiple times. However, it is not allowed to assign values to the same parameter more than once. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--experimental_remote_cache_compression_threshold`](#build-flag--experimental_remote_cache_compression_threshold)`=<an integer>` default: "100" -The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote_cache_compression is set. +`--target_pattern_file=<a string>` default: "" +: If set, build will read patterns from the file named here, rather than on the command line. It is an error to specify a file here as well as command-line patterns. -[`--experimental_remote_cache_eviction_retries`](#build-flag--experimental_remote_cache_eviction_retries)`=<an integer>` default: "5" -The maximum number of attempts to retry if the build encountered a transient remote cache error that would otherwise fail the build. Applies for example when artifacts are evicted from the remote cache, or in certain cache failure conditions. A new invocation id will be generated for each attempt. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION) +Remote caching and execution options: -[`--[no]experimental_remote_cache_lease_extension`](#build-flag--experimental_remote_cache_lease_extension) default: "false" -If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. +`--experimental_circuit_breaker_strategy=<failure>` default: see description +: Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. -[`--experimental_remote_cache_ttl`](#build-flag--experimental_remote_cache_ttl)`=<An immutable length of time.>` default: "3h" -The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--experimental_remote_cache_compression_threshold=<an integer>` default: "100" +: The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote\_cache\_compression is set. -[`--experimental_remote_capture_corrupted_outputs`](#build-flag--experimental_remote_capture_corrupted_outputs)`=<a path>` default: see description -A path to a directory where the corrupted outputs will be captured to. +`--experimental_remote_cache_eviction_retries=<an integer>` default: "5" +: The maximum number of attempts to retry if the build encountered a transient remote cache error that would otherwise fail the build. Applies for example when artifacts are evicted from the remote cache, or in certain cache failure conditions. A new invocation id will be generated for each attempt. -[`--[no]experimental_remote_discard_merkle_trees`](#build-flag--experimental_remote_discard_merkle_trees) default: "true" -If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_remote_downloader`](#build-flag--experimental_remote_downloader)`=<a string>` default: see description -A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote_asset.proto +`--[no]experimental_remote_cache_lease_extension` default: "false" +: If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. -[`--[no]experimental_remote_downloader_local_fallback`](#build-flag--experimental_remote_downloader_local_fallback) default: "false" -Whether to fall back to the local downloader if remote downloader fails. +`--experimental_remote_cache_ttl=<An immutable length of time.>` default: "3h" +: The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. -[`--[no]experimental_remote_downloader_propagate_credentials`](#build-flag--experimental_remote_downloader_propagate_credentials) default: "false" -Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_remote_execution_keepalive`](#build-flag--experimental_remote_execution_keepalive) default: "false" -Whether to use keepalive for remote execution calls. +`--experimental_remote_capture_corrupted_outputs=<a path>` default: see description +: A path to a directory where the corrupted outputs will be captured to. -[`--experimental_remote_failure_rate_threshold`](#build-flag--experimental_remote_failure_rate_threshold)`=<an integer in 0-100 range>` default: "10" -Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. +`--[no]experimental_remote_discard_merkle_trees` default: "true" +: If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. -Tags: -[`execution`](#effect_tag_EXECUTION) +`--experimental_remote_downloader=<a string>` default: see description +: A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote\_asset.proto -[`--experimental_remote_failure_window_interval`](#build-flag--experimental_remote_failure_window_interval)`=<An immutable length of time.>` default: "60s" -The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. +`--[no]experimental_remote_downloader_local_fallback` default: "false" +: Whether to fall back to the local downloader if remote downloader fails. -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]experimental_remote_downloader_propagate_credentials` default: "false" +: Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. -[`--[no]experimental_remote_mark_tool_inputs`](#build-flag--experimental_remote_mark_tool_inputs) default: "false" -If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. +`--[no]experimental_remote_execution_keepalive` default: "false" +: Whether to use keepalive for remote execution calls. -[`--[no]experimental_remote_merkle_tree_cache`](#build-flag--experimental_remote_merkle_tree_cache) default: "false" -If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental_remote_merkle_tree_cache_size. +`--experimental_remote_failure_rate_threshold=<an integer in 0-100 range>` default: "10" +: Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. -[`--experimental_remote_merkle_tree_cache_size`](#build-flag--experimental_remote_merkle_tree_cache_size)`=<a long integer>` default: "1000" -The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--experimental_remote_output_service`](#build-flag--experimental_remote_output_service)`=<a string>` default: see description -HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. +`--experimental_remote_failure_window_interval=<An immutable length of time.>` default: "60s" +: The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. -[`--experimental_remote_output_service_output_path_prefix`](#build-flag--experimental_remote_output_service_output_path_prefix)`=<a string>` default: "" -The path under which the contents of output directories managed by the --experimental_remote_output_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_remote_require_cached`](#build-flag--experimental_remote_require_cached) default: "false" -If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. +`--[no]experimental_remote_mark_tool_inputs` default: "false" +: If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. -[`--experimental_remote_scrubbing_config`](#build-flag--experimental_remote_scrubbing_config)`=<Converts to a Scrubber>` default: see description -Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote_scrubbing.proto). +`--[no]experimental_remote_merkle_tree_cache` default: "false" +: If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental\_remote\_merkle\_tree\_cache\_size. -This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. +`--experimental_remote_merkle_tree_cache_size=<a long integer>` default: "1000" +: The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. -Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. +`--experimental_remote_output_service=<a string>` default: see description +: HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. -Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. +`--experimental_remote_output_service_output_path_prefix=<a string>` default: "" +: The path under which the contents of output directories managed by the --experimental\_remote\_output\_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. -In order to successfully use this feature, you likely want to set a custom --host_platform together with --experimental_platform_in_output_dir (to normalize output prefixes) and --incompatible_strict_action_env (to normalize environment variables). +`--[no]experimental_remote_require_cached` default: "false" +: If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. -[`--[no]guard_against_concurrent_changes`](#build-flag--guard_against_concurrent_changes) default: "lite" -Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. +`--experimental_remote_scrubbing_config=<Converts to a Scrubber>` default: see description +: Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote\_scrubbing.proto). -Tags: -[`execution`](#effect_tag_EXECUTION) + This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. -[`--[no]remote_accept_cached`](#build-flag--remote_accept_cached) default: "true" -Whether to accept remotely cached action results. + Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. -[`--remote_build_event_upload`](#build-flag--remote_build_event_upload)`=<all or minimal>` default: "minimal" -If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. -If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. -Default to 'minimal'. + Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. -[`--remote_bytestream_uri_prefix`](#build-flag--remote_bytestream_uri_prefix)`=<a string>` default: see description -The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote_executor and --remote_instance_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "\${hostname}/\${instance_name}". + In order to successfully use this feature, you likely want to set a custom --host\_platform together with --experimental\_platform\_in\_output\_dir (to normalize output prefixes) and --incompatible\_strict\_action\_env (to normalize environment variables). -[`--remote_cache`](#build-flag--remote_cache)`=<a string>` default: see description -A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching +`--[no]guard_against_concurrent_changes` default: "lite" +: Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. -[`--[no]remote_cache_async`](#build-flag--remote_cache_async) default: "true" -If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]remote_cache_compression`](#build-flag--remote_cache_compression) default: "false" -If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental_remote_cache_compression_threshold. +`--[no]remote_accept_cached` default: "true" +: Whether to accept remotely cached action results. -[`--remote_cache_header`](#build-flag--remote_cache_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header that will be included in cache requests: --remote_cache_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. +`--remote_build_event_upload=<all or minimal>` default: "minimal" +: If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. + If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. + Default to 'minimal'. -[`--remote_default_exec_properties`](#build-flag--remote_default_exec_properties)`=<a 'name=value' assignment>` multiple uses are accumulated -Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec_properties. +`--remote_bytestream_uri_prefix=<a string>` default: see description +: The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote\_executor and --remote\_instance\_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "$\{hostname\}/$\{instance\_name\}". -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--remote_cache=<a string>` default: see description +: A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching -[`--remote_default_platform_properties`](#build-flag--remote_default_platform_properties)`=<a string>` default: "" -Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote_execution_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. +`--[no]remote_cache_async` default: "true" +: If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. -[`--remote_download_regex`](#build-flag--remote_download_regex)`=<a valid Java regular expression>` multiple uses are accumulated -Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote_download_outputs. Multiple patterns may be specified by repeating this flag. +`--[no]remote_cache_compression` default: "false" +: If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental\_remote\_cache\_compression\_threshold. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--remote_cache_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header that will be included in cache requests: --remote\_cache\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -[`--remote_downloader_header`](#build-flag--remote_downloader_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header that will be included in remote downloader requests: --remote_downloader_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. +`--remote_default_exec_properties=<a 'name=value' assignment>` multiple uses are accumulated +: Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec\_properties. -[`--remote_exec_header`](#build-flag--remote_exec_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header that will be included in execution requests: --remote_exec_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--remote_execution_priority`](#build-flag--remote_execution_priority)`=<an integer>` default: "0" -The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. +`--remote_default_platform_properties=<a string>` default: "" +: Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote\_execution\_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. -[`--remote_executor`](#build-flag--remote_executor)`=<a string>` default: see description -HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. +`--remote_download_regex=<a valid Java regular expression>` multiple uses are accumulated +: Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote\_download\_outputs. Multiple patterns may be specified by repeating this flag. -[`--remote_grpc_log`](#build-flag--remote_grpc_log)`=<a path>` default: see description -If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--remote_header`](#build-flag--remote_header)`=<a 'name=value' assignment>` multiple uses are accumulated -Specify a header that will be included in requests: --remote_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. +`--remote_downloader_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header that will be included in remote downloader requests: --remote\_downloader\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -[`--remote_instance_name`](#build-flag--remote_instance_name)`=<a string>` default: "" -Value to pass as instance_name in the remote execution API. +`--remote_exec_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header that will be included in execution requests: --remote\_exec\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -[`--[no]remote_local_fallback`](#build-flag--remote_local_fallback) default: "false" -Whether to fall back to standalone local execution strategy if remote execution fails. +`--remote_execution_priority=<an integer>` default: "0" +: The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. -[`--remote_local_fallback_strategy`](#build-flag--remote_local_fallback_strategy)`=<a string>` default: "local" -Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. +`--remote_executor=<a string>` default: see description +: HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. -[`--remote_max_connections`](#build-flag--remote_max_connections)`=<an integer>` default: "100" -Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. -For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote_max_connections concurrent requests. -For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. +`--remote_grpc_log=<a path>` default: see description +: If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) +`--remote_header=<a 'name=value' assignment>` multiple uses are accumulated +: Specify a header that will be included in requests: --remote\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. -[`--remote_proxy`](#build-flag--remote_proxy)`=<a string>` default: see description -Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). +`--remote_instance_name=<a string>` default: "" +: Value to pass as instance\_name in the remote execution API. -[`--remote_result_cache_priority`](#build-flag--remote_result_cache_priority)`=<an integer>` default: "0" -The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. +`--[no]remote_local_fallback` default: "false" +: Whether to fall back to standalone local execution strategy if remote execution fails. -[`--remote_retries`](#build-flag--remote_retries)`=<an integer>` default: "5" -The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. +`--remote_local_fallback_strategy=<a string>` default: "local" +: Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. -[`--remote_retry_max_delay`](#build-flag--remote_retry_max_delay)`=<An immutable length of time.>` default: "5s" -The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. +`--remote_max_connections=<an integer>` default: "100" +: Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. + For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote\_max\_connections concurrent requests. + For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. -[`--remote_timeout`](#build-flag--remote_timeout)`=<An immutable length of time.>` default: "60s" -The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]remote_upload_local_results`](#build-flag--remote_upload_local_results) default: "true" -Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. +`--remote_proxy=<a string>` default: see description +: Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). -[`--[no]remote_verify_downloads`](#build-flag--remote_verify_downloads) default: "true" -If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. +`--remote_result_cache_priority=<an integer>` default: "0" +: The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. -<!-- --> +`--remote_retries=<an integer>` default: "5" +: The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. -[`--[no]allow_analysis_cache_discard`](#build-flag--allow_analysis_cache_discard) default: "true" -If discarding the analysis cache due to a change in the build system, setting this option to false will cause bazel to exit, rather than continuing with the build. This option has no effect when 'discard_analysis_cache' is also set. +`--remote_retry_max_delay=<An immutable length of time.>` default: "5s" +: The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--remote_timeout=<An immutable length of time.>` default: "60s" +: The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. -[`--auto_output_filter`](#build-flag--auto_output_filter)`=<none, all, packages or subpackages>` default: "none" -If --output_filter is not specified, then the value for this option is used create a filter automatically. Allowed values are 'none' (filter nothing / show everything), 'all' (filter everything / show nothing), 'packages' (include output from rules in packages mentioned on the Blaze command line), and 'subpackages' (like 'packages', but also include subpackages). For the 'packages' and 'subpackages' values //java/foo and //javatests/foo are treated as one package)'. +`--[no]remote_upload_local_results` default: "true" +: Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. -[`--[no]build_manual_tests`](#build-flag--build_manual_tests) default: "false" -Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from processing. This option forces them to be built (but not executed). +`--[no]remote_verify_downloads` default: "true" +: If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. -[`--build_tag_filters`](#build-flag--build_tag_filters)`=<comma-separated list of options>` default: "" -Specifies a comma-separated list of tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those targets will be built that contain at least one included tag and do not contain any excluded tags. This option does not affect the set of tests executed with the 'test' command; those are be governed by the test filtering options, for example '--test_tag_filters' +Miscellaneous options, not otherwise categorized.: -[`--[no]build_tests_only`](#build-flag--build_tests_only) default: "false" -If specified, only \*\_test and test_suite rules will be built and other targets specified on the command line will be ignored. By default everything that was requested will be built. +`--[no]allow_analysis_cache_discard` default: "true" +: If discarding the analysis cache due to a change in the build system, setting this option to false will cause bazel to exit, rather than continuing with the build. This option has no effect when 'discard\_analysis\_cache' is also set. -[`--combined_report`](#build-flag--combined_report)`=<none or lcov>` default: "lcov" -Specifies desired cumulative coverage report type. At this point only LCOV is supported. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--[no]compile_one_dependency`](#build-flag--compile_one_dependency) default: "false" -Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single target that depends on the source file to detect errors as early as possible in the edit/build/test cycle. This argument affects the way all non-flag arguments are interpreted; instead of being targets to build they are source filenames. For each source filename an arbitrary target that depends on it will be built. +`--auto_output_filter=<none, all, packages or subpackages>` default: "none" +: If --output\_filter is not specified, then the value for this option is used create a filter automatically. Allowed values are 'none' (filter nothing / show everything), 'all' (filter everything / show nothing), 'packages' (include output from rules in packages mentioned on the Blaze command line), and 'subpackages' (like 'packages', but also include subpackages). For the 'packages' and 'subpackages' values //java/foo and //javatests/foo are treated as one package)'. -[`--deleted_packages`](#build-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated -A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. +`--[no]build_manual_tests` default: "false" +: Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from processing. This option forces them to be built (but not executed). -[`--[no]discard_analysis_cache`](#build-flag--discard_analysis_cache) default: "false" -Discard the analysis cache immediately after the analysis phase completes. Reduces memory usage by ~10%, but makes further incremental builds slower. +`--build_tag_filters=<comma-separated list of options>` default: "" +: Specifies a comma-separated list of tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those targets will be built that contain at least one included tag and do not contain any excluded tags. This option does not affect the set of tests executed with the 'test' command; those are be governed by the test filtering options, for example '--test\_tag\_filters' -[`--disk_cache`](#build-flag--disk_cache)`=<a path>` default: see description -A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. +`--[no]build_tests_only` default: "false" +: If specified, only \*\_test and test\_suite rules will be built and other targets specified on the command line will be ignored. By default everything that was requested will be built. -[`--embed_label`](#build-flag--embed_label)`=<a one-line string>` default: "" -Embed source control revision or release label in binary +`--combined_report=<none or lcov>` default: "lcov" +: Specifies desired cumulative coverage report type. At this point only LCOV is supported. -[`--execution_log_binary_file`](#build-flag--execution_log_binary_file)`=<a path>` default: see description -Log the executed spawns into this file as length-delimited SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution_log_compact_file, which is significantly smaller and cheaper to produce. Related flags: --execution_log_compact_file (compact format; mutually exclusive), --execution_log_json_file (text JSON format; mutually exclusive), --execution_log_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). +`--[no]compile_one_dependency` default: "false" +: Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single target that depends on the source file to detect errors as early as possible in the edit/build/test cycle. This argument affects the way all non-flag arguments are interpreted; instead of being targets to build they are source filenames. For each source filename an arbitrary target that depends on it will be built. -[`--execution_log_compact_file`](#build-flag--execution_log_compact_file)`=<a path>` default: see description -Log the executed spawns into this file as length-delimited ExecLogEntry protos, according to src/main/protobuf/spawn.proto. The entire file is zstd compressed. Related flags: --execution_log_binary_file (binary protobuf format; mutually exclusive), --execution_log_json_file (text JSON format; mutually exclusive), --subcommands (for displaying subcommands in terminal output). +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated +: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. + Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. -[`--execution_log_json_file`](#build-flag--execution_log_json_file)`=<a path>` default: see description -Log the executed spawns into this file as newline-delimited JSON representations of SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution_log_compact_file, which is significantly smaller and cheaper to produce. Related flags: --execution_log_compact_file (compact format; mutually exclusive), --execution_log_binary_file (binary protobuf format; mutually exclusive), --execution_log_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). +`--[no]discard_analysis_cache` default: "false" +: Discard the analysis cache immediately after the analysis phase completes. Reduces memory usage by ~10%, but makes further incremental builds slower. -[`--[no]execution_log_sort`](#build-flag--execution_log_sort) default: "true" -Whether to sort the execution log, making it easier to compare logs across invocations. Set to false to avoid potentially significant CPU and memory usage at the end of the invocation, at the cost of producing the log in nondeterministic execution order. Only applies to the binary and JSON formats; the compact format is never sorted. +`--disk_cache=<a path>` default: see description +: A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. -[`--[no]expand_test_suites`](#build-flag--expand_test_suites) default: "true" -Expand test_suite targets into their constituent tests before analysis. When this flag is turned on (the default), negative target patterns will apply to the tests belonging to the test suite, otherwise they will not. Turning off this flag is useful when top-level aspects are applied at command line: then they can analyze test_suite targets. +`--embed_label=<a one-line string>` default: "" +: Embed source control revision or release label in binary -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--execution_log_binary_file=<a path>` default: see description +: Log the executed spawns into this file as length-delimited SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution\_log\_compact\_file, which is significantly smaller and cheaper to produce. Related flags: --execution\_log\_compact\_file (compact format; mutually exclusive), --execution\_log\_json\_file (text JSON format; mutually exclusive), --execution\_log\_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). -[`--experimental_disk_cache_gc_idle_delay`](#build-flag--experimental_disk_cache_gc_idle_delay)`=<An immutable length of time.>` default: "5m" -How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental_disk_cache_gc_max_size and/or --experimental_disk_cache_gc_max_age. +`--execution_log_compact_file=<a path>` default: see description +: Log the executed spawns into this file as length-delimited ExecLogEntry protos, according to src/main/protobuf/spawn.proto. The entire file is zstd compressed. Related flags: --execution\_log\_binary\_file (binary protobuf format; mutually exclusive), --execution\_log\_json\_file (text JSON format; mutually exclusive), --subcommands (for displaying subcommands in terminal output). -[`--experimental_disk_cache_gc_max_age`](#build-flag--experimental_disk_cache_gc_max_age)`=<An immutable length of time.>` default: "0" -If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental_disk_cache_gc_max_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag. +`--execution_log_json_file=<a path>` default: see description +: Log the executed spawns into this file as newline-delimited JSON representations of SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution\_log\_compact\_file, which is significantly smaller and cheaper to produce. Related flags: --execution\_log\_compact\_file (compact format; mutually exclusive), --execution\_log\_binary\_file (binary protobuf format; mutually exclusive), --execution\_log\_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). -[`--experimental_disk_cache_gc_max_size`](#build-flag--experimental_disk_cache_gc_max_size)`=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" -If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental_disk_cache_gc_max_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental_disk_cache_gc_idle_delay flag. +`--[no]execution_log_sort` default: "true" +: Whether to sort the execution log, making it easier to compare logs across invocations. Set to false to avoid potentially significant CPU and memory usage at the end of the invocation, at the cost of producing the log in nondeterministic execution order. Only applies to the binary and JSON formats; the compact format is never sorted. -[`--experimental_extra_action_filter`](#build-flag--experimental_extra_action_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "" -Deprecated in favor of aspects. Filters set of targets to schedule extra_actions for. +`--[no]expand_test_suites` default: "true" +: Expand test\_suite targets into their constituent tests before analysis. When this flag is turned on (the default), negative target patterns will apply to the tests belonging to the test suite, otherwise they will not. Turning off this flag is useful when top-level aspects are applied at command line: then they can analyze test\_suite targets. -[`--[no]experimental_extra_action_top_level_only`](#build-flag--experimental_extra_action_top_level_only) default: "false" -Deprecated in favor of aspects. Only schedules extra_actions for top level targets. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--experimental_spawn_scheduler`](#build-flag--experimental_spawn_scheduler) -Enable dynamic execution by running actions locally and remotely in parallel. Bazel spawns each action locally and remotely and picks the one that completes first. If an action supports workers, the local action will be run in the persistent worker mode. To enable dynamic execution for an individual action mnemonic, use the `--internal_spawn_scheduler` and `--strategy=<mnemonic>=dynamic` flags instead. +`--experimental_disk_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" +: How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental\_disk\_cache\_gc\_max\_size and/or --experimental\_disk\_cache\_gc\_max\_age. -Expands to: -  [`--internal_spawn_scheduler`](#flag--internal_spawn_scheduler) -  [`--spawn_strategy=dynamic`](#flag--spawn_strategy) +`--experimental_disk_cache_gc_max_age=<An immutable length of time.>` default: "0" +: If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. -[`--[no]fetch`](#build-flag--fetch) default: "true" -Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. +`--experimental_disk_cache_gc_max_size=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" +: If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. -[`--local_termination_grace_seconds`](#build-flag--local_termination_grace_seconds)`=<an integer>` default: "15" -Time to wait between terminating a local process due to timeout and forcefully shutting it down. +`--experimental_extra_action_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "" +: Deprecated in favor of aspects. Filters set of targets to schedule extra\_actions for. -[`--package_path`](#build-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" -A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. +`--[no]experimental_extra_action_top_level_only` default: "false" +: Deprecated in favor of aspects. Only schedules extra\_actions for top level targets. -[`--[no]show_loading_progress`](#build-flag--show_loading_progress) default: "true" -If enabled, causes Bazel to print "Loading package:" messages. +`--experimental_spawn_scheduler` +: Enable dynamic execution by running actions locally and remotely in parallel. Bazel spawns each action locally and remotely and picks the one that completes first. If an action supports workers, the local action will be run in the persistent worker mode. To enable dynamic execution for an individual action mnemonic, use the `--internal_spawn_scheduler` and `--strategy=<mnemonic>=dynamic` flags instead. -[`--test_lang_filters`](#build-flag--test_lang_filters)`=<comma-separated list of options>` default: "" -Specifies a comma-separated list of test languages. Each language can be optionally preceded with '-' to specify excluded languages. Only those test targets will be found that are written in the specified languages. The name used for each language should be the same as the language prefix in the \*\_test rule, e.g. one of 'cc', 'java', 'py', etc. This option affects --build_tests_only behavior and the test command. + Expands to: + +   `--internal_spawn_scheduler` + +   `--spawn_strategy=dynamic` -[`--test_size_filters`](#build-flag--test_size_filters)`=<comma-separated list of values: small, medium, large, or enormous>` default: "" -Specifies a comma-separated list of test sizes. Each size can be optionally preceded with '-' to specify excluded sizes. Only those test targets will be found that contain at least one included size and do not contain any excluded sizes. This option affects --build_tests_only behavior and the test command. +`--[no]fetch` default: "true" +: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. -[`--test_tag_filters`](#build-flag--test_tag_filters)`=<comma-separated list of options>` default: "" -Specifies a comma-separated list of test tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those test targets will be found that contain at least one included tag and do not contain any excluded tags. This option affects --build_tests_only behavior and the test command. +`--local_termination_grace_seconds=<an integer>` default: "15" +: Time to wait between terminating a local process due to timeout and forcefully shutting it down. -[`--test_timeout_filters`](#build-flag--test_timeout_filters)`=<comma-separated list of values: short, moderate, long, or eternal>` default: "" -Specifies a comma-separated list of test timeouts. Each timeout can be optionally preceded with '-' to specify excluded timeouts. Only those test targets will be found that contain at least one included timeout and do not contain any excluded timeouts. This option affects --build_tests_only behavior and the test command. +`--package_path=<colon-separated list of options>` default: "%workspace%" +: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. -[`--workspace_status_command`](#build-flag--workspace_status_command)`=<path>` default: "" -A command invoked at the beginning of the build to provide status information about the workspace in the form of key/value pairs. See the User's Manual for the full specification. Also see tools/buildstamp/get_workspace_status for an example. +`--[no]show_loading_progress` default: "true" +: If enabled, causes Bazel to print "Loading package:" messages. -<!-- --> +`--test_lang_filters=<comma-separated list of options>` default: "" +: Specifies a comma-separated list of test languages. Each language can be optionally preceded with '-' to specify excluded languages. Only those test targets will be found that are written in the specified languages. The name used for each language should be the same as the language prefix in the \*\_test rule, e.g. one of 'cc', 'java', 'py', etc. This option affects --build\_tests\_only behavior and the test command. -[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" -Enable persistent aar extractor by using workers. +`--test_size_filters=<comma-separated list of values: small, medium, large, or enormous>` default: "" +: Specifies a comma-separated list of test sizes. Each size can be optionally preceded with '-' to specify excluded sizes. Only those test targets will be found that contain at least one included size and do not contain any excluded sizes. This option affects --build\_tests\_only behavior and the test command. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--test_tag_filters=<comma-separated list of options>` default: "" +: Specifies a comma-separated list of test tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those test targets will be found that contain at least one included tag and do not contain any excluded tags. This option affects --build\_tests\_only behavior and the test command. -[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" -Whether to make source manifest actions remotable +`--test_timeout_filters=<comma-separated list of values: short, moderate, long, or eternal>` default: "" +: Specifies a comma-separated list of test timeouts. Each timeout can be optionally preceded with '-' to specify excluded timeouts. Only those test targets will be found that contain at least one included timeout and do not contain any excluded timeouts. This option affects --build\_tests\_only behavior and the test command. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--workspace_status_command=<path>` default: "" +: A command invoked at the beginning of the build to provide status information about the workspace in the form of key/value pairs. See the User's Manual for the full specification. Also see tools/buildstamp/get\_workspace\_status for an example. -[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" -If true, then Bazel will run coverage postprocessing for test in a new spawn. +Options that control build execution: -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_persistent_aar_extractor` default: "false" +: Enable persistent aar extractor by using workers. -[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" -If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_remotable_source_manifests` default: "false" +: Whether to make source manifest actions remotable -[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" -When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]experimental_split_coverage_postprocessing` default: "false" +: If true, then Bazel will run coverage postprocessing for test in a new spawn. -[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". +`--[no]experimental_strict_fileset_output` default: "false" +: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. -Examples: -'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_modify_execution_info_additive` default: "true" +: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + + Syntax: "regex=[+-]key,regex=[+-]key,...". + + Examples: + '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. + 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. + '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` +: Enable persistent Android dex and desugar actions by using workers. + + Expands to: + +   `--internal_persistent_android_dex_desugar` + +   `--strategy=Desugar=worker` + +   `--strategy=DexBuilder=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` +: Enable persistent Android resource processor by using workers. + + Expands to: + +   `--internal_persistent_busybox_tools` + +   `--strategy=AaptPackage=worker` + +   `--strategy=AndroidResourceParser=worker` + +   `--strategy=AndroidResourceValidator=worker` + +   `--strategy=AndroidResourceCompiler=worker` + +   `--strategy=RClassGenerator=worker` + +   `--strategy=AndroidResourceLink=worker` + +   `--strategy=AndroidAapt2=worker` + +   `--strategy=AndroidAssetMerger=worker` + +   `--strategy=AndroidResourceMerger=worker` + +   `--strategy=AndroidCompiledResourceMerger=worker` + +   `--strategy=ManifestMerger=worker` + +   `--strategy=AndroidManifestMerger=worker` + +   `--strategy=Aapt2Optimize=worker` + +   `--strategy=AARGenerator=worker` + +   `--strategy=ProcessDatabinding=worker` + +   `--strategy=GenerateDataBindingBaseClasses=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` +: Enable persistent multiplexed Android dex and desugar actions by using workers. + + Expands to: + +   `--persistent_android_dex_desugar` + +   `--internal_persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` +: Enable persistent multiplexed Android resource processor by using workers. + + Expands to: + +   `--persistent_android_resource_processor` + +   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` +: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + + Expands to: + +   `--internal_persistent_multiplex_busybox_tools` + +   `--persistent_multiplex_android_resource_processor` + +   `--persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" +: If true, use the target platform for running tests rather than the test exec group. + + Tags: + [`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: + +`--android_compiler=<a string>` default: see description +: The Android target compiler. + + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" +: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -Enable persistent Android dex and desugar actions by using workers. +`--android_platforms=<a build target label>` default: "" +: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. -Expands to: -  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) -  [`--strategy=Desugar=worker`](#flag--strategy) -  [`--strategy=DexBuilder=worker`](#flag--strategy) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--cc_output_directory_tag=<a string>` default: "" +: Specifies a suffix to be added to the configuration directory. -[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -Enable persistent Android resource processor by using workers. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Expands to: -  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) -  [`--strategy=AaptPackage=worker`](#flag--strategy) -  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) -  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) -  [`--strategy=RClassGenerator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) -  [`--strategy=AndroidAapt2=worker`](#flag--strategy) -  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) -  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) -  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) -  [`--strategy=ManifestMerger=worker`](#flag--strategy) -  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) -  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) -  [`--strategy=AARGenerator=worker`](#flag--strategy) -  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) -  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) +`--compiler=<a string>` default: see description +: The C++ compiler to use for compiling the target. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) -Enable persistent multiplexed Android dex and desugar actions by using workers. +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" +: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. -Expands to: -  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" +: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. -[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -Enable persistent multiplexed Android resource processor by using workers. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Expands to: -  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" +: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) -Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). +`--custom_malloc=<a build target label>` default: see description +: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. -Expands to: -  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) -  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--[no]experimental_include_xcode_execution_requirements` default: "false" +: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. -[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" -If true, use the target platform for running tests rather than the test exec group. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]experimental_prefer_mutual_xcode` default: "true" +: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. -<!-- --> + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description -The Android target compiler. +`--extra_execution_platforms=<comma-separated list of options>` default: "" +: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" -Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated +: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" -Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. +`--grte_top=<a label>` default: see description +: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" -Specifies a suffix to be added to the configuration directory. +`--host_compiler=<a string>` default: see description +: No-op flag. Will be removed in a future release. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -[`--compiler`](#flag--compiler)`=<a string>` default: see description -The C++ compiler to use for compiling the target. +`--host_grte_top=<a label>` default: see description +: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" -Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" +: The label of a platform rule that describes the host system. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" -Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. +`--[no]incompatible_bazel_test_exec_run_under` default: "true" +: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" -Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. +`--[no]incompatible_builtin_objc_strip_action` default: "true" +: Whether to emit a strip action as part of objc linking. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description -Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" +: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" -If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" +: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" -If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. +`--[no]incompatible_remove_legacy_whole_archive` default: "true" +: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" -The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. +`--[no]incompatible_strip_executable_safely` default: "false" +: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated -The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). +`--[no]interface_shared_objects` default: "true" +: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--grte_top`](#flag--grte_top)`=<a label>` default: see description -A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description -No-op flag. Will be removed in a future release. +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description -If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. +`--minimum_os_version=<a string>` default: see description +: The minimum OS version which your compilation targets. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" -The label of a platform rule that describes the host system. +`--platform_mappings=<a main workspace-relative path>` default: "" +: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" -If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. +`--platforms=<a build target label>` default: "" +: The labels of the platform rules describing the target platforms for the current command. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" -Whether to emit a strip action as part of objc linking. +`--python_path=<a string>` default: see description +: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" -If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" -Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" -If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" -If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. +`--xcode_version=<a string>` default: see description +: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" -Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" +: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. +Options that control the output of the command: -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]apple_generate_dsym` default: "false" +: Whether to generate debug symbol(.dSYM) file(s). -[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]build_runfile_links` default: "true" +: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. -[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description -The minimum OS version which your compilation targets. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]build_runfile_manifests` default: "true" +: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. -[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" -The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]build_test_dwp` default: "false" +: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. -[`--platforms`](#flag--platforms)`=<a build target label>` default: "" -The labels of the platform rules describing the target platforms for the current command. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" +: Sets the suffixes of header files that a cc\_proto\_library creates. -[`--python_path`](#flag--python_path)`=<a string>` default: see description -The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" +: Sets the suffixes of source files that a cc\_proto\_library creates. -[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" +: Run extra actions for alternative Java api versions in a proto\_library. -[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" -Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]experimental_save_feature_state` default: "false" +: Save the state of enabled and requested feautres as an output of compilation. -[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--fission=<a set of compilation modes>` default: "no" +: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. -[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description -If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]incompatible_always_include_files_in_data` default: "true" +: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). -[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" -The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" +: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" -Whether to generate debug symbol(.dSYM) file(s). +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" +: List of flags for which the use in select() is disabled. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" -If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" +: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" -If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. +`--[no]objc_generate_linkmap` default: "false" +: Specifies whether to generate a linkmap file. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" -If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. +`--[no]save_temps` default: "false" +: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" -Sets the suffixes of header files that a cc_proto_library creates. +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case + the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + \<br\> + Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. -[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" -Sets the suffixes of source files that a cc_proto_library creates. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--allowed_cpu_values=<comma-separated set of options>` default: "" +: Allowed values for the --cpu flag. -[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" -Run extra actions for alternative Java api versions in a proto_library. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]android_databinding_use_androidx` default: "true" +: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. -[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" -Save the state of enabled and requested feautres as an output of compilation. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]android_databinding_use_v3_4_args` default: "true" +: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. -[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" -Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--android_dynamic_mode=<off, default or fully>` default: "off" +: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" -If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. -[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" -If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" -List of flags for which the use in select() is disabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]build_python_zip` default: "auto" +: Build python executable zip; on on Windows, off on other platforms -[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" -If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple Catalyst binaries. -[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" -Specifies whether to generate a linkmap file. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]collect_code_coverage` default: "false" +: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. -[`--[no]save_temps`](#flag--save_temps) default: "false" -If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" +: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case -the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -\<br\> -Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. +`--conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C source files. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" -Allowed values for the --cpu flag. +`--copt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" -Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. +`--cpu=<a string>` default: "" +: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" -Use android databinding v2 with 3.4.0 argument. This flag is a no-op. +`--cs_fdo_absolute_path=<a string>` default: see description +: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" -Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. +`--cs_fdo_instrument=<a string>` default: see description +: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. +`--cs_fdo_profile=<a build target label>` default: see description +: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. +`--cxxopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C++ source files. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" -Build python executable zip; on on Windows, off on other platforms +`--define=<a 'name=value' assignment>` multiple uses are accumulated +: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple Catalyst binaries. +`--dynamic_mode=<off, default or fully>` default: "default" +: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" -If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. +`--[no]enable_propeller_optimize_absolute_paths` default: "true" +: If set, any use of absolute paths for propeller optimize will raise an error. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" -Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. +`--[no]enable_remaining_fdo_absolute_paths` default: "true" +: If set, any use of absolute paths for FDO will raise an error. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C source files. +`--[no]enable_runfiles` default: "auto" +: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc. +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--cpu`](#flag--cpu)`=<a string>` default: "" -Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. +`--experimental_action_listener=<a build target label>` multiple uses are accumulated +: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description -Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. +`--[no]experimental_android_compress_java_resources` default: "false" +: Compress Java resources in APKs -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description -Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. +`--[no]experimental_android_databinding_v2` default: "true" +: Use android databinding v2. This flag is a no-op. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description -The cs_fdo_profile representing the context sensitive profile to be used for optimization. +`--[no]experimental_android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C++ source files. +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" +: use rex tool to rewrite dex files -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated -Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" +: If specified, Bazel will also generate collect coverage information for generated files. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" -Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +: Uses these strings as objc fastbuild compiler options. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" -If set, any use of absolute paths for propeller optimize will raise an error. +`--[no]experimental_omitfp` default: "false" +: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" -If set, any use of absolute paths for FDO will raise an error. +`--experimental_output_paths=<off or strip>` default: "off" +: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) -[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" -Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated +: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. +`--[no]experimental_platform_in_output_dir` default: "false" +: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated -Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. +`--[no]experimental_py_binaries_include_label` default: "false" +: py\_binary targets include their label even when stamping is disabled. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" -Compress Java resources in APKs +`--[no]experimental_use_llvm_covmap` default: "false" +: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" -Use android databinding v2. This flag is a no-op. +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" +: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. +`--fdo_instrument=<a string>` default: see description +: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" -use rex tool to rewrite dex files +`--fdo_optimize=<a string>` default: see description +: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" -If specified, Bazel will also generate collect coverage information for generated files. +`--fdo_prefetch_hints=<a build target label>` default: see description +: Use cache prefetch hints. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -Uses these strings as objc fastbuild compiler options. +`--fdo_profile=<a build target label>` default: see description +: The fdo\_profile representing the profile to be used for optimization. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" -If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. +`--features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" -Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. +`--[no]force_pic` default: "false" +: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated -Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" -If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" +: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" -py_binary targets include their label even when stamping is disabled. +`--host_conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" -If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. +`--host_copt=<a string>` multiple uses are accumulated +: Additional options to pass to the C compiler for tools built in the exec configurations. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" -Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. +`--host_cpu=<a string>` default: "" +: The host CPU. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description -Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. +`--host_cxxopt=<a string>` multiple uses are accumulated +: Additional options to pass to C++ compiler for tools built in the exec configurations. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description -Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. +`--host_features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description -Use cache prefetch hints. +`--host_linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to linker when linking tools in the exec configurations. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description -The fdo_profile representing the profile to be used for optimization. +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--features`](#flag--features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]force_pic`](#flag--force_pic) default: "false" -If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). +`--[no]incompatible_auto_exec_groups` default: "false" +: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +`--[no]incompatible_merge_genfiles_directory` default: "true" +: If true, the genfiles directory is folded into the bin directory. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" -Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. +`--[no]incompatible_target_cpu_from_platform` default: "true" +: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. +`--[no]instrument_test_targets` default: "false" +: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated -Additional options to pass to the C compiler for tools built in the exec configurations. +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" +: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" -The host CPU. +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated -Additional options to pass to C++ compiler for tools built in the exec configurations. +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. +`--[no]legacy_whole_archive` default: "true" +: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) -[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to linker when linking tools in the exec configurations. +`--linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when linking. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. +`--ltobackendopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO backend step (under --features=thin\_lto). -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. +`--ltoindexopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO indexing step (under --features=thin\_lto). -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" -When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple macOS binaries. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" -If true, the genfiles directory is folded into the bin directory. +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" -If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. +`--memprof_profile=<a build target label>` default: see description +: Use memprof profile. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" -When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. +`--[no]objc_debug_with_GLIBCXX` default: "false" +: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" -When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. +`--[no]objc_enable_binary_stripping` default: "false" +: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. +`--objccopt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc when compiling Objective-C/C++ source files. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" -Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when linking. +`--platform_suffix=<a string>` default: see description +: Specifies a suffix to be added to the configuration directory. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO backend step (under --features=thin_lto). +`--propeller_optimize=<a build target label>` default: see description +: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO indexing step (under --features=thin_lto). +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description +: Absolute path name of cc\_profile file for Propeller Optimized builds. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple macOS binaries. +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description +: Absolute path name of ld\_profile file for Propeller Optimized builds. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. +`--run_under=<a prefix in front of command>` default: see description +: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description -Use memprof profile. +`--[no]share_native_deps` default: "true" +: If true, native libraries that contain identical functionality will be shared among different targets -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" -If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. +`--[no]stamp` default: "false" +: Stamp binaries with the date, username, hostname, workspace information, etc. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" -Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. +`--strip=<always, sometimes or never>` default: "sometimes" +: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc when compiling Objective-C/C++ source files. +`--stripopt=<a string>` multiple uses are accumulated +: Additional options to pass to strip when generating a '\<name\>.stripped' binary. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple tvOS binaries. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description -Specifies a suffix to be added to the configuration directory. +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple visionOS binaries. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description -Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple watchOS binaries. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description -Absolute path name of cc_profile file for Propeller Optimized builds. +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description -Absolute path name of ld_profile file for Propeller Optimized builds. +`--xbinary_fdo=<a build target label>` default: see description +: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description -Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]check_visibility` default: "true" +: If disabled, visibility errors in target dependencies are demoted to warnings. -[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" -If true, native libraries that contain identical functionality will be shared among different targets + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]desugar_for_android` default: "true" +: Whether to desugar Java 8 bytecode before dexing. -[`--[no]stamp`](#flag--stamp) default: "false" -Stamp binaries with the date, username, hostname, workspace information, etc. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]desugar_java8_libs` default: "false" +: Whether to include supported Java 8 libraries in apps for legacy devices. -[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" -Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]enforce_constraints` default: "true" +: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments -[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated -Additional options to pass to strip when generating a '\<name\>.stripped' binary. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_check_desugar_deps` default: "true" +: Whether to double-check correct desugaring at Android binary level. -[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple tvOS binaries. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[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. -[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" +: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. -[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple visionOS binaries. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" +: If true, checks that a Java target explicitly declares all directly used targets as dependencies. -[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple watchOS binaries. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_check_testonly_for_output_files` default: "false" +: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. -[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]incompatible_disable_native_android_rules` default: "false" +: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android -[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description -Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" +: No-op. Kept here for backwards compatibility. -<!-- --> + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]check_visibility`](#flag--check_visibility) default: "true" -If disabled, visibility errors in target dependencies are demoted to warnings. +`--[no]one_version_enforcement_on_java_tests` default: "true" +: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" -Whether to desugar Java 8 bytecode before dexing. +`--python_native_rules_allowlist=<a build target label>` default: see description +: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" -Whether to include supported Java 8 libraries in apps for legacy devices. +`--[no]strict_filesets` default: "false" +: If this option is enabled, filesets crossing package boundaries are reported as errors. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" -Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" +: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_check_desugar_deps`](#flag--experimental_check_desugar_deps) default: "true" -Whether to double-check correct desugaring at Android binary level. +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" +: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_enforce_transitive_visibility`](#flag--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. +`--[no]strict_system_includes` default: "false" +: If true, headers found through system include paths (-isystem) are also required to be declared. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" -When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. +`--target_environment=<a build target label>` multiple uses are accumulated +: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" -If true, checks that a Java target explicitly declares all directly used targets as dependencies. +Options that affect the signing outputs of a build: -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" +: Implementation to use to sign APKs -[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" -If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]device_debug_entitlements` default: "true" +: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. -[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" -If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--ios_signing_cert_name=<a string>` default: see description +: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). -[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" -No-op. Kept here for backwards compatibility. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" -When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" +: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description -An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. +`--[no]incompatible_objc_alwayslink_by_default` default: "false" +: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" -If this option is enabled, filesets crossing package boundaries are reported as errors. +`--[no]incompatible_python_disallow_native_rules` default: "false" +: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" -Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. +Options that govern the behavior of the test environment or test runner: -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]allow_analysis_failures` default: "false" +: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. -[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" -Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--analysis_testing_deps_limit=<an integer>` default: "2000" +: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. -[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" -If true, headers found through system include paths (-isystem) are also required to be declared. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" +: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. -[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated -Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. -<!-- --> +`--[no]experimental_android_use_parallel_dex2oat` default: "false" +: Use dex2oat in parallel to possibly speed up android\_test. -[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" -Implementation to use to sign APKs + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]ios_memleaks` default: "false" +: Enable checking for memory leaks in ios\_test targets. -[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" -If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--ios_simulator_device=<a string>` default: see description +: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. -[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description -Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. -<!-- --> + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" -If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. -[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" -If true, make the default value true for alwayslink attributes in objc_library and objc_import. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" +: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. -[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" -When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. +`--[no]zip_undeclared_test_outputs` default: "false" +: If true, undeclared test outputs will be archived in a zip file. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -<!-- --> +Options that trigger optimizations of the build time: -[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" -If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" +: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" -Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. +`--[no]experimental_inmemory_dotd_files` default: "true" +: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" -If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. +`--[no]experimental_inmemory_jdeps_files` default: "true" +: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" +: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. -[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" -Use dex2oat in parallel to possibly speed up android_test. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" +: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. -[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" -Enable checking for memory leaks in ios_test targets. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]incremental_dexing` default: "true" +: Does most of the work for dexing separately for each Jar file. -[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description -The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--[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. -[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--[no]process_headers_in_dependencies` default: "false" +: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). -[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. +`--[no]trim_test_configuration` default: "true" +: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" -Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. +Options that affect the verbosity, format or location of logging: -[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" -If true, undeclared test outputs will be archived in a zip file. +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -<!-- --> +`--[no]verbose_visibility_errors` default: "false" +: If enabled, visibility errors include additional diagnostic information. -[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" -Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" -If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated +: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" -If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. +`--[no]incompatible_default_to_explicit_init_py` default: "false" +: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" -When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. +Miscellaneous options, not otherwise categorized.: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]cache_test_results` [`-t`] default: "auto" +: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. -[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" -Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. +`--[no]experimental_cancel_concurrent_tests` default: "never" +: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incremental_dexing`](#flag--incremental_dexing) default: "true" -Does most of the work for dexing separately for each Jar file. +`--[no]experimental_fetch_all_coverage_outputs` default: "false" +: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]objc_use_dotd_pruning`](#flag--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. +`--[no]experimental_generate_llvm_lcov` default: "false" +: If true, coverage for clang will generate an LCOV report. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" -When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +: Enables reduced classpaths for Java compilations. -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]experimental_run_android_lint_on_java_rules` default: "false" +: Whether to validate java\_\* sources. -[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" -When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[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. -<!-- --> +`--host_java_launcher=<a build target label>` default: see description +: The Java launcher used by tools that are executed during a build. -[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. +`--host_javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac when building tools that are executed during a build. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--host_jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. -[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" -If enabled, visibility errors include additional diagnostic information. +`--[no]incompatible_check_sharding_support` default: "true" +: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +`--[no]incompatible_exclusive_test_sandboxed` default: "true" +: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally -[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated -Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]incompatible_strict_action_env` default: "false" +: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. -[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" -This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. -<!-- --> +`--java_debug` +: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. -[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" -If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + Expands to: + +   `--test_arg=--wrapper_script_flag=--debug` + +   `--test_output=streamed` + +   `--test_strategy=exclusive` + +   `--test_timeout=9999` + +   `--nocache_test_results` -[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" -If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. +`--[no]java_deps` default: "true" +: Generate dependency information (for now, compile-time classpath) per Java target. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]java_header_compilation` default: "true" +: Compile ijars directly from source. -[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" -If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. +`--java_language_version=<a string>` default: "" +: The Java language version -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--java_launcher=<a build target label>` default: see description +: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. -[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" -If true, coverage for clang will generate an LCOV report. +`--java_runtime_version=<a string>` default: "local\_jdk" +: The Java runtime version -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac. -[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -Enables reduced classpaths for Java compilations. +`--jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. -[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" -Whether to validate java\_\* sources. +`--legacy_main_dex_list_generator=<a build target label>` default: see description +: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--optimizing_dexer=<a build target label>` default: see description +: Specifies a binary to use to do dexing without sharding. -[`--[no]explicit_java_test_deps`](#flag--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. +`--plugin=<a build target label>` multiple uses are accumulated +: Plugins to use in the build. Currently works with java\_plugin. -[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description -The Java launcher used by tools that are executed during a build. +`--proguard_top=<a build target label>` default: see description +: Specifies which version of ProGuard to use for code removal when building a Java binary. -[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac when building tools that are executed during a build. +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" +: The label of the proto-compiler. -[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" -If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. +`--[no]proto_profile` default: "true" +: Whether to pass profile\_path to the proto compiler. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" -If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally +`--proto_profile_path=<a build target label>` default: see description +: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" -If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile C++ protos -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated -Additional options to pass to the J2ObjC tool. +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos -[`--java_debug`](#flag--java_debug) -Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Expands to: -  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) -  [`--test_output=streamed`](#flag--test_output) -  [`--test_strategy=exclusive`](#flag--test_strategy) -  [`--test_timeout=9999`](#flag--test_timeout) -  [`--nocache_test_results`](#flag--nocache_test_results) +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile Java protos -[`--[no]java_deps`](#flag--java_deps) default: "true" -Generate dependency information (for now, compile-time classpath) per Java target. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" -Compile ijars directly from source. +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos -[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" -The Java language version + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description -The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. +`--protocopt=<a string>` multiple uses are accumulated +: Additional options to pass to the protobuf compiler. -[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" -The Java runtime version + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac. +`--[no]runs_per_test_detects_flakes` default: "false" +: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. -[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. +`--shell_executable=<a path>` default: see description +: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. -[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description -Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description -Specifies a binary to use to do dexing without sharding. +`--test_arg=<a string>` multiple uses are accumulated +: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. -[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated -Plugins to use in the build. Currently works with java_plugin. +`--test_filter=<a string>` default: see description +: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. -[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description -Specifies which version of ProGuard to use for code removal when building a Java binary. +`--test_result_expiration=<an integer>` default: "-1" +: This option is deprecated and has no effect. -[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" -The label of the proto-compiler. +`--[no]test_runner_fail_fast` default: "false" +: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. -[`--[no]proto_profile`](#flag--proto_profile) default: "true" -Whether to pass profile_path to the proto compiler. +`--tool_java_language_version=<a string>` default: "" +: The Java language version used to execute the tools that are needed during a build -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" +: The Java runtime version used to execute tools during the build -[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description -The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. +`--[no]use_ijars` default: "true" +: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +## Canonicalize-flags Options -[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" -Label of proto_lang_toolchain() which describes how to compile C++ protos +Inherits all options from [build](#build). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +Options that control the output of the command: -[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" -Label of proto_lang_toolchain() which describes how to compile j2objc protos +`--[no]canonicalize_policy` default: "false" +: Output the canonical policy, after expansion and filtering. To keep the output clean, the canonicalized command arguments will NOT be shown when this option is set to true. Note that the command specified by --for\_command affects the filtered policy, and if none is specified, the default command is 'build'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" -Label of proto_lang_toolchain() which describes how to compile Java protos +`--[no]experimental_include_default_values` default: "true" +: Whether Starlark options set to their default values are included in the output. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" -Label of proto_lang_toolchain() which describes how to compile JavaLite protos +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_config_setting_private_default_visibility` default: "false" +: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. -[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the protobuf compiler. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_enforce_config_setting_visibility` default: "true" +: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. -[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" -If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description -Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--for_command=<a string>` default: "build" +: The command for which the options should be canonicalized. -[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated -Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--test_filter`](#flag--test_filter)`=<a string>` default: see description -Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. +`--invocation_policy=<a string>` default: "" +: Applies an invocation policy to the options to be canonicalized. -[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" -This option is deprecated and has no effect. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" -Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. +Miscellaneous options, not otherwise categorized.: -[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated +: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. + Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. -[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" -The Java language version used to execute the tools that are needed during a build +`--[no]fetch` default: "true" +: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. -[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" -The Java runtime version used to execute tools during the build +`--package_path=<colon-separated list of options>` default: "%workspace%" +: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. -[`--[no]use_ijars`](#flag--use_ijars) default: "true" -If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. +`--[no]show_loading_progress` default: "true" +: If enabled, causes Bazel to print "Loading package:" messages. -## <span id="canonicalize-flags">Canonicalize-flags Options</span> +## Clean Options Inherits all options from [build](#build). -[`--[no]canonicalize_policy`](#canonicalize-flags-flag--canonicalize_policy) default: "false" -Output the canonical policy, after expansion and filtering. To keep the output clean, the canonicalized command arguments will NOT be shown when this option is set to true. Note that the command specified by --for_command affects the filtered policy, and if none is specified, the default command is 'build'. - -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -[`--[no]experimental_include_default_values`](#canonicalize-flags-flag--experimental_include_default_values) default: "true" -Whether Starlark options set to their default values are included in the output. - -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -<!-- --> - -[`--[no]incompatible_config_setting_private_default_visibility`](#canonicalize-flags-flag--incompatible_config_setting_private_default_visibility) default: "false" -If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. - -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -[`--[no]incompatible_enforce_config_setting_visibility`](#canonicalize-flags-flag--incompatible_enforce_config_setting_visibility) default: "true" -If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. - -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -<!-- --> - -[`--for_command`](#canonicalize-flags-flag--for_command)`=<a string>` default: "build" -The command for which the options should be canonicalized. - -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +Options that control the output of the command: -[`--invocation_policy`](#canonicalize-flags-flag--invocation_policy)`=<a string>` default: "" -Applies an invocation policy to the options to be canonicalized. +`--[no]async` default: "false" +: If true, output cleaning is asynchronous. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -<!-- --> +`--[no]expunge` default: "false" +: If true, clean removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. -[`--deleted_packages`](#canonicalize-flags-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated -A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -[`--[no]fetch`](#canonicalize-flags-flag--fetch) default: "true" -Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. +`--expunge_async` +: If specified, clean asynchronously removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. -[`--package_path`](#canonicalize-flags-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" -A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + Expands to: + +   `--expunge` + +   `--async` -[`--[no]show_loading_progress`](#canonicalize-flags-flag--show_loading_progress) default: "true" -If enabled, causes Bazel to print "Loading package:" messages. + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) -## <span id="clean">Clean Options</span> +## Config Options -Inherits all options from [build](#build). - -[`--[no]async`](#clean-flag--async) default: "false" -If true, output cleaning is asynchronous. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. - -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -[`--[no]expunge`](#clean-flag--expunge) default: "false" -If true, clean removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. - -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -[`--expunge_async`](#clean-flag--expunge_async) -If specified, clean asynchronously removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. - -Expands to: -  [`--expunge`](#flag--expunge) -  [`--async`](#flag--async) - -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -## <span id="config">Config Options</span> - -## <span id="coverage">Coverage Options</span> +## Coverage Options Inherits all options from [test](#test). -## <span id="cquery">Cquery Options</span> +## Cquery Options Inherits all options from [test](#test). -[`--aspect_deps`](#cquery-flag--aspect_deps)`=<off, conservative or precise>` default: "conservative" -How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. - -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -[`--[no]consistent_labels`](#cquery-flag--consistent_labels) default: "false" -If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. - -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -[`--[no]experimental_explicit_aspects`](#cquery-flag--experimental_explicit_aspects) default: "false" -aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). - -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -[`--[no]graph:factored`](#cquery-flag--graph:factored) default: "true" -If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. +Options relating to query output and semantics: -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--aspect_deps=<off, conservative or precise>` default: "conservative" +: How to resolve aspect dependencies when the output format is one of \{xml,proto,record\}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. -[`--graph:node_limit`](#cquery-flag--graph:node_limit)`=<an integer>` default: "512" -The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]consistent_labels` default: "false" +: If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. -[`--[no]implicit_deps`](#cquery-flag--implicit_deps) default: "true" -If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--[no]experimental_explicit_aspects` default: "false" +: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). -[`--[no]include_aspects`](#cquery-flag--include_aspects) default: "true" -aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]graph:factored` default: "true" +: If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. -[`--[no]incompatible_package_group_includes_double_slash`](#cquery-flag--incompatible_package_group_includes_double_slash) default: "true" -If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--graph:node_limit=<an integer>` default: "512" +: The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. -[`--[no]infer_universe_scope`](#cquery-flag--infer_universe_scope) default: "false" -If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]implicit_deps` default: "true" +: If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. -[`--[no]line_terminator_null`](#cquery-flag--line_terminator_null) default: "false" -Whether each format is terminated with \0 instead of newline. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]include_aspects` default: "true" +: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). -[`--[no]nodep_deps`](#cquery-flag--nodep_deps) default: "true" -If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--[no]incompatible_package_group_includes_double_slash` default: "true" +: If enabled, when outputting package\_group's `packages` attribute, the leading `//` will not be omitted. -[`--output`](#cquery-flag--output)`=<a string>` default: "label" -The format in which the cquery results should be printed. Allowed values for cquery are: label, label_kind, textproto, transitions, proto, streamed_proto, jsonproto. If you select 'transitions', you also have to specify the --transitions=(lite\|full) option. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]infer_universe_scope` default: "false" +: If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). -[`--output_file`](#cquery-flag--output_file)`=<a string>` default: "" -When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]line_terminator_null` default: "false" +: Whether each format is terminated with \0 instead of newline. -[`--[no]proto:default_values`](#cquery-flag--proto:default_values) default: "true" -If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]nodep_deps` default: "true" +: If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. -[`--[no]proto:definition_stack`](#cquery-flag--proto:definition_stack) default: "false" -Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--output=<a string>` default: "label" +: The format in which the cquery results should be printed. Allowed values for cquery are: label, label\_kind, textproto, transitions, proto, streamed\_proto, jsonproto. If you select 'transitions', you also have to specify the --transitions=(lite|full) option. -[`--[no]proto:flatten_selects`](#cquery-flag--proto:flatten_selects) default: "true" -If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--output_file=<a string>` default: "" +: When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. -[`--[no]proto:include_attribute_source_aspects`](#cquery-flag--proto:include_attribute_source_aspects) default: "false" -Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:default_values` default: "true" +: If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto -[`--[no]proto:include_configurations`](#cquery-flag--proto:include_configurations) default: "true" -if enabled, proto output will include information about configurations. When disabled,cquery proto output format resembles query output format. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]proto:definition_stack` default: "false" +: Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. -[`--[no]proto:include_starlark_rule_env`](#cquery-flag--proto:include_starlark_rule_env) default: "true" -Use the starlark environment in the value of the generated \$internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:flatten_selects` default: "true" +: If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. -[`--[no]proto:include_synthetic_attribute_hash`](#cquery-flag--proto:include_synthetic_attribute_hash) default: "false" -Whether or not to calculate and populate the \$internal_attr_hash attribute. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:include_attribute_source_aspects` default: "false" +: Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). -[`--[no]proto:instantiation_stack`](#cquery-flag--proto:instantiation_stack) default: "false" -Populate the instantiation call stack of each rule. Note that this requires the stack to be present + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:include_configurations` default: "true" +: if enabled, proto output will include information about configurations. When disabled,cquery proto output format resembles query output format. -[`--[no]proto:locations`](#cquery-flag--proto:locations) default: "true" -Whether to output location information in proto output at all. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:include_starlark_rule_env` default: "true" +: Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. -[`--proto:output_rule_attrs`](#cquery-flag--proto:output_rule_attrs)`=<comma-separated list of options>` default: "all" -Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:include_synthetic_attribute_hash` default: "false" +: Whether or not to calculate and populate the $internal\_attr\_hash attribute. -[`--[no]proto:rule_classes`](#cquery-flag--proto:rule_classes) default: "false" -Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:instantiation_stack` default: "false" +: Populate the instantiation call stack of each rule. Note that this requires the stack to be present -[`--[no]proto:rule_inputs_and_outputs`](#cquery-flag--proto:rule_inputs_and_outputs) default: "true" -Whether or not to populate the rule_input and rule_output fields. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:locations` default: "true" +: Whether to output location information in proto output at all. -[`--query_file`](#cquery-flag--query_file)`=<a string>` default: "" -If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" +: Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. -[`--[no]relative_locations`](#cquery-flag--relative_locations) default: "false" -If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]proto:rule_classes` default: "false" +: Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. -[`--show_config_fragments`](#cquery-flag--show_config_fragments)`=<off, direct or transitive>` default: "off" -Shows the configuration fragments required by a rule and its transitive dependencies. This can be useful for evaluating how much a configured target graph can be trimmed. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]proto:rule_inputs_and_outputs` default: "true" +: Whether or not to populate the rule\_input and rule\_output fields. -[`--starlark:expr`](#cquery-flag--starlark:expr)`=<a string>` default: "" -A Starlark expression to format each configured target in cquery's --output=starlark mode. The configured target is bound to 'target'. If neither --starlark:expr nor --starlark:file is specified, this option will default to 'str(target.label)'. It is an error to specify both --starlark:expr and --starlark:file. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--query_file=<a string>` default: "" +: If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. -[`--starlark:file`](#cquery-flag--starlark:file)`=<a string>` default: "" -The name of a file that defines a Starlark function called 'format', of one argument, that is applied to each configured target to format it as a string. It is an error to specify both --starlark:expr and --starlark:file. See help for --output=starlark for additional detail. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]relative_locations` default: "false" +: If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. -[`--[no]tool_deps`](#cquery-flag--tool_deps) default: "true" -Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. -Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--show_config_fragments=<off, direct or transitive>` default: "off" +: Shows the configuration fragments required by a rule and its transitive dependencies. This can be useful for evaluating how much a configured target graph can be trimmed. -[`--transitions`](#cquery-flag--transitions)`=<full, lite or none>` default: "none" -The format in which cquery will print transition information. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--starlark:expr=<a string>` default: "" +: A Starlark expression to format each configured target in cquery's --output=starlark mode. The configured target is bound to 'target'. If neither --starlark:expr nor --starlark:file is specified, this option will default to 'str(target.label)'. It is an error to specify both --starlark:expr and --starlark:file. -[`--universe_scope`](#cquery-flag--universe_scope)`=<comma-separated list of options>` default: "" -A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. -For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--starlark:file=<a string>` default: "" +: The name of a file that defines a Starlark function called 'format', of one argument, that is applied to each configured target to format it as a string. It is an error to specify both --starlark:expr and --starlark:file. See help for --output=starlark for additional detail. -<!-- --> + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" -Enable persistent aar extractor by using workers. +`--[no]tool_deps` default: "true" +: Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. + Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" -Whether to make source manifest actions remotable +`--transitions=<full, lite or none>` default: "none" +: The format in which cquery will print transition information. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" -If true, then Bazel will run coverage postprocessing for test in a new spawn. +`--universe_scope=<comma-separated list of options>` default: "" +: A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. + For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" -If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. +Options that control build execution: -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_persistent_aar_extractor` default: "false" +: Enable persistent aar extractor by using workers. -[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" -When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]experimental_remotable_source_manifests` default: "false" +: Whether to make source manifest actions remotable -[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". +`--[no]experimental_split_coverage_postprocessing` default: "false" +: If true, then Bazel will run coverage postprocessing for test in a new spawn. -Examples: -'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]experimental_strict_fileset_output` default: "false" +: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. -[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -Enable persistent Android dex and desugar actions by using workers. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Expands to: -  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) -  [`--strategy=Desugar=worker`](#flag--strategy) -  [`--strategy=DexBuilder=worker`](#flag--strategy) +`--[no]incompatible_modify_execution_info_additive` default: "true" +: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + + Syntax: "regex=[+-]key,regex=[+-]key,...". + + Examples: + '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. + 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. + '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` +: Enable persistent Android dex and desugar actions by using workers. + + Expands to: + +   `--internal_persistent_android_dex_desugar` + +   `--strategy=Desugar=worker` + +   `--strategy=DexBuilder=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` +: Enable persistent Android resource processor by using workers. + + Expands to: + +   `--internal_persistent_busybox_tools` + +   `--strategy=AaptPackage=worker` + +   `--strategy=AndroidResourceParser=worker` + +   `--strategy=AndroidResourceValidator=worker` + +   `--strategy=AndroidResourceCompiler=worker` + +   `--strategy=RClassGenerator=worker` + +   `--strategy=AndroidResourceLink=worker` + +   `--strategy=AndroidAapt2=worker` + +   `--strategy=AndroidAssetMerger=worker` + +   `--strategy=AndroidResourceMerger=worker` + +   `--strategy=AndroidCompiledResourceMerger=worker` + +   `--strategy=ManifestMerger=worker` + +   `--strategy=AndroidManifestMerger=worker` + +   `--strategy=Aapt2Optimize=worker` + +   `--strategy=AARGenerator=worker` + +   `--strategy=ProcessDatabinding=worker` + +   `--strategy=GenerateDataBindingBaseClasses=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` +: Enable persistent multiplexed Android dex and desugar actions by using workers. + + Expands to: + +   `--persistent_android_dex_desugar` + +   `--internal_persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` +: Enable persistent multiplexed Android resource processor by using workers. + + Expands to: + +   `--persistent_android_resource_processor` + +   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` +: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + + Expands to: + +   `--internal_persistent_multiplex_busybox_tools` + +   `--persistent_multiplex_android_resource_processor` + +   `--persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" +: If true, use the target platform for running tests rather than the test exec group. + + Tags: + [`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: + +`--android_compiler=<a string>` default: see description +: The Android target compiler. + + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" +: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -Enable persistent Android resource processor by using workers. +`--android_platforms=<a build target label>` default: "" +: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. -Expands to: -  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) -  [`--strategy=AaptPackage=worker`](#flag--strategy) -  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) -  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) -  [`--strategy=RClassGenerator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) -  [`--strategy=AndroidAapt2=worker`](#flag--strategy) -  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) -  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) -  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) -  [`--strategy=ManifestMerger=worker`](#flag--strategy) -  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) -  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) -  [`--strategy=AARGenerator=worker`](#flag--strategy) -  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) -  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--cc_output_directory_tag=<a string>` default: "" +: Specifies a suffix to be added to the configuration directory. -[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) -Enable persistent multiplexed Android dex and desugar actions by using workers. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Expands to: -  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) +`--compiler=<a string>` default: see description +: The C++ compiler to use for compiling the target. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -Enable persistent multiplexed Android resource processor by using workers. +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" +: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. -Expands to: -  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" +: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. -[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) -Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Expands to: -  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) -  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" +: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" -If true, use the target platform for running tests rather than the test exec group. +`--custom_malloc=<a build target label>` default: see description +: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -<!-- --> +`--[no]experimental_include_xcode_execution_requirements` default: "false" +: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. -[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description -The Android target compiler. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]experimental_prefer_mutual_xcode` default: "true" +: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. -[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" -Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--extra_execution_platforms=<comma-separated list of options>` default: "" +: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. -[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" -Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated +: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). -[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" -Specifies a suffix to be added to the configuration directory. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--grte_top=<a label>` default: see description +: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. -[`--compiler`](#flag--compiler)`=<a string>` default: see description -The C++ compiler to use for compiling the target. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) +`--host_compiler=<a string>` default: see description +: No-op flag. Will be removed in a future release. -[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" -Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--host_grte_top=<a label>` default: see description +: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. -[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" -Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" +: The label of a platform rule that describes the host system. -[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" -Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_bazel_test_exec_run_under` default: "true" +: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. -[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description -Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_builtin_objc_strip_action` default: "true" +: Whether to emit a strip action as part of objc linking. -[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" -If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" +: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). -[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" -If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" +: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) -[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" -The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]incompatible_remove_legacy_whole_archive` default: "true" +: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). -[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated -The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_strip_executable_safely` default: "false" +: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. -[`--grte_top`](#flag--grte_top)`=<a label>` default: see description -A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]interface_shared_objects` default: "true" +: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. -[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description -No-op flag. Will be removed in a future release. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. -[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description -If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. -[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" -The label of a platform rule that describes the host system. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--minimum_os_version=<a string>` default: see description +: The minimum OS version which your compilation targets. -[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" -If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--platform_mappings=<a main workspace-relative path>` default: "" +: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). -[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" -Whether to emit a strip action as part of objc linking. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--platforms=<a build target label>` default: "" +: The labels of the platform rules describing the target platforms for the current command. -[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" -If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--python_path=<a string>` default: see description +: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. -[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" -Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. -[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" -If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. -[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" -If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. -[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" -Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--xcode_version=<a string>` default: see description +: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. -[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" +: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. -[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +Options that control the output of the command: -[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description -The minimum OS version which your compilation targets. +`--[no]apple_generate_dsym` default: "false" +: Whether to generate debug symbol(.dSYM) file(s). -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" -The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). +`--[no]build_runfile_links` default: "true" +: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--platforms`](#flag--platforms)`=<a build target label>` default: "" -The labels of the platform rules describing the target platforms for the current command. +`--[no]build_runfile_manifests` default: "true" +: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--python_path`](#flag--python_path)`=<a string>` default: see description -The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. +`--[no]build_test_dwp` default: "false" +: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" +: Sets the suffixes of header files that a cc\_proto\_library creates. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" -Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" +: Sets the suffixes of source files that a cc\_proto\_library creates. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" +: Run extra actions for alternative Java api versions in a proto\_library. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description -If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. +`--[no]experimental_save_feature_state` default: "false" +: Save the state of enabled and requested feautres as an output of compilation. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" -The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. +`--fission=<a set of compilation modes>` default: "no" +: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -<!-- --> +`--[no]incompatible_always_include_files_in_data` default: "true" +: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). -[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" -Whether to generate debug symbol(.dSYM) file(s). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" +: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. -[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" -If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" +: List of flags for which the use in select() is disabled. -[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" -If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" +: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. -[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" -If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]objc_generate_linkmap` default: "false" +: Specifies whether to generate a linkmap file. -[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" -Sets the suffixes of header files that a cc_proto_library creates. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]save_temps` default: "false" +: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). -[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" -Sets the suffixes of source files that a cc_proto_library creates. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" -Run extra actions for alternative Java api versions in a proto_library. +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case + the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + \<br\> + Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" -Save the state of enabled and requested feautres as an output of compilation. +`--allowed_cpu_values=<comma-separated set of options>` default: "" +: Allowed values for the --cpu flag. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" -Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. +`--[no]android_databinding_use_androidx` default: "true" +: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" -If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). +`--[no]android_databinding_use_v3_4_args` default: "true" +: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" -If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. +`--android_dynamic_mode=<off, default or fully>` default: "off" +: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" -List of flags for which the use in select() is disabled. +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) -[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" -If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. +`--[no]android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" -Specifies whether to generate a linkmap file. +`--[no]build_python_zip` default: "auto" +: Build python executable zip; on on Windows, off on other platforms -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]save_temps`](#flag--save_temps) default: "false" -If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple Catalyst binaries. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -<!-- --> +`--[no]collect_code_coverage` default: "false" +: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. -[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case -the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -\<br\> -Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" +: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. -[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" -Allowed values for the --cpu flag. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C source files. -[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" -Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--copt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc. -[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" -Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--cpu=<a string>` default: "" +: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. -[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" -Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--cs_fdo_absolute_path=<a string>` default: see description +: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. -[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) +`--cs_fdo_instrument=<a string>` default: see description +: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--cs_fdo_profile=<a build target label>` default: see description +: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. -[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" -Build python executable zip; on on Windows, off on other platforms + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cxxopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C++ source files. -[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple Catalyst binaries. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--define=<a 'name=value' assignment>` multiple uses are accumulated +: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. -[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" -If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--dynamic_mode=<off, default or fully>` default: "default" +: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" -Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]enable_propeller_optimize_absolute_paths` default: "true" +: If set, any use of absolute paths for propeller optimize will raise an error. -[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C source files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]enable_remaining_fdo_absolute_paths` default: "true" +: If set, any use of absolute paths for FDO will raise an error. -[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]enable_runfiles` default: "auto" +: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. -[`--cpu`](#flag--cpu)`=<a string>` default: "" -Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. -[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description -Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--experimental_action_listener=<a build target label>` multiple uses are accumulated +: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. -[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description -Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_android_compress_java_resources` default: "false" +: Compress Java resources in APKs -[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description -The cs_fdo_profile representing the context sensitive profile to be used for optimization. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_android_databinding_v2` default: "true" +: Use android databinding v2. This flag is a no-op. -[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C++ source files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated -Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" +: use rex tool to rewrite dex files -[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" -Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" +: If specified, Bazel will also generate collect coverage information for generated files. -[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" -If set, any use of absolute paths for propeller optimize will raise an error. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +: Uses these strings as objc fastbuild compiler options. -[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" -If set, any use of absolute paths for FDO will raise an error. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_omitfp` default: "false" +: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. -[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" -Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--experimental_output_paths=<off or strip>` default: "off" +: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. -[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated +: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. -[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated -Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_platform_in_output_dir` default: "false" +: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. -[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" -Compress Java resources in APKs + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_py_binaries_include_label` default: "false" +: py\_binary targets include their label even when stamping is disabled. -[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" -Use android databinding v2. This flag is a no-op. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_use_llvm_covmap` default: "false" +: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. -[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" +: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. -[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" -use rex tool to rewrite dex files + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--fdo_instrument=<a string>` default: see description +: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" -If specified, Bazel will also generate collect coverage information for generated files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--fdo_optimize=<a string>` default: see description +: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. -[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -Uses these strings as objc fastbuild compiler options. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--fdo_prefetch_hints=<a build target label>` default: see description +: Use cache prefetch hints. -[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" -If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--fdo_profile=<a build target label>` default: see description +: The fdo\_profile representing the profile to be used for optimization. -[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" -Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) +`--features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features -[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated -Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]force_pic` default: "false" +: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). -[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" -If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" -py_binary targets include their label even when stamping is disabled. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" +: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. -[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" -If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--host_conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. -[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" -Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--host_copt=<a string>` multiple uses are accumulated +: Additional options to pass to the C compiler for tools built in the exec configurations. -[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description -Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_cpu=<a string>` default: "" +: The host CPU. -[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description -Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_cxxopt=<a string>` multiple uses are accumulated +: Additional options to pass to C++ compiler for tools built in the exec configurations. -[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description -Use cache prefetch hints. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. -[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description -The fdo_profile representing the profile to be used for optimization. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to linker when linking tools in the exec configurations. -[`--features`](#flag--features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. -[`--[no]force_pic`](#flag--force_pic) default: "false" -If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]incompatible_auto_exec_groups` default: "false" +: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. -[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" -Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]incompatible_merge_genfiles_directory` default: "true" +: If true, the genfiles directory is folded into the bin directory. -[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_target_cpu_from_platform` default: "true" +: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. -[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated -Additional options to pass to the C compiler for tools built in the exec configurations. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]instrument_test_targets` default: "false" +: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. -[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" -The host CPU. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" +: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. -[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated -Additional options to pass to C++ compiler for tools built in the exec configurations. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. -[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. -[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to linker when linking tools in the exec configurations. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]legacy_whole_archive` default: "true" +: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. -[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when linking. -[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ltobackendopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO backend step (under --features=thin\_lto). -[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" -When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--ltoindexopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO indexing step (under --features=thin\_lto). -[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" -If true, the genfiles directory is folded into the bin directory. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple macOS binaries. -[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" -If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. -[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" -When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--memprof_profile=<a build target label>` default: see description +: Use memprof profile. -[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" -When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]objc_debug_with_GLIBCXX` default: "false" +: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. -[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]objc_enable_binary_stripping` default: "false" +: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. -[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--objccopt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc when compiling Objective-C/C++ source files. -[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" -Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when linking. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. -[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO backend step (under --features=thin_lto). + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--platform_suffix=<a string>` default: see description +: Specifies a suffix to be added to the configuration directory. -[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO indexing step (under --features=thin_lto). + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--propeller_optimize=<a build target label>` default: see description +: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile -[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple macOS binaries. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description +: Absolute path name of cc\_profile file for Propeller Optimized builds. -[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description +: Absolute path name of ld\_profile file for Propeller Optimized builds. -[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description -Use memprof profile. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--run_under=<a prefix in front of command>` default: see description +: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. -[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" -If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]share_native_deps` default: "true" +: If true, native libraries that contain identical functionality will be shared among different targets -[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" -Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]stamp` default: "false" +: Stamp binaries with the date, username, hostname, workspace information, etc. -[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc when compiling Objective-C/C++ source files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--strip=<always, sometimes or never>` default: "sometimes" +: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. -[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--stripopt=<a string>` multiple uses are accumulated +: Additional options to pass to strip when generating a '\<name\>.stripped' binary. -[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple tvOS binaries. -[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description -Specifies a suffix to be added to the configuration directory. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. -[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description -Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple visionOS binaries. -[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description -Absolute path name of cc_profile file for Propeller Optimized builds. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple watchOS binaries. -[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description -Absolute path name of ld_profile file for Propeller Optimized builds. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. -[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description -Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--xbinary_fdo=<a build target label>` default: see description +: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. -[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" -If true, native libraries that contain identical functionality will be shared among different targets + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -[`--[no]stamp`](#flag--stamp) default: "false" -Stamp binaries with the date, username, hostname, workspace information, etc. +`--[no]check_visibility` default: "true" +: If disabled, visibility errors in target dependencies are demoted to warnings. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" -Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. +`--[no]desugar_for_android` default: "true" +: Whether to desugar Java 8 bytecode before dexing. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated -Additional options to pass to strip when generating a '\<name\>.stripped' binary. +`--[no]desugar_java8_libs` default: "false" +: Whether to include supported Java 8 libraries in apps for legacy devices. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple tvOS binaries. +`--[no]enforce_constraints` default: "true" +: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. +`--[no]experimental_check_desugar_deps` default: "true" +: Whether to double-check correct desugaring at Android binary level. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple visionOS binaries. +`--[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. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple watchOS binaries. +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" +: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" +: If true, checks that a Java target explicitly declares all directly used targets as dependencies. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description -Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. +`--[no]incompatible_check_testonly_for_output_files` default: "false" +: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +`--[no]incompatible_disable_native_android_rules` default: "false" +: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android -[`--[no]check_visibility`](#flag--check_visibility) default: "true" -If disabled, visibility errors in target dependencies are demoted to warnings. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" +: No-op. Kept here for backwards compatibility. -[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" -Whether to desugar Java 8 bytecode before dexing. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]one_version_enforcement_on_java_tests` default: "true" +: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. -[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" -Whether to include supported Java 8 libraries in apps for legacy devices. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--python_native_rules_allowlist=<a build target label>` default: see description +: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. -[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" -Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--[no]strict_filesets` default: "false" +: If this option is enabled, filesets crossing package boundaries are reported as errors. -[`--[no]experimental_check_desugar_deps`](#flag--experimental_check_desugar_deps) default: "true" -Whether to double-check correct desugaring at Android binary level. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" +: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. -[`--[no]experimental_enforce_transitive_visibility`](#flag--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. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" +: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. -[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" -When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]strict_system_includes` default: "false" +: If true, headers found through system include paths (-isystem) are also required to be declared. -[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" -If true, checks that a Java target explicitly declares all directly used targets as dependencies. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--target_environment=<a build target label>` multiple uses are accumulated +: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. -[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" -If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +Options that affect the signing outputs of a build: -[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" -If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" +: Implementation to use to sign APKs -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" -No-op. Kept here for backwards compatibility. +`--[no]device_debug_entitlements` default: "true" +: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" -When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. +`--ios_signing_cert_name=<a string>` default: see description +: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description -An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" +: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. -[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" -If this option is enabled, filesets crossing package boundaries are reported as errors. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--[no]incompatible_objc_alwayslink_by_default` default: "false" +: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. -[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" -Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_python_disallow_native_rules` default: "false" +: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. -[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" -Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +Options that govern the behavior of the test environment or test runner: -[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" -If true, headers found through system include paths (-isystem) are also required to be declared. +`--[no]allow_analysis_failures` default: "false" +: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated -Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. +`--analysis_testing_deps_limit=<an integer>` default: "2000" +: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -<!-- --> +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" +: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. -[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" -Implementation to use to sign APKs + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. -[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" -If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. +`--[no]experimental_android_use_parallel_dex2oat` default: "false" +: Use dex2oat in parallel to possibly speed up android\_test. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description -Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). +`--[no]ios_memleaks` default: "false" +: Enable checking for memory leaks in ios\_test targets. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -<!-- --> +`--ios_simulator_device=<a string>` default: see description +: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. -[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" -If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. -[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" -If true, make the default value true for alwayslink attributes in objc_library and objc_import. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. -[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" -When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -<!-- --> +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" +: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. -[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" -If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. +`--[no]zip_undeclared_test_outputs` default: "false" +: If true, undeclared test outputs will be archived in a zip file. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" -Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. +Options that trigger optimizations of the build time: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" +: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. -[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" -If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_inmemory_dotd_files` default: "true" +: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. -[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" -Use dex2oat in parallel to possibly speed up android_test. +`--[no]experimental_inmemory_jdeps_files` default: "true" +: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" -Enable checking for memory leaks in ios_test targets. +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" +: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description -The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" +: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. +`--[no]incremental_dexing` default: "true" +: Does most of the work for dexing separately for each Jar file. -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. +`--[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. -[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--[no]process_headers_in_dependencies` default: "false" +: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). -[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" -Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" -If true, undeclared test outputs will be archived in a zip file. +`--[no]trim_test_configuration` default: "true" +: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -<!-- --> +Options that affect the verbosity, format or location of logging: -[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" -Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" -If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. +`--[no]verbose_visibility_errors` default: "false" +: If enabled, visibility errors include additional diagnostic information. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" -If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated +: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. -[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" -When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]incompatible_default_to_explicit_init_py` default: "false" +: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. -[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" -Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +Miscellaneous options, not otherwise categorized.: -[`--[no]incremental_dexing`](#flag--incremental_dexing) default: "true" -Does most of the work for dexing separately for each Jar file. +`--[no]cache_test_results` [`-t`] default: "auto" +: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]experimental_cancel_concurrent_tests` default: "never" +: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. -[`--[no]objc_use_dotd_pruning`](#flag--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. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]experimental_fetch_all_coverage_outputs` default: "false" +: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. -[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" -When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]experimental_generate_llvm_lcov` default: "false" +: If true, coverage for clang will generate an LCOV report. -[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" -When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +: Enables reduced classpaths for Java compilations. -<!-- --> +`--[no]experimental_run_android_lint_on_java_rules` default: "false" +: Whether to validate java\_\* sources. -[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[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. -[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" -If enabled, visibility errors include additional diagnostic information. +`--host_java_launcher=<a build target label>` default: see description +: The Java launcher used by tools that are executed during a build. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--host_javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac when building tools that are executed during a build. -<!-- --> +`--host_jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. -[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated -Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. +`--[no]incompatible_check_sharding_support` default: "true" +: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" -This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. +`--[no]incompatible_exclusive_test_sandboxed` default: "true" +: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +`--[no]incompatible_strict_action_env` default: "false" +: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. -[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" -If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" -If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--java_debug` +: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. -[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" -If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + Expands to: + +   `--test_arg=--wrapper_script_flag=--debug` + +   `--test_output=streamed` + +   `--test_strategy=exclusive` + +   `--test_timeout=9999` + +   `--nocache_test_results` -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]java_deps` default: "true" +: Generate dependency information (for now, compile-time classpath) per Java target. -[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" -If true, coverage for clang will generate an LCOV report. +`--[no]java_header_compilation` default: "true" +: Compile ijars directly from source. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--java_language_version=<a string>` default: "" +: The Java language version -[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -Enables reduced classpaths for Java compilations. +`--java_launcher=<a build target label>` default: see description +: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. -[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" -Whether to validate java\_\* sources. +`--java_runtime_version=<a string>` default: "local\_jdk" +: The Java runtime version -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac. -[`--[no]explicit_java_test_deps`](#flag--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. +`--jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. -[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description -The Java launcher used by tools that are executed during a build. +`--legacy_main_dex_list_generator=<a build target label>` default: see description +: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. -[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac when building tools that are executed during a build. +`--optimizing_dexer=<a build target label>` default: see description +: Specifies a binary to use to do dexing without sharding. -[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. +`--plugin=<a build target label>` multiple uses are accumulated +: Plugins to use in the build. Currently works with java\_plugin. -[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" -If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. +`--proguard_top=<a build target label>` default: see description +: Specifies which version of ProGuard to use for code removal when building a Java binary. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" +: The label of the proto-compiler. -[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" -If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]proto_profile` default: "true" +: Whether to pass profile\_path to the proto compiler. -[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" -If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--proto_profile_path=<a build target label>` default: see description +: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. -[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated -Additional options to pass to the J2ObjC tool. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--java_debug`](#flag--java_debug) -Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile C++ protos -Expands to: -  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) -  [`--test_output=streamed`](#flag--test_output) -  [`--test_strategy=exclusive`](#flag--test_strategy) -  [`--test_timeout=9999`](#flag--test_timeout) -  [`--nocache_test_results`](#flag--nocache_test_results) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]java_deps`](#flag--java_deps) default: "true" -Generate dependency information (for now, compile-time classpath) per Java target. +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos -[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" -Compile ijars directly from source. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" -The Java language version +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile Java protos -[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description -The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" -The Java runtime version +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos -[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. +`--protocopt=<a string>` multiple uses are accumulated +: Additional options to pass to the protobuf compiler. -[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description -Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description -Specifies a binary to use to do dexing without sharding. +`--[no]runs_per_test_detects_flakes` default: "false" +: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. -[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated -Plugins to use in the build. Currently works with java_plugin. +`--shell_executable=<a path>` default: see description +: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. -[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description -Specifies which version of ProGuard to use for code removal when building a Java binary. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" -The label of the proto-compiler. +`--test_arg=<a string>` multiple uses are accumulated +: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--test_filter=<a string>` default: see description +: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. -[`--[no]proto_profile`](#flag--proto_profile) default: "true" -Whether to pass profile_path to the proto compiler. +`--test_result_expiration=<an integer>` default: "-1" +: This option is deprecated and has no effect. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]test_runner_fail_fast` default: "false" +: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. -[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description -The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tool_java_language_version=<a string>` default: "" +: The Java language version used to execute the tools that are needed during a build -[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" -Label of proto_lang_toolchain() which describes how to compile C++ protos +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" +: The Java runtime version used to execute tools during the build -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]use_ijars` default: "true" +: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. -[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" -Label of proto_lang_toolchain() which describes how to compile j2objc protos +## Dump Options -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +Options that control the output of the command: -[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" -Label of proto_lang_toolchain() which describes how to compile Java protos +`--[no]action_cache` default: "false" +: Dump action cache content. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" -Label of proto_lang_toolchain() which describes how to compile JavaLite protos +`--memory=<memory mode>` default: see description +: Dump the memory use of the given Skyframe node. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the protobuf compiler. +`--[no]packages` default: "false" +: Dump package cache content. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" -If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. +`--[no]rule_classes` default: "false" +: Dump rule classes. -[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description -Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]rules` default: "false" +: Dump rules, including counts and memory usage (if memory is tracked). -[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated -Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--test_filter`](#flag--test_filter)`=<a string>` default: see description -Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. +`--skyframe=<off, summary, count, value, deps, rdeps, function_graph, active_directories or active_directories_frontier_deps>` default: "off" +: Dump the Skyframe graph. -[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" -This option is deprecated and has no effect. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" -Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. +`--skykey_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: ".\*" +: Regex filter of SkyKey names to output. Only used with --skyframe=deps, rdeps, function\_graph. -[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" -The Java language version used to execute the tools that are needed during a build +`--skylark_memory=<a string>` default: see description +: Dumps a pprof-compatible memory profile to the specified path. To learn more please see https://github.com/google/pprof. -[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" -The Java runtime version used to execute tools during the build + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -[`--[no]use_ijars`](#flag--use_ijars) default: "true" -If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. - -## <span id="dump">Dump Options</span> - -[`--[no]action_cache`](#dump-flag--action_cache) default: "false" -Dump action cache content. - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -[`--memory`](#dump-flag--memory)`=<memory mode>` default: see description -Dump the memory use of the given Skyframe node. - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -[`--[no]packages`](#dump-flag--packages) default: "false" -Dump package cache content. - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -[`--[no]rule_classes`](#dump-flag--rule_classes) default: "false" -Dump rule classes. - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -[`--[no]rules`](#dump-flag--rules) default: "false" -Dump rules, including counts and memory usage (if memory is tracked). - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -[`--skyframe`](#dump-flag--skyframe)`=<off, summary, count, value, deps, rdeps, function_graph, active_directories or active_directories_frontier_deps>` default: "off" -Dump the Skyframe graph. - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -[`--skykey_filter`](#dump-flag--skykey_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: ".\*" -Regex filter of SkyKey names to output. Only used with --skyframe=deps, rdeps, function_graph. - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -[`--skylark_memory`](#dump-flag--skylark_memory)`=<a string>` default: see description -Dumps a pprof-compatible memory profile to the specified path. To learn more please see https://github.com/google/pprof. - -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -## <span id="fetch">Fetch Options</span> +## Fetch Options Inherits all options from [test](#test). -[`--[no]all`](#fetch-flag--all) default: "false" -Fetches all external repositories necessary for building any target or repository. This is the default if no other flags and arguments are provided. Only works when --enable_bzlmod is on. - -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -[`--[no]keep_going`](#fetch-flag--keep_going) \[`-k`\] default: "false" -Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. - -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -[`--loading_phase_threads`](#fetch-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. - -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -<!-- --> - -[`--[no]incompatible_config_setting_private_default_visibility`](#fetch-flag--incompatible_config_setting_private_default_visibility) default: "false" -If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. - -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -[`--[no]incompatible_enforce_config_setting_visibility`](#fetch-flag--incompatible_enforce_config_setting_visibility) default: "true" -If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. - -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -<!-- --> - -[`--[no]configure`](#fetch-flag--configure) default: "false" -Only fetches repositories marked as 'configure' for system-configuration purpose. Only works when --enable_bzlmod is on. - -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -[`--[no]force`](#fetch-flag--force) default: "false" -Ignore existing repository if any and force fetch the repository again. Only works when --enable_bzlmod is on. +Options that control build execution: -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--[no]all` default: "false" +: Fetches all external repositories necessary for building any target or repository. This is the default if no other flags and arguments are provided. Only works when --enable\_bzlmod is on. -[`--repo`](#fetch-flag--repo)`=<a string>` multiple uses are accumulated -Only fetches the specified repository, which can be either {@apparent_repo_name} or {@@canonical_repo_name}. Only works when --enable_bzlmod is on. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--[no]keep_going` [`-k`] default: "false" +: Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. -<!-- --> + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--deleted_packages`](#fetch-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated -A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. -[`--[no]fetch`](#fetch-flag--fetch) default: "true" -Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--package_path`](#fetch-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" -A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -[`--[no]show_loading_progress`](#fetch-flag--show_loading_progress) default: "true" -If enabled, causes Bazel to print "Loading package:" messages. +`--[no]incompatible_config_setting_private_default_visibility` default: "false" +: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. -<!-- --> + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" -Enable persistent aar extractor by using workers. +`--[no]incompatible_enforce_config_setting_visibility` default: "true" +: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" -Whether to make source manifest actions remotable +Options relating to Bzlmod output and semantics: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]configure` default: "false" +: Only fetches repositories marked as 'configure' for system-configuration purpose. Only works when --enable\_bzlmod is on. -[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" -If true, then Bazel will run coverage postprocessing for test in a new spawn. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]force` default: "false" +: Ignore existing repository if any and force fetch the repository again. Only works when --enable\_bzlmod is on. -[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" -If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--repo=<a string>` multiple uses are accumulated +: Only fetches the specified repository, which can be either \{@apparent\_repo\_name\} or \{@@canonical\_repo\_name\}. Only works when --enable\_bzlmod is on. -[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" -When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +Miscellaneous options, not otherwise categorized.: -[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated +: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. + Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. -Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". +`--[no]fetch` default: "true" +: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. -Examples: -'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. +`--package_path=<colon-separated list of options>` default: "%workspace%" +: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]show_loading_progress` default: "true" +: If enabled, causes Bazel to print "Loading package:" messages. -[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -Enable persistent Android dex and desugar actions by using workers. +Options that control build execution: -Expands to: -  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) -  [`--strategy=Desugar=worker`](#flag--strategy) -  [`--strategy=DexBuilder=worker`](#flag--strategy) +`--[no]experimental_persistent_aar_extractor` default: "false" +: Enable persistent aar extractor by using workers. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -Enable persistent Android resource processor by using workers. +`--[no]experimental_remotable_source_manifests` default: "false" +: Whether to make source manifest actions remotable -Expands to: -  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) -  [`--strategy=AaptPackage=worker`](#flag--strategy) -  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) -  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) -  [`--strategy=RClassGenerator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) -  [`--strategy=AndroidAapt2=worker`](#flag--strategy) -  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) -  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) -  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) -  [`--strategy=ManifestMerger=worker`](#flag--strategy) -  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) -  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) -  [`--strategy=AARGenerator=worker`](#flag--strategy) -  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) -  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--[no]experimental_split_coverage_postprocessing` default: "false" +: If true, then Bazel will run coverage postprocessing for test in a new spawn. -[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) -Enable persistent multiplexed Android dex and desugar actions by using workers. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Expands to: -  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) +`--[no]experimental_strict_fileset_output` default: "false" +: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -Enable persistent multiplexed Android resource processor by using workers. +`--[no]incompatible_modify_execution_info_additive` default: "true" +: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. -Expands to: -  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + + Syntax: "regex=[+-]key,regex=[+-]key,...". + + Examples: + '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. + 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. + '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` +: Enable persistent Android dex and desugar actions by using workers. + + Expands to: + +   `--internal_persistent_android_dex_desugar` + +   `--strategy=Desugar=worker` + +   `--strategy=DexBuilder=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` +: Enable persistent Android resource processor by using workers. + + Expands to: + +   `--internal_persistent_busybox_tools` + +   `--strategy=AaptPackage=worker` + +   `--strategy=AndroidResourceParser=worker` + +   `--strategy=AndroidResourceValidator=worker` + +   `--strategy=AndroidResourceCompiler=worker` + +   `--strategy=RClassGenerator=worker` + +   `--strategy=AndroidResourceLink=worker` + +   `--strategy=AndroidAapt2=worker` + +   `--strategy=AndroidAssetMerger=worker` + +   `--strategy=AndroidResourceMerger=worker` + +   `--strategy=AndroidCompiledResourceMerger=worker` + +   `--strategy=ManifestMerger=worker` + +   `--strategy=AndroidManifestMerger=worker` + +   `--strategy=Aapt2Optimize=worker` + +   `--strategy=AARGenerator=worker` + +   `--strategy=ProcessDatabinding=worker` + +   `--strategy=GenerateDataBindingBaseClasses=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` +: Enable persistent multiplexed Android dex and desugar actions by using workers. + + Expands to: + +   `--persistent_android_dex_desugar` + +   `--internal_persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` +: Enable persistent multiplexed Android resource processor by using workers. + + Expands to: + +   `--persistent_android_resource_processor` + +   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` +: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + + Expands to: + +   `--internal_persistent_multiplex_busybox_tools` + +   `--persistent_multiplex_android_resource_processor` + +   `--persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" +: If true, use the target platform for running tests rather than the test exec group. + + Tags: + [`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: + +`--android_compiler=<a string>` default: see description +: The Android target compiler. + + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" +: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) -Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). +`--android_platforms=<a build target label>` default: "" +: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. -Expands to: -  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) -  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--cc_output_directory_tag=<a string>` default: "" +: Specifies a suffix to be added to the configuration directory. -[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" -If true, use the target platform for running tests rather than the test exec group. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--compiler=<a string>` default: see description +: The C++ compiler to use for compiling the target. -<!-- --> + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description -The Android target compiler. +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" +: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" -Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" +: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" -Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" +: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" -Specifies a suffix to be added to the configuration directory. +`--custom_malloc=<a build target label>` default: see description +: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--compiler`](#flag--compiler)`=<a string>` default: see description -The C++ compiler to use for compiling the target. +`--[no]experimental_include_xcode_execution_requirements` default: "false" +: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" -Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. +`--[no]experimental_prefer_mutual_xcode` default: "true" +: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" -Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. +`--extra_execution_platforms=<comma-separated list of options>` default: "" +: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" -Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated +: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description -Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. +`--grte_top=<a label>` default: see description +: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" -If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. +`--host_compiler=<a string>` default: see description +: No-op flag. Will be removed in a future release. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" -If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. +`--host_grte_top=<a label>` default: see description +: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" -The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" +: The label of a platform rule that describes the host system. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated -The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). +`--[no]incompatible_bazel_test_exec_run_under` default: "true" +: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--grte_top`](#flag--grte_top)`=<a label>` default: see description -A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. +`--[no]incompatible_builtin_objc_strip_action` default: "true" +: Whether to emit a strip action as part of objc linking. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description -No-op flag. Will be removed in a future release. +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" +: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description -If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" +: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" -The label of a platform rule that describes the host system. +`--[no]incompatible_remove_legacy_whole_archive` default: "true" +: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" -If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. +`--[no]incompatible_strip_executable_safely` default: "false" +: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" -Whether to emit a strip action as part of objc linking. +`--[no]interface_shared_objects` default: "true" +: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" -If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" -Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" -If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). +`--minimum_os_version=<a string>` default: see description +: The minimum OS version which your compilation targets. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" -If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. +`--platform_mappings=<a main workspace-relative path>` default: "" +: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" -Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. +`--platforms=<a build target label>` default: "" +: The labels of the platform rules describing the target platforms for the current command. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. +`--python_path=<a string>` default: see description +: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description -The minimum OS version which your compilation targets. +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" -The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--platforms`](#flag--platforms)`=<a build target label>` default: "" -The labels of the platform rules describing the target platforms for the current command. +`--xcode_version=<a string>` default: see description +: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--python_path`](#flag--python_path)`=<a string>` default: see description -The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" +: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. +Options that control the output of the command: -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]apple_generate_dsym` default: "false" +: Whether to generate debug symbol(.dSYM) file(s). -[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" -Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]build_runfile_links` default: "true" +: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. -[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]build_runfile_manifests` default: "true" +: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. -[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description -If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]build_test_dwp` default: "false" +: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. -[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" -The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" +: Sets the suffixes of header files that a cc\_proto\_library creates. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" -Whether to generate debug symbol(.dSYM) file(s). +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" +: Sets the suffixes of source files that a cc\_proto\_library creates. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" -If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" +: Run extra actions for alternative Java api versions in a proto\_library. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" -If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. +`--[no]experimental_save_feature_state` default: "false" +: Save the state of enabled and requested feautres as an output of compilation. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" -If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. +`--fission=<a set of compilation modes>` default: "no" +: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" -Sets the suffixes of header files that a cc_proto_library creates. +`--[no]incompatible_always_include_files_in_data` default: "true" +: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" -Sets the suffixes of source files that a cc_proto_library creates. +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" +: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" -Run extra actions for alternative Java api versions in a proto_library. +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" +: List of flags for which the use in select() is disabled. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" -Save the state of enabled and requested feautres as an output of compilation. +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" +: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" -Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. +`--[no]objc_generate_linkmap` default: "false" +: Specifies whether to generate a linkmap file. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" -If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). +`--[no]save_temps` default: "false" +: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" -If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case + the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + \<br\> + Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. -[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" -List of flags for which the use in select() is disabled. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--allowed_cpu_values=<comma-separated set of options>` default: "" +: Allowed values for the --cpu flag. -[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" -If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]android_databinding_use_androidx` default: "true" +: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. -[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" -Specifies whether to generate a linkmap file. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]android_databinding_use_v3_4_args` default: "true" +: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. -[`--[no]save_temps`](#flag--save_temps) default: "false" -If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--android_dynamic_mode=<off, default or fully>` default: "off" +: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case -the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -\<br\> -Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) -[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" -Allowed values for the --cpu flag. +`--[no]android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" -Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. +`--[no]build_python_zip` default: "auto" +: Build python executable zip; on on Windows, off on other platforms -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" -Use android databinding v2 with 3.4.0 argument. This flag is a no-op. +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple Catalyst binaries. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" -Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. +`--[no]collect_code_coverage` default: "false" +: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. +`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" +: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. +`--conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C source files. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" -Build python executable zip; on on Windows, off on other platforms +`--copt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple Catalyst binaries. +`--cpu=<a string>` default: "" +: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" -If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. +`--cs_fdo_absolute_path=<a string>` default: see description +: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" -Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. +`--cs_fdo_instrument=<a string>` default: see description +: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C source files. +`--cs_fdo_profile=<a build target label>` default: see description +: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc. +`--cxxopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C++ source files. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--cpu`](#flag--cpu)`=<a string>` default: "" -Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. +`--define=<a 'name=value' assignment>` multiple uses are accumulated +: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description -Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. +`--dynamic_mode=<off, default or fully>` default: "default" +: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description -Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. +`--[no]enable_propeller_optimize_absolute_paths` default: "true" +: If set, any use of absolute paths for propeller optimize will raise an error. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description -The cs_fdo_profile representing the context sensitive profile to be used for optimization. +`--[no]enable_remaining_fdo_absolute_paths` default: "true" +: If set, any use of absolute paths for FDO will raise an error. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C++ source files. +`--[no]enable_runfiles` default: "auto" +: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated -Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" -Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. +`--experimental_action_listener=<a build target label>` multiple uses are accumulated +: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" -If set, any use of absolute paths for propeller optimize will raise an error. +`--[no]experimental_android_compress_java_resources` default: "false" +: Compress Java resources in APKs -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" -If set, any use of absolute paths for FDO will raise an error. +`--[no]experimental_android_databinding_v2` default: "true" +: Use android databinding v2. This flag is a no-op. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" -Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. +`--[no]experimental_android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" +: use rex tool to rewrite dex files -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated -Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" +: If specified, Bazel will also generate collect coverage information for generated files. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" -Compress Java resources in APKs +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +: Uses these strings as objc fastbuild compiler options. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" -Use android databinding v2. This flag is a no-op. +`--[no]experimental_omitfp` default: "false" +: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. +`--experimental_output_paths=<off or strip>` default: "off" +: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" -use rex tool to rewrite dex files +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated +: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" -If specified, Bazel will also generate collect coverage information for generated files. +`--[no]experimental_platform_in_output_dir` default: "false" +: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -Uses these strings as objc fastbuild compiler options. +`--[no]experimental_py_binaries_include_label` default: "false" +: py\_binary targets include their label even when stamping is disabled. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" -If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. +`--[no]experimental_use_llvm_covmap` default: "false" +: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" -Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" +: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated -Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. +`--fdo_instrument=<a string>` default: see description +: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" -If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. +`--fdo_optimize=<a string>` default: see description +: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" -py_binary targets include their label even when stamping is disabled. +`--fdo_prefetch_hints=<a build target label>` default: see description +: Use cache prefetch hints. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" -If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. +`--fdo_profile=<a build target label>` default: see description +: The fdo\_profile representing the profile to be used for optimization. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" -Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. +`--features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description -Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. +`--[no]force_pic` default: "false" +: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description -Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description -Use cache prefetch hints. +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" +: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description -The fdo_profile representing the profile to be used for optimization. +`--host_conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--features`](#flag--features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features +`--host_copt=<a string>` multiple uses are accumulated +: Additional options to pass to the C compiler for tools built in the exec configurations. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]force_pic`](#flag--force_pic) default: "false" -If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). +`--host_cpu=<a string>` default: "" +: The host CPU. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +`--host_cxxopt=<a string>` multiple uses are accumulated +: Additional options to pass to C++ compiler for tools built in the exec configurations. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" -Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. +`--host_features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. +`--host_linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to linker when linking tools in the exec configurations. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated -Additional options to pass to the C compiler for tools built in the exec configurations. +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" -The host CPU. +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated -Additional options to pass to C++ compiler for tools built in the exec configurations. +`--[no]incompatible_auto_exec_groups` default: "false" +: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. +`--[no]incompatible_merge_genfiles_directory` default: "true" +: If true, the genfiles directory is folded into the bin directory. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to linker when linking tools in the exec configurations. +`--[no]incompatible_target_cpu_from_platform` default: "true" +: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. +`--[no]instrument_test_targets` default: "false" +: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" +: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" -When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" -If true, the genfiles directory is folded into the bin directory. +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" -If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. +`--[no]legacy_whole_archive` default: "true" +: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) -[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" -When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. +`--linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when linking. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" -When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. +`--ltobackendopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO backend step (under --features=thin\_lto). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. +`--ltoindexopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO indexing step (under --features=thin\_lto). -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple macOS binaries. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" -Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when linking. +`--memprof_profile=<a build target label>` default: see description +: Use memprof profile. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO backend step (under --features=thin_lto). +`--[no]objc_debug_with_GLIBCXX` default: "false" +: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO indexing step (under --features=thin_lto). +`--[no]objc_enable_binary_stripping` default: "false" +: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple macOS binaries. +`--objccopt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc when compiling Objective-C/C++ source files. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description -Use memprof profile. +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" -If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. +`--platform_suffix=<a string>` default: see description +: Specifies a suffix to be added to the configuration directory. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" -Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. +`--propeller_optimize=<a build target label>` default: see description +: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc when compiling Objective-C/C++ source files. +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description +: Absolute path name of cc\_profile file for Propeller Optimized builds. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description +: Absolute path name of ld\_profile file for Propeller Optimized builds. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. +`--run_under=<a prefix in front of command>` default: see description +: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description -Specifies a suffix to be added to the configuration directory. +`--[no]share_native_deps` default: "true" +: If true, native libraries that contain identical functionality will be shared among different targets -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description -Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile +`--[no]stamp` default: "false" +: Stamp binaries with the date, username, hostname, workspace information, etc. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description -Absolute path name of cc_profile file for Propeller Optimized builds. +`--strip=<always, sometimes or never>` default: "sometimes" +: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description -Absolute path name of ld_profile file for Propeller Optimized builds. +`--stripopt=<a string>` multiple uses are accumulated +: Additional options to pass to strip when generating a '\<name\>.stripped' binary. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description -Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple tvOS binaries. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" -If true, native libraries that contain identical functionality will be shared among different targets +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]stamp`](#flag--stamp) default: "false" -Stamp binaries with the date, username, hostname, workspace information, etc. +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple visionOS binaries. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" -Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple watchOS binaries. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated -Additional options to pass to strip when generating a '\<name\>.stripped' binary. +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple tvOS binaries. +`--xbinary_fdo=<a build target label>` default: see description +: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]check_visibility` default: "true" +: If disabled, visibility errors in target dependencies are demoted to warnings. -[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple visionOS binaries. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]desugar_for_android` default: "true" +: Whether to desugar Java 8 bytecode before dexing. -[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple watchOS binaries. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]desugar_java8_libs` default: "false" +: Whether to include supported Java 8 libraries in apps for legacy devices. -[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]enforce_constraints` default: "true" +: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments -[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description -Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[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]check_visibility`](#flag--check_visibility) default: "true" -If disabled, visibility errors in target dependencies are demoted to warnings. +`--[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. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" -Whether to desugar Java 8 bytecode before dexing. +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" +: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" -Whether to include supported Java 8 libraries in apps for legacy devices. +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" +: If true, checks that a Java target explicitly declares all directly used targets as dependencies. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" -Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments +`--[no]incompatible_check_testonly_for_output_files` default: "false" +: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_check_desugar_deps`](#flag--experimental_check_desugar_deps) default: "true" -Whether to double-check correct desugaring at Android binary level. +`--[no]incompatible_disable_native_android_rules` default: "false" +: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_enforce_transitive_visibility`](#flag--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. +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" +: No-op. Kept here for backwards compatibility. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" -When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. +`--[no]one_version_enforcement_on_java_tests` default: "true" +: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" -If true, checks that a Java target explicitly declares all directly used targets as dependencies. +`--python_native_rules_allowlist=<a build target label>` default: see description +: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" -If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. +`--[no]strict_filesets` default: "false" +: If this option is enabled, filesets crossing package boundaries are reported as errors. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" -If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" +: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" -No-op. Kept here for backwards compatibility. +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" +: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" -When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. +`--[no]strict_system_includes` default: "false" +: If true, headers found through system include paths (-isystem) are also required to be declared. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description -An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. +`--target_environment=<a build target label>` multiple uses are accumulated +: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" -If this option is enabled, filesets crossing package boundaries are reported as errors. +Options that affect the signing outputs of a build: -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" +: Implementation to use to sign APKs -[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" -Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]device_debug_entitlements` default: "true" +: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. -[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" -Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--ios_signing_cert_name=<a string>` default: see description +: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). -[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" -If true, headers found through system include paths (-isystem) are also required to be declared. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated -Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" +: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +`--[no]incompatible_objc_alwayslink_by_default` default: "false" +: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. -[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" -Implementation to use to sign APKs + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_python_disallow_native_rules` default: "false" +: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. -[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" -If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +Options that govern the behavior of the test environment or test runner: -[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description -Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). +`--[no]allow_analysis_failures` default: "false" +: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -<!-- --> +`--analysis_testing_deps_limit=<an integer>` default: "2000" +: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. -[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" -If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" +: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. -[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" -If true, make the default value true for alwayslink attributes in objc_library and objc_import. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. -[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" -When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. +`--[no]experimental_android_use_parallel_dex2oat` default: "false" +: Use dex2oat in parallel to possibly speed up android\_test. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) -<!-- --> +`--[no]ios_memleaks` default: "false" +: Enable checking for memory leaks in ios\_test targets. -[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" -If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--ios_simulator_device=<a string>` default: see description +: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. -[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" -Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. -[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" -If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. -[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. -[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" -Use dex2oat in parallel to possibly speed up android_test. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" +: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. -[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" -Enable checking for memory leaks in ios_test targets. +`--[no]zip_undeclared_test_outputs` default: "false" +: If true, undeclared test outputs will be archived in a zip file. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description -The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. +Options that trigger optimizations of the build time: -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" +: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. -[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--[no]experimental_inmemory_dotd_files` default: "true" +: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. -[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. +`--[no]experimental_inmemory_jdeps_files` default: "true" +: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" -Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" +: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. -[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" -If true, undeclared test outputs will be archived in a zip file. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" +: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. -<!-- --> + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" -Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. +`--[no]incremental_dexing` default: "true" +: Does most of the work for dexing separately for each Jar file. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" -If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. +`--[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. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" -If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. +`--[no]process_headers_in_dependencies` default: "false" +: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" -When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. +`--[no]trim_test_configuration` default: "true" +: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" -Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. +Options that affect the verbosity, format or location of logging: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. -[`--[no]incremental_dexing`](#flag--incremental_dexing) default: "true" -Does most of the work for dexing separately for each Jar file. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]verbose_visibility_errors` default: "false" +: If enabled, visibility errors include additional diagnostic information. -[`--[no]objc_use_dotd_pruning`](#flag--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. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" -When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated +: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" -When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. +`--[no]incompatible_default_to_explicit_init_py` default: "false" +: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +Miscellaneous options, not otherwise categorized.: -[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. +`--[no]cache_test_results` [`-t`] default: "auto" +: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]experimental_cancel_concurrent_tests` default: "never" +: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. -[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" -If enabled, visibility errors include additional diagnostic information. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]experimental_fetch_all_coverage_outputs` default: "false" +: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated -Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. +`--[no]experimental_generate_llvm_lcov` default: "false" +: If true, coverage for clang will generate an LCOV report. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" -This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +: Enables reduced classpaths for Java compilations. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]experimental_run_android_lint_on_java_rules` default: "false" +: Whether to validate java\_\* sources. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" -If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. +`--[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. -[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" -If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. +`--host_java_launcher=<a build target label>` default: see description +: The Java launcher used by tools that are executed during a build. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--host_javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac when building tools that are executed during a build. -[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" -If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. +`--host_jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]incompatible_check_sharding_support` default: "true" +: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. -[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" -If true, coverage for clang will generate an LCOV report. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]incompatible_exclusive_test_sandboxed` default: "true" +: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally -[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -Enables reduced classpaths for Java compilations. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" -Whether to validate java\_\* sources. +`--[no]incompatible_strict_action_env` default: "false" +: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]explicit_java_test_deps`](#flag--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. +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. -[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description -The Java launcher used by tools that are executed during a build. +`--java_debug` +: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. -[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac when building tools that are executed during a build. + Expands to: + +   `--test_arg=--wrapper_script_flag=--debug` + +   `--test_output=streamed` + +   `--test_strategy=exclusive` + +   `--test_timeout=9999` + +   `--nocache_test_results` -[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. +`--[no]java_deps` default: "true" +: Generate dependency information (for now, compile-time classpath) per Java target. -[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" -If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. +`--[no]java_header_compilation` default: "true" +: Compile ijars directly from source. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--java_language_version=<a string>` default: "" +: The Java language version -[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" -If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally +`--java_launcher=<a build target label>` default: see description +: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--java_runtime_version=<a string>` default: "local\_jdk" +: The Java runtime version -[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" -If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. +`--javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. -[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated -Additional options to pass to the J2ObjC tool. +`--legacy_main_dex_list_generator=<a build target label>` default: see description +: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. -[`--java_debug`](#flag--java_debug) -Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. +`--optimizing_dexer=<a build target label>` default: see description +: Specifies a binary to use to do dexing without sharding. -Expands to: -  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) -  [`--test_output=streamed`](#flag--test_output) -  [`--test_strategy=exclusive`](#flag--test_strategy) -  [`--test_timeout=9999`](#flag--test_timeout) -  [`--nocache_test_results`](#flag--nocache_test_results) +`--plugin=<a build target label>` multiple uses are accumulated +: Plugins to use in the build. Currently works with java\_plugin. -[`--[no]java_deps`](#flag--java_deps) default: "true" -Generate dependency information (for now, compile-time classpath) per Java target. +`--proguard_top=<a build target label>` default: see description +: Specifies which version of ProGuard to use for code removal when building a Java binary. -[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" -Compile ijars directly from source. +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" +: The label of the proto-compiler. -[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" -The Java language version + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description -The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. +`--[no]proto_profile` default: "true" +: Whether to pass profile\_path to the proto compiler. -[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" -The Java runtime version + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac. +`--proto_profile_path=<a build target label>` default: see description +: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. -[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description -Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile C++ protos -[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description -Specifies a binary to use to do dexing without sharding. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated -Plugins to use in the build. Currently works with java_plugin. +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos -[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description -Specifies which version of ProGuard to use for code removal when building a Java binary. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" -The label of the proto-compiler. +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile Java protos -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]proto_profile`](#flag--proto_profile) default: "true" -Whether to pass profile_path to the proto compiler. +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description -The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. +`--protocopt=<a string>` multiple uses are accumulated +: Additional options to pass to the protobuf compiler. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" -Label of proto_lang_toolchain() which describes how to compile C++ protos +`--[no]runs_per_test_detects_flakes` default: "false" +: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--shell_executable=<a path>` default: see description +: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. -[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" -Label of proto_lang_toolchain() which describes how to compile j2objc protos + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--test_arg=<a string>` multiple uses are accumulated +: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. -[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" -Label of proto_lang_toolchain() which describes how to compile Java protos +`--test_filter=<a string>` default: see description +: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--test_result_expiration=<an integer>` default: "-1" +: This option is deprecated and has no effect. -[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" -Label of proto_lang_toolchain() which describes how to compile JavaLite protos +`--[no]test_runner_fail_fast` default: "false" +: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. -[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the protobuf compiler. +`--tool_java_language_version=<a string>` default: "" +: The Java language version used to execute the tools that are needed during a build -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" +: The Java runtime version used to execute tools during the build -[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" -If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. +`--[no]use_ijars` default: "true" +: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. -[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description -Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. +## Help Options -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +Options that affect the verbosity, format or location of logging: -[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated -Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. +`--help_verbosity=<long, medium or short>` default: "medium" +: Select the verbosity of the help command. -[`--test_filter`](#flag--test_filter)`=<a string>` default: see description -Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" -This option is deprecated and has no effect. +`--long` [`-l`] +: Show full description of each option, instead of just its name. -[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" -Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + Expands to: + +   `--help_verbosity=long` -[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" -The Java language version used to execute the tools that are needed during a build +`--short` +: Show only the names of the options, not their types or meanings. -[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" -The Java runtime version used to execute tools during the build + Expands to: + +   `--help_verbosity=short` -[`--[no]use_ijars`](#flag--use_ijars) default: "true" -If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -## <span id="help">Help Options</span> +## Info Options -[`--help_verbosity`](#help-flag--help_verbosity)`=<long, medium or short>` default: "medium" -Select the verbosity of the help command. +Inherits all options from [build](#build). -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -[`--long`](#help-flag--long) \[`-l`\] -Show full description of each option, instead of just its name. +`--info_output_type=<stdout or response_proto>` default: "stdout" +: If stdout, results are directly printed to the console. If response\_proto, the info command results are packed in response extensions. -Expands to: -  [`--help_verbosity=long`](#flag--help_verbosity) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +Options that affect the verbosity, format or location of logging: -[`--short`](#help-flag--short) -Show only the names of the options, not their types or meanings. +`--[no]show_make_env` default: "false" +: Include the "Make" environment in the output. -Expands to: -  [`--help_verbosity=short`](#flag--help_verbosity) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +## License Options -## <span id="info">Info Options</span> +## Mobile-install Options Inherits all options from [build](#build). -[`--info_output_type`](#info-flag--info_output_type)`=<stdout or response_proto>` default: "stdout" -If stdout, results are directly printed to the console. If response_proto, the info command results are packed in response extensions. - -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -<!-- --> - -[`--[no]show_make_env`](#info-flag--show_make_env) default: "false" -Include the "Make" environment in the output. +Options that control build execution: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -## <span id="license">License Options</span> - -## <span id="mobile-install">Mobile-install Options</span> - -Inherits all options from [build](#build). +`--mode=<classic, classic_internal_test_do_not_use or skylark>` default: "skylark" +: Deprecated no-effect flag. Only skylark mode is still supported. -[`--mode`](#mobile-install-flag--mode)`=<classic, classic_internal_test_do_not_use or skylark>` default: "skylark" -Deprecated no-effect flag. Only skylark mode is still supported. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +Options that configure the toolchain used for action execution: -<!-- --> +`--adb=<a string>` default: "" +: adb binary to use for the 'mobile-install' command. If unspecified, the one in the Android SDK specified by the --android\_sdk\_channel command line option (or the default SDK if --android\_sdk\_channel is not specified) is used. -[`--adb`](#mobile-install-flag--adb)`=<a string>` default: "" -adb binary to use for the 'mobile-install' command. If unspecified, the one in the Android SDK specified by the --android_sdk_channel command line option (or the default SDK if --android_sdk_channel is not specified) is used. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +Options that control the output of the command: -<!-- --> +`--[no]incremental` default: "false" +: Whether to do an incremental install. If true, try to avoid unnecessary additional work by reading the state of the device the code is to be installed on and using that information to avoid unnecessary work. If false (the default), always do a full install. -[`--[no]incremental`](#mobile-install-flag--incremental) default: "false" -Whether to do an incremental install. If true, try to avoid unnecessary additional work by reading the state of the device the code is to be installed on and using that information to avoid unnecessary work. If false (the default), always do a full install. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]split_apks` default: "false" +: Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later -[`--[no]split_apks`](#mobile-install-flag--split_apks) default: "false" -Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<!-- --> +`--adb_arg=<a string>` multiple uses are accumulated +: Extra arguments to pass to adb. Usually used to designate a device to install to. -[`--adb_arg`](#mobile-install-flag--adb_arg)`=<a string>` multiple uses are accumulated -Extra arguments to pass to adb. Usually used to designate a device to install to. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--debug_app` +: Whether to wait for the debugger before starting the app. -[`--debug_app`](#mobile-install-flag--debug_app) -Whether to wait for the debugger before starting the app. + Expands to: + +   `--start=DEBUG` -Expands to: -  [`--start=DEBUG`](#flag--start) + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--device=<a string>` default: "" +: The adb device serial number. If not specified, the first device will be used. -[`--device`](#mobile-install-flag--device)`=<a string>` default: "" -The adb device serial number. If not specified, the first device will be used. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--start=<no, cold, warm or debug>` default: "NO" +: How the app should be started after installing it. Set to WARM to preserve and restore application state on incremental installs. -[`--start`](#mobile-install-flag--start)`=<no, cold, warm or debug>` default: "NO" -How the app should be started after installing it. Set to WARM to preserve and restore application state on incremental installs. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--start_app` +: Whether to start the app after installing it. -[`--start_app`](#mobile-install-flag--start_app) -Whether to start the app after installing it. + Expands to: + +   `--start=COLD` -Expands to: -  [`--start=COLD`](#flag--start) + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`execution`](#effect_tag_EXECUTION) +Options that affect the verbosity, format or location of logging: -<!-- --> +`--incremental_install_verbosity=<a string>` default: "" +: The verbosity for incremental install. Set to 1 for debug logging. -[`--incremental_install_verbosity`](#mobile-install-flag--incremental_install_verbosity)`=<a string>` default: "" -The verbosity for incremental install. Set to 1 for debug logging. + Tags: + [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) -Tags: -[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) +## Mod Options -## <span id="mod">Mod Options</span> +Options that control build execution: -[`--[no]experimental_remotable_source_manifests`](#mod-flag--experimental_remotable_source_manifests) default: "false" -Whether to make source manifest actions remotable +`--[no]experimental_remotable_source_manifests` default: "false" +: Whether to make source manifest actions remotable -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_strict_fileset_output`](#mod-flag--experimental_strict_fileset_output) default: "false" -If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. +`--[no]experimental_strict_fileset_output` default: "false" +: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_modify_execution_info_additive`](#mod-flag--incompatible_modify_execution_info_additive) default: "true" -When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. +`--[no]incompatible_modify_execution_info_additive` default: "true" +: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--loading_phase_threads`](#mod-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--modify_execution_info`](#mod-flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. -Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + Syntax: "regex=[+-]key,regex=[+-]key,...". -Examples: -'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + Examples: + '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. + 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. + '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]use_target_platform_for_tests`](#mod-flag--use_target_platform_for_tests) default: "false" -If true, use the target platform for running tests rather than the test exec group. +`--[no]use_target_platform_for_tests` default: "false" +: If true, use the target platform for running tests rather than the test exec group. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION) -<!-- --> +Options that configure the toolchain used for action execution: -[`--[no]incompatible_bazel_test_exec_run_under`](#mod-flag--incompatible_bazel_test_exec_run_under) default: "true" -If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. +`--[no]incompatible_bazel_test_exec_run_under` default: "true" +: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +Options that control the output of the command: -[`--[no]build_runfile_links`](#mod-flag--build_runfile_links) default: "true" -If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. +`--[no]build_runfile_links` default: "true" +: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]build_runfile_manifests`](#mod-flag--build_runfile_manifests) default: "true" -If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. +`--[no]build_runfile_manifests` default: "true" +: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_always_include_files_in_data`](#mod-flag--incompatible_always_include_files_in_data) default: "true" -If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). +`--[no]incompatible_always_include_files_in_data` default: "true" +: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_compact_repo_mapping_manifest`](#mod-flag--incompatible_compact_repo_mapping_manifest) default: "false" -If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" +: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--incompatible_disable_select_on`](#mod-flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" -List of flags for which the use in select() is disabled. +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" +: List of flags for which the use in select() is disabled. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]incompatible_filegroup_runfiles_for_data`](#mod-flag--incompatible_filegroup_runfiles_for_data) default: "true" -If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" +: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -[`--action_env`](#mod-flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case -the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -\<br\> -Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case + the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + \<br\> + Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--allowed_cpu_values`](#mod-flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" -Allowed values for the --cpu flag. +`--allowed_cpu_values=<comma-separated set of options>` default: "" +: Allowed values for the --cpu flag. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]collect_code_coverage`](#mod-flag--collect_code_coverage) default: "false" -If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. +`--[no]collect_code_coverage` default: "false" +: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--compilation_mode`](#mod-flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" -Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. +`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" +: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--cpu`](#mod-flag--cpu)`=<a string>` default: "" -Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. +`--cpu=<a string>` default: "" +: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--define`](#mod-flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated -Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. +`--define=<a 'name=value' assignment>` multiple uses are accumulated +: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]enable_runfiles`](#mod-flag--enable_runfiles) default: "auto" -Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. +`--[no]enable_runfiles` default: "auto" +: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--exec_aspects`](#mod-flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--experimental_action_listener`](#mod-flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated -Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. +`--experimental_action_listener=<a build target label>` multiple uses are accumulated +: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_collect_code_coverage_for_generated_files`](#mod-flag--experimental_collect_code_coverage_for_generated_files) default: "false" -If specified, Bazel will also generate collect coverage information for generated files. +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" +: If specified, Bazel will also generate collect coverage information for generated files. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--experimental_output_paths`](#mod-flag--experimental_output_paths)`=<off or strip>` default: "off" -Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. +`--experimental_output_paths=<off or strip>` default: "off" +: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) -[`--experimental_override_platform_cpu_name`](#mod-flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated -Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated +: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_platform_in_output_dir`](#mod-flag--experimental_platform_in_output_dir) default: "false" -If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. +`--[no]experimental_platform_in_output_dir` default: "false" +: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#mod-flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" -Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" +: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--features`](#mod-flag--features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features +`--features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_action_env`](#mod-flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--host_compilation_mode`](#mod-flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" -Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" +: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--host_cpu`](#mod-flag--host_cpu)`=<a string>` default: "" -The host CPU. +`--host_cpu=<a string>` default: "" +: The host CPU. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--host_features`](#mod-flag--host_features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. +`--host_features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_auto_exec_groups`](#mod-flag--incompatible_auto_exec_groups) default: "false" -When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. +`--[no]incompatible_auto_exec_groups` default: "false" +: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_merge_genfiles_directory`](#mod-flag--incompatible_merge_genfiles_directory) default: "true" -If true, the genfiles directory is folded into the bin directory. +`--[no]incompatible_merge_genfiles_directory` default: "true" +: If true, the genfiles directory is folded into the bin directory. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_target_cpu_from_platform`](#mod-flag--incompatible_target_cpu_from_platform) default: "true" -If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. +`--[no]incompatible_target_cpu_from_platform` default: "true" +: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]instrument_test_targets`](#mod-flag--instrument_test_targets) default: "false" -When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. +`--[no]instrument_test_targets` default: "false" +: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--instrumentation_filter`](#mod-flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" -When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" +: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--platform_suffix`](#mod-flag--platform_suffix)`=<a string>` default: see description -Specifies a suffix to be added to the configuration directory. +`--platform_suffix=<a string>` default: see description +: Specifies a suffix to be added to the configuration directory. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--run_under`](#mod-flag--run_under)`=<a prefix in front of command>` default: see description -Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. +`--run_under=<a prefix in front of command>` default: see description +: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]stamp`](#mod-flag--stamp) default: "false" -Stamp binaries with the date, username, hostname, workspace information, etc. +`--[no]stamp` default: "false" +: Stamp binaries with the date, username, hostname, workspace information, etc. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -<!-- --> +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -[`--[no]check_visibility`](#mod-flag--check_visibility) default: "true" -If disabled, visibility errors in target dependencies are demoted to warnings. +`--[no]check_visibility` default: "true" +: If disabled, visibility errors in target dependencies are demoted to warnings. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -[`--[no]enforce_constraints`](#mod-flag--enforce_constraints) default: "true" -Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments +`--[no]enforce_constraints` default: "true" +: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--[no]experimental_enforce_transitive_visibility`](#mod-flag--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. +`--[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. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_check_testonly_for_output_files`](#mod-flag--incompatible_check_testonly_for_output_files) default: "false" -If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. +`--[no]incompatible_check_testonly_for_output_files` default: "false" +: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]strict_filesets`](#mod-flag--strict_filesets) default: "false" -If this option is enabled, filesets crossing package boundaries are reported as errors. +`--[no]strict_filesets` default: "false" +: If this option is enabled, filesets crossing package boundaries are reported as errors. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--target_environment`](#mod-flag--target_environment)`=<a build target label>` multiple uses are accumulated -Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. +`--target_environment=<a build target label>` multiple uses are accumulated +: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -<!-- --> +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -[`--[no]incompatible_config_setting_private_default_visibility`](#mod-flag--incompatible_config_setting_private_default_visibility) default: "false" -If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. +`--[no]incompatible_config_setting_private_default_visibility` default: "false" +: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]incompatible_enforce_config_setting_visibility`](#mod-flag--incompatible_enforce_config_setting_visibility) default: "true" -If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. +`--[no]incompatible_enforce_config_setting_visibility` default: "true" +: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +Options that govern the behavior of the test environment or test runner: -[`--[no]allow_analysis_failures`](#mod-flag--allow_analysis_failures) default: "false" -If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. +`--[no]allow_analysis_failures` default: "false" +: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--analysis_testing_deps_limit`](#mod-flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" -Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. +`--analysis_testing_deps_limit=<an integer>` default: "2000" +: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -<!-- --> +Options relating to the output and semantics of the `mod` subcommand: -[`--base_module`](#mod-flag--base_module)`=<"<root>" for the root module; <module>@<version> for a specific version of a module; <module> for all versions of a module; @<name> for a repo with the given apparent name; or @@<name> for a repo with the given canonical name>` default: "\<root\>" -Specify a module relative to which the specified target repos will be interpreted. +`--base_module=<"<root>" for the root module; <module>@<version> for a specific version of a module; <module> for all versions of a module; @<name> for a repo with the given apparent name; or @@<name> for a repo with the given canonical name>` default: "<root>" +: Specify a module relative to which the specified target repos will be interpreted. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--charset`](#mod-flag--charset)`=<utf8 or ascii>` default: "utf8" -Chooses the character set to use for the tree. Only affects text output. Valid values are "utf8" or "ascii". Default is "utf8" +`--charset=<utf8 or ascii>` default: "utf8" +: Chooses the character set to use for the tree. Only affects text output. Valid values are "utf8" or "ascii". Default is "utf8" -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]cycles`](#mod-flag--cycles) default: "true" -Points out dependency cycles inside the displayed tree. +`--[no]cycles` default: "true" +: Points out dependency cycles inside the displayed tree. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--depth`](#mod-flag--depth)`=<an integer>` default: "-1" -Maximum display depth of the dependency tree. A depth of 1 displays the direct dependencies, for example. For tree, path and all_paths it defaults to Integer.MAX_VALUE, while for deps and explain it defaults to 1 (only displays direct deps of the root besides the target leaves and their parents). +`--depth=<an integer>` default: "-1" +: Maximum display depth of the dependency tree. A depth of 1 displays the direct dependencies, for example. For tree, path and all\_paths it defaults to Integer.MAX\_VALUE, while for deps and explain it defaults to 1 (only displays direct deps of the root besides the target leaves and their parents). -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--extension_filter`](#mod-flag--extension_filter)`=<a comma-separated list of <extension>s>` default: see description -Only display the usages of these module extensions and the repos generated by them if their respective flags are set. If set, the result graph will only include paths that contain modules using the specified extensions. An empty list disables the filter, effectively specifying all possible extensions. +`--extension_filter=<a comma-separated list of <extension>s>` default: see description +: Only display the usages of these module extensions and the repos generated by them if their respective flags are set. If set, the result graph will only include paths that contain modules using the specified extensions. An empty list disables the filter, effectively specifying all possible extensions. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--extension_info`](#mod-flag--extension_info)`=<hidden, usages, repos or all>` default: "hidden" -Specify how much detail about extension usages to include in the query result. "Usages" will only show the extensions names, "repos" will also include repos imported with use_repo, and "all" will also show the other repositories generated by extensions. +`--extension_info=<hidden, usages, repos or all>` default: "hidden" +: Specify how much detail about extension usages to include in the query result. "Usages" will only show the extensions names, "repos" will also include repos imported with use\_repo, and "all" will also show the other repositories generated by extensions. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--extension_usages`](#mod-flag--extension_usages)`=<a comma-separated list of <module>s>` default: "" -Specify modules whose extension usages will be displayed in the show_extension query. +`--extension_usages=<a comma-separated list of <module>s>` default: "" +: Specify modules whose extension usages will be displayed in the show\_extension query. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--from`](#mod-flag--from)`=<a comma-separated list of <module>s>` default: "\<root\>" -The module(s) starting from which the dependency graph query will be displayed. Check each query’s description for the exact semantics. Defaults to \<root\>. +`--from=<a comma-separated list of <module>s>` default: "<root>" +: The module(s) starting from which the dependency graph query will be displayed. Check each query’s description for the exact semantics. Defaults to \<root\>. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]include_builtin`](#mod-flag--include_builtin) default: "false" -Include built-in modules in the dependency graph. Disabled by default because it is quite noisy. +`--[no]include_builtin` default: "false" +: Include built-in modules in the dependency graph. Disabled by default because it is quite noisy. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]include_unused`](#mod-flag--include_unused) default: "false" -The queries will also take into account and display the unused modules, which are not present in the module resolution graph after selection (due to the Minimal-Version Selection or override rules). This can have different effects for each of the query types i.e. include new paths in the all_paths command, or extra dependants in the explain command. +`--[no]include_unused` default: "false" +: The queries will also take into account and display the unused modules, which are not present in the module resolution graph after selection (due to the Minimal-Version Selection or override rules). This can have different effects for each of the query types i.e. include new paths in the all\_paths command, or extra dependants in the explain command. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--output`](#mod-flag--output)`=<text, json or graph>` default: "text" -The format in which the query results should be printed. Allowed values for query are: text, json, graph +`--output=<text, json or graph>` default: "text" +: The format in which the query results should be printed. Allowed values for query are: text, json, graph -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]verbose`](#mod-flag--verbose) default: "false" -The queries will also display the reason why modules were resolved to their current version (if changed). Defaults to true only for the explain query. +`--[no]verbose` default: "false" +: The queries will also display the reason why modules were resolved to their current version (if changed). Defaults to true only for the explain query. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -<!-- --> +Options that affect the verbosity, format or location of logging: -[`--[no]verbose_visibility_errors`](#mod-flag--verbose_visibility_errors) default: "false" -If enabled, visibility errors include additional diagnostic information. +`--[no]verbose_visibility_errors` default: "false" +: If enabled, visibility errors include additional diagnostic information. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -<!-- --> +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -[`--flag_alias`](#mod-flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated -Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated +: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -<!-- --> +Miscellaneous options, not otherwise categorized.: -[`--deleted_packages`](#mod-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated -A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated +: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. + Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. -[`--[no]fetch`](#mod-flag--fetch) default: "true" -Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. +`--[no]fetch` default: "true" +: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. -[`--package_path`](#mod-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" -A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. +`--package_path=<colon-separated list of options>` default: "%workspace%" +: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. -[`--[no]show_loading_progress`](#mod-flag--show_loading_progress) default: "true" -If enabled, causes Bazel to print "Loading package:" messages. +`--[no]show_loading_progress` default: "true" +: If enabled, causes Bazel to print "Loading package:" messages. -## <span id="print_action">Print_action Options</span> +## Print\_action Options Inherits all options from [build](#build). -[`--print_action_mnemonics`](#print_action-flag--print_action_mnemonics)`=<a string>` multiple uses are accumulated -Lists which mnemonics to filter print_action data by, no filtering takes place when left empty. - -## <span id="query">Query Options</span> - -[`--[no]experimental_remotable_source_manifests`](#query-flag--experimental_remotable_source_manifests) default: "false" -Whether to make source manifest actions remotable - -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -[`--[no]experimental_strict_fileset_output`](#query-flag--experimental_strict_fileset_output) default: "false" -If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. - -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -[`--[no]incompatible_modify_execution_info_additive`](#query-flag--incompatible_modify_execution_info_additive) default: "true" -When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. - -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -[`--[no]keep_going`](#query-flag--keep_going) \[`-k`\] default: "false" -Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. +Miscellaneous options, not otherwise categorized.: -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--print_action_mnemonics=<a string>` multiple uses are accumulated +: Lists which mnemonics to filter print\_action data by, no filtering takes place when left empty. -[`--loading_phase_threads`](#query-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. +## Query Options -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +Options that control build execution: -[`--modify_execution_info`](#query-flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. +`--[no]experimental_remotable_source_manifests` default: "false" +: Whether to make source manifest actions remotable -Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Examples: -'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. +`--[no]experimental_strict_fileset_output` default: "false" +: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]use_target_platform_for_tests`](#query-flag--use_target_platform_for_tests) default: "false" -If true, use the target platform for running tests rather than the test exec group. +`--[no]incompatible_modify_execution_info_additive` default: "true" +: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +`--[no]keep_going` [`-k`] default: "false" +: Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. -[`--[no]incompatible_bazel_test_exec_run_under`](#query-flag--incompatible_bazel_test_exec_run_under) default: "true" -If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. -<!-- --> + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -[`--[no]build_runfile_links`](#query-flag--build_runfile_links) default: "true" -If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Syntax: "regex=[+-]key,regex=[+-]key,...". -[`--[no]build_runfile_manifests`](#query-flag--build_runfile_manifests) default: "true" -If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + Examples: + '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. + 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. + '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]incompatible_always_include_files_in_data`](#query-flag--incompatible_always_include_files_in_data) default: "true" -If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). +`--[no]use_target_platform_for_tests` default: "false" +: If true, use the target platform for running tests rather than the test exec group. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`execution`](#effect_tag_EXECUTION) -[`--[no]incompatible_compact_repo_mapping_manifest`](#query-flag--incompatible_compact_repo_mapping_manifest) default: "false" -If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. +Options that configure the toolchain used for action execution: -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_bazel_test_exec_run_under` default: "true" +: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. -[`--incompatible_disable_select_on`](#query-flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" -List of flags for which the use in select() is disabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +Options that control the output of the command: -[`--[no]incompatible_filegroup_runfiles_for_data`](#query-flag--incompatible_filegroup_runfiles_for_data) default: "true" -If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. +`--[no]build_runfile_links` default: "true" +: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -<!-- --> +`--[no]build_runfile_manifests` default: "true" +: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. -[`--action_env`](#query-flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case -the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -\<br\> -Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]incompatible_always_include_files_in_data` default: "true" +: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). -[`--allowed_cpu_values`](#query-flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" -Allowed values for the --cpu flag. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" +: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. -[`--[no]collect_code_coverage`](#query-flag--collect_code_coverage) default: "false" -If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" +: List of flags for which the use in select() is disabled. -[`--compilation_mode`](#query-flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" -Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" +: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. -[`--cpu`](#query-flag--cpu)`=<a string>` default: "" -Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -[`--define`](#query-flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated -Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case + the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + \<br\> + Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]enable_runfiles`](#query-flag--enable_runfiles) default: "auto" -Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. +`--allowed_cpu_values=<comma-separated set of options>` default: "" +: Allowed values for the --cpu flag. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--exec_aspects`](#query-flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. +`--[no]collect_code_coverage` default: "false" +: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--experimental_action_listener`](#query-flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated -Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. +`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" +: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]experimental_collect_code_coverage_for_generated_files`](#query-flag--experimental_collect_code_coverage_for_generated_files) default: "false" -If specified, Bazel will also generate collect coverage information for generated files. +`--cpu=<a string>` default: "" +: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--experimental_output_paths`](#query-flag--experimental_output_paths)`=<off or strip>` default: "off" -Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. +`--define=<a 'name=value' assignment>` multiple uses are accumulated +: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--experimental_override_platform_cpu_name`](#query-flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated -Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. +`--[no]enable_runfiles` default: "auto" +: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_platform_in_output_dir`](#query-flag--experimental_platform_in_output_dir) default: "false" -If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#query-flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" -Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. +`--experimental_action_listener=<a build target label>` multiple uses are accumulated +: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--features`](#query-flag--features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" +: If specified, Bazel will also generate collect coverage information for generated files. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--host_action_env`](#query-flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +`--experimental_output_paths=<off or strip>` default: "off" +: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) -[`--host_compilation_mode`](#query-flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" -Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated +: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--host_cpu`](#query-flag--host_cpu)`=<a string>` default: "" -The host CPU. +`--[no]experimental_platform_in_output_dir` default: "false" +: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--host_features`](#query-flag--host_features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" +: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]incompatible_auto_exec_groups`](#query-flag--incompatible_auto_exec_groups) default: "false" -When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. +`--features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_merge_genfiles_directory`](#query-flag--incompatible_merge_genfiles_directory) default: "true" -If true, the genfiles directory is folded into the bin directory. +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]incompatible_target_cpu_from_platform`](#query-flag--incompatible_target_cpu_from_platform) default: "true" -If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" +: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -[`--[no]instrument_test_targets`](#query-flag--instrument_test_targets) default: "false" -When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. +`--host_cpu=<a string>` default: "" +: The host CPU. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--instrumentation_filter`](#query-flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" -When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. +`--host_features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--platform_suffix`](#query-flag--platform_suffix)`=<a string>` default: see description -Specifies a suffix to be added to the configuration directory. +`--[no]incompatible_auto_exec_groups` default: "false" +: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--run_under`](#query-flag--run_under)`=<a prefix in front of command>` default: see description -Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. +`--[no]incompatible_merge_genfiles_directory` default: "true" +: If true, the genfiles directory is folded into the bin directory. -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]stamp`](#query-flag--stamp) default: "false" -Stamp binaries with the date, username, hostname, workspace information, etc. +`--[no]incompatible_target_cpu_from_platform` default: "true" +: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -<!-- --> +`--[no]instrument_test_targets` default: "false" +: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. -[`--[no]check_visibility`](#query-flag--check_visibility) default: "true" -If disabled, visibility errors in target dependencies are demoted to warnings. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" +: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. -[`--[no]enforce_constraints`](#query-flag--enforce_constraints) default: "true" -Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) +`--platform_suffix=<a string>` default: see description +: Specifies a suffix to be added to the configuration directory. -[`--[no]experimental_enforce_transitive_visibility`](#query-flag--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. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--run_under=<a prefix in front of command>` default: see description +: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. -[`--[no]incompatible_check_testonly_for_output_files`](#query-flag--incompatible_check_testonly_for_output_files) default: "false" -If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]stamp` default: "false" +: Stamp binaries with the date, username, hostname, workspace information, etc. -[`--[no]strict_filesets`](#query-flag--strict_filesets) default: "false" -If this option is enabled, filesets crossing package boundaries are reported as errors. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -[`--target_environment`](#query-flag--target_environment)`=<a build target label>` multiple uses are accumulated -Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. +`--[no]check_visibility` default: "true" +: If disabled, visibility errors in target dependencies are demoted to warnings. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -<!-- --> +`--[no]enforce_constraints` default: "true" +: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments -[`--[no]incompatible_config_setting_private_default_visibility`](#query-flag--incompatible_config_setting_private_default_visibility) default: "false" -If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[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. -[`--[no]incompatible_enforce_config_setting_visibility`](#query-flag--incompatible_enforce_config_setting_visibility) default: "true" -If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_check_testonly_for_output_files` default: "false" +: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. -<!-- --> + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]allow_analysis_failures`](#query-flag--allow_analysis_failures) default: "false" -If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. +`--[no]strict_filesets` default: "false" +: If this option is enabled, filesets crossing package boundaries are reported as errors. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--analysis_testing_deps_limit`](#query-flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" -Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. +`--target_environment=<a build target label>` multiple uses are accumulated +: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -<!-- --> +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -[`--aspect_deps`](#query-flag--aspect_deps)`=<off, conservative or precise>` default: "conservative" -How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. +`--[no]incompatible_config_setting_private_default_visibility` default: "false" +: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]consistent_labels`](#query-flag--consistent_labels) default: "false" -If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. +`--[no]incompatible_enforce_config_setting_visibility` default: "true" +: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--[no]experimental_explicit_aspects`](#query-flag--experimental_explicit_aspects) default: "false" -aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). +Options that govern the behavior of the test environment or test runner: -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]allow_analysis_failures` default: "false" +: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. -[`--[no]experimental_graphless_query`](#query-flag--experimental_graphless_query) default: "auto" -If true, uses a Query implementation that does not make a copy of the graph. The new implementation only supports --order_output=no, as well as only a subset of output formatters. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--analysis_testing_deps_limit=<an integer>` default: "2000" +: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. -[`--graph:conditional_edges_limit`](#query-flag--graph:conditional_edges_limit)`=<an integer>` default: "4" -The maximum number of condition labels to show. -1 means no truncation and 0 means no annotation. This option is only applicable to --output=graph. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +Options relating to query output and semantics: -[`--[no]graph:factored`](#query-flag--graph:factored) default: "true" -If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. +`--aspect_deps=<off, conservative or precise>` default: "conservative" +: How to resolve aspect dependencies when the output format is one of \{xml,proto,record\}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--graph:node_limit`](#query-flag--graph:node_limit)`=<an integer>` default: "512" -The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. +`--[no]consistent_labels` default: "false" +: If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]implicit_deps`](#query-flag--implicit_deps) default: "true" -If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. +`--[no]experimental_explicit_aspects` default: "false" +: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]include_aspects`](#query-flag--include_aspects) default: "true" -aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). +`--[no]experimental_graphless_query` default: "auto" +: If true, uses a Query implementation that does not make a copy of the graph. The new implementation only supports --order\_output=no, as well as only a subset of output formatters. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -[`--[no]incompatible_lexicographical_output`](#query-flag--incompatible_lexicographical_output) default: "true" -If this option is set, sorts --order_output=auto output in lexicographical order. +`--graph:conditional_edges_limit=<an integer>` default: "4" +: The maximum number of condition labels to show. -1 means no truncation and 0 means no annotation. This option is only applicable to --output=graph. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]incompatible_package_group_includes_double_slash`](#query-flag--incompatible_package_group_includes_double_slash) default: "true" -If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted. +`--[no]graph:factored` default: "true" +: If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]infer_universe_scope`](#query-flag--infer_universe_scope) default: "false" -If set and --universe_scope is unset, then a value of --universe_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). +`--graph:node_limit=<an integer>` default: "512" +: The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]line_terminator_null`](#query-flag--line_terminator_null) default: "false" -Whether each format is terminated with \0 instead of newline. +`--[no]implicit_deps` default: "true" +: If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--[no]nodep_deps`](#query-flag--nodep_deps) default: "true" -If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. +`--[no]include_aspects` default: "true" +: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--noorder_results`](#query-flag--noorder_results) -Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. +`--[no]incompatible_lexicographical_output` default: "true" +: If this option is set, sorts --order\_output=auto output in lexicographical order. -Expands to: -  [`--order_output=no`](#flag--order_output) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]incompatible_package_group_includes_double_slash` default: "true" +: If enabled, when outputting package\_group's `packages` attribute, the leading `//` will not be omitted. -[`--null`](#query-flag--null) -Whether each format is terminated with \0 instead of newline. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Expands to: -  [`--line_terminator_null=true`](#flag--line_terminator_null) +`--[no]infer_universe_scope` default: "false" +: If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -[`--order_output`](#query-flag--order_output)`=<no, deps, auto or full>` default: "auto" -Output the results unordered (no), dependency-ordered (deps), or fully ordered (full). The default is 'auto', meaning that results are output either dependency-ordered or fully ordered, depending on the output formatter (dependency-ordered for proto, minrank, maxrank, and graph, fully ordered for all others). When output is fully ordered, nodes are printed in a fully deterministic (total) order. First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a post-order depth-first search in which outgoing edges to unvisited nodes are traversed in alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order in which they were visited. +`--[no]line_terminator_null` default: "false" +: Whether each format is terminated with \0 instead of newline. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--order_results`](#query-flag--order_results) -Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. +`--[no]nodep_deps` default: "true" +: If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. -Expands to: -  [`--order_output=auto`](#flag--order_output) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--noorder_results` +: Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. -[`--output`](#query-flag--output)`=<a string>` default: "label" -The format in which the query results should be printed. Allowed values for query are: build, graph, streamed_jsonproto, label, label_kind, location, maxrank, minrank, package, proto, streamed_proto, xml. + Expands to: + +   `--order_output=no` -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--output_file`](#query-flag--output_file)`=<a string>` default: "" -When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. +`--null` +: Whether each format is terminated with \0 instead of newline. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Expands to: + +   `--line_terminator_null=true` -[`--[no]proto:default_values`](#query-flag--proto:default_values) default: "true" -If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--order_output=<no, deps, auto or full>` default: "auto" +: Output the results unordered (no), dependency-ordered (deps), or fully ordered (full). The default is 'auto', meaning that results are output either dependency-ordered or fully ordered, depending on the output formatter (dependency-ordered for proto, minrank, maxrank, and graph, fully ordered for all others). When output is fully ordered, nodes are printed in a fully deterministic (total) order. First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a post-order depth-first search in which outgoing edges to unvisited nodes are traversed in alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order in which they were visited. -[`--[no]proto:definition_stack`](#query-flag--proto:definition_stack) default: "false" -Populate the definition_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--order_results` +: Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. -[`--[no]proto:flatten_selects`](#query-flag--proto:flatten_selects) default: "true" -If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + Expands to: + +   `--order_output=auto` -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]proto:include_attribute_source_aspects`](#query-flag--proto:include_attribute_source_aspects) default: "false" -Populate the source_aspect_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). +`--output=<a string>` default: "label" +: The format in which the query results should be printed. Allowed values for query are: build, graph, streamed\_jsonproto, label, label\_kind, location, maxrank, minrank, package, proto, streamed\_proto, xml. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]proto:include_starlark_rule_env`](#query-flag--proto:include_starlark_rule_env) default: "true" -Use the starlark environment in the value of the generated \$internal_attr_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. +`--output_file=<a string>` default: "" +: When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]proto:include_synthetic_attribute_hash`](#query-flag--proto:include_synthetic_attribute_hash) default: "false" -Whether or not to calculate and populate the \$internal_attr_hash attribute. +`--[no]proto:default_values` default: "true" +: If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]proto:instantiation_stack`](#query-flag--proto:instantiation_stack) default: "false" -Populate the instantiation call stack of each rule. Note that this requires the stack to be present +`--[no]proto:definition_stack` default: "false" +: Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]proto:locations`](#query-flag--proto:locations) default: "true" -Whether to output location information in proto output at all. +`--[no]proto:flatten_selects` default: "true" +: If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--proto:output_rule_attrs`](#query-flag--proto:output_rule_attrs)`=<comma-separated list of options>` default: "all" -Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. +`--[no]proto:include_attribute_source_aspects` default: "false" +: Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]proto:rule_classes`](#query-flag--proto:rule_classes) default: "false" -Populate the rule_class_key field of each rule; and for the first rule with a given rule_class_key, also populate its rule_class_info proto field. The rule_class_key field uniquely identifies a rule class, and the rule_class_info field is a Stardoc-format rule class API definition. +`--[no]proto:include_starlark_rule_env` default: "true" +: Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]proto:rule_inputs_and_outputs`](#query-flag--proto:rule_inputs_and_outputs) default: "true" -Whether or not to populate the rule_input and rule_output fields. +`--[no]proto:include_synthetic_attribute_hash` default: "false" +: Whether or not to calculate and populate the $internal\_attr\_hash attribute. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--query_file`](#query-flag--query_file)`=<a string>` default: "" -If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. +`--[no]proto:instantiation_stack` default: "false" +: Populate the instantiation call stack of each rule. Note that this requires the stack to be present -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]relative_locations`](#query-flag--relative_locations) default: "false" -If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. +`--[no]proto:locations` default: "true" +: Whether to output location information in proto output at all. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]strict_test_suite`](#query-flag--strict_test_suite) default: "false" -If true, the tests() expression gives an error if it encounters a test_suite containing non-test targets. +`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" +: Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]tool_deps`](#query-flag--tool_deps) default: "true" -Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. -Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. +`--[no]proto:rule_classes` default: "false" +: Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--universe_scope`](#query-flag--universe_scope)`=<comma-separated list of options>` default: "" -A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. -For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. +`--[no]proto:rule_inputs_and_outputs` default: "true" +: Whether or not to populate the rule\_input and rule\_output fields. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]xml:default_values`](#query-flag--xml:default_values) default: "false" -If true, rule attributes whose value is not explicitly specified in the BUILD file are printed; otherwise they are omitted. +`--query_file=<a string>` default: "" +: If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -[`--[no]xml:line_numbers`](#query-flag--xml:line_numbers) default: "true" -If true, XML output contains line numbers. Disabling this option may make diffs easier to read. This option is only applicable to --output=xml. +`--[no]relative_locations` default: "false" +: If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -<!-- --> +`--[no]strict_test_suite` default: "false" +: If true, the tests() expression gives an error if it encounters a test\_suite containing non-test targets. -[`--[no]verbose_visibility_errors`](#query-flag--verbose_visibility_errors) default: "false" -If enabled, visibility errors include additional diagnostic information. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]tool_deps` default: "true" +: Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. + Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. -<!-- --> + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -[`--flag_alias`](#query-flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated -Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. +`--universe_scope=<comma-separated list of options>` default: "" +: A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. + For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -<!-- --> +`--[no]xml:default_values` default: "false" +: If true, rule attributes whose value is not explicitly specified in the BUILD file are printed; otherwise they are omitted. -[`--deleted_packages`](#query-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated -A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]fetch`](#query-flag--fetch) default: "true" -Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. +`--[no]xml:line_numbers` default: "true" +: If true, XML output contains line numbers. Disabling this option may make diffs easier to read. This option is only applicable to --output=xml. -[`--package_path`](#query-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" -A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -[`--[no]show_loading_progress`](#query-flag--show_loading_progress) default: "true" -If enabled, causes Bazel to print "Loading package:" messages. +Options that affect the verbosity, format or location of logging: -## <span id="run">Run Options</span> +`--[no]verbose_visibility_errors` default: "false" +: If enabled, visibility errors include additional diagnostic information. -Inherits all options from [build](#build). - -[`--[no]portable_paths`](#run-flag--portable_paths) default: "false" -If true, includes paths to replace in ExecRequest to make the resulting paths portable. - -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -[`--[no]run`](#run-flag--run) default: "true" -If false, skip running the command line constructed for the built target. Note that this flag is ignored for all --script_path builds. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -[`--run_env`](#run-flag--run_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to the target to run. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. Note that the executed target will generally see the full environment of the host except for those variables that have been explicitly unset. +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated +: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -<!-- --> +Miscellaneous options, not otherwise categorized.: -[`--script_path`](#run-flag--script_path)`=<a path>` default: see description -If set, write a shell script to the given file which invokes the target. If this option is set, the target is not run from bazel. Use 'bazel run --script_path=foo //foo && ./foo' to invoke target '//foo' This differs from 'bazel run //foo' in that the bazel lock is released and the executable is connected to the terminal's stdin. +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated +: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. + Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) +`--[no]fetch` default: "true" +: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. -## <span id="shutdown">Shutdown Options</span> +`--package_path=<colon-separated list of options>` default: "%workspace%" +: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. -[`--iff_heap_size_greater_than`](#shutdown-flag--iff_heap_size_greater_than)`=<an integer>` default: "0" -Iff non-zero, then shutdown will only shut down the server if the total memory (in MB) consumed by the JVM exceeds this value. +`--[no]show_loading_progress` default: "true" +: If enabled, causes Bazel to print "Loading package:" messages. -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -## <span id="test">Test Options</span> +## Run Options Inherits all options from [build](#build). -[`--[no]print_relative_test_log_paths`](#test-flag--print_relative_test_log_paths) default: "false" -If true, when printing the path to a test log, use relative path that makes use of the 'testlogs' convenience symlink. N.B. - A subsequent 'build'/'test'/etc invocation with a different configuration can cause the target of this symlink to change, making the path printed previously no longer useful. - -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -[`--[no]test_verbose_timeout_warnings`](#test-flag--test_verbose_timeout_warnings) default: "false" -If true, print additional warnings when the actual test execution time does not match the timeout defined by the test (whether implied or explicit). - -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that appear before the command and are parsed by the client: -[`--[no]verbose_test_summary`](#test-flag--verbose_test_summary) default: "true" -If true, print additional information (timing, number of failed runs, etc) in the test summary. +`--[no]portable_paths` default: "false" +: If true, includes paths to replace in ExecRequest to make the resulting paths portable. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -## <span id="vendor">Vendor Options</span> +`--[no]run` default: "true" +: If false, skip running the command line constructed for the built target. Note that this flag is ignored for all --script\_path builds. -Inherits all options from [test](#test). - -[`--[no]keep_going`](#vendor-flag--keep_going) \[`-k`\] default: "false" -Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. - -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -[`--loading_phase_threads`](#vendor-flag--loading_phase_threads)`=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation (\[-\|*\]\<float\>) eg. "auto", "HOST_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) +`--run_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to the target to run. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. Note that the executed target will generally see the full environment of the host except for those variables that have been explicitly unset. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]incompatible_config_setting_private_default_visibility`](#vendor-flag--incompatible_config_setting_private_default_visibility) default: "false" -If incompatible_enforce_config_setting_visibility=false, this is a noop. Else, if this flag is false, any config_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--script_path=<a path>` default: see description +: If set, write a shell script to the given file which invokes the target. If this option is set, the target is not run from bazel. Use 'bazel run --script\_path=foo //foo && ./foo' to invoke target '//foo' This differs from 'bazel run //foo' in that the bazel lock is released and the executable is connected to the terminal's stdin. -[`--[no]incompatible_enforce_config_setting_visibility`](#vendor-flag--incompatible_enforce_config_setting_visibility) default: "true" -If true, enforce config_setting visibility restrictions. If false, every config_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +## Shutdown Options -<!-- --> +Options that control the output of the command: -[`--repo`](#vendor-flag--repo)`=<a string>` multiple uses are accumulated -Only vendors the specified repository, which can be either `@apparent_repo_name` or `@@canonical_repo_name`. This option can be set multiple times +`--iff_heap_size_greater_than=<an integer>` default: "0" +: Iff non-zero, then shutdown will only shut down the server if the total memory (in MB) consumed by the JVM exceeds this value. -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -<!-- --> +## Test Options -[`--deleted_packages`](#vendor-flag--deleted_packages)`=<comma-separated list of package names>` multiple uses are accumulated -A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. -Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package_path entry. Specifying --deleted_packages x/y avoids this problem. - -[`--[no]fetch`](#vendor-flag--fetch) default: "true" -Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. +Inherits all options from [build](#build). -[`--package_path`](#vendor-flag--package_path)`=<colon-separated list of options>` default: "%workspace%" -A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. +Options that affect the verbosity, format or location of logging: -[`--[no]show_loading_progress`](#vendor-flag--show_loading_progress) default: "true" -If enabled, causes Bazel to print "Loading package:" messages. +`--[no]print_relative_test_log_paths` default: "false" +: If true, when printing the path to a test log, use relative path that makes use of the 'testlogs' convenience symlink. N.B. - A subsequent 'build'/'test'/etc invocation with a different configuration can cause the target of this symlink to change, making the path printed previously no longer useful. -<!-- --> + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_persistent_aar_extractor`](#flag--experimental_persistent_aar_extractor) default: "false" -Enable persistent aar extractor by using workers. +`--[no]test_verbose_timeout_warnings` default: "false" +: If true, print additional warnings when the actual test execution time does not match the timeout defined by the test (whether implied or explicit). -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_remotable_source_manifests`](#flag--experimental_remotable_source_manifests) default: "false" -Whether to make source manifest actions remotable +`--[no]verbose_test_summary` default: "true" +: If true, print additional information (timing, number of failed runs, etc) in the test summary. -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -[`--[no]experimental_split_coverage_postprocessing`](#flag--experimental_split_coverage_postprocessing) default: "false" -If true, then Bazel will run coverage postprocessing for test in a new spawn. +## Vendor Options -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +Inherits all options from [test](#test). -[`--[no]experimental_strict_fileset_output`](#flag--experimental_strict_fileset_output) default: "false" -If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. +Options that control build execution: -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]keep_going` [`-k`] default: "false" +: Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. -[`--[no]incompatible_modify_execution_info_additive`](#flag--incompatible_modify_execution_info_additive) default: "true" -When enabled, passing multiple --modify_execution_info flags is additive. When disabled, only the last flag is taken into account. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" +: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. -[`--modify_execution_info`](#flag--modify_execution_info)`=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + Tags: + [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) -Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -Examples: -'.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. -'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. -'(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. +`--[no]incompatible_config_setting_private_default_visibility` default: "false" +: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. -Tags: -[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -[`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -Enable persistent Android dex and desugar actions by using workers. +`--[no]incompatible_enforce_config_setting_visibility` default: "true" +: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. -Expands to: -  [`--internal_persistent_android_dex_desugar`](#flag--internal_persistent_android_dex_desugar) -  [`--strategy=Desugar=worker`](#flag--strategy) -  [`--strategy=DexBuilder=worker`](#flag--strategy) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +Options relating to Bzlmod output and semantics: -[`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -Enable persistent Android resource processor by using workers. +`--repo=<a string>` multiple uses are accumulated +: Only vendors the specified repository, which can be either `@apparent_repo_name` or `@@canonical_repo_name`. This option can be set multiple times -Expands to: -  [`--internal_persistent_busybox_tools`](#flag--internal_persistent_busybox_tools) -  [`--strategy=AaptPackage=worker`](#flag--strategy) -  [`--strategy=AndroidResourceParser=worker`](#flag--strategy) -  [`--strategy=AndroidResourceValidator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceCompiler=worker`](#flag--strategy) -  [`--strategy=RClassGenerator=worker`](#flag--strategy) -  [`--strategy=AndroidResourceLink=worker`](#flag--strategy) -  [`--strategy=AndroidAapt2=worker`](#flag--strategy) -  [`--strategy=AndroidAssetMerger=worker`](#flag--strategy) -  [`--strategy=AndroidResourceMerger=worker`](#flag--strategy) -  [`--strategy=AndroidCompiledResourceMerger=worker`](#flag--strategy) -  [`--strategy=ManifestMerger=worker`](#flag--strategy) -  [`--strategy=AndroidManifestMerger=worker`](#flag--strategy) -  [`--strategy=Aapt2Optimize=worker`](#flag--strategy) -  [`--strategy=AARGenerator=worker`](#flag--strategy) -  [`--strategy=ProcessDatabinding=worker`](#flag--strategy) -  [`--strategy=GenerateDataBindingBaseClasses=worker`](#flag--strategy) + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +Miscellaneous options, not otherwise categorized.: -[`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) -Enable persistent multiplexed Android dex and desugar actions by using workers. +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated +: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. + Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. -Expands to: -  [`--persistent_android_dex_desugar`](#flag--persistent_android_dex_desugar) -  [`--internal_persistent_multiplex_android_dex_desugar`](#flag--internal_persistent_multiplex_android_dex_desugar) +`--[no]fetch` default: "true" +: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--package_path=<colon-separated list of options>` default: "%workspace%" +: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. -[`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -Enable persistent multiplexed Android resource processor by using workers. +`--[no]show_loading_progress` default: "true" +: If enabled, causes Bazel to print "Loading package:" messages. -Expands to: -  [`--persistent_android_resource_processor`](#flag--persistent_android_resource_processor) -  [`--modify_execution_info=AaptPackage=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=RClassGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=ManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers`](#flag--modify_execution_info) -  [`--modify_execution_info=AARGenerator=+supports-multiplex-workers`](#flag--modify_execution_info) +Options that control build execution: -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) +`--[no]experimental_persistent_aar_extractor` default: "false" +: Enable persistent aar extractor by using workers. -[`--persistent_multiplex_android_tools`](#flag--persistent_multiplex_android_tools) -Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Expands to: -  [`--internal_persistent_multiplex_busybox_tools`](#flag--internal_persistent_multiplex_busybox_tools) -  [`--persistent_multiplex_android_resource_processor`](#flag--persistent_multiplex_android_resource_processor) -  [`--persistent_multiplex_android_dex_desugar`](#flag--persistent_multiplex_android_dex_desugar) +`--[no]experimental_remotable_source_manifests` default: "false" +: Whether to make source manifest actions remotable -Tags: -[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -[`--[no]use_target_platform_for_tests`](#flag--use_target_platform_for_tests) default: "false" -If true, use the target platform for running tests rather than the test exec group. +`--[no]experimental_split_coverage_postprocessing` default: "false" +: If true, then Bazel will run coverage postprocessing for test in a new spawn. -Tags: -[`execution`](#effect_tag_EXECUTION) + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -<!-- --> +`--[no]experimental_strict_fileset_output` default: "false" +: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. -[`--android_compiler`](#flag--android_compiler)`=<a string>` default: see description -The Android target compiler. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]incompatible_modify_execution_info_additive` default: "true" +: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated +: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + + Syntax: "regex=[+-]key,regex=[+-]key,...". + + Examples: + '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. + 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. + '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + + Tags: + [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` +: Enable persistent Android dex and desugar actions by using workers. + + Expands to: + +   `--internal_persistent_android_dex_desugar` + +   `--strategy=Desugar=worker` + +   `--strategy=DexBuilder=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` +: Enable persistent Android resource processor by using workers. + + Expands to: + +   `--internal_persistent_busybox_tools` + +   `--strategy=AaptPackage=worker` + +   `--strategy=AndroidResourceParser=worker` + +   `--strategy=AndroidResourceValidator=worker` + +   `--strategy=AndroidResourceCompiler=worker` + +   `--strategy=RClassGenerator=worker` + +   `--strategy=AndroidResourceLink=worker` + +   `--strategy=AndroidAapt2=worker` + +   `--strategy=AndroidAssetMerger=worker` + +   `--strategy=AndroidResourceMerger=worker` + +   `--strategy=AndroidCompiledResourceMerger=worker` + +   `--strategy=ManifestMerger=worker` + +   `--strategy=AndroidManifestMerger=worker` + +   `--strategy=Aapt2Optimize=worker` + +   `--strategy=AARGenerator=worker` + +   `--strategy=ProcessDatabinding=worker` + +   `--strategy=GenerateDataBindingBaseClasses=worker` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` +: Enable persistent multiplexed Android dex and desugar actions by using workers. + + Expands to: + +   `--persistent_android_dex_desugar` + +   `--internal_persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` +: Enable persistent multiplexed Android resource processor by using workers. + + Expands to: + +   `--persistent_android_resource_processor` + +   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` +: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + + Expands to: + +   `--internal_persistent_multiplex_busybox_tools` + +   `--persistent_multiplex_android_resource_processor` + +   `--persistent_multiplex_android_dex_desugar` + + Tags: + [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" +: If true, use the target platform for running tests rather than the test exec group. + + Tags: + [`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: + +`--android_compiler=<a string>` default: see description +: The Android target compiler. + + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" +: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. -[`--android_manifest_merger`](#flag--android_manifest_merger)`=<legacy, android or force_android>` default: "android" -Selects the manifest merger to use for android_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--android_platforms=<a build target label>` default: "" +: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. -[`--android_platforms`](#flag--android_platforms)`=<a build target label>` default: "" -Sets the platforms that android_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--cc_output_directory_tag=<a string>` default: "" +: Specifies a suffix to be added to the configuration directory. -[`--cc_output_directory_tag`](#flag--cc_output_directory_tag)`=<a string>` default: "" -Specifies a suffix to be added to the configuration directory. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--compiler=<a string>` default: see description +: The C++ compiler to use for compiling the target. -[`--compiler`](#flag--compiler)`=<a string>` default: see description -The C++ compiler to use for compiling the target. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" +: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. -[`--coverage_output_generator`](#flag--coverage_output_generator)`=<a build target label>` default: "@bazel_tools//tools/test:lcov_merger" -Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov_merger'. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" +: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. -[`--coverage_report_generator`](#flag--coverage_report_generator)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_report_generator" -Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage_report_generator'. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" +: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. -[`--coverage_support`](#flag--coverage_support)`=<a build target label>` default: "@bazel_tools//tools/test:coverage_support" -Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage_support'. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--custom_malloc=<a build target label>` default: see description +: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. -[`--custom_malloc`](#flag--custom_malloc)`=<a build target label>` default: see description -Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]experimental_include_xcode_execution_requirements` default: "false" +: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. -[`--[no]experimental_include_xcode_execution_requirements`](#flag--experimental_include_xcode_execution_requirements) default: "false" -If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version_label}" execution requirement. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_prefer_mutual_xcode` default: "true" +: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. -[`--[no]experimental_prefer_mutual_xcode`](#flag--experimental_prefer_mutual_xcode) default: "true" -If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--extra_execution_platforms=<comma-separated list of options>` default: "" +: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. -[`--extra_execution_platforms`](#flag--extra_execution_platforms)`=<comma-separated list of options>` default: "" -The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register_execution_platforms(). This option may only be set once; later instances will override earlier flag settings. + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated +: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). -[`--extra_toolchains`](#flag--extra_toolchains)`=<comma-separated list of options>` multiple uses are accumulated -The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register_toolchains(). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--grte_top=<a label>` default: see description +: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. -[`--grte_top`](#flag--grte_top)`=<a label>` default: see description -A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_compiler=<a string>` default: see description +: No-op flag. Will be removed in a future release. -[`--host_compiler`](#flag--host_compiler)`=<a string>` default: see description -No-op flag. Will be removed in a future release. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) +`--host_grte_top=<a label>` default: see description +: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. -[`--host_grte_top`](#flag--host_grte_top)`=<a label>` default: see description -If specified, this setting overrides the libc top-level directory (--grte_top) for the exec configuration. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" +: The label of a platform rule that describes the host system. -[`--host_platform`](#flag--host_platform)`=<a build target label>` default: "@bazel_tools//tools:host_platform" -The label of a platform rule that describes the host system. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]incompatible_bazel_test_exec_run_under` default: "true" +: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. -[`--[no]incompatible_bazel_test_exec_run_under`](#flag--incompatible_bazel_test_exec_run_under) default: "true" -If enabled, "bazel test --run_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run_under=//foo" in the target configuration. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_builtin_objc_strip_action` default: "true" +: Whether to emit a strip action as part of objc linking. -[`--[no]incompatible_builtin_objc_strip_action`](#flag--incompatible_builtin_objc_strip_action) default: "true" -Whether to emit a strip action as part of objc linking. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" +: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). -[`--[no]incompatible_dont_enable_host_nonhost_crosstool_features`](#flag--incompatible_dont_enable_host_nonhost_crosstool_features) default: "true" -If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" +: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) -[`--[no]incompatible_enable_apple_toolchain_resolution`](#flag--incompatible_enable_apple_toolchain_resolution) default: "false" -Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_remove_legacy_whole_archive` default: "true" +: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). -[`--[no]incompatible_remove_legacy_whole_archive`](#flag--incompatible_remove_legacy_whole_archive) default: "true" -If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_strip_executable_safely` default: "false" +: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. -[`--[no]incompatible_strip_executable_safely`](#flag--incompatible_strip_executable_safely) default: "false" -If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]interface_shared_objects` default: "true" +: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. -[`--[no]interface_shared_objects`](#flag--interface_shared_objects) default: "true" -Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. -[`--ios_sdk_version`](#flag--ios_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. -[`--macos_sdk_version`](#flag--macos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--minimum_os_version=<a string>` default: see description +: The minimum OS version which your compilation targets. -[`--minimum_os_version`](#flag--minimum_os_version)`=<a string>` default: see description -The minimum OS version which your compilation targets. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--platform_mappings=<a main workspace-relative path>` default: "" +: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). -[`--platform_mappings`](#flag--platform_mappings)`=<a main workspace-relative path>` default: "" -The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform_mappings' (a file directly under the workspace root). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--platforms=<a build target label>` default: "" +: The labels of the platform rules describing the target platforms for the current command. -[`--platforms`](#flag--platforms)`=<a build target label>` default: "" -The labels of the platform rules describing the target platforms for the current command. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--python_path=<a string>` default: see description +: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. -[`--python_path`](#flag--python_path)`=<a string>` default: see description -The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible_use_python_toolchains. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. -[`--tvos_sdk_version`](#flag--tvos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. -[`--[no]use_platforms_in_apple_crosstool_transition`](#flag--use_platforms_in_apple_crosstool_transition) default: "false" -Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. -[`--watchos_sdk_version`](#flag--watchos_sdk_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--xcode_version=<a string>` default: see description +: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. -[`--xcode_version`](#flag--xcode_version)`=<a string>` default: see description -If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" +: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. -[`--xcode_version_config`](#flag--xcode_version_config)`=<a build target label>` default: "@bazel_tools//tools/cpp:host_xcodes" -The label of the xcode_config rule to be used for selecting the Xcode version in the build configuration. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +Options that control the output of the command: -<!-- --> +`--[no]apple_generate_dsym` default: "false" +: Whether to generate debug symbol(.dSYM) file(s). -[`--[no]apple_generate_dsym`](#flag--apple_generate_dsym) default: "false" -Whether to generate debug symbol(.dSYM) file(s). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]build_runfile_links` default: "true" +: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. -[`--[no]build_runfile_links`](#flag--build_runfile_links) default: "true" -If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]build_runfile_manifests` default: "true" +: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. -[`--[no]build_runfile_manifests`](#flag--build_runfile_manifests) default: "true" -If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]build_test_dwp` default: "false" +: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. -[`--[no]build_test_dwp`](#flag--build_test_dwp) default: "false" -If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" +: Sets the suffixes of header files that a cc\_proto\_library creates. -[`--cc_proto_library_header_suffixes`](#flag--cc_proto_library_header_suffixes)`=<comma-separated set of options>` default: ".pb.h" -Sets the suffixes of header files that a cc_proto_library creates. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" +: Sets the suffixes of source files that a cc\_proto\_library creates. -[`--cc_proto_library_source_suffixes`](#flag--cc_proto_library_source_suffixes)`=<comma-separated set of options>` default: ".pb.cc" -Sets the suffixes of source files that a cc_proto_library creates. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" +: Run extra actions for alternative Java api versions in a proto\_library. -[`--[no]experimental_proto_descriptor_sets_include_source_info`](#flag--experimental_proto_descriptor_sets_include_source_info) default: "false" -Run extra actions for alternative Java api versions in a proto_library. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_save_feature_state` default: "false" +: Save the state of enabled and requested feautres as an output of compilation. -[`--[no]experimental_save_feature_state`](#flag--experimental_save_feature_state) default: "false" -Save the state of enabled and requested feautres as an output of compilation. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--fission=<a set of compilation modes>` default: "no" +: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. -[`--fission`](#flag--fission)`=<a set of compilation modes>` default: "no" -Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_always_include_files_in_data` default: "true" +: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). -[`--[no]incompatible_always_include_files_in_data`](#flag--incompatible_always_include_files_in_data) default: "true" -If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles_features_to_avoid). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" +: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. -[`--[no]incompatible_compact_repo_mapping_manifest`](#flag--incompatible_compact_repo_mapping_manifest) default: "false" -If enabled, the \<binary\>.repo_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" +: List of flags for which the use in select() is disabled. -[`--incompatible_disable_select_on`](#flag--incompatible_disable_select_on)`=<comma-separated set of options>` default: "" -List of flags for which the use in select() is disabled. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" +: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. -[`--[no]incompatible_filegroup_runfiles_for_data`](#flag--incompatible_filegroup_runfiles_for_data) default: "true" -If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]objc_generate_linkmap` default: "false" +: Specifies whether to generate a linkmap file. -[`--[no]objc_generate_linkmap`](#flag--objc_generate_linkmap) default: "false" -Specifies whether to generate a linkmap file. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]save_temps` default: "false" +: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). -[`--[no]save_temps`](#flag--save_temps) default: "false" -If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -<!-- --> +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case + the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + \<br\> + Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. -[`--action_env`](#flag--action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case -the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -\<br\> -Note that unless \<code\>--incompatible_repo_env_ignores_action_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--allowed_cpu_values=<comma-separated set of options>` default: "" +: Allowed values for the --cpu flag. -[`--allowed_cpu_values`](#flag--allowed_cpu_values)`=<comma-separated set of options>` default: "" -Allowed values for the --cpu flag. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]android_databinding_use_androidx` default: "true" +: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. -[`--[no]android_databinding_use_androidx`](#flag--android_databinding_use_androidx) default: "true" -Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]android_databinding_use_v3_4_args` default: "true" +: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. -[`--[no]android_databinding_use_v3_4_args`](#flag--android_databinding_use_v3_4_args) default: "true" -Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--android_dynamic_mode=<off, default or fully>` default: "off" +: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -[`--android_dynamic_mode`](#flag--android_dynamic_mode)`=<off, default or fully>` default: "off" -Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" +: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. -[`--android_manifest_merger_order`](#flag--android_manifest_merger_order)`=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL_BY_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) +`--[no]android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -[`--[no]android_resource_shrinking`](#flag--android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]build_python_zip` default: "auto" +: Build python executable zip; on on Windows, off on other platforms -[`--[no]build_python_zip`](#flag--build_python_zip) default: "auto" -Build python executable zip; on on Windows, off on other platforms + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple Catalyst binaries. -[`--catalyst_cpus`](#flag--catalyst_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple Catalyst binaries. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]collect_code_coverage` default: "false" +: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. -[`--[no]collect_code_coverage`](#flag--collect_code_coverage) default: "false" -If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" +: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. -[`--compilation_mode`](#flag--compilation_mode)`=<fastbuild, dbg or opt>` \[`-c`\] default: "fastbuild" -Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C source files. -[`--conlyopt`](#flag--conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C source files. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--copt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc. -[`--copt`](#flag--copt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cpu=<a string>` default: "" +: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. -[`--cpu`](#flag--cpu)`=<a string>` default: "" -Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cs_fdo_absolute_path=<a string>` default: see description +: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. -[`--cs_fdo_absolute_path`](#flag--cs_fdo_absolute_path)`=<a string>` default: see description -Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cs_fdo_instrument=<a string>` default: see description +: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -[`--cs_fdo_instrument`](#flag--cs_fdo_instrument)`=<a string>` default: see description -Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cs_fdo_profile=<a build target label>` default: see description +: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. -[`--cs_fdo_profile`](#flag--cs_fdo_profile)`=<a build target label>` default: see description -The cs_fdo_profile representing the context sensitive profile to be used for optimization. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--cxxopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when compiling C++ source files. -[`--cxxopt`](#flag--cxxopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when compiling C++ source files. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--define=<a 'name=value' assignment>` multiple uses are accumulated +: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. -[`--define`](#flag--define)`=<a 'name=value' assignment>` multiple uses are accumulated -Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--dynamic_mode=<off, default or fully>` default: "default" +: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. -[`--dynamic_mode`](#flag--dynamic_mode)`=<off, default or fully>` default: "default" -Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]enable_propeller_optimize_absolute_paths` default: "true" +: If set, any use of absolute paths for propeller optimize will raise an error. -[`--[no]enable_propeller_optimize_absolute_paths`](#flag--enable_propeller_optimize_absolute_paths) default: "true" -If set, any use of absolute paths for propeller optimize will raise an error. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]enable_remaining_fdo_absolute_paths` default: "true" +: If set, any use of absolute paths for FDO will raise an error. -[`--[no]enable_remaining_fdo_absolute_paths`](#flag--enable_remaining_fdo_absolute_paths) default: "true" -If set, any use of absolute paths for FDO will raise an error. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]enable_runfiles` default: "auto" +: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. -[`--[no]enable_runfiles`](#flag--enable_runfiles) default: "auto" -Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. -[`--exec_aspects`](#flag--exec_aspects)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--experimental_action_listener=<a build target label>` multiple uses are accumulated +: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. -[`--experimental_action_listener`](#flag--experimental_action_listener)`=<a build target label>` multiple uses are accumulated -Deprecated in favor of aspects. Use action_listener to attach an extra_action to existing build actions. + Tags: + [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_android_compress_java_resources` default: "false" +: Compress Java resources in APKs -[`--[no]experimental_android_compress_java_resources`](#flag--experimental_android_compress_java_resources) default: "false" -Compress Java resources in APKs + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_android_databinding_v2` default: "true" +: Use android databinding v2. This flag is a no-op. -[`--[no]experimental_android_databinding_v2`](#flag--experimental_android_databinding_v2) default: "true" -Use android databinding v2. This flag is a no-op. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_android_resource_shrinking` default: "false" +: Enables resource shrinking for android\_binary APKs that use ProGuard. -[`--[no]experimental_android_resource_shrinking`](#flag--experimental_android_resource_shrinking) default: "false" -Enables resource shrinking for android_binary APKs that use ProGuard. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" +: use rex tool to rewrite dex files -[`--[no]experimental_android_rewrite_dexes_with_rex`](#flag--experimental_android_rewrite_dexes_with_rex) default: "false" -use rex tool to rewrite dex files + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" +: If specified, Bazel will also generate collect coverage information for generated files. -[`--[no]experimental_collect_code_coverage_for_generated_files`](#flag--experimental_collect_code_coverage_for_generated_files) default: "false" -If specified, Bazel will also generate collect coverage information for generated files. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" +: Uses these strings as objc fastbuild compiler options. -[`--experimental_objc_fastbuild_options`](#flag--experimental_objc_fastbuild_options)`=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -Uses these strings as objc fastbuild compiler options. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]experimental_omitfp` default: "false" +: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. -[`--[no]experimental_omitfp`](#flag--experimental_omitfp) default: "false" -If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_output_paths=<off or strip>` default: "off" +: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. -[`--experimental_output_paths`](#flag--experimental_output_paths)`=<off or strip>` default: "off" -Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution_requirements' dict. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated +: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. -[`--experimental_override_platform_cpu_name`](#flag--experimental_override_platform_cpu_name)`=<a 'label=value' assignment>` multiple uses are accumulated -Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in \$(TARGET_CPU) make variable and output path. Only used when --experimental_platform_in_output_dir, --incompatible_target_cpu_from_platform or --incompatible_bep_cpu_from_platform is true. Has highest naming priority. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_platform_in_output_dir` default: "false" +: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. -[`--[no]experimental_platform_in_output_dir`](#flag--experimental_platform_in_output_dir) default: "false" -If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental_override_name_platform_in_output_dir, then that shortname is used. Then, if --experimental_use_platforms_in_output_dir_legacy_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_py_binaries_include_label` default: "false" +: py\_binary targets include their label even when stamping is disabled. -[`--[no]experimental_py_binaries_include_label`](#flag--experimental_py_binaries_include_label) default: "false" -py_binary targets include their label even when stamping is disabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_use_llvm_covmap` default: "false" +: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. -[`--[no]experimental_use_llvm_covmap`](#flag--experimental_use_llvm_covmap) default: "false" -If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect_code_coverage is enabled. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" +: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. -[`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic`](#flag--experimental_use_platforms_in_output_dir_legacy_heuristic) default: "true" -Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental_override_name_platform_in_output_dir. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--fdo_instrument=<a string>` default: see description +: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. -[`--fdo_instrument`](#flag--fdo_instrument)`=<a string>` default: see description -Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--fdo_optimize=<a string>` default: see description +: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. -[`--fdo_optimize`](#flag--fdo_optimize)`=<a string>` default: see description -Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--fdo_prefetch_hints=<a build target label>` default: see description +: Use cache prefetch hints. -[`--fdo_prefetch_hints`](#flag--fdo_prefetch_hints)`=<a build target label>` default: see description -Use cache prefetch hints. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--fdo_profile=<a build target label>` default: see description +: The fdo\_profile representing the profile to be used for optimization. -[`--fdo_profile`](#flag--fdo_profile)`=<a build target label>` default: see description -The fdo_profile representing the profile to be used for optimization. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features -[`--features`](#flag--features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host_features + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]force_pic` default: "false" +: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). -[`--[no]force_pic`](#flag--force_pic) default: "false" -If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. -[`--host_action_env`](#flag--host_action_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code\>=name\</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" +: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. -[`--host_compilation_mode`](#flag--host_compilation_mode)`=<fastbuild, dbg or opt>` default: "opt" -Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--host_conlyopt=<a string>` multiple uses are accumulated +: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. -[`--host_conlyopt`](#flag--host_conlyopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_copt=<a string>` multiple uses are accumulated +: Additional options to pass to the C compiler for tools built in the exec configurations. -[`--host_copt`](#flag--host_copt)`=<a string>` multiple uses are accumulated -Additional options to pass to the C compiler for tools built in the exec configurations. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_cpu=<a string>` default: "" +: The host CPU. -[`--host_cpu`](#flag--host_cpu)`=<a string>` default: "" -The host CPU. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_cxxopt=<a string>` multiple uses are accumulated +: Additional options to pass to C++ compiler for tools built in the exec configurations. -[`--host_cxxopt`](#flag--host_cxxopt)`=<a string>` multiple uses are accumulated -Additional options to pass to C++ compiler for tools built in the exec configurations. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_features=<a string>` multiple uses are accumulated +: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. -[`--host_features`](#flag--host_features)`=<a string>` multiple uses are accumulated -The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to linker when linking tools in the exec configurations. -[`--host_linkopt`](#flag--host_linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to linker when linking tools in the exec configurations. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. -[`--host_macos_minimum_os`](#flag--host_macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for host targets. If unspecified, uses 'macos_sdk_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -[`--host_per_file_copt`](#flag--host_per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host_per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]incompatible_auto_exec_groups` default: "false" +: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. -[`--[no]incompatible_auto_exec_groups`](#flag--incompatible_auto_exec_groups) default: "false" -When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_merge_genfiles_directory` default: "true" +: If true, the genfiles directory is folded into the bin directory. -[`--[no]incompatible_merge_genfiles_directory`](#flag--incompatible_merge_genfiles_directory) default: "true" -If true, the genfiles directory is folded into the bin directory. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_target_cpu_from_platform` default: "true" +: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. -[`--[no]incompatible_target_cpu_from_platform`](#flag--incompatible_target_cpu_from_platform) default: "true" -If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the \$(TARGET_CPU) make variable. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]instrument_test_targets` default: "false" +: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. -[`--[no]instrument_test_targets`](#flag--instrument_test_targets) default: "false" -When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" +: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. -[`--instrumentation_filter`](#flag--instrumentation_filter)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" -When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument_test_targets is enabled. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. -[`--ios_minimum_os`](#flag--ios_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios_sdk_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. -[`--ios_multi_cpus`](#flag--ios_multi_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures to build an ios_application with. The result is a universal binary containing all specified architectures. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]legacy_whole_archive` default: "true" +: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. -[`--[no]legacy_whole_archive`](#flag--legacy_whole_archive) default: "true" -Deprecated, superseded by --incompatible_remove_legacy_whole_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) +`--linkopt=<a string>` multiple uses are accumulated +: Additional option to pass to gcc when linking. -[`--linkopt`](#flag--linkopt)`=<a string>` multiple uses are accumulated -Additional option to pass to gcc when linking. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ltobackendopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO backend step (under --features=thin\_lto). -[`--ltobackendopt`](#flag--ltobackendopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO backend step (under --features=thin_lto). + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ltoindexopt=<a string>` multiple uses are accumulated +: Additional option to pass to the LTO indexing step (under --features=thin\_lto). -[`--ltoindexopt`](#flag--ltoindexopt)`=<a string>` multiple uses are accumulated -Additional option to pass to the LTO indexing step (under --features=thin_lto). + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple macOS binaries. -[`--macos_cpus`](#flag--macos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple macOS binaries. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. -[`--macos_minimum_os`](#flag--macos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible macOS version for targets. If unspecified, uses 'macos_sdk_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--memprof_profile=<a build target label>` default: see description +: Use memprof profile. -[`--memprof_profile`](#flag--memprof_profile)`=<a build target label>` default: see description -Use memprof profile. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]objc_debug_with_GLIBCXX` default: "false" +: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. -[`--[no]objc_debug_with_GLIBCXX`](#flag--objc_debug_with_GLIBCXX) default: "false" -If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]objc_enable_binary_stripping` default: "false" +: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. -[`--[no]objc_enable_binary_stripping`](#flag--objc_enable_binary_stripping) default: "false" -Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation_mode=opt are specified. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--objccopt=<a string>` multiple uses are accumulated +: Additional options to pass to gcc when compiling Objective-C/C++ source files. -[`--objccopt`](#flag--objccopt)`=<a string>` multiple uses are accumulated -Additional options to pass to gcc when compiling Objective-C/C++ source files. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. -[`--per_file_copt`](#flag--per_file_copt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated +: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. -[`--per_file_ltobackendopt`](#flag--per_file_ltobackendopt)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -Additional options to selectively pass to LTO backend (under --features=thin_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex_filter@option_1,option_2,...,option_n. Where regex_filter stands for a list of include and exclude regular expression patterns. option_1 to option_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per_file_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--platform_suffix=<a string>` default: see description +: Specifies a suffix to be added to the configuration directory. -[`--platform_suffix`](#flag--platform_suffix)`=<a string>` default: see description -Specifies a suffix to be added to the configuration directory. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--propeller_optimize=<a build target label>` default: see description +: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile -[`--propeller_optimize`](#flag--propeller_optimize)`=<a build target label>` default: see description -Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller_optimize( name = "propeller_profile", cc_profile = "propeller_cc_profile.txt", ld_profile = "propeller_ld_profile.txt",)An exports_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller_optimize=//a/b:propeller_profile + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description +: Absolute path name of cc\_profile file for Propeller Optimized builds. -[`--propeller_optimize_absolute_cc_profile`](#flag--propeller_optimize_absolute_cc_profile)`=<a string>` default: see description -Absolute path name of cc_profile file for Propeller Optimized builds. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description +: Absolute path name of ld\_profile file for Propeller Optimized builds. -[`--propeller_optimize_absolute_ld_profile`](#flag--propeller_optimize_absolute_ld_profile)`=<a string>` default: see description -Absolute path name of ld_profile file for Propeller Optimized builds. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--run_under=<a prefix in front of command>` default: see description +: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. -[`--run_under`](#flag--run_under)`=<a prefix in front of command>` default: see description -Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test_binary -baz', then the final command line is 'foo -bar test_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--[no]share_native_deps` default: "true" +: If true, native libraries that contain identical functionality will be shared among different targets -[`--[no]share_native_deps`](#flag--share_native_deps) default: "true" -If true, native libraries that contain identical functionality will be shared among different targets + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]stamp` default: "false" +: Stamp binaries with the date, username, hostname, workspace information, etc. -[`--[no]stamp`](#flag--stamp) default: "false" -Stamp binaries with the date, username, hostname, workspace information, etc. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--strip=<always, sometimes or never>` default: "sometimes" +: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. -[`--strip`](#flag--strip)`=<always, sometimes or never>` default: "sometimes" -Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation_mode=fastbuild. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--stripopt=<a string>` multiple uses are accumulated +: Additional options to pass to strip when generating a '\<name\>.stripped' binary. -[`--stripopt`](#flag--stripopt)`=<a string>` multiple uses are accumulated -Additional options to pass to strip when generating a '\<name\>.stripped' binary. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple tvOS binaries. -[`--tvos_cpus`](#flag--tvos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple tvOS binaries. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. -[`--tvos_minimum_os`](#flag--tvos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos_sdk_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple visionOS binaries. -[`--visionos_cpus`](#flag--visionos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple visionOS binaries. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated +: Comma-separated list of architectures for which to build Apple watchOS binaries. -[`--watchos_cpus`](#flag--watchos_cpus)`=<comma-separated list of options>` multiple uses are accumulated -Comma-separated list of architectures for which to build Apple watchOS binaries. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. -[`--watchos_minimum_os`](#flag--watchos_minimum_os)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos_sdk_version'. + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--xbinary_fdo=<a build target label>` default: see description +: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. -[`--xbinary_fdo`](#flag--xbinary_fdo)`=<a build target label>` default: see description -Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo_instrument/--fdo_optimize/--fdo_profile, those options will always prevail as if xbinary_fdo is never specified. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): -<!-- --> +`--[no]check_visibility` default: "true" +: If disabled, visibility errors in target dependencies are demoted to warnings. -[`--[no]check_visibility`](#flag--check_visibility) default: "true" -If disabled, visibility errors in target dependencies are demoted to warnings. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]desugar_for_android` default: "true" +: Whether to desugar Java 8 bytecode before dexing. -[`--[no]desugar_for_android`](#flag--desugar_for_android) default: "true" -Whether to desugar Java 8 bytecode before dexing. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +`--[no]desugar_java8_libs` default: "false" +: Whether to include supported Java 8 libraries in apps for legacy devices. -[`--[no]desugar_java8_libs`](#flag--desugar_java8_libs) default: "false" -Whether to include supported Java 8 libraries in apps for legacy devices. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]enforce_constraints` default: "true" +: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments -[`--[no]enforce_constraints`](#flag--enforce_constraints) default: "true" -Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) -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. -[`--[no]experimental_check_desugar_deps`](#flag--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) -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. -[`--[no]experimental_enforce_transitive_visibility`](#flag--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. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" +: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. -[`--experimental_one_version_enforcement`](#flag--experimental_one_version_enforcement)`=<off, warning or error>` default: "OFF" -When enabled, enforce that a java_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" +: If true, checks that a Java target explicitly declares all directly used targets as dependencies. -[`--experimental_strict_java_deps`](#flag--experimental_strict_java_deps)`=<off, warn, error, strict or default>` default: "default" -If true, checks that a Java target explicitly declares all directly used targets as dependencies. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--[no]incompatible_check_testonly_for_output_files` default: "false" +: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. -[`--[no]incompatible_check_testonly_for_output_files`](#flag--incompatible_check_testonly_for_output_files) default: "false" -If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_disable_native_android_rules` default: "false" +: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android -[`--[no]incompatible_disable_native_android_rules`](#flag--incompatible_disable_native_android_rules) default: "false" -If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules_android + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" +: No-op. Kept here for backwards compatibility. -[`--[no]incompatible_disable_native_apple_binary_rule`](#flag--incompatible_disable_native_apple_binary_rule) default: "false" -No-op. Kept here for backwards compatibility. + Tags: + [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]one_version_enforcement_on_java_tests` default: "true" +: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. -[`--[no]one_version_enforcement_on_java_tests`](#flag--one_version_enforcement_on_java_tests) default: "true" -When enabled, and with experimental_one_version_enforcement set to a non-NONE value, enforce one version on java_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--python_native_rules_allowlist=<a build target label>` default: see description +: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. -[`--python_native_rules_allowlist`](#flag--python_native_rules_allowlist)`=<a build target label>` default: see description -An allowlist (package_group target) to use when enforcing --incompatible_python_disallow_native_rules. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]strict_filesets` default: "false" +: If this option is enabled, filesets crossing package boundaries are reported as errors. -[`--[no]strict_filesets`](#flag--strict_filesets) default: "false" -If this option is enabled, filesets crossing package boundaries are reported as errors. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" +: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. -[`--strict_proto_deps`](#flag--strict_proto_deps)`=<off, warn, error, strict or default>` default: "error" -Unless OFF, checks that a proto_library target explicitly declares all directly used targets as dependencies. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" +: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. -[`--strict_public_imports`](#flag--strict_public_imports)`=<off, warn, error, strict or default>` default: "off" -Unless OFF, checks that a proto_library target explicitly declares all targets used in 'import public' as exported. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]strict_system_includes` default: "false" +: If true, headers found through system include paths (-isystem) are also required to be declared. -[`--[no]strict_system_includes`](#flag--strict_system_includes) default: "false" -If true, headers found through system include paths (-isystem) are also required to be declared. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) +`--target_environment=<a build target label>` multiple uses are accumulated +: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. -[`--target_environment`](#flag--target_environment)`=<a build target label>` multiple uses are accumulated -Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +Options that affect the signing outputs of a build: -<!-- --> +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" +: Implementation to use to sign APKs -[`--apk_signing_method`](#flag--apk_signing_method)`=<v1, v2, v1_v2 or v4>` default: "v1_v2" -Implementation to use to sign APKs + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]device_debug_entitlements` default: "true" +: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. -[`--[no]device_debug_entitlements`](#flag--device_debug_entitlements) default: "true" -If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS) +`--ios_signing_cert_name=<a string>` default: see description +: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). -[`--ios_signing_cert_name`](#flag--ios_signing_cert_name)`=<a string>` default: see description -Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: -<!-- --> +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" +: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. -[`--[no]incompatible_disallow_sdk_frameworks_attributes`](#flag--incompatible_disallow_sdk_frameworks_attributes) default: "false" -If true, disallow sdk_frameworks and weak_sdk_frameworks attributes in objc_library andobjc_import. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_objc_alwayslink_by_default` default: "false" +: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. -[`--[no]incompatible_objc_alwayslink_by_default`](#flag--incompatible_objc_alwayslink_by_default) default: "false" -If true, make the default value true for alwayslink attributes in objc_library and objc_import. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_python_disallow_native_rules` default: "false" +: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. -[`--[no]incompatible_python_disallow_native_rules`](#flag--incompatible_python_disallow_native_rules) default: "false" -When true, an error occurs when using the builtin py\_\* rules; instead the rule_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +Options that govern the behavior of the test environment or test runner: -<!-- --> +`--[no]allow_analysis_failures` default: "false" +: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. -[`--[no]allow_analysis_failures`](#flag--allow_analysis_failures) default: "false" -If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--analysis_testing_deps_limit=<an integer>` default: "2000" +: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. -[`--analysis_testing_deps_limit`](#flag--analysis_testing_deps_limit)`=<an integer>` default: "2000" -Sets the maximum number of transitive dependencies through a rule attribute with a for_analysis_testing configuration transition. Exceeding this limit will result in a rule error. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" +: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. -[`--[no]break_build_on_parallel_dex2oat_failure`](#flag--break_build_on_parallel_dex2oat_failure) default: "false" -If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated +: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. -[`--default_test_resources`](#flag--default_test_resources)`=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -Override the default resources amount for tests. The expected format is \<resource\>=\<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST_RAM/HOST_CPU, optionally followed by \[-\|*\]\<float\> (eg. memory=HOST_RAM*.1,HOST_RAM\*.2,HOST_RAM\*.3,HOST_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. +`--[no]experimental_android_use_parallel_dex2oat` default: "false" +: Use dex2oat in parallel to possibly speed up android\_test. -[`--[no]experimental_android_use_parallel_dex2oat`](#flag--experimental_android_use_parallel_dex2oat) default: "false" -Use dex2oat in parallel to possibly speed up android_test. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]ios_memleaks` default: "false" +: Enable checking for memory leaks in ios\_test targets. -[`--[no]ios_memleaks`](#flag--ios_memleaks) default: "false" -Enable checking for memory leaks in ios_test targets. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) +`--ios_simulator_device=<a string>` default: see description +: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. -[`--ios_simulator_device`](#flag--ios_simulator_device)`=<a string>` default: see description -The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description +: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. -[`--ios_simulator_version`](#flag--ios_simulator_version)`=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -The version of iOS to run on the simulator when running or testing. This is ignored for ios_test rules if a target device is specified in the rule. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated +: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. -[`--runs_per_test`](#flag--runs_per_test)`=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs_per_test=3 will run all tests 3 times. Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for an integer value and regex_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation_filter). Example: --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated +: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. -[`--test_env`](#flag--test_env)`=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code\>=name\</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" +: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. -[`--test_timeout`](#flag--test_timeout)`=<a single integer or comma-separated list of 4 integers>` default: "-1" -Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. +`--[no]zip_undeclared_test_outputs` default: "false" +: If true, undeclared test outputs will be archived in a zip file. -[`--[no]zip_undeclared_test_outputs`](#flag--zip_undeclared_test_outputs) default: "false" -If true, undeclared test outputs will be archived in a zip file. + Tags: + [`test_runner`](#effect_tag_TEST_RUNNER) -Tags: -[`test_runner`](#effect_tag_TEST_RUNNER) +Options that trigger optimizations of the build time: -<!-- --> +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" +: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. -[`--[no]experimental_filter_library_jar_with_program_jar`](#flag--experimental_filter_library_jar_with_program_jar) default: "false" -Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + Tags: + [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_inmemory_dotd_files` default: "true" +: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. -[`--[no]experimental_inmemory_dotd_files`](#flag--experimental_inmemory_dotd_files) default: "true" -If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_inmemory_jdeps_files` default: "true" +: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. -[`--[no]experimental_inmemory_jdeps_files`](#flag--experimental_inmemory_jdeps_files) default: "true" -If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" +: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. -[`--[no]experimental_retain_test_configuration_across_testonly`](#flag--experimental_retain_test_configuration_across_testonly) default: "false" -When enabled, --trim_test_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc_test rules. No effect if --trim_test_configuration is false. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" +: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. -[`--[no]experimental_unsupported_and_brittle_include_scanning`](#flag--experimental_unsupported_and_brittle_include_scanning) default: "false" -Whether to narrow inputs to C/C++ compilation by parsing \#include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic \#include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -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. -[`--[no]incremental_dexing`](#flag--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) -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. -[`--[no]objc_use_dotd_pruning`](#flag--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. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]process_headers_in_dependencies` default: "false" +: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). -[`--[no]process_headers_in_dependencies`](#flag--process_headers_in_dependencies) default: "false" -When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + Tags: + [`execution`](#effect_tag_EXECUTION) -Tags: -[`execution`](#effect_tag_EXECUTION) +`--[no]trim_test_configuration` default: "true" +: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. -[`--[no]trim_test_configuration`](#flag--trim_test_configuration) default: "true" -When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) +Options that affect the verbosity, format or location of logging: -<!-- --> +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" +: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. -[`--toolchain_resolution_debug`](#flag--toolchain_resolution_debug)`=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + Tags: + [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) -Tags: -[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) +`--[no]verbose_visibility_errors` default: "false" +: If enabled, visibility errors include additional diagnostic information. -[`--[no]verbose_visibility_errors`](#flag--verbose_visibility_errors) default: "false" -If enabled, visibility errors include additional diagnostic information. + Tags: + [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: -<!-- --> +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated +: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. -[`--flag_alias`](#flag--flag_alias)`=<a 'name=value' flag alias>` multiple uses are accumulated -Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key\>=\<value\>" as an argument. + Tags: + [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) -Tags: -[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) +`--[no]incompatible_default_to_explicit_init_py` default: "false" +: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. -[`--[no]incompatible_default_to_explicit_init_py`](#flag--incompatible_default_to_explicit_init_py) default: "false" -This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py_binary or py_test target has legacy_create_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +Miscellaneous options, not otherwise categorized.: -<!-- --> +`--[no]cache_test_results` [`-t`] default: "auto" +: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. -[`--[no]cache_test_results`](#flag--cache_test_results) \[`-t`\] default: "auto" -If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs_per_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. +`--[no]experimental_cancel_concurrent_tests` default: "never" +: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. -[`--[no]experimental_cancel_concurrent_tests`](#flag--experimental_cancel_concurrent_tests) default: "never" -If 'on_failed' or 'on_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs_per_test_detects_flakes. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_fetch_all_coverage_outputs` default: "false" +: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. -[`--[no]experimental_fetch_all_coverage_outputs`](#flag--experimental_fetch_all_coverage_outputs) default: "false" -If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[no]experimental_generate_llvm_lcov` default: "false" +: If true, coverage for clang will generate an LCOV report. -[`--[no]experimental_generate_llvm_lcov`](#flag--experimental_generate_llvm_lcov) default: "false" -If true, coverage for clang will generate an LCOV report. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" +: Enables reduced classpaths for Java compilations. -[`--experimental_java_classpath`](#flag--experimental_java_classpath)`=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -Enables reduced classpaths for Java compilations. +`--[no]experimental_run_android_lint_on_java_rules` default: "false" +: Whether to validate java\_\* sources. -[`--[no]experimental_run_android_lint_on_java_rules`](#flag--experimental_run_android_lint_on_java_rules) default: "false" -Whether to validate java\_\* sources. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) +`--[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. -[`--[no]explicit_java_test_deps`](#flag--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. +`--host_java_launcher=<a build target label>` default: see description +: The Java launcher used by tools that are executed during a build. -[`--host_java_launcher`](#flag--host_java_launcher)`=<a build target label>` default: see description -The Java launcher used by tools that are executed during a build. +`--host_javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac when building tools that are executed during a build. -[`--host_javacopt`](#flag--host_javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac when building tools that are executed during a build. +`--host_jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. -[`--host_jvmopt`](#flag--host_jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java_binary target. +`--[no]incompatible_check_sharding_support` default: "true" +: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. -[`--[no]incompatible_check_sharding_support`](#flag--incompatible_check_sharding_support) default: "true" -If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST_SHARD_STATUS_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_exclusive_test_sandboxed` default: "true" +: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally -[`--[no]incompatible_exclusive_test_sandboxed`](#flag--incompatible_exclusive_test_sandboxed) default: "true" -If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + Tags: + [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--[no]incompatible_strict_action_env` default: "false" +: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. -[`--[no]incompatible_strict_action_env`](#flag--incompatible_strict_action_env) default: "false" -If true, Bazel uses an environment with a static value for PATH and does not inherit LD_LIBRARY_PATH. Use --action_env=ENV_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. -[`--j2objc_translation_flags`](#flag--j2objc_translation_flags)`=<comma-separated list of options>` multiple uses are accumulated -Additional options to pass to the J2ObjC tool. +`--java_debug` +: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. -[`--java_debug`](#flag--java_debug) -Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. + Expands to: + +   `--test_arg=--wrapper_script_flag=--debug` + +   `--test_output=streamed` + +   `--test_strategy=exclusive` + +   `--test_timeout=9999` + +   `--nocache_test_results` -Expands to: -  [`--test_arg=--wrapper_script_flag=--debug`](#flag--test_arg) -  [`--test_output=streamed`](#flag--test_output) -  [`--test_strategy=exclusive`](#flag--test_strategy) -  [`--test_timeout=9999`](#flag--test_timeout) -  [`--nocache_test_results`](#flag--nocache_test_results) +`--[no]java_deps` default: "true" +: Generate dependency information (for now, compile-time classpath) per Java target. -[`--[no]java_deps`](#flag--java_deps) default: "true" -Generate dependency information (for now, compile-time classpath) per Java target. +`--[no]java_header_compilation` default: "true" +: Compile ijars directly from source. -[`--[no]java_header_compilation`](#flag--java_header_compilation) default: "true" -Compile ijars directly from source. +`--java_language_version=<a string>` default: "" +: The Java language version -[`--java_language_version`](#flag--java_language_version)`=<a string>` default: "" -The Java language version +`--java_launcher=<a build target label>` default: see description +: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. -[`--java_launcher`](#flag--java_launcher)`=<a build target label>` default: see description -The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. +`--java_runtime_version=<a string>` default: "local\_jdk" +: The Java runtime version -[`--java_runtime_version`](#flag--java_runtime_version)`=<a string>` default: "local_jdk" -The Java runtime version +`--javacopt=<a string>` multiple uses are accumulated +: Additional options to pass to javac. -[`--javacopt`](#flag--javacopt)`=<a string>` multiple uses are accumulated -Additional options to pass to javac. +`--jvmopt=<a string>` multiple uses are accumulated +: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. -[`--jvmopt`](#flag--jvmopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the Java VM. These options will get added to the VM startup options of each java_binary target. +`--legacy_main_dex_list_generator=<a build target label>` default: see description +: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. -[`--legacy_main_dex_list_generator`](#flag--legacy_main_dex_list_generator)`=<a build target label>` default: see description -Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. +`--optimizing_dexer=<a build target label>` default: see description +: Specifies a binary to use to do dexing without sharding. -[`--optimizing_dexer`](#flag--optimizing_dexer)`=<a build target label>` default: see description -Specifies a binary to use to do dexing without sharding. +`--plugin=<a build target label>` multiple uses are accumulated +: Plugins to use in the build. Currently works with java\_plugin. -[`--plugin`](#flag--plugin)`=<a build target label>` multiple uses are accumulated -Plugins to use in the build. Currently works with java_plugin. +`--proguard_top=<a build target label>` default: see description +: Specifies which version of ProGuard to use for code removal when building a Java binary. -[`--proguard_top`](#flag--proguard_top)`=<a build target label>` default: see description -Specifies which version of ProGuard to use for code removal when building a Java binary. +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" +: The label of the proto-compiler. -[`--proto_compiler`](#flag--proto_compiler)`=<a build target label>` default: "@bazel_tools//tools/proto:protoc" -The label of the proto-compiler. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--[no]proto_profile` default: "true" +: Whether to pass profile\_path to the proto compiler. -[`--[no]proto_profile`](#flag--proto_profile) default: "true" -Whether to pass profile_path to the proto compiler. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_profile_path=<a build target label>` default: see description +: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. -[`--proto_profile_path`](#flag--proto_profile_path)`=<a build target label>` default: see description -The profile to pass to the proto compiler as profile_path. If unset, but --proto_profile is true (the default), infers the path from --fdo_optimize. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile C++ protos -[`--proto_toolchain_for_cc`](#flag--proto_toolchain_for_cc)`=<a build target label>` default: "@bazel_tools//tools/proto:cc_toolchain" -Label of proto_lang_toolchain() which describes how to compile C++ protos + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos -[`--proto_toolchain_for_j2objc`](#flag--proto_toolchain_for_j2objc)`=<a build target label>` default: "@bazel_tools//tools/j2objc:j2objc_proto_toolchain" -Label of proto_lang_toolchain() which describes how to compile j2objc protos + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile Java protos -[`--proto_toolchain_for_java`](#flag--proto_toolchain_for_java)`=<a build target label>` default: "@bazel_tools//tools/proto:java_toolchain" -Label of proto_lang_toolchain() which describes how to compile Java protos + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" +: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos -[`--proto_toolchain_for_javalite`](#flag--proto_toolchain_for_javalite)`=<a build target label>` default: "@bazel_tools//tools/proto:javalite_toolchain" -Label of proto_lang_toolchain() which describes how to compile JavaLite protos + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--protocopt=<a string>` multiple uses are accumulated +: Additional options to pass to the protobuf compiler. -[`--protocopt`](#flag--protocopt)`=<a string>` multiple uses are accumulated -Additional options to pass to the protobuf compiler. + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--[no]runs_per_test_detects_flakes` default: "false" +: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. -[`--[no]runs_per_test_detects_flakes`](#flag--runs_per_test_detects_flakes) default: "false" -If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. +`--shell_executable=<a path>` default: see description +: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. -[`--shell_executable`](#flag--shell_executable)`=<a path>` default: see description -Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) -Tags: -[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--test_arg=<a string>` multiple uses are accumulated +: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. -[`--test_arg`](#flag--test_arg)`=<a string>` multiple uses are accumulated -Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. +`--test_filter=<a string>` default: see description +: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. -[`--test_filter`](#flag--test_filter)`=<a string>` default: see description -Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. +`--test_result_expiration=<an integer>` default: "-1" +: This option is deprecated and has no effect. -[`--test_result_expiration`](#flag--test_result_expiration)`=<an integer>` default: "-1" -This option is deprecated and has no effect. +`--[no]test_runner_fail_fast` default: "false" +: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. -[`--[no]test_runner_fail_fast`](#flag--test_runner_fail_fast) default: "false" -Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" +: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. -[`--test_sharding_strategy`](#flag--test_sharding_strategy)`=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard_count' BUILD attribute. +`--tool_java_language_version=<a string>` default: "" +: The Java language version used to execute the tools that are needed during a build -[`--tool_java_language_version`](#flag--tool_java_language_version)`=<a string>` default: "" -The Java language version used to execute the tools that are needed during a build +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" +: The Java runtime version used to execute tools during the build -[`--tool_java_runtime_version`](#flag--tool_java_runtime_version)`=<a string>` default: "remotejdk_11" -The Java runtime version used to execute tools during the build +`--[no]use_ijars` default: "true" +: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. -[`--[no]use_ijars`](#flag--use_ijars) default: "true" -If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. +## Version Options -## <span id="version">Version Options</span> +Options that let the user configure the intended output, affecting its value, as opposed to its existence: -[`--[no]gnu_format`](#version-flag--gnu_format) default: "false" -If set, write the version to stdout using the conventions described in the GNU standards. +`--[no]gnu_format` default: "false" +: If set, write the version to stdout using the conventions described in the GNU standards. -Tags: -[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + Tags: + [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) ### Option Effect Tags | | | -|----|----| +| --- | --- | | `unknown` | This option has unknown, or undocumented, effect. | | `no_op` | This option has literally no effect. | | `loses_incremental_state` | Changing the value of this option can cause significant loss of incremental state, which slows builds. State could be lost due to a server restart or to invalidation of a large part of the dependency graph. | @@ -11859,7 +12147,7 @@ Tags: ### Option Metadata Tags | | | -|----|----| +| --- | --- | | `experimental` | This option triggers an experimental feature with no guarantees of functionality. | | `incompatible_change` | This option triggers a breaking change. Use this option to test your migration readiness or get early access to the new feature | | `deprecated` | This option is deprecated. It might be that the feature it affects is deprecated, or that another method of supplying the information is preferred. | @@ -11868,4 +12156,4 @@ Tags: - + \ No newline at end of file diff --git a/rules/lib/builtins.mdx b/rules/lib/builtins.mdx index c97f74f..8fbd257 100644 --- a/rules/lib/builtins.mdx +++ b/rules/lib/builtins.mdx @@ -2,69 +2,66 @@ title: 'builtins' --- -# Built-in Types -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} This section lists types of Starlark objects. With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. -- [Action](/rules/lib/builtins/Action) -- [actions](/rules/lib/builtins/actions) -- [apple_platform](/rules/lib/builtins/apple_platform) -- [Args](/rules/lib/builtins/Args) -- [Aspect](/rules/lib/builtins/Aspect) -- [Attribute](/rules/lib/builtins/Attribute) -- [bazel_module](/rules/lib/builtins/bazel_module) -- [bazel_module_tags](/rules/lib/builtins/bazel_module_tags) -- [BuildSetting](/rules/lib/builtins/BuildSetting) -- [CcCompilationOutputs](/rules/lib/builtins/CcCompilationOutputs) -- [CcLinkingOutputs](/rules/lib/builtins/CcLinkingOutputs) -- [CompilationContext](/rules/lib/builtins/CompilationContext) -- [configuration](/rules/lib/builtins/configuration) -- [ctx](/rules/lib/builtins/ctx) -- [depset](/rules/lib/builtins/depset) -- [DirectoryExpander](/rules/lib/builtins/DirectoryExpander) -- [DottedVersion](/rules/lib/builtins/DottedVersion) -- [exec_result](/rules/lib/builtins/exec_result) -- [ExecGroupCollection](/rules/lib/builtins/ExecGroupCollection) -- [ExecGroupContext](/rules/lib/builtins/ExecGroupContext) -- [ExecTransitionFactory](/rules/lib/builtins/ExecTransitionFactory) -- [ExpandedDirectory](/rules/lib/builtins/ExpandedDirectory) -- [extension_metadata](/rules/lib/builtins/extension_metadata) -- [FeatureConfiguration](/rules/lib/builtins/FeatureConfiguration) -- [File](/rules/lib/builtins/File) -- [fragments](/rules/lib/builtins/fragments) -- [java_annotation_processing](/rules/lib/builtins/java_annotation_processing) -- [Label](/rules/lib/builtins/Label) -- [LateBoundDefault](/rules/lib/builtins/LateBoundDefault) -- [LibraryToLink](/rules/lib/builtins/LibraryToLink) -- [License](/rules/lib/builtins/License) -- [LinkerInput](/rules/lib/builtins/LinkerInput) -- [LinkingContext](/rules/lib/builtins/LinkingContext) -- [macro](/rules/lib/builtins/macro) -- [mapped_root](/rules/lib/builtins/mapped_root) -- [module_ctx](/rules/lib/builtins/module_ctx) -- [path](/rules/lib/builtins/path) -- [propagation_ctx](/rules/lib/builtins/propagation_ctx) -- [Provider](/rules/lib/builtins/Provider) -- [repo_metadata](/rules/lib/builtins/repo_metadata) -- [repository_ctx](/rules/lib/builtins/repository_ctx) -- [repository_os](/rules/lib/builtins/repository_os) -- [repository_rule](/rules/lib/builtins/repository_rule) -- [root](/rules/lib/builtins/root) -- [rule](/rules/lib/builtins/rule) -- [rule_attributes](/rules/lib/builtins/rule_attributes) -- [runfiles](/rules/lib/builtins/runfiles) -- [struct](/rules/lib/builtins/struct) -- [Subrule](/rules/lib/builtins/Subrule) -- [subrule_ctx](/rules/lib/builtins/subrule_ctx) -- [SymlinkEntry](/rules/lib/builtins/SymlinkEntry) -- [tag_class](/rules/lib/builtins/tag_class) -- [Target](/rules/lib/builtins/Target) -- [template_ctx](/rules/lib/builtins/template_ctx) -- [TemplateDict](/rules/lib/builtins/TemplateDict) -- [toolchain_type](/rules/lib/builtins/toolchain_type) -- [ToolchainContext](/rules/lib/builtins/ToolchainContext) -- [transition](/rules/lib/builtins/transition) -- [wasm_exec_result](/rules/lib/builtins/wasm_exec_result) -- [wasm_module](/rules/lib/builtins/wasm_module) +* [Action](./rules/lib/builtins/Action) +* [actions](./rules/lib/builtins/actions) +* [apple\_platform](./rules/lib/builtins/apple_platform) +* [Args](./rules/lib/builtins/Args) +* [Aspect](./rules/lib/builtins/Aspect) +* [Attribute](./rules/lib/builtins/Attribute) +* [bazel\_module](./rules/lib/builtins/bazel_module) +* [bazel\_module\_tags](./rules/lib/builtins/bazel_module_tags) +* [BuildSetting](./rules/lib/builtins/BuildSetting) +* [CcCompilationOutputs](./rules/lib/builtins/CcCompilationOutputs) +* [CcLinkingOutputs](./rules/lib/builtins/CcLinkingOutputs) +* [CompilationContext](./rules/lib/builtins/CompilationContext) +* [configuration](./rules/lib/builtins/configuration) +* [ctx](./rules/lib/builtins/ctx) +* [depset](./rules/lib/builtins/depset) +* [DirectoryExpander](./rules/lib/builtins/DirectoryExpander) +* [DottedVersion](./rules/lib/builtins/DottedVersion) +* [exec\_result](./rules/lib/builtins/exec_result) +* [ExecGroupCollection](./rules/lib/builtins/ExecGroupCollection) +* [ExecGroupContext](./rules/lib/builtins/ExecGroupContext) +* [ExecTransitionFactory](./rules/lib/builtins/ExecTransitionFactory) +* [ExpandedDirectory](./rules/lib/builtins/ExpandedDirectory) +* [extension\_metadata](./rules/lib/builtins/extension_metadata) +* [FeatureConfiguration](./rules/lib/builtins/FeatureConfiguration) +* [File](./rules/lib/builtins/File) +* [fragments](./rules/lib/builtins/fragments) +* [java\_annotation\_processing](./rules/lib/builtins/java_annotation_processing) +* [Label](./rules/lib/builtins/Label) +* [LateBoundDefault](./rules/lib/builtins/LateBoundDefault) +* [LibraryToLink](./rules/lib/builtins/LibraryToLink) +* [License](./rules/lib/builtins/License) +* [LinkerInput](./rules/lib/builtins/LinkerInput) +* [LinkingContext](./rules/lib/builtins/LinkingContext) +* [macro](./rules/lib/builtins/macro) +* [mapped\_root](./rules/lib/builtins/mapped_root) +* [module\_ctx](./rules/lib/builtins/module_ctx) +* [path](./rules/lib/builtins/path) +* [propagation\_ctx](./rules/lib/builtins/propagation_ctx) +* [Provider](./rules/lib/builtins/Provider) +* [repo\_metadata](./rules/lib/builtins/repo_metadata) +* [repository\_ctx](./rules/lib/builtins/repository_ctx) +* [repository\_os](./rules/lib/builtins/repository_os) +* [repository\_rule](./rules/lib/builtins/repository_rule) +* [root](./rules/lib/builtins/root) +* [rule](./rules/lib/builtins/rule) +* [rule\_attributes](./rules/lib/builtins/rule_attributes) +* [runfiles](./rules/lib/builtins/runfiles) +* [struct](./rules/lib/builtins/struct) +* [Subrule](./rules/lib/builtins/Subrule) +* [subrule\_ctx](./rules/lib/builtins/subrule_ctx) +* [SymlinkEntry](./rules/lib/builtins/SymlinkEntry) +* [tag\_class](./rules/lib/builtins/tag_class) +* [Target](./rules/lib/builtins/Target) +* [template\_ctx](./rules/lib/builtins/template_ctx) +* [TemplateDict](./rules/lib/builtins/TemplateDict) +* [toolchain\_type](./rules/lib/builtins/toolchain_type) +* [ToolchainContext](./rules/lib/builtins/ToolchainContext) +* [transition](./rules/lib/builtins/transition) +* [wasm\_exec\_result](./rules/lib/builtins/wasm_exec_result) +* [wasm\_module](./rules/lib/builtins/wasm_module) \ No newline at end of file diff --git a/rules/lib/builtins/Action.mdx b/rules/lib/builtins/Action.mdx index 606546f..e2d7de8 100644 --- a/rules/lib/builtins/Action.mdx +++ b/rules/lib/builtins/Action.mdx @@ -2,59 +2,56 @@ title: 'Action' --- -# Action -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java" %} -{% include "\_buttons.html" %} An action created during rule analysis. -This object is visible for the purpose of testing, and may be obtained from an `Actions` provider. It is normally not necessary to access `Action` objects or their fields within a rule's implementation function. You may instead want to see the [Rules page](https://bazel.build/extending/rules#actions) for a general discussion of how to use actions when defining custom rules, or the [API reference](../builtins/actions.html) for creating actions. +This object is visible for the purpose of testing, and may be obtained from an `Actions` provider. It is normally not necessary to access `Action` objects or their fields within a rule's implementation function. You may instead want to see the [Rules page](https://bazel.build/extending/rules#actions) for a general discussion of how to use actions when defining custom rules, or the [API reference](../builtins/actions.mdx) for creating actions. Some fields of this object are only applicable for certain kinds of actions. Fields that are inapplicable are set to `None`. ## Members -- [args](#args) -- [argv](#argv) -- [content](#content) -- [env](#env) -- [inputs](#inputs) -- [mnemonic](#mnemonic) -- [outputs](#outputs) -- [substitutions](#substitutions) +* [args](#args) +* [argv](#argv) +* [content](#content) +* [env](#env) +* [inputs](#inputs) +* [mnemonic](#mnemonic) +* [outputs](#outputs) +* [substitutions](#substitutions) ## args -``` rule-signature +``` sequence Action.args ``` -A list of frozen [Args](../builtins/Args.html) objects containing information about the action arguments. These objects contain accurate argument information, including arguments involving expanded action output directories. However, [Args](../builtins/Args.html) objects are not readable in the analysis phase. For a less accurate account of arguments which is available in the analysis phase, see [argv](#argv). +A list of frozen [Args](../builtins/Args.mdx) objects containing information about the action arguments. These objects contain accurate argument information, including arguments involving expanded action output directories. However, [Args](../builtins/Args.mdx) objects are not readable in the analysis phase. For a less accurate account of arguments which is available in the analysis phase, see [argv](#argv). Note that some types of actions do not yet support exposure of this field. For such action types, this is `None`. May return `None`. ## argv -``` rule-signature +``` sequence Action.argv ``` -For actions created by [ctx.actions.run()](../builtins/actions.html#run) or [ctx.actions.run_shell()](../builtins/actions.html#run_shell) an immutable list of the arguments for the command line to be executed. Note that for shell actions the first two arguments will be the shell path and `"-c"`. +For actions created by [ctx.actions.run()](../builtins/actions.html#run) or [ctx.actions.run\_shell()](../builtins/actions.html#run_shell) an immutable list of the arguments for the command line to be executed. Note that for shell actions the first two arguments will be the shell path and `"-c"`. May return `None`. ## content -``` rule-signature +``` string Action.content ``` -For actions created by [ctx.actions.write()](../builtins/actions.html#write) or [ctx.actions.expand_template()](../builtins/actions.html#expand_template), the contents of the file to be written, if those contents can be computed during the analysis phase. The value is `None` if the contents cannot be determined until the execution phase, such as when a directory in an [Args](../builtins/Args.html) object needs to be expanded. +For actions created by [ctx.actions.write()](../builtins/actions.html#write) or [ctx.actions.expand\_template()](../builtins/actions.html#expand_template), the contents of the file to be written, if those contents can be computed during the analysis phase. The value is `None` if the contents cannot be determined until the execution phase, such as when a directory in an [Args](../builtins/Args.mdx) object needs to be expanded. May return `None`. ## env -``` rule-signature +``` dict Action.env ``` @@ -62,7 +59,7 @@ The 'fixed' environment variables for this action. This includes only environmen ## inputs -``` rule-signature +``` depset Action.inputs ``` @@ -70,7 +67,7 @@ A set of the input files of this action. ## mnemonic -``` rule-signature +``` string Action.mnemonic ``` @@ -78,7 +75,7 @@ The mnemonic for this action. ## outputs -``` rule-signature +``` depset Action.outputs ``` @@ -86,9 +83,9 @@ A set of the output files of this action. ## substitutions -``` rule-signature +``` dict Action.substitutions ``` -For actions created by [ctx.actions.expand_template()](../builtins/actions.html#expand_template), an immutable dict holding the substitution mapping. -May return `None`. +For actions created by [ctx.actions.expand\_template()](../builtins/actions.html#expand_template), an immutable dict holding the substitution mapping. +May return `None`. \ No newline at end of file diff --git a/rules/lib/builtins/Args.mdx b/rules/lib/builtins/Args.mdx index 9157f4a..a1f8241 100644 --- a/rules/lib/builtins/Args.mdx +++ b/rules/lib/builtins/Args.mdx @@ -2,13 +2,10 @@ title: 'Args' --- -# Args -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java" %} -{% include "\_buttons.html" %} An object that encapsulates, in a memory-efficient way, the data needed to build part or all of a command line. -It often happens that an action requires a large command line containing values accumulated from transitive dependencies. For example, a linker command line might list every object file needed by all of the libraries being linked. It is best practice to store such transitive data in [`depset`](../builtins/depset.html)s, so that they can be shared by multiple targets. However, if the rule author had to convert these depsets into lists of strings in order to construct an action command line, it would defeat this memory-sharing optimization. +It often happens that an action requires a large command line containing values accumulated from transitive dependencies. For example, a linker command line might list every object file needed by all of the libraries being linked. It is best practice to store such transitive data in [`depset`](../builtins/depset.mdx)s, so that they can be shared by multiple targets. However, if the rule author had to convert these depsets into lists of strings in order to construct an action command line, it would defeat this memory-sharing optimization. For this reason, the action-constructing functions accept `Args` objects in addition to strings. Each `Args` object represents a concatenation of strings and depsets, with optional transformations for manipulating the data. `Args` objects do not process the depsets they encapsulate until the execution phase, when it comes time to calculate the command line. This helps defer any expensive copying until after the analysis phase is complete. See the [Optimizing Performance](https://bazel.build/rules/performance) page for more information. @@ -16,10 +13,7 @@ For this reason, the action-constructing functions accept `Args` objects in addi The `map_each` feature allows you to customize how items are transformed into strings. If you do not provide a `map_each` function, the standard conversion is as follows: -- Values that are already strings are left as-is. -- [`File`](../builtins/File.html) objects are turned into their `File.path` values. -- [`Label`](../builtins/Label.html) objects are turned into a string representation that resolves back to the same object when resolved in the context of the main repository. If possible, the string representation uses the apparent name of a repository in favor of the repository's canonical name, which makes this representation suited for use in BUILD files. While the exact form of the representation is not guaranteed, typical examples are `//foo:bar`, `@repo//foo:bar` and `@@canonical_name+//foo:bar.bzl`. -- All other types are turned into strings in an *unspecified* manner. For this reason, you should avoid passing values that are not of string or `File` type to `add()`, and if you pass them to `add_all()` or `add_joined()` then you should provide a `map_each` function. +* Values that are already strings are left as-is.* [`File`](../builtins/File.mdx) objects are turned into their `File.path` values.* [`Label`](../builtins/Label.mdx) objects are turned into a string representation that resolves back to the same object when resolved in the context of the main repository. If possible, the string representation uses the apparent name of a repository in favor of the repository's canonical name, which makes this representation suited for use in BUILD files. While the exact form of the representation is not guaranteed, typical examples are `//foo:bar`, `@repo//foo:bar` and `@@canonical_name+//foo:bar.bzl`.* All other types are turned into strings in an *unspecified* manner. For this reason, you should avoid passing values that are not of string or `File` type to `add()`, and if you pass them to `add_all()` or `add_joined()` then you should provide a `map_each` function. When using string formatting (`format`, `format_each`, and `format_joined` params of the `add*()` methods), the format template is interpreted in the same way as `%`-substitution on strings, except that the template must have exactly one substitution placeholder and it must be `%s`. Literal percents may be escaped as `%%`. Formatting is applied after the value is converted to a string as per the above. @@ -29,13 +23,13 @@ If the size of the command line can grow longer than the maximum size allowed by Example: Suppose we wanted to generate the command line: - - --foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz +``` +--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz +``` We could use the following `Args` object: -``` python - +``` # foo_deps and bar_deps are depsets containing # File objects for the foo and bar .txt files. args = ctx.actions.args() @@ -51,15 +45,15 @@ ctx.actions.run( ## Members -- [add](#add) -- [add_all](#add_all) -- [add_joined](#add_joined) -- [set_param_file_format](#set_param_file_format) -- [use_param_file](#use_param_file) +* [add](#add) +* [add\_all](#add_all) +* [add\_joined](#add_joined) +* [set\_param\_file\_format](#set_param_file_format) +* [use\_param\_file](#use_param_file) ## add -``` rule-signature +``` Args Args.add(arg_name_or_value, value=unbound, *, format=None) ``` @@ -67,36 +61,15 @@ Appends an argument to this command line. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="add.arg_name_or_value"><code>arg_name_or_value</code></td> -<td>required<br /> -If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the value without any processing. If only one positional parameter is passed, it is interpreted as <code>value</code> (see below).</td> -</tr> -<tr> -<td id="add.value"><code>value</code></td> -<td>default is <code>unbound</code><br /> -The object to append. It will be converted to a string using the standard conversion mentioned above. Since there is no <code>map_each</code> parameter for this function, <code>value</code> should be either a string or a <code>File</code>. A list, tuple, depset, or directory <code>File</code> must be passed to <a href="#add_all"><code>add_all()</code> or</a> <a href="#add_joined"><code>add_joined()</code></a> instead of this method.</td> -</tr> -<tr> -<td id="add.format"><code>format</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A format string pattern, to be applied to the stringified version of <code>value</code>.</td> -</tr> -</tbody> -</table> - -## add_all - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `arg_name_or_value` | required If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the value without any processing. If only one positional parameter is passed, it is interpreted as `value` (see below). | +| `value` | default is `unbound` The object to append. It will be converted to a string using the standard conversion mentioned above. Since there is no `map_each` parameter for this function, `value` should be either a string or a `File`. A list, tuple, depset, or directory `File` must be passed to [`add_all()` or [`add_joined()`](#add_joined) instead of this method.](#add_all) | +| `format` | [string](../core/string.mdx); or `None`; default is `None` A format string pattern, to be applied to the stringified version of `value`. | + +## add\_all + +``` Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False) ``` @@ -104,101 +77,29 @@ Appends multiple arguments to this command line. The items are processed lazily Most of the processing occurs over a list of arguments to be appended, as per the following steps: -1. Each directory `File` item is replaced by all `File`s recursively contained in that directory. -2. If `map_each` is given, it is applied to each item, and the resulting lists of strings are concatenated to form the initial argument list. Otherwise, the initial argument list is the result of applying the standard conversion to each item. -3. Each argument in the list is formatted with `format_each`, if present. -4. If `uniquify` is true, duplicate arguments are removed. The first occurrence is the one that remains. -5. If a `before_each` string is given, it is inserted as a new argument before each existing argument in the list. This effectively doubles the number of arguments to be appended by this point. -6. Except in the case that the list is empty and `omit_if_empty` is true (the default), the arg name and `terminate_with` are inserted as the first and last arguments, respectively, if they are given. +1. Each directory `File` item is replaced by all `File`s recursively contained in that directory. +2. If `map_each` is given, it is applied to each item, and the resulting lists of strings are concatenated to form the initial argument list. Otherwise, the initial argument list is the result of applying the standard conversion to each item.- Each argument in the list is formatted with `format_each`, if present.- If `uniquify` is true, duplicate arguments are removed. The first occurrence is the one that remains.- If a `before_each` string is given, it is inserted as a new argument before each existing argument in the list. This effectively doubles the number of arguments to be appended by this point.- Except in the case that the list is empty and `omit_if_empty` is true (the default), the arg name and `terminate_with` are inserted as the first and last arguments, respectively, if they are given. Note that empty strings are valid arguments that are subject to all these processing steps. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="add_all.arg_name_or_values"><code>arg_name_or_values</code></td> -<td>required<br /> -If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the <code>values</code> as a separate argument without any processing. This arg name will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below).</td> -</tr> -<tr> -<td id="add_all.values"><code>values</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>unbound</code><br /> -The list, tuple, or depset whose items will be appended.</td> -</tr> -<tr> -<td id="add_all.map_each"><code>map_each</code></td> -<td>callable; or <code>None</code>; -default is <code>None</code><br /> -A function that converts each item to zero or more strings, which may be further processed before appending. If this param is not provided, the standard conversion is used. -<p>The function is passed either one or two positional arguments: the item to convert, followed by an optional <a href="../builtins/DirectoryExpander.html"><code>DirectoryExpander</code></a>. The second argument will be passed only if the supplied function is user-defined (not built-in) and declares more than one parameter.</p> -<p>The return value's type depends on how many arguments are to be produced for the item:</p> -<ul> -<li>In the common case when each item turns into one string, the function should return that string.</li> -<li>If the item is to be filtered out entirely, the function should return <code>None</code>.</li> -<li>If the item turns into multiple strings, the function returns a list of those strings.</li> -</ul> -Returning a single string or <code>None</code> has the same effect as returning a list of length 1 or length 0 respectively. However, it is more efficient and readable to avoid creating a list where it is not needed. -<p>Ordinarily, items that are directories are automatically expanded to their contents when <code>expand_directories=True</code> is set. However, this will not expand directories contained inside other values -- for instance, when the items are structs that have directories as fields. In this situation, the <code>DirectoryExpander</code> argument can be applied to manually obtain the files of a given directory.</p> -<p>To avoid unintended retention of large analysis-phase data structures into the execution phase, the <code>map_each</code> function must be declared by a top-level <code>def</code> statement; it may not be a nested function closure by default.</p> -<p><em>Warning:</em> <a href="../globals/all.html#print"><code>print()</code></a> statements that are executed during the call to <code>map_each</code> will not produce any visible output.</p></td> -</tr> -<tr> -<td id="add_all.format_each"><code>format_each</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -An optional format string pattern, applied to each string returned by the <code>map_each</code> function. The format string must have exactly one '%s' placeholder.</td> -</tr> -<tr> -<td id="add_all.before_each"><code>before_each</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -An optional argument to append before each argument derived from <code>values</code> is appended.</td> -</tr> -<tr> -<td id="add_all.omit_if_empty"><code>omit_if_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -If true, if there are no arguments derived from <code>values</code> to be appended, then all further processing is suppressed and the command line will be unchanged. If false, the arg name and <code>terminate_with</code>, if provided, will still be appended regardless of whether or not there are other arguments.</td> -</tr> -<tr> -<td id="add_all.uniquify"><code>uniquify</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, duplicate arguments that are derived from <code>values</code> will be omitted. Only the first occurrence of each argument will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items.</td> -</tr> -<tr> -<td id="add_all.expand_directories"><code>expand_directories</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -If true, any directories in <code>values</code> will be expanded to a flat list of files. This happens before <code>map_each</code> is applied.</td> -</tr> -<tr> -<td id="add_all.terminate_with"><code>terminate_with</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -An optional argument to append after all other arguments. This argument will not be added if <code>omit_if_empty</code> is true (the default) and no other items are appended (as happens if <code>values</code> is empty or all of its items are filtered).</td> -</tr> -<tr> -<td id="add_all.allow_closure"><code>allow_closure</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase.</td> -</tr> -</tbody> -</table> - -## add_joined - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `arg_name_or_values` | required If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the `values` as a separate argument without any processing. This arg name will not be added if `omit_if_empty` is true (the default) and no other items are appended (as happens if `values` is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as `values` (see below). | +| `values` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `unbound` The list, tuple, or depset whose items will be appended. | +| `map_each` | callable; or `None`; default is `None` A function that converts each item to zero or more strings, which may be further processed before appending. If this param is not provided, the standard conversion is used. The function is passed either one or two positional arguments: the item to convert, followed by an optional [`DirectoryExpander`](../builtins/DirectoryExpander.mdx). The second argument will be passed only if the supplied function is user-defined (not built-in) and declares more than one parameter. The return value's type depends on how many arguments are to be produced for the item: * In the common case when each item turns into one string, the function should return that string.* If the item is to be filtered out entirely, the function should return `None`.* If the item turns into multiple strings, the function returns a list of those strings. Returning a single string or `None` has the same effect as returning a list of length 1 or length 0 respectively. However, it is more efficient and readable to avoid creating a list where it is not needed. Ordinarily, items that are directories are automatically expanded to their contents when `expand_directories=True` is set. However, this will not expand directories contained inside other values -- for instance, when the items are structs that have directories as fields. In this situation, the `DirectoryExpander` argument can be applied to manually obtain the files of a given directory. To avoid unintended retention of large analysis-phase data structures into the execution phase, the `map_each` function must be declared by a top-level `def` statement; it may not be a nested function closure by default. *Warning:* [`print()`](../globals/all.html#print) statements that are executed during the call to `map_each` will not produce any visible output. | +| `format_each` | [string](../core/string.mdx); or `None`; default is `None` An optional format string pattern, applied to each string returned by the `map_each` function. The format string must have exactly one '%s' placeholder. | +| `before_each` | [string](../core/string.mdx); or `None`; default is `None` An optional argument to append before each argument derived from `values` is appended. | +| `omit_if_empty` | [bool](../core/bool.mdx); default is `True` If true, if there are no arguments derived from `values` to be appended, then all further processing is suppressed and the command line will be unchanged. If false, the arg name and `terminate_with`, if provided, will still be appended regardless of whether or not there are other arguments. | +| `uniquify` | [bool](../core/bool.mdx); default is `False` If true, duplicate arguments that are derived from `values` will be omitted. Only the first occurrence of each argument will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if `map_each` emits the same string for multiple items. | +| `expand_directories` | [bool](../core/bool.mdx); default is `True` If true, any directories in `values` will be expanded to a flat list of files. This happens before `map_each` is applied. | +| `terminate_with` | [string](../core/string.mdx); or `None`; default is `None` An optional argument to append after all other arguments. This argument will not be added if `omit_if_empty` is true (the default) and no other items are appended (as happens if `values` is empty or all of its items are filtered). | +| `allow_closure` | [bool](../core/bool.mdx); default is `False` If true, allows the use of closures in function parameters like `map_each`. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. | + +## add\_joined + +``` Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False) ``` @@ -210,79 +111,22 @@ If after filtering there are no strings to join into an argument, and if `omit_i ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="add_joined.arg_name_or_values"><code>arg_name_or_values</code></td> -<td>required<br /> -If two positional parameters are passed this is interpreted as the arg name. The arg name is added before <code>values</code> without any processing. This arg will not be added if <code>omit_if_empty</code> is true (the default) and there are no strings derived from <code>values</code> to join together (which can happen if <code>values</code> is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as <code>values</code> (see below).</td> -</tr> -<tr> -<td id="add_joined.values"><code>values</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>unbound</code><br /> -The list, tuple, or depset whose items will be joined.</td> -</tr> -<tr> -<td id="add_joined.join_with"><code>join_with</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A delimiter string used to join together the strings obtained from applying <code>map_each</code> and <code>format_each</code>, in the same manner as <a href="../core/string.html#join"><code>string.join()</code></a>.</td> -</tr> -<tr> -<td id="add_joined.map_each"><code>map_each</code></td> -<td>callable; or <code>None</code>; -default is <code>None</code><br /> -Same as for <a href="#add_all.map_each"><code>add_all</code></a>.</td> -</tr> -<tr> -<td id="add_joined.format_each"><code>format_each</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Same as for <a href="#add_all.format_each"><code>add_all</code></a>.</td> -</tr> -<tr> -<td id="add_joined.format_joined"><code>format_joined</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder.</td> -</tr> -<tr> -<td id="add_joined.omit_if_empty"><code>omit_if_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -If true, if there are no strings to join together (either because <code>values</code> is empty or all its items are filtered), then all further processing is suppressed and the command line will be unchanged. If false, then even if there are no strings to join together, two arguments will be appended: the arg name followed by an empty string (which is the logical join of zero strings).</td> -</tr> -<tr> -<td id="add_joined.uniquify"><code>uniquify</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Same as for <a href="#add_all.uniquify"><code>add_all</code></a>.</td> -</tr> -<tr> -<td id="add_joined.expand_directories"><code>expand_directories</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -Same as for <a href="#add_all.expand_directories"><code>add_all</code></a>.</td> -</tr> -<tr> -<td id="add_joined.allow_closure"><code>allow_closure</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Same as for <a href="#add_all.allow_closure"><code>add_all</code></a>.</td> -</tr> -</tbody> -</table> - -## set_param_file_format - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `arg_name_or_values` | required If two positional parameters are passed this is interpreted as the arg name. The arg name is added before `values` without any processing. This arg will not be added if `omit_if_empty` is true (the default) and there are no strings derived from `values` to join together (which can happen if `values` is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as `values` (see below). | +| `values` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `unbound` The list, tuple, or depset whose items will be joined. | +| `join_with` | [string](../core/string.mdx); required A delimiter string used to join together the strings obtained from applying `map_each` and `format_each`, in the same manner as [`string.join()`](../core/string.html#join). | +| `map_each` | callable; or `None`; default is `None` Same as for [`add_all`](#add_all.map_each). | +| `format_each` | [string](../core/string.mdx); or `None`; default is `None` Same as for [`add_all`](#add_all.format_each). | +| `format_joined` | [string](../core/string.mdx); or `None`; default is `None` An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. | +| `omit_if_empty` | [bool](../core/bool.mdx); default is `True` If true, if there are no strings to join together (either because `values` is empty or all its items are filtered), then all further processing is suppressed and the command line will be unchanged. If false, then even if there are no strings to join together, two arguments will be appended: the arg name followed by an empty string (which is the logical join of zero strings). | +| `uniquify` | [bool](../core/bool.mdx); default is `False` Same as for [`add_all`](#add_all.uniquify). | +| `expand_directories` | [bool](../core/bool.mdx); default is `True` Same as for [`add_all`](#add_all.expand_directories). | +| `allow_closure` | [bool](../core/bool.mdx); default is `False` Same as for [`add_all`](#add_all.allow_closure). | + +## set\_param\_file\_format + +``` Args Args.set_param_file_format(format) ``` @@ -290,32 +134,13 @@ Sets the format of the param file, if one is used ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="set_param_file_format.format"><code>format</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Must be one of: -<ul> -<li>"multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it.</li> -<li>"shell": Same as "multiline", but the items are shell-quoted</li> -<li>"flag_per_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library.</li> -</ul> -<p>The format defaults to "shell" if not called.</p></td> -</tr> -</tbody> -</table> - -## use_param_file - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `format` | [string](../core/string.mdx); required Must be one of: * "multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it. * "shell": Same as "multiline", but the items are shell-quoted * "flag\_per\_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library. The format defaults to "shell" if not called. | + +## use\_param\_file + +``` Args Args.use_param_file(param_file_arg, *, use_always=False) ``` @@ -325,26 +150,7 @@ Bazel may choose to elide writing the params file to the output tree during exec ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="use_param_file.param_file_arg"><code>param_file_arg</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A format string with a single "%s". If the args are spilled to a params file then they are replaced with an argument consisting of this string formatted with the path of the params file. -<p>For example, if the args are spilled to a params file "params.txt", then specifying "--file=%s" would cause the action command line to contain "--file=params.txt".</p></td> -</tr> -<tr> -<td id="use_param_file.use_always"><code>use_always</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether to always spill the args to a params file. If false, bazel will decide whether the arguments need to be spilled based on your system and arg length.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `param_file_arg` | [string](../core/string.mdx); required A format string with a single "%s". If the args are spilled to a params file then they are replaced with an argument consisting of this string formatted with the path of the params file. For example, if the args are spilled to a params file "params.txt", then specifying "--file=%s" would cause the action command line to contain "--file=params.txt". | +| `use_always` | [bool](../core/bool.mdx); default is `False` Whether to always spill the args to a params file. If false, bazel will decide whether the arguments need to be spilled based on your system and arg length. | \ No newline at end of file diff --git a/rules/lib/builtins/Aspect.mdx b/rules/lib/builtins/Aspect.mdx index 6fbc509..b9383df 100644 --- a/rules/lib/builtins/Aspect.mdx +++ b/rules/lib/builtins/Aspect.mdx @@ -2,9 +2,6 @@ title: 'Aspect' --- -# Aspect -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java" %} -{% include "\_buttons.html" %} For more information about Aspects, please consult the -[documentation of the aspect function](../globals/bzl.html#aspect) or the [introduction to Aspects](https://bazel.build/extending/aspects). +[documentation of the aspect function](../globals/bzl.html#aspect) or the [introduction to Aspects](https://bazel.build/extending/aspects). \ No newline at end of file diff --git a/rules/lib/builtins/Attribute.mdx b/rules/lib/builtins/Attribute.mdx index cfb9b15..8dc8b2d 100644 --- a/rules/lib/builtins/Attribute.mdx +++ b/rules/lib/builtins/Attribute.mdx @@ -2,8 +2,5 @@ title: 'Attribute' --- -# Attribute -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java" %} -{% include "\_buttons.html" %} -Representation of a definition of an attribute. Use the [attr](../toplevel/attr.html) module to create an Attribute. They are only for use with a [rule](../globals/bzl.html#rule) or an [aspect](../globals/bzl.html#aspect). +Representation of a definition of an attribute. Use the [attr](../toplevel/attr.mdx) module to create an Attribute. They are only for use with a [rule](../globals/bzl.html#rule) or an [aspect](../globals/bzl.html#aspect). \ No newline at end of file diff --git a/rules/lib/builtins/BuildSetting.mdx b/rules/lib/builtins/BuildSetting.mdx index 11be963..896632c 100644 --- a/rules/lib/builtins/BuildSetting.mdx +++ b/rules/lib/builtins/BuildSetting.mdx @@ -2,8 +2,5 @@ title: 'BuildSetting' --- -# BuildSetting -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} -{% include "\_buttons.html" %} -The descriptor for a single piece of configuration information. If configuration is a key-value map of settings like {'cpu': 'ppc', 'copt': '-DFoo'}, this describes a single entry in that map. +The descriptor for a single piece of configuration information. If configuration is a key-value map of settings like \{'cpu': 'ppc', 'copt': '-DFoo'\}, this describes a single entry in that map. \ No newline at end of file diff --git a/rules/lib/builtins/CcCompilationOutputs.mdx b/rules/lib/builtins/CcCompilationOutputs.mdx index e291103..ca1c2e4 100644 --- a/rules/lib/builtins/CcCompilationOutputs.mdx +++ b/rules/lib/builtins/CcCompilationOutputs.mdx @@ -2,29 +2,26 @@ title: 'CcCompilationOutputs' --- -# CcCompilationOutputs -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationOutputsApi.java" %} -{% include "\_buttons.html" %} Helper class containing CC compilation outputs. ## Members -- [objects](#objects) -- [pic_objects](#pic_objects) +* [objects](#objects) +* [pic\_objects](#pic_objects) ## objects -``` rule-signature +``` sequence CcCompilationOutputs.objects ``` Non-PIC object files. -## pic_objects +## pic\_objects -``` rule-signature +``` sequence CcCompilationOutputs.pic_objects ``` -PIC object files. +PIC object files. \ No newline at end of file diff --git a/rules/lib/builtins/CcLinkingOutputs.mdx b/rules/lib/builtins/CcLinkingOutputs.mdx index 975708f..b8bb713 100644 --- a/rules/lib/builtins/CcLinkingOutputs.mdx +++ b/rules/lib/builtins/CcLinkingOutputs.mdx @@ -2,31 +2,28 @@ title: 'CcLinkingOutputs' --- -# CcLinkingOutputs -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java" %} -{% include "\_buttons.html" %} Helper class containing CC compilation outputs. ## Members -- [executable](#executable) -- [library_to_link](#library_to_link) +* [executable](#executable) +* [library\_to\_link](#library_to_link) ## executable -``` rule-signature +``` File CcLinkingOutputs.executable ``` Represents the linked executable. May return `None`. -## library_to_link +## library\_to\_link -``` rule-signature +``` LibraryToLink CcLinkingOutputs.library_to_link ``` `LibraryToLink` for including these outputs in further linking. -May return `None`. +May return `None`. \ No newline at end of file diff --git a/rules/lib/builtins/CompilationContext.mdx b/rules/lib/builtins/CompilationContext.mdx index 27c5f88..ea67aab 100644 --- a/rules/lib/builtins/CompilationContext.mdx +++ b/rules/lib/builtins/CompilationContext.mdx @@ -2,79 +2,76 @@ title: 'CompilationContext' --- -# CompilationContext -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java" %} -{% include "\_buttons.html" %} Immutable store of information needed for C++ compilation that is aggregated across dependencies. ## Members -- [defines](#defines) -- [direct_headers](#direct_headers) -- [direct_private_headers](#direct_private_headers) -- [direct_public_headers](#direct_public_headers) -- [direct_textual_headers](#direct_textual_headers) -- [external_includes](#external_includes) -- [framework_includes](#framework_includes) -- [headers](#headers) -- [includes](#includes) -- [local_defines](#local_defines) -- [quote_includes](#quote_includes) -- [system_includes](#system_includes) -- [validation_artifacts](#validation_artifacts) +* [defines](#defines) +* [direct\_headers](#direct_headers) +* [direct\_private\_headers](#direct_private_headers) +* [direct\_public\_headers](#direct_public_headers) +* [direct\_textual\_headers](#direct_textual_headers) +* [external\_includes](#external_includes) +* [framework\_includes](#framework_includes) +* [headers](#headers) +* [includes](#includes) +* [local\_defines](#local_defines) +* [quote\_includes](#quote_includes) +* [system\_includes](#system_includes) +* [validation\_artifacts](#validation_artifacts) ## defines -``` rule-signature +``` depset CompilationContext.defines ``` Returns the set of defines needed to compile this target. Each define is a string. These values are propagated to the target's transitive dependents, that is, any rules that depend on this target. -## direct_headers +## direct\_headers -``` rule-signature +``` list CompilationContext.direct_headers ``` Returns the list of modular headers that are declared by this target. This includes both public headers (such as those listed in "hdrs") and private headers (such as those listed in "srcs"). -## direct_private_headers +## direct\_private\_headers -``` rule-signature +``` list CompilationContext.direct_private_headers ``` Returns the list of modular private headers (those listed in "srcs") that are declared by this target. -## direct_public_headers +## direct\_public\_headers -``` rule-signature +``` list CompilationContext.direct_public_headers ``` Returns the list of modular public headers (those listed in "hdrs") that are declared by this target. -## direct_textual_headers +## direct\_textual\_headers -``` rule-signature +``` list CompilationContext.direct_textual_headers ``` Returns the list of textual headers that are declared by this target. -## external_includes +## external\_includes -``` rule-signature +``` depset CompilationContext.external_includes ``` Returns the set of search paths (as strings) for external header files referenced by angle bracket. Usually passed with -isystem. -## framework_includes +## framework\_includes -``` rule-signature +``` depset CompilationContext.framework_includes ``` @@ -82,7 +79,7 @@ Returns the set of search paths (as strings) for framework header files. Usually ## headers -``` rule-signature +``` depset CompilationContext.headers ``` @@ -90,40 +87,40 @@ Returns the set of headers needed to compile this target. ## includes -``` rule-signature +``` depset CompilationContext.includes ``` Returns the set of search paths (as strings) for header files referenced both by angle bracket and quotes. Usually passed with -I. -## local_defines +## local\_defines -``` rule-signature +``` depset CompilationContext.local_defines ``` Returns the set of defines needed to compile this target. Each define is a string. These values are not propagated to the target's transitive dependents. -## quote_includes +## quote\_includes -``` rule-signature +``` depset CompilationContext.quote_includes ``` -Returns the set of search paths (as strings) for header files referenced by quotes, e.g. \#include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. +Returns the set of search paths (as strings) for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. -## system_includes +## system\_includes -``` rule-signature +``` depset CompilationContext.system_includes ``` -Returns the set of search paths (as strings) for header files referenced by angle brackets, e.g. \#include \<foo/bar/header.h\>. They can be either relative to the exec root or absolute. Usually passed with -isystem. +Returns the set of search paths (as strings) for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. -## validation_artifacts +## validation\_artifacts -``` rule-signature +``` depset CompilationContext.validation_artifacts ``` -Returns the set of validation artifacts. +Returns the set of validation artifacts. \ No newline at end of file diff --git a/rules/lib/builtins/DirectoryExpander.mdx b/rules/lib/builtins/DirectoryExpander.mdx index f2f90dd..e1de798 100644 --- a/rules/lib/builtins/DirectoryExpander.mdx +++ b/rules/lib/builtins/DirectoryExpander.mdx @@ -2,19 +2,16 @@ title: 'DirectoryExpander' --- -# DirectoryExpander -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java" %} -{% include "\_buttons.html" %} Expands directories created by [`ctx.actions.declare_directory`](../builtins/actions.html#declare_directory) during the execution phase. This is useful to expand directories in [`map_each`](../builtins/Args.html#add_all.map_each). ## Members -- [expand](#expand) +* [expand](#expand) ## expand -``` rule-signature +``` list DirectoryExpander.expand(file) ``` @@ -22,19 +19,6 @@ If the given `File` is a directory, this returns a list of `File`s recursively u ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="expand.file"><code>file</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The directory or file to expand.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `file` | [File](../builtins/File.mdx); required The directory or file to expand. | \ No newline at end of file diff --git a/rules/lib/builtins/DottedVersion.mdx b/rules/lib/builtins/DottedVersion.mdx index 0e665f3..9dcbb0f 100644 --- a/rules/lib/builtins/DottedVersion.mdx +++ b/rules/lib/builtins/DottedVersion.mdx @@ -2,39 +2,23 @@ title: 'DottedVersion' --- -# DottedVersion -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/DottedVersionApi.java" %} -{% include "\_buttons.html" %} A value representing a version with multiple components, separated by periods, such as 1.2.3.4. ## Members -- [compare_to](#compare_to) +* [compare\_to](#compare_to) -## compare_to +## compare\_to -``` rule-signature +``` int DottedVersion.compare_to(other) ``` -Compares based on most significant (first) not-matching version component. So, for example, 1.2.3 \< 1.2.4 +Compares based on most significant (first) not-matching version component. So, for example, 1.2.3 < 1.2.4 ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="compare_to.other"><code>other</code></td> -<td><a href="../builtins/DottedVersion.html" class="anchor">DottedVersion</a>; -required<br /> -The other dotted version.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `other` | [DottedVersion](../builtins/DottedVersion.mdx); required The other dotted version. | \ No newline at end of file diff --git a/rules/lib/builtins/ExecGroupCollection.mdx b/rules/lib/builtins/ExecGroupCollection.mdx index 295bd7e..7b85845 100644 --- a/rules/lib/builtins/ExecGroupCollection.mdx +++ b/rules/lib/builtins/ExecGroupCollection.mdx @@ -2,8 +2,5 @@ title: 'ExecGroupCollection' --- -# ExecGroupCollection -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ExecGroupCollectionApi.java" %} -{% include "\_buttons.html" %} -Stores exec groups available to a given rule. +Stores exec groups available to a given rule. \ No newline at end of file diff --git a/rules/lib/builtins/ExecGroupContext.mdx b/rules/lib/builtins/ExecGroupContext.mdx index e68d256..c615c1f 100644 --- a/rules/lib/builtins/ExecGroupContext.mdx +++ b/rules/lib/builtins/ExecGroupContext.mdx @@ -2,20 +2,17 @@ title: 'ExecGroupContext' --- -# ExecGroupContext -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ExecGroupCollectionApi.java" %} -{% include "\_buttons.html" %} Stores information about an exec group. ## Members -- [toolchains](#toolchains) +* [toolchains](#toolchains) ## toolchains -``` rule-signature +``` ToolchainContext ExecGroupContext.toolchains ``` -Toolchains required for this exec group +Toolchains required for this exec group \ No newline at end of file diff --git a/rules/lib/builtins/ExecTransitionFactory.mdx b/rules/lib/builtins/ExecTransitionFactory.mdx index eb88c4d..eaaa96b 100644 --- a/rules/lib/builtins/ExecTransitionFactory.mdx +++ b/rules/lib/builtins/ExecTransitionFactory.mdx @@ -2,8 +2,5 @@ title: 'ExecTransitionFactory' --- -# ExecTransitionFactory -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} -{% include "\_buttons.html" %} -an execution transition. +an execution transition. \ No newline at end of file diff --git a/rules/lib/builtins/ExpandedDirectory.mdx b/rules/lib/builtins/ExpandedDirectory.mdx index 0477583..e5facf0 100644 --- a/rules/lib/builtins/ExpandedDirectory.mdx +++ b/rules/lib/builtins/ExpandedDirectory.mdx @@ -2,20 +2,17 @@ title: 'ExpandedDirectory' --- -# ExpandedDirectory -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ExpandedDirectoryApi.java" %} -{% include "\_buttons.html" %} Represents an expanded directory that makes the files within the it directly accessible. ## Members -- [children](#children) -- [directory](#directory) +* [children](#children) +* [directory](#directory) ## children -``` rule-signature +``` list ExpandedDirectory.children ``` @@ -23,8 +20,8 @@ Contains the files within the directory. ## directory -``` rule-signature +``` File ExpandedDirectory.directory ``` -The input directory that was expanded. +The input directory that was expanded. \ No newline at end of file diff --git a/rules/lib/builtins/FeatureConfiguration.mdx b/rules/lib/builtins/FeatureConfiguration.mdx index 32b0277..e1a30eb 100644 --- a/rules/lib/builtins/FeatureConfiguration.mdx +++ b/rules/lib/builtins/FeatureConfiguration.mdx @@ -2,8 +2,5 @@ title: 'FeatureConfiguration' --- -# FeatureConfiguration -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/FeatureConfigurationApi.java" %} -{% include "\_buttons.html" %} -Class used to construct command lines from CROSSTOOL features. +Class used to construct command lines from CROSSTOOL features. \ No newline at end of file diff --git a/rules/lib/builtins/File.mdx b/rules/lib/builtins/File.mdx index 1f12468..a2d7b08 100644 --- a/rules/lib/builtins/File.mdx +++ b/rules/lib/builtins/File.mdx @@ -2,31 +2,28 @@ title: 'File' --- -# File -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java" %} -{% include "\_buttons.html" %} This object is created during the analysis phase to represent a file or directory that will be read or written during the execution phase. It is not an open file handle, and cannot be used to directly read or write file contents. Rather, you use it to construct the action graph in a rule implementation function by passing it to action-creating functions. See the [Rules page](https://bazel.build/extending/rules#files) for more information. -When a `File` is passed to an [`Args`](../builtins/Args.html) object without using a `map_each` function, it is converted to a string by taking the value of its `path` field. +When a `File` is passed to an [`Args`](../builtins/Args.mdx) object without using a `map_each` function, it is converted to a string by taking the value of its `path` field. ## Members -- [basename](#basename) -- [dirname](#dirname) -- [extension](#extension) -- [is_directory](#is_directory) -- [is_source](#is_source) -- [is_symlink](#is_symlink) -- [owner](#owner) -- [path](#path) -- [root](#root) -- [short_path](#short_path) -- [tree_relative_path](#tree_relative_path) +* [basename](#basename) +* [dirname](#dirname) +* [extension](#extension) +* [is\_directory](#is_directory) +* [is\_source](#is_source) +* [is\_symlink](#is_symlink) +* [owner](#owner) +* [path](#path) +* [root](#root) +* [short\_path](#short_path) +* [tree\_relative\_path](#tree_relative_path) ## basename -``` rule-signature +``` string File.basename ``` @@ -34,7 +31,7 @@ The base name of this file. This is the name of the file inside the directory. ## dirname -``` rule-signature +``` string File.dirname ``` @@ -42,39 +39,39 @@ The name of the directory containing this file. It's taken from [path](#path) an ## extension -``` rule-signature +``` string File.extension ``` The file extension of this file, following (not including) the rightmost period. Empty string if the file's basename includes no periods. -## is_directory +## is\_directory -``` rule-signature +``` bool File.is_directory ``` -Returns true if this is a directory. This reflects the type the file was declared as (i.e. ctx.actions.declare_directory), not its type on the filesystem, which might differ. +Returns true if this is a directory. This reflects the type the file was declared as (i.e. ctx.actions.declare\_directory), not its type on the filesystem, which might differ. -## is_source +## is\_source -``` rule-signature +``` bool File.is_source ``` Returns true if this is a source file, i.e. it is not generated. -## is_symlink +## is\_symlink -``` rule-signature +``` bool File.is_symlink ``` -Returns true if this was declared as a symlink. This reflects the type the file was declared as (i.e. ctx.actions.declare_symlink), not its type on the filesystem, which might differ. +Returns true if this was declared as a symlink. This reflects the type the file was declared as (i.e. ctx.actions.declare\_symlink), not its type on the filesystem, which might differ. ## owner -``` rule-signature +``` Label File.owner ``` @@ -83,32 +80,32 @@ May return `None`. ## path -``` rule-signature +``` string File.path ``` -The execution path of this file, relative to the workspace's execution directory. It consists of two parts, an optional first part called the *root* (see also the [root](../builtins/root.html) module), and the second part which is the `short_path`. The root may be empty, which it usually is for non-generated files. For generated files it usually contains a configuration-specific path fragment that encodes things like the target CPU architecture that was used while building said file. Use the `short_path` for the path under which the file is mapped if it's in the runfiles of a binary. +The execution path of this file, relative to the workspace's execution directory. It consists of two parts, an optional first part called the *root* (see also the [root](../builtins/root.mdx) module), and the second part which is the `short_path`. The root may be empty, which it usually is for non-generated files. For generated files it usually contains a configuration-specific path fragment that encodes things like the target CPU architecture that was used while building said file. Use the `short_path` for the path under which the file is mapped if it's in the runfiles of a binary. ## root -``` rule-signature +``` root File.root ``` The root beneath which this file resides. -## short_path +## short\_path -``` rule-signature +``` string File.short_path ``` The path of this file relative to its root. This excludes the aforementioned *root*, i.e. configuration-specific fragments of the path. This is also the path under which the file is mapped if it's in the runfiles of a binary. -## tree_relative_path +## tree\_relative\_path -``` rule-signature +``` string File.tree_relative_path ``` -The path of this file relative to the root of the ancestor's tree, if the ancestor's [is_directory](#is_directory) field is true. `tree_relative_path` is only available for expanded files of a directory in an action command, i.e. [Args.add_all()](../builtins/Args.html#add_all). For other types of files, it is an error to access this field. +The path of this file relative to the root of the ancestor's tree, if the ancestor's [is\_directory](#is_directory) field is true. `tree_relative_path` is only available for expanded files of a directory in an action command, i.e. [Args.add\_all()](../builtins/Args.html#add_all). For other types of files, it is an error to access this field. \ No newline at end of file diff --git a/rules/lib/builtins/Label.mdx b/rules/lib/builtins/Label.mdx index e7669bc..cc8cfff 100644 --- a/rules/lib/builtins/Label.mdx +++ b/rules/lib/builtins/Label.mdx @@ -2,94 +2,77 @@ title: 'Label' --- -# Label -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/cmdline/Label.java" %} -{% include "\_buttons.html" %} A BUILD target identifier. For every `Label` instance `l`, the string representation `str(l)` has the property that `Label(str(l)) == l`, regardless of where the `Label()` call occurs. -When passed as positional arguments to `print()` or `fail()`, `Label` use a string representation optimized for human readability instead. This representation uses an [apparent repository name](/external/overview#apparent-repo-name) from the perspective of the main repository if possible. +When passed as positional arguments to `print()` or `fail()`, `Label` use a string representation optimized for human readability instead. This representation uses an [apparent repository name](./external/overview#apparent-repo-name) from the perspective of the main repository if possible. ## Members -- [Label](#Label) -- [name](#name) -- [package](#package) -- [relative](#relative) -- [repo_name](#repo_name) -- [same_package_label](#same_package_label) -- [workspace_name](#workspace_name) -- [workspace_root](#workspace_root) +* [Label](#Label) +* [name](#name) +* [package](#package) +* [relative](#relative) +* [repo\_name](#repo_name) +* [same\_package\_label](#same_package_label) +* [workspace\_name](#workspace_name) +* [workspace\_root](#workspace_root) ## Label -``` rule-signature +``` Label Label(input) ``` Converts a label string into a `Label` object, in the context of the package where the calling `.bzl` source file lives. If the given value is already a `Label`, it is returned unchanged. -For macros, a related function, [`native.package_relative_label()`](../toplevel/native.html#package_relative_label), converts the input into a `Label` in the context of the package currently being constructed. Use that function to mimic the string-to-label conversion that is automatically done by label-valued rule attributes. +For macros, a related function, `native.package_relative_label()`, converts the input into a `Label` in the context of the package currently being constructed. Use that function to mimic the string-to-label conversion that is automatically done by label-valued rule attributes. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="Label.input"><code>input</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; -required<br /> -The input label string or Label object. If a Label object is passed, it's returned as is.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `input` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); required The input label string or Label object. If a Label object is passed, it's returned as is. | ## name -``` rule-signature +``` string Label.name ``` The name of the target referred to by this label. For instance: -``` python +``` Label("@@foo//pkg/foo:abc").name == "abc" ``` ## package -``` rule-signature +``` string Label.package ``` The name of the package containing the target referred to by this label, without the repository name. For instance: -``` python +``` Label("@@repo//pkg/foo:abc").package == "pkg/foo" ``` ## relative -``` rule-signature +``` Label Label.relative(relName) ``` -**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` +**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` **Deprecated.** This method behaves surprisingly when used with an argument containing an apparent repo name. Prefer [`Label.same_package_label()`](#same_package_label), [`native.package_relative_label()`](../toplevel/native.html#package_relative_label), or [`Label()`](#Label) instead. Resolves a label that is either absolute (starts with `//`) or relative to the current package. If this label is in a remote repository, the argument will be resolved relative to that repository. If the argument contains a repository name, the current label is ignored and the argument is returned as-is, except that the repository name is rewritten if it is in the current repository mapping. Reserved labels will also be returned as-is. For example: -``` python - +``` Label("//foo/bar:baz").relative(":quux") == Label("//foo/bar:quux") Label("//foo/bar:baz").relative("//wiz:quux") == Label("//wiz:quux") Label("@repo//foo/bar:baz").relative("//wiz:quux") == Label("@repo//wiz:quux") @@ -97,47 +80,33 @@ Label("@repo//foo/bar:baz").relative("//visibility:public") == Label("//visibili Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@other//wiz:quux") ``` -If the repository mapping passed in is `{'@other' : '@remapped'}`, then the following remapping will take place: - -``` python +If the repository mapping passed in is `\{'@other' : '@remapped'\}`, then the following remapping will take place: +``` Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@remapped//wiz:quux") ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="relative.relName"><code>relName</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The label that will be resolved relative to this one.</td> -</tr> -</tbody> -</table> - -## repo_name - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `relName` | [string](../core/string.mdx); required | + +## repo\_name + +``` string Label.repo_name ``` The canonical name of the repository containing the target referred to by this label, without any leading at-signs (`@`). For instance, -``` python +``` Label("@@foo//bar:baz").repo_name == "foo" ``` -## same_package_label +## same\_package\_label -``` rule-signature +``` Label Label.same_package_label(target_name) ``` @@ -145,46 +114,33 @@ Creates a label in the same package as this label with the given target name. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="same_package_label.target_name"><code>target_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The target name of the new label.</td> -</tr> -</tbody> -</table> - -## workspace_name - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `target_name` | [string](../core/string.mdx); required | + +## workspace\_name + +``` string Label.workspace_name ``` -**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` +**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` **Deprecated.** The field name "workspace name" is a misnomer here; use the identically-behaving [`Label.repo_name`](#repo_name) instead. The canonical name of the repository containing the target referred to by this label, without any leading at-signs (`@`). For instance, -``` python +``` Label("@@foo//bar:baz").workspace_name == "foo" ``` -## workspace_root +## workspace\_root -``` rule-signature +``` string Label.workspace_root ``` Returns the execution root for the repository containing the target referred to by this label, relative to the execroot. For instance: -``` python -Label("@repo//pkg/foo:abc").workspace_root == "external/repo" ``` +Label("@repo//pkg/foo:abc").workspace_root == "external/repo" +``` \ No newline at end of file diff --git a/rules/lib/builtins/LateBoundDefault.mdx b/rules/lib/builtins/LateBoundDefault.mdx index b29aeb7..9dbc0bf 100644 --- a/rules/lib/builtins/LateBoundDefault.mdx +++ b/rules/lib/builtins/LateBoundDefault.mdx @@ -2,10 +2,7 @@ title: 'LateBoundDefault' --- -# LateBoundDefault -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java" %} -{% include "\_buttons.html" %} Represents a late-bound default attribute value of type 'Label'. The value of a LateBoundDefault is only resolvable in the context of a rule implementation function, and depends on the current build configuration. For example, a LateBoundDefault might represent the Label of the java toolchain in the current build configuration. -See [configuration_field](../globals/bzl.html#configuration_field) for example usage. +See [configuration\_field](../globals/bzl.html#configuration_field) for example usage. \ No newline at end of file diff --git a/rules/lib/builtins/LibraryToLink.mdx b/rules/lib/builtins/LibraryToLink.mdx index 324e45b..d424b9c 100644 --- a/rules/lib/builtins/LibraryToLink.mdx +++ b/rules/lib/builtins/LibraryToLink.mdx @@ -2,55 +2,52 @@ title: 'LibraryToLink' --- -# LibraryToLink -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/LibraryToLinkApi.java" %} -{% include "\_buttons.html" %} A library the user can link against. ## Members -- [alwayslink](#alwayslink) -- [dynamic_library](#dynamic_library) -- [interface_library](#interface_library) -- [lto_bitcode_files](#lto_bitcode_files) -- [objects](#objects) -- [pic_lto_bitcode_files](#pic_lto_bitcode_files) -- [pic_objects](#pic_objects) -- [pic_static_library](#pic_static_library) -- [resolved_symlink_dynamic_library](#resolved_symlink_dynamic_library) -- [resolved_symlink_interface_library](#resolved_symlink_interface_library) -- [static_library](#static_library) +* [alwayslink](#alwayslink) +* [dynamic\_library](#dynamic_library) +* [interface\_library](#interface_library) +* [lto\_bitcode\_files](#lto_bitcode_files) +* [objects](#objects) +* [pic\_lto\_bitcode\_files](#pic_lto_bitcode_files) +* [pic\_objects](#pic_objects) +* [pic\_static\_library](#pic_static_library) +* [resolved\_symlink\_dynamic\_library](#resolved_symlink_dynamic_library) +* [resolved\_symlink\_interface\_library](#resolved_symlink_interface_library) +* [static\_library](#static_library) ## alwayslink -``` rule-signature +``` bool LibraryToLink.alwayslink ``` -Whether to link the static library/objects in the --whole_archive block. +Whether to link the static library/objects in the --whole\_archive block. -## dynamic_library +## dynamic\_library -``` rule-signature +``` File LibraryToLink.dynamic_library ``` `Artifact` of dynamic library to be linked. Always used for runtime and used for linking if `interface_library` is not passed. May return `None`. -## interface_library +## interface\_library -``` rule-signature +``` File LibraryToLink.interface_library ``` `Artifact` of interface library to be linked. May return `None`. -## lto_bitcode_files +## lto\_bitcode\_files -``` rule-signature +``` sequence LibraryToLink.lto_bitcode_files ``` @@ -59,63 +56,63 @@ May return `None`. ## objects -``` rule-signature +``` sequence LibraryToLink.objects ``` `List` of object files in the library. May return `None`. -## pic_lto_bitcode_files +## pic\_lto\_bitcode\_files -``` rule-signature +``` sequence LibraryToLink.pic_lto_bitcode_files ``` `List` of pic LTO bitcode files in the library. May return `None`. -## pic_objects +## pic\_objects -``` rule-signature +``` sequence LibraryToLink.pic_objects ``` `List` of pic object files in the library. May return `None`. -## pic_static_library +## pic\_static\_library -``` rule-signature +``` File LibraryToLink.pic_static_library ``` `Artifact` of pic static library to be linked. May return `None`. -## resolved_symlink_dynamic_library +## resolved\_symlink\_dynamic\_library -``` rule-signature +``` File LibraryToLink.resolved_symlink_dynamic_library ``` The resolved `Artifact` of the dynamic library to be linked if `dynamic_library` is a symlink, otherwise this is None. May return `None`. -## resolved_symlink_interface_library +## resolved\_symlink\_interface\_library -``` rule-signature +``` File LibraryToLink.resolved_symlink_interface_library ``` The resolved `Artifact` of the interface library to be linked if `interface_library` is a symlink, otherwise this is None. May return `None`. -## static_library +## static\_library -``` rule-signature +``` File LibraryToLink.static_library ``` `Artifact` of static library to be linked. -May return `None`. +May return `None`. \ No newline at end of file diff --git a/rules/lib/builtins/License.mdx b/rules/lib/builtins/License.mdx index d4f5d9b..e977075 100644 --- a/rules/lib/builtins/License.mdx +++ b/rules/lib/builtins/License.mdx @@ -2,8 +2,5 @@ title: 'License' --- -# License -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LicenseApi.java" %} -{% include "\_buttons.html" %} -This API is deprecated and will be removed. Please do not depend on it. This object represents the value of a license attribute. +This API is deprecated and will be removed. Please do not depend on it. This object represents the value of a license attribute. \ No newline at end of file diff --git a/rules/lib/builtins/LinkerInput.mdx b/rules/lib/builtins/LinkerInput.mdx index 5f9dafb..2fa8b95 100644 --- a/rules/lib/builtins/LinkerInput.mdx +++ b/rules/lib/builtins/LinkerInput.mdx @@ -2,22 +2,19 @@ title: 'LinkerInput' --- -# LinkerInput -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/LinkerInputApi.java" %} -{% include "\_buttons.html" %} Either libraries, flags or other files that may be passed to the linker as inputs. ## Members -- [additional_inputs](#additional_inputs) -- [libraries](#libraries) -- [owner](#owner) -- [user_link_flags](#user_link_flags) +* [additional\_inputs](#additional_inputs) +* [libraries](#libraries) +* [owner](#owner) +* [user\_link\_flags](#user_link_flags) -## additional_inputs +## additional\_inputs -``` rule-signature +``` sequence LinkerInput.additional_inputs ``` @@ -25,24 +22,24 @@ Returns the depset of additional inputs, e.g.: linker scripts. ## libraries -``` rule-signature +``` sequence LinkerInput.libraries ``` -Returns the depset of `LibraryToLink`. May return a list but this is deprecated. See \#8118. +Returns the depset of `LibraryToLink`. May return a list but this is deprecated. See #8118. ## owner -``` rule-signature +``` Label LinkerInput.owner ``` Returns the owner of this LinkerInput. -## user_link_flags +## user\_link\_flags -``` rule-signature +``` sequence LinkerInput.user_link_flags ``` -Returns the list of user link flags passed as strings. +Returns the list of user link flags passed as strings. \ No newline at end of file diff --git a/rules/lib/builtins/LinkingContext.mdx b/rules/lib/builtins/LinkingContext.mdx index b24fb8f..d5072e8 100644 --- a/rules/lib/builtins/LinkingContext.mdx +++ b/rules/lib/builtins/LinkingContext.mdx @@ -2,20 +2,17 @@ title: 'LinkingContext' --- -# LinkingContext -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingContextApi.java" %} -{% include "\_buttons.html" %} Immutable store of information needed for C++ linking that is aggregated across dependencies. ## Members -- [linker_inputs](#linker_inputs) +* [linker\_inputs](#linker_inputs) -## linker_inputs +## linker\_inputs -``` rule-signature +``` depset LinkingContext.linker_inputs ``` -Returns the depset of linker inputs. +Returns the depset of linker inputs. \ No newline at end of file diff --git a/rules/lib/builtins/Provider.mdx b/rules/lib/builtins/Provider.mdx index e42d987..b2f281b 100644 --- a/rules/lib/builtins/Provider.mdx +++ b/rules/lib/builtins/Provider.mdx @@ -2,29 +2,25 @@ title: 'Provider' --- -# Provider -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java" %} -{% include "\_buttons.html" %} A constructor for simple value objects, known as provider instances. This value has a dual purpose: -- It is a function that can be called to construct 'struct'-like values: +* It is a function that can be called to construct 'struct'-like values: - ``` python + ``` DataInfo = provider() d = DataInfo(x = 2, y = 3) print(d.x + d.y) # prints 5 ``` Note: Some providers, defined internally, do not allow instance creation +* It is a *key* to access a provider instance on a [Target](../builtins/Target.mdx) -- It is a *key* to access a provider instance on a [Target](../builtins/Target.html) - - ``` python + ``` DataInfo = provider() def _rule_impl(ctx) ... ctx.attr.dep[DataInfo] ``` -Create a new `Provider` using the [provider](../globals/bzl.html#provider) function. +Create a new `Provider` using the [provider](../globals/bzl.html#provider) function. \ No newline at end of file diff --git a/rules/lib/builtins/Subrule.mdx b/rules/lib/builtins/Subrule.mdx index 100313b..b608c95 100644 --- a/rules/lib/builtins/Subrule.mdx +++ b/rules/lib/builtins/Subrule.mdx @@ -2,8 +2,5 @@ title: 'Subrule' --- -# Subrule -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkSubruleApi.java" %} -{% include "\_buttons.html" %} -Experimental: a building block for writing rules with shared code. For more information, please see the subrule proposal: https://docs.google.com/document/d/1RbNC88QieKvBEwir7iV5zZU08AaMlOzxhVkPnmKDedQ +Experimental: a building block for writing rules with shared code. For more information, please see the subrule proposal: https://docs.google.com/document/d/1RbNC88QieKvBEwir7iV5zZU08AaMlOzxhVkPnmKDedQ \ No newline at end of file diff --git a/rules/lib/builtins/SymlinkEntry.mdx b/rules/lib/builtins/SymlinkEntry.mdx index 7a6eba0..94a6fe2 100644 --- a/rules/lib/builtins/SymlinkEntry.mdx +++ b/rules/lib/builtins/SymlinkEntry.mdx @@ -2,29 +2,26 @@ title: 'SymlinkEntry' --- -# SymlinkEntry -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/SymlinkEntryApi.java" %} -{% include "\_buttons.html" %} A single runfiles symlink represented by a link name and target. ## Members -- [path](#path) -- [target_file](#target_file) +* [path](#path) +* [target\_file](#target_file) ## path -``` rule-signature +``` string SymlinkEntry.path ``` The path of the symlink in the runfiles tree -## target_file +## target\_file -``` rule-signature +``` File SymlinkEntry.target_file ``` -Target file of the symlink +Target file of the symlink \ No newline at end of file diff --git a/rules/lib/builtins/Target.mdx b/rules/lib/builtins/Target.mdx index 558a708..d750a1f 100644 --- a/rules/lib/builtins/Target.mdx +++ b/rules/lib/builtins/Target.mdx @@ -2,18 +2,13 @@ title: 'Target' --- -# Target -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java" %} -{% include "\_buttons.html" %} -The BUILD target for a dependency. Appears in the fields of [`ctx.attr`](../builtins/ctx.html#attr) corresponding to [dependency attributes](https://bazel.build/extending/rules#dependency_attributes) ([`label`](../toplevel/attr.html#label) or [`label_list`](../toplevel/attr.html#label_list)). Has the following fields: +The BUILD target for a dependency. Appears in the fields of `ctx.attr` corresponding to [dependency attributes](https://bazel.build/extending/rules#dependency_attributes) (`label` or `label_list`). Has the following fields: -- ### label +* ### label - [`Label`](../builtins/Label.html)` Target.label` + `Label Target.label` The identifier of the target. +* ### Providers -- ### Providers - - The [providers](https://bazel.build/extending/rules#providers) of a rule target can be accessed by type using index notation (`target[DefaultInfo]`). The presence of providers can be checked using the `in` operator (`SomeInfo in target`). - + The [providers](https://bazel.build/extending/rules#providers) of a rule target can be accessed by type using index notation (`target[DefaultInfo]`). The presence of providers can be checked using the `in` operator (`SomeInfo in target`). \ No newline at end of file diff --git a/rules/lib/builtins/TemplateDict.mdx b/rules/lib/builtins/TemplateDict.mdx index 92bad78..3f10a99 100644 --- a/rules/lib/builtins/TemplateDict.mdx +++ b/rules/lib/builtins/TemplateDict.mdx @@ -2,20 +2,17 @@ title: 'TemplateDict' --- -# TemplateDict -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java" %} -{% include "\_buttons.html" %} -An Args-like structure for use in ctx.actions.expand_template(), which allows for deferring evaluation of values till the execution phase. +An Args-like structure for use in ctx.actions.expand\_template(), which allows for deferring evaluation of values till the execution phase. ## Members -- [add](#add) -- [add_joined](#add_joined) +* [add](#add) +* [add\_joined](#add_joined) ## add -``` rule-signature +``` TemplateDict TemplateDict.add(key, value) ``` @@ -23,32 +20,14 @@ Add a String value ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="add.key"><code>key</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A String key</td> -</tr> -<tr> -<td id="add.value"><code>value</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A String value</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `key` | [string](../core/string.mdx); required A String key | +| `value` | [string](../core/string.mdx); required A String value | -## add_joined +## add\_joined -``` rule-signature +``` TemplateDict TemplateDict.add_joined(key, values, *, join_with, map_each, uniquify=False, format_joined=None, allow_closure=False) ``` @@ -56,55 +35,12 @@ Add depset of values ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="add_joined.key"><code>key</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A String key</td> -</tr> -<tr> -<td id="add_joined.values"><code>values</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; -required<br /> -The depset whose items will be joined.</td> -</tr> -<tr> -<td id="add_joined.join_with"><code>join_with</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A delimiter string used to join together the strings obtained from applying <code>map_each</code>, in the same manner as <a href="../core/string.html#join"><code>string.join()</code></a>.</td> -</tr> -<tr> -<td id="add_joined.map_each"><code>map_each</code></td> -<td>callable; -required<br /> -A Starlark function accepting a single argument and returning either a string, <code>None</code>, or a list of strings. This function is applied to each item of the depset specified in the <code>values</code> parameter</td> -</tr> -<tr> -<td id="add_joined.uniquify"><code>uniquify</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, duplicate strings derived from <code>values</code> will be omitted. Only the first occurrence of each string will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if <code>map_each</code> emits the same string for multiple items.</td> -</tr> -<tr> -<td id="add_joined.format_joined"><code>format_joined</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder.</td> -</tr> -<tr> -<td id="add_joined.allow_closure"><code>allow_closure</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, allows the use of closures in function parameters like <code>map_each</code>. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `key` | [string](../core/string.mdx); required A String key | +| `values` | [depset](../builtins/depset.mdx); required The depset whose items will be joined. | +| `join_with` | [string](../core/string.mdx); required A delimiter string used to join together the strings obtained from applying `map_each`, in the same manner as [`string.join()`](../core/string.html#join). | +| `map_each` | callable; required A Starlark function accepting a single argument and returning either a string, `None`, or a list of strings. This function is applied to each item of the depset specified in the `values` parameter | +| `uniquify` | [bool](../core/bool.mdx); default is `False` If true, duplicate strings derived from `values` will be omitted. Only the first occurrence of each string will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if `map_each` emits the same string for multiple items. | +| `format_joined` | [string](../core/string.mdx); or `None`; default is `None` An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. | +| `allow_closure` | [bool](../core/bool.mdx); default is `False` If true, allows the use of closures in function parameters like `map_each`. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. | \ No newline at end of file diff --git a/rules/lib/builtins/ToolchainContext.mdx b/rules/lib/builtins/ToolchainContext.mdx index 89a9c5e..33ff674 100644 --- a/rules/lib/builtins/ToolchainContext.mdx +++ b/rules/lib/builtins/ToolchainContext.mdx @@ -2,8 +2,5 @@ title: 'ToolchainContext' --- -# ToolchainContext -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainContextApi.java" %} -{% include "\_buttons.html" %} -Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in `ctx.toolchains["//pkg:my_toolchain_type"]`. If the toolchain was optional and no toolchain was resolved, this will return `None`. Accessing toolchains of an aspect or rule via `ctx.toolchains` returns the indexed toolchain as a `ToolchainInfo` provider. While when using aspects, `ToolchainContext` is also used to hold the toolchains of the base target. It can be accessed by `ctx.rule.toolchains["//pkg:my_toolchain_type"]` and it returns the list of providers resulted from applying the aspects on these toolchain targets. +Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in `ctx.toolchains["//pkg:my_toolchain_type"]`. If the toolchain was optional and no toolchain was resolved, this will return `None`. Accessing toolchains of an aspect or rule via `ctx.toolchains` returns the indexed toolchain as a `ToolchainInfo` provider. While when using aspects, `ToolchainContext` is also used to hold the toolchains of the base target. It can be accessed by `ctx.rule.toolchains["//pkg:my_toolchain_type"]` and it returns the list of providers resulted from applying the aspects on these toolchain targets. \ No newline at end of file diff --git a/rules/lib/builtins/actions.mdx b/rules/lib/builtins/actions.mdx index 78bb0ca..67e4387 100644 --- a/rules/lib/builtins/actions.mdx +++ b/rules/lib/builtins/actions.mdx @@ -2,71 +2,50 @@ title: 'actions' --- -# actions -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java" %} -{% include "\_buttons.html" %} Module providing functions to create actions. Access this module using [`ctx.actions`](../builtins/ctx.html#actions). ## Members -- [args](#args) -- [declare_directory](#declare_directory) -- [declare_file](#declare_file) -- [declare_symlink](#declare_symlink) -- [do_nothing](#do_nothing) -- [expand_template](#expand_template) -- [map_directory](#map_directory) -- [run](#run) -- [run_shell](#run_shell) -- [symlink](#symlink) -- [template_dict](#template_dict) -- [write](#write) +* [args](#args) +* [declare\_directory](#declare_directory) +* [declare\_file](#declare_file) +* [declare\_symlink](#declare_symlink) +* [do\_nothing](#do_nothing) +* [expand\_template](#expand_template) +* [map\_directory](#map_directory) +* [run](#run) +* [run\_shell](#run_shell) +* [symlink](#symlink) +* [template\_dict](#template_dict) +* [write](#write) ## args -``` rule-signature +``` Args actions.args() ``` Returns an Args object that can be used to build memory-efficient command lines. -## declare_directory +## declare\_directory -``` rule-signature +``` File actions.declare_directory(filename, *, sibling=None) ``` -Declares that the rule or aspect creates a directory with the given name, in the current package. You must create an action that generates the directory. The contents of the directory are not directly accessible from Starlark, but can be expanded in an action command with [`Args.add_all()`](../builtins/Args.html#add_all). Only regular files and directories can be in the expanded contents of a declare_directory. +Declares that the rule or aspect creates a directory with the given name, in the current package. You must create an action that generates the directory. The contents of the directory are not directly accessible from Starlark, but can be expanded in an action command with [`Args.add_all()`](../builtins/Args.html#add_all). Only regular files and directories can be in the expanded contents of a declare\_directory. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="declare_directory.filename"><code>filename</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -If no 'sibling' provided, path of the new directory, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory).</td> -</tr> -<tr> -<td id="declare_directory.sibling"><code>sibling</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -A file that lives in the same directory as the newly declared directory. The file must be in the current package.</td> -</tr> -</tbody> -</table> - -## declare_file - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `filename` | [string](../core/string.mdx); required If no 'sibling' provided, path of the new directory, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). | +| `sibling` | [File](../builtins/File.mdx); or `None`; default is `None` A file that lives in the same directory as the newly declared directory. The file must be in the current package. | + +## declare\_file + +``` File actions.declare_file(filename, *, sibling=None) ``` @@ -78,32 +57,14 @@ Note that [predeclared output files](https://bazel.build/extending/rules#files) ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="declare_file.filename"><code>filename</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -If no 'sibling' provided, path of the new file, relative to the current package. Otherwise a base name for a file ('sibling' determines a directory).</td> -</tr> -<tr> -<td id="declare_file.sibling"><code>sibling</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -A file that lives in the same directory as the newly created file. The file must be in the current package.</td> -</tr> -</tbody> -</table> - -## declare_symlink - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `filename` | [string](../core/string.mdx); required If no 'sibling' provided, path of the new file, relative to the current package. Otherwise a base name for a file ('sibling' determines a directory). | +| `sibling` | [File](../builtins/File.mdx); or `None`; default is `None` A file that lives in the same directory as the newly created file. The file must be in the current package. | + +## declare\_symlink + +``` File actions.declare_symlink(filename, *, sibling=None) ``` @@ -111,32 +72,14 @@ Declares that the rule or aspect creates a symlink with the given name in the cu ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="declare_symlink.filename"><code>filename</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -If no 'sibling' provided, path of the new symlink, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory).</td> -</tr> -<tr> -<td id="declare_symlink.sibling"><code>sibling</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -A file that lives in the same directory as the newly declared symlink.</td> -</tr> -</tbody> -</table> - -## do_nothing - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `filename` | [string](../core/string.mdx); required If no 'sibling' provided, path of the new symlink, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). | +| `sibling` | [File](../builtins/File.mdx); or `None`; default is `None` A file that lives in the same directory as the newly declared symlink. | + +## do\_nothing + +``` None actions.do_nothing(*, mnemonic, inputs=[]) ``` @@ -144,204 +87,57 @@ Creates an empty action that neither executes a command nor produces any output, ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="do_nothing.mnemonic"><code>mnemonic</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A one-word description of the action, for example, CppCompile or GoLink.</td> -</tr> -<tr> -<td id="do_nothing.inputs"><code>inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>[]</code><br /> -List of the input files of the action.</td> -</tr> -</tbody> -</table> - -## expand_template - -``` rule-signature -None actions.expand_template(*, template, output, substitutions={}, is_executable=False, computed_substitutions=unbound) +| Parameter | Description | +| --- | --- | +| `mnemonic` | [string](../core/string.mdx); required A one-word description of the action, for example, CppCompile or GoLink. | +| `inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `[]` List of the input files of the action. | + +## expand\_template + +``` +None actions.expand_template(*, template, output, substitutions=\{\}, is_executable=False, computed_substitutions=unbound) ``` -Creates a template expansion action. When the action is executed, it will generate a file based on a template. Parts of the template will be replaced using the `substitutions` dictionary, in the order the substitutions are specified. Whenever a key of the dictionary appears in the template (or a result of a previous substitution), it is replaced with the associated value. There is no special syntax for the keys. You may, for example, use curly braces to avoid conflicts (for example, `{KEY}`). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). +Creates a template expansion action. When the action is executed, it will generate a file based on a template. Parts of the template will be replaced using the `substitutions` dictionary, in the order the substitutions are specified. Whenever a key of the dictionary appears in the template (or a result of a previous substitution), it is replaced with the associated value. There is no special syntax for the keys. You may, for example, use curly braces to avoid conflicts (for example, `\{KEY\}`). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="expand_template.template"><code>template</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The template file, which is a UTF-8 encoded text file.</td> -</tr> -<tr> -<td id="expand_template.output"><code>output</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The output file, which is a UTF-8 encoded text file.</td> -</tr> -<tr> -<td id="expand_template.substitutions"><code>substitutions</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -Substitutions to make when expanding the template.</td> -</tr> -<tr> -<td id="expand_template.is_executable"><code>is_executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether the output file should be executable.</td> -</tr> -<tr> -<td id="expand_template.computed_substitutions"><code>computed_substitutions</code></td> -<td><a href="../builtins/TemplateDict.html" class="anchor">TemplateDict</a>; -default is <code>unbound</code><br /> -Substitutions to make when expanding the template.</td> -</tr> -</tbody> -</table> - -## map_directory - -``` rule-signature -None actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation) +| Parameter | Description | +| --- | --- | +| `template` | [File](../builtins/File.mdx); required The template file, which is a UTF-8 encoded text file. | +| `output` | [File](../builtins/File.mdx); required The output file, which is a UTF-8 encoded text file. | +| `substitutions` | [dict](../core/dict.mdx); default is `\{\}` Substitutions to make when expanding the template. | +| `is_executable` | [bool](../core/bool.mdx); default is `False` Whether the output file should be executable. | +| `computed_substitutions` | [TemplateDict](../builtins/TemplateDict.mdx); default is `unbound` Substitutions to make when expanding the template. | + +## map\_directory + +``` +None actions.map_directory(*, input_directories, additional_inputs=\{\}, output_directories, tools, additional_params=\{\}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation) ``` Creates multiple actions based on the files within one or more input directories, to output one or more output directories. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="map_directory.input_directories"><code>input_directories</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -required<br /> -A dictionary mapping of strings to input directories, as declared by <code>ctx.actions.declare_directory()</code> (only directories are allowed as values here). The values specify the directories that we want expanded to access their files in the implementation function. The keys (strings) act as identifiers to easily reference a specific directory in the implementation function.</td> -</tr> -<tr> -<td id="map_directory.additional_inputs"><code>additional_inputs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary of mapping of strings to additional inputs (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify any additional inputs that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific input from within the implementation function.</td> -</tr> -<tr> -<td id="map_directory.output_directories"><code>output_directories</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -required<br /> -A dictionary mapping of strings to output directories, as declared by <code>ctx.actions.declare_directory()</code>. The values specify the output directories that we want to generate by the actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific output directory from within the implementation function.</td> -</tr> -<tr> -<td id="map_directory.tools"><code>tools</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -required<br /> -A dictionary mapping of strings to tools (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify the tools that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific tool from within the implementation function.</td> -</tr> -<tr> -<td id="map_directory.additional_params"><code>additional_params</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary mapping of strings to additional parameters (only string, boolean and integer values are allowed here). The values specify any additional parameters that we want to make accessible to the implementation function that could be used to influence its behavior. The keys (strings) act as identifiers to easily reference a specific parameter from within the implementation function.</td> -</tr> -<tr> -<td id="map_directory.execution_requirements"><code>execution_requirements</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Information for scheduling the created actions. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys.</td> -</tr> -<tr> -<td id="map_directory.exec_group"><code>exec_group</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Run the created actions on the given exec group's execution platform. If none, uses the target's default execution platform.</td> -</tr> -<tr> -<td id="map_directory.toolchain"><code>toolchain</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> - <p>Toolchain type of the executable or tools used by the created actions.</p> -<p>If executable and tools are not coming from a toolchain, set this parameter to <code>None</code>.</p> -<p>If executable and tools are coming from a toolchain, toolchain type must be set so that the created actions execute on the correct execution platform.</p> -<p>Note that the rule which creates these actions needs to define this toolchain inside its 'rule()' function.</p> -<p>When <code>toolchain</code> and <code>exec_group</code> parameters are both set, <code>exec_group</code> will be used. An error is raised in case the <code>exec_group</code> doesn't specify the same toolchain.</p></td> -</tr> -<tr> -<td id="map_directory.use_default_shell_env"><code>use_default_shell_env</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether the created actions should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>. -<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> -</tr> -<tr> -<td id="map_directory.env"><code>env</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Sets the dictionary of environment variables. -<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> -</tr> -<tr> -<td id="map_directory.mnemonic"><code>mnemonic</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A one-word description of the created actions, for example, CppCompile or GoLink.</td> -</tr> -<tr> -<td id="map_directory.implementation"><code>implementation</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -required<br /> -A Starlark function that gets called after input directories have been built to generate actions -that output files to the specified output directories. This function is passed the following -arguments: -<ul> -<li><code>template_ctx</code> (positional): A <a href="../builtins/template_ctx.html"><code>template_ctx</code></a> object that can be used to -create actions.</li> -<li><code>input_directories</code> (keyword-only): A dictionary mapping from the string keys of -the <code>input_directories</code> argument of <code>actions.map_directory()</code> to their -values' corresponding <a href="../builtins/File.html"><code>ExpandedDirectory</code></a> -objects.</li> -<li><code>output_directories</code> (keyword-only): The value of the -<code>output_directories</code> argument of <code>actions.map_directory()</code>; a -dictionary mapping from strings to output directories.</li> -<li><code>additional_inputs</code> (keyword-only): The value of the -<code>additional_inputs</code> argument of <code>actions.map_directory()</code>; a -dictionary mapping from strings to input files.</li> -<li><code>tools</code> (keyword-only): The value of the <code>tools</code> argument of -<code>actions.map_directory()</code>; a dictionary mapping from strings to tools.</li> -<li><code>additional_params</code> (keyword-only): The value of the -<code>additional_params</code> argument of <code>actions.map_directory()</code>; a -dictionary mapping from strings to strings, booleans, or integers.</li> -</ul> -This function must be top-level, i.e. lambdas and nested functions are not allowed.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `input_directories` | [dict](../core/dict.mdx) of [File](../builtins/File.mdx)s; required A dictionary mapping of strings to input directories, as declared by `ctx.actions.declare_directory()` (only directories are allowed as values here). The values specify the directories that we want expanded to access their files in the implementation function. The keys (strings) act as identifiers to easily reference a specific directory in the implementation function. | +| `additional_inputs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary of mapping of strings to additional inputs (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify any additional inputs that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific input from within the implementation function. | +| `output_directories` | [dict](../core/dict.mdx) of [File](../builtins/File.mdx)s; required A dictionary mapping of strings to output directories, as declared by `ctx.actions.declare_directory()`. The values specify the output directories that we want to generate by the actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific output directory from within the implementation function. | +| `tools` | [dict](../core/dict.mdx); required A dictionary mapping of strings to tools (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify the tools that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific tool from within the implementation function. | +| `additional_params` | [dict](../core/dict.mdx); default is `\{\}` A dictionary mapping of strings to additional parameters (only string, boolean and integer values are allowed here). The values specify any additional parameters that we want to make accessible to the implementation function that could be used to influence its behavior. The keys (strings) act as identifiers to easily reference a specific parameter from within the implementation function. | +| `execution_requirements` | [dict](../core/dict.mdx); or `None`; default is `None` Information for scheduling the created actions. See [tags](./reference/be/common-definitions#common.tags) for useful keys. | +| `exec_group` | [string](../core/string.mdx); or `None`; default is `None` Run the created actions on the given exec group's execution platform. If none, uses the target's default execution platform. | +| `toolchain` | [Label](../builtins/Label.mdx); or [string](../core/string.mdx); or `None`; default is `None` Toolchain type of the executable or tools used by the created actions. 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 created actions execute on the correct execution platform. Note that the rule which creates these actions 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. | +| `use_default_shell_env` | [bool](../core/bool.mdx); default is `False` Whether the created actions should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](./reference/command-line-reference#flag--action_env). If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | +| `env` | [dict](../core/dict.mdx); or `None`; default is `None` Sets the dictionary of environment variables. If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | +| `mnemonic` | [string](../core/string.mdx); or `None`; default is `None` A one-word description of the created actions, for example, CppCompile or GoLink. | +| `implementation` | [function](../core/function.mdx); required A Starlark function that gets called after input directories have been built to generate actions that output files to the specified output directories. This function is passed the following arguments: * `template_ctx` (positional): A [`template_ctx`](../builtins/template_ctx.mdx) object that can be used to create actions. * `input_directories` (keyword-only): A dictionary mapping from the string keys of the `input_directories` argument of `actions.map_directory()` to their values' corresponding [`ExpandedDirectory`](../builtins/File.mdx) objects. * `output_directories` (keyword-only): The value of the `output_directories` argument of `actions.map_directory()`; a dictionary mapping from strings to output directories. * `additional_inputs` (keyword-only): The value of the `additional_inputs` argument of `actions.map_directory()`; a dictionary mapping from strings to input files. * `tools` (keyword-only): The value of the `tools` argument of `actions.map_directory()`; a dictionary mapping from strings to tools. * `additional_params` (keyword-only): The value of the `additional_params` argument of `actions.map_directory()`; a dictionary mapping from strings to strings, booleans, or integers. This function must be top-level, i.e. lambdas and nested functions are not allowed. | ## run -``` rule-signature +``` 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) ``` @@ -349,138 +145,28 @@ Creates an action that runs an executable. [See example of use](https://github.c ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="run.outputs"><code>outputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -required<br /> -List of the output files of the action.</td> -</tr> -<tr> -<td id="run.inputs"><code>inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>[]</code><br /> -List or depset of the input files of the action.</td> -</tr> -<tr> -<td id="run.unused_inputs_list"><code>unused_inputs_list</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -File containing list of inputs unused by the action. -<p>The content of this file (generally one of the outputs of the action) corresponds to the list of input files that were not used during the whole action execution. Any change in those files must not affect in any way the outputs of the action.</p></td> -</tr> -<tr> -<td id="run.executable"><code>executable</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <a href="../core/string.html" class="anchor">string</a>; or <a href="../providers/FilesToRunProvider.html" class="anchor">FilesToRunProvider</a>; -required<br /> -The executable file to be called by the action.</td> -</tr> -<tr> -<td id="run.tools"><code>tools</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>unbound</code><br /> -List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. -<p>When a list is provided, it can be a heterogenous collection of:</p> -<ul> -<li><code>File</code>s</li> -<li><code>FilesToRunProvider</code> instances</li> -<li><code>depset</code>s of <code>File</code>s</li> -</ul> -<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs.</td> -</tr> -<tr> -<td id="run.arguments"><code>arguments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects.</td> -</tr> -<tr> -<td id="run.mnemonic"><code>mnemonic</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A one-word description of the action, for example, CppCompile or GoLink.</td> -</tr> -<tr> -<td id="run.progress_message"><code>progress_message</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain <code>%{label}</code>, <code>%{input}</code>, or <code>%{output}</code> patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient.</td> -</tr> -<tr> -<td id="run.use_default_shell_env"><code>use_default_shell_env</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>. -<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> -</tr> -<tr> -<td id="run.env"><code>env</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Sets the dictionary of environment variables. -<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> -</tr> -<tr> -<td id="run.execution_requirements"><code>execution_requirements</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Information for scheduling the action. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys.</td> -</tr> -<tr> -<td id="run.input_manifests"><code>input_manifests</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; -default is <code>None</code><br /> -Legacy argument. Ignored.</td> -</tr> -<tr> -<td id="run.exec_group"><code>exec_group</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform.</td> -</tr> -<tr> -<td id="run.shadowed_action"><code>shadowed_action</code></td> -<td><a href="../builtins/Action.html" class="anchor">Action</a>; -default is <code>None</code><br /> -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.</td> -</tr> -<tr> -<td id="run.resource_set"><code>resource_set</code></td> -<td>callable; or <code>None</code>; -default is <code>None</code><br /> -A callback function that returns a resource set dictionary, used to estimate resource usage at execution time if this action is run locally. -<p>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:</p> -<ul> -<li>"cpu": number of CPUs; default 1</li> -<li>"memory": in MB; default 250</li> -<li>"local_test": number of local tests; default 1</li> -</ul> -<p>If this parameter is set to <code>None</code> , the default values are used.</p> -<p>The callback must be top-level (lambda and nested functions aren't allowed).</p></td> -</tr> -<tr> -<td id="run.toolchain"><code>toolchain</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>unbound</code><br /> - <p>Toolchain type of the executable or tools used in this action.</p> -<p>If executable and tools are not coming from a toolchain, set this parameter to `None`.</p> -<p>If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform.</p> -<p>Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function.</p> -<p>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.</p></td> -</tr> -</tbody> -</table> - -## run_shell - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `outputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; required List of the output files of the action. | +| `inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `[]` List or depset of the input files of the action. | +| `unused_inputs_list` | [File](../builtins/File.mdx); or `None`; default is `None` File containing list of inputs unused by the action. The content of this file (generally one of the outputs of the action) corresponds to the list of input files that were not used during the whole action execution. Any change in those files must not affect in any way the outputs of the action. | +| `executable` | [File](../builtins/File.mdx); or [string](../core/string.mdx); or [FilesToRunProvider](../providers/FilesToRunProvider.mdx); required The executable file to be called by the action. | +| `tools` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `unbound` List or [`depset`](../builtins/depset.mdx) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. When a list is provided, it can be a heterogenous collection of: * `File`s * `FilesToRunProvider` instances * `depset`s of `File`s `File`s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider`s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. | +| `arguments` | [sequence](../core/list.mdx); default is `[]` Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. | +| `mnemonic` | [string](../core/string.mdx); or `None`; default is `None` A one-word description of the action, for example, CppCompile or GoLink. | +| `progress_message` | [string](../core/string.mdx); or `None`; default is `None` Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain `%\{label\}`, `%\{input\}`, or `%\{output\}` patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | +| `use_default_shell_env` | [bool](../core/bool.mdx); default is `False` Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](./reference/command-line-reference#flag--action_env). If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | +| `env` | [dict](../core/dict.mdx); or `None`; default is `None` Sets the dictionary of environment variables. If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | +| `execution_requirements` | [dict](../core/dict.mdx); or `None`; default is `None` Information for scheduling the action. See [tags](./reference/be/common-definitions#common.tags) for useful keys. | +| `input_manifests` | [sequence](../core/list.mdx); or `None`; default is `None` Legacy argument. Ignored. | +| `exec_group` | [string](../core/string.mdx); or `None`; default is `None` Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. | +| `shadowed_action` | [Action](../builtins/Action.mdx); 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.mdx); or [string](../core/string.mdx); 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. | + +## 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) ``` @@ -488,128 +174,27 @@ Creates an action that runs a shell command. [See example of use](https://github ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="run_shell.outputs"><code>outputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -required<br /> -List of the output files of the action.</td> -</tr> -<tr> -<td id="run_shell.inputs"><code>inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>[]</code><br /> -List or depset of the input files of the action.</td> -</tr> -<tr> -<td id="run_shell.tools"><code>tools</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>unbound</code><br /> -List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. -<p>When a list is provided, it can be a heterogenous collection of:</p> -<ul> -<li><code>File</code>s</li> -<li><code>FilesToRunProvider</code> instances</li> -<li><code>depset</code>s of <code>File</code>s</li> -</ul> -<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs.</td> -</tr> -<tr> -<td id="run_shell.arguments"><code>arguments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects. -<p>Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as <code>$1</code>, <code>$2</code>, etc. Note that since Args objects are flattened before indexing, if there is an Args object of unknown size then all subsequent strings will be at unpredictable indices. It may be useful to use <code>$@</code> (to retrieve all arguments) in conjunction with Args objects of indeterminate size.</p> -<p>In the case where <code>command</code> is a list of strings, this parameter may not be used.</p></td> -</tr> -<tr> -<td id="run_shell.mnemonic"><code>mnemonic</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A one-word description of the action, for example, CppCompile or GoLink.</td> -</tr> -<tr> -<td id="run_shell.command"><code>command</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -Shell command to execute. This may either be a string (preferred) or a sequence of strings <strong>(deprecated)</strong>. -<p>If <code>command</code> is a string, then it is executed as if by <code>sh -c <command> "" <arguments></code> -- that is, the elements in <code>arguments</code> are made available to the command as <code>$1</code>, <code>$2</code> (or <code>%1</code>, <code>%2</code> if using Windows batch), etc. If <code>arguments</code> contains any <a href="#args"><code>actions.args()</code></a> objects, their contents are appended one by one to the command line, so <code>$</code><em>i</em> can refer to individual strings within an Args object. Note that if an Args object of unknown size is passed as part of <code>arguments</code>, then the strings will be at unknown indices; in this case the <code>$@</code> shell substitution (retrieve all arguments) may be useful.</p> -<p><strong>(Deprecated)</strong> If <code>command</code> is a sequence of strings, the first item is the executable to run and the remaining items are its arguments. If this form is used, the <code>arguments</code> parameter must not be supplied. <em>Note that this form is deprecated and will soon be removed. It is disabled with `--incompatible_run_shell_command_string`. Use this flag to verify your code is compatible.</em></p> -<p>Bazel uses the same shell to execute the command as it does for genrules.</p></td> -</tr> -<tr> -<td id="run_shell.progress_message"><code>progress_message</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain <code>%{label}</code>, <code>%{input}</code>, or <code>%{output}</code> patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient.</td> -</tr> -<tr> -<td id="run_shell.use_default_shell_env"><code>use_default_shell_env</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via <a href="/reference/command-line-reference#flag--action_env"><code>--action_env</code></a>. -<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> -</tr> -<tr> -<td id="run_shell.env"><code>env</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Sets the dictionary of environment variables. -<p>If both <code>use_default_shell_env</code> and <code>env</code> are set to <code>True</code>, values set in <code>env</code> will overwrite the default shell environment.</p></td> -</tr> -<tr> -<td id="run_shell.execution_requirements"><code>execution_requirements</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Information for scheduling the action. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys.</td> -</tr> -<tr> -<td id="run_shell.input_manifests"><code>input_manifests</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; -default is <code>None</code><br /> -Legacy argument. Ignored.</td> -</tr> -<tr> -<td id="run_shell.exec_group"><code>exec_group</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform.</td> -</tr> -<tr> -<td id="run_shell.shadowed_action"><code>shadowed_action</code></td> -<td><a href="../builtins/Action.html" class="anchor">Action</a>; -default is <code>None</code><br /> -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.</td> -</tr> -<tr> -<td id="run_shell.resource_set"><code>resource_set</code></td> -<td>callable; or <code>None</code>; -default is <code>None</code><br /> -A callback function for estimating resource usage if run locally. See<a href="#run.resource_set"><code>ctx.actions.run()</code></a>.</td> -</tr> -<tr> -<td id="run_shell.toolchain"><code>toolchain</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>unbound</code><br /> - <p>Toolchain type of the executable or tools used in this action.</p> -<p>If executable and tools are not coming from a toolchain, set this parameter to `None`.</p> -<p>If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform.</p> -<p>Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function.</p> -<p>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.</p></td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `outputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; required List of the output files of the action. | +| `inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `[]` List or depset of the input files of the action. | +| `tools` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `unbound` List or [`depset`](../builtins/depset.mdx) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. When a list is provided, it can be a heterogenous collection of: * `File`s * `FilesToRunProvider` instances * `depset`s of `File`s `File`s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider`s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. | +| `arguments` | [sequence](../core/list.mdx); default is `[]` Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as `$1`, `$2`, etc. Note that since Args objects are flattened before indexing, if there is an Args object of unknown size then all subsequent strings will be at unpredictable indices. It may be useful to use `$@` (to retrieve all arguments) in conjunction with Args objects of indeterminate size. In the case where `command` is a list of strings, this parameter may not be used. | +| `mnemonic` | [string](../core/string.mdx); or `None`; default is `None` A one-word description of the action, for example, CppCompile or GoLink. | +| `command` | [string](../core/string.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required Shell command to execute. This may either be a string (preferred) or a sequence of strings **(deprecated)**. If `command` is a string, then it is executed as if by `sh -c <command> "" <arguments>` -- that is, the elements in `arguments` are made available to the command as `$1`, `$2` (or `%1`, `%2` if using Windows batch), etc. If `arguments` contains any [`actions.args()`](#args) objects, their contents are appended one by one to the command line, so `$`*i* can refer to individual strings within an Args object. Note that if an Args object of unknown size is passed as part of `arguments`, then the strings will be at unknown indices; in this case the `$@` shell substitution (retrieve all arguments) may be useful. **(Deprecated)** If `command` is a sequence of strings, the first item is the executable to run and the remaining items are its arguments. If this form is used, the `arguments` parameter must not be supplied. *Note that this form is deprecated and will soon be removed. It is disabled with `--incompatible\_run\_shell\_command\_string`. Use this flag to verify your code is compatible.* Bazel uses the same shell to execute the command as it does for genrules. | +| `progress_message` | [string](../core/string.mdx); or `None`; default is `None` Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain `%\{label\}`, `%\{input\}`, or `%\{output\}` patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | +| `use_default_shell_env` | [bool](../core/bool.mdx); default is `False` Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](./reference/command-line-reference#flag--action_env). If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | +| `env` | [dict](../core/dict.mdx); or `None`; default is `None` Sets the dictionary of environment variables. If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | +| `execution_requirements` | [dict](../core/dict.mdx); or `None`; default is `None` Information for scheduling the action. See [tags](./reference/be/common-definitions#common.tags) for useful keys. | +| `input_manifests` | [sequence](../core/list.mdx); or `None`; default is `None` Legacy argument. Ignored. | +| `exec_group` | [string](../core/string.mdx); or `None`; default is `None` Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. | +| `shadowed_action` | [Action](../builtins/Action.mdx); 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.mdx); or [string](../core/string.mdx); 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. | ## symlink -``` rule-signature +``` None actions.symlink(*, output, target_file=None, target_path=None, is_executable=False, progress_message=None) ``` @@ -623,51 +208,17 @@ Otherwise, when you use `target_path`, declare `output` with [`declare_symlink() ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="symlink.output"><code>output</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The output of this action.</td> -</tr> -<tr> -<td id="symlink.target_file"><code>target_file</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -The File that the output symlink will point to.</td> -</tr> -<tr> -<td id="symlink.target_path"><code>target_path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The exact path that the output symlink will point to. No normalization or other processing is applied.</td> -</tr> -<tr> -<td id="symlink.is_executable"><code>is_executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -May only be used with <code>target_file</code>, not <code>target_path</code>. If true, when the action is executed, the <code>target_file</code>'s path is checked to confirm that it is executable, and an error is reported if it is not. Setting <code>is_executable</code> to False does not mean the target is not executable, just that no verification is done. -<p>This feature does not make sense for <code>target_path</code> because dangling symlinks might not exist at build time.</p></td> -</tr> -<tr> -<td id="symlink.progress_message"><code>progress_message</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Progress message to show to the user during the build.</td> -</tr> -</tbody> -</table> - -## template_dict - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `output` | [File](../builtins/File.mdx); required The output of this action. | +| `target_file` | [File](../builtins/File.mdx); or `None`; default is `None` The File that the output symlink will point to. | +| `target_path` | [string](../core/string.mdx); or `None`; default is `None` The exact path that the output symlink will point to. No normalization or other processing is applied. | +| `is_executable` | [bool](../core/bool.mdx); default is `False` May only be used with `target_file`, not `target_path`. If true, when the action is executed, the `target_file`'s path is checked to confirm that it is executable, and an error is reported if it is not. Setting `is_executable` to False does not mean the target is not executable, just that no verification is done. This feature does not make sense for `target_path` because dangling symlinks might not exist at build time. | +| `progress_message` | [string](../core/string.mdx); or `None`; default is `None` Progress message to show to the user during the build. | + +## template\_dict + +``` TemplateDict actions.template_dict() ``` @@ -675,7 +226,7 @@ Returns a TemplateDict object for memory-efficient template expansion. ## write -``` rule-signature +``` None actions.write(output, content, is_executable=False, *, mnemonic=None) ``` @@ -683,37 +234,9 @@ Creates a file write action. When the action is executed, it will write the give ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="write.output"><code>output</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The output file.</td> -</tr> -<tr> -<td id="write.content"><code>content</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Args.html" class="anchor">Args</a>; -required<br /> -the contents of the file. May be a either a string or an <a href="#args"><code>actions.args()</code></a> object.</td> -</tr> -<tr> -<td id="write.is_executable"><code>is_executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether the output file should be executable.</td> -</tr> -<tr> -<td id="write.mnemonic"><code>mnemonic</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A one-word description of the action, for example, CppCompile or GoLink.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `output` | [File](../builtins/File.mdx); required The output file. | +| `content` | [string](../core/string.mdx); or [Args](../builtins/Args.mdx); required the contents of the file. May be a either a string or an [`actions.args()`](#args) object. | +| `is_executable` | [bool](../core/bool.mdx); default is `False` Whether the output file should be executable. | +| `mnemonic` | [string](../core/string.mdx); or `None`; default is `None` A one-word description of the action, for example, CppCompile or GoLink. | \ No newline at end of file diff --git a/rules/lib/builtins/apple_platform.mdx b/rules/lib/builtins/apple_platform.mdx index 6fc1cb3..0a7ae8d 100644 --- a/rules/lib/builtins/apple_platform.mdx +++ b/rules/lib/builtins/apple_platform.mdx @@ -2,42 +2,38 @@ title: 'apple_platform' --- -# apple_platform -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java" %} -{% include "\_buttons.html" %} Corresponds to Xcode's notion of a platform as would be found in `Xcode.app/Contents/Developer/Platforms`. Each platform represents an Apple platform type (such as iOS or tvOS) combined with one or more related CPU architectures. For example, the iOS simulator platform supports `x86_64` and `i386` architectures. -Specific instances of this type can be retrieved from the fields of the [apple_common.platform](../toplevel/apple_common.html#platform) struct: +Specific instances of this type can be retrieved from the fields of the [apple\_common.platform](../toplevel/apple_common.html#platform) struct: -- `apple_common.platform.ios_device` -- `apple_common.platform.ios_simulator` -- `apple_common.platform.macos` -- `apple_common.platform.tvos_device` -- `apple_common.platform.tvos_simulator` -- `apple_common.platform.watchos_device` -- `apple_common.platform.watchos_simulator` +* `apple_common.platform.ios_device` +* `apple_common.platform.ios_simulator` +* `apple_common.platform.macos` +* `apple_common.platform.tvos_device` +* `apple_common.platform.tvos_simulator` +* `apple_common.platform.watchos_device` +* `apple_common.platform.watchos_simulator` -More commonly, however, the [apple](../fragments/apple.html) configuration fragment has fields/methods that allow rules to determine the platform for which a target is being built. +More commonly, however, the [apple](../fragments/apple.mdx) configuration fragment has fields/methods that allow rules to determine the platform for which a target is being built. Example: -``` python - +``` p = apple_common.platform.ios_device print(p.name_in_plist) # 'iPhoneOS' ``` ## Members -- [is_device](#is_device) -- [name](#name) -- [name_in_plist](#name_in_plist) -- [platform_type](#platform_type) +* [is\_device](#is_device) +* [name](#name) +* [name\_in\_plist](#name_in_plist) +* [platform\_type](#platform_type) -## is_device +## is\_device -``` rule-signature +``` bool apple_platform.is_device ``` @@ -45,25 +41,25 @@ Returns `True` if this platform is a device platform or `False` if it is a simul ## name -``` rule-signature +``` string apple_platform.name ``` Returns the name aka starlarkKey of this platform. -## name_in_plist +## name\_in\_plist -``` rule-signature +``` string apple_platform.name_in_plist ``` The name of the platform as it appears in the `CFBundleSupportedPlatforms` entry of an Info.plist file and in Xcode's platforms directory, without the extension (for example, `iPhoneOS` or `iPhoneSimulator`). This name, when converted to lowercase (e.g., `iphoneos`, `iphonesimulator`), can be passed to Xcode's command-line tools like `ibtool` and `actool` when they expect a platform name. -## platform_type +## platform\_type -``` rule-signature +``` string apple_platform.platform_type ``` -Returns the platform type of this platform. +Returns the platform type of this platform. \ No newline at end of file diff --git a/rules/lib/builtins/bazel_module.mdx b/rules/lib/builtins/bazel_module.mdx index e52f7fd..f71a893 100644 --- a/rules/lib/builtins/bazel_module.mdx +++ b/rules/lib/builtins/bazel_module.mdx @@ -2,22 +2,19 @@ title: 'bazel_module' --- -# bazel_module -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java" %} -{% include "\_buttons.html" %} Represents a Bazel module in the external dependency graph. ## Members -- [is_root](#is_root) -- [name](#name) -- [tags](#tags) -- [version](#version) +* [is\_root](#is_root) +* [name](#name) +* [tags](#tags) +* [version](#version) -## is_root +## is\_root -``` rule-signature +``` bool bazel_module.is_root ``` @@ -25,7 +22,7 @@ Whether this module is the root module. ## name -``` rule-signature +``` string bazel_module.name ``` @@ -33,7 +30,7 @@ The name of the module. ## tags -``` rule-signature +``` bazel_module_tags bazel_module.tags ``` @@ -41,8 +38,8 @@ The tags in the module related to the module extension currently being processed ## version -``` rule-signature +``` string bazel_module.version ``` -The version of the module. +The version of the module. \ No newline at end of file diff --git a/rules/lib/builtins/bazel_module_tags.mdx b/rules/lib/builtins/bazel_module_tags.mdx index d2a7c7e..aa093a8 100644 --- a/rules/lib/builtins/bazel_module_tags.mdx +++ b/rules/lib/builtins/bazel_module_tags.mdx @@ -2,9 +2,6 @@ title: 'bazel_module_tags' --- -# bazel_module_tags -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java" %} -{% include "\_buttons.html" %} Contains the tags in a module for the module extension currently being processed. This object has a field for each tag class of the extension, and the value of the field is a list containing an object for each tag instance. This "tag instance" object in turn has a field for each attribute of the tag class. -When passed as positional arguments to `print()` or `fail()`, tag instance objects turn into a meaningful string representation of the form "'install' tag at /home/user/workspace/MODULE.bazel:3:4". This can be used to construct error messages that point to the location of the tag in the module file, e.g. `fail("Conflict between", tag1, "and", tag2)`. +When passed as positional arguments to `print()` or `fail()`, tag instance objects turn into a meaningful string representation of the form "'install' tag at /home/user/workspace/MODULE.bazel:3:4". This can be used to construct error messages that point to the location of the tag in the module file, e.g. `fail("Conflict between", tag1, "and", tag2)`. \ No newline at end of file diff --git a/rules/lib/builtins/configuration.mdx b/rules/lib/builtins/configuration.mdx index 37ab4da..5ad6b28 100644 --- a/rules/lib/builtins/configuration.mdx +++ b/rules/lib/builtins/configuration.mdx @@ -2,47 +2,44 @@ title: 'configuration' --- -# configuration -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java" %} -{% include "\_buttons.html" %} This object holds information about the environment in which the build is running. See the [Rules page](https://bazel.build/extending/rules#configurations) for more on the general concept of configurations. ## Members -- [coverage_enabled](#coverage_enabled) -- [default_shell_env](#default_shell_env) -- [host_path_separator](#host_path_separator) -- [short_id](#short_id) -- [test_env](#test_env) +* [coverage\_enabled](#coverage_enabled) +* [default\_shell\_env](#default_shell_env) +* [host\_path\_separator](#host_path_separator) +* [short\_id](#short_id) +* [test\_env](#test_env) -## coverage_enabled +## coverage\_enabled -``` rule-signature +``` bool configuration.coverage_enabled ``` A boolean that tells whether code coverage is enabled for this run. Note that this does not compute whether a specific rule should be instrumented for code coverage data collection. For that, see the [`ctx.coverage_instrumented`](../builtins/ctx.html#coverage_instrumented) function. -## default_shell_env +## default\_shell\_env -``` rule-signature +``` dict configuration.default_shell_env ``` A dictionary representing the static local shell environment. It maps variables to their values (strings). -## host_path_separator +## host\_path\_separator -``` rule-signature +``` string configuration.host_path_separator ``` Returns the separator for PATH environment variable, which is ':' on Unix. -## short_id +## short\_id -``` rule-signature +``` string configuration.short_id ``` @@ -50,14 +47,12 @@ A short identifier for this configuration understood by the `config` and query s Use this to distinguish different configurations for the same target in a way that is friendly to humans and tool usage, for example in an aspect used by an IDE. Keep in mind the following caveats: -The value may differ across Bazel versions, including patch releases. - -The value encodes the value of **every** flag, including those that aren't otherwise relevant for the current target and may thus invalidate caches more frequently. +* The value may differ across Bazel versions, including patch releases.* The value encodes the value of **every** flag, including those that aren't otherwise relevant for the current target and may thus invalidate caches more frequently. -## test_env + ## test\_env -``` rule-signature -dict configuration.test_env -``` + ``` + dict configuration.test_env + ``` -A dictionary containing user-specified test environment variables and their values, as set by the --test_env options. DO NOT USE! This is not the complete environment! + A dictionary containing user-specified test environment variables and their values, as set by the --test\_env options. DO NOT USE! This is not the complete environment! \ No newline at end of file diff --git a/rules/lib/builtins/ctx.mdx b/rules/lib/builtins/ctx.mdx index 8335a3c..bb7d85d 100644 --- a/rules/lib/builtins/ctx.mdx +++ b/rules/lib/builtins/ctx.mdx @@ -2,10 +2,7 @@ title: 'ctx' --- -# ctx -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java" %} -{% include "\_buttons.html" %} A context object that is passed to the implementation function for a rule or aspect. It provides access to the information and methods needed to analyze the current target. In particular, it lets the implementation function access the current target's label, attributes, configuration, and the providers of its dependencies. It has methods for declaring output files and the actions that produce them. @@ -14,51 +11,51 @@ Context objects essentially live for the duration of the call to the implementat ## Members -- [actions](#actions) -- [aspect_ids](#aspect_ids) -- [attr](#attr) -- [bin_dir](#bin_dir) -- [build_file_path](#build_file_path) -- [build_setting_value](#build_setting_value) -- [configuration](#configuration) -- [coverage_instrumented](#coverage_instrumented) -- [created_actions](#created_actions) -- [disabled_features](#disabled_features) -- [exec_groups](#exec_groups) -- [executable](#executable) -- [expand_location](#expand_location) -- [expand_make_variables](#expand_make_variables) -- [features](#features) -- [file](#file) -- [files](#files) -- [fragments](#fragments) -- [genfiles_dir](#genfiles_dir) -- [info_file](#info_file) -- [label](#label) -- [outputs](#outputs) -- [resolve_command](#resolve_command) -- [resolve_tools](#resolve_tools) -- [rule](#rule) -- [runfiles](#runfiles) -- [split_attr](#split_attr) -- [super](#super) -- [target_platform_has_constraint](#target_platform_has_constraint) -- [toolchains](#toolchains) -- [var](#var) -- [version_file](#version_file) -- [workspace_name](#workspace_name) +* [actions](#actions) +* [aspect\_ids](#aspect_ids) +* [attr](#attr) +* [bin\_dir](#bin_dir) +* [build\_file\_path](#build_file_path) +* [build\_setting\_value](#build_setting_value) +* [configuration](#configuration) +* [coverage\_instrumented](#coverage_instrumented) +* [created\_actions](#created_actions) +* [disabled\_features](#disabled_features) +* [exec\_groups](#exec_groups) +* [executable](#executable) +* [expand\_location](#expand_location) +* [expand\_make\_variables](#expand_make_variables) +* [features](#features) +* [file](#file) +* [files](#files) +* [fragments](#fragments) +* [genfiles\_dir](#genfiles_dir) +* [info\_file](#info_file) +* [label](#label) +* [outputs](#outputs) +* [resolve\_command](#resolve_command) +* [resolve\_tools](#resolve_tools) +* [rule](#rule) +* [runfiles](#runfiles) +* [split\_attr](#split_attr) +* [super](#super) +* [target\_platform\_has\_constraint](#target_platform_has_constraint) +* [toolchains](#toolchains) +* [var](#var) +* [version\_file](#version_file) +* [workspace\_name](#workspace_name) ## actions -``` rule-signature +``` actions ctx.actions ``` Contains methods for declaring output files and the actions that produce them. -## aspect_ids +## aspect\_ids -``` rule-signature +``` list ctx.aspect_ids ``` @@ -66,31 +63,31 @@ A list of ids for all aspects applied to the target. Only available in aspect im ## attr -``` rule-signature +``` struct ctx.attr ``` A struct to access the values of the [attributes](https://bazel.build/extending/rules#attributes). The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the [`attrs` dict](../globals/bzl.html#rule.attrs) provided to the [`rule` function](../globals/bzl.html#rule). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl). -## bin_dir +## bin\_dir -``` rule-signature +``` root ctx.bin_dir ``` The root corresponding to bin directory. -## build_file_path +## build\_file\_path -``` rule-signature +``` string ctx.build_file_path ``` Deprecated: Use `ctx.label.package + '/BUILD'`. The path to the BUILD file for this rule, relative to the source root. -## build_setting_value +## build\_setting\_value -``` rule-signature +``` unknown ctx.build_setting_value ``` @@ -98,60 +95,47 @@ Value of the build setting represented by the current target. If this isn't the ## configuration -``` rule-signature +``` configuration ctx.configuration ``` -The default configuration. See the [configuration](../builtins/configuration.html) type for more details. +The default configuration. See the [configuration](../builtins/configuration.mdx) type for more details. -## coverage_instrumented +## coverage\_instrumented -``` rule-signature +``` bool ctx.coverage_instrumented(target=None) ``` -Returns whether code coverage instrumentation should be generated when performing compilation actions for this rule or, if `target` is provided, the rule specified by that Target. (If a non-rule or a Starlark rule Target is provided, this returns False.) Checks if the sources of the current rule (if no Target is provided) or the sources of Target should be instrumented based on the --instrumentation_filter and --instrument_test_targets config settings. This differs from `coverage_enabled` in the [configuration](../builtins/configuration.html), which notes whether coverage data collection is enabled for the entire run, but not whether a specific target should be instrumented. +Returns whether code coverage instrumentation should be generated when performing compilation actions for this rule or, if `target` is provided, the rule specified by that Target. (If a non-rule or a Starlark rule Target is provided, this returns False.) Checks if the sources of the current rule (if no Target is provided) or the sources of Target should be instrumented based on the --instrumentation\_filter and --instrument\_test\_targets config settings. This differs from `coverage_enabled` in the [configuration](../builtins/configuration.mdx), which notes whether coverage data collection is enabled for the entire run, but not whether a specific target should be instrumented. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="coverage_instrumented.target"><code>target</code></td> -<td><a href="../builtins/Target.html" class="anchor">Target</a>; or <code>None</code>; -default is <code>None</code><br /> -A Target specifying a rule. If not provided, defaults to the current rule.</td> -</tr> -</tbody> -</table> - -## created_actions - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `target` | [Target](../builtins/Target.mdx); or `None`; default is `None` A Target specifying a rule. If not provided, defaults to the current rule. | + +## created\_actions + +``` StarlarkValue ctx.created_actions() ``` -For rules with [\_skylark_testable](../globals/bzl.html#rule._skylark_testable) set to `True`, this returns an `Actions` provider representing all actions created so far for the current rule. For all other rules, returns `None`. Note that the provider is not updated when subsequent actions are created, so you will have to call this function again if you wish to inspect them. +For rules with [\_skylark\_testable](../globals/bzl.html#rule._skylark_testable) set to `True`, this returns an `Actions` provider representing all actions created so far for the current rule. For all other rules, returns `None`. Note that the provider is not updated when subsequent actions are created, so you will have to call this function again if you wish to inspect them. This is intended to help write tests for rule-implementation helper functions, which may take in a `ctx` object and create actions on it. -## disabled_features +## disabled\_features -``` rule-signature +``` list ctx.disabled_features ``` The set of features that are explicitly disabled by the user for this rule. -## exec_groups +## exec\_groups -``` rule-signature +``` ExecGroupCollection ctx.exec_groups ``` @@ -159,19 +143,19 @@ A collection of the execution groups available for this rule, indexed by their n ## executable -``` rule-signature +``` struct ctx.executable ``` -A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). +A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.mdx) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). -## expand_location +## expand\_location -``` rule-signature +``` string ctx.expand_location(input, targets=[]) ``` -Expands all `$(location ...)` templates in the given string by replacing `$(location //x)` with the path of the output file of target //x. Expansion only works for labels that point to direct dependencies of this rule or that are explicitly listed in the optional argument `targets`. +Expands all `$(location ...)` templates in the given string by replacing `$(location //x)` with the path of the output file of target //x. Expansion only works for labels that point to direct dependencies of this rule or that are explicitly listed in the optional argument `targets`. `$(location ...)` will cause an error if the referenced target has multiple outputs. In this case, please use `$(locations ...)` since it produces a space-separated list of output paths. It can be safely used for a single output file, too. @@ -179,82 +163,40 @@ This function is useful to let the user specify a command in a BUILD file (like ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="expand_location.input"><code>input</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -String to be expanded.</td> -</tr> -<tr> -<td id="expand_location.targets"><code>targets</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Target.html" class="anchor">Target</a>s; -default is <code>[]</code><br /> -List of targets for additional lookup information. These are expanded as follows: A target with a single file in <code>DefaultInfo.files</code> expands to that file. Other targets expand to their <code>DefaultInfo.executable</code> file if set and if <code>--incompatible_locations_prefers_executable</code> is enabled, otherwise they expand to <code>DefaultInfo.files</code>.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `input` | [string](../core/string.mdx); required String to be expanded. | +| `targets` | [sequence](../core/list.mdx) of [Target](../builtins/Target.mdx)s; default is `[]` List of targets for additional lookup information. These are expanded as follows: A target with a single file in `DefaultInfo.files` expands to that file. Other targets expand to their `DefaultInfo.executable` file if set and if `--incompatible_locations_prefers_executable` is enabled, otherwise they expand to `DefaultInfo.files`. | May return `None`. -## expand_make_variables +## expand\_make\_variables -``` rule-signature +``` string ctx.expand_make_variables(attribute_name, command, additional_substitutions) ``` **Deprecated.** Use [ctx.var](../builtins/ctx.html#var) to access the variables instead. Returns a string after expanding all references to "Make variables". The variables must have the following format: `$(VAR_NAME)`. Also, `$$VAR_NAME` expands to `$VAR_NAME`. Examples: -``` python - -ctx.expand_make_variables("cmd", "$(MY_VAR)", {"MY_VAR": "Hi"}) # == "Hi" -ctx.expand_make_variables("cmd", "$$PWD", {}) # == "$PWD" +``` +ctx.expand_make_variables("cmd", "$(MY_VAR)", \{"MY_VAR": "Hi"\}) # == "Hi" +ctx.expand_make_variables("cmd", "$$PWD", \{\}) # == "$PWD" ``` Additional variables may come from other places, such as configurations. Note that this function is experimental. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="expand_make_variables.attribute_name"><code>attribute_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The attribute name. Used for error reporting.</td> -</tr> -<tr> -<td id="expand_make_variables.command"><code>command</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The expression to expand. It can contain references to "Make variables".</td> -</tr> -<tr> -<td id="expand_make_variables.additional_substitutions"><code>additional_substitutions</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -required<br /> -Additional substitutions to make beyond the default make variables.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `attribute_name` | [string](../core/string.mdx); required | +| `command` | [string](../core/string.mdx); required The expression to expand. It can contain references to "Make variables". | +| `additional_substitutions` | [dict](../core/dict.mdx); required Additional substitutions to make beyond the default make variables. | ## features -``` rule-signature +``` list ctx.features ``` @@ -262,59 +204,59 @@ The set of features that are explicitly enabled by the user for this rule. [See ## file -``` rule-signature +``` struct ctx.file ``` -A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: +A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.mdx) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: -``` python -list(ctx.attr.<ATTR>.files)[0] +``` +list(ctx.attr.\<ATTR\>.files)[0] ``` In other words, use `file` to access the (singular) [default output](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). ## files -``` rule-signature +``` struct ctx.files ``` -A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.html)s. It is a shortcut for: +A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.mdx)s. It is a shortcut for: -``` python -[f for t in ctx.attr.<ATTR> for f in t.files] +``` +[f for t in ctx.attr.\<ATTR\> for f in t.files] ``` -In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). +In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). ## fragments -``` rule-signature +``` fragments ctx.fragments ``` Allows access to configuration fragments in target configuration. -## genfiles_dir +## genfiles\_dir -``` rule-signature +``` root ctx.genfiles_dir ``` The root corresponding to genfiles directory. -## info_file +## info\_file -``` rule-signature +``` File ctx.info_file ``` -The file that is used to hold the non-volatile workspace status for the current build request. See documentation for --workspace_status_command for more information. +The file that is used to hold the non-volatile workspace status for the current build request. See documentation for --workspace\_status\_command for more information. ## label -``` rule-signature +``` Label ctx.label ``` @@ -322,25 +264,22 @@ The label of the target currently being analyzed. ## outputs -``` rule-signature +``` structure ctx.outputs ``` -A pseudo-struct containing all the predeclared output files, represented by [`File`](../builtins/File.html) objects. See the [Rules page](https://bazel.build/extending/rules#files) for more information and examples. +A pseudo-struct containing all the predeclared output files, represented by [`File`](../builtins/File.mdx) objects. See the [Rules page](https://bazel.build/extending/rules#files) for more information and examples. This field does not exist on aspect contexts, since aspects do not have predeclared outputs. The fields of this object are defined as follows. It is an error if two outputs produce the same field name or have the same label. -- If the rule declares an [`outputs`](../globals/bzl.html#rule.outputs) dict, then for every entry in the dict, there is a field whose name is the key and whose value is the corresponding `File`. -- For every attribute of type [`attr.output`](../toplevel/attr.html#output) that the rule declares, there is a field whose name is the attribute's name. If the target specified a label for that attribute, then the field value is the corresponding `File`; otherwise the field value is `None`. -- For every attribute of type [`attr.output_list`](../toplevel/attr.html#output_list) that the rule declares, there is a field whose name is the attribute's name. The field value is a list of `File` objects corresponding to the labels given for that attribute in the target, or an empty list if the attribute was not specified in the target. -- **(Deprecated)** If the rule is marked [`executable`](../globals/bzl.html#rule.executable) or [`test`](../globals/bzl.html#rule.test), there is a field named `"executable"`, which is the default executable. It is recommended that instead of using this, you pass another file (either predeclared or not) to the `executable` arg of [`DefaultInfo`](../providers/DefaultInfo.html). +* If the rule declares an [`outputs`](../globals/bzl.html#rule.outputs) dict, then for every entry in the dict, there is a field whose name is the key and whose value is the corresponding `File`.* For every attribute of type [`attr.output`](../toplevel/attr.html#output) that the rule declares, there is a field whose name is the attribute's name. If the target specified a label for that attribute, then the field value is the corresponding `File`; otherwise the field value is `None`.* For every attribute of type [`attr.output_list`](../toplevel/attr.html#output_list) that the rule declares, there is a field whose name is the attribute's name. The field value is a list of `File` objects corresponding to the labels given for that attribute in the target, or an empty list if the attribute was not specified in the target.* **(Deprecated)** If the rule is marked [`executable`](../globals/bzl.html#rule.executable) or [`test`](../globals/bzl.html#rule.test), there is a field named `"executable"`, which is the default executable. It is recommended that instead of using this, you pass another file (either predeclared or not) to the `executable` arg of [`DefaultInfo`](../providers/DefaultInfo.mdx). -## resolve_command +## resolve\_command -``` rule-signature -tuple ctx.resolve_command(*, command='', attribute=None, expand_locations=False, make_variables=None, tools=[], label_dict={}, execution_requirements={}) +``` +tuple ctx.resolve_command(*, command='', attribute=None, expand_locations=False, make_variables=None, tools=[], label_dict=\{\}, execution_requirements=\{\}) ``` *(Experimental)* Returns a tuple `(inputs, command, empty list)` of the list of resolved inputs and the argv list for the resolved command both of them suitable for passing as the same-named arguments of the `ctx.action` method. @@ -348,91 +287,35 @@ tuple ctx.resolve_command(*, command='', attribute=None, expand_locations=False, ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="resolve_command.command"><code>command</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Command to resolve.</td> -</tr> -<tr> -<td id="resolve_command.attribute"><code>attribute</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Name of the associated attribute for which to issue an error, or None.</td> -</tr> -<tr> -<td id="resolve_command.expand_locations"><code>expand_locations</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Shall we expand $(location) variables? See <a href="#expand_location">ctx.expand_location()</a> for more details.</td> -</tr> -<tr> -<td id="resolve_command.make_variables"><code>make_variables</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Make variables to expand, or None.</td> -</tr> -<tr> -<td id="resolve_command.tools"><code>tools</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Target.html" class="anchor">Target</a>s; -default is <code>[]</code><br /> -List of tools (list of targets).</td> -</tr> -<tr> -<td id="resolve_command.label_dict"><code>label_dict</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -Dictionary of resolved labels and the corresponding list of Files (a dict of Label : list of Files).</td> -</tr> -<tr> -<td id="resolve_command.execution_requirements"><code>execution_requirements</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -Information for scheduling the action to resolve this command. See <a href="/reference/be/common-definitions#common.tags">tags</a> for useful keys.</td> -</tr> -</tbody> -</table> - -## resolve_tools - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `command` | [string](../core/string.mdx); default is `''` Command to resolve. | +| `attribute` | [string](../core/string.mdx); or `None`; default is `None` Name of the associated attribute for which to issue an error, or None. | +| `expand_locations` | [bool](../core/bool.mdx); default is `False` Shall we expand $(location) variables? See [ctx.expand\_location()](#expand_location) for more details. | +| `make_variables` | [dict](../core/dict.mdx); or `None`; default is `None` Make variables to expand, or None. | +| `tools` | [sequence](../core/list.mdx) of [Target](../builtins/Target.mdx)s; default is `[]` List of tools (list of targets). | +| `label_dict` | [dict](../core/dict.mdx); default is `\{\}` Dictionary of resolved labels and the corresponding list of Files (a dict of Label : list of Files). | +| `execution_requirements` | [dict](../core/dict.mdx); default is `\{\}` Information for scheduling the action to resolve this command. See [tags](./reference/be/common-definitions#common.tags) for useful keys. | + +## resolve\_tools + +``` tuple ctx.resolve_tools(*, tools=[]) ``` -Returns a tuple `(inputs, empty list)` of the depset of resolved inputs required to run the tools, suitable for passing as the same-named argument of the `ctx.actions.run` and `ctx.actions.run_shell` methods. +Returns a tuple `(inputs, empty list)` of the depset of resolved inputs required to run the tools, suitable for passing as the same-named argument of the `ctx.actions.run` and `ctx.actions.run_shell` methods. In contrast to `ctx.resolve_command`, this method does not require that Bash be installed on the machine, so it's suitable for rules built on Windows. The empty list is returned as part of the tuple for backward compatibility. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="resolve_tools.tools"><code>tools</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Target.html" class="anchor">Target</a>s; -default is <code>[]</code><br /> -List of tools (list of targets).</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `tools` | [sequence](../core/list.mdx) of [Target](../builtins/Target.mdx)s; default is `[]` List of tools (list of targets). | ## rule -``` rule-signature +``` rule_attributes ctx.rule ``` @@ -440,82 +323,42 @@ Rule attributes descriptor for the rule that the aspect is applied to. Only avai ## runfiles -``` rule-signature -runfiles ctx.runfiles(files=[], transitive_files=None, collect_data=False, collect_default=False, symlinks={}, root_symlinks={}) +``` +runfiles ctx.runfiles(files=[], transitive_files=None, collect_data=False, collect_default=False, symlinks=\{\}, root_symlinks=\{\}) ``` Creates a runfiles object. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="runfiles.files"><code>files</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -The list of files to be added to the runfiles.</td> -</tr> -<tr> -<td id="runfiles.transitive_files"><code>transitive_files</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <code>None</code>; -default is <code>None</code><br /> -The (transitive) set of files to be added to the runfiles. The depset should use the <code>default</code> order (which, as the name implies, is the default).</td> -</tr> -<tr> -<td id="runfiles.collect_data"><code>collect_data</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -<strong>Use of this parameter is not recommended. See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a></strong>. -<p>Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes.</p></td> -</tr> -<tr> -<td id="runfiles.collect_default"><code>collect_default</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -<strong>Use of this parameter is not recommended. See <a href="https://bazel.build/extending/rules#runfiles">runfiles guide</a></strong>. -<p>Whether to collect the default runfiles from the dependencies in srcs, data and deps attributes.</p></td> -</tr> -<tr> -<td id="runfiles.symlinks"><code>symlinks</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <a href="../builtins/depset.html" class="anchor">depset</a> of <a href="../builtins/SymlinkEntry.html" class="anchor">SymlinkEntry</a>s; -default is <code>{}</code><br /> -Either a SymlinkEntry depset or the map of symlinks to be added to the runfiles. Symlinks are always added under the main workspace's runfiles directory (e.g. <code><runfiles_root>/_main/<symlink_path></code>, <strong>not</strong> the directory corresponding to the current target's repository. See <a href="https://bazel.build/extending/rules#runfiles_symlinks">Runfiles symlinks</a> in the rules guide.</td> -</tr> -<tr> -<td id="runfiles.root_symlinks"><code>root_symlinks</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <a href="../builtins/depset.html" class="anchor">depset</a> of <a href="../builtins/SymlinkEntry.html" class="anchor">SymlinkEntry</a>s; -default is <code>{}</code><br /> -Either a SymlinkEntry depset or a map of symlinks to be added to the runfiles. See <a href="https://bazel.build/extending/rules#runfiles_symlinks">Runfiles symlinks</a> in the rules guide.</td> -</tr> -</tbody> -</table> - -## split_attr - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `files` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` The list of files to be added to the runfiles. | +| `transitive_files` | [depset](../builtins/depset.mdx) of [File](../builtins/File.mdx)s; or `None`; default is `None` The (transitive) set of files to be added to the runfiles. The depset should use the `default` order (which, as the name implies, is the default). | +| `collect_data` | [bool](../core/bool.mdx); default is `False` **Use of this parameter is not recommended. See [runfiles guide](https://bazel.build/extending/rules#runfiles)**. Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes. | +| `collect_default` | [bool](../core/bool.mdx); default is `False` **Use of this parameter is not recommended. See [runfiles guide](https://bazel.build/extending/rules#runfiles)**. Whether to collect the default runfiles from the dependencies in srcs, data and deps attributes. | +| `symlinks` | [dict](../core/dict.mdx); or [depset](../builtins/depset.mdx) of [SymlinkEntry](../builtins/SymlinkEntry.mdx)s; default is `\{\}` Either a SymlinkEntry depset or the map of symlinks to be added to the runfiles. Symlinks are always added under the main workspace's runfiles directory (e.g. `<runfiles_root>/_main/\<symlink_path\>`, **not** the directory corresponding to the current target's repository. See [Runfiles symlinks](https://bazel.build/extending/rules#runfiles_symlinks) in the rules guide. | +| `root_symlinks` | [dict](../core/dict.mdx); or [depset](../builtins/depset.mdx) of [SymlinkEntry](../builtins/SymlinkEntry.mdx)s; default is `\{\}` Either a SymlinkEntry depset or a map of symlinks to be added to the runfiles. See [Runfiles symlinks](https://bazel.build/extending/rules#runfiles_symlinks) in the rules guide. | + +## split\_attr + +``` struct ctx.split_attr ``` -A struct to access the values of attributes with split configurations. If the attribute is a label list, the value of split_attr is a dict of the keys of the split (as strings) to lists of the ConfiguredTargets in that branch of the split. If the attribute is a label, then the value of split_attr is a dict of the keys of the split (as strings) to single ConfiguredTargets. Attributes with split configurations still appear in the attr struct, but their values will be single lists with all the branches of the split merged together. +A struct to access the values of attributes with split configurations. If the attribute is a label list, the value of split\_attr is a dict of the keys of the split (as strings) to lists of the ConfiguredTargets in that branch of the split. If the attribute is a label, then the value of split\_attr is a dict of the keys of the split (as strings) to single ConfiguredTargets. Attributes with split configurations still appear in the attr struct, but their values will be single lists with all the branches of the split merged together. ## super -``` rule-signature +``` unknown ctx.super() ``` Experimental: Calls parent's implementation function and returns its providers -## target_platform_has_constraint +## target\_platform\_has\_constraint -``` rule-signature +``` bool ctx.target_platform_has_constraint(constraintValue) ``` @@ -523,26 +366,13 @@ Returns true if the given constraint value is part of the current target platfor ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="target_platform_has_constraint.constraintValue"><code>constraintValue</code></td> -<td><a href="../providers/ConstraintValueInfo.html" class="anchor">ConstraintValueInfo</a>; -required<br /> -The constraint value to check the target platform against.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `constraintValue` | [ConstraintValueInfo](../providers/ConstraintValueInfo.mdx); required The constraint value to check the target platform against. | ## toolchains -``` rule-signature +``` ToolchainContext ctx.toolchains ``` @@ -550,24 +380,24 @@ Toolchains for the default exec group of this rule. ## var -``` rule-signature +``` dict ctx.var ``` Dictionary (String to String) of configuration variables. -## version_file +## version\_file -``` rule-signature +``` File ctx.version_file ``` -The file that is used to hold the volatile workspace status for the current build request. See documentation for --workspace_status_command for more information. +The file that is used to hold the volatile workspace status for the current build request. See documentation for --workspace\_status\_command for more information. -## workspace_name +## workspace\_name -``` rule-signature +``` string ctx.workspace_name ``` -The name of the workspace, which is effectively the execution root name and runfiles prefix for the main repo. If `--enable_bzlmod` is on, this is the fixed string `_main`. Otherwise, this is the workspace name as defined in the WORKSPACE file. +The name of the workspace, which is effectively the execution root name and runfiles prefix for the main repo. If `--enable_bzlmod` is on, this is the fixed string `_main`. Otherwise, this is the workspace name as defined in the WORKSPACE file. \ No newline at end of file diff --git a/rules/lib/builtins/depset.mdx b/rules/lib/builtins/depset.mdx index 23d8009..5e84d17 100644 --- a/rules/lib/builtins/depset.mdx +++ b/rules/lib/builtins/depset.mdx @@ -2,14 +2,10 @@ title: 'depset' --- -# depset - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java" %} -{% include "\_buttons.html" %} A specialized data structure that supports efficient merge operations and has a defined traversal order. Commonly used for accumulating data from transitive dependencies in rules and aspects. For -more information see [here](/extending/depsets). +more information see [here](./extending/depsets). The elements of a depset must be hashable and all of the same type (as defined by the built-in [`type(x)`](../globals/all#type) function), but depsets are not simply hash @@ -29,15 +25,15 @@ depsets via the `transitive` argument. The `order` parameter determines the kind of traversal that is done to convert the depset to an iterable. There are four possible values: -- `"default"` (formerly `"stable"`): Order is unspecified (but +* `"default"` (formerly `"stable"`): Order is unspecified (but deterministic). -- `"postorder"` (formerly `"compile"`): A left-to-right post-ordering. +* `"postorder"` (formerly `"compile"`): A left-to-right post-ordering. Precisely, this recursively traverses all children leftmost-first, then the direct elements leftmost-first. -- `"preorder"` (formerly `"naive_link"`): A left-to-right pre-ordering. +* `"preorder"` (formerly `"naive_link"`): A left-to-right pre-ordering. Precisely, this traverses the direct elements leftmost-first, then recursively traverses the children leftmost-first. -- `"topological"` (formerly `"link"`): A topological ordering from the root +* `"topological"` (formerly `"link"`): A topological ordering from the root down to the leaves. There is no left-to-right guarantee. Two depsets may only be merged if either both depsets have the same order, or one of them has @@ -50,12 +46,12 @@ semantics. ## Members -- [to_list](#to_list) +* [to\_list](#to_list) -## to_list +## to\_list -``` rule-signature +``` list depset.to_list() ``` -Returns a list of the elements, without duplicates, in the depset's traversal order. Note that order is unspecified (but deterministic) for elements that were added more than once to the depset. Order is also unspecified for `"default"`-ordered depsets, and for elements of child depsets whose order differs from that of the parent depset. The list is a copy; modifying it has no effect on the depset and vice versa. +Returns a list of the elements, without duplicates, in the depset's traversal order. Note that order is unspecified (but deterministic) for elements that were added more than once to the depset. Order is also unspecified for `"default"`-ordered depsets, and for elements of child depsets whose order differs from that of the parent depset. The list is a copy; modifying it has no effect on the depset and vice versa. \ No newline at end of file diff --git a/rules/lib/builtins/exec_result.mdx b/rules/lib/builtins/exec_result.mdx index 2251122..47fbfdd 100644 --- a/rules/lib/builtins/exec_result.mdx +++ b/rules/lib/builtins/exec_result.mdx @@ -2,21 +2,18 @@ title: 'exec_result' --- -# exec_result -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkExecutionResult.java" %} -{% include "\_buttons.html" %} -A structure storing result of repository_ctx.execute() method. It contains the standard output stream content, the standard error stream content and the execution return code. +A structure storing result of repository\_ctx.execute() method. It contains the standard output stream content, the standard error stream content and the execution return code. ## Members -- [return_code](#return_code) -- [stderr](#stderr) -- [stdout](#stdout) +* [return\_code](#return_code) +* [stderr](#stderr) +* [stdout](#stdout) -## return_code +## return\_code -``` rule-signature +``` int exec_result.return_code ``` @@ -24,7 +21,7 @@ The return code returned after the execution of the program. 256 if the process ## stderr -``` rule-signature +``` string exec_result.stderr ``` @@ -32,8 +29,8 @@ The content of the standard error output returned by the execution. ## stdout -``` rule-signature +``` string exec_result.stdout ``` -The content of the standard output returned by the execution. +The content of the standard output returned by the execution. \ No newline at end of file diff --git a/rules/lib/builtins/extension_metadata.mdx b/rules/lib/builtins/extension_metadata.mdx index 43ec1eb..180e16d 100644 --- a/rules/lib/builtins/extension_metadata.mdx +++ b/rules/lib/builtins/extension_metadata.mdx @@ -2,8 +2,5 @@ title: 'extension_metadata' --- -# extension_metadata -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionMetadata.java" %} -{% include "\_buttons.html" %} -Return values of this type from a module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. +Return values of this type from a module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. \ No newline at end of file diff --git a/rules/lib/builtins/fragments.mdx b/rules/lib/builtins/fragments.mdx index 62aa893..70b847a 100644 --- a/rules/lib/builtins/fragments.mdx +++ b/rules/lib/builtins/fragments.mdx @@ -2,12 +2,9 @@ title: 'fragments' --- -# fragments -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java" %} -{% include "\_buttons.html" %} A collection of configuration fragments available in the current rule implementation context. Access a specific fragment by its field name. For example, `ctx.fragments.java` Only configuration fragments which are declared in the rule definition may be accessed in this collection. -See the [configuration fragment reference](../fragments.html) for a list of available fragments and the [rules documentation](https://bazel.build/extending/rules#configuration_fragments) for how to use them. +See the [configuration fragment reference](../fragments.mdx) for a list of available fragments and the [rules documentation](https://bazel.build/extending/rules#configuration_fragments) for how to use them. \ No newline at end of file diff --git a/rules/lib/builtins/java_annotation_processing.mdx b/rules/lib/builtins/java_annotation_processing.mdx index 7c10274..82bbaad 100644 --- a/rules/lib/builtins/java_annotation_processing.mdx +++ b/rules/lib/builtins/java_annotation_processing.mdx @@ -2,25 +2,22 @@ title: 'java_annotation_processing' --- -# java_annotation_processing -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaAnnotationProcessingApi.java" %} -{% include "\_buttons.html" %} Information about jars that are a result of annotation processing for a Java rule. ## Members -- [class_jar](#class_jar) -- [enabled](#enabled) -- [processor_classnames](#processor_classnames) -- [processor_classpath](#processor_classpath) -- [source_jar](#source_jar) -- [transitive_class_jars](#transitive_class_jars) -- [transitive_source_jars](#transitive_source_jars) +* [class\_jar](#class_jar) +* [enabled](#enabled) +* [processor\_classnames](#processor_classnames) +* [processor\_classpath](#processor_classpath) +* [source\_jar](#source_jar) +* [transitive\_class\_jars](#transitive_class_jars) +* [transitive\_source\_jars](#transitive_source_jars) -## class_jar +## class\_jar -``` rule-signature +``` File java_annotation_processing.class_jar ``` @@ -29,49 +26,49 @@ May return `None`. ## enabled -``` rule-signature +``` bool java_annotation_processing.enabled ``` Deprecated. Returns true if annotation processing was applied on this target. -## processor_classnames +## processor\_classnames -``` rule-signature +``` list java_annotation_processing.processor_classnames ``` Deprecated: Please use `JavaInfo.plugins` instead. Returns class names of annotation processors applied to this rule. -## processor_classpath +## processor\_classpath -``` rule-signature +``` depset java_annotation_processing.processor_classpath ``` Deprecated: Please use `JavaInfo.plugins` instead. Returns a classpath of annotation processors applied to this rule. -## source_jar +## source\_jar -``` rule-signature +``` File java_annotation_processing.source_jar ``` Deprecated: Please use `JavaInfo.java_outputs.generated_source_jar` instead. May return `None`. -## transitive_class_jars +## transitive\_class\_jars -``` rule-signature +``` depset java_annotation_processing.transitive_class_jars ``` Deprecated. Returns a transitive set of class file jars resulting from annotation processing of this rule and its dependencies. -## transitive_source_jars +## transitive\_source\_jars -``` rule-signature +``` depset java_annotation_processing.transitive_source_jars ``` -Deprecated. Returns a transitive set of source archives resulting from annotation processing of this rule and its dependencies. +Deprecated. Returns a transitive set of source archives resulting from annotation processing of this rule and its dependencies. \ No newline at end of file diff --git a/rules/lib/builtins/macro.mdx b/rules/lib/builtins/macro.mdx index a89093d..8228c3b 100644 --- a/rules/lib/builtins/macro.mdx +++ b/rules/lib/builtins/macro.mdx @@ -2,13 +2,10 @@ title: 'macro' --- -# macro -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/MacroFunctionApi.java" %} -{% include "\_buttons.html" %} A callable Starlark value representing a symbolic macro; in other words, the return value of [`macro()`](../globals/bzl.html#macro). Invoking this value during package construction time will instantiate the macro, and cause the macro's implementation function to be evaluated (in a separate context, different from the context in which the macro value was invoked), in most cases causing targets to be added to the package's target set. For more information, see -[Macros](https://bazel.build/extending/macros). +[Macros](https://bazel.build/extending/macros). \ No newline at end of file diff --git a/rules/lib/builtins/mapped_root.mdx b/rules/lib/builtins/mapped_root.mdx index bd66b22..70ce184 100644 --- a/rules/lib/builtins/mapped_root.mdx +++ b/rules/lib/builtins/mapped_root.mdx @@ -2,20 +2,17 @@ title: 'mapped_root' --- -# mapped_root -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/actions/PathMapper.java" %} -{% include "\_buttons.html" %} A root for files that have been subject to path mapping ## Members -- [path](#path) +* [path](#path) ## path -``` rule-signature +``` string mapped_root.path ``` -Returns the relative path from the exec root to the actual root. +Returns the relative path from the exec root to the actual root. \ No newline at end of file diff --git a/rules/lib/builtins/module_ctx.mdx b/rules/lib/builtins/module_ctx.mdx index a8c53f6..b6b0e33 100644 --- a/rules/lib/builtins/module_ctx.mdx +++ b/rules/lib/builtins/module_ctx.mdx @@ -2,261 +2,98 @@ title: 'module_ctx' --- -# module_ctx -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java" %} -{% include "\_buttons.html" %} -The context of the module extension containing helper functions and information about pertinent tags across the dependency graph. You get a module_ctx object as an argument to the `implementation` function when you create a module extension. +The context of the module extension containing helper functions and information about pertinent tags across the dependency graph. You get a module\_ctx object as an argument to the `implementation` function when you create a module extension. ## Members -- [download](#download) -- [download_and_extract](#download_and_extract) -- [execute](#execute) -- [extension_metadata](#extension_metadata) -- [extract](#extract) -- [file](#file) -- [getenv](#getenv) -- [is_dev_dependency](#is_dev_dependency) -- [modules](#modules) -- [os](#os) -- [path](#path) -- [read](#read) -- [report_progress](#report_progress) -- [root_module_has_non_dev_dependency](#root_module_has_non_dev_dependency) -- [watch](#watch) -- [which](#which) +* [download](#download) +* [download\_and\_extract](#download_and_extract) +* [execute](#execute) +* [extension\_metadata](#extension_metadata) +* [extract](#extract) +* [file](#file) +* [getenv](#getenv) +* [is\_dev\_dependency](#is_dev_dependency) +* [modules](#modules) +* [os](#os) +* [path](#path) +* [read](#read) +* [report\_progress](#report_progress) +* [root\_module\_has\_non\_dev\_dependency](#root_module_has_non_dev_dependency) +* [watch](#watch) +* [which](#which) ## download -``` rule-signature -unknown module_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True) ``` +unknown module_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth=\{\}, headers=\{\}, *, integrity='', block=True) +``` + +Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](./rules/lib/repo/cache#get_default_canonical_id) -Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="download.url"><code>url</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or Iterable of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -List of mirror URLs referencing the same file.</td> -</tr> -<tr> -<td id="download.output"><code>output</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -default is <code>''</code><br /> -path to the output file, relative to the repository directory.</td> -</tr> -<tr> -<td id="download.sha256"><code>sha256</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> -</tr> -<tr> -<td id="download.executable"><code>executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Set the executable flag on the created file, false by default.</td> -</tr> -<tr> -<td id="download.allow_fail"><code>allow_fail</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If set, indicate the error in the return value instead of raising an error for failed downloads.</td> -</tr> -<tr> -<td id="download.canonical_id"><code>canonical_id</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (<code>sha256</code> or <code>integrity</code>).</td> -</tr> -<tr> -<td id="download.auth"><code>auth</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying authentication information for some of the URLs.</td> -</tr> -<tr> -<td id="download.headers"><code>headers</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying http headers for all URLs.</td> -</tr> -<tr> -<td id="download.integrity"><code>integrity</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> -</tr> -<tr> -<td id="download.block"><code>block</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual.</td> -</tr> -</tbody> -</table> - -## download_and_extract - -``` rule-signature -struct module_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={}) -``` - -Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) +| Parameter | Description | +| --- | --- | +| `url` | [string](../core/string.mdx); or Iterable of [string](../core/string.mdx)s; required List of mirror URLs referencing the same file. | +| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` path to the output file, relative to the repository directory. | +| `sha256` | [string](../core/string.mdx); default is `''` The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | +| `executable` | [bool](../core/bool.mdx); default is `False` Set the executable flag on the created file, false by default. | +| `allow_fail` | [bool](../core/bool.mdx); default is `False` If set, indicate the error in the return value instead of raising an error for failed downloads. | +| `canonical_id` | [string](../core/string.mdx); default is `''` If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (`sha256` or `integrity`). | +| `auth` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying authentication information for some of the URLs. | +| `headers` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying http headers for all URLs. | +| `integrity` | [string](../core/string.mdx); default is `''` Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | +| `block` | [bool](../core/bool.mdx); default is `True` If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. | + +## download\_and\_extract + +``` +struct module_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth=\{\}, headers=\{\}, *, integrity='', rename_files=\{\}) +``` + +Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](./rules/lib/repo/cache#get_default_canonical_id) + ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="download_and_extract.url"><code>url</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or Iterable of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -List of mirror URLs referencing the same file.</td> -</tr> -<tr> -<td id="download_and_extract.output"><code>output</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -default is <code>''</code><br /> -Path to the directory where the archive will be unpacked, relative to the repository directory.</td> -</tr> -<tr> -<td id="download_and_extract.sha256"><code>sha256</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> -</tr> -<tr> -<td id="download_and_extract.type"><code>type</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here.</td> -</tr> -<tr> -<td id="download_and_extract.strip_prefix"><code>strip_prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -A directory prefix to strip from the extracted files. Many archives contain a -top-level directory that contains all files in the archive. Instead of needing to -specify this prefix over and over in the <code>build_file</code>, this field can -be used to strip it from extracted files. -<p>For compatibility, this parameter may also be used under the deprecated name -<code>stripPrefix</code>.</p></td> -</tr> -<tr> -<td id="download_and_extract.allow_fail"><code>allow_fail</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If set, indicate the error in the return value instead of raising an error for failed downloads.</td> -</tr> -<tr> -<td id="download_and_extract.canonical_id"><code>canonical_id</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum -(<code>sha256</code> or <code>integrity</code>).</td> -</tr> -<tr> -<td id="download_and_extract.auth"><code>auth</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying authentication information for some of the URLs.</td> -</tr> -<tr> -<td id="download_and_extract.headers"><code>headers</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying http headers for all URLs.</td> -</tr> -<tr> -<td id="download_and_extract.integrity"><code>integrity</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> -</tr> -<tr> -<td id="download_and_extract.rename_files"><code>rename_files</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `url` | [string](../core/string.mdx); or Iterable of [string](../core/string.mdx)s; required List of mirror URLs referencing the same file. | +| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` Path to the directory where the archive will be unpacked, relative to the repository directory. | +| `sha256` | [string](../core/string.mdx); default is `''` The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | +| `type` | [string](../core/string.mdx); default is `''` The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. | +| `strip_prefix` | [string](../core/string.mdx); default is `''` A directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the `build_file`, this field can be used to strip it from extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. | +| `allow_fail` | [bool](../core/bool.mdx); default is `False` If set, indicate the error in the return value instead of raising an error for failed downloads. | +| `canonical_id` | [string](../core/string.mdx); default is `''` If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (`sha256` or `integrity`). | +| `auth` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying authentication information for some of the URLs. | +| `headers` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying http headers for all URLs. | +| `integrity` | [string](../core/string.mdx); default is `''` Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | +| `rename_files` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. | ## execute -``` rule-signature -exec_result module_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="") +``` +exec_result module_ctx.execute(arguments, timeout=600, environment=\{\}, quiet=True, working_directory="") ``` Executes the command given by the list of arguments. The execution time of the command is limited by `timeout` (in seconds, default 600 seconds). This method returns an `exec_result` structure containing the output of the command. The `environment` map can be used to override some environment variables to be passed to the process. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="execute.arguments"><code>arguments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -required<br /> -List of arguments, the first element should be the path to the program to execute.</td> -</tr> -<tr> -<td id="execute.timeout"><code>timeout</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>600</code><br /> -Maximum duration of the command in seconds (default is 600 seconds).</td> -</tr> -<tr> -<td id="execute.environment"><code>environment</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -Force some environment variables to be set to be passed to the process. The value can be <code>None</code> to remove the environment variable.</td> -</tr> -<tr> -<td id="execute.quiet"><code>quiet</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -If stdout and stderr should be printed to the terminal.</td> -</tr> -<tr> -<td id="execute.working_directory"><code>working_directory</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>""</code><br /> -Working directory for command execution. -Can be relative to the repository root or absolute. -The default is the repository root.</td> -</tr> -</tbody> -</table> - -## extension_metadata - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `arguments` | [sequence](../core/list.mdx); required List of arguments, the first element should be the path to the program to execute. | +| `timeout` | [int](../core/int.mdx); default is `600` Maximum duration of the command in seconds (default is 600 seconds). | +| `environment` | [dict](../core/dict.mdx); default is `\{\}` Force some environment variables to be set to be passed to the process. The value can be `None` to remove the environment variable. | +| `quiet` | [bool](../core/bool.mdx); default is `True` If stdout and stderr should be printed to the terminal. | +| `working_directory` | [string](../core/string.mdx); default is `""` Working directory for command execution. Can be relative to the repository root or absolute. The default is the repository root. | + +## extension\_metadata + +``` extension_metadata module_ctx.extension_metadata(*, root_module_direct_deps=None, root_module_direct_dev_deps=None, reproducible=False) ``` @@ -264,99 +101,33 @@ Constructs an opaque object that can be returned from the module extension's imp ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="extension_metadata.root_module_direct_deps"><code>root_module_direct_deps</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The names of the repositories that the extension considers to be direct dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via <a href="../globals/module.html#use_repo"><code>use_repo</code></a>, Bazel will print a warning when the extension is evaluated, instructing the user to run <code>bazel mod tidy</code> to fix the <code>use_repo</code> calls automatically. -<p>If one of <code>root_module_direct_deps</code> and will print a warning and a fixup command when the extension is evaluated.</p> -<p>If one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> is specified, the other has to be as well. The lists specified by these two parameters must be disjoint.</p> -<p>Exactly one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> can be set to the special value <code>"all"</code>, which is treated as if a list with the names of all repositories generated by the extension was specified as the value.</p></td> -</tr> -<tr> -<td id="extension_metadata.root_module_direct_dev_deps"><code>root_module_direct_dev_deps</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The names of the repositories that the extension considers to be direct dev dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via <a href="../globals/module.html#use_repo"><code>use_repo</code></a> on an extension proxy created with <a href="../globals/module.html#use_extension"><code>use_extension</code></a><code>(..., dev_dependency = True)</code>, Bazel will print a warning when the extension is evaluated, instructing the user to run <code>bazel mod tidy</code> to fix the <code>use_repo</code> calls automatically. -<p>If one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> is specified, the other has to be as well. The lists specified by these two parameters must be disjoint.</p> -<p>Exactly one of <code>root_module_direct_deps</code> and <code>root_module_direct_dev_deps</code> can be set to the special value <code>"all"</code>, which is treated as if a list with the names of all repositories generated by the extension was specified as the value.</p></td> -</tr> -<tr> -<td id="extension_metadata.reproducible"><code>reproducible</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -States that this module extension ensures complete reproducibility, thereby it should not be stored in the lockfile.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `root_module_direct_deps` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or [string](../core/string.mdx); or `None`; default is `None` The names of the repositories that the extension considers to be direct dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via [`use_repo`](../globals/module.html#use_repo), Bazel will print a warning when the extension is evaluated, instructing the user to run `bazel mod tidy` to fix the `use_repo` calls automatically. If one of `root_module_direct_deps` and will print a warning and a fixup command when the extension is evaluated. If one of `root_module_direct_deps` and `root_module_direct_dev_deps` is specified, the other has to be as well. The lists specified by these two parameters must be disjoint. Exactly one of `root_module_direct_deps` and `root_module_direct_dev_deps` can be set to the special value `"all"`, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. | +| `root_module_direct_dev_deps` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or [string](../core/string.mdx); or `None`; default is `None` The names of the repositories that the extension considers to be direct dev dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via [`use_repo`](../globals/module.html#use_repo) on an extension proxy created with `use_extension(..., dev_dependency = True)`, Bazel will print a warning when the extension is evaluated, instructing the user to run `bazel mod tidy` to fix the `use_repo` calls automatically. If one of `root_module_direct_deps` and `root_module_direct_dev_deps` is specified, the other has to be as well. The lists specified by these two parameters must be disjoint. Exactly one of `root_module_direct_deps` and `root_module_direct_dev_deps` can be set to the special value `"all"`, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. | +| `reproducible` | [bool](../core/bool.mdx); default is `False` States that this module extension ensures complete reproducibility, thereby it should not be stored in the lockfile. | ## extract -``` rule-signature -None module_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto') +``` +None module_ctx.extract(archive, output='', strip_prefix='', *, rename_files=\{\}, watch_archive='auto') ``` Extract an archive to the repository directory. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="extract.archive"><code>archive</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -path to the archive that will be unpacked, relative to the repository directory.</td> -</tr> -<tr> -<td id="extract.output"><code>output</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -default is <code>''</code><br /> -path to the directory where the archive will be unpacked, relative to the repository directory.</td> -</tr> -<tr> -<td id="extract.strip_prefix"><code>strip_prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -a directory prefix to strip from the extracted files. Many archives contain a -top-level directory that contains all files in the archive. Instead of needing to -specify this prefix over and over in the <code>build_file</code>, this field can be -used to strip it from extracted files. -<p>For compatibility, this parameter may also be used under the deprecated name -<code>stripPrefix</code>.</p></td> -</tr> -<tr> -<td id="extract.rename_files"><code>rename_files</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems.</td> -</tr> -<tr> -<td id="extract.watch_archive"><code>watch_archive</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'auto'</code><br /> -whether to <a href="#watch">watch</a> the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `archive` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required path to the archive that will be unpacked, relative to the repository directory. | +| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` path to the directory where the archive will be unpacked, relative to the repository directory. | +| `strip_prefix` | [string](../core/string.mdx); default is `''` a directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the `build_file`, this field can be used to strip it from extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. | +| `rename_files` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. | +| `watch_archive` | [string](../core/string.mdx); default is `'auto'` whether to [watch](#watch) the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | ## file -``` rule-signature +``` None module_ctx.file(path, content='', executable=True, legacy_utf8=False) ``` @@ -364,44 +135,16 @@ Generates a file in the repository directory with the provided content. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="file.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the file to create, relative to the repository directory.</td> -</tr> -<tr> -<td id="file.content"><code>content</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The content of the file to create, empty by default.</td> -</tr> -<tr> -<td id="file.executable"><code>executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -Set the executable flag on the created file, true by default.</td> -</tr> -<tr> -<td id="file.legacy_utf8"><code>legacy_utf8</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -No-op. This parameter is deprecated and will be removed in a future version of Bazel.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to create, relative to the repository directory. | +| `content` | [string](../core/string.mdx); default is `''` The content of the file to create, empty by default. | +| `executable` | [bool](../core/bool.mdx); default is `True` Set the executable flag on the created file, true by default. | +| `legacy_utf8` | [bool](../core/bool.mdx); default is `False` No-op. This parameter is deprecated and will be removed in a future version of Bazel. | ## getenv -``` rule-signature +``` string module_ctx.getenv(name, default=None) ``` @@ -411,69 +154,38 @@ When building incrementally, any change to the value of the variable named by `n ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="getenv.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of desired environment variable.</td> -</tr> -<tr> -<td id="getenv.default"><code>default</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Default value to return if <code>name</code> is not found.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required Name of desired environment variable. | +| `default` | [string](../core/string.mdx); or `None`; default is `None` Default value to return if `name` is not found. | May return `None`. -## is_dev_dependency +## is\_dev\_dependency -``` rule-signature +``` bool module_ctx.is_dev_dependency(tag) ``` -Returns whether the given tag was specified on the result of a [use_extension](../globals/module.html#use_extension) call with `devDependency = True`. +Returns whether the given tag was specified on the result of a [use\_extension](../globals/module.html#use_extension) call with `devDependency = True`. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="is_dev_dependency.tag"><code>tag</code></td> -<td>bazel_module_tag; -required<br /> -A tag obtained from <a href="../builtins/bazel_module.html#tags">bazel_module.tags</a>.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `tag` | bazel\_module\_tag; required A tag obtained from [bazel\_module.tags](../builtins/bazel_module.html#tags). | ## modules -``` rule-signature +``` list module_ctx.modules ``` -A list of all the Bazel modules in the external dependency graph that use this module extension, each of which is a [bazel_module](../builtins/bazel_module.html) object that exposes all the tags it specified for this extension. The iteration order of this dictionary is guaranteed to be the same as breadth-first search starting from the root module. +A list of all the Bazel modules in the external dependency graph that use this module extension, each of which is a [bazel\_module](../builtins/bazel_module.mdx) object that exposes all the tags it specified for this extension. The iteration order of this dictionary is guaranteed to be the same as breadth-first search starting from the root module. ## os -``` rule-signature +``` repository_os module_ctx.os ``` @@ -481,7 +193,7 @@ A struct to access information from the system. ## path -``` rule-signature +``` path module_ctx.path(path) ``` @@ -489,26 +201,13 @@ Returns a path from a string, label, or path. If this context is a `repository_c ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="path.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -<code>string</code>, <code>Label</code> or <code>path</code> from which to create a path from.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required `string`, `Label` or `path` from which to create a path from. | ## read -``` rule-signature +``` string module_ctx.read(path, *, watch='auto') ``` @@ -516,32 +215,14 @@ Reads the content of a file on the filesystem. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="read.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the file to read from.</td> -</tr> -<tr> -<td id="read.watch"><code>watch</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'auto'</code><br /> -Whether to <a href="#watch">watch</a> the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> -</tr> -</tbody> -</table> - -## report_progress - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to read from. | +| `watch` | [string](../core/string.mdx); default is `'auto'` Whether to [watch](#watch) the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | + +## report\_progress + +``` None module_ctx.report_progress(status='') ``` @@ -549,26 +230,13 @@ Updates the progress status for the fetching of this repository or module extens ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="report_progress.status"><code>status</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -<code>string</code> describing the current status of the fetch progress.</td> -</tr> -</tbody> -</table> - -## root_module_has_non_dev_dependency - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `status` | [string](../core/string.mdx); default is `''` `string` describing the current status of the fetch progress. | + +## root\_module\_has\_non\_dev\_dependency + +``` bool module_ctx.root_module_has_non_dev_dependency ``` @@ -576,7 +244,7 @@ Whether the root module uses this extension as a non-dev dependency. ## watch -``` rule-signature +``` None module_ctx.watch(path) ``` @@ -588,26 +256,13 @@ Note that attempting to watch paths inside the repo currently being fetched, or ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="watch.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the file to watch.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to watch. | ## which -``` rule-signature +``` path module_ctx.which(program) ``` @@ -615,21 +270,8 @@ Returns the `path` of the corresponding program or `None` if there is no such pr ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="which.program"><code>program</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Program to find in the path.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `program` | [string](../core/string.mdx); required Program to find in the path. | -May return `None`. +May return `None`. \ No newline at end of file diff --git a/rules/lib/builtins/path.mdx b/rules/lib/builtins/path.mdx index 53d4582..95ab28a 100644 --- a/rules/lib/builtins/path.mdx +++ b/rules/lib/builtins/path.mdx @@ -2,25 +2,22 @@ title: 'path' --- -# path -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkPath.java" %} -{% include "\_buttons.html" %} A structure representing a file to be used inside a repository. ## Members -- [basename](#basename) -- [dirname](#dirname) -- [exists](#exists) -- [get_child](#get_child) -- [is_dir](#is_dir) -- [readdir](#readdir) -- [realpath](#realpath) +* [basename](#basename) +* [dirname](#dirname) +* [exists](#exists) +* [get\_child](#get_child) +* [is\_dir](#is_dir) +* [readdir](#readdir) +* [realpath](#realpath) ## basename -``` rule-signature +``` string path.basename ``` @@ -28,7 +25,7 @@ A string giving the basename of the file. ## dirname -``` rule-signature +``` path path.dirname ``` @@ -37,7 +34,7 @@ May return `None`. ## exists -``` rule-signature +``` bool path.exists ``` @@ -45,9 +42,9 @@ Returns true if the file or directory denoted by this path exists. Note that accessing this field does *not* cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to the path's existence, use the `watch()` method on the context object. -## get_child +## get\_child -``` rule-signature +``` path path.get_child(*relative_paths) ``` @@ -55,25 +52,13 @@ Returns the path obtained by joining this path with the given relative paths. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="get_child.relative_paths"><code>relative_paths</code></td> -<td>required<br /> -Zero or more relative path strings to append to this path with path separators added as needed.</td> -</tr> -</tbody> -</table> - -## is_dir - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `relative_paths` | required Zero or more relative path strings to append to this path with path separators added as needed. | + +## is\_dir + +``` bool path.is_dir ``` @@ -83,7 +68,7 @@ Note that accessing this field does *not* cause the path to be watched. If you'd ## readdir -``` rule-signature +``` list path.readdir(*, watch='auto') ``` @@ -91,28 +76,14 @@ Returns the list of entries in the directory denoted by this path. Each entry is ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="readdir.watch"><code>watch</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'auto'</code><br /> -whether Bazel should watch the list of entries in this directory and refetch the repository or re-evaluate the module extension next time when any changes are detected. Changes to detect include entry creation, deletion, and renaming. Note that this doesn't watch the <em>contents</em> of any entries in the directory. -<p>Can be the string 'yes', 'no', or 'auto'. If set to 'auto', Bazel will only watch this directory when it is legal to do so (see <a href="repository_ctx.html#watch"><code>repository_ctx.watch()</code></a> docs for more information).</p></td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `watch` | [string](../core/string.mdx); default is `'auto'` whether Bazel should watch the list of entries in this directory and refetch the repository or re-evaluate the module extension next time when any changes are detected. Changes to detect include entry creation, deletion, and renaming. Note that this doesn't watch the *contents* of any entries in the directory. Can be the string 'yes', 'no', or 'auto'. If set to 'auto', Bazel will only watch this directory when it is legal to do so (see [`repository_ctx.watch()`](repository_ctx.html#watch) docs for more information). | ## realpath -``` rule-signature +``` path path.realpath ``` -Returns the canonical path for this path by repeatedly replacing all symbolic links with their referents. +Returns the canonical path for this path by repeatedly replacing all symbolic links with their referents. \ No newline at end of file diff --git a/rules/lib/builtins/propagation_ctx.mdx b/rules/lib/builtins/propagation_ctx.mdx index c58fd9b..30f2138 100644 --- a/rules/lib/builtins/propagation_ctx.mdx +++ b/rules/lib/builtins/propagation_ctx.mdx @@ -2,20 +2,17 @@ title: 'propagation_ctx' --- -# propagation_ctx -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectPropagationContextApi.java" %} -{% include "\_buttons.html" %} A context object that is passed to the `propagation_predicate`, `attr_aspects` and `toolchains_aspects` functions of aspects. It provides access to the information needed to determine whether the aspect should be propagated to the target and what attributes or toolchain types it should be propagated to next. ## Members -- [attr](#attr) -- [rule](#rule) +* [attr](#attr) +* [rule](#rule) ## attr -``` rule-signature +``` struct propagation_ctx.attr ``` @@ -23,8 +20,8 @@ A struct to access only the public parameters of the aspect. The keys and values ## rule -``` rule-signature +``` StarlarkAspectPropagationRuleApi propagation_ctx.rule ``` -Allows access to the details of the rule. +Allows access to the details of the rule. \ No newline at end of file diff --git a/rules/lib/builtins/repo_metadata.mdx b/rules/lib/builtins/repo_metadata.mdx index 6fddea8..fbcf9dc 100644 --- a/rules/lib/builtins/repo_metadata.mdx +++ b/rules/lib/builtins/repo_metadata.mdx @@ -2,8 +2,5 @@ title: 'repo_metadata' --- -# repo_metadata -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/RepoMetadata.java" %} -{% include "\_buttons.html" %} -See [`repository_ctx.repo_metadata`](repository_ctx#repo_metadata). +See [`repository_ctx.repo_metadata`](repository_ctx#repo_metadata). \ No newline at end of file diff --git a/rules/lib/builtins/repository_ctx.mdx b/rules/lib/builtins/repository_ctx.mdx index 0dad60b..8540496 100644 --- a/rules/lib/builtins/repository_ctx.mdx +++ b/rules/lib/builtins/repository_ctx.mdx @@ -2,41 +2,38 @@ title: 'repository_ctx' --- -# repository_ctx -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryContext.java" %} -{% include "\_buttons.html" %} -The context of the repository rule containing helper functions and information about attributes. You get a repository_ctx object as an argument to the `implementation` function when you create a repository rule. +The context of the repository rule containing helper functions and information about attributes. You get a repository\_ctx object as an argument to the `implementation` function when you create a repository rule. ## Members -- [attr](#attr) -- [delete](#delete) -- [download](#download) -- [download_and_extract](#download_and_extract) -- [execute](#execute) -- [extract](#extract) -- [file](#file) -- [getenv](#getenv) -- [name](#name) -- [original_name](#original_name) -- [os](#os) -- [patch](#patch) -- [path](#path) -- [read](#read) -- [rename](#rename) -- [repo_metadata](#repo_metadata) -- [report_progress](#report_progress) -- [symlink](#symlink) -- [template](#template) -- [watch](#watch) -- [watch_tree](#watch_tree) -- [which](#which) -- [workspace_root](#workspace_root) +* [attr](#attr) +* [delete](#delete) +* [download](#download) +* [download\_and\_extract](#download_and_extract) +* [execute](#execute) +* [extract](#extract) +* [file](#file) +* [getenv](#getenv) +* [name](#name) +* [original\_name](#original_name) +* [os](#os) +* [patch](#patch) +* [path](#path) +* [read](#read) +* [rename](#rename) +* [repo\_metadata](#repo_metadata) +* [report\_progress](#report_progress) +* [symlink](#symlink) +* [template](#template) +* [watch](#watch) +* [watch\_tree](#watch_tree) +* [which](#which) +* [workspace\_root](#workspace_root) ## attr -``` rule-signature +``` structure repository_ctx.attr ``` @@ -44,7 +41,7 @@ A struct to access the values of the attributes. The values are provided by the ## delete -``` rule-signature +``` bool repository_ctx.delete(path) ``` @@ -52,309 +49,98 @@ Deletes a file or a directory. Returns a bool, indicating whether the file or di ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="delete.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [path](../builtins/path.mdx); required Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string. | ## download -``` rule-signature -unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True) +``` +unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth=\{\}, headers=\{\}, *, integrity='', block=True) ``` -Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) +Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](./rules/lib/repo/cache#get_default_canonical_id) + ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="download.url"><code>url</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or Iterable of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -List of mirror URLs referencing the same file.</td> -</tr> -<tr> -<td id="download.output"><code>output</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -default is <code>''</code><br /> -path to the output file, relative to the repository directory.</td> -</tr> -<tr> -<td id="download.sha256"><code>sha256</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> -</tr> -<tr> -<td id="download.executable"><code>executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Set the executable flag on the created file, false by default.</td> -</tr> -<tr> -<td id="download.allow_fail"><code>allow_fail</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If set, indicate the error in the return value instead of raising an error for failed downloads.</td> -</tr> -<tr> -<td id="download.canonical_id"><code>canonical_id</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (<code>sha256</code> or <code>integrity</code>).</td> -</tr> -<tr> -<td id="download.auth"><code>auth</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying authentication information for some of the URLs.</td> -</tr> -<tr> -<td id="download.headers"><code>headers</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying http headers for all URLs.</td> -</tr> -<tr> -<td id="download.integrity"><code>integrity</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> -</tr> -<tr> -<td id="download.block"><code>block</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual.</td> -</tr> -</tbody> -</table> - -## download_and_extract - -``` rule-signature -struct repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={}) -``` - -Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) +| Parameter | Description | +| --- | --- | +| `url` | [string](../core/string.mdx); or Iterable of [string](../core/string.mdx)s; required List of mirror URLs referencing the same file. | +| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` path to the output file, relative to the repository directory. | +| `sha256` | [string](../core/string.mdx); default is `''` The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | +| `executable` | [bool](../core/bool.mdx); default is `False` Set the executable flag on the created file, false by default. | +| `allow_fail` | [bool](../core/bool.mdx); default is `False` If set, indicate the error in the return value instead of raising an error for failed downloads. | +| `canonical_id` | [string](../core/string.mdx); default is `''` If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (`sha256` or `integrity`). | +| `auth` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying authentication information for some of the URLs. | +| `headers` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying http headers for all URLs. | +| `integrity` | [string](../core/string.mdx); default is `''` Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | +| `block` | [bool](../core/bool.mdx); default is `True` If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. | + +## download\_and\_extract + +``` +struct repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth=\{\}, headers=\{\}, *, integrity='', rename_files=\{\}) +``` + +Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](./rules/lib/repo/cache#get_default_canonical_id) + ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="download_and_extract.url"><code>url</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or Iterable of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -List of mirror URLs referencing the same file.</td> -</tr> -<tr> -<td id="download_and_extract.output"><code>output</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -default is <code>''</code><br /> -Path to the directory where the archive will be unpacked, relative to the repository directory.</td> -</tr> -<tr> -<td id="download_and_extract.sha256"><code>sha256</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> -</tr> -<tr> -<td id="download_and_extract.type"><code>type</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here.</td> -</tr> -<tr> -<td id="download_and_extract.strip_prefix"><code>strip_prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -A directory prefix to strip from the extracted files. Many archives contain a -top-level directory that contains all files in the archive. Instead of needing to -specify this prefix over and over in the <code>build_file</code>, this field can -be used to strip it from extracted files. -<p>For compatibility, this parameter may also be used under the deprecated name -<code>stripPrefix</code>.</p></td> -</tr> -<tr> -<td id="download_and_extract.allow_fail"><code>allow_fail</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If set, indicate the error in the return value instead of raising an error for failed downloads.</td> -</tr> -<tr> -<td id="download_and_extract.canonical_id"><code>canonical_id</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum -(<code>sha256</code> or <code>integrity</code>).</td> -</tr> -<tr> -<td id="download_and_extract.auth"><code>auth</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying authentication information for some of the URLs.</td> -</tr> -<tr> -<td id="download_and_extract.headers"><code>headers</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying http headers for all URLs.</td> -</tr> -<tr> -<td id="download_and_extract.integrity"><code>integrity</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache.</td> -</tr> -<tr> -<td id="download_and_extract.rename_files"><code>rename_files</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `url` | [string](../core/string.mdx); or Iterable of [string](../core/string.mdx)s; required List of mirror URLs referencing the same file. | +| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` Path to the directory where the archive will be unpacked, relative to the repository directory. | +| `sha256` | [string](../core/string.mdx); default is `''` The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | +| `type` | [string](../core/string.mdx); default is `''` The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. | +| `strip_prefix` | [string](../core/string.mdx); default is `''` A directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the `build_file`, this field can be used to strip it from extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. | +| `allow_fail` | [bool](../core/bool.mdx); default is `False` If set, indicate the error in the return value instead of raising an error for failed downloads. | +| `canonical_id` | [string](../core/string.mdx); default is `''` If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (`sha256` or `integrity`). | +| `auth` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying authentication information for some of the URLs. | +| `headers` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying http headers for all URLs. | +| `integrity` | [string](../core/string.mdx); default is `''` Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | +| `rename_files` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. | ## execute -``` rule-signature -exec_result repository_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="") +``` +exec_result repository_ctx.execute(arguments, timeout=600, environment=\{\}, quiet=True, working_directory="") ``` Executes the command given by the list of arguments. The execution time of the command is limited by `timeout` (in seconds, default 600 seconds). This method returns an `exec_result` structure containing the output of the command. The `environment` map can be used to override some environment variables to be passed to the process. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="execute.arguments"><code>arguments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -required<br /> -List of arguments, the first element should be the path to the program to execute.</td> -</tr> -<tr> -<td id="execute.timeout"><code>timeout</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>600</code><br /> -Maximum duration of the command in seconds (default is 600 seconds).</td> -</tr> -<tr> -<td id="execute.environment"><code>environment</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -Force some environment variables to be set to be passed to the process. The value can be <code>None</code> to remove the environment variable.</td> -</tr> -<tr> -<td id="execute.quiet"><code>quiet</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -If stdout and stderr should be printed to the terminal.</td> -</tr> -<tr> -<td id="execute.working_directory"><code>working_directory</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>""</code><br /> -Working directory for command execution. -Can be relative to the repository root or absolute. -The default is the repository root.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `arguments` | [sequence](../core/list.mdx); required List of arguments, the first element should be the path to the program to execute. | +| `timeout` | [int](../core/int.mdx); default is `600` Maximum duration of the command in seconds (default is 600 seconds). | +| `environment` | [dict](../core/dict.mdx); default is `\{\}` Force some environment variables to be set to be passed to the process. The value can be `None` to remove the environment variable. | +| `quiet` | [bool](../core/bool.mdx); default is `True` If stdout and stderr should be printed to the terminal. | +| `working_directory` | [string](../core/string.mdx); default is `""` Working directory for command execution. Can be relative to the repository root or absolute. The default is the repository root. | ## extract -``` rule-signature -None repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto') +``` +None repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files=\{\}, watch_archive='auto') ``` Extract an archive to the repository directory. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="extract.archive"><code>archive</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -path to the archive that will be unpacked, relative to the repository directory.</td> -</tr> -<tr> -<td id="extract.output"><code>output</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -default is <code>''</code><br /> -path to the directory where the archive will be unpacked, relative to the repository directory.</td> -</tr> -<tr> -<td id="extract.strip_prefix"><code>strip_prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -a directory prefix to strip from the extracted files. Many archives contain a -top-level directory that contains all files in the archive. Instead of needing to -specify this prefix over and over in the <code>build_file</code>, this field can be -used to strip it from extracted files. -<p>For compatibility, this parameter may also be used under the deprecated name -<code>stripPrefix</code>.</p></td> -</tr> -<tr> -<td id="extract.rename_files"><code>rename_files</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems.</td> -</tr> -<tr> -<td id="extract.watch_archive"><code>watch_archive</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'auto'</code><br /> -whether to <a href="#watch">watch</a> the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `archive` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required path to the archive that will be unpacked, relative to the repository directory. | +| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` path to the directory where the archive will be unpacked, relative to the repository directory. | +| `strip_prefix` | [string](../core/string.mdx); default is `''` a directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the `build_file`, this field can be used to strip it from extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. | +| `rename_files` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. | +| `watch_archive` | [string](../core/string.mdx); default is `'auto'` whether to [watch](#watch) the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | ## file -``` rule-signature +``` None repository_ctx.file(path, content='', executable=True, legacy_utf8=False) ``` @@ -362,44 +148,16 @@ Generates a file in the repository directory with the provided content. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="file.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the file to create, relative to the repository directory.</td> -</tr> -<tr> -<td id="file.content"><code>content</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The content of the file to create, empty by default.</td> -</tr> -<tr> -<td id="file.executable"><code>executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -Set the executable flag on the created file, true by default.</td> -</tr> -<tr> -<td id="file.legacy_utf8"><code>legacy_utf8</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -No-op. This parameter is deprecated and will be removed in a future version of Bazel.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to create, relative to the repository directory. | +| `content` | [string](../core/string.mdx); default is `''` The content of the file to create, empty by default. | +| `executable` | [bool](../core/bool.mdx); default is `True` Set the executable flag on the created file, true by default. | +| `legacy_utf8` | [bool](../core/bool.mdx); default is `False` No-op. This parameter is deprecated and will be removed in a future version of Bazel. | ## getenv -``` rule-signature +``` string repository_ctx.getenv(name, default=None) ``` @@ -409,42 +167,24 @@ When building incrementally, any change to the value of the variable named by `n ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="getenv.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of desired environment variable.</td> -</tr> -<tr> -<td id="getenv.default"><code>default</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Default value to return if <code>name</code> is not found.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required Name of desired environment variable. | +| `default` | [string](../core/string.mdx); or `None`; default is `None` Default value to return if `name` is not found. | May return `None`. ## name -``` rule-signature +``` string repository_ctx.name ``` The canonical name of the external repository created by this rule. This name is guaranteed to be unique among all external repositories, but its exact format is not specified. Use [`original_name`](#original_name) instead to get the name that was originally specified as the `name` when this repository rule was instantiated. -## original_name +## original\_name -``` rule-signature +``` string repository_ctx.original_name ``` @@ -452,7 +192,7 @@ The name that was originally specified as the `name` attribute when this reposit ## os -``` rule-signature +``` repository_os repository_ctx.os ``` @@ -460,46 +200,23 @@ A struct to access information from the system. ## patch -``` rule-signature +``` None repository_ctx.patch(patch_file, strip=0, *, watch_patch='auto') ``` -Apply a patch file to the root directory of external repository. The patch file should be a standard [unified diff format](https://en.wikipedia.org/wiki/Diff#Unified_format) file. The Bazel-native patch implementation doesn't support fuzz match and binary patch like the patch command line tool. +Apply a patch file to the root directory of external repository. The patch file should be a standard [unified diff format](https://en.wikipedia.org/wiki/Diff#Unified_format) file. The Bazel-native patch implementation doesn't support fuzz match and binary patch like the patch command line tool. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="patch.patch_file"><code>patch_file</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -The patch file to apply, it can be label, relative path or absolute path. If it's a relative path, it will resolve to the repository directory.</td> -</tr> -<tr> -<td id="patch.strip"><code>strip</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>0</code><br /> -Strip the specified number of leading components from file names.</td> -</tr> -<tr> -<td id="patch.watch_patch"><code>watch_patch</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'auto'</code><br /> -Whether to <a href="#watch">watch</a> the patch file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `patch_file` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The patch file to apply, it can be label, relative path or absolute path. If it's a relative path, it will resolve to the repository directory. | +| `strip` | [int](../core/int.mdx); default is `0` Strip the specified number of leading components from file names. | +| `watch_patch` | [string](../core/string.mdx); default is `'auto'` Whether to [watch](#watch) the patch file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | ## path -``` rule-signature +``` path repository_ctx.path(path) ``` @@ -507,26 +224,13 @@ Returns a path from a string, label, or path. If this context is a `repository_c ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="path.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -<code>string</code>, <code>Label</code> or <code>path</code> from which to create a path from.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required `string`, `Label` or `path` from which to create a path from. | ## read -``` rule-signature +``` string repository_ctx.read(path, *, watch='auto') ``` @@ -534,32 +238,14 @@ Reads the content of a file on the filesystem. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="read.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the file to read from.</td> -</tr> -<tr> -<td id="read.watch"><code>watch</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'auto'</code><br /> -Whether to <a href="#watch">watch</a> the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to read from. | +| `watch` | [string](../core/string.mdx); default is `'auto'` Whether to [watch](#watch) the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | ## rename -``` rule-signature +``` None repository_ctx.rename(src, dst) ``` @@ -568,68 +254,29 @@ already exists. Both paths must be located within the repository. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="rename.src"><code>src</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -The path of the existing file or directory to rename, relative -to the repository directory.</td> -</tr> -<tr> -<td id="rename.dst"><code>dst</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -The new name to which the file or directory will be renamed to, -relative to the repository directory.</td> -</tr> -</tbody> -</table> - -## repo_metadata - -``` rule-signature -repo_metadata repository_ctx.repo_metadata(*, reproducible=False, attrs_for_reproducibility={}) +| Parameter | Description | +| --- | --- | +| `src` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The path of the existing file or directory to rename, relative to the repository directory. | +| `dst` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The new name to which the file or directory will be renamed to, relative to the repository directory. | + +## repo\_metadata + +``` +repo_metadata repository_ctx.repo_metadata(*, reproducible=False, attrs_for_reproducibility=\{\}) ``` Constructs an opaque object that can be returned from the repo rule's implementation function to provide metadata about its reproducibility. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="repo_metadata.reproducible"><code>reproducible</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -States that this repo can be reproducibly refetched; that is, if it were fetched another time with exactly the same input attributes, repo rule definition, watched files and environment variables, etc., then exactly the same output would be produced. This property needs to hold even if other untracked conditions change, such as information from the internet, the path of the workspace root, output from running arbitrary executables, etc. If set to True, this allows the fetched repo contents to be cached across workspaces. -<p>Note that setting this to True does not guarantee caching in the repo contents cache; for example, local repo rules are never cached.</p></td> -</tr> -<tr> -<td id="repo_metadata.attrs_for_reproducibility"><code>attrs_for_reproducibility</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -If <code>reproducible</code> is False, this can be specified to tell Bazel which attributes of the original repo rule to change to make it reproducible.</td> -</tr> -</tbody> -</table> - -## report_progress - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `reproducible` | [bool](../core/bool.mdx); default is `False` States that this repo can be reproducibly refetched; that is, if it were fetched another time with exactly the same input attributes, repo rule definition, watched files and environment variables, etc., then exactly the same output would be produced. This property needs to hold even if other untracked conditions change, such as information from the internet, the path of the workspace root, output from running arbitrary executables, etc. If set to True, this allows the fetched repo contents to be cached across workspaces. Note that setting this to True does not guarantee caching in the repo contents cache; for example, local repo rules are never cached. | +| `attrs_for_reproducibility` | [dict](../core/dict.mdx); default is `\{\}` If `reproducible` is False, this can be specified to tell Bazel which attributes of the original repo rule to change to make it reproducible. | + +## report\_progress + +``` None repository_ctx.report_progress(status='') ``` @@ -637,26 +284,13 @@ Updates the progress status for the fetching of this repository or module extens ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="report_progress.status"><code>status</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -<code>string</code> describing the current status of the fetch progress.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `status` | [string](../core/string.mdx); default is `''` `string` describing the current status of the fetch progress. | ## symlink -``` rule-signature +``` None repository_ctx.symlink(target, link_name) ``` @@ -664,83 +298,32 @@ Creates a symlink on the filesystem. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="symlink.target"><code>target</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -The path that the symlink should point to.</td> -</tr> -<tr> -<td id="symlink.link_name"><code>link_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -The path of the symlink to create.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `target` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The path that the symlink should point to. | +| `link_name` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The path of the symlink to create. | ## template -``` rule-signature -None repository_ctx.template(path, template, substitutions={}, executable=True, *, watch_template='auto') +``` +None repository_ctx.template(path, template, substitutions=\{\}, executable=True, *, watch_template='auto') ``` Generates a new file using a `template`. Every occurrence in `template` of a key of `substitutions` will be replaced by the corresponding value. The result is written in `path`. An optional `executable` argument (default to true) can be set to turn on or off the executable bit. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="template.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the file to create, relative to the repository directory.</td> -</tr> -<tr> -<td id="template.template"><code>template</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path to the template file.</td> -</tr> -<tr> -<td id="template.substitutions"><code>substitutions</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -Substitutions to make when expanding the template.</td> -</tr> -<tr> -<td id="template.executable"><code>executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -Set the executable flag on the created file, true by default.</td> -</tr> -<tr> -<td id="template.watch_template"><code>watch_template</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'auto'</code><br /> -Whether to <a href="#watch">watch</a> the template file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the <a href="#watch"><code>watch()</code></a> method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see <code>watch()</code> docs for more information.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to create, relative to the repository directory. | +| `template` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path to the template file. | +| `substitutions` | [dict](../core/dict.mdx); default is `\{\}` Substitutions to make when expanding the template. | +| `executable` | [bool](../core/bool.mdx); default is `True` Set the executable flag on the created file, true by default. | +| `watch_template` | [string](../core/string.mdx); default is `'auto'` Whether to [watch](#watch) the template file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | ## watch -``` rule-signature +``` None repository_ctx.watch(path) ``` @@ -752,26 +335,13 @@ Note that attempting to watch paths inside the repo currently being fetched, or ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="watch.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the file to watch.</td> -</tr> -</tbody> -</table> - -## watch_tree - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to watch. | + +## watch\_tree + +``` None repository_ctx.watch_tree(path) ``` @@ -781,26 +351,13 @@ Note that attempting to watch paths inside the repo currently being fetched will ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="watch_tree.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../builtins/path.html" class="anchor">path</a>; -required<br /> -Path of the directory tree to watch.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the directory tree to watch. | ## which -``` rule-signature +``` path repository_ctx.which(program) ``` @@ -808,29 +365,16 @@ Returns the `path` of the corresponding program or `None` if there is no such pr ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="which.program"><code>program</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Program to find in the path.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `program` | [string](../core/string.mdx); required Program to find in the path. | May return `None`. -## workspace_root +## workspace\_root -``` rule-signature +``` path repository_ctx.workspace_root ``` -The path to the root workspace of the bazel invocation. +The path to the root workspace of the bazel invocation. \ No newline at end of file diff --git a/rules/lib/builtins/repository_os.mdx b/rules/lib/builtins/repository_os.mdx index bb7f1fd..baac91e 100644 --- a/rules/lib/builtins/repository_os.mdx +++ b/rules/lib/builtins/repository_os.mdx @@ -2,21 +2,18 @@ title: 'repository_os' --- -# repository_os -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkOS.java" %} -{% include "\_buttons.html" %} Various data about the current platform Bazel is running on. ## Members -- [arch](#arch) -- [environ](#environ) -- [name](#name) +* [arch](#arch) +* [environ](#environ) +* [name](#name) ## arch -``` rule-signature +``` string repository_os.arch ``` @@ -24,7 +21,7 @@ A string identifying the architecture Bazel is running on (the value of the `"os ## environ -``` rule-signature +``` dict repository_os.environ ``` @@ -34,8 +31,8 @@ The dictionary of environment variables. ## name -``` rule-signature +``` string repository_os.name ``` -A string identifying the operating system Bazel is running on (the value of the `"os.name"` Java property converted to lower case). +A string identifying the operating system Bazel is running on (the value of the `"os.name"` Java property converted to lower case). \ No newline at end of file diff --git a/rules/lib/builtins/repository_rule.mdx b/rules/lib/builtins/repository_rule.mdx index 9280546..269be17 100644 --- a/rules/lib/builtins/repository_rule.mdx +++ b/rules/lib/builtins/repository_rule.mdx @@ -2,8 +2,5 @@ title: 'repository_rule' --- -# repository_rule -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java" %} -{% include "\_buttons.html" %} -A callable value that may be invoked within the implementation function of a module extension to instantiate and return a repository rule. Created by [`repository_rule()`](../globals/bzl.html#repository_rule). +A callable value that may be invoked within the implementation function of a module extension to instantiate and return a repository rule. Created by [`repository_rule()`](../globals/bzl.html#repository_rule). \ No newline at end of file diff --git a/rules/lib/builtins/root.mdx b/rules/lib/builtins/root.mdx index b53b1f1..43fe0d5 100644 --- a/rules/lib/builtins/root.mdx +++ b/rules/lib/builtins/root.mdx @@ -2,20 +2,17 @@ title: 'root' --- -# root -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileRootApi.java" %} -{% include "\_buttons.html" %} A root for files. The roots are the directories containing files, and they are mapped together into a single directory tree to form the execution environment. ## Members -- [path](#path) +* [path](#path) ## path -``` rule-signature +``` string root.path ``` -Returns the relative path from the exec root to the actual root. +Returns the relative path from the exec root to the actual root. \ No newline at end of file diff --git a/rules/lib/builtins/rule.mdx b/rules/lib/builtins/rule.mdx index 3e9629d..cd2e123 100644 --- a/rules/lib/builtins/rule.mdx +++ b/rules/lib/builtins/rule.mdx @@ -2,12 +2,9 @@ title: 'rule' --- -# rule -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RuleFunctionApi.java" %} -{% include "\_buttons.html" %} A callable value representing the type of a native or Starlark rule (created by [`rule()`](../globals/bzl.html#rule)). Calling the value during evaluation of a package's BUILD file creates an instance of the rule and adds it to the package's target set. For more information, visit this page about -[Rules](https://bazel.build/extending/rules). +[Rules](https://bazel.build/extending/rules). \ No newline at end of file diff --git a/rules/lib/builtins/rule_attributes.mdx b/rules/lib/builtins/rule_attributes.mdx index 71866c5..91d9d68 100644 --- a/rules/lib/builtins/rule_attributes.mdx +++ b/rules/lib/builtins/rule_attributes.mdx @@ -2,34 +2,31 @@ title: 'rule_attributes' --- -# rule_attributes -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttributesCollectionApi.java" %} -{% include "\_buttons.html" %} Information about attributes of a rule an aspect is applied to. ## Members -- [attr](#attr) -- [exec_groups](#exec_groups) -- [executable](#executable) -- [file](#file) -- [files](#files) -- [kind](#kind) -- [toolchains](#toolchains) -- [var](#var) +* [attr](#attr) +* [exec\_groups](#exec_groups) +* [executable](#executable) +* [file](#file) +* [files](#files) +* [kind](#kind) +* [toolchains](#toolchains) +* [var](#var) ## attr -``` rule-signature +``` struct rule_attributes.attr ``` A struct to access the values of the [attributes](https://bazel.build/extending/rules#attributes). The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the [`attrs` dict](../globals/bzl.html#rule.attrs) provided to the [`rule` function](../globals/bzl.html#rule). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl). -## exec_groups +## exec\_groups -``` rule-signature +``` ExecGroupCollection rule_attributes.exec_groups ``` @@ -37,51 +34,51 @@ A collection of the execution groups available for the rule the aspect is applie ## executable -``` rule-signature +``` struct rule_attributes.executable ``` -A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). +A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.mdx) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). ## file -``` rule-signature +``` struct rule_attributes.file ``` -A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: +A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.mdx) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: -``` python -list(ctx.attr.<ATTR>.files)[0] +``` +list(ctx.attr.\<ATTR\>.files)[0] ``` In other words, use `file` to access the (singular) [default output](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). ## files -``` rule-signature +``` struct rule_attributes.files ``` -A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.html)s. It is a shortcut for: +A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.mdx)s. It is a shortcut for: -``` python -[f for t in ctx.attr.<ATTR> for f in t.files] +``` +[f for t in ctx.attr.\<ATTR\> for f in t.files] ``` -In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). +In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). ## kind -``` rule-signature +``` string rule_attributes.kind ``` -The kind of a rule, such as 'cc_library' +The kind of a rule, such as 'cc\_library' ## toolchains -``` rule-signature +``` ToolchainContext rule_attributes.toolchains ``` @@ -89,8 +86,8 @@ Toolchains for the default exec group of the rule the aspect is applied to. ## var -``` rule-signature +``` dict rule_attributes.var ``` -Dictionary (String to String) of configuration variables. +Dictionary (String to String) of configuration variables. \ No newline at end of file diff --git a/rules/lib/builtins/runfiles.mdx b/rules/lib/builtins/runfiles.mdx index e5bd09e..a14b8a8 100644 --- a/rules/lib/builtins/runfiles.mdx +++ b/rules/lib/builtins/runfiles.mdx @@ -2,26 +2,23 @@ title: 'runfiles' --- -# runfiles -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java" %} -{% include "\_buttons.html" %} -A container of information regarding a set of files required at runtime by an executable. This object should be passed via [`DefaultInfo`](../providers/DefaultInfo.html) in order to tell the build system about the runfiles needed by the outputs produced by the rule. +A container of information regarding a set of files required at runtime by an executable. This object should be passed via [`DefaultInfo`](../providers/DefaultInfo.mdx) in order to tell the build system about the runfiles needed by the outputs produced by the rule. See [runfiles guide](https://bazel.build/extending/rules#runfiles) for details. ## Members -- [empty_filenames](#empty_filenames) -- [files](#files) -- [merge](#merge) -- [merge_all](#merge_all) -- [root_symlinks](#root_symlinks) -- [symlinks](#symlinks) +* [empty\_filenames](#empty_filenames) +* [files](#files) +* [merge](#merge) +* [merge\_all](#merge_all) +* [root\_symlinks](#root_symlinks) +* [symlinks](#symlinks) -## empty_filenames +## empty\_filenames -``` rule-signature +``` depset runfiles.empty_filenames ``` @@ -29,7 +26,7 @@ Returns names of empty files to create. ## files -``` rule-signature +``` depset runfiles.files ``` @@ -37,7 +34,7 @@ Returns the set of runfiles as files. ## merge -``` rule-signature +``` runfiles runfiles.merge(other) ``` @@ -47,26 +44,13 @@ Returns a new runfiles object that includes all the contents of this one and the ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="merge.other"><code>other</code></td> -<td><a href="../builtins/runfiles.html" class="anchor">runfiles</a>; -required<br /> -The runfiles object to merge into this.</td> -</tr> -</tbody> -</table> - -## merge_all - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `other` | [runfiles](../builtins/runfiles.mdx); required The runfiles object to merge into this. | + +## merge\_all + +``` runfiles runfiles.merge_all(other) ``` @@ -74,26 +58,13 @@ Returns a new runfiles object that includes all the contents of this one and of ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="merge_all.other"><code>other</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/runfiles.html" class="anchor">runfiles</a>s; -required<br /> -The sequence of runfiles objects to merge into this.</td> -</tr> -</tbody> -</table> - -## root_symlinks - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `other` | [sequence](../core/list.mdx) of [runfiles](../builtins/runfiles.mdx)s; required The sequence of runfiles objects to merge into this. | + +## root\_symlinks + +``` depset runfiles.root_symlinks ``` @@ -101,8 +72,8 @@ Returns the set of root symlinks. ## symlinks -``` rule-signature +``` depset runfiles.symlinks ``` -Returns the set of symlinks. +Returns the set of symlinks. \ No newline at end of file diff --git a/rules/lib/builtins/struct.mdx b/rules/lib/builtins/struct.mdx index e44043c..eb8d04b 100644 --- a/rules/lib/builtins/struct.mdx +++ b/rules/lib/builtins/struct.mdx @@ -2,45 +2,30 @@ title: 'struct' --- -# struct -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/StructApi.java" %} -{% include "\_buttons.html" %} A generic object with fields. Structs fields cannot be reassigned once the struct is created. Two structs are equal if they have the same fields and if corresponding field values are equal. ## Members -- [struct](#struct) +* [struct](#struct) ## struct -``` rule-signature +``` struct struct(**kwargs) ``` Creates an immutable struct using the keyword arguments as attributes. It is used to group multiple values together. Example: -``` python +``` s = struct(x = 2, y = 3) return s.x + getattr(s, "y") # returns 5 ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="struct.kwargs"><code>kwargs</code></td> -<td>default is <code>{}</code><br /> -Dictionary of arguments.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `kwargs` | default is `\{\}` | \ No newline at end of file diff --git a/rules/lib/builtins/subrule_ctx.mdx b/rules/lib/builtins/subrule_ctx.mdx index 7635743..cb82a90 100644 --- a/rules/lib/builtins/subrule_ctx.mdx +++ b/rules/lib/builtins/subrule_ctx.mdx @@ -2,22 +2,19 @@ title: 'subrule_ctx' --- -# subrule_ctx -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkSubrule.java" %} -{% include "\_buttons.html" %} A context object passed to the implementation function of a subrule. ## Members -- [actions](#actions) -- [fragments](#fragments) -- [label](#label) -- [toolchains](#toolchains) +* [actions](#actions) +* [fragments](#fragments) +* [label](#label) +* [toolchains](#toolchains) ## actions -``` rule-signature +``` actions subrule_ctx.actions ``` @@ -25,7 +22,7 @@ Contains methods for declaring output files and the actions that produce them ## fragments -``` rule-signature +``` fragments subrule_ctx.fragments ``` @@ -33,7 +30,7 @@ Allows access to configuration fragments in target configuration. ## label -``` rule-signature +``` Label subrule_ctx.label ``` @@ -41,8 +38,8 @@ The label of the target currently being analyzed ## toolchains -``` rule-signature +``` ToolchainContext subrule_ctx.toolchains ``` -Contains methods for declaring output files and the actions that produce them +Contains methods for declaring output files and the actions that produce them \ No newline at end of file diff --git a/rules/lib/builtins/tag_class.mdx b/rules/lib/builtins/tag_class.mdx index 6af948b..2014823 100644 --- a/rules/lib/builtins/tag_class.mdx +++ b/rules/lib/builtins/tag_class.mdx @@ -2,8 +2,5 @@ title: 'tag_class' --- -# tag_class -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java" %} -{% include "\_buttons.html" %} -Defines a schema of attributes for a tag, created by [`tag_class()`](../globals/bzl.html#tag_class). +Defines a schema of attributes for a tag, created by [`tag_class()`](../globals/bzl.html#tag_class). \ No newline at end of file diff --git a/rules/lib/builtins/template_ctx.mdx b/rules/lib/builtins/template_ctx.mdx index 38433e7..cc8078f 100644 --- a/rules/lib/builtins/template_ctx.mdx +++ b/rules/lib/builtins/template_ctx.mdx @@ -2,29 +2,26 @@ title: 'template_ctx' --- -# template_ctx -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkTemplateContextApi.java" %} -{% include "\_buttons.html" %} A context object that is passed to the action template expansion function. ## Members -- [args](#args) -- [declare_file](#declare_file) -- [run](#run) +* [args](#args) +* [declare\_file](#declare_file) +* [run](#run) ## args -``` rule-signature +``` Args template_ctx.args() ``` Returns an Args object that can be used to build memory-efficient command lines. -## declare_file +## declare\_file -``` rule-signature +``` File template_ctx.declare_file(filename, *, directory) ``` @@ -34,32 +31,14 @@ Remember that in addition to declaring a file, you must separately create an act ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="declare_file.filename"><code>filename</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The relative path of the file within the directory.</td> -</tr> -<tr> -<td id="declare_file.directory"><code>directory</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The directory in which the file should be created.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `filename` | [string](../core/string.mdx); required The relative path of the file within the directory. | +| `directory` | [File](../builtins/File.mdx); required The directory in which the file should be created. | ## run -``` rule-signature +``` None template_ctx.run(*, outputs, inputs=[], executable, tools=None, arguments=[], progress_message=None) ``` @@ -67,56 +46,11 @@ Creates an action that runs an executable. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="run.outputs"><code>outputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -required<br /> -List of the output files of the action.</td> -</tr> -<tr> -<td id="run.inputs"><code>inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>[]</code><br /> -List or depset of the input files of the action.</td> -</tr> -<tr> -<td id="run.executable"><code>executable</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <a href="../core/string.html" class="anchor">string</a>; or <a href="../providers/FilesToRunProvider.html" class="anchor">FilesToRunProvider</a>; -required<br /> -The executable file to be called by the action.</td> -</tr> -<tr> -<td id="run.tools"><code>tools</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -List or <a href="../builtins/depset.html"><code>depset</code></a> of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. -<p>When a list is provided, it can be a heterogenous collection of:</p> -<ul> -<li><code>File</code>s</li> -<li><code>FilesToRunProvider</code> instances</li> -<li><code>depset</code>s of <code>File</code>s</li> -</ul> -<code>File</code>s from <a href="../builtins/ctx#executable"><code>ctx.executable</code></a> and <code>FilesToRunProvider</code>s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs.</td> -</tr> -<tr> -<td id="run.arguments"><code>arguments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Command line arguments of the action. Must be a list of strings or <a href="#args"><code>actions.args()</code></a> objects.</td> -</tr> -<tr> -<td id="run.progress_message"><code>progress_message</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Progress message to show to the user during the build.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `outputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; required List of the output files of the action. | +| `inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `[]` List or depset of the input files of the action. | +| `executable` | [File](../builtins/File.mdx); or [string](../core/string.mdx); or [FilesToRunProvider](../providers/FilesToRunProvider.mdx); required The executable file to be called by the action. | +| `tools` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); or `None`; default is `None` List or [`depset`](../builtins/depset.mdx) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. When a list is provided, it can be a heterogenous collection of: * `File`s * `FilesToRunProvider` instances * `depset`s of `File`s `File`s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider`s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. | +| `arguments` | [sequence](../core/list.mdx); default is `[]` Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. | +| `progress_message` | [string](../core/string.mdx); or `None`; default is `None` Progress message to show to the user during the build. | \ No newline at end of file diff --git a/rules/lib/builtins/toolchain_type.mdx b/rules/lib/builtins/toolchain_type.mdx index ee9df28..d5c67a9 100644 --- a/rules/lib/builtins/toolchain_type.mdx +++ b/rules/lib/builtins/toolchain_type.mdx @@ -2,29 +2,26 @@ title: 'toolchain_type' --- -# toolchain_type -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkToolchainTypeRequirement.java" %} -{% include "\_buttons.html" %} A data type describing a dependency on a specific toolchain type. ## Members -- [mandatory](#mandatory) -- [toolchain_type](#toolchain_type) +* [mandatory](#mandatory) +* [toolchain\_type](#toolchain_type) ## mandatory -``` rule-signature +``` bool toolchain_type.mandatory ``` Whether the toolchain type is mandatory or optional. -## toolchain_type +## toolchain\_type -``` rule-signature +``` Label toolchain_type.toolchain_type ``` -The toolchain type that is required. +The toolchain type that is required. \ No newline at end of file diff --git a/rules/lib/builtins/transition.mdx b/rules/lib/builtins/transition.mdx index d5e39f5..520b936 100644 --- a/rules/lib/builtins/transition.mdx +++ b/rules/lib/builtins/transition.mdx @@ -2,20 +2,16 @@ title: 'transition' --- -# transition - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigurationTransitionApi.java" %} -{% include "\_buttons.html" %} Represents a configuration transition across a dependency edge. For example, if `//package:foo` depends on `//package:bar` with a configuration transition, then the configuration of `//package:bar` (and its dependencies) will be `//package:foo`'s configuration plus the changes specified by the transition function. ## Members -- [transition](#transition) +* [transition](#transition) ## transition -``` rule-signature +``` transition transition(*, implementation, inputs, outputs) ``` @@ -23,13 +19,12 @@ A transition that reads a set of input build settings and writes a set of output Example: -``` python - +``` def _transition_impl(settings, attr): # This transition just reads the current CPU value as a demonstration. # A real transition could incorporate this into its followup logic. current_cpu = settings["//command_line_option:cpu"] - return {"//command_line_option:compilation_mode": "dbg"} + return \{"//command_line_option:compilation_mode": "dbg"\} build_in_debug_mode = transition( implementation = _transition_impl, @@ -42,33 +37,8 @@ For more details see [here](https://bazel.build/rules/config#user-defined-transi ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="transition.implementation"><code>implementation</code></td> -<td>callable; -required<br /> -The function implementing this transition. This function always has two parameters: <code>settings</code> and <code>attr</code>. The <code>settings</code> param is a dictionary whose set of keys is defined by the inputs parameter. So, for each build setting <code>--//foo=bar</code>, if <code>inputs</code> contains <code>//foo</code>, <code>settings</code> will have an entry <code>settings['//foo']='bar'</code>. -<p>The <code>attr</code> param is a reference to <code>ctx.attr</code>. This gives the implementation function access to the rule's attributes to make attribute-parameterized transitions possible.</p> -<p>This function must return a <code>dict</code> from build setting identifier to build setting value; this represents the configuration transition: for each entry in the returned <code>dict</code>, the transition updates that setting to the new value. All other settings are unchanged. This function can also return a <code>list</code> of <code>dict</code>s or a <code>dict</code> of <code>dict</code>s in the case of a split transition.</p></td> -</tr> -<tr> -<td id="transition.inputs"><code>inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -List of build settings that can be read by this transition. This becomes the key set of the settings parameter of the implementation function parameter.</td> -</tr> -<tr> -<td id="transition.outputs"><code>outputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -List of build settings that can be written by this transition. This must be a superset of the key set of the dictionary returned by this transition.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `implementation` | callable; required The function implementing this transition. This function always has two parameters: `settings` and `attr`. The `settings` param is a dictionary whose set of keys is defined by the inputs parameter. So, for each build setting `--//foo=bar`, if `inputs` contains `//foo`, `settings` will have an entry `settings['//foo']='bar'`. The `attr` param is a reference to `ctx.attr`. This gives the implementation function access to the rule's attributes to make attribute-parameterized transitions possible. This function must return a `dict` from build setting identifier to build setting value; this represents the configuration transition: for each entry in the returned `dict`, the transition updates that setting to the new value. All other settings are unchanged. This function can also return a `list` of `dict`s or a `dict` of `dict`s in the case of a split transition. | +| `inputs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required List of build settings that can be read by this transition. This becomes the key set of the settings parameter of the implementation function parameter. | +| `outputs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required List of build settings that can be written by this transition. This must be a superset of the key set of the dictionary returned by this transition. | \ No newline at end of file diff --git a/rules/lib/builtins/wasm_exec_result.mdx b/rules/lib/builtins/wasm_exec_result.mdx index 25f6706..7d2c4ae 100644 --- a/rules/lib/builtins/wasm_exec_result.mdx +++ b/rules/lib/builtins/wasm_exec_result.mdx @@ -2,10 +2,7 @@ title: 'wasm_exec_result' --- -# wasm_exec_result -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkWasmExecutionResult.java" %} -{% include "\_buttons.html" %} The result of executing a WebAssembly function with `repository_ctx.execute_wasm()`. It contains the function's return value and output buffer. @@ -15,13 +12,13 @@ and the `error_message` field will be set. ## Members -- [error_message](#error_message) -- [output](#output) -- [return_code](#return_code) +* [error\_message](#error_message) +* [output](#output) +* [return\_code](#return_code) -## error_message +## error\_message -``` rule-signature +``` string wasm_exec_result.error_message ``` @@ -29,17 +26,17 @@ Contains an error message if execution failed before the function returned. ## output -``` rule-signature +``` string wasm_exec_result.output ``` The content of the output buffer returned by the WebAssembly function. -## return_code +## return\_code -``` rule-signature +``` long wasm_exec_result.return_code ``` The return value of the WebAssembly function, or a negative value if execution -was terminated before the function returned. +was terminated before the function returned. \ No newline at end of file diff --git a/rules/lib/builtins/wasm_module.mdx b/rules/lib/builtins/wasm_module.mdx index 4bc626f..c0e6fa1 100644 --- a/rules/lib/builtins/wasm_module.mdx +++ b/rules/lib/builtins/wasm_module.mdx @@ -2,20 +2,17 @@ title: 'wasm_module' --- -# wasm_module -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkWasmModule.java" %} -{% include "\_buttons.html" %} A WebAssembly module loaded by `repository_ctx.load_wasm()`. ## Members -- [path](#path) +* [path](#path) ## path -``` rule-signature +``` unknown wasm_module.path ``` -The path this WebAssembly module was loaded from. +The path this WebAssembly module was loaded from. \ No newline at end of file diff --git a/rules/lib/core.mdx b/rules/lib/core.mdx index 1d1c5ce..fa6f884 100644 --- a/rules/lib/core.mdx +++ b/rules/lib/core.mdx @@ -2,21 +2,18 @@ title: 'core' --- -# Core Starlark data types -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} This section lists the data types of the [Starlark core language](https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions). With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. -- [bool](/rules/lib/core/bool) -- [builtin_function_or_method](/rules/lib/core/builtin_function_or_method) -- [dict](/rules/lib/core/dict) -- [float](/rules/lib/core/float) -- [function](/rules/lib/core/function) -- [int](/rules/lib/core/int) -- [json](/rules/lib/core/json) -- [list](/rules/lib/core/list) -- [range](/rules/lib/core/range) -- [set](/rules/lib/core/set) -- [string](/rules/lib/core/string) -- [tuple](/rules/lib/core/tuple) +* [bool](./rules/lib/core/bool) +* [builtin\_function\_or\_method](./rules/lib/core/builtin_function_or_method) +* [dict](./rules/lib/core/dict) +* [float](./rules/lib/core/float) +* [function](./rules/lib/core/function) +* [int](./rules/lib/core/int) +* [json](./rules/lib/core/json) +* [list](./rules/lib/core/list) +* [range](./rules/lib/core/range) +* [set](./rules/lib/core/set) +* [string](./rules/lib/core/string) +* [tuple](./rules/lib/core/tuple) \ No newline at end of file diff --git a/rules/lib/core/bool.mdx b/rules/lib/core/bool.mdx index 82c316f..1d30674 100644 --- a/rules/lib/core/bool.mdx +++ b/rules/lib/core/bool.mdx @@ -2,8 +2,5 @@ title: 'bool' --- -# bool -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/MethodLibrary.java" %} -{% include "\_buttons.html" %} -A type to represent booleans. There are only two possible values: True and False. Any value can be converted to a boolean using the [bool](../globals/all.html#bool) function. +A type to represent booleans. There are only two possible values: True and False. Any value can be converted to a boolean using the [bool](../globals/all.html#bool) function. \ No newline at end of file diff --git a/rules/lib/core/builtin_function_or_method.mdx b/rules/lib/core/builtin_function_or_method.mdx index bbb0cc6..f930792 100644 --- a/rules/lib/core/builtin_function_or_method.mdx +++ b/rules/lib/core/builtin_function_or_method.mdx @@ -2,8 +2,5 @@ title: 'builtin_function_or_method' --- -# builtin_function_or_method -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/BuiltinFunction.java" %} -{% include "\_buttons.html" %} -The type of a built-in function, defined by Java code. +The type of a built-in function, defined by Java code. \ No newline at end of file diff --git a/rules/lib/core/dict.mdx b/rules/lib/core/dict.mdx index e77c454..f514c82 100644 --- a/rules/lib/core/dict.mdx +++ b/rules/lib/core/dict.mdx @@ -2,58 +2,52 @@ title: 'dict' --- -# dict -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/Dict.java" %} -{% include "\_buttons.html" %} dict is a built-in type representing an associative mapping or *dictionary*. A dictionary supports indexing using `d[k]` and key membership testing using `k in d`; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to `d[k]` or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key. - d = {0: "x", 2: "z", 1: "y"} - [k for k in d] # [0, 2, 1] - d.pop(2) - d[0], d[2] = "a", "b" - 0 in d, "a" in d # (True, False) - [(k, v) for k, v in d.items()] # [(0, "a"), (1, "y"), (2, "b")] +``` +d = \{0: "x", 2: "z", 1: "y"\} +[k for k in d] # [0, 2, 1] +d.pop(2) +d[0], d[2] = "a", "b" +0 in d, "a" in d # (True, False) +[(k, v) for k, v in d.items()] # [(0, "a"), (1, "y"), (2, "b")] +``` There are four ways to construct a dictionary: -1. A dictionary expression `{k: v, ...}` yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value. - -2. A dictionary comprehension `{k: v for vars in seq}` yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value. - - ``` python +1. A dictionary expression `\{k: v, ...\}` yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value.- A dictionary comprehension `\{k: v for vars in seq\}` yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value. - {k: v for k, v in (("a", 0), ("b", 1), ("a", 2))} # {"a": 2, "b": 1} - {i: 2*i for i in range(3)} # {0: 0, 1: 2, 2: 4} - ``` + ``` + \{k: v for k, v in (("a", 0), ("b", 1), ("a", 2))\} # \{"a": 2, "b": 1\} + \{i: 2*i for i in range(3)\} # \{0: 0, 1: 2, 2: 4\} + ``` -3. A call to the built-in [dict](../globals/all.html#dict) function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted. + - A call to the built-in [dict](../globals/all.html#dict) function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted.- The union expression `x | y` yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key `k` in common, the right hand side dictionary's value of the key (in other words, `y[k]`) wins. The `|=` variant of the union operator modifies a dictionary in-place. Example: -4. The union expression `x | y` yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key `k` in common, the right hand side dictionary's value of the key (in other words, `y[k]`) wins. The `|=` variant of the union operator modifies a dictionary in-place. Example: - - ``` python - d = {"foo": "FOO", "bar": "BAR"} | {"foo": "FOO2", "baz": "BAZ"} - # d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"} - d = {"a": 1, "b": 2} - d |= {"b": 3, "c": 4} - # d == {"a": 1, "b": 3, "c": 4} - ``` + ``` + d = \{"foo": "FOO", "bar": "BAR"\} | \{"foo": "FOO2", "baz": "BAZ"\} + # d == \{"foo": "FOO2", "bar": "BAR", "baz": "BAZ"\} + d = \{"a": 1, "b": 2\} + d |= \{"b": 3, "c": 4\} + # d == \{"a": 1, "b": 3, "c": 4\} + ``` ## Members -- [clear](#clear) -- [get](#get) -- [items](#items) -- [keys](#keys) -- [pop](#pop) -- [popitem](#popitem) -- [setdefault](#setdefault) -- [update](#update) -- [values](#values) +* [clear](#clear) +* [get](#get) +* [items](#items) +* [keys](#keys) +* [pop](#pop) +* [popitem](#popitem) +* [setdefault](#setdefault) +* [update](#update) +* [values](#values) ## clear -``` rule-signature +``` None dict.clear() ``` @@ -61,7 +55,7 @@ Remove all items from the dictionary. ## get -``` rule-signature +``` unknown dict.get(key, default=None) ``` @@ -69,54 +63,38 @@ Returns the value for `key` if `key` is in the dictionary, else `default`. If `d ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="get.key"><code>key</code></td> -<td>required<br /> -The key to look for.</td> -</tr> -<tr> -<td id="get.default"><code>default</code></td> -<td>default is <code>None</code><br /> -The default value to use (instead of None) if the key is not found.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `key` | required | +| `default` | default is `None` The default value to use (instead of None) if the key is not found. | ## items -``` rule-signature +``` list dict.items() ``` Returns the list of key-value tuples: -``` python -{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")] +``` +\{2: "a", 4: "b", 1: "c"\}.items() == [(2, "a"), (4, "b"), (1, "c")] ``` ## keys -``` rule-signature +``` list dict.keys() ``` Returns the list of keys: -``` python -{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1] +``` +\{2: "a", 4: "b", 1: "c"\}.keys() == [2, 4, 1] ``` ## pop -``` rule-signature +``` unknown dict.pop(key, default=unbound) ``` @@ -124,30 +102,14 @@ Removes a `key` from the dict, and returns the associated value. If no entry wit ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="pop.key"><code>key</code></td> -<td>required<br /> -The key.</td> -</tr> -<tr> -<td id="pop.default"><code>default</code></td> -<td>default is <code>unbound</code><br /> -a default value if the key is absent.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `key` | required The key. | +| `default` | default is `unbound` a default value if the key is absent. | ## popitem -``` rule-signature +``` tuple dict.popitem() ``` @@ -155,7 +117,7 @@ Remove and return the first `(key, value)` pair from the dictionary. `popitem` i ## setdefault -``` rule-signature +``` unknown dict.setdefault(key, default=None) ``` @@ -163,30 +125,14 @@ If `key` is in the dictionary, return its value. If not, insert key with a value ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="setdefault.key"><code>key</code></td> -<td>required<br /> -The key.</td> -</tr> -<tr> -<td id="setdefault.default"><code>default</code></td> -<td>default is <code>None</code><br /> -a default value if the key is absent.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `key` | required The key. | +| `default` | default is `None` a default value if the key is absent. | ## update -``` rule-signature +``` None dict.update(pairs=[], **kwargs) ``` @@ -197,35 +143,19 @@ Each keyword argument `name=value` causes the name/value pair to be inserted int ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="update.pairs"><code>pairs</code></td> -<td>default is <code>[]</code><br /> -Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value.</td> -</tr> -<tr> -<td id="update.kwargs"><code>kwargs</code></td> -<td>required<br /> -Dictionary of additional entries.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `pairs` | default is `[]` Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value. | +| `kwargs` | required Dictionary of additional entries. | ## values -``` rule-signature +``` list dict.values() ``` Returns the list of values: -``` python -{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"] ``` +\{2: "a", 4: "b", 1: "c"\}.values() == ["a", "b", "c"] +``` \ No newline at end of file diff --git a/rules/lib/core/float.mdx b/rules/lib/core/float.mdx index 988c842..e307157 100644 --- a/rules/lib/core/float.mdx +++ b/rules/lib/core/float.mdx @@ -2,8 +2,5 @@ title: 'float' --- -# float -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkFloat.java" %} -{% include "\_buttons.html" %} -The type of floating-point numbers in Starlark. +The type of floating-point numbers in Starlark. \ No newline at end of file diff --git a/rules/lib/core/function.mdx b/rules/lib/core/function.mdx index 1bc566e..5775b15 100644 --- a/rules/lib/core/function.mdx +++ b/rules/lib/core/function.mdx @@ -2,8 +2,5 @@ title: 'function' --- -# function -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkFunction.java" %} -{% include "\_buttons.html" %} -The type of functions declared in Starlark. +The type of functions declared in Starlark. \ No newline at end of file diff --git a/rules/lib/core/int.mdx b/rules/lib/core/int.mdx index 59e9b50..294e908 100644 --- a/rules/lib/core/int.mdx +++ b/rules/lib/core/int.mdx @@ -2,13 +2,10 @@ title: 'int' --- -# int -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkInt.java" %} -{% include "\_buttons.html" %} The type of integers in Starlark. Starlark integers may be of any magnitude; arithmetic is exact. Examples of integer expressions: -``` python +``` 153 0x2A # hexadecimal literal 0o54 # octal literal @@ -16,4 +13,4 @@ The type of integers in Starlark. Starlark integers may be of any magnitude; ari 100 / -7 100 % -7 # -5 (unlike in some other languages) int("18") -``` +``` \ No newline at end of file diff --git a/rules/lib/core/json.mdx b/rules/lib/core/json.mdx index 1fdcc7c..1b3c2e0 100644 --- a/rules/lib/core/json.mdx +++ b/rules/lib/core/json.mdx @@ -2,138 +2,75 @@ title: 'json' --- -# json -{% dynamic setvar source_file "src/main/java/net/starlark/java/lib/json/Json.java" %} -{% include "\_buttons.html" %} Module json is a Starlark module of JSON-related functions. ## Members -- [decode](#decode) -- [encode](#encode) -- [encode_indent](#encode_indent) -- [indent](#indent) +* [decode](#decode) +* [encode](#encode) +* [encode\_indent](#encode_indent) +* [indent](#indent) ## decode -``` rule-signature +``` unknown json.decode(x, default=unbound) ``` The decode function has one required positional parameter: a JSON string. It returns the Starlark value that the string denotes. -- `"null"`, `"true"` and `"false"` are parsed as `None`, `True`, and `False`. -- Numbers are parsed as int, or as a float if they contain a decimal point or an exponent. Although JSON has no syntax for non-finite values, very large values may be decoded as infinity. -- a JSON object is parsed as a new unfrozen Starlark dict. If the same key string occurs more than once in the object, the last value for the key is kept. -- a JSON array is parsed as new unfrozen Starlark list. +* `"null"`, `"true"` and `"false"` are parsed as `None`, `True`, and `False`.* Numbers are parsed as int, or as a float if they contain a decimal point or an exponent. Although JSON has no syntax for non-finite values, very large values may be decoded as infinity.* a JSON object is parsed as a new unfrozen Starlark dict. If the same key string occurs more than once in the object, the last value for the key is kept.* a JSON array is parsed as new unfrozen Starlark list. If `x` is not a valid JSON encoding and the optional `default` parameter is specified (including specified as `None`), this function returns the `default` value. If `x` is not a valid JSON encoding and the optional `default` parameter is *not* specified, this function fails. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="decode.x"><code>x</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -JSON string to decode.</td> -</tr> -<tr> -<td id="decode.default"><code>default</code></td> -<td>default is <code>unbound</code><br /> -If specified, the value to return when <code>x</code> cannot be decoded.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | [string](../core/string.mdx); required JSON string to decode. | +| `default` | default is `unbound` If specified, the value to return when `x` cannot be decoded. | ## encode -``` rule-signature +``` string json.encode(x) ``` The encode function accepts one required positional argument, which it converts to JSON by cases: -- None, True, and False are converted to 'null', 'true', and 'false', respectively. -- An int, no matter how large, is encoded as a decimal integer. Some decoders may not be able to decode very large integers. -- A float is encoded using a decimal point or an exponent or both, even if its numeric value is an integer. It is an error to encode a non-finite floating-point value. -- A string value is encoded as a JSON string literal that denotes the value. Each unpaired surrogate is replaced by U+FFFD. -- A dict is encoded as a JSON object, in lexicographical key order. It is an error if any key is not a string. -- A list or tuple is encoded as a JSON array. -- A struct-like value is encoded as a JSON object, in field name order. +* None, True, and False are converted to 'null', 'true', and 'false', respectively.* An int, no matter how large, is encoded as a decimal integer. Some decoders may not be able to decode very large integers.* A float is encoded using a decimal point or an exponent or both, even if its numeric value is an integer. It is an error to encode a non-finite floating-point value.* A string value is encoded as a JSON string literal that denotes the value. Each unpaired surrogate is replaced by U+FFFD.* A dict is encoded as a JSON object, in lexicographical key order. It is an error if any key is not a string.* A list or tuple is encoded as a JSON array.* A struct-like value is encoded as a JSON object, in field name order. An application-defined type may define its own JSON encoding. Encoding any other value yields an error. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="encode.x"><code>x</code></td> -<td>required<br /> -</td> -</tr> -</tbody> -</table> - -## encode_indent - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `x` | required | + +## encode\_indent + +``` string json.encode_indent(x, *, prefix='', indent='\t') ``` -The encode_indent function is equivalent to `json.indent(json.encode(x), ...)`. See `indent` for description of formatting parameters. +The encode\_indent function is equivalent to `json.indent(json.encode(x), ...)`. See `indent` for description of formatting parameters. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="encode_indent.x"><code>x</code></td> -<td>required<br /> -</td> -</tr> -<tr> -<td id="encode_indent.prefix"><code>prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -</td> -</tr> -<tr> -<td id="encode_indent.indent"><code>indent</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'\t'</code><br /> -</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required | +| `prefix` | [string](../core/string.mdx); default is `''` | +| `indent` | [string](../core/string.mdx); default is `'\t'` | ## indent -``` rule-signature +``` string json.indent(s, *, prefix='', indent='\t') ``` @@ -146,31 +83,8 @@ If the input is not valid, the function may fail or return invalid output. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="indent.s"><code>s</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -</td> -</tr> -<tr> -<td id="indent.prefix"><code>prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -</td> -</tr> -<tr> -<td id="indent.indent"><code>indent</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'\t'</code><br /> -</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `s` | [string](../core/string.mdx); required | +| `prefix` | [string](../core/string.mdx); default is `''` | +| `indent` | [string](../core/string.mdx); default is `'\t'` | \ No newline at end of file diff --git a/rules/lib/core/list.mdx b/rules/lib/core/list.mdx index 593144f..9c0263b 100644 --- a/rules/lib/core/list.mdx +++ b/rules/lib/core/list.mdx @@ -2,25 +2,22 @@ title: 'list' --- -# list -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkList.java" %} -{% include "\_buttons.html" %} The built-in list type. Example list expressions: -``` python +``` x = [1, 2, 3] ``` Accessing elements is possible using indexing (starts from `0`): -``` python +``` e = x[1] # e == 2 ``` Lists support the `+` operator to concatenate two lists. Example: -``` python +``` x = [1, 2] + [3, 4] # x == [1, 2, 3, 4] x = ["a", "b"] x += ["c"] # x == ["a", "b", "c"] @@ -28,7 +25,7 @@ x += ["c"] # x == ["a", "b", "c"] Similar to strings, lists support slice operations: -``` python +``` ['a', 'b', 'c', 'd'][1:3] # ['b', 'c'] ['a', 'b', 'c', 'd'][::2] # ['a', 'c'] ['a', 'b', 'c', 'd'][3:0:-1] # ['d', 'c', 'b'] @@ -38,17 +35,17 @@ Lists are mutable, as in Python. ## Members -- [append](#append) -- [clear](#clear) -- [extend](#extend) -- [index](#index) -- [insert](#insert) -- [pop](#pop) -- [remove](#remove) +* [append](#append) +* [clear](#clear) +* [extend](#extend) +* [index](#index) +* [insert](#insert) +* [pop](#pop) +* [remove](#remove) ## append -``` rule-signature +``` None list.append(item) ``` @@ -56,25 +53,13 @@ Adds an item to the end of the list. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="append.item"><code>item</code></td> -<td>required<br /> -Item to add at the end.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `item` | required | ## clear -``` rule-signature +``` None list.clear() ``` @@ -82,7 +67,7 @@ Removes all the elements of the list. ## extend -``` rule-signature +``` None list.extend(items) ``` @@ -90,26 +75,13 @@ Adds all items to the end of the list. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="extend.items"><code>items</code></td> -<td>iterable; -required<br /> -Items to add at the end.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `items` | iterable; required | ## index -``` rule-signature +``` int list.index(x, start=unbound, end=unbound) ``` @@ -117,37 +89,15 @@ Returns the index in the list of the first item whose value is x. It is an error ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="index.x"><code>x</code></td> -<td>required<br /> -The object to search.</td> -</tr> -<tr> -<td id="index.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>unbound</code><br /> -The start index of the list portion to inspect.</td> -</tr> -<tr> -<td id="index.end"><code>end</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>unbound</code><br /> -The end index of the list portion to inspect.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required | +| `start` | [int](../core/int.mdx); default is `unbound` The start index of the list portion to inspect. | +| `end` | [int](../core/int.mdx); default is `unbound` The end index of the list portion to inspect. | ## insert -``` rule-signature +``` None list.insert(index, item) ``` @@ -155,31 +105,14 @@ Inserts an item at a given position. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="insert.index"><code>index</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -required<br /> -The index of the given position.</td> -</tr> -<tr> -<td id="insert.item"><code>item</code></td> -<td>required<br /> -The item.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `index` | [int](../core/int.mdx); required The index of the given position. | +| `item` | required The item. | ## pop -``` rule-signature +``` unknown list.pop(i=-1) ``` @@ -187,26 +120,13 @@ Removes the item at the given position in the list, and returns it. If no `index ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="pop.i"><code>i</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>-1</code><br /> -The index of the item.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `i` | [int](../core/int.mdx); default is `-1` The index of the item. | ## remove -``` rule-signature +``` None list.remove(x) ``` @@ -214,18 +134,6 @@ Removes the first item from the list whose value is x. It is an error if there i ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="remove.x"><code>x</code></td> -<td>required<br /> -The object to remove.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required The object to remove. | \ No newline at end of file diff --git a/rules/lib/core/range.mdx b/rules/lib/core/range.mdx index 277a4f8..bbcff5a 100644 --- a/rules/lib/core/range.mdx +++ b/rules/lib/core/range.mdx @@ -2,28 +2,25 @@ title: 'range' --- -# range -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/RangeList.java" %} -{% include "\_buttons.html" %} A language built-in type to support ranges. Example of range literal: -``` python +``` x = range(1, 10, 3) ``` Accessing elements is possible using indexing (starts from `0`): -``` python +``` e = x[1] # e == 2 ``` Ranges do not support the `+` operator for concatenation.Similar to strings, ranges support slice operations: -``` python +``` range(10)[1:3] # range(1, 3) range(10)[::2] # range(0, 10, 2) range(10)[3:0:-1] # range(3, 0, -1) ``` -Ranges are immutable, as in Python 3. +Ranges are immutable, as in Python 3. \ No newline at end of file diff --git a/rules/lib/core/set.mdx b/rules/lib/core/set.mdx index 90b416d..337a7cb 100644 --- a/rules/lib/core/set.mdx +++ b/rules/lib/core/set.mdx @@ -2,10 +2,7 @@ title: 'set' --- -# set -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkSet.java" %} -{% include "\_buttons.html" %} The built-in set type. A set is a mutable collection of unique values – the set's *elements*. The [type name](../globals/all#type) of a set is `"set"`. @@ -22,8 +19,7 @@ have no literal syntax. The `in` and `not in` operations check whether a value is (or is not) in a set: -``` python - +``` s = set(["a", "b", "c"]) "a" in s # True "z" in s # False @@ -34,8 +30,7 @@ comprehension, and the various built-in functions that operate on iterables. Its retrieved using the [`len()`](../globals/all#len) built-in function, and the order of iteration is the order in which elements were first added to the set: -``` python - +``` s = set(["z", "y", "z", "y"]) len(s) # prints 2 s.add("x") @@ -46,8 +41,7 @@ for e in s: A set used in Boolean context is true if and only if it is non-empty. -``` python - +``` s = set() "non-empty" if s else "empty" # "empty" t = set(["x", "y"]) @@ -58,11 +52,10 @@ Sets may be compared for equality or inequality using `==` and `!=`. A set `s` is equal to `t` if and only if `t` is a set containing the same elements; iteration order is not significant. In particular, a set is *not* equal to the list of its elements. Sets are not ordered with respect to other sets, and an attempt to compare two sets -using `<`, `<=`, `>`, `>=`, or to sort a +using `<`, `<=`, `>`, `>=`, or to sort a sequence of sets, will fail. -``` python - +``` set() == set() # True set() != [] # True set([1, 2]) == set([2, 1]) # True @@ -72,16 +65,14 @@ set([1, 2]) != [1, 2] # True The `|` operation on two sets returns the union of the two sets: a set containing the elements found in either one or both of the original sets. -``` python - +``` set([1, 2]) | set([3, 2]) # set([1, 2, 3]) ``` The `&` operation on two sets returns the intersection of the two sets: a set containing only the elements found in both of the original sets. -``` python - +``` set([1, 2]) & set([2, 3]) # set([2]) set([1, 2]) & set([3, 4]) # set() ``` @@ -89,8 +80,7 @@ set([1, 2]) & set([3, 4]) # set() The `-` operation on two sets returns the difference of the two sets: a set containing the elements found in the left-hand side set but not the right-hand side set. -``` python - +``` set([1, 2]) - set([2, 3]) # set([1]) set([1, 2]) - set([3, 4]) # set([1, 2]) ``` @@ -98,8 +88,7 @@ set([1, 2]) - set([3, 4]) # set([1, 2]) The `^` operation on two sets returns the symmetric difference of the two sets: a set containing the elements found in exactly one of the two original sets, but not in both. -``` python - +``` set([1, 2]) ^ set([2, 3]) # set([1, 3]) set([1, 2]) ^ set([3, 4]) # set([1, 2, 3, 4]) ``` @@ -111,8 +100,7 @@ element that was only present in the right-hand side. The corresponding augmented assignments, `|=`, `&=`, `-=`, and `^=`, modify the left-hand set in place. -``` python - +``` s = set([1, 2]) s |= set([2, 3, 4]) # s now equals set([1, 2, 3, 4]) s &= set([0, 1, 2, 3]) # s now equals set([1, 2, 3]) @@ -125,26 +113,26 @@ operations that attempt to update it will fail. ## Members -- [add](#add) -- [clear](#clear) -- [difference](#difference) -- [difference_update](#difference_update) -- [discard](#discard) -- [intersection](#intersection) -- [intersection_update](#intersection_update) -- [isdisjoint](#isdisjoint) -- [issubset](#issubset) -- [issuperset](#issuperset) -- [pop](#pop) -- [remove](#remove) -- [symmetric_difference](#symmetric_difference) -- [symmetric_difference_update](#symmetric_difference_update) -- [union](#union) -- [update](#update) +* [add](#add) +* [clear](#clear) +* [difference](#difference) +* [difference\_update](#difference_update) +* [discard](#discard) +* [intersection](#intersection) +* [intersection\_update](#intersection_update) +* [isdisjoint](#isdisjoint) +* [issubset](#issubset) +* [issuperset](#issuperset) +* [pop](#pop) +* [remove](#remove) +* [symmetric\_difference](#symmetric_difference) +* [symmetric\_difference\_update](#symmetric_difference_update) +* [union](#union) +* [update](#update) ## add -``` rule-signature +``` None set.add(element) ``` @@ -158,25 +146,13 @@ the `|=` augmented assignment operation. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="add.element"><code>element</code></td> -<td>required<br /> -Element to add.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `element` | required Element to add. | ## clear -``` rule-signature +``` None set.clear() ``` @@ -184,7 +160,7 @@ Removes all the elements of the set. ## difference -``` rule-signature +``` set set.difference(*others) ``` @@ -199,33 +175,20 @@ the set. For example, -``` python - +``` set([1, 2, 3]).difference([2]) # set([1, 3]) set([1, 2, 3]).difference([0, 1], [3, 4]) # set([2]) ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="difference.others"><code>others</code></td> -<td>required<br /> -Collections of hashable elements.</td> -</tr> -</tbody> -</table> - -## difference_update - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `others` | required Collections of hashable elements. | + +## difference\_update + +``` None set.difference_update(*others) ``` @@ -240,8 +203,7 @@ set unchanged. For example, -``` python - +``` s = set([1, 2, 3, 4]) s.difference_update([2]) # None; s is set([1, 3, 4]) s.difference_update([0, 1], [4, 5]) # None; s is set([3]) @@ -249,25 +211,13 @@ s.difference_update([0, 1], [4, 5]) # None; s is set([3]) ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="difference_update.others"><code>others</code></td> -<td>required<br /> -Collections of hashable elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `others` | required Collections of hashable elements. | ## discard -``` rule-signature +``` None set.discard(element) ``` @@ -281,8 +231,7 @@ augmented assignment operation. For example, -``` python - +``` s = set(["x", "y"]) s.discard("y") # None; s == set(["x"]) s.discard("y") # None; s == set(["x"]) @@ -290,25 +239,13 @@ s.discard("y") # None; s == set(["x"]) ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="discard.element"><code>element</code></td> -<td>required<br /> -Element to discard. Must be hashable.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `element` | required Element to discard. Must be hashable. | ## intersection -``` rule-signature +``` set set.intersection(*others) ``` @@ -323,33 +260,20 @@ the set. For example, -``` python - +``` set([1, 2]).intersection([2, 3]) # set([2]) set([1, 2, 3]).intersection([0, 1], [1, 2]) # set([1]) ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="intersection.others"><code>others</code></td> -<td>required<br /> -Collections of hashable elements.</td> -</tr> -</tbody> -</table> - -## intersection_update - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `others` | required Collections of hashable elements. | + +## intersection\_update + +``` None set.intersection_update(*others) ``` @@ -365,8 +289,7 @@ set unchanged. For example, -``` python - +``` s = set([1, 2, 3, 4]) s.intersection_update([0, 1, 2]) # None; s is set([1, 2]) s.intersection_update([0, 1], [1, 2]) # None; s is set([1]) @@ -374,25 +297,13 @@ s.intersection_update([0, 1], [1, 2]) # None; s is set([1]) ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="intersection_update.others"><code>others</code></td> -<td>required<br /> -Collections of hashable elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `others` | required Collections of hashable elements. | ## isdisjoint -``` rule-signature +``` bool set.isdisjoint(other) ``` @@ -400,8 +311,7 @@ Returns true if this set has no elements in common with another. For example, -``` python - +``` set([1, 2]).isdisjoint([3, 4]) # True set().isdisjoint(set()) # True set([1, 2]).isdisjoint([2, 3]) # False @@ -409,25 +319,13 @@ set([1, 2]).isdisjoint([2, 3]) # False ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="isdisjoint.other"><code>other</code></td> -<td>required<br /> -A collection of hashable elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `other` | required A collection of hashable elements. | ## issubset -``` rule-signature +``` bool set.issubset(other) ``` @@ -437,8 +335,7 @@ Note that a set is always considered to be a subset of itself. For example, -``` python - +``` set([1, 2]).issubset([1, 2, 3]) # True set([1, 2]).issubset([1, 2]) # True set([1, 2]).issubset([2, 3]) # False @@ -446,25 +343,13 @@ set([1, 2]).issubset([2, 3]) # False ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="issubset.other"><code>other</code></td> -<td>required<br /> -A collection of hashable elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `other` | required A collection of hashable elements. | ## issuperset -``` rule-signature +``` bool set.issuperset(other) ``` @@ -474,8 +359,7 @@ Note that a set is always considered to be a superset of itself. For example, -``` python - +``` set([1, 2, 3]).issuperset([1, 2]) # True set([1, 2, 3]).issuperset([1, 2, 3]) # True set([1, 2, 3]).issuperset([2, 3, 4]) # False @@ -483,25 +367,13 @@ set([1, 2, 3]).issuperset([2, 3, 4]) # False ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="issuperset.other"><code>other</code></td> -<td>required<br /> -A collection of hashable elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `other` | required A collection of hashable elements. | ## pop -``` rule-signature +``` unknown set.pop() ``` @@ -512,8 +384,7 @@ Fails if the set is empty. For example, -``` python - +``` s = set([3, 1, 2]) s.pop() # 3; s == set([1, 2]) s.pop() # 1; s == set([2]) @@ -523,7 +394,7 @@ s.pop() # error: empty set ## remove -``` rule-signature +``` None set.remove(element) ``` @@ -537,25 +408,13 @@ assignment operation. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="remove.element"><code>element</code></td> -<td>required<br /> -Element to remove. Must be an element of the set (and hashable).</td> -</tr> -</tbody> -</table> - -## symmetric_difference - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `element` | required Element to remove. Must be an element of the set (and hashable). | + +## symmetric\_difference + +``` set set.symmetric_difference(other) ``` @@ -569,32 +428,19 @@ dict. For example, -``` python - +``` set([1, 2]).symmetric_difference([2, 3]) # set([1, 3]) ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="symmetric_difference.other"><code>other</code></td> -<td>required<br /> -A collection of hashable elements.</td> -</tr> -</tbody> -</table> - -## symmetric_difference_update - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `other` | required A collection of hashable elements. | + +## symmetric\_difference\_update + +``` None set.symmetric_difference_update(other) ``` @@ -602,39 +448,26 @@ Returns a new mutable set containing the symmetric difference of this set with a hashable elements. If `s` and `t` are sets, `s.symmetric_difference_update(t)` is -equivalent to \`s ^= t`; however, note that the `^=\` augmented assignment requires both +equivalent to `s ^= t`; however, note that the` ^=` augmented assignment requires both sides to be sets, while the `symmetric_difference_update` method also accepts a sequence or a dict. For example, -``` python - +``` s = set([1, 2]) s.symmetric_difference_update([2, 3]) # None; s == set([1, 3]) ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="symmetric_difference_update.other"><code>other</code></td> -<td>required<br /> -A collection of hashable elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `other` | required A collection of hashable elements. | ## union -``` rule-signature +``` set set.union(*others) ``` @@ -649,33 +482,20 @@ set. For example, -``` python - +``` set([1, 2]).union([2, 3]) # set([1, 2, 3]) -set([1, 2]).union([2, 3], {3: "a", 4: "b"}) # set([1, 2, 3, 4]) +set([1, 2]).union([2, 3], \{3: "a", 4: "b"\}) # set([1, 2, 3, 4]) ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="union.others"><code>others</code></td> -<td>required<br /> -Collections of hashable elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `others` | required Collections of hashable elements. | ## update -``` rule-signature +``` None set.update(*others) ``` @@ -683,8 +503,7 @@ Adds the elements found in others to this set. For example, -``` python - +``` s = set() s.update([1, 2]) # None; s is set([1, 2]) s.update([2, 3], [3, 4]) # None; s is set([1, 2, 3, 4]) @@ -699,18 +518,6 @@ unchanged. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="update.others"><code>others</code></td> -<td>required<br /> -Collections of hashable elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `others` | required Collections of hashable elements. | \ No newline at end of file diff --git a/rules/lib/core/string.mdx b/rules/lib/core/string.mdx index c3c298c..90ddd78 100644 --- a/rules/lib/core/string.mdx +++ b/rules/lib/core/string.mdx @@ -2,13 +2,10 @@ title: 'string' --- -# string -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StringModule.java" %} -{% include "\_buttons.html" %} A language built-in type to support strings. Examples of string literals: -``` python +``` a = 'abc\ndef' b = "ab'cd" c = """multiline string""" @@ -24,7 +21,7 @@ t = "hello"[3:0:-1] # "lle" Strings are not directly iterable, use the `.elems()` method to iterate over their characters. Examples: -``` python +``` "bc" in "abcd" # evaluates to True x = [c for c in "abc".elems()] # x == ["a", "b", "c"] ``` @@ -33,42 +30,42 @@ Implicit concatenation of strings is not allowed; use the `+` operator instead. ## Members -- [capitalize](#capitalize) -- [count](#count) -- [elems](#elems) -- [endswith](#endswith) -- [find](#find) -- [format](#format) -- [index](#index) -- [isalnum](#isalnum) -- [isalpha](#isalpha) -- [isdigit](#isdigit) -- [islower](#islower) -- [isspace](#isspace) -- [istitle](#istitle) -- [isupper](#isupper) -- [join](#join) -- [lower](#lower) -- [lstrip](#lstrip) -- [partition](#partition) -- [removeprefix](#removeprefix) -- [removesuffix](#removesuffix) -- [replace](#replace) -- [rfind](#rfind) -- [rindex](#rindex) -- [rpartition](#rpartition) -- [rsplit](#rsplit) -- [rstrip](#rstrip) -- [split](#split) -- [splitlines](#splitlines) -- [startswith](#startswith) -- [strip](#strip) -- [title](#title) -- [upper](#upper) +* [capitalize](#capitalize) +* [count](#count) +* [elems](#elems) +* [endswith](#endswith) +* [find](#find) +* [format](#format) +* [index](#index) +* [isalnum](#isalnum) +* [isalpha](#isalpha) +* [isdigit](#isdigit) +* [islower](#islower) +* [isspace](#isspace) +* [istitle](#istitle) +* [isupper](#isupper) +* [join](#join) +* [lower](#lower) +* [lstrip](#lstrip) +* [partition](#partition) +* [removeprefix](#removeprefix) +* [removesuffix](#removesuffix) +* [replace](#replace) +* [rfind](#rfind) +* [rindex](#rindex) +* [rpartition](#rpartition) +* [rsplit](#rsplit) +* [rstrip](#rstrip) +* [split](#split) +* [splitlines](#splitlines) +* [startswith](#startswith) +* [strip](#strip) +* [title](#title) +* [upper](#upper) ## capitalize -``` rule-signature +``` string string.capitalize() ``` @@ -76,7 +73,7 @@ Returns a copy of the string with its first character (if any) capitalized and t ## count -``` rule-signature +``` int string.count(sub, start=0, end=None) ``` @@ -84,38 +81,15 @@ Returns the number of (non-overlapping) occurrences of substring `sub` in string ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="count.sub"><code>sub</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The substring to count.</td> -</tr> -<tr> -<td id="count.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>0</code><br /> -Restrict to search from this position.</td> -</tr> -<tr> -<td id="count.end"><code>end</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>None</code><br /> -optional position before which to restrict to search.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sub` | [string](../core/string.mdx); required | +| `start` | [int](../core/int.mdx); or `None`; default is `0` | +| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | ## elems -``` rule-signature +``` sequence string.elems() ``` @@ -123,7 +97,7 @@ Returns an iterable value containing successive 1-element substrings of the stri ## endswith -``` rule-signature +``` bool string.endswith(sub, start=0, end=None) ``` @@ -131,38 +105,15 @@ Returns True if the string ends with `sub`, otherwise False, optionally restrict ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="endswith.sub"><code>sub</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/tuple.html" class="anchor">tuple</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The suffix (or tuple of alternative suffixes) to match.</td> -</tr> -<tr> -<td id="endswith.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>0</code><br /> -Test beginning at this position.</td> -</tr> -<tr> -<td id="endswith.end"><code>end</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>None</code><br /> -optional position at which to stop comparing.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sub` | [string](../core/string.mdx); or [tuple](../core/tuple.mdx) of [string](../core/string.mdx)s; required The suffix (or tuple of alternative suffixes) to match. | +| `start` | [int](../core/int.mdx); or `None`; default is `0` Test beginning at this position. | +| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position at which to stop comparing. | ## find -``` rule-signature +``` int string.find(sub, start=0, end=None) ``` @@ -170,78 +121,39 @@ Returns the first index where `sub` is found, or -1 if no such index exists, opt ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="find.sub"><code>sub</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The substring to find.</td> -</tr> -<tr> -<td id="find.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>0</code><br /> -Restrict to search from this position.</td> -</tr> -<tr> -<td id="find.end"><code>end</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>None</code><br /> -optional position before which to restrict to search.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sub` | [string](../core/string.mdx); required The substring to find. | +| `start` | [int](../core/int.mdx); or `None`; default is `0` Restrict to search from this position. | +| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | ## format -``` rule-signature +``` string string.format(*args, **kwargs) ``` -Perform string interpolation. Format strings contain replacement fields surrounded by curly braces `{}`. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output.If you need to include a brace character in the literal text, it can be escaped by doubling: `{{` and `}}`A replacement field can be either a name, a number, or empty. Values are converted to strings using the [str](../globals/all.html#str) function. +Perform string interpolation. Format strings contain replacement fields surrounded by curly braces `\{\}`. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output.If you need to include a brace character in the literal text, it can be escaped by doubling: ``A replacement field can be either a name, a number, or empty. Values are converted to strings using the [str](../globals/all.html#str) function. -``` python +``` # Access in order: -"{} < {}".format(4, 5) == "4 < 5" +"\{\} < \{\}".format(4, 5) == "4 < 5" # Access by position: -"{1}, {0}".format(2, 1) == "1, 2" +"\{1\}, \{0\}".format(2, 1) == "1, 2" # Access by name: -"x{key}x".format(key = 2) == "x2x" +"x\{key\}x".format(key = 2) == "x2x" ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="format.args"><code>args</code></td> -<td>default is <code>()</code><br /> -List of arguments.</td> -</tr> -<tr> -<td id="format.kwargs"><code>kwargs</code></td> -<td>default is <code>{}</code><br /> -Dictionary of arguments.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `args` | default is `()` List of arguments. | +| `kwargs` | default is `\{\}` Dictionary of arguments. | ## index -``` rule-signature +``` int string.index(sub, start=0, end=None) ``` @@ -249,62 +161,39 @@ Returns the first index where `sub` is found, or raises an error if no such inde ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="index.sub"><code>sub</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The substring to find.</td> -</tr> -<tr> -<td id="index.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>0</code><br /> -Restrict to search from this position.</td> -</tr> -<tr> -<td id="index.end"><code>end</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>None</code><br /> -optional position before which to restrict to search.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sub` | [string](../core/string.mdx); required The substring to find. | +| `start` | [int](../core/int.mdx); or `None`; default is `0` Restrict to search from this position. | +| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | ## isalnum -``` rule-signature +``` bool string.isalnum() ``` -Returns True if all characters in the string are alphanumeric (\[a-zA-Z0-9\]) and there is at least one character. +Returns True if all characters in the string are alphanumeric ([a-zA-Z0-9]) and there is at least one character. ## isalpha -``` rule-signature +``` bool string.isalpha() ``` -Returns True if all characters in the string are alphabetic (\[a-zA-Z\]) and there is at least one character. +Returns True if all characters in the string are alphabetic ([a-zA-Z]) and there is at least one character. ## isdigit -``` rule-signature +``` bool string.isdigit() ``` -Returns True if all characters in the string are digits (\[0-9\]) and there is at least one character. +Returns True if all characters in the string are digits ([0-9]) and there is at least one character. ## islower -``` rule-signature +``` bool string.islower() ``` @@ -312,7 +201,7 @@ Returns True if all cased characters in the string are lowercase and there is at ## isspace -``` rule-signature +``` bool string.isspace() ``` @@ -320,7 +209,7 @@ Returns True if all characters are white space characters and the string contain ## istitle -``` rule-signature +``` bool string.istitle() ``` @@ -328,7 +217,7 @@ Returns True if the string is in title case and it contains at least one charact ## isupper -``` rule-signature +``` bool string.isupper() ``` @@ -336,38 +225,25 @@ Returns True if all cased characters in the string are uppercase and there is at ## join -``` rule-signature +``` string string.join(elements) ``` Returns a string in which the string elements of the argument have been joined by this string as a separator. Example: -``` python +``` "|".join(["a", "b", "c"]) == "a|b|c" ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="join.elements"><code>elements</code></td> -<td>iterable of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The objects to join.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `elements` | iterable of [string](../core/string.mdx)s; required | ## lower -``` rule-signature +``` string string.lower() ``` @@ -375,38 +251,25 @@ Returns the lower case version of this string. ## lstrip -``` rule-signature +``` string string.lstrip(chars=None) ``` Returns a copy of the string where leading characters that appear in `chars` are removed. Note that `chars` is not a prefix: all combinations of its value are removed: -``` python +``` "abcba".lstrip("ba") == "cba" ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="lstrip.chars"><code>chars</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The characters to remove, or all whitespace if None.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `chars` | [string](../core/string.mdx); or `None`; default is `None` The characters to remove, or all whitespace if None. | ## partition -``` rule-signature +``` tuple string.partition(sep) ``` @@ -414,26 +277,13 @@ Splits the input string at the first occurrence of the separator `sep` and retur ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="partition.sep"><code>sep</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The string to split on.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sep` | [string](../core/string.mdx); required The string to split on. | ## removeprefix -``` rule-signature +``` string string.removeprefix(prefix) ``` @@ -441,26 +291,13 @@ If the string starts with `prefix`, returns a new string with the prefix removed ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="removeprefix.prefix"><code>prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The prefix to remove if present.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `prefix` | [string](../core/string.mdx); required The prefix to remove if present. | ## removesuffix -``` rule-signature +``` string string.removesuffix(suffix) ``` @@ -468,26 +305,13 @@ If the string ends with `suffix`, returns a new string with the suffix removed. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="removesuffix.suffix"><code>suffix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The suffix to remove if present.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `suffix` | [string](../core/string.mdx); required The suffix to remove if present. | ## replace -``` rule-signature +``` string string.replace(old, new, count=-1) ``` @@ -495,38 +319,15 @@ Returns a copy of the string in which the occurrences of `old` have been replace ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="replace.old"><code>old</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The string to be replaced.</td> -</tr> -<tr> -<td id="replace.new"><code>new</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The string to replace with.</td> -</tr> -<tr> -<td id="replace.count"><code>count</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>-1</code><br /> -The maximum number of replacements. If omitted, or if the value is negative, there is no limit.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `old` | [string](../core/string.mdx); required The string to be replaced. | +| `new` | [string](../core/string.mdx); required The string to replace with. | +| `count` | [int](../core/int.mdx); default is `-1` The maximum number of replacements. If omitted, or if the value is negative, there is no limit. | ## rfind -``` rule-signature +``` int string.rfind(sub, start=0, end=None) ``` @@ -534,38 +335,15 @@ Returns the last index where `sub` is found, or -1 if no such index exists, opti ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="rfind.sub"><code>sub</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The substring to find.</td> -</tr> -<tr> -<td id="rfind.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>0</code><br /> -Restrict to search from this position.</td> -</tr> -<tr> -<td id="rfind.end"><code>end</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>None</code><br /> -optional position before which to restrict to search.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sub` | [string](../core/string.mdx); required The substring to find. | +| `start` | [int](../core/int.mdx); or `None`; default is `0` Restrict to search from this position. | +| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | ## rindex -``` rule-signature +``` int string.rindex(sub, start=0, end=None) ``` @@ -573,38 +351,15 @@ Returns the last index where `sub` is found, or raises an error if no such index ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="rindex.sub"><code>sub</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The substring to find.</td> -</tr> -<tr> -<td id="rindex.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>0</code><br /> -Restrict to search from this position.</td> -</tr> -<tr> -<td id="rindex.end"><code>end</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>None</code><br /> -optional position before which to restrict to search.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sub` | [string](../core/string.mdx); required The substring to find. | +| `start` | [int](../core/int.mdx); or `None`; default is `0` Restrict to search from this position. | +| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | ## rpartition -``` rule-signature +``` tuple string.rpartition(sep) ``` @@ -612,26 +367,13 @@ Splits the input string at the last occurrence of the separator `sep` and return ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="rpartition.sep"><code>sep</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The string to split on.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sep` | [string](../core/string.mdx); required The string to split on. | ## rsplit -``` rule-signature +``` list string.rsplit(sep, maxsplit=unbound) ``` @@ -639,63 +381,32 @@ Returns a list of all the words in the string, using `sep` as the separator, opt ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="rsplit.sep"><code>sep</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The string to split on.</td> -</tr> -<tr> -<td id="rsplit.maxsplit"><code>maxsplit</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>unbound</code><br /> -The maximum number of splits.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sep` | [string](../core/string.mdx); required The string to split on. | +| `maxsplit` | [int](../core/int.mdx); default is `unbound` The maximum number of splits. | ## rstrip -``` rule-signature +``` string string.rstrip(chars=None) ``` Returns a copy of the string where trailing characters that appear in `chars` are removed. Note that `chars` is not a suffix: all combinations of its value are removed: -``` python +``` "abcbaa".rstrip("ab") == "abc" ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="rstrip.chars"><code>chars</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The characters to remove, or all whitespace if None.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `chars` | [string](../core/string.mdx); or `None`; default is `None` The characters to remove, or all whitespace if None. | ## split -``` rule-signature +``` list string.split(sep, maxsplit=unbound) ``` @@ -703,32 +414,14 @@ Returns a list of all the words in the string, using `sep` as the separator, opt ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="split.sep"><code>sep</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The string to split on.</td> -</tr> -<tr> -<td id="split.maxsplit"><code>maxsplit</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>unbound</code><br /> -The maximum number of splits.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sep` | [string](../core/string.mdx); required The string to split on. | +| `maxsplit` | [int](../core/int.mdx); default is `unbound` The maximum number of splits. | ## splitlines -``` rule-signature +``` sequence string.splitlines(keepends=False) ``` @@ -736,26 +429,13 @@ Splits the string at line boundaries ('\n', '\r\n', '\r') and returns the result ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="splitlines.keepends"><code>keepends</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether the line breaks should be included in the resulting list.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `keepends` | [bool](../core/bool.mdx); default is `False` Whether the line breaks should be included in the resulting list. | ## startswith -``` rule-signature +``` bool string.startswith(sub, start=0, end=None) ``` @@ -763,69 +443,33 @@ Returns True if the string starts with `sub`, otherwise False, optionally restri ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="startswith.sub"><code>sub</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/tuple.html" class="anchor">tuple</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The prefix (or tuple of alternative prefixes) to match.</td> -</tr> -<tr> -<td id="startswith.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>0</code><br /> -Test beginning at this position.</td> -</tr> -<tr> -<td id="startswith.end"><code>end</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <code>None</code>; -default is <code>None</code><br /> -Stop comparing at this position.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sub` | [string](../core/string.mdx); or [tuple](../core/tuple.mdx) of [string](../core/string.mdx)s; required The prefix (or tuple of alternative prefixes) to match. | +| `start` | [int](../core/int.mdx); or `None`; default is `0` Test beginning at this position. | +| `end` | [int](../core/int.mdx); or `None`; default is `None` Stop comparing at this position. | ## strip -``` rule-signature +``` string string.strip(chars=None) ``` Returns a copy of the string where leading or trailing characters that appear in `chars` are removed. Note that `chars` is neither a prefix nor a suffix: all combinations of its value are removed: -``` python +``` "aabcbcbaa".strip("ab") == "cbc" ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="strip.chars"><code>chars</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The characters to remove, or all whitespace if None.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `chars` | [string](../core/string.mdx); or `None`; default is `None` The characters to remove, or all whitespace if None. | ## title -``` rule-signature +``` string string.title() ``` @@ -833,8 +477,8 @@ Converts the input string into title case, i.e. every word starts with an upperc ## upper -``` rule-signature +``` string string.upper() ``` -Returns the upper case version of this string. +Returns the upper case version of this string. \ No newline at end of file diff --git a/rules/lib/core/tuple.mdx b/rules/lib/core/tuple.mdx index b468c96..bac6886 100644 --- a/rules/lib/core/tuple.mdx +++ b/rules/lib/core/tuple.mdx @@ -2,25 +2,22 @@ title: 'tuple' --- -# tuple -{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/Tuple.java" %} -{% include "\_buttons.html" %} The built-in tuple type. Example tuple expressions: -``` python +``` x = (1, 2, 3) ``` Accessing elements is possible using indexing (starts from `0`): -``` python +``` e = x[1] # e == 2 ``` Lists support the `+` operator to concatenate two tuples. Example: -``` python +``` x = (1, 2) + (3, 4) # x == (1, 2, 3, 4) x = ("a", "b") x += ("c",) # x == ("a", "b", "c") @@ -28,10 +25,10 @@ x += ("c",) # x == ("a", "b", "c") Similar to lists, tuples support slice operations: -``` python +``` ('a', 'b', 'c', 'd')[1:3] # ('b', 'c') ('a', 'b', 'c', 'd')[::2] # ('a', 'c') ('a', 'b', 'c', 'd')[3:0:-1] # ('d', 'c', 'b') ``` -Tuples are immutable, therefore `x[1] = "a"` is not supported. +Tuples are immutable, therefore `x[1] = "a"` is not supported. \ No newline at end of file diff --git a/rules/lib/fragments.mdx b/rules/lib/fragments.mdx index bc620dc..729bb53 100644 --- a/rules/lib/fragments.mdx +++ b/rules/lib/fragments.mdx @@ -2,22 +2,19 @@ title: 'fragments' --- -# Configuration Fragments -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} -Configuration fragments give rules access to language-specific parts of [configuration](builtins/configuration.html). +Configuration fragments give rules access to language-specific parts of [configuration](builtins/configuration.mdx). -Rule implementations can get them using [`ctx.fragments`](builtins/ctx.html#fragments)`.`*`[fragment name]`* +Rule implementations can get them using `ctx.fragments.[fragment name]` -- [apple](/rules/lib/fragments/apple) -- [bazel_android](/rules/lib/fragments/bazel_android) -- [bazel_py](/rules/lib/fragments/bazel_py) -- [coverage](/rules/lib/fragments/coverage) -- [cpp](/rules/lib/fragments/cpp) -- [j2objc](/rules/lib/fragments/j2objc) -- [java](/rules/lib/fragments/java) -- [objc](/rules/lib/fragments/objc) -- [platform](/rules/lib/fragments/platform) -- [proto](/rules/lib/fragments/proto) -- [py](/rules/lib/fragments/py) +* [apple](./rules/lib/fragments/apple) +* [bazel\_android](./rules/lib/fragments/bazel_android) +* [bazel\_py](./rules/lib/fragments/bazel_py) +* [coverage](./rules/lib/fragments/coverage) +* [cpp](./rules/lib/fragments/cpp) +* [j2objc](./rules/lib/fragments/j2objc) +* [java](./rules/lib/fragments/java) +* [objc](./rules/lib/fragments/objc) +* [platform](./rules/lib/fragments/platform) +* [proto](./rules/lib/fragments/proto) +* [py](./rules/lib/fragments/py) \ No newline at end of file diff --git a/rules/lib/fragments/apple.mdx b/rules/lib/fragments/apple.mdx index a3e00a9..61b7b02 100644 --- a/rules/lib/fragments/apple.mdx +++ b/rules/lib/fragments/apple.mdx @@ -2,57 +2,41 @@ title: 'apple' --- -# apple -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleConfigurationApi.java" %} -{% include "\_buttons.html" %} A configuration fragment for Apple platforms. ## Members -- [multi_arch_platform](#multi_arch_platform) -- [single_arch_cpu](#single_arch_cpu) -- [single_arch_platform](#single_arch_platform) +* [multi\_arch\_platform](#multi_arch_platform) +* [single\_arch\_cpu](#single_arch_cpu) +* [single\_arch\_platform](#single_arch_platform) -## multi_arch_platform +## multi\_arch\_platform -``` rule-signature +``` apple_platform apple.multi_arch_platform(platform_type) ``` -The platform of the current configuration for the given platform type. This should only be invoked in a context where multiple architectures may be supported; consider [single_arch_platform](#single_arch_platform) for other cases. +The platform of the current configuration for the given platform type. This should only be invoked in a context where multiple architectures may be supported; consider [single\_arch\_platform](#single_arch_platform) for other cases. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="multi_arch_platform.platform_type"><code>platform_type</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The apple platform type.</td> -</tr> -</tbody> -</table> - -## single_arch_cpu - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `platform_type` | [string](../core/string.mdx); required The apple platform type. | + +## single\_arch\_cpu + +``` string apple.single_arch_cpu ``` The single "effective" architecture for this configuration (e.g., `i386` or `arm64`) in the context of rule logic that is only concerned with a single architecture (such as `objc_library`, which registers single-architecture compile actions). -## single_arch_platform +## single\_arch\_platform -``` rule-signature +``` apple_platform apple.single_arch_platform ``` -The platform of the current configuration. This should only be invoked in a context where only a single architecture may be supported; consider [multi_arch_platform](#multi_arch_platform) for other cases. +The platform of the current configuration. This should only be invoked in a context where only a single architecture may be supported; consider [multi\_arch\_platform](#multi_arch_platform) for other cases. \ No newline at end of file diff --git a/rules/lib/fragments/bazel_android.mdx b/rules/lib/fragments/bazel_android.mdx index 393b736..a1655f7 100644 --- a/rules/lib/fragments/bazel_android.mdx +++ b/rules/lib/fragments/bazel_android.mdx @@ -2,19 +2,15 @@ title: 'bazel_android' --- -# bazel_android - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/rules/android/BazelAndroidConfiguration.java" %} -{% include "\_buttons.html" %} ## Members -- [merge_android_manifest_permissions](#merge_android_manifest_permissions) +* [merge\_android\_manifest\_permissions](#merge_android_manifest_permissions) -## merge_android_manifest_permissions +## merge\_android\_manifest\_permissions -``` rule-signature +``` bool bazel_android.merge_android_manifest_permissions ``` -The value of --merge_android_manifest_permissions flag. +The value of --merge\_android\_manifest\_permissions flag. \ No newline at end of file diff --git a/rules/lib/fragments/bazel_py.mdx b/rules/lib/fragments/bazel_py.mdx index b1246d4..394f74a 100644 --- a/rules/lib/fragments/bazel_py.mdx +++ b/rules/lib/fragments/bazel_py.mdx @@ -2,28 +2,24 @@ title: 'bazel_py' --- -# bazel_py - -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java" %} -{% include "\_buttons.html" %} ## Members -- [python_import_all_repositories](#python_import_all_repositories) -- [python_path](#python_path) +* [python\_import\_all\_repositories](#python_import_all_repositories) +* [python\_path](#python_path) -## python_import_all_repositories +## python\_import\_all\_repositories -``` rule-signature +``` bool bazel_py.python_import_all_repositories ``` -The value of the --experimental_python_import_all_repositories flag. +The value of the --experimental\_python\_import\_all\_repositories flag. -## python_path +## python\_path -``` rule-signature +``` string bazel_py.python_path ``` -The value of the --python_path flag. +The value of the --python\_path flag. \ No newline at end of file diff --git a/rules/lib/fragments/coverage.mdx b/rules/lib/fragments/coverage.mdx index 782c9b2..357c29f 100644 --- a/rules/lib/fragments/coverage.mdx +++ b/rules/lib/fragments/coverage.mdx @@ -2,29 +2,28 @@ title: 'coverage' --- -# coverage -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java" %} -{% include "\_buttons.html" %} A configuration fragment representing the coverage configuration. ## Members -- [output_generator](#output_generator) +* [output\_generator](#output_generator) -## output_generator +## output\_generator -``` rule-signature +``` Label coverage.output_generator ``` Returns the label pointed to by the [`--coverage_output_generator`](https://bazel.build/reference/command-line-reference#flag--coverage_output_generator) option if coverage collection is enabled, otherwise returns `None`. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): - attr.label( - default = configuration_field( - fragment = "coverage", - name = "output_generator" - ) - ) +``` +attr.label( + default = configuration_field( + fragment = "coverage", + name = "output_generator" + ) +) +``` -May return `None`. +May return `None`. \ No newline at end of file diff --git a/rules/lib/fragments/cpp.mdx b/rules/lib/fragments/cpp.mdx index 6c28cb9..f516b69 100644 --- a/rules/lib/fragments/cpp.mdx +++ b/rules/lib/fragments/cpp.mdx @@ -2,27 +2,24 @@ title: 'cpp' --- -# cpp -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java" %} -{% include "\_buttons.html" %} A configuration fragment for C++. ## Members -- [apple_generate_dsym](#apple_generate_dsym) -- [conlyopts](#conlyopts) -- [copts](#copts) -- [custom_malloc](#custom_malloc) -- [cxxopts](#cxxopts) -- [linkopts](#linkopts) -- [objc_generate_linkmap](#objc_generate_linkmap) -- [objc_should_strip_binary](#objc_should_strip_binary) -- [objccopts](#objccopts) +* [apple\_generate\_dsym](#apple_generate_dsym) +* [conlyopts](#conlyopts) +* [copts](#copts) +* [custom\_malloc](#custom_malloc) +* [cxxopts](#cxxopts) +* [linkopts](#linkopts) +* [objc\_generate\_linkmap](#objc_generate_linkmap) +* [objc\_should\_strip\_binary](#objc_should_strip_binary) +* [objccopts](#objccopts) -## apple_generate_dsym +## apple\_generate\_dsym -``` rule-signature +``` bool cpp.apple_generate_dsym ``` @@ -30,64 +27,66 @@ Whether to generate Apple debug symbol(.dSYM) artifacts. ## conlyopts -``` rule-signature +``` list cpp.conlyopts ``` -The flags passed to Bazel by [`--conlyopt`](/docs/user-manual#flag--conlyopt) option. +The flags passed to Bazel by [`--conlyopt`](./docs/user-manual#flag--conlyopt) option. ## copts -``` rule-signature +``` list cpp.copts ``` -The flags passed to Bazel by [`--copt`](/docs/user-manual#flag--copt) option. +The flags passed to Bazel by [`--copt`](./docs/user-manual#flag--copt) option. -## custom_malloc +## custom\_malloc -``` rule-signature +``` Label cpp.custom_malloc ``` -Returns label pointed to by [`--custom_malloc`](/docs/user-manual#flag--custom_malloc) option. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): +Returns label pointed to by [`--custom_malloc`](./docs/user-manual#flag--custom_malloc) option. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): - attr.label( - default = configuration_field( - fragment = "cpp", - name = "custom_malloc" - ) - ) +``` +attr.label( + default = configuration_field( + fragment = "cpp", + name = "custom_malloc" + ) +) +``` May return `None`. ## cxxopts -``` rule-signature +``` list cpp.cxxopts ``` -The flags passed to Bazel by [`--cxxopt`](/docs/user-manual#flag--cxxopt) option. +The flags passed to Bazel by [`--cxxopt`](./docs/user-manual#flag--cxxopt) option. ## linkopts -``` rule-signature +``` list cpp.linkopts ``` -The flags passed to Bazel by [`--linkopt`](/docs/user-manual#flag--linkopt) option. +The flags passed to Bazel by [`--linkopt`](./docs/user-manual#flag--linkopt) option. -## objc_generate_linkmap +## objc\_generate\_linkmap -``` rule-signature +``` bool cpp.objc_generate_linkmap ``` (Apple-only) Whether to generate linkmap artifacts. -## objc_should_strip_binary +## objc\_should\_strip\_binary -``` rule-signature +``` bool cpp.objc_should_strip_binary ``` @@ -95,8 +94,8 @@ bool cpp.objc_should_strip_binary ## objccopts -``` rule-signature +``` list cpp.objccopts ``` -The flags passed to Bazel by [`--objccopt`](/docs/user-manual#flag--objccopt) option. +The flags passed to Bazel by [`--objccopt`](./docs/user-manual#flag--objccopt) option. \ No newline at end of file diff --git a/rules/lib/fragments/j2objc.mdx b/rules/lib/fragments/j2objc.mdx index 23f0ffd..05923d9 100644 --- a/rules/lib/fragments/j2objc.mdx +++ b/rules/lib/fragments/j2objc.mdx @@ -2,20 +2,17 @@ title: 'j2objc' --- -# j2objc -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/J2ObjcConfigurationApi.java" %} -{% include "\_buttons.html" %} A configuration fragment for j2Objc. ## Members -- [translation_flags](#translation_flags) +* [translation\_flags](#translation_flags) -## translation_flags +## translation\_flags -``` rule-signature +``` list j2objc.translation_flags ``` -The list of flags to be used when the j2objc compiler is invoked. +The list of flags to be used when the j2objc compiler is invoked. \ No newline at end of file diff --git a/rules/lib/fragments/java.mdx b/rules/lib/fragments/java.mdx index fcbb189..a42a07b 100644 --- a/rules/lib/fragments/java.mdx +++ b/rules/lib/fragments/java.mdx @@ -2,137 +2,134 @@ title: 'java' --- -# java -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaConfigurationApi.java" %} -{% include "\_buttons.html" %} A java compiler configuration. ## Members -- [bytecode_optimization_pass_actions](#bytecode_optimization_pass_actions) -- [bytecode_optimizer_mnemonic](#bytecode_optimizer_mnemonic) -- [default_javac_flags](#default_javac_flags) -- [default_javac_flags_depset](#default_javac_flags_depset) -- [default_jvm_opts](#default_jvm_opts) -- [disallow_java_import_exports](#disallow_java_import_exports) -- [multi_release_deploy_jars](#multi_release_deploy_jars) -- [one_version_enforcement_level](#one_version_enforcement_level) -- [plugins](#plugins) -- [run_android_lint](#run_android_lint) -- [split_bytecode_optimization_pass](#split_bytecode_optimization_pass) -- [strict_java_deps](#strict_java_deps) -- [use_header_compilation_direct_deps](#use_header_compilation_direct_deps) -- [use_ijars](#use_ijars) - -## bytecode_optimization_pass_actions - -``` rule-signature +* [bytecode\_optimization\_pass\_actions](#bytecode_optimization_pass_actions) +* [bytecode\_optimizer\_mnemonic](#bytecode_optimizer_mnemonic) +* [default\_javac\_flags](#default_javac_flags) +* [default\_javac\_flags\_depset](#default_javac_flags_depset) +* [default\_jvm\_opts](#default_jvm_opts) +* [disallow\_java\_import\_exports](#disallow_java_import_exports) +* [multi\_release\_deploy\_jars](#multi_release_deploy_jars) +* [one\_version\_enforcement\_level](#one_version_enforcement_level) +* [plugins](#plugins) +* [run\_android\_lint](#run_android_lint) +* [split\_bytecode\_optimization\_pass](#split_bytecode_optimization_pass) +* [strict\_java\_deps](#strict_java_deps) +* [use\_header\_compilation\_direct\_deps](#use_header_compilation_direct_deps) +* [use\_ijars](#use_ijars) + +## bytecode\_optimization\_pass\_actions + +``` int java.bytecode_optimization_pass_actions ``` -This specifies the number of actions to divide the OPTIMIZATION stage of the bytecode optimizer into. Note that if split_bytecode_optimization_pass is set, this will only change behavior if it is \> 2. +This specifies the number of actions to divide the OPTIMIZATION stage of the bytecode optimizer into. Note that if split\_bytecode\_optimization\_pass is set, this will only change behavior if it is > 2. -## bytecode_optimizer_mnemonic +## bytecode\_optimizer\_mnemonic -``` rule-signature +``` string java.bytecode_optimizer_mnemonic ``` The mnemonic for the bytecode optimizer. -## default_javac_flags +## default\_javac\_flags -``` rule-signature +``` list java.default_javac_flags ``` The default flags for the Java compiler. -## default_javac_flags_depset +## default\_javac\_flags\_depset -``` rule-signature +``` depset java.default_javac_flags_depset ``` The default flags for the Java compiler. -## default_jvm_opts +## default\_jvm\_opts -``` rule-signature +``` list java.default_jvm_opts ``` -Additional options to pass to the Java VM for each java_binary target +Additional options to pass to the Java VM for each java\_binary target -## disallow_java_import_exports +## disallow\_java\_import\_exports -``` rule-signature +``` bool java.disallow_java_import_exports() ``` -Returns true if java_import exports are not allowed. +Returns true if java\_import exports are not allowed. -## multi_release_deploy_jars +## multi\_release\_deploy\_jars -``` rule-signature +``` bool java.multi_release_deploy_jars ``` -The value of the --incompatible_multi_release_deploy_jars flag. +The value of the --incompatible\_multi\_release\_deploy\_jars flag. -## one_version_enforcement_level +## one\_version\_enforcement\_level -``` rule-signature +``` string java.one_version_enforcement_level ``` -The value of the --experimental_one_version_enforcement flag. +The value of the --experimental\_one\_version\_enforcement flag. ## plugins -``` rule-signature +``` list java.plugins ``` A list containing the labels provided with --plugins, if any. -## run_android_lint +## run\_android\_lint -``` rule-signature +``` bool java.run_android_lint ``` -The value of the --experimental_run_android_lint_on_java_rules flag. +The value of the --experimental\_run\_android\_lint\_on\_java\_rules flag. -## split_bytecode_optimization_pass +## split\_bytecode\_optimization\_pass -``` rule-signature +``` bool java.split_bytecode_optimization_pass ``` Returns whether the OPTIMIZATION stage of the bytecode optimizer will be split across two actions. -## strict_java_deps +## strict\_java\_deps -``` rule-signature +``` string java.strict_java_deps ``` -The value of the strict_java_deps flag. +The value of the strict\_java\_deps flag. -## use_header_compilation_direct_deps +## use\_header\_compilation\_direct\_deps -``` rule-signature +``` bool java.use_header_compilation_direct_deps() ``` Returns true if Java header compilation should use separate outputs for direct deps. -## use_ijars +## use\_ijars -``` rule-signature +``` bool java.use_ijars() ``` -Returns true iff Java compilation should use ijars. +Returns true iff Java compilation should use ijars. \ No newline at end of file diff --git a/rules/lib/fragments/objc.mdx b/rules/lib/fragments/objc.mdx index c6dd982..ef26650 100644 --- a/rules/lib/fragments/objc.mdx +++ b/rules/lib/fragments/objc.mdx @@ -2,104 +2,101 @@ title: 'objc' --- -# objc -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ObjcConfigurationApi.java" %} -{% include "\_buttons.html" %} A configuration fragment for Objective-C. ## Members -- [alwayslink_by_default](#alwayslink_by_default) -- [builtin_objc_strip_action](#builtin_objc_strip_action) -- [copts_for_current_compilation_mode](#copts_for_current_compilation_mode) -- [disallow_sdk_frameworks_attributes](#disallow_sdk_frameworks_attributes) -- [ios_simulator_device](#ios_simulator_device) -- [ios_simulator_version](#ios_simulator_version) -- [run_memleaks](#run_memleaks) -- [signing_certificate_name](#signing_certificate_name) -- [strip_executable_safely](#strip_executable_safely) -- [uses_device_debug_entitlements](#uses_device_debug_entitlements) +* [alwayslink\_by\_default](#alwayslink_by_default) +* [builtin\_objc\_strip\_action](#builtin_objc_strip_action) +* [copts\_for\_current\_compilation\_mode](#copts_for_current_compilation_mode) +* [disallow\_sdk\_frameworks\_attributes](#disallow_sdk_frameworks_attributes) +* [ios\_simulator\_device](#ios_simulator_device) +* [ios\_simulator\_version](#ios_simulator_version) +* [run\_memleaks](#run_memleaks) +* [signing\_certificate\_name](#signing_certificate_name) +* [strip\_executable\_safely](#strip_executable_safely) +* [uses\_device\_debug\_entitlements](#uses_device_debug_entitlements) -## alwayslink_by_default +## alwayslink\_by\_default -``` rule-signature +``` bool objc.alwayslink_by_default ``` -Returns whether objc_library and objc_import should default to alwayslink=True. +Returns whether objc\_library and objc\_import should default to alwayslink=True. -## builtin_objc_strip_action +## builtin\_objc\_strip\_action -``` rule-signature +``` bool objc.builtin_objc_strip_action ``` Returns whether to emit a strip action as part of objc linking. -## copts_for_current_compilation_mode +## copts\_for\_current\_compilation\_mode -``` rule-signature +``` list objc.copts_for_current_compilation_mode ``` Returns a list of default options to use for compiling Objective-C in the current mode. -## disallow_sdk_frameworks_attributes +## disallow\_sdk\_frameworks\_attributes -``` rule-signature +``` bool objc.disallow_sdk_frameworks_attributes ``` -Returns whether sdk_frameworks and weak_sdk_frameworks are disallowed attributes. +Returns whether sdk\_frameworks and weak\_sdk\_frameworks are disallowed attributes. -## ios_simulator_device +## ios\_simulator\_device -``` rule-signature +``` string objc.ios_simulator_device ``` The type of device (e.g. 'iPhone 6') to use when running on the simulator. May return `None`. -## ios_simulator_version +## ios\_simulator\_version -``` rule-signature +``` DottedVersion objc.ios_simulator_version ``` The SDK version of the iOS simulator to use when running on the simulator. May return `None`. -## run_memleaks +## run\_memleaks -``` rule-signature +``` bool objc.run_memleaks ``` Returns a boolean indicating whether memleaks should be run during tests or not. -## signing_certificate_name +## signing\_certificate\_name -``` rule-signature +``` string objc.signing_certificate_name ``` Returns the flag-supplied certificate name to be used in signing, or None if no such certificate was specified. May return `None`. -## strip_executable_safely +## strip\_executable\_safely -``` rule-signature +``` bool objc.strip_executable_safely ``` Returns whether executable strip action should use flag -x, which does not break dynamic symbol resolution. -## uses_device_debug_entitlements +## uses\_device\_debug\_entitlements -``` rule-signature +``` bool objc.uses_device_debug_entitlements ``` -Returns whether device debug entitlements should be included when signing an application. +Returns whether device debug entitlements should be included when signing an application. \ No newline at end of file diff --git a/rules/lib/fragments/platform.mdx b/rules/lib/fragments/platform.mdx index bd008c5..704068e 100644 --- a/rules/lib/fragments/platform.mdx +++ b/rules/lib/fragments/platform.mdx @@ -2,20 +2,17 @@ title: 'platform' --- -# platform -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformConfigurationApi.java" %} -{% include "\_buttons.html" %} The platform configuration. ## Members -- [host_platform](#host_platform) -- [platform](#platform) +* [host\_platform](#host_platform) +* [platform](#platform) -## host_platform +## host\_platform -``` rule-signature +``` Label platform.host_platform ``` @@ -23,8 +20,8 @@ The current host platform ## platform -``` rule-signature +``` Label platform.platform ``` -The current target platform +The current target platform \ No newline at end of file diff --git a/rules/lib/fragments/proto.mdx b/rules/lib/fragments/proto.mdx index e04ae09..22ffd17 100644 --- a/rules/lib/fragments/proto.mdx +++ b/rules/lib/fragments/proto.mdx @@ -2,8 +2,5 @@ title: 'proto' --- -# proto -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ProtoConfigurationApi.java" %} -{% include "\_buttons.html" %} -A configuration fragment representing protocol buffers. +A configuration fragment representing protocol buffers. \ No newline at end of file diff --git a/rules/lib/fragments/py.mdx b/rules/lib/fragments/py.mdx index d3721fd..c51900c 100644 --- a/rules/lib/fragments/py.mdx +++ b/rules/lib/fragments/py.mdx @@ -2,74 +2,71 @@ title: 'py' --- -# py -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/rules/python/PythonConfiguration.java" %} -{% include "\_buttons.html" %} A configuration fragment for Python. ## Members -- [build_python_zip](#build_python_zip) -- [default_python_version](#default_python_version) -- [default_to_explicit_init_py](#default_to_explicit_init_py) -- [disable_py2](#disable_py2) -- [disallow_native_rules](#disallow_native_rules) -- [include_label_in_linkstamp](#include_label_in_linkstamp) -- [use_toolchains](#use_toolchains) +* [build\_python\_zip](#build_python_zip) +* [default\_python\_version](#default_python_version) +* [default\_to\_explicit\_init\_py](#default_to_explicit_init_py) +* [disable\_py2](#disable_py2) +* [disallow\_native\_rules](#disallow_native_rules) +* [include\_label\_in\_linkstamp](#include_label_in_linkstamp) +* [use\_toolchains](#use_toolchains) -## build_python_zip +## build\_python\_zip -``` rule-signature +``` bool py.build_python_zip ``` -The effective value of --build_python_zip +The effective value of --build\_python\_zip -## default_python_version +## default\_python\_version -``` rule-signature +``` string py.default_python_version ``` No-op: PY3 is the default Python version. -## default_to_explicit_init_py +## default\_to\_explicit\_init\_py -``` rule-signature +``` bool py.default_to_explicit_init_py ``` -The value from the --incompatible_default_to_explicit_init_py flag +The value from the --incompatible\_default\_to\_explicit\_init\_py flag -## disable_py2 +## disable\_py2 -``` rule-signature +``` bool py.disable_py2 ``` No-op: PY2 is no longer supported. -## disallow_native_rules +## disallow\_native\_rules -``` rule-signature +``` bool py.disallow_native_rules ``` -The value of the --incompatible_python_disallow_native_rules flag. +The value of the --incompatible\_python\_disallow\_native\_rules flag. -## include_label_in_linkstamp +## include\_label\_in\_linkstamp -``` rule-signature +``` bool py.include_label_in_linkstamp ``` Whether the build label is included in unstamped builds. -## use_toolchains +## use\_toolchains -``` rule-signature +``` bool py.use_toolchains ``` -No-op: Python toolchains are always used. +No-op: Python toolchains are always used. \ No newline at end of file diff --git a/rules/lib/globals.mdx b/rules/lib/globals.mdx index b8d5af2..f74bca9 100644 --- a/rules/lib/globals.mdx +++ b/rules/lib/globals.mdx @@ -2,15 +2,12 @@ title: 'globals' --- -# Global functions -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} This section lists the global functions available in Starlark. The list of available functions differs depending on the file type (whether a BUILD file, or a .bzl file, etc). -- [.bzl files](/rules/lib/globals/bzl) -- [All Bazel files](/rules/lib/globals/all) -- [BUILD files](/rules/lib/globals/build) -- [MODULE.bazel files](/rules/lib/globals/module) -- [REPO.bazel files](/rules/lib/globals/repo) -- [VENDOR.bazel files](/rules/lib/globals/vendor) +* [.bzl files](./rules/lib/globals/bzl) +* [All Bazel files](./rules/lib/globals/all) +* [BUILD files](./rules/lib/globals/build) +* [MODULE.bazel files](./rules/lib/globals/module) +* [REPO.bazel files](./rules/lib/globals/repo) +* [VENDOR.bazel files](./rules/lib/globals/vendor) \ No newline at end of file diff --git a/rules/lib/globals/all.mdx b/rules/lib/globals/all.mdx index bc01aa1..6711ea1 100644 --- a/rules/lib/globals/all.mdx +++ b/rules/lib/globals/all.mdx @@ -2,140 +2,98 @@ title: 'all' --- -# All Bazel files -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} Methods available in all Bazel files, including .bzl files, BUILD, MODULE.bazel, VENDOR.bazel, and WORKSPACE. ## Members -- [abs](#abs) -- [all](#all) -- [any](#any) -- [bool](#bool) -- [dict](#dict) -- [dir](#dir) -- [enumerate](#enumerate) -- [fail](#fail) -- [float](#float) -- [getattr](#getattr) -- [hasattr](#hasattr) -- [hash](#hash) -- [int](#int) -- [len](#len) -- [list](#list) -- [max](#max) -- [min](#min) -- [print](#print) -- [range](#range) -- [repr](#repr) -- [reversed](#reversed) -- [set](#set) -- [sorted](#sorted) -- [str](#str) -- [tuple](#tuple) -- [type](#type) -- [zip](#zip) +* [abs](#abs) +* [all](#all) +* [any](#any) +* [bool](#bool) +* [dict](#dict) +* [dir](#dir) +* [enumerate](#enumerate) +* [fail](#fail) +* [float](#float) +* [getattr](#getattr) +* [hasattr](#hasattr) +* [hash](#hash) +* [int](#int) +* [len](#len) +* [list](#list) +* [max](#max) +* [min](#min) +* [print](#print) +* [range](#range) +* [repr](#repr) +* [reversed](#reversed) +* [set](#set) +* [sorted](#sorted) +* [str](#str) +* [tuple](#tuple) +* [type](#type) +* [zip](#zip) ## abs -``` rule-signature +``` unknown abs(x) ``` Returns the absolute value of a number (a non-negative number with the same magnitude). -``` python +``` abs(-2.3) == 2.3 ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="abs.x"><code>x</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; or <a href="../core/float.html" class="anchor">float</a>; -required<br /> -A number (int or float)</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | [int](../core/int.mdx); or [float](../core/float.mdx); required A number (int or float) | ## all -``` rule-signature +``` bool all(elements) ``` Returns true if all elements evaluate to True or if the collection is empty. Elements are converted to boolean using the [bool](#bool) function. -``` python +``` all(["hello", 3, True]) == True all([-1, 0, 1]) == False ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="all.elements"><code>elements</code></td> -<td>iterable; -required<br /> -A collection of elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `elements` | iterable; required A collection of elements. | ## any -``` rule-signature +``` bool any(elements) ``` Returns true if at least one element evaluates to True. Elements are converted to boolean using the [bool](#bool) function. -``` python +``` any([-1, 0, 1]) == True any([False, 0, ""]) == False ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="any.elements"><code>elements</code></td> -<td>iterable; -required<br /> -A collection of elements.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `elements` | iterable; required A collection of elements. | ## bool -``` rule-signature +``` bool bool(x=False) ``` @@ -143,56 +101,28 @@ Constructor for the bool type. It returns `False` if the object is `None`, `Fals ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="bool.x"><code>x</code></td> -<td>default is <code>False</code><br /> -The variable to convert.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | default is `False` The variable to convert. | ## dict -``` rule-signature +``` dict dict(pairs=[], **kwargs) ``` -Creates a [dictionary](../core/dict.html) from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument. +Creates a [dictionary](../core/dict.mdx) from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="dict.pairs"><code>pairs</code></td> -<td>default is <code>[]</code><br /> -A dict, or an iterable whose elements are each of length 2 (key, value).</td> -</tr> -<tr> -<td id="dict.kwargs"><code>kwargs</code></td> -<td>required<br /> -Dictionary of additional entries.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `pairs` | default is `[]` A dict, or an iterable whose elements are each of length 2 (key, value). | +| `kwargs` | required Dictionary of additional entries. | ## dir -``` rule-signature +``` list dir(x) ``` @@ -200,61 +130,32 @@ Returns a list of strings: the names of the attributes and methods of the parame ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="dir.x"><code>x</code></td> -<td>required<br /> -The object to check.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required The object to check. | ## enumerate -``` rule-signature +``` list enumerate(list, start=0) ``` Returns a list of pairs (two-element tuples), with the index (int) and the item from the input sequence. -``` python +``` enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)] ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="enumerate.list"><code>list</code></td> -<td>required<br /> -input sequence.</td> -</tr> -<tr> -<td id="enumerate.start"><code>start</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>0</code><br /> -start index.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `list` | required input sequence. | +| `start` | [int](../core/int.mdx); default is `0` start index. | ## fail -``` rule-signature +``` None fail(*args, msg=None, attr=None, sep=" ") ``` @@ -262,160 +163,80 @@ Causes execution to fail with an error. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="fail.msg"><code>msg</code></td> -<td>default is <code>None</code><br /> -Deprecated: use positional arguments instead. This argument acts like an implicit leading positional argument.</td> -</tr> -<tr> -<td id="fail.attr"><code>attr</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Deprecated. Causes an optional prefix containing this string to be added to the error message.</td> -</tr> -<tr> -<td id="fail.sep"><code>sep</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>" "</code><br /> -The separator string between the objects, default is space (" ").</td> -</tr> -<tr> -<td id="fail.args"><code>args</code></td> -<td>required<br /> -A list of values, formatted with debugPrint (which is equivalent to str by default) and joined with sep (defaults to " "), that appear in the error message.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `msg` | default is `None` Deprecated: use positional arguments instead. This argument acts like an implicit leading positional argument. | +| `attr` | [string](../core/string.mdx); or `None`; default is `None` Deprecated. Causes an optional prefix containing this string to be added to the error message. | +| `sep` | [string](../core/string.mdx); default is `" "` The separator string between the objects, default is space (" "). | +| `args` | required A list of values, formatted with debugPrint (which is equivalent to str by default) and joined with sep (defaults to " "), that appear in the error message. | ## float -``` rule-signature +``` float float(x=unbound) ``` Returns x as a float value. -- If `x` is already a float, `float` returns it unchanged. -- If `x` is a bool, `float` returns 1.0 for True and 0.0 for False. -- If `x` is an int, `float` returns the nearest finite floating-point value to x, or an error if the magnitude is too large. -- If `x` is a string, it must be a valid floating-point literal, or be equal (ignoring case) to `NaN`, `Inf`, or `Infinity`, optionally preceded by a `+` or `-` sign. +* If `x` is already a float, `float` returns it unchanged.* If `x` is a bool, `float` returns 1.0 for True and 0.0 for False.* If `x` is an int, `float` returns the nearest finite floating-point value to x, or an error if the magnitude is too large.* If `x` is a string, it must be a valid floating-point literal, or be equal (ignoring case) to `NaN`, `Inf`, or `Infinity`, optionally preceded by a `+` or `-` sign. Any other value causes an error. With no argument, `float()` returns 0.0. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="float.x"><code>x</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/int.html" class="anchor">int</a>; or <a href="../core/float.html" class="anchor">float</a>; -default is <code>unbound</code><br /> -The value to convert.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | [string](../core/string.mdx); or [bool](../core/bool.mdx); or [int](../core/int.mdx); or [float](../core/float.mdx); default is `unbound` The value to convert. | ## getattr -``` rule-signature +``` unknown getattr(x, name, default=unbound) ``` Returns the struct's field of the given name if it exists. If not, it either returns `default` (if specified) or raises an error. `getattr(x, "foobar")` is equivalent to `x.foobar`. -``` python +``` getattr(ctx.attr, "myattr") getattr(ctx.attr, "myattr", "mydefault") ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="getattr.x"><code>x</code></td> -<td>required<br /> -The struct whose attribute is accessed.</td> -</tr> -<tr> -<td id="getattr.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the struct attribute.</td> -</tr> -<tr> -<td id="getattr.default"><code>default</code></td> -<td>default is <code>unbound</code><br /> -The default value to return in case the struct doesn't have an attribute of the given name.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required The struct whose attribute is accessed. | +| `name` | [string](../core/string.mdx); required The name of the struct attribute. | +| `default` | default is `unbound` The default value to return in case the struct doesn't have an attribute of the given name. | ## hasattr -``` rule-signature +``` bool hasattr(x, name) ``` Returns True if the object `x` has an attribute or method of the given `name`, otherwise False. Example: -``` python +``` hasattr(ctx.attr, "myattr") ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="hasattr.x"><code>x</code></td> -<td>required<br /> -The object to check.</td> -</tr> -<tr> -<td id="hasattr.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the attribute.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required | +| `name` | [string](../core/string.mdx); required The name of the attribute. | ## hash -``` rule-signature +``` int hash(value) ``` Return a hash value for a string. This is computed deterministically using the same algorithm as Java's `String.hashCode()`, namely: -``` python +``` s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1] ``` @@ -423,41 +244,25 @@ Hashing of values besides strings is not currently supported. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="hash.value"><code>value</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -String value to hash.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `value` | [string](../core/string.mdx); required String value to hash. | ## int -``` rule-signature +``` int int(x, base=unbound) ``` Returns x as an int value. -- If `x` is already an int, `int` returns it unchanged. -- If `x` is a bool, `int` returns 1 for True and 0 for False. -- If `x` is a string, it must have the format `<sign><prefix><digits>`. `<sign>` is either `"+"`, `"-"`, or empty (interpreted as positive). `<digits>` are a sequence of digits from 0 up to `base` - 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where `base` is 2/8/16, `<prefix>` is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the `base` is any other value besides these bases or the special value 0, the prefix must be empty. In the case where `base` is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If `base` is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type. -- If `x` is a float, `int` returns the integer value of the float, rounding towards zero. It is an error if x is non-finite (NaN or infinity). +* If `x` is already an int, `int` returns it unchanged.* If `x` is a bool, `int` returns 1 for True and 0 for False.* If `x` is a string, it must have the format `<sign><prefix><digits>`. `<sign>` is either `"+"`, `"-"`, or empty (interpreted as positive). `<digits>` are a sequence of digits from 0 up to `base` - 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where `base` is 2/8/16, `<prefix>` is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the `base` is any other value besides these bases or the special value 0, the prefix must be empty. In the case where `base` is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If `base` is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type.* If `x` is a float, `int` returns the integer value of the float, rounding towards zero. It is an error if x is non-finite (NaN or infinity). This function fails if `x` is any other type, or if the value is a string not satisfying the above format. Unlike Python's `int` function, this function does not allow zero arguments, and does not allow extraneous whitespace for string arguments. Examples: -``` python +``` int("123") == 123 int("-123") == -123 int("+123") == 123 @@ -471,32 +276,14 @@ int("123.456") == 123 ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="int.x"><code>x</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/int.html" class="anchor">int</a>; or <a href="../core/float.html" class="anchor">float</a>; -required<br /> -The string to convert.</td> -</tr> -<tr> -<td id="int.base"><code>base</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>unbound</code><br /> -The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if <code>x</code> were an integer literal. This parameter must not be supplied if the value is not a string.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | [string](../core/string.mdx); or [bool](../core/bool.mdx); or [int](../core/int.mdx); or [float](../core/float.mdx); required The string to convert. | +| `base` | [int](../core/int.mdx); default is `unbound` The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if `x` were an integer literal. This parameter must not be supplied if the value is not a string. | ## len -``` rule-signature +``` int len(x) ``` @@ -504,66 +291,39 @@ Returns the length of a string, sequence (such as a list or tuple), dict, set, o ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="len.x"><code>x</code></td> -<td>iterable; or <a href="../core/string.html" class="anchor">string</a>; -required<br /> -The value whose length to report.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | iterable; or [string](../core/string.mdx); required The value whose length to report. | ## list -``` rule-signature +``` list list(x=[]) ``` Returns a new list with the same elements as the given iterable value. -``` python +``` list([1, 2]) == [1, 2] list((2, 3, 2)) == [2, 3, 2] -list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4] +list(\{5: "a", 2: "b", 4: "c"\}) == [5, 2, 4] ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="list.x"><code>x</code></td> -<td>iterable; -default is <code>[]</code><br /> -The object to convert.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | iterable; default is `[]` The object to convert. | ## max -``` rule-signature +``` unknown max(*args, key=None) ``` Returns the largest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable.It is an error if elements are not comparable (for example int with string), or if no arguments are given. -``` python - +``` max(2, 5, 4) == 5 max([5, 6, 3]) == 6 max("two", "three", "four", key = len) =="three" # the longest @@ -572,38 +332,20 @@ max([1, -1, -2, 2], key = abs) == -2 # the first encountered with maximal key v ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="max.key"><code>key</code></td> -<td>callable; or <code>None</code>; -default is <code>None</code><br /> -An optional function applied to each element before comparison.</td> -</tr> -<tr> -<td id="max.args"><code>args</code></td> -<td>required<br /> -The elements to be checked.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `key` | callable; or `None`; default is `None` An optional function applied to each element before comparison. | +| `args` | required The elements to be checked. | ## min -``` rule-signature +``` unknown min(*args, key=None) ``` Returns the smallest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable. It is an error if elements are not comparable (for example int with string), or if no arguments are given. -``` python - +``` min(2, 5, 4) == 2 min([5, 6, 3]) == 3 min("six", "three", "four", key = len) == "six" # the shortest @@ -612,31 +354,14 @@ min([2, -2, -1, 1], key = abs) == -1 # the first encountered with minimal key v ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="min.key"><code>key</code></td> -<td>callable; or <code>None</code>; -default is <code>None</code><br /> -An optional function applied to each element before comparison.</td> -</tr> -<tr> -<td id="min.args"><code>args</code></td> -<td>required<br /> -The elements to be checked.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `key` | callable; or `None`; default is `None` An optional function applied to each element before comparison. | +| `args` | required The elements to be checked. | ## print -``` rule-signature +``` None print(*args, sep=" ") ``` @@ -646,37 +371,20 @@ Using `print` in production code is discouraged due to the spam it creates for u ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="print.sep"><code>sep</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>" "</code><br /> -The separator string between the objects, default is space (" ").</td> -</tr> -<tr> -<td id="print.args"><code>args</code></td> -<td>required<br /> -The objects to print.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sep` | [string](../core/string.mdx); default is `" "` The separator string between the objects, default is space (" "). | +| `args` | required The objects to print. | ## range -``` rule-signature +``` sequence range(start_or_stop, stop=unbound, step=1) ``` Creates a list where items go from `start` to `stop`, using a `step` increment. If a single argument is provided, items will range from 0 to that element. -``` python +``` range(4) == [0, 1, 2, 3] range(3, 9, 2) == [3, 5, 7] range(3, 0, -1) == [3, 2, 1] @@ -684,146 +392,83 @@ range(3, 0, -1) == [3, 2, 1] ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="range.start_or_stop"><code>start_or_stop</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -required<br /> -Value of the start element if stop is provided, otherwise value of stop and the actual start is 0</td> -</tr> -<tr> -<td id="range.stop"><code>stop</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>unbound</code><br /> -optional index of the first item <em>not</em> to be included in the resulting list; generation of the list stops before <code>stop</code> is reached.</td> -</tr> -<tr> -<td id="range.step"><code>step</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>1</code><br /> -The increment (default is 1). It may be negative.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `start_or_stop` | [int](../core/int.mdx); required Value of the start element if stop is provided, otherwise value of stop and the actual start is 0 | +| `stop` | [int](../core/int.mdx); default is `unbound` optional index of the first item *not* to be included in the resulting list; generation of the list stops before `stop` is reached. | +| `step` | [int](../core/int.mdx); default is `1` The increment (default is 1). It may be negative. | ## repr -``` rule-signature +``` string repr(x) ``` Converts any object to a string representation. This is useful for debugging. -``` python +``` repr("ab") == '"ab"' ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="repr.x"><code>x</code></td> -<td>required<br /> -The object to convert.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required | ## reversed -``` rule-signature +``` list reversed(sequence) ``` Returns a new, unfrozen list that contains the elements of the original iterable sequence in reversed order. -``` python +``` reversed([3, 5, 4]) == [4, 5, 3] ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="reversed.sequence"><code>sequence</code></td> -<td>iterable; -required<br /> -The iterable sequence (e.g. list) to be reversed.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `sequence` | iterable; required The iterable sequence (e.g. list) to be reversed. | ## set -``` rule-signature +``` set set(elements=[]) ``` -Creates a new [set](../core/set.html) containing the unique elements of a given +Creates a new [set](../core/set.mdx) containing the unique elements of a given iterable, preserving iteration order. If called with no argument, `set()` returns a new empty set. For example, -``` python - +``` set() # an empty set set([3, 1, 1, 2]) # set([3, 1, 2]), a set of three elements -set({"k1": "v1", "k2": "v2"}) # set(["k1", "k2"]), a set of two elements +set(\{"k1": "v1", "k2": "v2"\}) # set(["k1", "k2"]), a set of two elements ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="set.elements"><code>elements</code></td> -<td>iterable; -default is <code>[]</code><br /> -An iterable of hashable values.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `elements` | iterable; default is `[]` An iterable of hashable values. | ## sorted -``` rule-signature +``` list sorted(iterable, key=None, *, reverse=False) ``` -Returns a new sorted list containing all the elements of the supplied iterable sequence. An error may occur if any pair of elements x, y may not be compared using x \< y. The elements are sorted into ascending order, unless the reverse argument is True, in which case the order is descending. +Returns a new sorted list containing all the elements of the supplied iterable sequence. An error may occur if any pair of elements x, y may not be compared using x < y. The elements are sorted into ascending order, unless the reverse argument is True, in which case the order is descending. Sorting is stable: elements that compare equal retain their original relative order. -``` python - +``` sorted([3, 5, 4]) == [3, 4, 5] sorted([3, 5, 4], reverse = True) == [5, 4, 3] sorted(["two", "three", "four"], key = len) == ["two", "four", "three"] # sort by length @@ -831,108 +476,60 @@ sorted(["two", "three", "four"], key = len) == ["two", "four", "three"] # sort ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="sorted.iterable"><code>iterable</code></td> -<td>iterable; -required<br /> -The iterable sequence to sort.</td> -</tr> -<tr> -<td id="sorted.key"><code>key</code></td> -<td>callable; or <code>None</code>; -default is <code>None</code><br /> -An optional function applied to each element before comparison.</td> -</tr> -<tr> -<td id="sorted.reverse"><code>reverse</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Return results in descending order.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `iterable` | iterable; required The iterable sequence to sort. | +| `key` | callable; or `None`; default is `None` An optional function applied to each element before comparison. | +| `reverse` | [bool](../core/bool.mdx); default is `False` Return results in descending order. | ## str -``` rule-signature +``` string str(x) ``` Converts any object to string. This is useful for debugging. -``` python +``` str("ab") == "ab" str(8) == "8" ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="str.x"><code>x</code></td> -<td>required<br /> -The object to convert.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required The object to convert. | ## tuple -``` rule-signature +``` tuple tuple(x=()) ``` Returns a tuple with the same elements as the given iterable value. -``` python +``` tuple([1, 2]) == (1, 2) tuple((2, 3, 2)) == (2, 3, 2) -tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4) +tuple(\{5: "a", 2: "b", 4: "c"\}) == (5, 2, 4) ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="tuple.x"><code>x</code></td> -<td>iterable; -default is <code>()</code><br /> -The object to convert.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | iterable; default is `()` The object to convert. | ## type -``` rule-signature +``` string type(x) ``` Returns the type name of its argument. This is useful for debugging and type-checking. Examples: -``` python +``` type(2) == "int" type([1]) == "list" type(struct(a = 2)) == "struct" @@ -940,37 +537,25 @@ type(struct(a = 2)) == "struct" This function might change in the future. To write Python-compatible code and be future-proof, use it only to compare return values: -``` python +``` if type(x) == type([]): # if x is a list ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="type.x"><code>x</code></td> -<td>required<br /> -The object to check type of.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | required The object to check type of. | ## zip -``` rule-signature +``` list zip(*args) ``` Returns a `list` of `tuple`s, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The list has the size of the shortest input. With a single iterable argument, it returns a list of 1-tuples. With no arguments, it returns an empty list. Examples: -``` python +``` zip() # == [] zip([1, 2]) # == [(1,), (2,)] zip([1, 2], [3, 4]) # == [(1, 3), (2, 4)] @@ -979,18 +564,6 @@ zip([1, 2], [3, 4, 5]) # == [(1, 3), (2, 4)] ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="zip.args"><code>args</code></td> -<td>required<br /> -lists to zip.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `args` | required lists to zip. | \ No newline at end of file diff --git a/rules/lib/globals/build.mdx b/rules/lib/globals/build.mdx index 74130b3..70ef741 100644 --- a/rules/lib/globals/build.mdx +++ b/rules/lib/globals/build.mdx @@ -2,42 +2,39 @@ title: 'build' --- -# BUILD files -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} -Methods available in BUILD files. See also the Build Encyclopedia for extra [functions](/reference/be/functions) and build rules, which can also be used in BUILD files. +Methods available in BUILD files. See also the Build Encyclopedia for extra [functions](./reference/be/functions) and build rules, which can also be used in BUILD files. ## Members -- [depset](#depset) -- [existing_rule](#existing_rule) -- [existing_rules](#existing_rules) -- [exports_files](#exports_files) -- [glob](#glob) -- [module_name](#module_name) -- [module_version](#module_version) -- [package](#package) -- [package_default_visibility](#package_default_visibility) -- [package_group](#package_group) -- [package_name](#package_name) -- [package_relative_label](#package_relative_label) -- [repo_name](#repo_name) -- [repository_name](#repository_name) -- [select](#select) -- [subpackages](#subpackages) +* [depset](#depset) +* [existing\_rule](#existing_rule) +* [existing\_rules](#existing_rules) +* [exports\_files](#exports_files) +* [glob](#glob) +* [module\_name](#module_name) +* [module\_version](#module_version) +* [package](#package) +* [package\_default\_visibility](#package_default_visibility) +* [package\_group](#package_group) +* [package\_name](#package_name) +* [package\_relative\_label](#package_relative_label) +* [repo\_name](#repo_name) +* [repository\_name](#repository_name) +* [select](#select) +* [subpackages](#subpackages) ## depset -``` rule-signature +``` depset depset(direct=None, order="default", *, transitive=None) ``` -Creates a [depset](../builtins/depset.html). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. +Creates a [depset](../builtins/depset.mdx). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression [`type(x)`](../globals/all#type). -Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see [Issue 10313](https://github.com/bazelbuild/bazel/issues/10313). +Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible\_always\_check\_depset\_elements flag to enable consistent checking; this will be the default behavior in future releases; see [Issue 10313](https://github.com/bazelbuild/bazel/issues/10313). In addition, elements must currently be immutable, though this restriction will be relaxed in future. @@ -45,38 +42,15 @@ The order of the created depset should be *compatible* with the order of its `tr ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="depset.direct"><code>direct</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; -default is <code>None</code><br /> -A list of <em>direct</em> elements of a depset.</td> -</tr> -<tr> -<td id="depset.order"><code>order</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>"default"</code><br /> -The traversal strategy for the new depset. See <a href="../builtins/depset.html">here</a> for the possible values.</td> -</tr> -<tr> -<td id="depset.transitive"><code>transitive</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/depset.html" class="anchor">depset</a>s; or <code>None</code>; -default is <code>None</code><br /> -A list of depsets whose elements will become indirect elements of the depset.</td> -</tr> -</tbody> -</table> - -## existing_rule - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `direct` | [sequence](../core/list.mdx); or `None`; default is `None` A list of *direct* elements of a depset. | +| `order` | [string](../core/string.mdx); default is `"default"` The traversal strategy for the new depset. See [here](../builtins/depset.mdx) for the possible values. | +| `transitive` | [sequence](../core/list.mdx) of [depset](../builtins/depset.mdx)s; or `None`; default is `None` A list of depsets whose elements will become indirect elements of the depset. | + +## existing\_rule + +``` unknown existing_rule(name) ``` @@ -88,36 +62,23 @@ The result contains an entry for each attribute, with the exception of private o The values of the result represent attribute values as follows: -- Attributes of type str, int, and bool are represented as is. -- Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. -- Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. -- `select` values are returned with their contents transformed as described above. -- Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). +* Attributes of type str, int, and bool are represented as is. +* Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. +* Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. +* `select` values are returned with their contents transformed as described above. +* Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by `ctx.attr.foo`. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="existing_rule.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the target.</td> -</tr> -</tbody> -</table> - -## existing_rules - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required The name of the target. | + +## existing\_rules + +``` unknown existing_rules() ``` @@ -127,9 +88,9 @@ Here, an *immutable dict-like object* means a deeply immutable object `x` suppor If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. -## exports_files +## exports\_files -``` rule-signature +``` None exports_files(srcs, visibility=None, licenses=None) ``` @@ -137,96 +98,46 @@ Specifies a list of files belonging to this package that are exported to other p ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="exports_files.srcs"><code>srcs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The list of files to export.</td> -</tr> -<tr> -<td id="exports_files.visibility"><code>visibility</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; -default is <code>None</code><br /> -A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package.</td> -</tr> -<tr> -<td id="exports_files.licenses"><code>licenses</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Licenses to be specified.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `srcs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The list of files to export. | +| `visibility` | [sequence](../core/list.mdx); or `None`; default is `None` A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. | +| `licenses` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Licenses to be specified. | ## glob -``` rule-signature +``` sequence glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound) ``` Glob returns a new, mutable, sorted list of every file in the current package that: -- Matches at least one pattern in `include`. -- Does not match any of the patterns in `exclude` (default `[]`). +* Matches at least one pattern in `include`. +* Does not match any of the patterns in `exclude` (default `[]`). If the `exclude_directories` argument is enabled (set to `1`), files of type directory will be omitted from the results (default `1`). ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="glob.include"><code>include</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -The list of glob patterns to include.</td> -</tr> -<tr> -<td id="glob.exclude"><code>exclude</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -The list of glob patterns to exclude.</td> -</tr> -<tr> -<td id="glob.exclude_directories"><code>exclude_directories</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>1</code><br /> -A flag whether to exclude directories or not.</td> -</tr> -<tr> -<td id="glob.allow_empty"><code>allow_empty</code></td> -<td>default is <code>unbound</code><br /> -Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded).</td> -</tr> -</tbody> -</table> - -## module_name - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `include` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to include. | +| `exclude` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to exclude. | +| `exclude_directories` | [int](../core/int.mdx); default is `1` A flag whether to exclude directories or not. | +| `allow_empty` | default is `unbound` Whether we allow glob patterns to match nothing. If `allow\_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). | + +## module\_name + +``` string module_name() ``` The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the `module.name` field seen in `module_ctx.modules`. May return `None`. -## module_version +## module\_version -``` rule-signature +``` string module_version() ``` @@ -235,7 +146,7 @@ May return `None`. ## package -``` rule-signature +``` unknown package(**kwargs) ``` @@ -243,33 +154,21 @@ Declares metadata that applies to every rule in the package. It must be called a ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="package.kwargs"><code>kwargs</code></td> -<td>required<br /> -See the <a href="/reference/be/functions#package"><code>package()</code></a> function in the Build Encyclopedia for applicable arguments.</td> -</tr> -</tbody> -</table> - -## package_default_visibility - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `kwargs` | required See the [`package()`](./reference/be/functions#package) function in the Build Encyclopedia for applicable arguments. | + +## package\_default\_visibility + +``` List package_default_visibility() ``` Returns the default visibility of the package being evaluated. This is the value of the `default_visibility` parameter of `package()`, extended to include the package itself. -## package_group +## package\_group -``` rule-signature +``` None package_group(*, name, packages=[], includes=[]) ``` @@ -277,50 +176,27 @@ This function defines a set of packages and assigns a label to the group. The la ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="package_group.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The unique name for this rule.</td> -</tr> -<tr> -<td id="package_group.packages"><code>packages</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A complete enumeration of packages in this group.</td> -</tr> -<tr> -<td id="package_group.includes"><code>includes</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Other package groups that are included in this one.</td> -</tr> -</tbody> -</table> - -## package_name - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required The unique name for this rule. | +| `packages` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A complete enumeration of packages in this group. | +| `includes` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Other package groups that are included in this one. | + +## package\_name + +``` string package_name() ``` The name of the package being evaluated, without the repository name. For example, in the BUILD file `some/package/BUILD`, its value will be `some/package`. If the BUILD file calls a function defined in a .bzl file, `package_name()` will match the caller BUILD file package. The value will always be an empty string for the root package. -## package_relative_label +## package\_relative\_label -``` rule-signature +``` Label package_relative_label(input) ``` -Converts the input string into a [Label](../builtins/Label.html) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. +Converts the input string into a [Label](../builtins/Label.mdx) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. @@ -330,110 +206,56 @@ The result of this function is the same `Label` value as would be produced by pa ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="package_relative_label.input"><code>input</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; -required<br /> -The input label string or Label object. If a Label object is passed, it's returned as is.</td> -</tr> -</tbody> -</table> - -## repo_name - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `input` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); required The input label string or Label object. If a Label object is passed, it's returned as is. | + +## repo\_name + +``` string repo_name() ``` The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. -## repository_name +## repository\_name -``` rule-signature +``` string repository_name() ``` -**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` +**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` **Deprecated.** Prefer to use [`repo_name`](#repo_name) instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise. The canonical name of the repository containing the package currently being evaluated, with a single at-sign (`@`) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza `local_repository(name='local', path=...)` it will be set to `@local`. In packages in the main repository, it will be set to `@`. ## select -``` rule-signature +``` unknown select(x, no_match_error='') ``` -`select()` is the helper function that makes a rule attribute [configurable](/reference/be/common-definitions#configurable-attributes). See [build encyclopedia](/reference/be/functions#select) for details. +`select()` is the helper function that makes a rule attribute [configurable](./reference/be/common-definitions#configurable-attributes). See [build encyclopedia](./reference/be/functions#select) for details. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="select.x"><code>x</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -required<br /> -A dict that maps configuration conditions to values. Each key is a <a href="../builtins/Label.html">Label</a> or a label string that identifies a config_setting or constraint_value instance. See the <a href="https://bazel.build/extending/legacy-macros#label-resolution">documentation on macros</a> for when to use a Label instead of a string. If <code>--incompatible_resolve_select_keys_eagerly</code> is enabled, the keys are resolved to <code>Label</code> objects relative to the package of the file that contains this call to <code>select</code>.</td> -</tr> -<tr> -<td id="select.no_match_error"><code>no_match_error</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Optional custom error to report if no condition matches.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | [dict](../core/dict.mdx); required | +| `no_match_error` | [string](../core/string.mdx); default is `''` Optional custom error to report if no condition matches. | ## subpackages -``` rule-signature +``` sequence subpackages(*, include, exclude=[], allow_empty=False) ``` -Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel_skylib.subpackages module rather than calling this function directly. +Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel\_skylib.subpackages module rather than calling this function directly. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="subpackages.include"><code>include</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The list of glob patterns to include in subpackages scan.</td> -</tr> -<tr> -<td id="subpackages.exclude"><code>exclude</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -The list of glob patterns to exclude from subpackages scan.</td> -</tr> -<tr> -<td id="subpackages.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `include` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The list of glob patterns to include in subpackages scan. | +| `exclude` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to exclude from subpackages scan. | +| `allow_empty` | [bool](../core/bool.mdx); default is `False` Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. | \ No newline at end of file diff --git a/rules/lib/globals/bzl.mdx b/rules/lib/globals/bzl.mdx index 9ad26a5..c98ebee 100644 --- a/rules/lib/globals/bzl.mdx +++ b/rules/lib/globals/bzl.mdx @@ -2,197 +2,77 @@ title: 'bzl' --- -# .bzl files -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} Global methods available in all .bzl files. ## Members -- [analysis_test_transition](#analysis_test_transition) -- [aspect](#aspect) -- [configuration_field](#configuration_field) -- [depset](#depset) -- [exec_group](#exec_group) -- [exec_transition](#exec_transition) -- [macro](#macro) -- [materializer_rule](#materializer_rule) -- [module_extension](#module_extension) -- [provider](#provider) -- [repository_rule](#repository_rule) -- [rule](#rule) -- [select](#select) -- [subrule](#subrule) -- [tag_class](#tag_class) -- [visibility](#visibility) - -## analysis_test_transition - -``` rule-signature +* [analysis\_test\_transition](#analysis_test_transition) +* [aspect](#aspect) +* [configuration\_field](#configuration_field) +* [depset](#depset) +* [exec\_group](#exec_group) +* [exec\_transition](#exec_transition) +* [macro](#macro) +* [materializer\_rule](#materializer_rule) +* [module\_extension](#module_extension) +* [provider](#provider) +* [repository\_rule](#repository_rule) +* [rule](#rule) +* [select](#select) +* [subrule](#subrule) +* [tag\_class](#tag_class) +* [visibility](#visibility) + +## analysis\_test\_transition + +``` transition analysis_test_transition(*, settings) ``` -Creates a configuration transition to be applied on an analysis-test rule's dependencies. This transition may only be applied on attributes of rules with `analysis_test = True`. Such rules are restricted in capabilities (for example, the size of their dependency tree is limited), so transitions created using this function are limited in potential scope as compared to transitions created using [`transition()`](../builtins/transition.html). +Creates a configuration transition to be applied on an analysis-test rule's dependencies. This transition may only be applied on attributes of rules with `analysis_test = True`. Such rules are restricted in capabilities (for example, the size of their dependency tree is limited), so transitions created using this function are limited in potential scope as compared to transitions created using [`transition()`](../builtins/transition.mdx). This function is primarily designed to facilitate the [Analysis Test Framework](https://bazel.build/rules/testing) core library. See its documentation (or its implementation) for best practices. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="analysis_test_transition.settings"><code>settings</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -required<br /> -A dictionary containing information about configuration settings which should be set by this configuration transition. Keys are build setting labels and values are their new post-transition values. All other settings are unchanged. Use this to declare specific configuration settings that an analysis test requires to be set in order to pass.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `settings` | [dict](../core/dict.mdx); required A dictionary containing information about configuration settings which should be set by this configuration transition. Keys are build setting labels and values are their new post-transition values. All other settings are unchanged. Use this to declare specific configuration settings that an analysis test requires to be set in order to pass. | ## aspect -``` rule-signature -Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], propagation_predicate=None, fragments=[], host_fragments=[], toolchains=[], doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[]) +``` +Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs=\{\}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], propagation_predicate=None, fragments=[], host_fragments=[], toolchains=[], doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[]) ``` Creates a new aspect. The result of this function must be stored in a global value. Please see the [introduction to Aspects](https://bazel.build/extending/aspects) for more details. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="aspect.implementation"><code>implementation</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -required<br /> -A Starlark function that implements this aspect, with exactly two parameters: <a href="../builtins/Target.html">Target</a> (the target to which the aspect is applied) and <a href="../builtins/ctx.html">ctx</a> (the rule context which the target is created from). Attributes of the target are available via the <code>ctx.rule</code> field. This function is evaluated during the analysis phase for each application of an aspect to a target.</td> -</tr> -<tr> -<td id="aspect.attr_aspects"><code>attr_aspects</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/function.html" class="anchor">function</a>; -default is <code>[]</code><br /> -Accepts a list of attribute names or [Experimental] a function that returns the list of attribute names. The aspect propagates along dependencies specified in the attributes of a target with these names. Common values here include <code>deps</code> and <code>exports</code>. The list can also contain a single string <code>"*"</code> to propagate along all dependencies of a target.</td> -</tr> -<tr> -<td id="aspect.toolchains_aspects"><code>toolchains_aspects</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../core/function.html" class="anchor">function</a>; -default is <code>[]</code><br /> -Accepts a list of toolchain types or [Experimental] a function that returns the list of toolchain types. The aspect propagates to target toolchains which match these toolchain types.</td> -</tr> -<tr> -<td id="aspect.attrs"><code>attrs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary declaring all the attributes of the aspect. It maps from an attribute name to an attribute object, like <code>attr.label</code> or <code>attr.string</code> (see <a href="../toplevel/attr.html"><code>attr</code></a> module). Aspect attributes are available to implementation function as fields of <code>ctx</code> parameter. -<p>Implicit attributes starting with <code>_</code> must have default values, and have type <code>label</code> or <code>label_list</code>.</p> -<p>Explicit attributes must have type <code>string</code>, and must use the <code>values</code> restriction. Explicit attributes restrict the aspect to only be used with rules that have attributes of the same name, type, and valid values according to the restriction.</p> -<p>Declared attributes will convert <code>None</code> to the default value.</p></td> -</tr> -<tr> -<td id="aspect.required_providers"><code>required_providers</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its required providers. The value must be a list containing either individual providers or lists of providers but not both. For example, <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code> is a valid value while <code>[FooInfo, BarInfo, [BazInfo, QuxInfo]]</code> is not valid. -<p>An unnested list of providers will automatically be converted to a list containing one list of providers. That is, <code>[FooInfo, BarInfo]</code> will automatically be converted to <code>[[FooInfo, BarInfo]]</code>.</p> -<p>To make some rule (e.g. <code>some_rule</code>) targets visible to an aspect, <code>some_rule</code> must advertise all providers from at least one of the required providers lists. For example, if the <code>required_providers</code> of an aspect are <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code>, this aspect can see <code>some_rule</code> targets if and only if <code>some_rule</code> provides <code>FooInfo</code>, <em>or</em> <code>BarInfo</code>, <em>or</em> both <code>BazInfo</code> <em>and</em> <code>QuxInfo</code>.</p></td> -</tr> -<tr> -<td id="aspect.required_aspect_providers"><code>required_aspect_providers</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -This attribute allows this aspect to inspect other aspects. The value must be a list containing either individual providers or lists of providers but not both. For example, <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code> is a valid value while <code>[FooInfo, BarInfo, [BazInfo, QuxInfo]]</code> is not valid. -<p>An unnested list of providers will automatically be converted to a list containing one list of providers. That is, <code>[FooInfo, BarInfo]</code> will automatically be converted to <code>[[FooInfo, BarInfo]]</code>.</p> -<p>To make another aspect (e.g. <code>other_aspect</code>) visible to this aspect, <code>other_aspect</code> must provide all providers from at least one of the lists. In the example of <code>[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]</code>, this aspect can see <code>other_aspect</code> if and only if <code>other_aspect</code> provides <code>FooInfo</code>, <em>or</em> <code>BarInfo</code>, <em>or</em> both <code>BazInfo</code> <em>and</em> <code>QuxInfo</code>.</p></td> -</tr> -<tr> -<td id="aspect.provides"><code>provides</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -A list of providers that the implementation function must return. -<p>It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.</p> -<p>Each element of the list is an <code>*Info</code> object returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a>. When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The <a href="../globals/bzl.html#aspect.required_providers"><code>required_providers</code></a> field of an <a href="../globals/bzl.html#aspect">aspect</a> does, however, require that providers are specified here.</p></td> -</tr> -<tr> -<td id="aspect.requires"><code>requires</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; -default is <code>[]</code><br /> -List of aspects required to be propagated before this aspect.</td> -</tr> -<tr> -<td id="aspect.propagation_predicate"><code>propagation_predicate</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; or <code>None</code>; -default is <code>None</code><br /> -Experimental: a function that returns a boolean value indicating whether the aspect should be propagated to a target.</td> -</tr> -<tr> -<td id="aspect.fragments"><code>fragments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -List of names of configuration fragments that the aspect requires in target configuration.</td> -</tr> -<tr> -<td id="aspect.host_fragments"><code>host_fragments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -List of names of configuration fragments that the aspect requires in host configuration.</td> -</tr> -<tr> -<td id="aspect.toolchains"><code>toolchains</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -If set, the set of toolchains this aspect requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the aspect implementation via <code>ctx.toolchain</code>.</td> -</tr> -<tr> -<td id="aspect.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the aspect that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="aspect.apply_to_generating_rules"><code>apply_to_generating_rules</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the aspect will, when applied to an output file, instead apply to the output file's generating rule. -<p>For example, suppose an aspect propagates transitively through attribute `deps` and it is applied to target `alpha`. Suppose `alpha` has `deps = [':beta_output']`, where `beta_output` is a declared output of a target `beta`. Suppose `beta` has a target `charlie` as one of its `deps`. If `apply_to_generating_rules=True` for the aspect, then the aspect will propagate through `alpha`, `beta`, and `charlie`. If False, then the aspect will propagate only to `alpha`.</p> -<p>False by default.</p></td> -</tr> -<tr> -<td id="aspect.exec_compatible_with"><code>exec_compatible_with</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A list of constraints on the execution platform that apply to all instances of this aspect.</td> -</tr> -<tr> -<td id="aspect.exec_groups"><code>exec_groups</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Dict of execution group name (string) to <a href="../globals/bzl.html#exec_group"><code>exec_group</code>s</a>. If set, allows aspects to run actions on multiple execution platforms within a single instance. See <a href="/reference/exec-groups">execution groups documentation</a> for more info.</td> -</tr> -<tr> -<td id="aspect.subrules"><code>subrules</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Subrule.html" class="anchor">Subrule</a>s; -default is <code>[]</code><br /> -Experimental: list of subrules used by this aspect.</td> -</tr> -</tbody> -</table> - -## configuration_field - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `implementation` | [function](../core/function.mdx); required A Starlark function that implements this aspect, with exactly two parameters: [Target](../builtins/Target.mdx) (the target to which the aspect is applied) and [ctx](../builtins/ctx.mdx) (the rule context which the target is created from). Attributes of the target are available via the `ctx.rule` field. This function is evaluated during the analysis phase for each application of an aspect to a target. | +| `attr_aspects` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or [function](../core/function.mdx); default is `[]` Accepts a list of attribute names or [Experimental] a function that returns the list of attribute names. The aspect propagates along dependencies specified in the attributes of a target with these names. Common values here include `deps` and `exports`. The list can also contain a single string `"*"` to propagate along all dependencies of a target. | +| `toolchains_aspects` | [sequence](../core/list.mdx); or [function](../core/function.mdx); default is `[]` Accepts a list of toolchain types or [Experimental] a function that returns the list of toolchain types. The aspect propagates to target toolchains which match these toolchain types. | +| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary declaring all the attributes of the aspect. It maps from an attribute name to an attribute object, like `attr.label` or `attr.string` (see [`attr`](../toplevel/attr.mdx) module). Aspect attributes are available to implementation function as fields of `ctx` parameter. Implicit attributes starting with `_` must have default values, and have type `label` or `label_list`. Explicit attributes must have type `string`, and must use the `values` restriction. Explicit attributes restrict the aspect to only be used with rules that have attributes of the same name, type, and valid values according to the restriction. Declared attributes will convert `None` to the default value. | +| `required_providers` | [sequence](../core/list.mdx); default is `[]` This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its required providers. The value must be a list containing either individual providers or lists of providers but not both. For example, `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]` is a valid value while `[FooInfo, BarInfo, [BazInfo, QuxInfo]]` is not valid. An unnested list of providers will automatically be converted to a list containing one list of providers. That is, `[FooInfo, BarInfo]` will automatically be converted to `[[FooInfo, BarInfo]]`. To make some rule (e.g. `some_rule`) targets visible to an aspect, `some_rule` must advertise all providers from at least one of the required providers lists. For example, if the `required_providers` of an aspect are `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]`, this aspect can see `some_rule` targets if and only if `some_rule` provides `FooInfo`, *or* `BarInfo`, *or* both `BazInfo` *and* `QuxInfo`. | +| `required_aspect_providers` | [sequence](../core/list.mdx); default is `[]` This attribute allows this aspect to inspect other aspects. The value must be a list containing either individual providers or lists of providers but not both. For example, `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]` is a valid value while `[FooInfo, BarInfo, [BazInfo, QuxInfo]]` is not valid. An unnested list of providers will automatically be converted to a list containing one list of providers. That is, `[FooInfo, BarInfo]` will automatically be converted to `[[FooInfo, BarInfo]]`. To make another aspect (e.g. `other_aspect`) visible to this aspect, `other_aspect` must provide all providers from at least one of the lists. In the example of `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]`, this aspect can see `other_aspect` if and only if `other_aspect` provides `FooInfo`, *or* `BarInfo`, *or* both `BazInfo` *and* `QuxInfo`. | +| `provides` | [sequence](../core/list.mdx); default is `[]` A list of providers that the implementation function must return. It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here. Each element of the list is an `*Info` object returned by [`provider()`](../globals/bzl.html#provider). When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The [`required_providers`](../globals/bzl.html#aspect.required_providers) field of an [aspect](../globals/bzl.html#aspect) does, however, require that providers are specified here. | +| `requires` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` List of aspects required to be propagated before this aspect. | +| `propagation_predicate` | [function](../core/function.mdx); or `None`; default is `None` Experimental: a function that returns a boolean value indicating whether the aspect should be propagated to a target. | +| `fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the aspect requires in target configuration. | +| `host_fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the aspect requires in host configuration. | +| `toolchains` | [sequence](../core/list.mdx); default is `[]` If set, the set of toolchains this aspect requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the aspect implementation via `ctx.toolchain`. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the aspect that can be extracted by documentation generating tools. | +| `apply_to_generating_rules` | [bool](../core/bool.mdx); default is `False` If true, the aspect will, when applied to an output file, instead apply to the output file's generating rule. For example, suppose an aspect propagates transitively through attribute `deps` and it is applied to target `alpha`. Suppose `alpha` has `deps = [':beta\_output']`, where `beta\_output` is a declared output of a target `beta`. Suppose `beta` has a target `charlie` as one of its `deps`. If `apply\_to\_generating\_rules=True` for the aspect, then the aspect will propagate through `alpha`, `beta`, and `charlie`. If False, then the aspect will propagate only to `alpha`. False by default. | +| `exec_compatible_with` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A list of constraints on the execution platform that apply to all instances of this aspect. | +| `exec_groups` | [dict](../core/dict.mdx); or `None`; default is `None` Dict of execution group name (string) to [`exec_group`s](../globals/bzl.html#exec_group). If set, allows aspects to run actions on multiple execution platforms within a single instance. See [execution groups documentation](./reference/exec-groups) for more info. | +| `subrules` | [sequence](../core/list.mdx) of [Subrule](../builtins/Subrule.mdx)s; default is `[]` Experimental: list of subrules used by this aspect. | + +## configuration\_field + +``` LateBoundDefault configuration_field(fragment, name) ``` @@ -200,15 +80,15 @@ References a late-bound default value for an attribute of type [label](../toplev Example usage: -Defining a rule attribute: +Defining a rule attribute: -``` python +``` '_foo': attr.label(default=configuration_field(fragment='java', name='toolchain')) ``` -Accessing in rule implementation: +Accessing in rule implementation: -``` python +``` def _rule_impl(ctx): foo_info = ctx.attr._foo ... @@ -216,40 +96,22 @@ Accessing in rule implementation: ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="configuration_field.fragment"><code>fragment</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of a configuration fragment which contains the late-bound value.</td> -</tr> -<tr> -<td id="configuration_field.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the value to obtain from the configuration fragment.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `fragment` | [string](../core/string.mdx); required | +| `name` | [string](../core/string.mdx); required | ## depset -``` rule-signature +``` depset depset(direct=None, order="default", *, transitive=None) ``` -Creates a [depset](../builtins/depset.html). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. +Creates a [depset](../builtins/depset.mdx). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression [`type(x)`](../globals/all#type). -Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see [Issue 10313](https://github.com/bazelbuild/bazel/issues/10313). +Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible\_always\_check\_depset\_elements flag to enable consistent checking; this will be the default behavior in future releases; see [Issue 10313](https://github.com/bazelbuild/bazel/issues/10313). In addition, elements must currently be immutable, though this restriction will be relaxed in future. @@ -257,111 +119,47 @@ The order of the created depset should be *compatible* with the order of its `tr ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="depset.direct"><code>direct</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; -default is <code>None</code><br /> -A list of <em>direct</em> elements of a depset.</td> -</tr> -<tr> -<td id="depset.order"><code>order</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>"default"</code><br /> -The traversal strategy for the new depset. See <a href="../builtins/depset.html">here</a> for the possible values.</td> -</tr> -<tr> -<td id="depset.transitive"><code>transitive</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/depset.html" class="anchor">depset</a>s; or <code>None</code>; -default is <code>None</code><br /> -A list of depsets whose elements will become indirect elements of the depset.</td> -</tr> -</tbody> -</table> - -## exec_group - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `direct` | [sequence](../core/list.mdx); or `None`; default is `None` A list of *direct* elements of a depset. | +| `order` | [string](../core/string.mdx); default is `"default"` The traversal strategy for the new depset. See [here](../builtins/depset.mdx) for the possible values. | +| `transitive` | [sequence](../core/list.mdx) of [depset](../builtins/depset.mdx)s; or `None`; default is `None` A list of depsets whose elements will become indirect elements of the depset. | + +## exec\_group + +``` exec_group exec_group(*, toolchains=[], exec_compatible_with=[]) ``` -Creates an [execution group](/reference/exec-groups) which can be used to create actions for a specific execution platform during rule implementation. +Creates an [execution group](./reference/exec-groups) which can be used to create actions for a specific execution platform during rule implementation. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="exec_group.toolchains"><code>toolchains</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -The set of toolchains this execution group requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination.</td> -</tr> -<tr> -<td id="exec_group.exec_compatible_with"><code>exec_compatible_with</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A list of constraints on the execution platform.</td> -</tr> -</tbody> -</table> - -## exec_transition - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `toolchains` | [sequence](../core/list.mdx); default is `[]` The set of toolchains this execution group requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. | +| `exec_compatible_with` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A list of constraints on the execution platform. | + +## exec\_transition + +``` transition exec_transition(*, implementation, inputs, outputs) ``` -A specialized version of [`transition()`](../builtins/transition.html) used to define the exec transition. See its documentation (or its implementation) for best practices. Only usable from the Bazel builtins. +A specialized version of [`transition()`](../builtins/transition.mdx) used to define the exec transition. See its documentation (or its implementation) for best practices. Only usable from the Bazel builtins. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="exec_transition.implementation"><code>implementation</code></td> -<td>callable; -required<br /> -</td> -</tr> -<tr> -<td id="exec_transition.inputs"><code>inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -</td> -</tr> -<tr> -<td id="exec_transition.outputs"><code>outputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `implementation` | callable; required | +| `inputs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required | +| `outputs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required | ## macro -``` rule-signature -macro macro(*, implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None) +``` +macro macro(*, implementation, attrs=\{\}, inherit_attrs=None, finalizer=False, doc=None) ``` Defines a symbolic macro, which may be called in `BUILD` files or macros (legacy or @@ -370,174 +168,23 @@ symbolic) to define targets – possibly multiple ones. The value returned by `macro(...)` must be assigned to a global variable in a .bzl file; the name of the global variable will be the macro symbol's name. -See [Macros](/extending/macros) for a comprehensive guide on how to use symbolic +See [Macros](./extending/macros) for a comprehensive guide on how to use symbolic macros. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="macro.implementation"><code>implementation</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -required<br /> -The Starlark function implementing this macro. The values of the macro's attributes are passed to -the implementation function as keyword arguments. The implementation function must have at least two -named parameters, <code>name</code> and <code>visibility</code>, and if the macro inherits -attributes (see <code>inherit_attrs</code> below), it must have a <code>**kwargs</code> residual -keyword parameter. -<p>By convention, the implementation function should have a named parameter for any attribute that -the macro needs to examine, modify, or pass to non-"main" targets, while the "bulk" inherited -attributes which will be passed to the "main" target unchanged are passed as <code>**kwargs</code>.</p> -<p>The implementation function must not return a value. Instead, the implementation function -<em>declares targets</em> by calling rule or macro symbols.</p> -<p>The name of any target or inner symbolic macro declared by a symbolic macro (including by any -Starlark function that the macro's implementation function transitively calls) must either equal -<code>name</code> (this is referred to as the "main" target) or start with <code>name</code>, -followed by a separator chracter (<code>"_"</code>, <code>"-"</code>, or <code>"."</code>) and a -string suffix. (Targets violating this naming scheme are allowed to be declared, but cannot be -built, configured, or depended upon.)</p> -<p>By default, targets declared by a symbolic macro (including by any Starlark function that the -macro's implementation function transitively calls) are visible only in the package containing the -.bzl file defining the macro. To declare targets visible externally, <em>including to the caller of -the symbolic macro</em>, the implementation function must set <code>visibility</code> appropriately -– typically, by passing <code>visibility = visibility</code> to the rule or macro symbol being -called.</p> -<p>The following APIs are unavailable within a macro implementation function and any Starlark -function it transitively calls:</p> -<ul> -<li><a href="/reference/be/functions#package"><code>package()</code>, <code>licenses()</code></a></li> -<li><code>environment_group()</code></li> -<li><a href="../toplevel/native#glob"><code>native.glob()</code></a> – instead, you may pass -a glob into the macro via a label list attribute</li> -<li><a href="../toplevel/native#subpackages"><code>native.subpackages()</code></a></li> -<li>(allowed in rule finalizers only, see <code>finalizer</code> below) -<a href="../toplevel/native#existing_rules"><code>native.existing_rules()</code></a>, -<a href="../toplevel/native#existing_rule"><code>native.existing_rule()</code></a></li> -<li>(for <code>WORKSPACE</code> threads) -<a href="../globals/workspace#workspace"><code>workspace()</code></a>, -<a href="../globals/workspace#register_toolchains"><code>register_toolchains()</code></a>, -<a href="../globals/workspace#register_execution_platforms%3E%3Ccode%3Eregister_execution_platforms()%3C/code%3E%3C/a%3E,%0A%20%20%20%20%3Ca%20href=" data-..="" data-globals="" data-workspace#bind"=""><code>bind()</code></a>, repository rule instantiation</li> -</ul></td> -</tr> -<tr> -<td id="macro.attrs"><code>attrs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary of the attributes this macro supports, analogous to -<a href="#rule.attrs">rule.attrs</a>. Keys are attribute names, and values are either attribute -objects like <code>attr.label_list(...)</code> (see the <a href="../toplevel/attr.html">attr</a> -module), or <code>None</code>. A <code>None</code> entry means that the macro does not have an -attribute by that name, even if it would have otherwise inherited one via <code>inherit_attrs</code> -(see below). -<p>The special <code>name</code> attribute is predeclared and must not be included in the -dictionary. The <code>visibility</code> attribute name is reserved and must not be included in the -dictionary.</p> -<p>Attributes whose names start with <code>_</code> are private -- they cannot be passed at the call -site of the rule. Such attributes can be assigned a default value (as in -<code>attr.label(default="//pkg:foo")</code>) to create an implicit dependency on a label.</p> -<p>To limit memory usage, there is a cap on the number of attributes that may be declared.</p></td> -</tr> -<tr> -<td id="macro.inherit_attrs"><code>inherit_attrs</code></td> -<td><a href="../builtins/rule.html" class="anchor">rule</a>; or <a href="../builtins/macro.html" class="anchor">macro</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A rule symbol, macro symbol, or the name of a built-in common attribute list (see below) from which -the macro should inherit attributes. -<p>If <code>inherit_attrs</code> is set to the string <code>"common"</code>, the macro will inherit -<a href="/reference/be/common-definitions#common-attributes">common rule attribute definitions</a> -used by all Starlark rules.</p> -<p>Note that if the return value of <code>rule()</code> or <code>macro()</code> was not assigned to -a global variable in a .bzl file, then such a value has not been registered as a rule or macro -symbol, and therefore cannot be used for <code>inherit_attrs</code>.</p> -<p>The inheritance mechanism works as follows:</p> -<ol> -<li>The special <code>name</code> and <code>visibility</code> attributes are never inherited;</li> -<li>Hidden attributes (ones whose name starts with <code>"_"</code>) are never inherited;</li> -<li>Attributes whose names are already defined in the <code>attrs</code> dictionary are never -inherited (the entry in <code>attrs</code> takes precedence; note that an entry may be set to -<code>None</code> to ensure that no attribute by that name gets defined on the macro);</li> -<li>All other attributes are inherited from the rule or macro and effectively merged into the -<code>attrs</code> dict.</li> -</ol> -<p>When a non-mandatory attribute is inherited, the default value of the attribute is overridden -to be <code>None</code>, regardless of what it was specified in the original rule or macro. This -ensures that when the macro forwards the attribute's value to an instance of the wrapped rule or -macro – such as by passing in the unmodified <code>**kwargs</code> – a value that was -absent from the outer macro's call will also be absent in the inner rule or macro's call (since -passing <code>None</code> to an attribute is treated the same as omitting the attribute). -This is important because omitting an attribute has subtly different semantics from passing -its apparent default value. In particular, omitted attributes are not shown in some <code>bazel query</code> output formats, and computed defaults only execute when the value is omitted. If the -macro needs to examine or modify an inherited attribute – for example, to add a value to an -inherited <code>tags</code> attribute – you must make sure to handle the <code>None</code> -case in the macro's implementation function.</p> -<p>For example, the following macro inherits all attributes from <code>native.cc_library</code>, -except for <code>cxxopts</code> (which is removed from the attribute list) and <code>copts</code> -(which is given a new definition). It also takes care to checks for the default <code>None</code> -value of the inherited <code>tags</code> attribute before appending an additional tag.</p> -<pre class="language-python"><code> -def _my_cc_library_impl(name, visibility, tags, **kwargs): - # Append a tag; tags attr was inherited from native.cc_library, and - # therefore is None unless explicitly set by the caller of my_cc_library() - my_tags = (tags or []) + ["my_custom_tag"] - native.cc_library( - name = name, - visibility = visibility, - tags = my_tags, - **kwargs - ) - my_cc_library = macro( - implementation = _my_cc_library_impl, - inherit_attrs = native.cc_library, - attrs = { - "cxxopts": None, - "copts": attr.string_list(default = ["-D_FOO"]), - }, -)</code></pre> -<p>If <code>inherit_attrs</code> is set, the macro's implementation function <em>must</em> have a -<code>**kwargs</code> residual keyword parameter.</p> -<p>By convention, a macro should pass inherited, non-overridden attributes unchanged to the "main" -rule or macro symbol which the macro is wrapping. Typically, most inherited attributes will not have -a parameter in the implementation function's parameter list, and will simply be passed via -<code>**kwargs</code>. It can be convenient for the implementation function to have explicit -parameters for some inherited attributes (most commonly, <code>tags</code> and -<code>testonly</code>) if the macro needs to pass those attributes to both "main" and non-"main" -targets – but if the macro also needs to examine or manipulate those attributes, you must take -care to handle the <code>None</code> default value of non-mandatory inherited attributes.</p></td> -</tr> -<tr> -<td id="macro.finalizer"><code>finalizer</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether this macro is a rule finalizer, which is a macro that, regardless of its position in a -<code>BUILD</code> file, is evaluated at the end of package loading, after all non-finalizer targets -have been defined. -<p>Unlike ordinary symbolic macros, rule finalizers may call -<a href="../toplevel/native#existing_rule"><code>native.existing_rule()</code></a> and -<a href="../toplevel/native#existing_rules"><code>native.existing_rules()</code></a> to query the -set of <em>non-finalizer</em> rule targets defined in the current package. Note that -<code>native.existing_rule()</code> and <code>native.existing_rules()</code> cannot access the -targets defined by any rule finalizer, including this one.</p></td> -</tr> -<tr> -<td id="macro.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the macro that can be extracted by documentation generating tools.</td> -</tr> -</tbody> -</table> - -## materializer_rule - -``` rule-signature -callable materializer_rule(*, implementation, attrs={}, doc=None) +| Parameter | Description | +| --- | --- | +| `implementation` | [function](../core/function.mdx); required The Starlark function implementing this macro. The values of the macro's attributes are passed to the implementation function as keyword arguments. The implementation function must have at least two named parameters, `name` and `visibility`, and if the macro inherits attributes (see `inherit_attrs` below), it must have a `**kwargs` residual keyword parameter. By convention, the implementation function should have a named parameter for any attribute that the macro needs to examine, modify, or pass to non-"main" targets, while the "bulk" inherited attributes which will be passed to the "main" target unchanged are passed as `**kwargs`. The implementation function must not return a value. Instead, the implementation function *declares targets* by calling rule or macro symbols. The name of any target or inner symbolic macro declared by a symbolic macro (including by any Starlark function that the macro's implementation function transitively calls) must either equal `name` (this is referred to as the "main" target) or start with `name`, followed by a separator chracter (`"_"`, `"-"`, or `"."`) and a string suffix. (Targets violating this naming scheme are allowed to be declared, but cannot be built, configured, or depended upon.) By default, targets declared by a symbolic macro (including by any Starlark function that the macro's implementation function transitively calls) are visible only in the package containing the .bzl file defining the macro. To declare targets visible externally, *including to the caller of the symbolic macro*, the implementation function must set `visibility` appropriately – typically, by passing `visibility = visibility` to the rule or macro symbol being called. The following APIs are unavailable within a macro implementation function and any Starlark function it transitively calls: * [`package()`, `licenses()`* `environment_group()`* [`native.glob()`](../toplevel/native#glob) – instead, you may pass a glob into the macro via a label list attribute* [`native.subpackages()`](../toplevel/native#subpackages)* (allowed in rule finalizers only, see `finalizer` below) [`native.existing_rules()`](../toplevel/native#existing_rules), [`native.existing_rule()`](../toplevel/native#existing_rule)* (for `WORKSPACE` threads) [`workspace()`](../globals/workspace#workspace), [`register_toolchains()`](../globals/workspace#register_toolchains), [`bind()`](../globals/workspace#register_execution_platforms](/reference/be/functions#package) | +| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary of the attributes this macro supports, analogous to [rule.attrs](#rule.attrs). Keys are attribute names, and values are either attribute objects like `attr.label_list(...)` (see the [attr](../toplevel/attr.mdx) module), or `None`. A `None` entry means that the macro does not have an attribute by that name, even if it would have otherwise inherited one via `inherit_attrs` (see below). The special `name` attribute is predeclared and must not be included in the dictionary. The `visibility` attribute name is reserved and must not be included in the dictionary. Attributes whose names start with `_` are private -- they cannot be passed at the call site of the rule. Such attributes can be assigned a default value (as in `attr.label(default="//pkg:foo")`) to create an implicit dependency on a label. To limit memory usage, there is a cap on the number of attributes that may be declared. | +| `inherit_attrs` | [rule](../builtins/rule.mdx); or [macro](../builtins/macro.mdx); or [string](../core/string.mdx); or `None`; default is `None` A rule symbol, macro symbol, or the name of a built-in common attribute list (see below) from which the macro should inherit attributes. If `inherit_attrs` is set to the string `"common"`, the macro will inherit [common rule attribute definitions](./reference/be/common-definitions#common-attributes) used by all Starlark rules. Note that if the return value of `rule()` or `macro()` was not assigned to a global variable in a .bzl file, then such a value has not been registered as a rule or macro symbol, and therefore cannot be used for `inherit_attrs`. The inheritance mechanism works as follows: 1. The special `name` and `visibility` attributes are never inherited;- Hidden attributes (ones whose name starts with `"_"`) are never inherited;- Attributes whose names are already defined in the `attrs` dictionary are never inherited (the entry in `attrs` takes precedence; note that an entry may be set to `None` to ensure that no attribute by that name gets defined on the macro);- All other attributes are inherited from the rule or macro and effectively merged into the `attrs` dict. When a non-mandatory attribute is inherited, the default value of the attribute is overridden to be `None`, regardless of what it was specified in the original rule or macro. This ensures that when the macro forwards the attribute's value to an instance of the wrapped rule or macro – such as by passing in the unmodified `**kwargs` – a value that was absent from the outer macro's call will also be absent in the inner rule or macro's call (since passing `None` to an attribute is treated the same as omitting the attribute). This is important because omitting an attribute has subtly different semantics from passing its apparent default value. In particular, omitted attributes are not shown in some `bazel query` output formats, and computed defaults only execute when the value is omitted. If the macro needs to examine or modify an inherited attribute – for example, to add a value to an inherited `tags` attribute – you must make sure to handle the `None` case in the macro's implementation function. For example, the following macro inherits all attributes from `native.cc_library`, except for `cxxopts` (which is removed from the attribute list) and `copts` (which is given a new definition). It also takes care to checks for the default `None` value of the inherited `tags` attribute before appending an additional tag. ``` def _my_cc_library_impl(name, visibility, tags, **kwargs): # Append a tag; tags attr was inherited from native.cc_library, and # therefore is None unless explicitly set by the caller of my_cc_library() my_tags = (tags or []) + ["my_custom_tag"] native.cc_library( name = name, visibility = visibility, tags = my_tags, **kwargs ) my_cc_library = macro( implementation = _my_cc_library_impl, inherit_attrs = native.cc_library, attrs = \{ "cxxopts": None, "copts": attr.string_list(default = ["-D_FOO"]), \}, ) ``` If `inherit_attrs` is set, the macro's implementation function *must* have a `**kwargs` residual keyword parameter. By convention, a macro should pass inherited, non-overridden attributes unchanged to the "main" rule or macro symbol which the macro is wrapping. Typically, most inherited attributes will not have a parameter in the implementation function's parameter list, and will simply be passed via `**kwargs`. It can be convenient for the implementation function to have explicit parameters for some inherited attributes (most commonly, `tags` and `testonly`) if the macro needs to pass those attributes to both "main" and non-"main" targets – but if the macro also needs to examine or manipulate those attributes, you must take care to handle the `None` default value of non-mandatory inherited attributes. | +| `finalizer` | [bool](../core/bool.mdx); default is `False` Whether this macro is a rule finalizer, which is a macro that, regardless of its position in a `BUILD` file, is evaluated at the end of package loading, after all non-finalizer targets have been defined. Unlike ordinary symbolic macros, rule finalizers may call [`native.existing_rule()`](../toplevel/native#existing_rule) and [`native.existing_rules()`](../toplevel/native#existing_rules) to query the set of *non-finalizer* rule targets defined in the current package. Note that `native.existing_rule()` and `native.existing_rules()` cannot access the targets defined by any rule finalizer, including this one. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the macro that can be extracted by documentation generating tools. | + +## materializer\_rule + +``` +callable materializer_rule(*, implementation, attrs=\{\}, doc=None) ``` Creates a new materializer rule, which can be called from a BUILD file or a macro to create materializer targets. @@ -546,103 +193,40 @@ Materializer targets are used to dynamically select dependencies at analysis tim ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="materializer_rule.implementation"><code>implementation</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -required<br /> -The Starlark function implementing this materializer rule. It must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. This function is called during the analysis phase for each instance of the rule. Materializer rules return exactly one and only one MaterializedDepsInfo provider which specifies the dependencies to materialize in place of any instance of this rule in the attributes of another target.</td> -</tr> -<tr> -<td id="materializer_rule.attrs"><code>attrs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see -<a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label. The attribute <code>name</code> is implicitly added and must not be specified. Attributes <code>visibility</code>, <code>deprecation</code>, <code>tags</code>, <code>testonly</code>, and <code>features</code> are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. -<p>Declared attributes will convert <code>None</code> to the default value.</p></td> -</tr> -<tr> -<td id="materializer_rule.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the rule that can be extracted by documentation generating tools.</td> -</tr> -</tbody> -</table> - -## module_extension - -``` rule-signature -unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False) +| Parameter | Description | +| --- | --- | +| `implementation` | [function](../core/function.mdx); required The Starlark function implementing this materializer rule. It must have exactly one parameter: [ctx](../builtins/ctx.mdx). This function is called during the analysis phase for each instance of the rule. Materializer rules return exactly one and only one MaterializedDepsInfo provider which specifies the dependencies to materialize in place of any instance of this rule in the attributes of another target. | +| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see [`attr`](../toplevel/attr.mdx) module). Attributes starting with `_` are private, and can be used to add an implicit dependency on a label. The attribute `name` is implicitly added and must not be specified. Attributes `visibility`, `deprecation`, `tags`, `testonly`, and `features` are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. Declared attributes will convert `None` to the default value. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the rule that can be extracted by documentation generating tools. | + +## module\_extension + +``` +unknown module_extension(implementation, *, tag_classes=\{\}, doc=None, environ=[], os_dependent=False, arch_dependent=False) ``` -Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with [`use_extension`](../globals/module.html#use_extension). +Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with `use_extension`. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="module_extension.implementation"><code>implementation</code></td> -<td>callable; -required<br /> -The function that implements this module extension. Must take a single parameter, <a href="../builtins/module_ctx.html"><code>module_ctx</code></a>. The function is called once at the beginning of a build to determine the set of available repos.</td> -</tr> -<tr> -<td id="module_extension.tag_classes"><code>tag_classes</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary to declare all the tag classes used by the extension. It maps from the name of the tag class to a <a href="../builtins/tag_class.html"><code>tag_class</code></a> object.</td> -</tr> -<tr> -<td id="module_extension.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the module extension that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="module_extension.environ"><code>environ</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated.</td> -</tr> -<tr> -<td id="module_extension.os_dependent"><code>os_dependent</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Indicates whether this extension is OS-dependent or not</td> -</tr> -<tr> -<td id="module_extension.arch_dependent"><code>arch_dependent</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Indicates whether this extension is architecture-dependent or not</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `implementation` | callable; required The function that implements this module extension. Must take a single parameter, `module_ctx`. The function is called once at the beginning of a build to determine the set of available repos. | +| `tag_classes` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the tag classes used by the extension. It maps from the name of the tag class to a `tag_class` object. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the module extension that can be extracted by documentation generating tools. | +| `environ` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated. | +| `os_dependent` | [bool](../core/bool.mdx); default is `False` Indicates whether this extension is OS-dependent or not | +| `arch_dependent` | [bool](../core/bool.mdx); default is `False` Indicates whether this extension is architecture-dependent or not | ## provider -``` rule-signature +``` unknown provider(doc=None, *, fields=None, init=None) ``` Defines a provider symbol. The resulting value of this function must be stored in a global value to be usable in a rule or aspect implementation. Providers can be instantiated by calling the resulting value as a function, or used directly as an index key for retrieving an instance of that provider from a target. Example: -``` python +``` MyInfo = provider() ... def _my_library_impl(ctx): @@ -655,76 +239,21 @@ def _my_library_impl(ctx): See [Rules (Providers)](https://bazel.build/extending/rules#providers) for a comprehensive guide on how to use providers. -Returns a [`Provider`](../builtins/Provider.html) callable value if `init` is not specified. +Returns a [`Provider`](../builtins/Provider.mdx) callable value if `init` is not specified. -If `init` is specified, returns a tuple of 2 elements: a [`Provider`](../builtins/Provider.html) callable value and a *raw constructor* callable value. See [Rules (Custom initialization of custom providers)](https://bazel.build/extending/rules#custom_initialization_of_providers) and the discussion of the `init` parameter below for details. +If `init` is specified, returns a tuple of 2 elements: a [`Provider`](../builtins/Provider.mdx) callable value and a *raw constructor* callable value. See [Rules (Custom initialization of custom providers)](https://bazel.build/extending/rules#custom_initialization_of_providers) and the discussion of the `init` parameter below for details. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="provider.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the provider that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="provider.fields"><code>fields</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -If specified, restricts the set of allowed fields.<br /> -Possible values are: -<ul> -<li><p>list of fields:<br /> -</p> -<pre class="language-python"><code>provider(fields = ['a', 'b'])</code></pre></li> -<li><p>dictionary field name -> documentation:<br /> -</p> -<pre class="language-python"><code>provider( - fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })</code></pre></li> -</ul> -All fields are optional.</td> -</tr> -<tr> -<td id="provider.init"><code>init</code></td> -<td>callable; or <code>None</code>; -default is <code>None</code><br /> -An optional callback for preprocessing and validating the provider's field values during instantiation. If <code>init</code> is specified, <code>provider()</code> returns a tuple of 2 elements: the normal provider symbol and a <em>raw constructor</em>. -<p>A precise description follows; see <a href="https://bazel.build/extending/rules#custom_initialization_of_providers">Rules (Custom initialization of providers)</a> for an intuitive discussion and use cases.</p> -<p>Let <code>P</code> be the provider symbol created by calling <code>provider()</code>. Conceptually, an instance of <code>P</code> is generated by calling a default constructor function <code>c(*args, **kwargs)</code>, which does the following:</p> -<ul> -<li>If <code>args</code> is non-empty, an error occurs.</li> -<li>If the <code>fields</code> parameter was specified when <code>provider()</code> was called, and if <code>kwargs</code> contains any key that was not listed in <code>fields</code>, an error occurs.</li> -<li>Otherwise, <code>c</code> returns a new instance that has, for each <code>k: v</code> entry in <code>kwargs</code>, a field named <code>k</code> with value <code>v</code>.</li> -</ul> -In the case where an <code>init</code> callback is <em>not</em> given, a call to the symbol <code>P</code> itself acts as a call to the default constructor function <code>c</code>; in other words, <code>P(*args, **kwargs)</code> returns <code>c(*args, **kwargs)</code>. For example, -<pre class="language-python"><code>MyInfo = provider() -m = MyInfo(foo = 1)</code></pre> -will straightforwardly make it so that <code>m</code> is a <code>MyInfo</code> instance with <code>m.foo == 1</code>. -<p>But in the case where <code>init</code> is specified, the call <code>P(*args, **kwargs)</code> will perform the following steps instead:</p> -<ol> -<li>The callback is invoked as <code>init(*args, **kwargs)</code>, that is, with the exact same positional and keyword arguments as were passed to <code>P</code>.</li> -<li>The return value of <code>init</code> is expected to be a dictionary, <code>d</code>, whose keys are field name strings. If it is not, an error occurs.</li> -<li>A new instance of <code>P</code> is generated as if by calling the default constructor with <code>d</code>'s entries as keyword arguments, as in <code>c(**d)</code>.</li> -</ol> -<p>NB: the above steps imply that an error occurs if <code>*args</code> or <code>**kwargs</code> does not match <code>init</code>'s signature, or the evaluation of <code>init</code>'s body fails (perhaps intentionally via a call to <a href="../globals/all.html#fail"><code>fail()</code></a>), or if the return value of <code>init</code> is not a dictionary with the expected schema.</p> -<p>In this way, the <code>init</code> callback generalizes normal provider construction by allowing positional arguments and arbitrary logic for preprocessing and validation. It does <em>not</em> enable circumventing the list of allowed <code>fields</code>.</p> -<p>When <code>init</code> is specified, the return value of <code>provider()</code> becomes a tuple <code>(P, r)</code>, where <code>r</code> is the <em>raw constructor</em>. In fact, the behavior of <code>r</code> is exactly that of the default constructor function <code>c</code> discussed above. Typically, <code>r</code> is bound to a variable whose name is prefixed with an underscore, so that only the current .bzl file has direct access to it:</p> -<pre class="language-python"><code>MyInfo, _new_myinfo = provider(init = ...)</code></pre></td> -</tr> -</tbody> -</table> - -## repository_rule - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` | +| `fields` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or [dict](../core/dict.mdx); or `None`; default is `None` If specified, restricts the set of allowed fields. Possible values are: * list of fields: ``` provider(fields = ['a', 'b']) ``` * dictionary field name -> documentation: ``` provider( fields = \{ 'a' : 'Documentation for a', 'b' : 'Documentation for b' \}) ``` All fields are optional. | +| `init` | callable; or `None`; default is `None` | + +## repository\_rule + +``` callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None) ``` @@ -732,67 +261,20 @@ Creates a new repository rule. Store it in a global value, so that it can be loa ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="repository_rule.implementation"><code>implementation</code></td> -<td>callable; -required<br /> -the function that implements this rule. Must have a single parameter, <a href="../builtins/repository_ctx.html"><code>repository_ctx</code></a>. The function is called during the loading phase for each instance of the rule.</td> -</tr> -<tr> -<td id="repository_rule.attrs"><code>attrs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -A dictionary to declare all the attributes of the repository rule. It maps from an attribute name to an attribute object (see -<a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label to a file (a repository rule cannot depend on a generated artifact). The attribute <code>name</code> is implicitly added and must not be specified. -<p>Declared attributes will convert <code>None</code> to the default value.</p></td> -</tr> -<tr> -<td id="repository_rule.local"><code>local</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch.</td> -</tr> -<tr> -<td id="repository_rule.environ"><code>environ</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -<strong>Deprecated</strong>. This parameter has been deprecated. Migrate to <code>repository_ctx.getenv</code> instead.<br /> -Provides a list of environment variable that this repository rule depends on. If an environment variable in that list change, the repository will be refetched.</td> -</tr> -<tr> -<td id="repository_rule.configure"><code>configure</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Indicate that the repository inspects the system for configuration purpose</td> -</tr> -<tr> -<td id="repository_rule.remotable"><code>remotable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -<strong>Experimental</strong>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_repo_remote_exec</code><br /> -Compatible with remote execution</td> -</tr> -<tr> -<td id="repository_rule.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the repository rule that can be extracted by documentation generating tools.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `implementation` | callable; required | +| `attrs` | [dict](../core/dict.mdx); or `None`; default is `None` | +| `local` | [bool](../core/bool.mdx); default is `False` Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch. | +| `environ` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` **Deprecated**. This parameter has been deprecated. Migrate to `repository_ctx.getenv` instead. Provides a list of environment variable that this repository rule depends on. If an environment variable in that list change, the repository will be refetched. | +| `configure` | [bool](../core/bool.mdx); default is `False` Indicate that the repository inspects the system for configuration purpose | +| `remotable` | [bool](../core/bool.mdx); default is `False` **Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_repo_remote_exec` Compatible with remote execution | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` | ## rule -``` rule-signature -callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[]) +``` +callable rule(implementation, *, test=unbound, attrs=\{\}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[]) ``` Creates a new rule, which can be called from a BUILD file or a macro to create targets. @@ -803,310 +285,82 @@ Test rules are required to have a name ending in `_test`, while all other rules ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="rule.implementation"><code>implementation</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -required<br /> -the Starlark function implementing this rule, must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. The function is called during the analysis phase for each instance of the rule. It can access the attributes provided by the user. It must create actions to generate all the declared outputs.</td> -</tr> -<tr> -<td id="rule.test"><code>test</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>unbound</code><br /> -Whether this rule is a test rule, that is, whether it may be the subject of a <code>bazel test</code> command. All test rules are automatically considered <a href="#rule.executable">executable</a>; it is unnecessary (and discouraged) to explicitly set <code>executable = True</code> for a test rule. The value defaults to <code>False</code>. See the <a href="https://bazel.build/extending/rules#executable_rules_and_test_rules">Rules page</a> for more information.</td> -</tr> -<tr> -<td id="rule.attrs"><code>attrs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see -<a href="../toplevel/attr.html"><code>attr</code></a> module). Attributes starting with <code>_</code> are private, and can be used to add an implicit dependency on a label. The attribute <code>name</code> is implicitly added and must not be specified. Attributes <code>visibility</code>, <code>deprecation</code>, <code>tags</code>, <code>testonly</code>, and <code>features</code> are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. -<p>Declared attributes will convert <code>None</code> to the default value.</p></td> -</tr> -<tr> -<td id="rule.outputs"><code>outputs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; or <a href="../core/function.html" class="anchor">function</a>; -default is <code>None</code><br /> -<strong>Deprecated</strong>. This parameter is deprecated and will be removed soon. Please do not depend on it. It is <em>disabled</em> with <code>--incompatible_no_rule_outputs_param</code>. Use this flag to verify your code is compatible with its imminent removal.<br /> -This parameter has been deprecated. Migrate rules to use <code>OutputGroupInfo</code> or <code>attr.output</code> instead. -<p>A schema for defining predeclared outputs. Unlike <a href="../toplevel/attr.html#output"><code>output</code></a> and <a href="../toplevel/attr.html#output_list"><code>output_list</code></a> attributes, the user does not specify the labels for these files. See the <a href="https://bazel.build/extending/rules#files">Rules page</a> for more on predeclared outputs.</p> -<p>The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass <code>outputs = _my_func</code> with the definition <code>def _my_func(srcs, deps): ...</code>, the function has access to the attributes <code>srcs</code> and <code>deps</code>. Whether the dictionary is specified directly or via a function, it is interpreted as follows.</p> -<p>Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's <a href="../builtins/File.html"><code>File</code></a> in <a href="../builtins/ctx.html#outputs"><code>ctx.outputs</code></a>. The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form <code>"%{ATTR}"</code> with a string formed from the value of the attribute <code>ATTR</code>:</p> -<ul> -<li>String-typed attributes are substituted verbatim.</li> -<li>Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label <code>"//pkg:a/b.c"</code> becomes <code>"a/b"</code>.</li> -<li>Output-typed attributes become the part of the label after the package, including the file extension (for the above example, <code>"a/b.c"</code>).</li> -<li>All list-typed attributes (for example, <code>attr.label_list</code>) used in placeholders are required to have <em>exactly one element</em>. Their conversion is the same as their non-list version (<code>attr.label</code>).</li> -<li>Other attribute types may not appear in placeholders.</li> -<li>The special non-attribute placeholders <code>%{dirname}</code> and <code>%{basename}</code> expand to those parts of the rule's label, excluding its package. For example, in <code>"//pkg:a/b.c"</code>, the dirname is <code>a</code> and the basename is <code>b.c</code>.</li> -</ul> -<p>In practice, the most common substitution placeholder is <code>"%{name}"</code>. For example, for a target named "foo", the outputs dict <code>{"bin": "%{name}.exe"}</code> predeclares an output named <code>foo.exe</code> that is accessible in the implementation function as <code>ctx.outputs.bin</code>.</p></td> -</tr> -<tr> -<td id="rule.executable"><code>executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>unbound</code><br /> -Whether this rule is considered executable, that is, whether it may be the subject of a <code>bazel run</code> command. It defaults to <code>False</code>. See the <a href="https://bazel.build/extending/rules#executable_rules_and_test_rules">Rules page</a> for more information.</td> -</tr> -<tr> -<td id="rule.output_to_genfiles"><code>output_to_genfiles</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the files will be generated in the genfiles directory instead of the bin directory. Unless you need it for compatibility with existing rules (e.g. when generating header files for C++), do not set this flag.</td> -</tr> -<tr> -<td id="rule.fragments"><code>fragments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -List of names of configuration fragments that the rule requires in target configuration.</td> -</tr> -<tr> -<td id="rule.host_fragments"><code>host_fragments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -List of names of configuration fragments that the rule requires in host configuration.</td> -</tr> -<tr> -<td id="rule._skylark_testable"><code>_skylark_testable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -<em>(Experimental)</em><br /> -<br /> -If true, this rule will expose its actions for inspection by rules that depend on it via an <code>Actions</code> provider. The provider is also available to the rule itself by calling <a href="../builtins/ctx.html#created_actions">ctx.created_actions()</a>.<br /> -<br /> -This should only be used for testing the analysis-time behavior of Starlark rules. This flag may be removed in the future.</td> -</tr> -<tr> -<td id="rule.toolchains"><code>toolchains</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -If set, the set of toolchains this rule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the rule implementation via <code>ctx.toolchain</code>.</td> -</tr> -<tr> -<td id="rule.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the rule that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="rule.provides"><code>provides</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -A list of providers that the implementation function must return. -<p>It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.</p> -<p>Each element of the list is an <code>*Info</code> object returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a>. When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The <a href="../globals/bzl.html#aspect.required_providers"><code>required_providers</code></a> field of an <a href="../globals/bzl.html#aspect">aspect</a> does, however, require that providers are specified here.</p></td> -</tr> -<tr> -<td id="rule.dependency_resolution_rule"><code>dependency_resolution_rule</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If set, the rule can be a dependency through attributes also marked as available in materializers. Every attribute of rules with this flag set must be marked as available in materializers also. This is so that rules so marked cannot depend on rules that are not so marked.</td> -</tr> -<tr> -<td id="rule.exec_compatible_with"><code>exec_compatible_with</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A list of constraints on the execution platform that apply to all targets of this rule type.</td> -</tr> -<tr> -<td id="rule.analysis_test"><code>analysis_test</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, then this rule is treated as an analysis test. -<p>Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See <a href="https://bazel.build/rules/testing#testing-rules">Testing</a> for guidance.</p> -<p>If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using <a href="#analysis_test_transition">analysis_test_transition</a> on its attributes, but opts into some restrictions:</p> -<ul> -<li>Targets of this rule are limited in the number of transitive dependencies they may have.</li> -<li>The rule is considered a test rule (as if <code>test=True</code> were set). This supersedes the value of <code>test</code></li> -<li>The rule implementation function may not register actions. Instead, it must register a pass/fail result via providing <a href="../providers/AnalysisTestResultInfo.html">AnalysisTestResultInfo</a>.</li> -</ul></td> -</tr> -<tr> -<td id="rule.build_setting"><code>build_setting</code></td> -<td><a href="../builtins/BuildSetting.html" class="anchor">BuildSetting</a>; or <code>None</code>; -default is <code>None</code><br /> -If set, describes what kind of <a href="/rules/config#user-defined-build-settings"><code>build setting</code></a> this rule is. See the <a href="../toplevel/config.html"><code>config</code></a> module. If this is set, a mandatory attribute named "build_setting_default" is automatically added to this rule, with a type corresponding to the value passed in here.</td> -</tr> -<tr> -<td id="rule.cfg"><code>cfg</code></td> -<td>default is <code>None</code><br /> -If set, points to the configuration transition the rule will apply to its own configuration before analysis.</td> -</tr> -<tr> -<td id="rule.exec_groups"><code>exec_groups</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <code>None</code>; -default is <code>None</code><br /> -Dict of execution group name (string) to <a href="../globals/bzl.html#exec_group"><code>exec_group</code>s</a>. If set, allows rules to run actions on multiple execution platforms within a single target. See <a href="/reference/exec-groups">execution groups documentation</a> for more info.</td> -</tr> -<tr> -<td id="rule.initializer"><code>initializer</code></td> -<td>default is <code>None</code><br /> -Experimental: the Stalark function initializing the attributes of the rule. -<p>The function is called at load time for each instance of the rule. It's called with <code>name</code> and the values of public attributes defined by the rule (not with generic attributes, for example <code>tags</code>).</p> -<p>It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning <code>None</code> as value results in using the default value specified in the attribute definition.</p> -<p>Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning <code>None</code>).</p> -<p>Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases.</p> -<p>It's a good practice to use <code>**kwargs</code> for attributes that are not handled.</p> -<p>In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about.</p></td> -</tr> -<tr> -<td id="rule.parent"><code>parent</code></td> -<td>default is <code>None</code><br /> -Experimental: the Stalark rule that is extended. When set the public attributes are merged as well as advertised providers. The rule matches <code>executable</code> and <code>test</code> from the parent. Values of <code>fragments</code>, <code>toolchains</code>, <code>exec_compatible_with</code>, and <code>exec_groups</code> are merged. Legacy or deprecated parameters may not be set. Incoming configuration transition <code>cfg</code> of parent is applied after thisrule's incoming configuration.</td> -</tr> -<tr> -<td id="rule.extendable"><code>extendable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Experimental: A label of an allowlist defining which rules can extending this rule. It can be set also to True/False to always allow/disallow extending. Bazel defaults to always allowing extensions.</td> -</tr> -<tr> -<td id="rule.subrules"><code>subrules</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Subrule.html" class="anchor">Subrule</a>s; -default is <code>[]</code><br /> -Experimental: List of subrules used by this rule.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `implementation` | [function](../core/function.mdx); required the Starlark function implementing this rule, must have exactly one parameter: [ctx](../builtins/ctx.mdx). The function is called during the analysis phase for each instance of the rule. It can access the attributes provided by the user. It must create actions to generate all the declared outputs. | +| `test` | [bool](../core/bool.mdx); default is `unbound` Whether this rule is a test rule, that is, whether it may be the subject of a `bazel test` command. All test rules are automatically considered [executable](#rule.executable); it is unnecessary (and discouraged) to explicitly set `executable = True` for a test rule. The value defaults to `False`. See the [Rules page](https://bazel.build/extending/rules#executable_rules_and_test_rules) for more information. | +| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see [`attr`](../toplevel/attr.mdx) module). Attributes starting with `_` are private, and can be used to add an implicit dependency on a label. The attribute `name` is implicitly added and must not be specified. Attributes `visibility`, `deprecation`, `tags`, `testonly`, and `features` are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. Declared attributes will convert `None` to the default value. | +| `outputs` | [dict](../core/dict.mdx); or `None`; or [function](../core/function.mdx); default is `None` **Deprecated**. This parameter is deprecated and will be removed soon. Please do not depend on it. It is *disabled* with `--incompatible_no_rule_outputs_param`. Use this flag to verify your code is compatible with its imminent removal. This parameter has been deprecated. Migrate rules to use `OutputGroupInfo` or `attr.output` instead. A schema for defining predeclared outputs. Unlike [`output`](../toplevel/attr.html#output) and [`output_list`](../toplevel/attr.html#output_list) attributes, the user does not specify the labels for these files. See the [Rules page](https://bazel.build/extending/rules#files) for more on predeclared outputs. The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass `outputs = _my_func` with the definition `def _my_func(srcs, deps): ...`, the function has access to the attributes `srcs` and `deps`. Whether the dictionary is specified directly or via a function, it is interpreted as follows. Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's [`File`](../builtins/File.mdx) in [`ctx.outputs`](../builtins/ctx.html#outputs). The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form `"%\{ATTR\}"` with a string formed from the value of the attribute `ATTR`: * String-typed attributes are substituted verbatim.* Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label `"//pkg:a/b.c"` becomes `"a/b"`.* Output-typed attributes become the part of the label after the package, including the file extension (for the above example, `"a/b.c"`).* All list-typed attributes (for example, `attr.label_list`) used in placeholders are required to have *exactly one element*. Their conversion is the same as their non-list version (`attr.label`).* Other attribute types may not appear in placeholders.* The special non-attribute placeholders `%\{dirname\}` and `%\{basename\}` expand to those parts of the rule's label, excluding its package. For example, in `"//pkg:a/b.c"`, the dirname is `a` and the basename is `b.c`. In practice, the most common substitution placeholder is `"%\{name\}"`. For example, for a target named "foo", the outputs dict `\{"bin": "%\{name\}.exe"\}` predeclares an output named `foo.exe` that is accessible in the implementation function as `ctx.outputs.bin`. | +| `executable` | [bool](../core/bool.mdx); default is `unbound` | +| `output_to_genfiles` | [bool](../core/bool.mdx); default is `False` If true, the files will be generated in the genfiles directory instead of the bin directory. Unless you need it for compatibility with existing rules (e.g. when generating header files for C++), do not set this flag. | +| `fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the rule requires in target configuration. | +| `host_fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the rule requires in host configuration. | +| `_skylark_testable` | [bool](../core/bool.mdx); default is `False` *(Experimental)* If true, this rule will expose its actions for inspection by rules that depend on it via an `Actions` provider. The provider is also available to the rule itself by calling [ctx.created\_actions()](../builtins/ctx.html#created_actions). This should only be used for testing the analysis-time behavior of Starlark rules. This flag may be removed in the future. | +| `toolchains` | [sequence](../core/list.mdx); default is `[]` If set, the set of toolchains this rule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the rule implementation via `ctx.toolchain`. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the rule that can be extracted by documentation generating tools. | +| `provides` | [sequence](../core/list.mdx); default is `[]` A list of providers that the implementation function must return. It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here. Each element of the list is an `*Info` object returned by [`provider()`](../globals/bzl.html#provider). When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The [`required_providers`](../globals/bzl.html#aspect.required_providers) field of an [aspect](../globals/bzl.html#aspect) does, however, require that providers are specified here. | +| `dependency_resolution_rule` | [bool](../core/bool.mdx); default is `False` If set, the rule can be a dependency through attributes also marked as available in materializers. Every attribute of rules with this flag set must be marked as available in materializers also. This is so that rules so marked cannot depend on rules that are not so marked. | +| `exec_compatible_with` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A list of constraints on the execution platform that apply to all targets of this rule type. | +| `analysis_test` | [bool](../core/bool.mdx); default is `False` If true, then this rule is treated as an analysis test. Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See [Testing](https://bazel.build/rules/testing#testing-rules) for guidance. If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using [analysis\_test\_transition](#analysis_test_transition) on its attributes, but opts into some restrictions: * Targets of this rule are limited in the number of transitive dependencies they may have.* The rule is considered a test rule (as if `test=True` were set). This supersedes the value of `test` * The rule implementation function may not register actions. Instead, it must register a pass/fail result via providing [AnalysisTestResultInfo](../providers/AnalysisTestResultInfo.mdx). | +| `build_setting` | [BuildSetting](../builtins/BuildSetting.mdx); or `None`; default is `None` If set, describes what kind of [`build setting`](./rules/config#user-defined-build-settings) this rule is. See the [`config`](../toplevel/config.mdx) module. If this is set, a mandatory attribute named "build\_setting\_default" is automatically added to this rule, with a type corresponding to the value passed in here. | +| `cfg` | default is `None` If set, points to the configuration transition the rule will apply to its own configuration before analysis. | +| `exec_groups` | [dict](../core/dict.mdx); or `None`; default is `None` Dict of execution group name (string) to [`exec_group`s](../globals/bzl.html#exec_group). If set, allows rules to run actions on multiple execution platforms within a single target. See [execution groups documentation](./reference/exec-groups) for more info. | +| `initializer` | default is `None` Experimental: the Stalark function initializing the attributes of the rule. The function is called at load time for each instance of the rule. It's called with `name` and the values of public attributes defined by the rule (not with generic attributes, for example `tags`). It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning `None` as value results in using the default value specified in the attribute definition. Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning `None`). Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases. It's a good practice to use `**kwargs` for attributes that are not handled. In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about. | +| `parent` | default is `None` Experimental: the Stalark rule that is extended. When set the public attributes are merged as well as advertised providers. The rule matches `executable` and `test` from the parent. Values of `fragments`, `toolchains`, `exec_compatible_with`, and `exec_groups` are merged. Legacy or deprecated parameters may not be set. Incoming configuration transition `cfg` of parent is applied after thisrule's incoming configuration. | +| `extendable` | [bool](../core/bool.mdx); or [Label](../builtins/Label.mdx); or [string](../core/string.mdx); or `None`; default is `None` Experimental: A label of an allowlist defining which rules can extending this rule. It can be set also to True/False to always allow/disallow extending. Bazel defaults to always allowing extensions. | +| `subrules` | [sequence](../core/list.mdx) of [Subrule](../builtins/Subrule.mdx)s; default is `[]` Experimental: List of subrules used by this rule. | ## select -``` rule-signature +``` unknown select(x, no_match_error='') ``` -`select()` is the helper function that makes a rule attribute [configurable](/reference/be/common-definitions#configurable-attributes). See [build encyclopedia](/reference/be/functions#select) for details. +`select()` is the helper function that makes a rule attribute [configurable](./reference/be/common-definitions#configurable-attributes). See [build encyclopedia](./reference/be/functions#select) for details. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="select.x"><code>x</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -required<br /> -A dict that maps configuration conditions to values. Each key is a <a href="../builtins/Label.html">Label</a> or a label string that identifies a config_setting or constraint_value instance. See the <a href="https://bazel.build/extending/legacy-macros#label-resolution">documentation on macros</a> for when to use a Label instead of a string. If <code>--incompatible_resolve_select_keys_eagerly</code> is enabled, the keys are resolved to <code>Label</code> objects relative to the package of the file that contains this call to <code>select</code>.</td> -</tr> -<tr> -<td id="select.no_match_error"><code>no_match_error</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Optional custom error to report if no condition matches.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | [dict](../core/dict.mdx); required A dict that maps configuration conditions to values. Each key is a [Label](../builtins/Label.mdx) or a label string that identifies a config\_setting or constraint\_value instance. See the [documentation on macros](https://bazel.build/extending/legacy-macros#label-resolution) for when to use a Label instead of a string. If `--incompatible_resolve_select_keys_eagerly` is enabled, the keys are resolved to `Label` objects relative to the package of the file that contains this call to `select`. | +| `no_match_error` | [string](../core/string.mdx); default is `''` Optional custom error to report if no condition matches. | ## subrule -``` rule-signature -Subrule subrule(*, implementation, attrs={}, toolchains=[], fragments=[], subrules=[]) +``` +Subrule subrule(*, implementation, attrs=\{\}, toolchains=[], fragments=[], subrules=[]) ``` Constructs a new instance of a subrule. The result of this function must be stored in a global variable before it can be used. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="subrule.implementation"><code>implementation</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -required<br /> -The Starlark function implementing this subrule</td> -</tr> -<tr> -<td id="subrule.attrs"><code>attrs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary to declare all the (private) attributes of the subrule. -Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be: -<ul> -<li><code>FilesToRunProvider</code> for label attributes with <code>executable=True</code></li> -<li><code>File</code> for label attributes with <code>allow_single_file=True</code></li> -<li><code>Target</code> for all other label attributes</li> -<li><code>[Target]</code> for all label-list attributes</li> -</ul></td> -</tr> -<tr> -<td id="subrule.toolchains"><code>toolchains</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -If set, the set of toolchains this subrule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the subrule implementation via <code>ctx.toolchains</code>. Note that AEGs need to be enabled on the consuming rule(s) if this parameter is set. In case you haven't migrated to AEGs yet, see https://bazel.build/extending/auto-exec-groups#migration-aegs.</td> -</tr> -<tr> -<td id="subrule.fragments"><code>fragments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -List of names of configuration fragments that the subrule requires in target configuration.</td> -</tr> -<tr> -<td id="subrule.subrules"><code>subrules</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Subrule.html" class="anchor">Subrule</a>s; -default is <code>[]</code><br /> -List of other subrules needed by this subrule.</td> -</tr> -</tbody> -</table> - -## tag_class - -``` rule-signature -tag_class tag_class(attrs={}, *, doc=None) +| Parameter | Description | +| --- | --- | +| `implementation` | [function](../core/function.mdx); required The Starlark function implementing this subrule | +| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the (private) attributes of the subrule. Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be: * `FilesToRunProvider` for label attributes with `executable=True` * `File` for label attributes with `allow_single_file=True` * `Target` for all other label attributes * `[Target]` for all label-list attributes | +| `toolchains` | [sequence](../core/list.mdx); default is `[]` If set, the set of toolchains this subrule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the subrule implementation via `ctx.toolchains`. Note that AEGs need to be enabled on the consuming rule(s) if this parameter is set. In case you haven't migrated to AEGs yet, see https://bazel.build/extending/auto-exec-groups#migration-aegs. | +| `fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the subrule requires in target configuration. | +| `subrules` | [sequence](../core/list.mdx) of [Subrule](../builtins/Subrule.mdx)s; default is `[]` List of other subrules needed by this subrule. | + +## tag\_class + +``` +tag_class tag_class(attrs=\{\}, *, doc=None) ``` -Creates a new tag_class object, which defines an attribute schema for a class of tags, which are data objects usable by a module extension. +Creates a new tag\_class object, which defines an attribute schema for a class of tags, which are data objects usable by a module extension. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="tag_class.attrs"><code>attrs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dictionary to declare all the attributes of this tag class. It maps from an attribute name to an attribute object (see -<a href="../toplevel/attr.html">attr</a> module). -<p>Note that unlike <a href="../globals/bzl.html#rule"><code>rule()</code></a>, <a href="../globals/bzl.html#aspect"><code>aspect()</code></a> and <a href="../globals/bzl.html#repository_rule"><code>repository_rule()</code></a>, -declared attributes will not convert <code>None</code> to the default value. For the default to be used, the attribute must be omitted entirely by the caller.</p></td> -</tr> -<tr> -<td id="tag_class.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the tag class that can be extracted by documentation generating tools.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the attributes of this tag class. It maps from an attribute name to an attribute object (see [attr](../toplevel/attr.mdx) module). Note that unlike [`rule()`](../globals/bzl.html#rule), [`aspect()`](../globals/bzl.html#aspect) and [`repository_rule()`](../globals/bzl.html#repository_rule), declared attributes will not convert `None` to the default value. For the default to be used, the attribute must be omitted entirely by the caller. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the tag class that can be extracted by documentation generating tools. | ## visibility -``` rule-signature +``` None visibility(value) ``` @@ -1120,27 +374,6 @@ If the flag `--check_bzl_visibility` is set to false, load visibility violations ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="visibility.value"><code>value</code></td> -<td>required<br /> -A list of package specification strings, or a single package specification string. -<p>Package specifications follow the same format as for <a href="/reference/be/functions#package_group"><code>package_group</code></a>, except that negative package specifications are not permitted. That is, a specification may have the forms:</p> -<ul> -<li><code>"//foo"</code>: the package <code>//foo</code></li> -<li><code>"//foo/..."</code>: the package <code>//foo</code> and all of its subpackages.</li> -<li><code>"public"</code> or <code>"private"</code>: all packages or no packages, respectively</li> -</ul> -<p>The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository.</p> -<p>If <code>value</code> is a list of strings, the set of packages granted visibility to this module is the union of the packages represented by each specification. (An empty list has the same effect as <code>private</code>.) If <code>value</code> is a single string, it is treated as if it were the singleton list <code>[value]</code>.</p> -<p>Note that the flags <code>--incompatible_package_group_has_public_syntax</code> and <code>--incompatible_fix_package_group_reporoot_syntax</code> have no effect on this argument. The <code>"public"</code> and <code>"private"</code> values are always available, and <code>"//..."</code> is always interpreted as "all packages in the current repository".</p></td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `value` | required A list of package specification strings, or a single package specification string. Package specifications follow the same format as for `package_group`, except that negative package specifications are not permitted. That is, a specification may have the forms: * `"//foo"`: the package `//foo`* `"//foo/..."`: the package `//foo` and all of its subpackages.* `"public"` or `"private"`: all packages or no packages, respectively The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository. If `value` is a list of strings, the set of packages granted visibility to this module is the union of the packages represented by each specification. (An empty list has the same effect as `private`.) If `value` is a single string, it is treated as if it were the singleton list `[value]`. Note that the flags `--incompatible_package_group_has_public_syntax` and `--incompatible_fix_package_group_reporoot_syntax` have no effect on this argument. The `"public"` and `"private"` values are always available, and `"//..."` is always interpreted as "all packages in the current repository". | \ No newline at end of file diff --git a/rules/lib/globals/module.mdx b/rules/lib/globals/module.mdx index 2091e8a..b4b9eaf 100644 --- a/rules/lib/globals/module.mdx +++ b/rules/lib/globals/module.mdx @@ -2,34 +2,31 @@ title: 'module' --- -# MODULE.bazel files -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} Methods available in MODULE.bazel files. ## Members -- [archive_override](#archive_override) -- [bazel_dep](#bazel_dep) -- [flag_alias](#flag_alias) -- [git_override](#git_override) -- [include](#include) -- [inject_repo](#inject_repo) -- [local_path_override](#local_path_override) -- [module](#module) -- [multiple_version_override](#multiple_version_override) -- [override_repo](#override_repo) -- [register_execution_platforms](#register_execution_platforms) -- [register_toolchains](#register_toolchains) -- [single_version_override](#single_version_override) -- [use_extension](#use_extension) -- [use_repo](#use_repo) -- [use_repo_rule](#use_repo_rule) - -## archive_override - -``` rule-signature +* [archive\_override](#archive_override) +* [bazel\_dep](#bazel_dep) +* [flag\_alias](#flag_alias) +* [git\_override](#git_override) +* [include](#include) +* [inject\_repo](#inject_repo) +* [local\_path\_override](#local_path_override) +* [module](#module) +* [multiple\_version\_override](#multiple_version_override) +* [override\_repo](#override_repo) +* [register\_execution\_platforms](#register_execution_platforms) +* [register\_toolchains](#register_toolchains) +* [single\_version\_override](#single_version_override) +* [use\_extension](#use_extension) +* [use\_repo](#use_repo) +* [use\_repo\_rule](#use_repo_rule) + +## archive\_override + +``` None archive_override(*, module_name, **kwargs) ``` @@ -42,33 +39,14 @@ used as a dependency by others, its own overrides are ignored. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="archive_override.module_name"><code>module_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the Bazel module dependency to apply this override to.</td> -</tr> -<tr> -<td id="archive_override.kwargs"><code>kwargs</code></td> -<td>required<br /> -All other arguments are forwarded to the underlying <code>http_archive</code> repo -rule. Note that the <code>name</code> attribute shouldn't be specified; use -<code>module_name</code> instead.</td> -</tr> -</tbody> -</table> - -## bazel_dep - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | +| `kwargs` | required All other arguments are forwarded to the underlying `http_archive` repo rule. Note that the `name` attribute shouldn't be specified; use `module_name` instead. | + +## bazel\_dep + +``` None bazel_dep(*, name, version='', max_compatibility_level=-1, repo_name='', dev_dependency=False) ``` @@ -76,88 +54,33 @@ Declares a direct dependency on another Bazel module. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="bazel_dep.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the module to be added as a direct dependency.</td> -</tr> -<tr> -<td id="bazel_dep.version"><code>version</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The version of the module to be added as a direct dependency.</td> -</tr> -<tr> -<td id="bazel_dep.max_compatibility_level"><code>max_compatibility_level</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>-1</code><br /> -The maximum <code>compatibility_level</code> supported for the module to be added as a direct dependency. The version of the module implies the minimum compatibility_level supported, as well as the maximum if this attribute is not specified.</td> -</tr> -<tr> -<td id="bazel_dep.repo_name"><code>repo_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>''</code><br /> -The name of the external repo representing this dependency. This is by default the -name of the module. Can be set to <code>None</code> to make this dependency a -"<em>nodep</em>" dependency: in this case, this <code>bazel_dep</code> specification -is only honored if the target module already exists in the dependency graph by some -other means.</td> -</tr> -<tr> -<td id="bazel_dep.dev_dependency"><code>dev_dependency</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, this dependency will be ignored if the current module is not the root module or <code>--ignore_dev_dependency</code> is enabled.</td> -</tr> -</tbody> -</table> - -## flag_alias - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required The name of the module to be added as a direct dependency. | +| `version` | [string](../core/string.mdx); default is `''` The version of the module to be added as a direct dependency. | +| `max_compatibility_level` | [int](../core/int.mdx); default is `-1` The maximum `compatibility_level` supported for the module to be added as a direct dependency. The version of the module implies the minimum compatibility\_level supported, as well as the maximum if this attribute is not specified. | +| `repo_name` | [string](../core/string.mdx); or `None`; default is `''` The name of the external repo representing this dependency. This is by default the name of the module. Can be set to `None` to make this dependency a "*nodep*" dependency: in this case, this `bazel_dep` specification is only honored if the target module already exists in the dependency graph by some other means. | +| `dev_dependency` | [bool](../core/bool.mdx); default is `False` If true, this dependency will be ignored if the current module is not the root module or `--ignore_dev_dependency` is enabled. | + +## flag\_alias + +``` None flag_alias(name, starlark_flag) ``` Maps a command-line flag --foo to a Starlark flag --@repo//defs:foo. Bazel translates all -instances of \$ bazel build //target --foo to \$ bazel build //target --@repo//defs:foo. +instances of $ bazel build //target --foo to $ bazel build //target --@repo//defs:foo. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="flag_alias.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the flag.</td> -</tr> -<tr> -<td id="flag_alias.starlark_flag"><code>starlark_flag</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The label of the Starlark flag to alias to.</td> -</tr> -</tbody> -</table> - -## git_override - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required The name of the flag. | +| `starlark_flag` | [string](../core/string.mdx); required The label of the Starlark flag to alias to. | + +## git\_override + +``` None git_override(*, module_name, **kwargs) ``` @@ -170,33 +93,14 @@ used as a dependency by others, its own overrides are ignored. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="git_override.module_name"><code>module_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the Bazel module dependency to apply this override to.</td> -</tr> -<tr> -<td id="git_override.kwargs"><code>kwargs</code></td> -<td>required<br /> -All other arguments are forwarded to the underlying <code>git_repository</code> -repo rule. Note that the <code>name</code> attribute shouldn't be specified; use -<code>module_name</code> instead.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | +| `kwargs` | required All other arguments are forwarded to the underlying `git_repository` repo rule. Note that the `name` attribute shouldn't be specified; use `module_name` instead. | ## include -``` rule-signature +``` None include(label) ``` @@ -210,28 +114,13 @@ Only files in the main repo may be included. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="include.label"><code>label</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The label pointing to the file to include. The label must point to a file in the main repo; in other words, it -must -start with double slashes (<code>//</code>). The name of the file must end with <code>.MODULE.bazel</code> and must not start with <code>.</code>.</td> -</tr> -</tbody> -</table> - -## inject_repo - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `label` | [string](../core/string.mdx); required The label pointing to the file to include. The label must point to a file in the main repo; in other words, it **must **start with double slashes (`//`). The name of the file must end with `.MODULE.bazel` and must not start with `.`.**** | + +## inject\_repo + +``` None inject_repo(extension_proxy, *args, **kwargs) ``` @@ -244,42 +133,15 @@ existing repo. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="inject_repo.extension_proxy"><code>extension_proxy</code></td> -<td>module_extension_proxy; -required<br /> -A module extension proxy object returned by a <code>use_extension</code> call.</td> -</tr> -<tr> -<td id="inject_repo.args"><code>args</code></td> -<td>required<br /> -The repos visible to the current module that should be injected into the -extension under the same name.</td> -</tr> -<tr> -<td id="inject_repo.kwargs"><code>kwargs</code></td> -<td>required<br /> -The new repos to inject into the extension, where the values are the names of -repos in the scope of the current module and the keys are the name they will be -visible under in the extension. -<p>Keys that are not valid identifiers can be specified via a literal dict -passed as extra keyword arguments, e.g., -<code>inject_repo(extension_proxy, **{"foo.2": "foo"})</code>.</p></td> -</tr> -</tbody> -</table> - -## local_path_override - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `extension_proxy` | module\_extension\_proxy; required A module extension proxy object returned by a `use_extension` call. | +| `args` | required The repos visible to the current module that should be injected into the extension under the same name. | +| `kwargs` | required The new repos to inject into the extension, where the values are the names of repos in the scope of the current module and the keys are the name they will be visible under in the extension. Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., `inject_repo(extension_proxy, **\{"foo.2": "foo"\})`. | + +## local\_path\_override + +``` None local_path_override(*, module_name, path) ``` @@ -292,32 +154,14 @@ used as a dependency by others, its own overrides are ignored. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="local_path_override.module_name"><code>module_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the Bazel module dependency to apply this override to.</td> -</tr> -<tr> -<td id="local_path_override.path"><code>path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The path to the directory where this module is.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | +| `path` | [string](../core/string.mdx); required The path to the directory where this module is. | ## module -``` rule-signature +``` None module(*, name='', version='', compatibility_level=0, repo_name='', bazel_compatibility=[]) ``` @@ -327,202 +171,83 @@ It should be called at most once, and if called, it must be the very first direc ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="module.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The name of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). A valid module name must: 1) only contain lowercase letters (a-z), digits (0-9), dots (.), hyphens (-), and underscores (_); 2) begin with a lowercase letter; 3) end with a lowercase letter or digit.</td> -</tr> -<tr> -<td id="module.version"><code>version</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The version of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). The version must be in a relaxed SemVer format; see <a href="/external/module#version_format">the documentation</a> for more details.</td> -</tr> -<tr> -<td id="module.compatibility_level"><code>compatibility_level</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>0</code><br /> -The compatibility level of the module; this should be changed every time a major incompatible change is introduced. This is essentially the "major version" of the module in terms of SemVer, except that it's not embedded in the version string itself, but exists as a separate field. Modules with different compatibility levels participate in version resolution as if they're modules with different names, but the final dependency graph cannot contain multiple modules with the same name but different compatibility levels (unless <code>multiple_version_override</code> is in effect). See <a href="/external/module#compatibility_level">the documentation</a> for more details.</td> -</tr> -<tr> -<td id="module.repo_name"><code>repo_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The name of the repository representing this module, as seen by the module itself. By default, the name of the repo is the name of the module. This can be specified to ease migration for projects that have been using a repo name for itself that differs from its module name.</td> -</tr> -<tr> -<td id="module.bazel_compatibility"><code>bazel_compatibility</code></td> -<td>Iterable of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A list of bazel versions that allows users to declare which Bazel versions are compatible with this module. It does NOT affect dependency resolution, but bzlmod will use this information to check if your current Bazel version is compatible. The format of this value is a string of some constraint values separated by comma. Three constraints are supported: <=X.X.X: The Bazel version must be equal or older than X.X.X. Used when there is a known incompatible change in a newer version. >=X.X.X: The Bazel version must be equal or newer than X.X.X.Used when you depend on some features that are only available since X.X.X. -X.X.X: The Bazel version X.X.X is not compatible. Used when there is a bug in X.X.X that breaks you, but fixed in later versions.</td> -</tr> -</tbody> -</table> - -## multiple_version_override - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); default is `''` The name of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). A valid module name must: 1) only contain lowercase letters (a-z), digits (0-9), dots (.), hyphens (-), and underscores (\_); 2) begin with a lowercase letter; 3) end with a lowercase letter or digit. | +| `version` | [string](../core/string.mdx); default is `''` The version of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). The version must be in a relaxed SemVer format; see [the documentation](./external/module#version_format) for more details. | +| `compatibility_level` | [int](../core/int.mdx); default is `0` The compatibility level of the module; this should be changed every time a major incompatible change is introduced. This is essentially the "major version" of the module in terms of SemVer, except that it's not embedded in the version string itself, but exists as a separate field. Modules with different compatibility levels participate in version resolution as if they're modules with different names, but the final dependency graph cannot contain multiple modules with the same name but different compatibility levels (unless `multiple_version_override` is in effect). See [the documentation](./external/module#compatibility_level) for more details. | +| `repo_name` | [string](../core/string.mdx); default is `''` The name of the repository representing this module, as seen by the module itself. By default, the name of the repo is the name of the module. This can be specified to ease migration for projects that have been using a repo name for itself that differs from its module name. | +| `bazel_compatibility` | Iterable of [string](../core/string.mdx)s; default is `[]` A list of bazel versions that allows users to declare which Bazel versions are compatible with this module. It does NOT affect dependency resolution, but bzlmod will use this information to check if your current Bazel version is compatible. The format of this value is a string of some constraint values separated by comma. Three constraints are supported: <=X.X.X: The Bazel version must be equal or older than X.X.X. Used when there is a known incompatible change in a newer version. >=X.X.X: The Bazel version must be equal or newer than X.X.X.Used when you depend on some features that are only available since X.X.X. -X.X.X: The Bazel version X.X.X is not compatible. Used when there is a bug in X.X.X that breaks you, but fixed in later versions. | + +## multiple\_version\_override + +``` None multiple_version_override(*, module_name, versions, registry='') ``` -Specifies that a dependency should still come from a registry, but multiple versions of it should be allowed to coexist. See [the documentation](/external/module#multiple-version_override) for more details. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. +Specifies that a dependency should still come from a registry, but multiple versions of it should be allowed to coexist. See [the documentation](./external/module#multiple-version_override) for more details. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="multiple_version_override.module_name"><code>module_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the Bazel module dependency to apply this override to.</td> -</tr> -<tr> -<td id="multiple_version_override.versions"><code>versions</code></td> -<td>Iterable of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -Explicitly specifies the versions allowed to coexist. These versions must already be present in the dependency graph pre-selection. Dependencies on this module will be "upgraded" to the nearest higher allowed version at the same compatibility level, whereas dependencies that have a higher version than any allowed versions at the same compatibility level will cause an error.</td> -</tr> -<tr> -<td id="multiple_version_override.registry"><code>registry</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used.</td> -</tr> -</tbody> -</table> - -## override_repo - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | +| `versions` | Iterable of [string](../core/string.mdx)s; required Explicitly specifies the versions allowed to coexist. These versions must already be present in the dependency graph pre-selection. Dependencies on this module will be "upgraded" to the nearest higher allowed version at the same compatibility level, whereas dependencies that have a higher version than any allowed versions at the same compatibility level will cause an error. | +| `registry` | [string](../core/string.mdx); default is `''` Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. | + +## override\_repo + +``` None override_repo(extension_proxy, *args, **kwargs) ``` Overrides one or more repos defined by the given module extension with the given repos visible to the current module. This is ignored if the current module is not the root -module or \`--ignore_dev_dependency\` is enabled. +module or `--ignore\_dev\_dependency` is enabled. Use [`inject_repo`](#inject_repo) instead to add a new repo. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="override_repo.extension_proxy"><code>extension_proxy</code></td> -<td>module_extension_proxy; -required<br /> -A module extension proxy object returned by a <code>use_extension</code> call.</td> -</tr> -<tr> -<td id="override_repo.args"><code>args</code></td> -<td>required<br /> -The repos in the extension that should be overridden with the repos of the same -name in the current module.</td> -</tr> -<tr> -<td id="override_repo.kwargs"><code>kwargs</code></td> -<td>required<br /> -The overrides to apply to the repos generated by the extension, where the values -are the names of repos in the scope of the current module and the keys are the -names of the repos they will override in the extension. -<p>Keys that are not valid identifiers can be specified via a literal dict -passed as extra keyword arguments, e.g., -<code>override_repo(extension_proxy, **{"foo.2": "foo"})</code>.</p></td> -</tr> -</tbody> -</table> - -## register_execution_platforms - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `extension_proxy` | module\_extension\_proxy; required A module extension proxy object returned by a `use_extension` call. | +| `args` | required The repos in the extension that should be overridden with the repos of the same name in the current module. | +| `kwargs` | required The overrides to apply to the repos generated by the extension, where the values are the names of repos in the scope of the current module and the keys are the names of the repos they will override in the extension. Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., `override_repo(extension_proxy, **\{"foo.2": "foo"\})`. | + +## register\_execution\_platforms + +``` None register_execution_platforms(*platform_labels, dev_dependency=False) ``` -Specifies already-defined execution platforms to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](/docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by name. +Specifies already-defined execution platforms to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](./docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by name. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="register_execution_platforms.dev_dependency"><code>dev_dependency</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the execution platforms will not be registered if the current module is not the root module or `--ignore_dev_dependency` is enabled.</td> -</tr> -<tr> -<td id="register_execution_platforms.platform_labels"><code>platform_labels</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The target patterns to register.</td> -</tr> -</tbody> -</table> - -## register_toolchains - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `dev_dependency` | [bool](../core/bool.mdx); default is `False` If true, the execution platforms will not be registered if the current module is not the root module or `--ignore\_dev\_dependency` is enabled. | +| `platform_labels` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The target patterns to register. | + +## register\_toolchains + +``` None register_toolchains(*toolchain_labels, dev_dependency=False) ``` -Specifies already-defined toolchains to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](/docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by target name (not the name of the toolchain implementation). +Specifies already-defined toolchains to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](./docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by target name (not the name of the toolchain implementation). ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="register_toolchains.dev_dependency"><code>dev_dependency</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the toolchains will not be registered if the current module is not the root module or `--ignore_dev_dependency` is enabled.</td> -</tr> -<tr> -<td id="register_toolchains.toolchain_labels"><code>toolchain_labels</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The target patterns to register.</td> -</tr> -</tbody> -</table> - -## single_version_override - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `dev_dependency` | [bool](../core/bool.mdx); default is `False` If true, the toolchains will not be registered if the current module is not the root module or `--ignore\_dev\_dependency` is enabled. | +| `toolchain_labels` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The target patterns to register. | + +## single\_version\_override + +``` None single_version_override(*, module_name, version='', registry='', patches=[], patch_cmds=[], patch_strip=0) ``` @@ -530,58 +255,18 @@ Specifies that a dependency should still come from a registry, but its version s ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="single_version_override.module_name"><code>module_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the Bazel module dependency to apply this override to.</td> -</tr> -<tr> -<td id="single_version_override.version"><code>version</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Overrides the declared version of this module in the dependency graph. In other words, this module will be "pinned" to this override version. This attribute can be omitted if all one wants to override is the registry or the patches.</td> -</tr> -<tr> -<td id="single_version_override.registry"><code>registry</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used.</td> -</tr> -<tr> -<td id="single_version_override.patches"><code>patches</code></td> -<td>Iterable of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A list of labels pointing to patch files to apply for this module. The patch files must exist in the source tree of the top level project. They are applied in the list order. -<p>If a patch makes changes to the MODULE.bazel file, these changes will only be effective if the patch file is provided by the root module.</p></td> -</tr> -<tr> -<td id="single_version_override.patch_cmds"><code>patch_cmds</code></td> -<td>Iterable of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Sequence of Bash commands to be applied on Linux/Macos after patches are applied. -<p>Changes to the MODULE.bazel file will not be effective.</p></td> -</tr> -<tr> -<td id="single_version_override.patch_strip"><code>patch_strip</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>0</code><br /> -Same as the --strip argument of Unix patch.</td> -</tr> -</tbody> -</table> - -## use_extension - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | +| `version` | [string](../core/string.mdx); default is `''` Overrides the declared version of this module in the dependency graph. In other words, this module will be "pinned" to this override version. This attribute can be omitted if all one wants to override is the registry or the patches. | +| `registry` | [string](../core/string.mdx); default is `''` Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. | +| `patches` | Iterable of [string](../core/string.mdx)s; default is `[]` A list of labels pointing to patch files to apply for this module. The patch files must exist in the source tree of the top level project. They are applied in the list order. If a patch makes changes to the MODULE.bazel file, these changes will only be effective if the patch file is provided by the root module. | +| `patch_cmds` | Iterable of [string](../core/string.mdx)s; default is `[]` Sequence of Bash commands to be applied on Linux/Macos after patches are applied. Changes to the MODULE.bazel file will not be effective. | +| `patch_strip` | [int](../core/int.mdx); default is `0` Same as the --strip argument of Unix patch. | + +## use\_extension + +``` module_extension_proxy use_extension(extension_bzl_file, extension_name, *, dev_dependency=False, isolate=False) ``` @@ -589,46 +274,16 @@ Returns a proxy object representing a module extension; its methods can be invok ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="use_extension.extension_bzl_file"><code>extension_bzl_file</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A label to the Starlark file defining the module extension.</td> -</tr> -<tr> -<td id="use_extension.extension_name"><code>extension_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the module extension to use. A symbol with this name must be exported by the Starlark file.</td> -</tr> -<tr> -<td id="use_extension.dev_dependency"><code>dev_dependency</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, this usage of the module extension will be ignored if the current module is not the root module or `--ignore_dev_dependency` is enabled.</td> -</tr> -<tr> -<td id="use_extension.isolate"><code>isolate</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -<strong>Experimental</strong>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_isolated_extension_usages</code><br /> -If true, this usage of the module extension will be isolated from all other usages, both in this and other modules. Tags created for this usage do not affect other usages and the repositories generated by the extension for this usage will be distinct from all other repositories generated by the extension. -<p>This parameter is currently experimental and only available with the flag <code>--experimental_isolated_extension_usages</code>.</p></td> -</tr> -</tbody> -</table> - -## use_repo - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `extension_bzl_file` | [string](../core/string.mdx); required A label to the Starlark file defining the module extension. | +| `extension_name` | [string](../core/string.mdx); required The name of the module extension to use. A symbol with this name must be exported by the Starlark file. | +| `dev_dependency` | [bool](../core/bool.mdx); default is `False` If true, this usage of the module extension will be ignored if the current module is not the root module or `--ignore\_dev\_dependency` is enabled. | +| `isolate` | [bool](../core/bool.mdx); default is `False` **Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_isolated_extension_usages` If true, this usage of the module extension will be isolated from all other usages, both in this and other modules. Tags created for this usage do not affect other usages and the repositories generated by the extension for this usage will be distinct from all other repositories generated by the extension. This parameter is currently experimental and only available with the flag `--experimental_isolated_extension_usages`. | + +## use\_repo + +``` None use_repo(extension_proxy, *args, **kwargs) ``` @@ -636,42 +291,15 @@ Imports one or more repos generated by the given module extension into the scope ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="use_repo.extension_proxy"><code>extension_proxy</code></td> -<td>module_extension_proxy; -required<br /> -A module extension proxy object returned by a <code>use_extension</code> call.</td> -</tr> -<tr> -<td id="use_repo.args"><code>args</code></td> -<td>required<br /> -The names of the repos to import.</td> -</tr> -<tr> -<td id="use_repo.kwargs"><code>kwargs</code></td> -<td>required<br /> -Specifies certain repos to import into the scope of the current module with -different names. The keys should be the name to use in the current scope, -whereas the values should be the original names exported by the module -extension. -<p>Keys that are not valid identifiers can be specified via a literal dict -passed as extra keyword arguments, e.g., -<code>use_repo(extension_proxy, **{"foo.2": "foo"})</code>.</p></td> -</tr> -</tbody> -</table> - -## use_repo_rule - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `extension_proxy` | module\_extension\_proxy; required | +| `args` | required The names of the repos to import. | +| `kwargs` | required Specifies certain repos to import into the scope of the current module with different names. The keys should be the name to use in the current scope, whereas the values should be the original names exported by the module extension. Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., `use_repo(extension_proxy, **\{"foo.2": "foo"\})`. | + +## use\_repo\_rule + +``` repo_rule_proxy use_repo_rule(repo_rule_bzl_file, repo_rule_name) ``` @@ -679,25 +307,7 @@ Returns a proxy value that can be directly invoked in the MODULE.bazel file as a ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="use_repo_rule.repo_rule_bzl_file"><code>repo_rule_bzl_file</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A label to the Starlark file defining the repo rule.</td> -</tr> -<tr> -<td id="use_repo_rule.repo_rule_name"><code>repo_rule_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the repo rule to use. A symbol with this name must be exported by the Starlark file.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `repo_rule_bzl_file` | [string](../core/string.mdx); required A label to the Starlark file defining the repo rule. | +| `repo_rule_name` | [string](../core/string.mdx); required The name of the repo rule to use. A symbol with this name must be exported by the Starlark file. | \ No newline at end of file diff --git a/rules/lib/globals/repo.mdx b/rules/lib/globals/repo.mdx index 979443f..afe8793 100644 --- a/rules/lib/globals/repo.mdx +++ b/rules/lib/globals/repo.mdx @@ -2,20 +2,17 @@ title: 'repo' --- -# REPO.bazel files -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} Methods available in REPO.bazel files. ## Members -- [ignore_directories](#ignore_directories) -- [repo](#repo) +* [ignore\_directories](#ignore_directories) +* [repo](#repo) -## ignore_directories +## ignore\_directories -``` rule-signature +``` None ignore_directories(dirs) ``` @@ -25,26 +22,13 @@ This function takes a list of strings and a directory is ignored if any of the g ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="ignore_directories.dirs"><code>dirs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `dirs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required | ## repo -``` rule-signature +``` None repo(**kwargs) ``` @@ -52,18 +36,6 @@ Declares metadata that applies to every rule in the repository. It must be calle ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="repo.kwargs"><code>kwargs</code></td> -<td>required<br /> -The <code>repo()</code> function accepts exactly the same arguments as the <a href="/reference/be/functions#package"><code>package()</code></a> function in BUILD files.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `kwargs` | required The `repo()` function accepts exactly the same arguments as the [`package()`](./reference/be/functions#package) function in BUILD files. | \ No newline at end of file diff --git a/rules/lib/globals/vendor.mdx b/rules/lib/globals/vendor.mdx index bda7740..2178490 100644 --- a/rules/lib/globals/vendor.mdx +++ b/rules/lib/globals/vendor.mdx @@ -2,20 +2,17 @@ title: 'vendor' --- -# VENDOR.bazel files -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} Methods available in VENDOR.bazel files. ## Members -- [ignore](#ignore) -- [pin](#pin) +* [ignore](#ignore) +* [pin](#pin) ## ignore -``` rule-signature +``` None ignore(*args) ``` @@ -23,44 +20,20 @@ Ignore this repo from vendoring. Bazel will never vendor it or use the correspon ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="ignore.args"><code>args</code></td> -<td>required<br /> -The canonical repo names of the repos to ignore.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `args` | required The canonical repo names of the repos to ignore. | ## pin -``` rule-signature +``` None pin(*args) ``` -Pin the contents of this repo under the vendor directory. Bazel will not update this repo while vendoring, and will use the vendored source as if there is a --override_repository flag when building in vendor mode +Pin the contents of this repo under the vendor directory. Bazel will not update this repo while vendoring, and will use the vendored source as if there is a --override\_repository flag when building in vendor mode ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="pin.args"><code>args</code></td> -<td>required<br /> -The canonical repo names of the repos to pin.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `args` | required The canonical repo names of the repos to pin. | \ No newline at end of file diff --git a/rules/lib/overview.mdx b/rules/lib/overview.mdx index 4740201..c5e801e 100644 --- a/rules/lib/overview.mdx +++ b/rules/lib/overview.mdx @@ -2,153 +2,149 @@ title: 'overview' --- -# One-Page Overview -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm" %} -{% include "\_buttons.html" %} +## [Global functions](./rules/lib/globals) -## [Global functions](/rules/lib/globals) +* [.bzl files](./rules/lib/globals/bzl) +* [All Bazel files](./rules/lib/globals/all) +* [BUILD files](./rules/lib/globals/build) +* [MODULE.bazel files](./rules/lib/globals/module) +* [REPO.bazel files](./rules/lib/globals/repo) +* [VENDOR.bazel files](./rules/lib/globals/vendor) -- [.bzl files](/rules/lib/globals/bzl) -- [All Bazel files](/rules/lib/globals/all) -- [BUILD files](/rules/lib/globals/build) -- [MODULE.bazel files](/rules/lib/globals/module) -- [REPO.bazel files](/rules/lib/globals/repo) -- [VENDOR.bazel files](/rules/lib/globals/vendor) +## [Configuration Fragments](./rules/lib/fragments) -## [Configuration Fragments](/rules/lib/fragments) +* [apple](./rules/lib/fragments/apple) +* [bazel\_android](./rules/lib/fragments/bazel_android) +* [bazel\_py](./rules/lib/fragments/bazel_py) +* [coverage](./rules/lib/fragments/coverage) +* [cpp](./rules/lib/fragments/cpp) +* [j2objc](./rules/lib/fragments/j2objc) +* [java](./rules/lib/fragments/java) +* [objc](./rules/lib/fragments/objc) +* [platform](./rules/lib/fragments/platform) +* [proto](./rules/lib/fragments/proto) +* [py](./rules/lib/fragments/py) -- [apple](/rules/lib/fragments/apple) -- [bazel_android](/rules/lib/fragments/bazel_android) -- [bazel_py](/rules/lib/fragments/bazel_py) -- [coverage](/rules/lib/fragments/coverage) -- [cpp](/rules/lib/fragments/cpp) -- [j2objc](/rules/lib/fragments/j2objc) -- [java](/rules/lib/fragments/java) -- [objc](/rules/lib/fragments/objc) -- [platform](/rules/lib/fragments/platform) -- [proto](/rules/lib/fragments/proto) -- [py](/rules/lib/fragments/py) +## [Providers](./rules/lib/providers) -## [Providers](/rules/lib/providers) +* [AnalysisTestResultInfo](./rules/lib/providers/AnalysisTestResultInfo) +* [CcInfo](./rules/lib/providers/CcInfo) +* [CcToolchainConfigInfo](./rules/lib/providers/CcToolchainConfigInfo) +* [CcToolchainInfo](./rules/lib/providers/CcToolchainInfo) +* [ConstraintCollection](./rules/lib/providers/ConstraintCollection) +* [ConstraintSettingInfo](./rules/lib/providers/ConstraintSettingInfo) +* [ConstraintValueInfo](./rules/lib/providers/ConstraintValueInfo) +* [DebugPackageInfo](./rules/lib/providers/DebugPackageInfo) +* [DefaultInfo](./rules/lib/providers/DefaultInfo) +* [ExecutionInfo](./rules/lib/providers/ExecutionInfo) +* [FeatureFlagInfo](./rules/lib/providers/FeatureFlagInfo) +* [file\_provider](./rules/lib/providers/file_provider) +* [FilesToRunProvider](./rules/lib/providers/FilesToRunProvider) +* [IncompatiblePlatformProvider](./rules/lib/providers/IncompatiblePlatformProvider) +* [InstrumentedFilesInfo](./rules/lib/providers/InstrumentedFilesInfo) +* [java\_compilation\_info](./rules/lib/providers/java_compilation_info) +* [java\_output\_jars](./rules/lib/providers/java_output_jars) +* [JavaRuntimeInfo](./rules/lib/providers/JavaRuntimeInfo) +* [JavaToolchainInfo](./rules/lib/providers/JavaToolchainInfo) +* [MaterializedDepsInfo](./rules/lib/providers/MaterializedDepsInfo) +* [ObjcProvider](./rules/lib/providers/ObjcProvider) +* [OutputGroupInfo](./rules/lib/providers/OutputGroupInfo) +* [PackageSpecificationInfo](./rules/lib/providers/PackageSpecificationInfo) +* [PlatformInfo](./rules/lib/providers/PlatformInfo) +* [RunEnvironmentInfo](./rules/lib/providers/RunEnvironmentInfo) +* [TemplateVariableInfo](./rules/lib/providers/TemplateVariableInfo) +* [ToolchainInfo](./rules/lib/providers/ToolchainInfo) +* [ToolchainTypeInfo](./rules/lib/providers/ToolchainTypeInfo) -- [AnalysisTestResultInfo](/rules/lib/providers/AnalysisTestResultInfo) -- [CcInfo](/rules/lib/providers/CcInfo) -- [CcToolchainConfigInfo](/rules/lib/providers/CcToolchainConfigInfo) -- [CcToolchainInfo](/rules/lib/providers/CcToolchainInfo) -- [ConstraintCollection](/rules/lib/providers/ConstraintCollection) -- [ConstraintSettingInfo](/rules/lib/providers/ConstraintSettingInfo) -- [ConstraintValueInfo](/rules/lib/providers/ConstraintValueInfo) -- [DebugPackageInfo](/rules/lib/providers/DebugPackageInfo) -- [DefaultInfo](/rules/lib/providers/DefaultInfo) -- [ExecutionInfo](/rules/lib/providers/ExecutionInfo) -- [FeatureFlagInfo](/rules/lib/providers/FeatureFlagInfo) -- [file_provider](/rules/lib/providers/file_provider) -- [FilesToRunProvider](/rules/lib/providers/FilesToRunProvider) -- [IncompatiblePlatformProvider](/rules/lib/providers/IncompatiblePlatformProvider) -- [InstrumentedFilesInfo](/rules/lib/providers/InstrumentedFilesInfo) -- [java_compilation_info](/rules/lib/providers/java_compilation_info) -- [java_output_jars](/rules/lib/providers/java_output_jars) -- [JavaRuntimeInfo](/rules/lib/providers/JavaRuntimeInfo) -- [JavaToolchainInfo](/rules/lib/providers/JavaToolchainInfo) -- [MaterializedDepsInfo](/rules/lib/providers/MaterializedDepsInfo) -- [ObjcProvider](/rules/lib/providers/ObjcProvider) -- [OutputGroupInfo](/rules/lib/providers/OutputGroupInfo) -- [PackageSpecificationInfo](/rules/lib/providers/PackageSpecificationInfo) -- [PlatformInfo](/rules/lib/providers/PlatformInfo) -- [RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo) -- [TemplateVariableInfo](/rules/lib/providers/TemplateVariableInfo) -- [ToolchainInfo](/rules/lib/providers/ToolchainInfo) -- [ToolchainTypeInfo](/rules/lib/providers/ToolchainTypeInfo) +## [Built-in Types](./rules/lib/builtins) -## [Built-in Types](/rules/lib/builtins) +* [Action](./rules/lib/builtins/Action) +* [actions](./rules/lib/builtins/actions) +* [apple\_platform](./rules/lib/builtins/apple_platform) +* [Args](./rules/lib/builtins/Args) +* [Aspect](./rules/lib/builtins/Aspect) +* [Attribute](./rules/lib/builtins/Attribute) +* [bazel\_module](./rules/lib/builtins/bazel_module) +* [bazel\_module\_tags](./rules/lib/builtins/bazel_module_tags) +* [BuildSetting](./rules/lib/builtins/BuildSetting) +* [CcCompilationOutputs](./rules/lib/builtins/CcCompilationOutputs) +* [CcLinkingOutputs](./rules/lib/builtins/CcLinkingOutputs) +* [CompilationContext](./rules/lib/builtins/CompilationContext) +* [configuration](./rules/lib/builtins/configuration) +* [ctx](./rules/lib/builtins/ctx) +* [depset](./rules/lib/builtins/depset) +* [DirectoryExpander](./rules/lib/builtins/DirectoryExpander) +* [DottedVersion](./rules/lib/builtins/DottedVersion) +* [exec\_result](./rules/lib/builtins/exec_result) +* [ExecGroupCollection](./rules/lib/builtins/ExecGroupCollection) +* [ExecGroupContext](./rules/lib/builtins/ExecGroupContext) +* [ExecTransitionFactory](./rules/lib/builtins/ExecTransitionFactory) +* [ExpandedDirectory](./rules/lib/builtins/ExpandedDirectory) +* [extension\_metadata](./rules/lib/builtins/extension_metadata) +* [FeatureConfiguration](./rules/lib/builtins/FeatureConfiguration) +* [File](./rules/lib/builtins/File) +* [fragments](./rules/lib/builtins/fragments) +* [java\_annotation\_processing](./rules/lib/builtins/java_annotation_processing) +* [Label](./rules/lib/builtins/Label) +* [LateBoundDefault](./rules/lib/builtins/LateBoundDefault) +* [LibraryToLink](./rules/lib/builtins/LibraryToLink) +* [License](./rules/lib/builtins/License) +* [LinkerInput](./rules/lib/builtins/LinkerInput) +* [LinkingContext](./rules/lib/builtins/LinkingContext) +* [macro](./rules/lib/builtins/macro) +* [mapped\_root](./rules/lib/builtins/mapped_root) +* [module\_ctx](./rules/lib/builtins/module_ctx) +* [path](./rules/lib/builtins/path) +* [propagation\_ctx](./rules/lib/builtins/propagation_ctx) +* [Provider](./rules/lib/builtins/Provider) +* [repo\_metadata](./rules/lib/builtins/repo_metadata) +* [repository\_ctx](./rules/lib/builtins/repository_ctx) +* [repository\_os](./rules/lib/builtins/repository_os) +* [repository\_rule](./rules/lib/builtins/repository_rule) +* [root](./rules/lib/builtins/root) +* [rule](./rules/lib/builtins/rule) +* [rule\_attributes](./rules/lib/builtins/rule_attributes) +* [runfiles](./rules/lib/builtins/runfiles) +* [struct](./rules/lib/builtins/struct) +* [Subrule](./rules/lib/builtins/Subrule) +* [subrule\_ctx](./rules/lib/builtins/subrule_ctx) +* [SymlinkEntry](./rules/lib/builtins/SymlinkEntry) +* [tag\_class](./rules/lib/builtins/tag_class) +* [Target](./rules/lib/builtins/Target) +* [template\_ctx](./rules/lib/builtins/template_ctx) +* [TemplateDict](./rules/lib/builtins/TemplateDict) +* [toolchain\_type](./rules/lib/builtins/toolchain_type) +* [ToolchainContext](./rules/lib/builtins/ToolchainContext) +* [transition](./rules/lib/builtins/transition) +* [wasm\_exec\_result](./rules/lib/builtins/wasm_exec_result) +* [wasm\_module](./rules/lib/builtins/wasm_module) -- [Action](/rules/lib/builtins/Action) -- [actions](/rules/lib/builtins/actions) -- [apple_platform](/rules/lib/builtins/apple_platform) -- [Args](/rules/lib/builtins/Args) -- [Aspect](/rules/lib/builtins/Aspect) -- [Attribute](/rules/lib/builtins/Attribute) -- [bazel_module](/rules/lib/builtins/bazel_module) -- [bazel_module_tags](/rules/lib/builtins/bazel_module_tags) -- [BuildSetting](/rules/lib/builtins/BuildSetting) -- [CcCompilationOutputs](/rules/lib/builtins/CcCompilationOutputs) -- [CcLinkingOutputs](/rules/lib/builtins/CcLinkingOutputs) -- [CompilationContext](/rules/lib/builtins/CompilationContext) -- [configuration](/rules/lib/builtins/configuration) -- [ctx](/rules/lib/builtins/ctx) -- [depset](/rules/lib/builtins/depset) -- [DirectoryExpander](/rules/lib/builtins/DirectoryExpander) -- [DottedVersion](/rules/lib/builtins/DottedVersion) -- [exec_result](/rules/lib/builtins/exec_result) -- [ExecGroupCollection](/rules/lib/builtins/ExecGroupCollection) -- [ExecGroupContext](/rules/lib/builtins/ExecGroupContext) -- [ExecTransitionFactory](/rules/lib/builtins/ExecTransitionFactory) -- [ExpandedDirectory](/rules/lib/builtins/ExpandedDirectory) -- [extension_metadata](/rules/lib/builtins/extension_metadata) -- [FeatureConfiguration](/rules/lib/builtins/FeatureConfiguration) -- [File](/rules/lib/builtins/File) -- [fragments](/rules/lib/builtins/fragments) -- [java_annotation_processing](/rules/lib/builtins/java_annotation_processing) -- [Label](/rules/lib/builtins/Label) -- [LateBoundDefault](/rules/lib/builtins/LateBoundDefault) -- [LibraryToLink](/rules/lib/builtins/LibraryToLink) -- [License](/rules/lib/builtins/License) -- [LinkerInput](/rules/lib/builtins/LinkerInput) -- [LinkingContext](/rules/lib/builtins/LinkingContext) -- [macro](/rules/lib/builtins/macro) -- [mapped_root](/rules/lib/builtins/mapped_root) -- [module_ctx](/rules/lib/builtins/module_ctx) -- [path](/rules/lib/builtins/path) -- [propagation_ctx](/rules/lib/builtins/propagation_ctx) -- [Provider](/rules/lib/builtins/Provider) -- [repo_metadata](/rules/lib/builtins/repo_metadata) -- [repository_ctx](/rules/lib/builtins/repository_ctx) -- [repository_os](/rules/lib/builtins/repository_os) -- [repository_rule](/rules/lib/builtins/repository_rule) -- [root](/rules/lib/builtins/root) -- [rule](/rules/lib/builtins/rule) -- [rule_attributes](/rules/lib/builtins/rule_attributes) -- [runfiles](/rules/lib/builtins/runfiles) -- [struct](/rules/lib/builtins/struct) -- [Subrule](/rules/lib/builtins/Subrule) -- [subrule_ctx](/rules/lib/builtins/subrule_ctx) -- [SymlinkEntry](/rules/lib/builtins/SymlinkEntry) -- [tag_class](/rules/lib/builtins/tag_class) -- [Target](/rules/lib/builtins/Target) -- [template_ctx](/rules/lib/builtins/template_ctx) -- [TemplateDict](/rules/lib/builtins/TemplateDict) -- [toolchain_type](/rules/lib/builtins/toolchain_type) -- [ToolchainContext](/rules/lib/builtins/ToolchainContext) -- [transition](/rules/lib/builtins/transition) -- [wasm_exec_result](/rules/lib/builtins/wasm_exec_result) -- [wasm_module](/rules/lib/builtins/wasm_module) +## [Top-level Modules](./rules/lib/toplevel) -## [Top-level Modules](/rules/lib/toplevel) +* [apple\_common](./rules/lib/toplevel/apple_common) +* [attr](./rules/lib/toplevel/attr) +* [cc\_common](./rules/lib/toplevel/cc_common) +* [config](./rules/lib/toplevel/config) +* [config\_common](./rules/lib/toplevel/config_common) +* [coverage\_common](./rules/lib/toplevel/coverage_common) +* [java\_common](./rules/lib/toplevel/java_common) +* [native](./rules/lib/toplevel/native) +* [platform\_common](./rules/lib/toplevel/platform_common) +* [proto](./rules/lib/toplevel/proto) +* [testing](./rules/lib/toplevel/testing) -- [apple_common](/rules/lib/toplevel/apple_common) -- [attr](/rules/lib/toplevel/attr) -- [cc_common](/rules/lib/toplevel/cc_common) -- [config](/rules/lib/toplevel/config) -- [config_common](/rules/lib/toplevel/config_common) -- [coverage_common](/rules/lib/toplevel/coverage_common) -- [java_common](/rules/lib/toplevel/java_common) -- [native](/rules/lib/toplevel/native) -- [platform_common](/rules/lib/toplevel/platform_common) -- [proto](/rules/lib/toplevel/proto) -- [testing](/rules/lib/toplevel/testing) +## [Core Starlark data types](./rules/lib/core) -## [Core Starlark data types](/rules/lib/core) - -- [bool](/rules/lib/core/bool) -- [builtin_function_or_method](/rules/lib/core/builtin_function_or_method) -- [dict](/rules/lib/core/dict) -- [float](/rules/lib/core/float) -- [function](/rules/lib/core/function) -- [int](/rules/lib/core/int) -- [json](/rules/lib/core/json) -- [list](/rules/lib/core/list) -- [range](/rules/lib/core/range) -- [set](/rules/lib/core/set) -- [string](/rules/lib/core/string) -- [tuple](/rules/lib/core/tuple) +* [bool](./rules/lib/core/bool) +* [builtin\_function\_or\_method](./rules/lib/core/builtin_function_or_method) +* [dict](./rules/lib/core/dict) +* [float](./rules/lib/core/float) +* [function](./rules/lib/core/function) +* [int](./rules/lib/core/int) +* [json](./rules/lib/core/json) +* [list](./rules/lib/core/list) +* [range](./rules/lib/core/range) +* [set](./rules/lib/core/set) +* [string](./rules/lib/core/string) +* [tuple](./rules/lib/core/tuple) \ No newline at end of file diff --git a/rules/lib/providers.mdx b/rules/lib/providers.mdx index ab815e6..228eaf6 100644 --- a/rules/lib/providers.mdx +++ b/rules/lib/providers.mdx @@ -2,37 +2,34 @@ title: 'providers' --- -# Providers -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} This section lists providers available on built-in rules. See the [Rules page](https://bazel.build/extending/rules#providers) for more on providers. These symbols are available only in .bzl files. -- [AnalysisTestResultInfo](/rules/lib/providers/AnalysisTestResultInfo) -- [CcInfo](/rules/lib/providers/CcInfo) -- [CcToolchainConfigInfo](/rules/lib/providers/CcToolchainConfigInfo) -- [CcToolchainInfo](/rules/lib/providers/CcToolchainInfo) -- [ConstraintCollection](/rules/lib/providers/ConstraintCollection) -- [ConstraintSettingInfo](/rules/lib/providers/ConstraintSettingInfo) -- [ConstraintValueInfo](/rules/lib/providers/ConstraintValueInfo) -- [DebugPackageInfo](/rules/lib/providers/DebugPackageInfo) -- [DefaultInfo](/rules/lib/providers/DefaultInfo) -- [ExecutionInfo](/rules/lib/providers/ExecutionInfo) -- [FeatureFlagInfo](/rules/lib/providers/FeatureFlagInfo) -- [file_provider](/rules/lib/providers/file_provider) -- [FilesToRunProvider](/rules/lib/providers/FilesToRunProvider) -- [IncompatiblePlatformProvider](/rules/lib/providers/IncompatiblePlatformProvider) -- [InstrumentedFilesInfo](/rules/lib/providers/InstrumentedFilesInfo) -- [java_compilation_info](/rules/lib/providers/java_compilation_info) -- [java_output_jars](/rules/lib/providers/java_output_jars) -- [JavaRuntimeInfo](/rules/lib/providers/JavaRuntimeInfo) -- [JavaToolchainInfo](/rules/lib/providers/JavaToolchainInfo) -- [MaterializedDepsInfo](/rules/lib/providers/MaterializedDepsInfo) -- [ObjcProvider](/rules/lib/providers/ObjcProvider) -- [OutputGroupInfo](/rules/lib/providers/OutputGroupInfo) -- [PackageSpecificationInfo](/rules/lib/providers/PackageSpecificationInfo) -- [PlatformInfo](/rules/lib/providers/PlatformInfo) -- [RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo) -- [TemplateVariableInfo](/rules/lib/providers/TemplateVariableInfo) -- [ToolchainInfo](/rules/lib/providers/ToolchainInfo) -- [ToolchainTypeInfo](/rules/lib/providers/ToolchainTypeInfo) +* [AnalysisTestResultInfo](./rules/lib/providers/AnalysisTestResultInfo) +* [CcInfo](./rules/lib/providers/CcInfo) +* [CcToolchainConfigInfo](./rules/lib/providers/CcToolchainConfigInfo) +* [CcToolchainInfo](./rules/lib/providers/CcToolchainInfo) +* [ConstraintCollection](./rules/lib/providers/ConstraintCollection) +* [ConstraintSettingInfo](./rules/lib/providers/ConstraintSettingInfo) +* [ConstraintValueInfo](./rules/lib/providers/ConstraintValueInfo) +* [DebugPackageInfo](./rules/lib/providers/DebugPackageInfo) +* [DefaultInfo](./rules/lib/providers/DefaultInfo) +* [ExecutionInfo](./rules/lib/providers/ExecutionInfo) +* [FeatureFlagInfo](./rules/lib/providers/FeatureFlagInfo) +* [file\_provider](./rules/lib/providers/file_provider) +* [FilesToRunProvider](./rules/lib/providers/FilesToRunProvider) +* [IncompatiblePlatformProvider](./rules/lib/providers/IncompatiblePlatformProvider) +* [InstrumentedFilesInfo](./rules/lib/providers/InstrumentedFilesInfo) +* [java\_compilation\_info](./rules/lib/providers/java_compilation_info) +* [java\_output\_jars](./rules/lib/providers/java_output_jars) +* [JavaRuntimeInfo](./rules/lib/providers/JavaRuntimeInfo) +* [JavaToolchainInfo](./rules/lib/providers/JavaToolchainInfo) +* [MaterializedDepsInfo](./rules/lib/providers/MaterializedDepsInfo) +* [ObjcProvider](./rules/lib/providers/ObjcProvider) +* [OutputGroupInfo](./rules/lib/providers/OutputGroupInfo) +* [PackageSpecificationInfo](./rules/lib/providers/PackageSpecificationInfo) +* [PlatformInfo](./rules/lib/providers/PlatformInfo) +* [RunEnvironmentInfo](./rules/lib/providers/RunEnvironmentInfo) +* [TemplateVariableInfo](./rules/lib/providers/TemplateVariableInfo) +* [ToolchainInfo](./rules/lib/providers/ToolchainInfo) +* [ToolchainTypeInfo](./rules/lib/providers/ToolchainTypeInfo) \ No newline at end of file diff --git a/rules/lib/providers/AnalysisTestResultInfo.mdx b/rules/lib/providers/AnalysisTestResultInfo.mdx index d1bbd00..ccd82c6 100644 --- a/rules/lib/providers/AnalysisTestResultInfo.mdx +++ b/rules/lib/providers/AnalysisTestResultInfo.mdx @@ -2,21 +2,18 @@ title: 'AnalysisTestResultInfo' --- -# AnalysisTestResultInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/AnalysisTestResultInfoApi.java" %} -{% include "\_buttons.html" %} Encapsulates the result of analyis-phase testing. Build targets which return an instance of this provider signal to the build system that it should generate a 'stub' test executable which generates the equivalent test result. Analysis test rules (rules created with `analysis_test=True` **must** return an instance of this provider, and non-analysis-phase test rules **cannot** return this provider. ## Members -- [AnalysisTestResultInfo](#AnalysisTestResultInfo) -- [message](#message) -- [success](#success) +* [AnalysisTestResultInfo](#AnalysisTestResultInfo) +* [message](#message) +* [success](#success) ## AnalysisTestResultInfo -``` rule-signature +``` AnalysisTestResultInfo AnalysisTestResultInfo(success, message) ``` @@ -24,32 +21,14 @@ The `AnalysisTestResultInfo` constructor. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="AnalysisTestResultInfo.success"><code>success</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -required<br /> -If true, then the analysis-phase test represented by this target should pass. If false, the test should fail.</td> -</tr> -<tr> -<td id="AnalysisTestResultInfo.message"><code>message</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -A descriptive message containing information about the test and its success/failure.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `success` | [bool](../core/bool.mdx); required If true, then the analysis-phase test represented by this target should pass. If false, the test should fail. | +| `message` | [string](../core/string.mdx); required A descriptive message containing information about the test and its success/failure. | ## message -``` rule-signature +``` string AnalysisTestResultInfo.message ``` @@ -57,8 +36,8 @@ A descriptive message containing information about the test and its success/fail ## success -``` rule-signature +``` bool AnalysisTestResultInfo.success ``` -If true, then the analysis-phase test represented by this target passed. If false, the test failed. +If true, then the analysis-phase test represented by this target passed. If false, the test failed. \ No newline at end of file diff --git a/rules/lib/providers/CcInfo.mdx b/rules/lib/providers/CcInfo.mdx index 2120d5a..7067e5a 100644 --- a/rules/lib/providers/CcInfo.mdx +++ b/rules/lib/providers/CcInfo.mdx @@ -2,21 +2,18 @@ title: 'CcInfo' --- -# CcInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcInfoApi.java" %} -{% include "\_buttons.html" %} A provider for compilation and linking of C++. This is also a marking provider telling C++ rules that they can depend on the rule with this provider. If it is not intended for the rule to be depended on by C++, the rule should wrap the CcInfo in some other provider. ## Members -- [CcInfo](#CcInfo) -- [compilation_context](#compilation_context) -- [linking_context](#linking_context) +* [CcInfo](#CcInfo) +* [compilation\_context](#compilation_context) +* [linking\_context](#linking_context) ## CcInfo -``` rule-signature +``` CcInfo CcInfo(*, compilation_context=None, linking_context=None, debug_context=None) ``` @@ -24,47 +21,24 @@ The `CcInfo` constructor. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="CcInfo.compilation_context"><code>compilation_context</code></td> -<td><a href="../builtins/CompilationContext.html" class="anchor">CompilationContext</a>; or <code>None</code>; -default is <code>None</code><br /> -The <code>CompilationContext</code>.</td> -</tr> -<tr> -<td id="CcInfo.linking_context"><code>linking_context</code></td> -<td><a href="../builtins/struct.html" class="anchor">struct</a>; or <code>None</code>; -default is <code>None</code><br /> -The <code>LinkingContext</code>.</td> -</tr> -<tr> -<td id="CcInfo.debug_context"><code>debug_context</code></td> -<td><a href="../builtins/struct.html" class="anchor">struct</a>; or <code>None</code>; -default is <code>None</code><br /> -The <code>DebugContext</code>.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `compilation_context` | [CompilationContext](../builtins/CompilationContext.mdx); or `None`; default is `None` The `CompilationContext`. | +| `linking_context` | [struct](../builtins/struct.mdx); or `None`; default is `None` The `LinkingContext`. | +| `debug_context` | [struct](../builtins/struct.mdx); or `None`; default is `None` The `DebugContext`. | -## compilation_context +## compilation\_context -``` rule-signature +``` CompilationContext CcInfo.compilation_context ``` Returns the `CompilationContext` -## linking_context +## linking\_context -``` rule-signature +``` struct CcInfo.linking_context ``` -Returns the `LinkingContext` +Returns the `LinkingContext` \ No newline at end of file diff --git a/rules/lib/providers/CcToolchainConfigInfo.mdx b/rules/lib/providers/CcToolchainConfigInfo.mdx index 788e882..fe5e9c2 100644 --- a/rules/lib/providers/CcToolchainConfigInfo.mdx +++ b/rules/lib/providers/CcToolchainConfigInfo.mdx @@ -2,8 +2,5 @@ title: 'CcToolchainConfigInfo' --- -# CcToolchainConfigInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcToolchainConfigInfoApi.java" %} -{% include "\_buttons.html" %} -Additional layer of configurability for C++ rules. Encapsulates platform-dependent specifics of C++ actions through features and action configs. It is used to configure the C++ toolchain, and later on for command line construction. Replaces the functionality of CROSSTOOL file. +Additional layer of configurability for C++ rules. Encapsulates platform-dependent specifics of C++ actions through features and action configs. It is used to configure the C++ toolchain, and later on for command line construction. Replaces the functionality of CROSSTOOL file. \ No newline at end of file diff --git a/rules/lib/providers/CcToolchainInfo.mdx b/rules/lib/providers/CcToolchainInfo.mdx index a45733d..34452d8 100644 --- a/rules/lib/providers/CcToolchainInfo.mdx +++ b/rules/lib/providers/CcToolchainInfo.mdx @@ -2,53 +2,50 @@ title: 'CcToolchainInfo' --- -# CcToolchainInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcToolchainProviderApi.java" %} -{% include "\_buttons.html" %} Information about the C++ compiler being used. ## Members -- [all_files](#all_files) -- [ar_executable](#ar_executable) -- [built_in_include_directories](#built_in_include_directories) -- [compiler](#compiler) -- [compiler_executable](#compiler_executable) -- [cpu](#cpu) -- [dynamic_runtime_lib](#dynamic_runtime_lib) -- [gcov_executable](#gcov_executable) -- [ld_executable](#ld_executable) -- [libc](#libc) -- [needs_pic_for_dynamic_libraries](#needs_pic_for_dynamic_libraries) -- [nm_executable](#nm_executable) -- [objcopy_executable](#objcopy_executable) -- [objdump_executable](#objdump_executable) -- [preprocessor_executable](#preprocessor_executable) -- [static_runtime_lib](#static_runtime_lib) -- [strip_executable](#strip_executable) -- [sysroot](#sysroot) -- [target_gnu_system_name](#target_gnu_system_name) - -## all_files - -``` rule-signature +* [all\_files](#all_files) +* [ar\_executable](#ar_executable) +* [built\_in\_include\_directories](#built_in_include_directories) +* [compiler](#compiler) +* [compiler\_executable](#compiler_executable) +* [cpu](#cpu) +* [dynamic\_runtime\_lib](#dynamic_runtime_lib) +* [gcov\_executable](#gcov_executable) +* [ld\_executable](#ld_executable) +* [libc](#libc) +* [needs\_pic\_for\_dynamic\_libraries](#needs_pic_for_dynamic_libraries) +* [nm\_executable](#nm_executable) +* [objcopy\_executable](#objcopy_executable) +* [objdump\_executable](#objdump_executable) +* [preprocessor\_executable](#preprocessor_executable) +* [static\_runtime\_lib](#static_runtime_lib) +* [strip\_executable](#strip_executable) +* [sysroot](#sysroot) +* [target\_gnu\_system\_name](#target_gnu_system_name) + +## all\_files + +``` None CcToolchainInfo.all_files ``` Returns all toolchain files (so they can be passed to actions using this toolchain as inputs). -## ar_executable +## ar\_executable -``` rule-signature +``` None CcToolchainInfo.ar_executable ``` The path to the ar binary. -## built_in_include_directories +## built\_in\_include\_directories -``` rule-signature +``` None CcToolchainInfo.built_in_include_directories ``` @@ -56,15 +53,15 @@ Returns the list of built-in directories of the compiler. ## compiler -``` rule-signature +``` None CcToolchainInfo.compiler ``` C++ compiler. -## compiler_executable +## compiler\_executable -``` rule-signature +``` None CcToolchainInfo.compiler_executable ``` @@ -72,49 +69,37 @@ The path to the compiler binary. ## cpu -``` rule-signature +``` None CcToolchainInfo.cpu ``` Target CPU of the C++ toolchain. -## dynamic_runtime_lib +## dynamic\_runtime\_lib -``` rule-signature +``` None CcToolchainInfo.dynamic_runtime_lib(*, feature_configuration) ``` -Returns the files from \`dynamic_runtime_lib\` attribute (so they can be passed to actions using this toolchain as inputs). The caller can check whether the feature_configuration enables \`static_link_cpp_runtimes\` feature (if not, neither \`static_runtime_lib\` nor \`dynamic_runtime_lib\` have to be used), and use \`static_runtime_lib\` if static linking mode is active. +Returns the files from `dynamic\_runtime\_lib` attribute (so they can be passed to actions using this toolchain as inputs). The caller can check whether the feature\_configuration enables `static\_link\_cpp\_runtimes` feature (if not, neither `static\_runtime\_lib` nor `dynamic\_runtime\_lib` have to be used), and use `static\_runtime\_lib` if static linking mode is active. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="dynamic_runtime_lib.feature_configuration"><code>feature_configuration</code></td> -<td>required<br /> -Feature configuration to be queried.</td> -</tr> -</tbody> -</table> - -## gcov_executable - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `feature_configuration` | required Feature configuration to be queried. | + +## gcov\_executable + +``` None CcToolchainInfo.gcov_executable ``` The path to the gcov binary. -## ld_executable +## ld\_executable -``` rule-signature +``` None CcToolchainInfo.ld_executable ``` @@ -122,99 +107,75 @@ The path to the ld binary. ## libc -``` rule-signature +``` None CcToolchainInfo.libc ``` libc version string. -## needs_pic_for_dynamic_libraries +## needs\_pic\_for\_dynamic\_libraries -``` rule-signature +``` None CcToolchainInfo.needs_pic_for_dynamic_libraries(*, feature_configuration) ``` -Returns true if this rule's compilations should apply -fPIC, false otherwise. Determines if we should apply -fPIC for this rule's C++ compilations depending on the C++ toolchain and presence of \`--force_pic\` Bazel option. +Returns true if this rule's compilations should apply -fPIC, false otherwise. Determines if we should apply -fPIC for this rule's C++ compilations depending on the C++ toolchain and presence of `--force\_pic` Bazel option. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="needs_pic_for_dynamic_libraries.feature_configuration"><code>feature_configuration</code></td> -<td>required<br /> -Feature configuration to be queried.</td> -</tr> -</tbody> -</table> - -## nm_executable - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `feature_configuration` | required Feature configuration to be queried. | + +## nm\_executable + +``` None CcToolchainInfo.nm_executable ``` The path to the nm binary. -## objcopy_executable +## objcopy\_executable -``` rule-signature +``` None CcToolchainInfo.objcopy_executable ``` The path to the objcopy binary. -## objdump_executable +## objdump\_executable -``` rule-signature +``` None CcToolchainInfo.objdump_executable ``` The path to the objdump binary. -## preprocessor_executable +## preprocessor\_executable -``` rule-signature +``` None CcToolchainInfo.preprocessor_executable ``` The path to the preprocessor binary. -## static_runtime_lib +## static\_runtime\_lib -``` rule-signature +``` None CcToolchainInfo.static_runtime_lib(*, feature_configuration) ``` -Returns the files from \`static_runtime_lib\` attribute (so they can be passed to actions using this toolchain as inputs). The caller should check whether the feature_configuration enables \`static_link_cpp_runtimes\` feature (if not, neither \`static_runtime_lib\` nor \`dynamic_runtime_lib\` should be used), and use \`dynamic_runtime_lib\` if dynamic linking mode is active. +Returns the files from `static\_runtime\_lib` attribute (so they can be passed to actions using this toolchain as inputs). The caller should check whether the feature\_configuration enables `static\_link\_cpp\_runtimes` feature (if not, neither `static\_runtime\_lib` nor `dynamic\_runtime\_lib` should be used), and use `dynamic\_runtime\_lib` if dynamic linking mode is active. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="static_runtime_lib.feature_configuration"><code>feature_configuration</code></td> -<td>required<br /> -Feature configuration to be queried.</td> -</tr> -</tbody> -</table> - -## strip_executable - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `feature_configuration` | required Feature configuration to be queried. | + +## strip\_executable + +``` None CcToolchainInfo.strip_executable ``` @@ -222,16 +183,16 @@ The path to the strip binary. ## sysroot -``` rule-signature +``` None CcToolchainInfo.sysroot ``` Returns the sysroot to be used. If the toolchain compiler does not support different sysroots, or the sysroot is the same as the default sysroot, then this method returns `None`. -## target_gnu_system_name +## target\_gnu\_system\_name -``` rule-signature +``` None CcToolchainInfo.target_gnu_system_name ``` -The GNU System Name. +The GNU System Name. \ No newline at end of file diff --git a/rules/lib/providers/ConstraintCollection.mdx b/rules/lib/providers/ConstraintCollection.mdx index cc2ba7c..01eecb9 100644 --- a/rules/lib/providers/ConstraintCollection.mdx +++ b/rules/lib/providers/ConstraintCollection.mdx @@ -2,9 +2,6 @@ title: 'ConstraintCollection' --- -# ConstraintCollection -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintCollectionApi.java" %} -{% include "\_buttons.html" %} -Provides access to data about a collection of ConstraintValueInfo providers. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* +Provides access to data about a collection of ConstraintValueInfo providers. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* \ No newline at end of file diff --git a/rules/lib/providers/ConstraintSettingInfo.mdx b/rules/lib/providers/ConstraintSettingInfo.mdx index 1635b7d..df75d99 100644 --- a/rules/lib/providers/ConstraintSettingInfo.mdx +++ b/rules/lib/providers/ConstraintSettingInfo.mdx @@ -2,21 +2,18 @@ title: 'ConstraintSettingInfo' --- -# ConstraintSettingInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintSettingInfoApi.java" %} -{% include "\_buttons.html" %} -A specific constraint setting that may be used to define a platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. +A specific constraint setting that may be used to define a platform. See [Defining Constraints and Platforms](./docs/platforms#constraints-platforms) for more information. *Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* ## Members -- [has_default_constraint_value](#has_default_constraint_value) +* [has\_default\_constraint\_value](#has_default_constraint_value) -## has_default_constraint_value +## has\_default\_constraint\_value -``` rule-signature +``` bool ConstraintSettingInfo.has_default_constraint_value ``` -Whether there is a default constraint_value for this setting. +Whether there is a default constraint\_value for this setting. \ No newline at end of file diff --git a/rules/lib/providers/ConstraintValueInfo.mdx b/rules/lib/providers/ConstraintValueInfo.mdx index 262a6fa..fc5ffc3 100644 --- a/rules/lib/providers/ConstraintValueInfo.mdx +++ b/rules/lib/providers/ConstraintValueInfo.mdx @@ -2,9 +2,6 @@ title: 'ConstraintValueInfo' --- -# ConstraintValueInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ConstraintValueInfoApi.java" %} -{% include "\_buttons.html" %} -A value for a constraint setting that can be used to define a platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* +A value for a constraint setting that can be used to define a platform. See [Defining Constraints and Platforms](./docs/platforms#constraints-platforms) for more information. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* \ No newline at end of file diff --git a/rules/lib/providers/DebugPackageInfo.mdx b/rules/lib/providers/DebugPackageInfo.mdx index 62e52de..576e4c0 100644 --- a/rules/lib/providers/DebugPackageInfo.mdx +++ b/rules/lib/providers/DebugPackageInfo.mdx @@ -2,23 +2,20 @@ title: 'DebugPackageInfo' --- -# DebugPackageInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/DebugPackageInfoApi.java" %} -{% include "\_buttons.html" %} -A provider for the binary file and its associated .dwp files, if fission is enabled.If Fission ({@url https://gcc.gnu.org/wiki/DebugFission}) is not enabled, the dwp file will be null. +A provider for the binary file and its associated .dwp files, if fission is enabled.If Fission (\{@url https://gcc.gnu.org/wiki/DebugFission\}) is not enabled, the dwp file will be null. ## Members -- [DebugPackageInfo](#DebugPackageInfo) -- [dwp_file](#dwp_file) -- [stripped_file](#stripped_file) -- [target_label](#target_label) -- [unstripped_file](#unstripped_file) +* [DebugPackageInfo](#DebugPackageInfo) +* [dwp\_file](#dwp_file) +* [stripped\_file](#stripped_file) +* [target\_label](#target_label) +* [unstripped\_file](#unstripped_file) ## DebugPackageInfo -``` rule-signature +``` DebugPackageInfo DebugPackageInfo(*, target_label, stripped_file=None, unstripped_file, dwp_file=None) ``` @@ -26,71 +23,43 @@ The `DebugPackageInfo` constructor. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="DebugPackageInfo.target_label"><code>target_label</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; -required<br /> -The label for the *_binary target</td> -</tr> -<tr> -<td id="DebugPackageInfo.stripped_file"><code>stripped_file</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -The stripped file (the explicit ".stripped" target)</td> -</tr> -<tr> -<td id="DebugPackageInfo.unstripped_file"><code>unstripped_file</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The unstripped file (the default executable target).</td> -</tr> -<tr> -<td id="DebugPackageInfo.dwp_file"><code>dwp_file</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -The .dwp file (for fission builds) or null if --fission=no.</td> -</tr> -</tbody> -</table> - -## dwp_file - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `target_label` | [Label](../builtins/Label.mdx); required The label for the \*\_binary target | +| `stripped_file` | [File](../builtins/File.mdx); or `None`; default is `None` The stripped file (the explicit ".stripped" target) | +| `unstripped_file` | [File](../builtins/File.mdx); required The unstripped file (the default executable target). | +| `dwp_file` | [File](../builtins/File.mdx); or `None`; default is `None` The .dwp file (for fission builds) or null if --fission=no. | + +## dwp\_file + +``` File DebugPackageInfo.dwp_file ``` Returns the .dwp file (for fission builds) or null if --fission=no. May return `None`. -## stripped_file +## stripped\_file -``` rule-signature +``` File DebugPackageInfo.stripped_file ``` Returns the stripped file (the explicit ".stripped" target). May return `None`. -## target_label +## target\_label -``` rule-signature +``` Label DebugPackageInfo.target_label ``` Returns the label for the \*\_binary target -## unstripped_file +## unstripped\_file -``` rule-signature +``` File DebugPackageInfo.unstripped_file ``` -Returns the unstripped file (the default executable target) +Returns the unstripped file (the default executable target) \ No newline at end of file diff --git a/rules/lib/providers/DefaultInfo.mdx b/rules/lib/providers/DefaultInfo.mdx index 2678287..99c287a 100644 --- a/rules/lib/providers/DefaultInfo.mdx +++ b/rules/lib/providers/DefaultInfo.mdx @@ -2,25 +2,22 @@ title: 'DefaultInfo' --- -# DefaultInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java" %} -{% include "\_buttons.html" %} A provider that gives general information about a target's direct and transitive files. Every rule type has this provider, even if it is not returned explicitly by the rule's implementation function. See the [rules](https://bazel.build/extending/rules) page for extensive guides on how to use this provider. ## Members -- [DefaultInfo](#DefaultInfo) -- [data_runfiles](#data_runfiles) -- [default_runfiles](#default_runfiles) -- [files](#files) -- [files_to_run](#files_to_run) +* [DefaultInfo](#DefaultInfo) +* [data\_runfiles](#data_runfiles) +* [default\_runfiles](#default_runfiles) +* [files](#files) +* [files\_to\_run](#files_to_run) ## DefaultInfo -``` rule-signature +``` DefaultInfo DefaultInfo(*, files=None, runfiles=None, data_runfiles=None, default_runfiles=None, executable=None) ``` @@ -28,61 +25,26 @@ The `DefaultInfo` constructor. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="DefaultInfo.files"><code>files</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -A <a href="../builtins/depset.html"><code>depset</code></a> of <a href="../builtins/File.html"><code>File</code></a> objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs.</td> -</tr> -<tr> -<td id="DefaultInfo.runfiles"><code>runfiles</code></td> -<td><a href="../builtins/runfiles.html" class="anchor">runfiles</a>; or <code>None</code>; -default is <code>None</code><br /> -<a href="../builtins/runfiles.html"><code>runfiles</code></a> descriptor describing the files that this target needs when run (e.g. via the <code>run</code> command or as a tool dependency for an action).</td> -</tr> -<tr> -<td id="DefaultInfo.data_runfiles"><code>data_runfiles</code></td> -<td><a href="../builtins/runfiles.html" class="anchor">runfiles</a>; or <code>None</code>; -default is <code>None</code><br /> - <p><strong>It is recommended that you avoid using this parameter (see <a href="https://bazel.build/extending/rules#runfiles_features_to_avoid">"runfiles features to avoid"</a>)</strong></p> -runfiles descriptor describing the runfiles this target needs to run when it is a dependency via the <code>data</code> attribute.</td> -</tr> -<tr> -<td id="DefaultInfo.default_runfiles"><code>default_runfiles</code></td> -<td><a href="../builtins/runfiles.html" class="anchor">runfiles</a>; or <code>None</code>; -default is <code>None</code><br /> - <p><strong>It is recommended that you avoid using this parameter (see <a href="https://bazel.build/extending/rules#runfiles_features_to_avoid">"runfiles features to avoid"</a>)</strong></p> -runfiles descriptor describing the runfiles this target needs to run when it is a dependency via any attribute other than the <code>data</code> attribute.</td> -</tr> -<tr> -<td id="DefaultInfo.executable"><code>executable</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -If this rule is marked <a href="../globals/bzl.html#rule.executable"><code>executable</code></a> or <a href="../globals/bzl.html#rule.test"><code>test</code></a>, this is a <a href="../builtins/File.html"><code>File</code></a> object representing the file that should be executed to run the target. By default it is the predeclared output <code>ctx.outputs.executable</code> but it is recommended to pass another file (either predeclared or not) explicitly.</td> -</tr> -</tbody> -</table> - -## data_runfiles - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `files` | [depset](../builtins/depset.mdx); or `None`; default is `None` A [`depset`](../builtins/depset.mdx) of [`File`](../builtins/File.mdx) objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. | +| `runfiles` | [runfiles](../builtins/runfiles.mdx); or `None`; default is `None` [`runfiles`](../builtins/runfiles.mdx) descriptor describing the files that this target needs when run (e.g. via the `run` command or as a tool dependency for an action). | +| `data_runfiles` | [runfiles](../builtins/runfiles.mdx); or `None`; default is `None` **It is recommended that you avoid using this parameter (see ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid))** runfiles descriptor describing the runfiles this target needs to run when it is a dependency via the `data` attribute. | +| `default_runfiles` | [runfiles](../builtins/runfiles.mdx); or `None`; default is `None` **It is recommended that you avoid using this parameter (see ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid))** runfiles descriptor describing the runfiles this target needs to run when it is a dependency via any attribute other than the `data` attribute. | +| `executable` | [File](../builtins/File.mdx); or `None`; default is `None` If this rule is marked [`executable`](../globals/bzl.html#rule.executable) or [`test`](../globals/bzl.html#rule.test), this is a [`File`](../builtins/File.mdx) object representing the file that should be executed to run the target. By default it is the predeclared output `ctx.outputs.executable` but it is recommended to pass another file (either predeclared or not) explicitly. | + +## data\_runfiles + +``` runfiles DefaultInfo.data_runfiles ``` runfiles descriptor describing the files that this target needs when run in the condition that it is a `data` dependency attribute. Under most circumstances, use the `default_runfiles` parameter instead. See ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid) for details. May return `None`. -## default_runfiles +## default\_runfiles -``` rule-signature +``` runfiles DefaultInfo.default_runfiles ``` @@ -91,18 +53,18 @@ May return `None`. ## files -``` rule-signature +``` depset DefaultInfo.files ``` -A [`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. +A [`depset`](../builtins/depset.mdx) of [`File`](../builtins/File.mdx) objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. May return `None`. -## files_to_run +## files\_to\_run -``` rule-signature +``` FilesToRunProvider DefaultInfo.files_to_run ``` -A [`FilesToRunProvider`](../providers/FilesToRunProvider.html) object containing information about the executable and runfiles of the target. -May return `None`. +A [`FilesToRunProvider`](../providers/FilesToRunProvider.mdx) object containing information about the executable and runfiles of the target. +May return `None`. \ No newline at end of file diff --git a/rules/lib/providers/ExecutionInfo.mdx b/rules/lib/providers/ExecutionInfo.mdx index 39db8c3..4f05a00 100644 --- a/rules/lib/providers/ExecutionInfo.mdx +++ b/rules/lib/providers/ExecutionInfo.mdx @@ -2,54 +2,33 @@ title: 'ExecutionInfo' --- -# ExecutionInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/ExecutionInfoApi.java" %} -{% include "\_buttons.html" %} Use this provider to specify special environment requirements needed to run tests. ## Members -- [ExecutionInfo](#ExecutionInfo) -- [exec_group](#exec_group) -- [requirements](#requirements) +* [ExecutionInfo](#ExecutionInfo) +* [exec\_group](#exec_group) +* [requirements](#requirements) ## ExecutionInfo -``` rule-signature -ExecutionInfo ExecutionInfo(requirements={}, exec_group='test') +``` +ExecutionInfo ExecutionInfo(requirements=\{\}, exec_group='test') ``` Creates an instance. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="ExecutionInfo.requirements"><code>requirements</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A dict indicating special execution requirements, such as hardware platforms.</td> -</tr> -<tr> -<td id="ExecutionInfo.exec_group"><code>exec_group</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'test'</code><br /> -The name of the exec group that is used to execute the test.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `requirements` | [dict](../core/dict.mdx); default is `\{\}` A dict indicating special execution requirements, such as hardware platforms. | +| `exec_group` | [string](../core/string.mdx); default is `'test'` The name of the exec group that is used to execute the test. | -## exec_group +## exec\_group -``` rule-signature +``` string ExecutionInfo.exec_group ``` @@ -57,8 +36,8 @@ The name of the exec group that is used to execute the test. ## requirements -``` rule-signature +``` dict ExecutionInfo.requirements ``` -A dict indicating special execution requirements, such as hardware platforms. +A dict indicating special execution requirements, such as hardware platforms. \ No newline at end of file diff --git a/rules/lib/providers/FeatureFlagInfo.mdx b/rules/lib/providers/FeatureFlagInfo.mdx index fe90ac4..074c211 100644 --- a/rules/lib/providers/FeatureFlagInfo.mdx +++ b/rules/lib/providers/FeatureFlagInfo.mdx @@ -2,30 +2,27 @@ title: 'FeatureFlagInfo' --- -# FeatureFlagInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigFeatureFlagProviderApi.java" %} -{% include "\_buttons.html" %} -A provider used to access information about config_feature_flag rules. +A provider used to access information about config\_feature\_flag rules. ## Members -- [error](#error) -- [is_valid_value](#is_valid_value) -- [value](#value) +* [error](#error) +* [is\_valid\_value](#is_valid_value) +* [value](#value) ## error -``` rule-signature +``` string FeatureFlagInfo.error ``` If non-None, this error was generated when trying to compute current value of flag. May return `None`. -## is_valid_value +## is\_valid\_value -``` rule-signature +``` bool FeatureFlagInfo.is_valid_value(value) ``` @@ -33,28 +30,15 @@ The value of the flag in the configuration used by the flag rule. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="is_valid_value.value"><code>value</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -String, the value to check for validity for this flag.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `value` | [string](../core/string.mdx); required String, the value to check for validity for this flag. | ## value -``` rule-signature +``` string FeatureFlagInfo.value ``` The current value of the flag in the flag's current configuration. None if there is an error. -May return `None`. +May return `None`. \ No newline at end of file diff --git a/rules/lib/providers/FilesToRunProvider.mdx b/rules/lib/providers/FilesToRunProvider.mdx index 6f46edb..1f57856 100644 --- a/rules/lib/providers/FilesToRunProvider.mdx +++ b/rules/lib/providers/FilesToRunProvider.mdx @@ -2,41 +2,38 @@ title: 'FilesToRunProvider' --- -# FilesToRunProvider -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FilesToRunProviderApi.java" %} -{% include "\_buttons.html" %} Contains information about executables produced by a target and the files needed to run it. This provider can not be created directly, it is an implicit output of executable targets accessible via [`DefaultInfo.files_to_run`](../providers/DefaultInfo.html#files_to_run). ## Members -- [executable](#executable) -- [repo_mapping_manifest](#repo_mapping_manifest) -- [runfiles_manifest](#runfiles_manifest) +* [executable](#executable) +* [repo\_mapping\_manifest](#repo_mapping_manifest) +* [runfiles\_manifest](#runfiles_manifest) ## executable -``` rule-signature +``` File FilesToRunProvider.executable ``` The main executable or None if it does not exist. May return `None`. -## repo_mapping_manifest +## repo\_mapping\_manifest -``` rule-signature +``` File FilesToRunProvider.repo_mapping_manifest ``` The repo mapping manifest or None if it does not exist. May return `None`. -## runfiles_manifest +## runfiles\_manifest -``` rule-signature +``` File FilesToRunProvider.runfiles_manifest ``` The runfiles manifest or None if it does not exist. -May return `None`. +May return `None`. \ No newline at end of file diff --git a/rules/lib/providers/IncompatiblePlatformProvider.mdx b/rules/lib/providers/IncompatiblePlatformProvider.mdx index a080314..8c27379 100644 --- a/rules/lib/providers/IncompatiblePlatformProvider.mdx +++ b/rules/lib/providers/IncompatiblePlatformProvider.mdx @@ -2,8 +2,5 @@ title: 'IncompatiblePlatformProvider' --- -# IncompatiblePlatformProvider -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/IncompatiblePlatformProviderApi.java" %} -{% include "\_buttons.html" %} -A provider for targets that are incompatible with the target platform. See [Detecting incompatible targets using `bazel cquery`](/docs/platforms#detecting-incompatible-targets-using-bazel-cquery) for more information. +A provider for targets that are incompatible with the target platform. See [Detecting incompatible targets using `bazel cquery`](./docs/platforms#detecting-incompatible-targets-using-bazel-cquery) for more information. \ No newline at end of file diff --git a/rules/lib/providers/InstrumentedFilesInfo.mdx b/rules/lib/providers/InstrumentedFilesInfo.mdx index bffb123..597a63b 100644 --- a/rules/lib/providers/InstrumentedFilesInfo.mdx +++ b/rules/lib/providers/InstrumentedFilesInfo.mdx @@ -2,29 +2,26 @@ title: 'InstrumentedFilesInfo' --- -# InstrumentedFilesInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java" %} -{% include "\_buttons.html" %} Contains information about source files and instrumentation metadata files for rule targets matched by [`--instrumentation_filter`](https://bazel.build/reference/command-line-reference#flag--instrumentation_filter) for purposes of [code coverage data collection](https://bazel.build/extending/rules#code_coverage). When coverage data collection is enabled, a manifest containing the combined paths in [`instrumented_files`](#instrumented_files) and [`metadata_files`](#metadata_files) are passed to the test action as inputs, with the manifest's path noted in the environment variable `COVERAGE_MANIFEST`. The metadata files, but not the source files, are also passed to the test action as inputs. When `InstrumentedFilesInfo` is returned by an [aspect](https://bazel.build/extending/aspects)'s implementation function, any `InstrumentedFilesInfo` from the base rule target is ignored. ## Members -- [instrumented_files](#instrumented_files) -- [metadata_files](#metadata_files) +* [instrumented\_files](#instrumented_files) +* [metadata\_files](#metadata_files) -## instrumented_files +## instrumented\_files -``` rule-signature +``` depset InstrumentedFilesInfo.instrumented_files ``` -[`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing instrumented source files for this target and its dependencies. +[`depset`](../builtins/depset.mdx) of [`File`](../builtins/File.mdx) objects representing instrumented source files for this target and its dependencies. -## metadata_files +## metadata\_files -``` rule-signature +``` depset InstrumentedFilesInfo.metadata_files ``` -[`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing coverage metadata files for this target and its dependencies. These files contain additional information required to generate LCOV-format coverage output after the code is executed, e.g. the `.gcno` files generated when `gcc` is run with `-ftest-coverage`. +[`depset`](../builtins/depset.mdx) of [`File`](../builtins/File.mdx) objects representing coverage metadata files for this target and its dependencies. These files contain additional information required to generate LCOV-format coverage output after the code is executed, e.g. the `.gcno` files generated when `gcc` is run with `-ftest-coverage`. \ No newline at end of file diff --git a/rules/lib/providers/JavaRuntimeInfo.mdx b/rules/lib/providers/JavaRuntimeInfo.mdx index 953e39e..f332acf 100644 --- a/rules/lib/providers/JavaRuntimeInfo.mdx +++ b/rules/lib/providers/JavaRuntimeInfo.mdx @@ -2,29 +2,26 @@ title: 'JavaRuntimeInfo' --- -# JavaRuntimeInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaRuntimeInfoApi.java" %} -{% include "\_buttons.html" %} Information about the Java runtime being used. ## Members -- [default_cds](#default_cds) -- [files](#files) -- [hermetic_files](#hermetic_files) -- [hermetic_static_libs](#hermetic_static_libs) -- [java_executable_exec_path](#java_executable_exec_path) -- [java_executable_runfiles_path](#java_executable_runfiles_path) -- [java_home](#java_home) -- [java_home_runfiles_path](#java_home_runfiles_path) -- [lib_ct_sym](#lib_ct_sym) -- [lib_modules](#lib_modules) -- [version](#version) - -## default_cds - -``` rule-signature +* [default\_cds](#default_cds) +* [files](#files) +* [hermetic\_files](#hermetic_files) +* [hermetic\_static\_libs](#hermetic_static_libs) +* [java\_executable\_exec\_path](#java_executable_exec_path) +* [java\_executable\_runfiles\_path](#java_executable_runfiles_path) +* [java\_home](#java_home) +* [java\_home\_runfiles\_path](#java_home_runfiles_path) +* [lib\_ct\_sym](#lib_ct_sym) +* [lib\_modules](#lib_modules) +* [version](#version) + +## default\_cds + +``` File JavaRuntimeInfo.default_cds ``` @@ -33,72 +30,72 @@ May return `None`. ## files -``` rule-signature +``` depset JavaRuntimeInfo.files ``` Returns the files in the Java runtime. -## hermetic_files +## hermetic\_files -``` rule-signature +``` depset JavaRuntimeInfo.hermetic_files ``` Returns the files in the Java runtime needed for hermetic deployments. -## hermetic_static_libs +## hermetic\_static\_libs -``` rule-signature +``` sequence JavaRuntimeInfo.hermetic_static_libs ``` Returns the JDK static libraries. -## java_executable_exec_path +## java\_executable\_exec\_path -``` rule-signature +``` string JavaRuntimeInfo.java_executable_exec_path ``` Returns the execpath of the Java executable. -## java_executable_runfiles_path +## java\_executable\_runfiles\_path -``` rule-signature +``` string JavaRuntimeInfo.java_executable_runfiles_path ``` -Returns the path of the Java executable in runfiles trees. This should only be used when one needs to access the JVM during the execution of a binary or a test built by Bazel. In particular, when one needs to invoke the JVM during an action, java_executable_exec_path should be used instead. +Returns the path of the Java executable in runfiles trees. This should only be used when one needs to access the JVM during the execution of a binary or a test built by Bazel. In particular, when one needs to invoke the JVM during an action, java\_executable\_exec\_path should be used instead. -## java_home +## java\_home -``` rule-signature +``` string JavaRuntimeInfo.java_home ``` Returns the execpath of the root of the Java installation. -## java_home_runfiles_path +## java\_home\_runfiles\_path -``` rule-signature +``` string JavaRuntimeInfo.java_home_runfiles_path ``` -Returns the path of the Java installation in runfiles trees. This should only be used when one needs to access the JDK during the execution of a binary or a test built by Bazel. In particular, when one needs the JDK during an action, java_home should be used instead. +Returns the path of the Java installation in runfiles trees. This should only be used when one needs to access the JDK during the execution of a binary or a test built by Bazel. In particular, when one needs the JDK during an action, java\_home should be used instead. -## lib_ct_sym +## lib\_ct\_sym -``` rule-signature +``` File JavaRuntimeInfo.lib_ct_sym ``` Returns the lib/ct.sym file. May return `None`. -## lib_modules +## lib\_modules -``` rule-signature +``` File JavaRuntimeInfo.lib_modules ``` @@ -107,8 +104,8 @@ May return `None`. ## version -``` rule-signature +``` int JavaRuntimeInfo.version ``` -The Java feature version of the runtime. This is 0 if the version is unknown. +The Java feature version of the runtime. This is 0 if the version is unknown. \ No newline at end of file diff --git a/rules/lib/providers/JavaToolchainInfo.mdx b/rules/lib/providers/JavaToolchainInfo.mdx index c924433..b878ff1 100644 --- a/rules/lib/providers/JavaToolchainInfo.mdx +++ b/rules/lib/providers/JavaToolchainInfo.mdx @@ -2,29 +2,26 @@ title: 'JavaToolchainInfo' --- -# JavaToolchainInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaToolchainStarlarkApiProviderApi.java" %} -{% include "\_buttons.html" %} -Provides access to information about the Java toolchain rule. Accessible as a 'java_toolchain' field on a Target struct. +Provides access to information about the Java toolchain rule. Accessible as a 'java\_toolchain' field on a Target struct. ## Members -- [bootclasspath](#bootclasspath) -- [ijar](#ijar) -- [jacocorunner](#jacocorunner) -- [java_runtime](#java_runtime) -- [jvm_opt](#jvm_opt) -- [label](#label) -- [proguard_allowlister](#proguard_allowlister) -- [single_jar](#single_jar) -- [source_version](#source_version) -- [target_version](#target_version) -- [tools](#tools) +* [bootclasspath](#bootclasspath) +* [ijar](#ijar) +* [jacocorunner](#jacocorunner) +* [java\_runtime](#java_runtime) +* [jvm\_opt](#jvm_opt) +* [label](#label) +* [proguard\_allowlister](#proguard_allowlister) +* [single\_jar](#single_jar) +* [source\_version](#source_version) +* [target\_version](#target_version) +* [tools](#tools) ## bootclasspath -``` rule-signature +``` depset JavaToolchainInfo.bootclasspath ``` @@ -32,7 +29,7 @@ The Java target bootclasspath entries. Corresponds to javac's -bootclasspath fla ## ijar -``` rule-signature +``` FilesToRunProvider JavaToolchainInfo.ijar ``` @@ -40,24 +37,24 @@ A FilesToRunProvider representing the ijar executable. ## jacocorunner -``` rule-signature +``` FilesToRunProvider JavaToolchainInfo.jacocorunner ``` The jacocorunner used by the toolchain. May return `None`. -## java_runtime +## java\_runtime -``` rule-signature +``` JavaRuntimeInfo JavaToolchainInfo.java_runtime ``` The java runtime information. -## jvm_opt +## jvm\_opt -``` rule-signature +``` depset JavaToolchainInfo.jvm_opt ``` @@ -65,40 +62,40 @@ The default options for the JVM running the java compiler and associated tools. ## label -``` rule-signature +``` Label JavaToolchainInfo.label ``` The toolchain label. -## proguard_allowlister +## proguard\_allowlister -``` rule-signature +``` FilesToRunProvider JavaToolchainInfo.proguard_allowlister ``` Return the binary to validate proguard configuration May return `None`. -## single_jar +## single\_jar -``` rule-signature +``` FilesToRunProvider JavaToolchainInfo.single_jar ``` The SingleJar deploy jar. -## source_version +## source\_version -``` rule-signature +``` string JavaToolchainInfo.source_version ``` The java source version. -## target_version +## target\_version -``` rule-signature +``` string JavaToolchainInfo.target_version ``` @@ -106,8 +103,8 @@ The java target version. ## tools -``` rule-signature +``` depset JavaToolchainInfo.tools ``` -The compilation tools. +The compilation tools. \ No newline at end of file diff --git a/rules/lib/providers/MaterializedDepsInfo.mdx b/rules/lib/providers/MaterializedDepsInfo.mdx index 4aaf374..ce6c00c 100644 --- a/rules/lib/providers/MaterializedDepsInfo.mdx +++ b/rules/lib/providers/MaterializedDepsInfo.mdx @@ -2,20 +2,17 @@ title: 'MaterializedDepsInfo' --- -# MaterializedDepsInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/MaterializedDepsInfoApi.java" %} -{% include "\_buttons.html" %} The provider returned from materializer rules to materialize dependencies. ## Members -- [deps](#deps) +* [deps](#deps) ## deps -``` rule-signature +``` list MaterializedDepsInfo.deps ``` -The list of dependencies. These may be ConfiguredTarget or DormantDependency objects. +The list of dependencies. These may be ConfiguredTarget or DormantDependency objects. \ No newline at end of file diff --git a/rules/lib/providers/ObjcProvider.mdx b/rules/lib/providers/ObjcProvider.mdx index ac2ad41..1bb39cf 100644 --- a/rules/lib/providers/ObjcProvider.mdx +++ b/rules/lib/providers/ObjcProvider.mdx @@ -2,49 +2,46 @@ title: 'ObjcProvider' --- -# ObjcProvider -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/ObjcProviderApi.java" %} -{% include "\_buttons.html" %} A provider for compilation and linking of objc. ## Members -- [direct_module_maps](#direct_module_maps) -- [direct_sources](#direct_sources) -- [j2objc_library](#j2objc_library) -- [module_map](#module_map) -- [source](#source) -- [strict_include](#strict_include) -- [umbrella_header](#umbrella_header) +* [direct\_module\_maps](#direct_module_maps) +* [direct\_sources](#direct_sources) +* [j2objc\_library](#j2objc_library) +* [module\_map](#module_map) +* [source](#source) +* [strict\_include](#strict_include) +* [umbrella\_header](#umbrella_header) -## direct_module_maps +## direct\_module\_maps -``` rule-signature +``` sequence ObjcProvider.direct_module_maps ``` Module map files from this target directly (no transitive module maps). Used to enforce proper use of private header files and for Swift compilation. -## direct_sources +## direct\_sources -``` rule-signature +``` sequence ObjcProvider.direct_sources ``` All direct source files from this target (no transitive files), including any headers in the 'srcs' attribute. -## j2objc_library +## j2objc\_library -``` rule-signature +``` depset ObjcProvider.j2objc_library ``` Static libraries that are built from J2ObjC-translated Java code. -## module_map +## module\_map -``` rule-signature +``` depset ObjcProvider.module_map ``` @@ -52,24 +49,24 @@ Clang module maps, used to enforce proper use of private header files. ## source -``` rule-signature +``` depset ObjcProvider.source ``` All transitive source files. -## strict_include +## strict\_include -``` rule-signature +``` depset ObjcProvider.strict_include ``` Non-propagated include search paths specified with '-I' on the command line. Also known as header search paths (and distinct from *user* header search paths). -## umbrella_header +## umbrella\_header -``` rule-signature +``` depset ObjcProvider.umbrella_header ``` -Clang umbrella header. Public headers are \#included in umbrella headers to be compatible with J2ObjC segmented headers. +Clang umbrella header. Public headers are #included in umbrella headers to be compatible with J2ObjC segmented headers. \ No newline at end of file diff --git a/rules/lib/providers/OutputGroupInfo.mdx b/rules/lib/providers/OutputGroupInfo.mdx index e44fa62..b520695 100644 --- a/rules/lib/providers/OutputGroupInfo.mdx +++ b/rules/lib/providers/OutputGroupInfo.mdx @@ -2,45 +2,30 @@ title: 'OutputGroupInfo' --- -# OutputGroupInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/OutputGroupInfoApi.java" %} -{% include "\_buttons.html" %} A provider that indicates what output groups a rule has. See [Requesting output files](https://bazel.build/extending/rules#requesting_output_files) for more information. ## Members -- [OutputGroupInfo](#OutputGroupInfo) +* [OutputGroupInfo](#OutputGroupInfo) ## OutputGroupInfo -``` rule-signature +``` OutputGroupInfo OutputGroupInfo(**kwargs) ``` -Instantiate this provider with +Instantiate this provider with -``` python -OutputGroupInfo(group1 = <files>, group2 = <files>...) +``` +OutputGroupInfo(group1 = \<files\>, group2 = \<files\>...) ``` -See [Requesting output files](https://bazel.build/extending/rules#requesting_output_files) for more information. +See [Requesting output files](https://bazel.build/extending/rules#requesting_output_files) for more information. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="OutputGroupInfo.kwargs"><code>kwargs</code></td> -<td>default is <code>{}</code><br /> -Dictionary of arguments.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `kwargs` | default is `\{\}` | \ No newline at end of file diff --git a/rules/lib/providers/PackageSpecificationInfo.mdx b/rules/lib/providers/PackageSpecificationInfo.mdx index 0b6dedc..c2562bc 100644 --- a/rules/lib/providers/PackageSpecificationInfo.mdx +++ b/rules/lib/providers/PackageSpecificationInfo.mdx @@ -2,19 +2,16 @@ title: 'PackageSpecificationInfo' --- -# PackageSpecificationInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/PackageSpecificationProviderApi.java" %} -{% include "\_buttons.html" %} Information about transitive package specifications used in package groups. ## Members -- [contains](#contains) +* [contains](#contains) ## contains -``` rule-signature +``` bool PackageSpecificationInfo.contains(target) ``` @@ -22,19 +19,6 @@ Checks if a target exists in a package group. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="contains.target"><code>target</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; -required<br /> -A target which is checked if it exists inside the package group.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `target` | [Label](../builtins/Label.mdx); or [string](../core/string.mdx); required A target which is checked if it exists inside the package group. | \ No newline at end of file diff --git a/rules/lib/providers/PlatformInfo.mdx b/rules/lib/providers/PlatformInfo.mdx index 0e6a33f..1fe60f9 100644 --- a/rules/lib/providers/PlatformInfo.mdx +++ b/rules/lib/providers/PlatformInfo.mdx @@ -2,9 +2,6 @@ title: 'PlatformInfo' --- -# PlatformInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformInfoApi.java" %} -{% include "\_buttons.html" %} -Provides access to data about a specific platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* +Provides access to data about a specific platform. See [Defining Constraints and Platforms](./docs/platforms#constraints-platforms) for more information. +*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* \ No newline at end of file diff --git a/rules/lib/providers/RunEnvironmentInfo.mdx b/rules/lib/providers/RunEnvironmentInfo.mdx index 1a53862..ae66c64 100644 --- a/rules/lib/providers/RunEnvironmentInfo.mdx +++ b/rules/lib/providers/RunEnvironmentInfo.mdx @@ -2,29 +2,26 @@ title: 'RunEnvironmentInfo' --- -# RunEnvironmentInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunEnvironmentInfoApi.java" %} -{% include "\_buttons.html" %} A provider that can be returned from executable rules to control the environment in which their executable is executed. ## Members -- [environment](#environment) -- [inherited_environment](#inherited_environment) +* [environment](#environment) +* [inherited\_environment](#inherited_environment) ## environment -``` rule-signature +``` dict RunEnvironmentInfo.environment ``` A map of string keys and values that represent environment variables and their values. These will be made available when the target that returns this provider is executed, either as a test or via the run command. -## inherited_environment +## inherited\_environment -``` rule-signature +``` List RunEnvironmentInfo.inherited_environment ``` -A sequence of names of environment variables. These variables are made available with their current value taken from the shell environment when the target that returns this provider is executed, either as a test or via the run command. If a variable is contained in both `environment` and `inherited_environment`, the value inherited from the shell environment will take precedence if set. This is most useful for test rules, which run with a hermetic environment under `bazel test` and can use this mechanism to non-hermetically include a variable from the outer environment. By contrast, `bazel run` already forwards the outer environment. Note, though, that it may be surprising for an otherwise hermetic test to hardcode a non-hermetic dependency on the environment, and that this may even accidentally expose sensitive information. Prefer setting the test environment explicitly with the `--test_env` flag, and even then prefer to avoid using this flag and instead populate the environment explicitly. +A sequence of names of environment variables. These variables are made available with their current value taken from the shell environment when the target that returns this provider is executed, either as a test or via the run command. If a variable is contained in both `environment` and `inherited_environment`, the value inherited from the shell environment will take precedence if set. This is most useful for test rules, which run with a hermetic environment under `bazel test` and can use this mechanism to non-hermetically include a variable from the outer environment. By contrast, `bazel run` already forwards the outer environment. Note, though, that it may be surprising for an otherwise hermetic test to hardcode a non-hermetic dependency on the environment, and that this may even accidentally expose sensitive information. Prefer setting the test environment explicitly with the `--test_env` flag, and even then prefer to avoid using this flag and instead populate the environment explicitly. \ No newline at end of file diff --git a/rules/lib/providers/TemplateVariableInfo.mdx b/rules/lib/providers/TemplateVariableInfo.mdx index e4328dd..06f69ff 100644 --- a/rules/lib/providers/TemplateVariableInfo.mdx +++ b/rules/lib/providers/TemplateVariableInfo.mdx @@ -2,24 +2,21 @@ title: 'TemplateVariableInfo' --- -# TemplateVariableInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateVariableInfoApi.java" %} -{% include "\_buttons.html" %} Encapsulates template variables, that is, variables that can be referenced by strings like `$(VARIABLE)` in BUILD files and expanded by `ctx.expand_make_variables` and implicitly in certain attributes of built-in rules. `TemplateVariableInfo` can be created by calling its eponymous constructor with a string-to-string dict as an argument that specifies the variables provided. -Example: `platform_common.TemplateVariableInfo({'FOO': 'bar'})` +Example: `platform_common.TemplateVariableInfo(\{'FOO': 'bar'\})` ## Members -- [variables](#variables) +* [variables](#variables) ## variables -``` rule-signature +``` dict TemplateVariableInfo.variables ``` -Returns the make variables defined by this target as a dictionary with string keys and string values +Returns the make variables defined by this target as a dictionary with string keys and string values \ No newline at end of file diff --git a/rules/lib/providers/ToolchainInfo.mdx b/rules/lib/providers/ToolchainInfo.mdx index 7997940..061d64e 100644 --- a/rules/lib/providers/ToolchainInfo.mdx +++ b/rules/lib/providers/ToolchainInfo.mdx @@ -2,8 +2,5 @@ title: 'ToolchainInfo' --- -# ToolchainInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainInfoApi.java" %} -{% include "\_buttons.html" %} -Provider returned by [toolchain rules](/docs/toolchains#defining-toolchains) to share data with [rules which depend on toolchains](/docs/toolchains#writing-rules-that-use-toolchains). Read about [toolchains](/docs/toolchains) for more information. +Provider returned by [toolchain rules](./docs/toolchains#defining-toolchains) to share data with [rules which depend on toolchains](./docs/toolchains#writing-rules-that-use-toolchains). Read about [toolchains](./docs/toolchains) for more information. \ No newline at end of file diff --git a/rules/lib/providers/ToolchainTypeInfo.mdx b/rules/lib/providers/ToolchainTypeInfo.mdx index b71acf2..5f8c4fb 100644 --- a/rules/lib/providers/ToolchainTypeInfo.mdx +++ b/rules/lib/providers/ToolchainTypeInfo.mdx @@ -2,21 +2,18 @@ title: 'ToolchainTypeInfo' --- -# ToolchainTypeInfo -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/ToolchainTypeInfoApi.java" %} -{% include "\_buttons.html" %} -Provides access to data about a specific toolchain type. +Provides access to data about a specific toolchain type. *Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* ## Members -- [type_label](#type_label) +* [type\_label](#type_label) -## type_label +## type\_label -``` rule-signature +``` Label ToolchainTypeInfo.type_label ``` -The label uniquely identifying this toolchain type. +The label uniquely identifying this toolchain type. \ No newline at end of file diff --git a/rules/lib/providers/file_provider.mdx b/rules/lib/providers/file_provider.mdx index fda26a3..af1169e 100644 --- a/rules/lib/providers/file_provider.mdx +++ b/rules/lib/providers/file_provider.mdx @@ -2,8 +2,5 @@ title: 'file_provider' --- -# file_provider -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileProviderApi.java" %} -{% include "\_buttons.html" %} -An interface for rules that provide files. +An interface for rules that provide files. \ No newline at end of file diff --git a/rules/lib/providers/java_compilation_info.mdx b/rules/lib/providers/java_compilation_info.mdx index 3eeec55..85b677e 100644 --- a/rules/lib/providers/java_compilation_info.mdx +++ b/rules/lib/providers/java_compilation_info.mdx @@ -2,47 +2,44 @@ title: 'java_compilation_info' --- -# java_compilation_info -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCompilationInfoProviderApi.java" %} -{% include "\_buttons.html" %} Provides access to compilation information for Java rules. ## Members -- [boot_classpath](#boot_classpath) -- [compilation_classpath](#compilation_classpath) -- [javac_options](#javac_options) -- [runtime_classpath](#runtime_classpath) +* [boot\_classpath](#boot_classpath) +* [compilation\_classpath](#compilation_classpath) +* [javac\_options](#javac_options) +* [runtime\_classpath](#runtime_classpath) -## boot_classpath +## boot\_classpath -``` rule-signature +``` list java_compilation_info.boot_classpath ``` Boot classpath for this Java target. -## compilation_classpath +## compilation\_classpath -``` rule-signature +``` depset java_compilation_info.compilation_classpath ``` Compilation classpath for this Java target. -## javac_options +## javac\_options -``` rule-signature +``` depset java_compilation_info.javac_options ``` -A depset of options to java compiler. To get the exact list of options passed to javac in the correct order, use the tokenize_javacopts utility in rules_java +A depset of options to java compiler. To get the exact list of options passed to javac in the correct order, use the tokenize\_javacopts utility in rules\_java -## runtime_classpath +## runtime\_classpath -``` rule-signature +``` depset java_compilation_info.runtime_classpath ``` -Run-time classpath for this Java target. +Run-time classpath for this Java target. \ No newline at end of file diff --git a/rules/lib/providers/java_output_jars.mdx b/rules/lib/providers/java_output_jars.mdx index 53ecf4c..85471a5 100644 --- a/rules/lib/providers/java_output_jars.mdx +++ b/rules/lib/providers/java_output_jars.mdx @@ -2,40 +2,37 @@ title: 'java_output_jars' --- -# java_output_jars -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaRuleOutputJarsProviderApi.java" %} -{% include "\_buttons.html" %} -Information about outputs of a Java rule. Deprecated: use java_info.java_outputs. +Information about outputs of a Java rule. Deprecated: use java\_info.java\_outputs. ## Members -- [jars](#jars) -- [jdeps](#jdeps) -- [native_headers](#native_headers) +* [jars](#jars) +* [jdeps](#jdeps) +* [native\_headers](#native_headers) ## jars -``` rule-signature +``` list java_output_jars.jars ``` -Returns information about outputs of this Java/Java-like target. Deprecated: Use java_info.java_outputs. +Returns information about outputs of this Java/Java-like target. Deprecated: Use java\_info.java\_outputs. ## jdeps -``` rule-signature +``` File java_output_jars.jdeps ``` -A manifest proto file. The protobuf file containing the manifest generated from JavaBuilder. This function returns a value when exactly one manifest proto file is present in the outputs. Deprecated: Use java_info.java_outputs\[i\].jdeps. +A manifest proto file. The protobuf file containing the manifest generated from JavaBuilder. This function returns a value when exactly one manifest proto file is present in the outputs. Deprecated: Use java\_info.java\_outputs[i].jdeps. May return `None`. -## native_headers +## native\_headers -``` rule-signature +``` File java_output_jars.native_headers ``` -A jar containing CC header files supporting native method implementation. This function returns a value when exactly one native headers jar file is present in the outputs. Deprecated: Use java_info.java_outputs\[i\].native_headers_jar. -May return `None`. +A jar containing CC header files supporting native method implementation. This function returns a value when exactly one native headers jar file is present in the outputs. Deprecated: Use java\_info.java\_outputs[i].native\_headers\_jar. +May return `None`. \ No newline at end of file diff --git a/rules/lib/toplevel.mdx b/rules/lib/toplevel.mdx index d49bc13..19d0d0e 100644 --- a/rules/lib/toplevel.mdx +++ b/rules/lib/toplevel.mdx @@ -2,20 +2,17 @@ title: 'toplevel' --- -# Top-level Modules -{% dynamic setvar source_file "NONE" %} -{% include "\_buttons.html" %} This section lists top-level modules. These symbols are available only in .bzl files. -- [apple_common](/rules/lib/toplevel/apple_common) -- [attr](/rules/lib/toplevel/attr) -- [cc_common](/rules/lib/toplevel/cc_common) -- [config](/rules/lib/toplevel/config) -- [config_common](/rules/lib/toplevel/config_common) -- [coverage_common](/rules/lib/toplevel/coverage_common) -- [java_common](/rules/lib/toplevel/java_common) -- [native](/rules/lib/toplevel/native) -- [platform_common](/rules/lib/toplevel/platform_common) -- [proto](/rules/lib/toplevel/proto) -- [testing](/rules/lib/toplevel/testing) +* [apple\_common](./rules/lib/toplevel/apple_common) +* [attr](./rules/lib/toplevel/attr) +* [cc\_common](./rules/lib/toplevel/cc_common) +* [config](./rules/lib/toplevel/config) +* [config\_common](./rules/lib/toplevel/config_common) +* [coverage\_common](./rules/lib/toplevel/coverage_common) +* [java\_common](./rules/lib/toplevel/java_common) +* [native](./rules/lib/toplevel/native) +* [platform\_common](./rules/lib/toplevel/platform_common) +* [proto](./rules/lib/toplevel/proto) +* [testing](./rules/lib/toplevel/testing) \ No newline at end of file diff --git a/rules/lib/toplevel/apple_common.mdx b/rules/lib/toplevel/apple_common.mdx index a0315a9..b3355fc 100644 --- a/rules/lib/toplevel/apple_common.mdx +++ b/rules/lib/toplevel/apple_common.mdx @@ -2,130 +2,101 @@ title: 'apple_common' --- -# apple_common -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java" %} -{% include "\_buttons.html" %} Functions for Starlark to access internals of the apple rule implementations. ## Members -- [apple_host_system_env](#apple_host_system_env) -- [apple_toolchain](#apple_toolchain) -- [dotted_version](#dotted_version) -- [platform](#platform) -- [platform_type](#platform_type) -- [target_apple_env](#target_apple_env) -- [XcodeProperties](#XcodeProperties) -- [XcodeVersionConfig](#XcodeVersionConfig) +* [apple\_host\_system\_env](#apple_host_system_env) +* [apple\_toolchain](#apple_toolchain) +* [dotted\_version](#dotted_version) +* [platform](#platform) +* [platform\_type](#platform_type) +* [target\_apple\_env](#target_apple_env) +* [XcodeProperties](#XcodeProperties) +* [XcodeVersionConfig](#XcodeVersionConfig) -## apple_host_system_env +## apple\_host\_system\_env -``` rule-signature +``` dict apple_common.apple_host_system_env(xcode_config) ``` -Returns a [dict](../core/dict.html) of environment variables that should be set for actions that need to run build tools on an Apple host system, such as the version of Xcode that should be used. The keys are variable names and the values are their corresponding values. +Returns a [dict](../core/dict.mdx) of environment variables that should be set for actions that need to run build tools on an Apple host system, such as the version of Xcode that should be used. The keys are variable names and the values are their corresponding values. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="apple_host_system_env.xcode_config"><code>xcode_config</code></td> -<td>required<br /> -A provider containing information about the Xcode configuration.</td> -</tr> -</tbody> -</table> - -## apple_toolchain - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `xcode_config` | required A provider containing information about the Xcode configuration. | + +## apple\_toolchain + +``` unknown apple_common.apple_toolchain() ``` Utilities for resolving items from the apple toolchain. -## dotted_version +## dotted\_version -``` rule-signature +``` DottedVersion apple_common.dotted_version(version) ``` -Creates a new [DottedVersion](../builtins/DottedVersion.html) instance. +Creates a new [DottedVersion](../builtins/DottedVersion.mdx) instance. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="dotted_version.version"><code>version</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The string representation of the DottedVersion.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `version` | [string](../core/string.mdx); required The string representation of the DottedVersion. | ## platform -``` rule-signature +``` struct apple_common.platform ``` An enum-like struct that contains the following fields corresponding to Apple platforms: -- `ios_device` -- `ios_simulator` -- `macos` -- `tvos_device` -- `tvos_simulator` -- `visionos_device` -- `visionos_simulator` -- `watchos_device` -- `watchos_simulator` +* `ios_device` +* `ios_simulator` +* `macos` +* `tvos_device` +* `tvos_simulator` +* `visionos_device` +* `visionos_simulator` +* `watchos_device` +* `watchos_simulator` -These values can be passed to methods that expect a platform, like [XcodeVersionConfig.sdk_version_for_platform](../providers/XcodeVersionConfig.html#sdk_version_for_platform). +These values can be passed to methods that expect a platform, like [XcodeVersionConfig.sdk\_version\_for\_platform](../providers/XcodeVersionConfig.html#sdk_version_for_platform). -## platform_type +## platform\_type -``` rule-signature +``` struct apple_common.platform_type ``` An enum-like struct that contains the following fields corresponding to Apple platform types: -- `ios` -- `macos` -- `tvos` -- `visionos` -- `watchos` +* `ios` +* `macos` +* `tvos` +* `visionos` +* `watchos` -These values can be passed to methods that expect a platform type, like the 'apple' configuration fragment's [multi_arch_platform](../fragments/apple.html#multi_arch_platform) method. +These values can be passed to methods that expect a platform type, like the 'apple' configuration fragment's [multi\_arch\_platform](../fragments/apple.html#multi_arch_platform) method. Example: -``` python - +``` ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios) ``` -## target_apple_env +## target\_apple\_env -``` rule-signature +``` dict apple_common.target_apple_env(xcode_config, platform) ``` @@ -133,30 +104,14 @@ Returns a `dict` of environment variables that should be set for actions that bu ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="target_apple_env.xcode_config"><code>xcode_config</code></td> -<td>required<br /> -A provider containing information about the Xcode configuration.</td> -</tr> -<tr> -<td id="target_apple_env.platform"><code>platform</code></td> -<td>required<br /> -The apple platform.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `xcode_config` | required | +| `platform` | required | ## XcodeProperties -``` rule-signature +``` Provider apple_common.XcodeProperties ``` @@ -164,16 +119,15 @@ The constructor/key for the `XcodeVersionProperties` provider. If a target propagates the `XcodeVersionProperties` provider, use this as the key with which to retrieve it. Example: -``` python - +``` dep = ctx.attr.deps[0] p = dep[apple_common.XcodeVersionProperties] ``` ## XcodeVersionConfig -``` rule-signature +``` Provider apple_common.XcodeVersionConfig ``` -The constructor/key for the `XcodeVersionConfig` provider. +The constructor/key for the `XcodeVersionConfig` provider. \ No newline at end of file diff --git a/rules/lib/toplevel/attr.mdx b/rules/lib/toplevel/attr.mdx index b6517ed..2e37d9b 100644 --- a/rules/lib/toplevel/attr.mdx +++ b/rules/lib/toplevel/attr.mdx @@ -2,10 +2,7 @@ title: 'attr' --- -# attr -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java" %} -{% include "\_buttons.html" %} This is a top-level module for defining the attribute schemas of a rule or aspect. Each function returns an object representing the schema of a single attribute. These objects are used as the values of the `attrs` dictionary argument of [`rule()`](../globals/bzl.html#rule), [`aspect()`](../globals/bzl.html#aspect), [`repository_rule()`](../globals/bzl.html#repository_rule) and [`tag_class()`](../globals/bzl.html#tag_class). See the Rules page for more on [defining](https://bazel.build/extending/rules#attributes) @@ -13,123 +10,58 @@ and [using](https://bazel.build/extending/rules#implementation_function) attribu ## Members -- [bool](#bool) -- [int](#int) -- [int_list](#int_list) -- [label](#label) -- [label_keyed_string_dict](#label_keyed_string_dict) -- [label_list](#label_list) -- [output](#output) -- [output_list](#output_list) -- [string](#string) -- [string_dict](#string_dict) -- [string_keyed_label_dict](#string_keyed_label_dict) -- [string_list](#string_list) -- [string_list_dict](#string_list_dict) +* [bool](#bool) +* [int](#int) +* [int\_list](#int_list) +* [label](#label) +* [label\_keyed\_string\_dict](#label_keyed_string_dict) +* [label\_list](#label_list) +* [output](#output) +* [output\_list](#output_list) +* [string](#string) +* [string\_dict](#string_dict) +* [string\_keyed\_label\_dict](#string_keyed_label_dict) +* [string\_list](#string_list) +* [string\_list\_dict](#string_list_dict) ## bool -``` rule-signature +``` Attribute attr.bool(*, configurable=unbound, default=False, doc=None, mandatory=False) ``` -Creates a schema for a boolean attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`bool`](../core/bool.html). +Creates a schema for a boolean attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`bool`](../core/bool.mdx). ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="bool.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="bool.default"><code>default</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.</td> -</tr> -<tr> -<td id="bool.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="bool.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [bool](../core/bool.mdx); default is `False` A default value to use if no value for this attribute is given when instantiating the rule. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | ## int -``` rule-signature +``` Attribute attr.int(*, configurable=unbound, default=0, doc=None, mandatory=False, values=[]) ``` -Creates a schema for an integer attribute. The value must be in the signed 32-bit range. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`int`](../core/int.html). +Creates a schema for an integer attribute. The value must be in the signed 32-bit range. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`int`](../core/int.mdx). ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="int.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="int.default"><code>default</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>0</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.</td> -</tr> -<tr> -<td id="int.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="int.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -<tr> -<td id="int.values"><code>values</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/int.html" class="anchor">int</a>s; -default is <code>[]</code><br /> -The list of allowed values for the attribute. An error is raised if any other value is given.</td> -</tr> -</tbody> -</table> - -## int_list - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [int](../core/int.mdx); default is `0` A default value to use if no value for this attribute is given when instantiating the rule. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +| `values` | [sequence](../core/list.mdx) of [int](../core/int.mdx)s; default is `[]` The list of allowed values for the attribute. An error is raised if any other value is given. | + +## int\_list + +``` Attribute attr.int_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None) ``` @@ -137,465 +69,151 @@ Creates a schema for a list-of-integers attribute. Each element must be in the s ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="int_list.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -<tr> -<td id="int_list.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True if the attribute can be empty.</td> -</tr> -<tr> -<td id="int_list.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="int_list.default"><code>default</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/int.html" class="anchor">int</a>s; -default is <code>[]</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.</td> -</tr> -<tr> -<td id="int_list.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [sequence](../core/list.mdx) of [int](../core/int.mdx)s; default is `[]` A default value to use if no value for this attribute is given when instantiating the rule. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | ## label -``` rule-signature +``` Attribute attr.label(*, configurable=unbound, default=None, materializer=None, doc=None, executable=False, allow_files=None, allow_single_file=None, mandatory=False, skip_validations=False, providers=[], for_dependency_resolution=unbound, allow_rules=None, cfg=None, aspects=[], flags=[]) ``` Creates a schema for a label attribute. This is a dependency attribute. -This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html)s. This allows you to access the providers of the current target's dependencies. +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.mdx)s. This allows you to access the providers of the current target's dependencies. In addition to ordinary source files, this kind of attribute is often used to refer to a tool -- for example, a compiler. Such tools are considered to be dependencies, just like source files. To avoid requiring users to specify the tool's label every time they use the rule in their BUILD files, you can hard-code the label of a canonical tool as the `default` value of this attribute. If you also want to prevent users from overriding this default, you can make the attribute private by giving it a name that starts with an underscore. See the [Rules](https://bazel.build/extending/rules#private-attributes) page for more information. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="label.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="label.default"><code>default</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/LateBoundDefault.html" class="anchor">LateBoundDefault</a>; or NativeComputedDefault; or <a href="../core/function.html" class="anchor">function</a>; or <code>None</code>; -default is <code>None</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify a default value, for example, <code>attr.label(default = "//a:b")</code>.</td> -</tr> -<tr> -<td id="label.materializer"><code>materializer</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -default is <code>None</code><br /> -<strong>Experimental</strong>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_dormant_deps</code><br /> -If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute</td> -</tr> -<tr> -<td id="label.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="label.executable"><code>executable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -True if the dependency has to be executable. This means the label must refer to an executable file, or to a rule that outputs an executable file. Access the label with <code>ctx.executable.<attribute_name></code>.</td> -</tr> -<tr> -<td id="label.allow_files"><code>allow_files</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>).</td> -</tr> -<tr> -<td id="label.allow_single_file"><code>allow_single_file</code></td> -<td>default is <code>None</code><br /> -This is similar to <code>allow_files</code>, with the restriction that the label must correspond to a single <a href="../builtins/File.html">File</a>. Access it through <code>ctx.file.<attribute_name></code>.</td> -</tr> -<tr> -<td id="label.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -<tr> -<td id="label.skip_validations"><code>skip_validations</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future.</td> -</tr> -<tr> -<td id="label.providers"><code>providers</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -The providers that must be given by any dependency appearing in this attribute. -<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice.</p></td> -</tr> -<tr> -<td id="label.for_dependency_resolution"><code>for_dependency_resolution</code></td> -<td>default is <code>unbound</code><br /> -If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes.</td> -</tr> -<tr> -<td id="label.allow_rules"><code>allow_rules</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.</td> -</tr> -<tr> -<td id="label.cfg"><code>cfg</code></td> -<td>default is <code>None</code><br /> -<a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>. This parameter is required if <code>executable</code> is True to guard against accidentally building host tools in the target configuration. <code>"target"</code> has no semantic effect, so don't set it when <code>executable</code> is False unless it really helps clarify your intentions.</td> -</tr> -<tr> -<td id="label.aspects"><code>aspects</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; -default is <code>[]</code><br /> -Aspects that should be applied to the dependency or dependencies specified by this attribute.</td> -</tr> -<tr> -<td id="label.flags"><code>flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Deprecated, will be removed.</td> -</tr> -</tbody> -</table> - -## label_keyed_string_dict - -``` rule-signature -Attribute attr.label_keyed_string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[]) +| Parameter | Description | +| --- | --- | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [Label](../builtins/Label.mdx); or [string](../core/string.mdx); or [LateBoundDefault](../builtins/LateBoundDefault.mdx); or NativeComputedDefault; or [function](../core/function.mdx); or `None`; default is `None` A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the [`Label`](../builtins/Label.html#Label) function to specify a default value, for example, `attr.label(default = "//a:b")`. | +| `materializer` | [function](../core/function.mdx); default is `None` **Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_dormant_deps` If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` | +| `executable` | [bool](../core/bool.mdx); default is `False` True if the dependency has to be executable. This means the label must refer to an executable file, or to a rule that outputs an executable file. Access the label with `ctx.executable.\<attribute_name\>`. | +| `allow_files` | [bool](../core/bool.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). | +| `allow_single_file` | default is `None` This is similar to `allow_files`, with the restriction that the label must correspond to a single [File](../builtins/File.mdx). Access it through `ctx.file.\<attribute_name\>`. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +| `skip_validations` | [bool](../core/bool.mdx); default is `False` If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. | +| `providers` | [sequence](../core/list.mdx); default is `[]` The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. | +| `for_dependency_resolution` | default is `unbound` If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. | +| `allow_rules` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. | +| `cfg` | default is `None` [Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. This parameter is required if `executable` is True to guard against accidentally building host tools in the target configuration. `"target"` has no semantic effect, so don't set it when `executable` is False unless it really helps clarify your intentions. | +| `aspects` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` Aspects that should be applied to the dependency or dependencies specified by this attribute. | +| `flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Deprecated, will be removed. | + +## label\_keyed\_string\_dict + +``` +Attribute attr.label_keyed_string_dict(allow_empty=True, *, configurable=unbound, default=\{\}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[]) ``` Creates a schema for an attribute holding a dictionary, where the keys are labels and the values are strings. This is a dependency attribute. -This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html)s. This allows you to access the providers of the current target's dependencies. +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.mdx)s. This allows you to access the providers of the current target's dependencies. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="label_keyed_string_dict.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True if the attribute can be empty.</td> -</tr> -<tr> -<td id="label_keyed_string_dict.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="label_keyed_string_dict.default"><code>default</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <a href="../core/function.html" class="anchor">function</a>; -default is <code>{}</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"})</code>.</td> -</tr> -<tr> -<td id="label_keyed_string_dict.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="label_keyed_string_dict.allow_files"><code>allow_files</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>).</td> -</tr> -<tr> -<td id="label_keyed_string_dict.allow_rules"><code>allow_rules</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.</td> -</tr> -<tr> -<td id="label_keyed_string_dict.providers"><code>providers</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -The providers that must be given by any dependency appearing in this attribute. -<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice.</p></td> -</tr> -<tr> -<td id="label_keyed_string_dict.for_dependency_resolution"><code>for_dependency_resolution</code></td> -<td>default is <code>unbound</code><br /> -If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes.</td> -</tr> -<tr> -<td id="label_keyed_string_dict.flags"><code>flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Deprecated, will be removed.</td> -</tr> -<tr> -<td id="label_keyed_string_dict.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -<tr> -<td id="label_keyed_string_dict.skip_validations"><code>skip_validations</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future.</td> -</tr> -<tr> -<td id="label_keyed_string_dict.cfg"><code>cfg</code></td> -<td>default is <code>None</code><br /> -<a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>.</td> -</tr> -<tr> -<td id="label_keyed_string_dict.aspects"><code>aspects</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; -default is <code>[]</code><br /> -Aspects that should be applied to the dependency or dependencies specified by this attribute.</td> -</tr> -</tbody> -</table> - -## label_list - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [dict](../core/dict.mdx); or [function](../core/function.mdx); default is `\{\}` A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.label_keyed_string_dict(default = \{"//a:b": "value", "//a:c": "string"\})`. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `allow_files` | [bool](../core/bool.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). | +| `allow_rules` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. | +| `providers` | [sequence](../core/list.mdx); default is `[]` The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. | +| `for_dependency_resolution` | default is `unbound` If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. | +| `flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Deprecated, will be removed. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +| `skip_validations` | [bool](../core/bool.mdx); default is `False` If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. | +| `cfg` | default is `None` [Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. | +| `aspects` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` Aspects that should be applied to the dependency or dependencies specified by this attribute. | + +## label\_list + +``` Attribute attr.label_list(allow_empty=True, *, configurable=unbound, default=[], materializer=None, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[]) ``` -Creates a schema for a list-of-labels attribute. This is a dependency attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [list](../core/list.html) of [`Target`s](../builtins/Target.html). +Creates a schema for a list-of-labels attribute. This is a dependency attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [list](../core/list.mdx) of [`Target`s](../builtins/Target.mdx). -This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html)s. This allows you to access the providers of the current target's dependencies. +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.mdx)s. This allows you to access the providers of the current target's dependencies. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="label_list.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True if the attribute can be empty.</td> -</tr> -<tr> -<td id="label_list.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="label_list.default"><code>default</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Label.html" class="anchor">Label</a>s; or <a href="../core/function.html" class="anchor">function</a>; -default is <code>[]</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.label_list(default = ["//a:b", "//a:c"])</code>.</td> -</tr> -<tr> -<td id="label_list.materializer"><code>materializer</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -default is <code>None</code><br /> -<strong>Experimental</strong>. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting <code>--experimental_dormant_deps</code><br /> -If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute</td> -</tr> -<tr> -<td id="label_list.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="label_list.allow_files"><code>allow_files</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>).</td> -</tr> -<tr> -<td id="label_list.allow_rules"><code>allow_rules</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.</td> -</tr> -<tr> -<td id="label_list.providers"><code>providers</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -The providers that must be given by any dependency appearing in this attribute. -<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice.</p></td> -</tr> -<tr> -<td id="label_list.for_dependency_resolution"><code>for_dependency_resolution</code></td> -<td>default is <code>unbound</code><br /> -If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes.</td> -</tr> -<tr> -<td id="label_list.flags"><code>flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Deprecated, will be removed.</td> -</tr> -<tr> -<td id="label_list.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -<tr> -<td id="label_list.skip_validations"><code>skip_validations</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future.</td> -</tr> -<tr> -<td id="label_list.cfg"><code>cfg</code></td> -<td>default is <code>None</code><br /> -<a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>.</td> -</tr> -<tr> -<td id="label_list.aspects"><code>aspects</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; -default is <code>[]</code><br /> -Aspects that should be applied to the dependency or dependencies specified by this attribute.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [sequence](../core/list.mdx) of [Label](../builtins/Label.mdx)s; or [function](../core/function.mdx); default is `[]` A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.label_list(default = ["//a:b", "//a:c"])`. | +| `materializer` | [function](../core/function.mdx); default is `None` **Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_dormant_deps` If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` | +| `allow_files` | [bool](../core/bool.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). | +| `allow_rules` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. | +| `providers` | [sequence](../core/list.mdx); default is `[]` The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. | +| `for_dependency_resolution` | default is `unbound` If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. | +| `flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Deprecated, will be removed. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +| `skip_validations` | [bool](../core/bool.mdx); default is `False` If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. | +| `cfg` | default is `None` [Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. | +| `aspects` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` Aspects that should be applied to the dependency or dependencies specified by this attribute. | ## output -``` rule-signature +``` Attribute attr.output(*, doc=None, mandatory=False) ``` Creates a schema for an output (label) attribute. -This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -At analysis time, the corresponding [`File`](../builtins/File.html) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). +At analysis time, the corresponding [`File`](../builtins/File.mdx) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="output.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="output.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -</tbody> -</table> - -## output_list - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | + +## output\_list + +``` Attribute attr.output_list(allow_empty=True, *, doc=None, mandatory=False) ``` Creates a schema for a list-of-outputs attribute. -This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -At analysis time, the corresponding [`File`](../builtins/File.html) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). +At analysis time, the corresponding [`File`](../builtins/File.mdx) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="output_list.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True if the attribute can be empty.</td> -</tr> -<tr> -<td id="output_list.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="output_list.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | ## string -``` rule-signature +``` Attribute attr.string(*, configurable=unbound, default='', doc=None, mandatory=False, values=[]) ``` @@ -603,203 +221,64 @@ Creates a schema for a [string](../core/string.html#attr) attribute. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="string.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="string.default"><code>default</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or NativeComputedDefault; -default is <code>''</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.</td> -</tr> -<tr> -<td id="string.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="string.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -<tr> -<td id="string.values"><code>values</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -The list of allowed values for the attribute. An error is raised if any other value is given.</td> -</tr> -</tbody> -</table> - -## string_dict - -``` rule-signature -Attribute attr.string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False) +| Parameter | Description | +| --- | --- | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [string](../core/string.mdx); or NativeComputedDefault; default is `''` A default value to use if no value for this attribute is given when instantiating the rule. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +| `values` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of allowed values for the attribute. An error is raised if any other value is given. | + +## string\_dict + +``` +Attribute attr.string_dict(allow_empty=True, *, configurable=unbound, default=\{\}, doc=None, mandatory=False) ``` Creates a schema for an attribute holding a dictionary, where the keys and values are strings. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="string_dict.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True if the attribute can be empty.</td> -</tr> -<tr> -<td id="string_dict.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="string_dict.default"><code>default</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.</td> -</tr> -<tr> -<td id="string_dict.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="string_dict.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -</tbody> -</table> - -## string_keyed_label_dict - -``` rule-signature -Attribute attr.string_keyed_label_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, cfg=None, aspects=[]) +| Parameter | Description | +| --- | --- | +| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [dict](../core/dict.mdx); default is `\{\}` A default value to use if no value for this attribute is given when instantiating the rule. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | + +## string\_keyed\_label\_dict + +``` +Attribute attr.string_keyed_label_dict(allow_empty=True, *, configurable=unbound, default=\{\}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, cfg=None, aspects=[]) ``` Creates a schema for an attribute whose value is a dictionary where the keys are strings and the values are labels. This is a dependency attribute. -This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html)s. This allows you to access the providers of the current target's dependencies. +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.mdx)s. This allows you to access the providers of the current target's dependencies. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="string_keyed_label_dict.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True if the attribute can be empty.</td> -</tr> -<tr> -<td id="string_keyed_label_dict.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="string_keyed_label_dict.default"><code>default</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; or <a href="../core/function.html" class="anchor">function</a>; -default is <code>{}</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the <a href="../builtins/Label.html#Label"><code>Label</code></a> function to specify default values, for example, <code>attr.string_keyed_label_dict(default = {"foo": "//a:b", "bar": "//a:c"})</code>.</td> -</tr> -<tr> -<td id="string_keyed_label_dict.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="string_keyed_label_dict.allow_files"><code>allow_files</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> (default), or a list of file extensions that are allowed (for example, <code>[".cc", ".cpp"]</code>).</td> -</tr> -<tr> -<td id="string_keyed_label_dict.allow_rules"><code>allow_rules</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.</td> -</tr> -<tr> -<td id="string_keyed_label_dict.providers"><code>providers</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -The providers that must be given by any dependency appearing in this attribute. -<p>The format of this argument is a list of lists of providers -- <code>*Info</code> objects returned by <a href="../globals/bzl.html#provider"><code>provider()</code></a> (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. <code>[A, B]</code> means <code>[[A, B]]</code>). It is NOT required that the rule of the dependency advertises those providers in its <code>provides</code> parameter, however, it is considered best practice.</p></td> -</tr> -<tr> -<td id="string_keyed_label_dict.for_dependency_resolution"><code>for_dependency_resolution</code></td> -<td>default is <code>unbound</code><br /> -If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes.</td> -</tr> -<tr> -<td id="string_keyed_label_dict.flags"><code>flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Deprecated, will be removed.</td> -</tr> -<tr> -<td id="string_keyed_label_dict.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -<tr> -<td id="string_keyed_label_dict.cfg"><code>cfg</code></td> -<td>default is <code>None</code><br /> -<a href="https://bazel.build/extending/rules#configurations">Configuration</a> of the attribute. It can be either <code>"exec"</code>, which indicates that the dependency is built for the <code>execution platform</code>, or <code>"target"</code>, which indicates that the dependency is build for the <code>target platform</code>. A typical example of the difference is when building mobile apps, where the <code>target platform</code> is <code>Android</code> or <code>iOS</code> while the <code>execution platform</code> is <code>Linux</code>, <code>macOS</code>, or <code>Windows</code>.</td> -</tr> -<tr> -<td id="string_keyed_label_dict.aspects"><code>aspects</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/Aspect.html" class="anchor">Aspect</a>s; -default is <code>[]</code><br /> -Aspects that should be applied to the dependency or dependencies specified by this attribute.</td> -</tr> -</tbody> -</table> - -## string_list - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [dict](../core/dict.mdx); or [function](../core/function.mdx); default is `\{\}` A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.string_keyed_label_dict(default = \{"foo": "//a:b", "bar": "//a:c"\})`. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `allow_files` | [bool](../core/bool.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). | +| `allow_rules` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. | +| `providers` | [sequence](../core/list.mdx); default is `[]` The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. | +| `for_dependency_resolution` | default is `unbound` If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. | +| `flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Deprecated, will be removed. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +| `cfg` | default is `None` [Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. | +| `aspects` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` Aspects that should be applied to the dependency or dependencies specified by this attribute. | + +## string\_list + +``` Attribute attr.string_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None) ``` @@ -807,98 +286,28 @@ Creates a schema for a list-of-strings attribute. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="string_list.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -<tr> -<td id="string_list.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True if the attribute can be empty.</td> -</tr> -<tr> -<td id="string_list.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="string_list.default"><code>default</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or NativeComputedDefault; -default is <code>[]</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.</td> -</tr> -<tr> -<td id="string_list.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -</tbody> -</table> - -## string_list_dict - -``` rule-signature -Attribute attr.string_list_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False) +| Parameter | Description | +| --- | --- | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or NativeComputedDefault; default is `[]` A default value to use if no value for this attribute is given when instantiating the rule. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | + +## string\_list\_dict + +``` +Attribute attr.string_list_dict(allow_empty=True, *, configurable=unbound, default=\{\}, doc=None, mandatory=False) ``` Creates a schema for an attribute holding a dictionary, where the keys are strings and the values are lists of strings. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="string_list_dict.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True if the attribute can be empty.</td> -</tr> -<tr> -<td id="string_list_dict.configurable"><code>configurable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; or unbound; -default is <code>unbound</code><br /> -This argument can only be specified for an attribute of a symbolic macro. -<p>If <code>configurable</code> is explicitly set to <code>False</code>, the symbolic macro attribute is non-configurable - in other words, it cannot take a <code>select()</code> value. If the <code>configurable</code> is either unbound or explicitly set to <code>True</code>, the attribute is configurable and can take a <code>select()</code> value.</p> -<p>For an attribute of a rule or aspect, <code>configurable</code> must be left unbound. Most Starlark rule attributes are always configurable, with the exception of <code>attr.output()</code>, <code>attr.output_list()</code>, and <code>attr.license()</code> rule attributes, which are always non-configurable.</p></td> -</tr> -<tr> -<td id="string_list_dict.default"><code>default</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -A default value to use if no value for this attribute is given when instantiating the rule.</td> -</tr> -<tr> -<td id="string_list_dict.doc"><code>doc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -A description of the attribute that can be extracted by documentation generating tools.</td> -</tr> -<tr> -<td id="string_list_dict.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If true, the value must be specified explicitly (even if it has a <code>default</code>).</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | +| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | +| `default` | [dict](../core/dict.mdx); default is `\{\}` A default value to use if no value for this attribute is given when instantiating the rule. | +| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | \ No newline at end of file diff --git a/rules/lib/toplevel/cc_common.mdx b/rules/lib/toplevel/cc_common.mdx index fd8a39f..af85221 100644 --- a/rules/lib/toplevel/cc_common.mdx +++ b/rules/lib/toplevel/cc_common.mdx @@ -2,75 +2,54 @@ title: 'cc_common' --- -# cc_common -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcModuleApi.java" %} -{% include "\_buttons.html" %} Utilities for C++ compilation, linking, and command line generation. ## Members -- [action_is_enabled](#action_is_enabled) -- [CcToolchainInfo](#CcToolchainInfo) -- [compile](#compile) -- [configure_features](#configure_features) -- [create_cc_toolchain_config_info](#create_cc_toolchain_config_info) -- [create_compilation_context](#create_compilation_context) -- [create_compilation_outputs](#create_compilation_outputs) -- [create_compile_variables](#create_compile_variables) -- [create_library_to_link](#create_library_to_link) -- [create_link_variables](#create_link_variables) -- [create_linker_input](#create_linker_input) -- [create_linking_context](#create_linking_context) -- [create_linking_context_from_compilation_outputs](#create_linking_context_from_compilation_outputs) -- [create_lto_compilation_context](#create_lto_compilation_context) -- [do_not_use_tools_cpp_compiler_present](#do_not_use_tools_cpp_compiler_present) -- [get_environment_variables](#get_environment_variables) -- [get_execution_requirements](#get_execution_requirements) -- [get_memory_inefficient_command_line](#get_memory_inefficient_command_line) -- [get_tool_for_action](#get_tool_for_action) -- [is_enabled](#is_enabled) -- [link](#link) -- [merge_cc_infos](#merge_cc_infos) -- [merge_compilation_contexts](#merge_compilation_contexts) -- [merge_compilation_outputs](#merge_compilation_outputs) - -## action_is_enabled - -``` rule-signature +* [action\_is\_enabled](#action_is_enabled) +* [CcToolchainInfo](#CcToolchainInfo) +* [compile](#compile) +* [configure\_features](#configure_features) +* [create\_cc\_toolchain\_config\_info](#create_cc_toolchain_config_info) +* [create\_compilation\_context](#create_compilation_context) +* [create\_compilation\_outputs](#create_compilation_outputs) +* [create\_compile\_variables](#create_compile_variables) +* [create\_library\_to\_link](#create_library_to_link) +* [create\_link\_variables](#create_link_variables) +* [create\_linker\_input](#create_linker_input) +* [create\_linking\_context](#create_linking_context) +* [create\_linking\_context\_from\_compilation\_outputs](#create_linking_context_from_compilation_outputs) +* [create\_lto\_compilation\_context](#create_lto_compilation_context) +* [do\_not\_use\_tools\_cpp\_compiler\_present](#do_not_use_tools_cpp_compiler_present) +* [get\_environment\_variables](#get_environment_variables) +* [get\_execution\_requirements](#get_execution_requirements) +* [get\_memory\_inefficient\_command\_line](#get_memory_inefficient_command_line) +* [get\_tool\_for\_action](#get_tool_for_action) +* [is\_enabled](#is_enabled) +* [link](#link) +* [merge\_cc\_infos](#merge_cc_infos) +* [merge\_compilation\_contexts](#merge_compilation_contexts) +* [merge\_compilation\_outputs](#merge_compilation_outputs) + +## action\_is\_enabled + +``` bool cc_common.action_is_enabled(*, feature_configuration, action_name) ``` -Returns True if given action_config is enabled in the feature configuration. +Returns True if given action\_config is enabled in the feature configuration. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="action_is_enabled.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -Feature configuration to be queried.</td> -</tr> -<tr> -<td id="action_is_enabled.action_name"><code>action_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of the action_config.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | +| `action_name` | [string](../core/string.mdx); required Name of the action\_config. | ## CcToolchainInfo -``` rule-signature +``` Provider cc_common.CcToolchainInfo ``` @@ -78,7 +57,7 @@ The key used to retrieve the provider that contains information about the C++ to ## compile -``` rule-signature +``` tuple cc_common.compile(*, actions, feature_configuration, cc_toolchain, srcs=[], public_hdrs=[], private_hdrs=[], includes=[], quote_includes=[], system_includes=[], framework_includes=[], defines=[], local_defines=[], include_prefix='', strip_include_prefix='', user_compile_flags=[], conly_flags=[], cxx_flags=[], compilation_contexts=[], name, disallow_pic_outputs=False, disallow_nopic_outputs=False, additional_inputs=[], module_interfaces=unbound) ``` @@ -86,209 +65,53 @@ Should be used for C++ compilation. Returns tuple of (`CompilationContext`, `CcC ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="compile.actions"><code>actions</code></td> -<td><a href="../builtins/actions.html" class="anchor">actions</a>; -required<br /> -<code>actions</code> object.</td> -</tr> -<tr> -<td id="compile.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -<code>feature_configuration</code> to be queried.</td> -</tr> -<tr> -<td id="compile.cc_toolchain"><code>cc_toolchain</code></td> -<td>Info; -required<br /> -<code>CcToolchainInfo</code> provider to be used.</td> -</tr> -<tr> -<td id="compile.srcs"><code>srcs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -The list of source files to be compiled.</td> -</tr> -<tr> -<td id="compile.public_hdrs"><code>public_hdrs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of headers needed for compilation of srcs and may be included by dependent rules transitively.</td> -</tr> -<tr> -<td id="compile.private_hdrs"><code>private_hdrs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of headers needed for compilation of srcs and NOT to be included by dependent rules.</td> -</tr> -<tr> -<td id="compile.includes"><code>includes</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>[]</code><br /> -Search paths for header files referenced both by angle bracket and quotes. Usually passed with -I. Propagated to dependents transitively.</td> -</tr> -<tr> -<td id="compile.quote_includes"><code>quote_includes</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Search paths for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. Propagated to dependents transitively.</td> -</tr> -<tr> -<td id="compile.system_includes"><code>system_includes</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Search paths for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. Propagated to dependents transitively.</td> -</tr> -<tr> -<td id="compile.framework_includes"><code>framework_includes</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Search paths for header files from Apple frameworks. They can be either relative to the exec root or absolute. Usually passed with -F. Propagated to dependents transitively.</td> -</tr> -<tr> -<td id="compile.defines"><code>defines</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Set of defines needed to compile this target. Each define is a string. Propagated to dependents transitively.</td> -</tr> -<tr> -<td id="compile.local_defines"><code>local_defines</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Set of defines needed to compile this target. Each define is a string. Not propagated to dependents transitively.</td> -</tr> -<tr> -<td id="compile.include_prefix"><code>include_prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the strip_include_prefix attribute is removed before this prefix is added.</td> -</tr> -<tr> -<td id="compile.strip_include_prefix"><code>strip_include_prefix</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the include_prefix attribute is added after this prefix is stripped.</td> -</tr> -<tr> -<td id="compile.user_compile_flags"><code>user_compile_flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Additional list of compilation options.</td> -</tr> -<tr> -<td id="compile.conly_flags"><code>conly_flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Additional list of compilation options for C compiles.</td> -</tr> -<tr> -<td id="compile.cxx_flags"><code>cxx_flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Additional list of compilation options for C++ compiles.</td> -</tr> -<tr> -<td id="compile.compilation_contexts"><code>compilation_contexts</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Headers from dependencies used for compilation.</td> -</tr> -<tr> -<td id="compile.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -This is used for naming the output artifacts of actions created by this method. See also the `main_output` arg.</td> -</tr> -<tr> -<td id="compile.disallow_pic_outputs"><code>disallow_pic_outputs</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether PIC outputs should be created.</td> -</tr> -<tr> -<td id="compile.disallow_nopic_outputs"><code>disallow_nopic_outputs</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether NOPIC outputs should be created.</td> -</tr> -<tr> -<td id="compile.additional_inputs"><code>additional_inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of additional files needed for compilation of srcs</td> -</tr> -<tr> -<td id="compile.module_interfaces"><code>module_interfaces</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>unbound</code><br /> -The list of module interfaces source files to be compiled. Note: this is an experimental feature, only enabled with --experimental_cpp_modules</td> -</tr> -</tbody> -</table> - -## configure_features - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `actions` | [actions](../builtins/actions.mdx); required `actions` object. | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required `feature_configuration` to be queried. | +| `cc_toolchain` | Info; required `CcToolchainInfo` provider to be used. | +| `srcs` | [sequence](../core/list.mdx); default is `[]` The list of source files to be compiled. | +| `public_hdrs` | [sequence](../core/list.mdx); default is `[]` List of headers needed for compilation of srcs and may be included by dependent rules transitively. | +| `private_hdrs` | [sequence](../core/list.mdx); default is `[]` List of headers needed for compilation of srcs and NOT to be included by dependent rules. | +| `includes` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `[]` Search paths for header files referenced both by angle bracket and quotes. Usually passed with -I. Propagated to dependents transitively. | +| `quote_includes` | [sequence](../core/list.mdx); default is `[]` Search paths for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. Propagated to dependents transitively. | +| `system_includes` | [sequence](../core/list.mdx); default is `[]` Search paths for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. Propagated to dependents transitively. | +| `framework_includes` | [sequence](../core/list.mdx); default is `[]` Search paths for header files from Apple frameworks. They can be either relative to the exec root or absolute. Usually passed with -F. Propagated to dependents transitively. | +| `defines` | [sequence](../core/list.mdx); default is `[]` Set of defines needed to compile this target. Each define is a string. Propagated to dependents transitively. | +| `local_defines` | [sequence](../core/list.mdx); default is `[]` Set of defines needed to compile this target. Each define is a string. Not propagated to dependents transitively. | +| `include_prefix` | [string](../core/string.mdx); default is `''` The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the strip\_include\_prefix attribute is removed before this prefix is added. | +| `strip_include_prefix` | [string](../core/string.mdx); default is `''` The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the include\_prefix attribute is added after this prefix is stripped. | +| `user_compile_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of compilation options. | +| `conly_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of compilation options for C compiles. | +| `cxx_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of compilation options for C++ compiles. | +| `compilation_contexts` | [sequence](../core/list.mdx); default is `[]` Headers from dependencies used for compilation. | +| `name` | [string](../core/string.mdx); required This is used for naming the output artifacts of actions created by this method. See also the `main\_output` arg. | +| `disallow_pic_outputs` | [bool](../core/bool.mdx); default is `False` Whether PIC outputs should be created. | +| `disallow_nopic_outputs` | [bool](../core/bool.mdx); default is `False` Whether NOPIC outputs should be created. | +| `additional_inputs` | [sequence](../core/list.mdx); default is `[]` List of additional files needed for compilation of srcs | +| `module_interfaces` | [sequence](../core/list.mdx); default is `unbound` The list of module interfaces source files to be compiled. Note: this is an experimental feature, only enabled with --experimental\_cpp\_modules | + +## configure\_features + +``` FeatureConfiguration cc_common.configure_features(*, ctx, cc_toolchain, language=None, requested_features=[], unsupported_features=[]) ``` -Creates a feature_configuration instance. Requires the cpp configuration fragment. +Creates a feature\_configuration instance. Requires the cpp configuration fragment. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="configure_features.ctx"><code>ctx</code></td> -<td><a href="../builtins/ctx.html" class="anchor">ctx</a>; -required<br /> -The rule context.</td> -</tr> -<tr> -<td id="configure_features.cc_toolchain"><code>cc_toolchain</code></td> -<td>Info; -required<br /> -cc_toolchain for which we configure features.</td> -</tr> -<tr> -<td id="configure_features.language"><code>language</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The language to configure for: either c++ or objc (default c++)</td> -</tr> -<tr> -<td id="configure_features.requested_features"><code>requested_features</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of features to be enabled.</td> -</tr> -<tr> -<td id="configure_features.unsupported_features"><code>unsupported_features</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of features that are unsupported by the current rule.</td> -</tr> -</tbody> -</table> - -## create_cc_toolchain_config_info - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `ctx` | [ctx](../builtins/ctx.mdx); required The rule context. | +| `cc_toolchain` | Info; required cc\_toolchain for which we configure features. | +| `language` | [string](../core/string.mdx); or `None`; default is `None` The language to configure for: either c++ or objc (default c++) | +| `requested_features` | [sequence](../core/list.mdx); default is `[]` List of features to be enabled. | +| `unsupported_features` | [sequence](../core/list.mdx); default is `[]` List of features that are unsupported by the current rule. | + +## create\_cc\_toolchain\_config\_info + +``` None cc_common.create_cc_toolchain_config_info(*, ctx, features=[], action_configs=[], artifact_name_patterns=[], cxx_builtin_include_directories=[], toolchain_identifier, host_system_name=None, target_system_name=None, target_cpu=None, target_libc=None, compiler, abi_version=None, abi_libc_version=None, tool_paths=[], make_variables=[], builtin_sysroot=None) ``` @@ -296,142 +119,28 @@ Creates a `CcToolchainConfigInfo` provider ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_cc_toolchain_config_info.ctx"><code>ctx</code></td> -<td><a href="../builtins/ctx.html" class="anchor">ctx</a>; -required<br /> -The rule context.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.features"><code>features</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Contains all flag specifications for one feature. -<p>Arguments:</p> -<p><code>name</code>: The feature's name. It is possible to introduce a feature without a change to Bazel by adding a 'feature' section to the toolchain and adding the corresponding string as feature in the <code>BUILD</code> file.</p> -<p><code>enabled</code>: If 'True', this feature is enabled unless a rule type explicitly marks it as unsupported.</p> -<p><code>flag_sets</code>: A FlagSet list. If the given feature is enabled, the flag sets will be applied for the actions are specified for.</p> -<p><code>env_sets</code>: an EnvSet list. If the given feature is enabled, the env sets will be applied for the actions they are specified for.</p> -<p><code>requires</code>: A list of feature sets defining when this feature is supported by the toolchain. The feature is supported if any of the feature sets fully apply, that is, when all features of a feature set are enabled. If <code>requires</code> is omitted, the feature is supported independently of which other features are enabled. Use this for example to filter flags depending on the build mode enabled (opt / fastbuild / dbg).</p> -<p><code>implies</code>: A string list of features or action configs that are automatically enabled when this feature is enabled. If any of the implied features or action configs cannot be enabled, this feature will (silently) not be enabled either.</p> -<p><code>provides</code>: A list of names this feature conflicts with.</p> -A feature cannot be enabled if:- <code>provides</code> contains the name of a different feature or action config that we want to enable.- <code>provides</code> contains the same value as a 'provides' in a different feature or action config that we want to enable. Use this in order to ensure that incompatible features cannot be accidentally activated at the same time, leading to hard to diagnose compiler errors.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.action_configs"><code>action_configs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -An action config corresponds to a Bazel action, and allows selection of a tool based on activated features. Action config activation occurs by the same semantics as features: a feature can 'require' or 'imply' an action config in the same way that it would another feature. -<p>Arguments:</p> -<p><code>action_name</code>: The name of the Bazel action that this config applies to, e.g. 'c-compile' or 'c-module-compile'.</p> -<p><code>enabled</code>: If 'True', this action is enabled unless a rule type explicitly marks it as unsupported.</p> -<p><code>tools</code>: The tool applied to the action will be the first tool with a feature set that matches the feature configuration. An error will be thrown if no tool matches a provided feature configuration - for that reason, it's a good idea to provide a default tool with an empty feature set.</p> -<p><code>flag_sets</code>: If the given action config is enabled, the flag sets will be applied to the corresponding action.</p> -<p><code>implies</code>: A list of features or action configs that are automatically enabled when this action config is enabled. If any of the implied features or action configs cannot be enabled, this action config will (silently) not be enabled either.</p></td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.artifact_name_patterns"><code>artifact_name_patterns</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -The name for an artifact of a given category of input or output artifacts to an action. -<p>Arguments:</p> -<p><code>category_name</code>: The category of artifacts that this selection applies to. This field is compared against a list of categories defined in Bazel. Example categories include "linked_output" or the artifact for this selection. Together with the extension it is used to create an artifact name based on the target name.</p> -<p><code>extension</code>: The extension for creating the artifact for this selection. Together with the prefix it is used to create an artifact name based on the target name.</p></td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.cxx_builtin_include_directories"><code>cxx_builtin_include_directories</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> - <p>Built-in include directories for C++ compilation. These should be the exact paths used by the compiler, and are generally relative to the exec root.</p> -<p>The paths used by the compiler can be determined by 'gcc -E -xc++ - -v'.</p> -<p>We currently use the C++ paths also for C compilation, which is safe as long as there are no name clashes between C++ and C header files.</p> -<p>Relative paths are resolved relative to the configuration file directory.</p> -<p>If the compiler has --sysroot support, then these paths should use %sysroot% rather than the include path, and specify the sysroot attribute in order to give blaze the information necessary to make the correct replacements.</p></td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.toolchain_identifier"><code>toolchain_identifier</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> - <p>The unique identifier of the toolchain within the crosstool release. It must be possible to use this as a directory name in a path.</p> -<p>It has to match the following regex: [a-zA-Z_][\.\- \w]*</p></td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.host_system_name"><code>host_system_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Ignored.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.target_system_name"><code>target_system_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Deprecated. The GNU System Name. The string is exposed to CcToolchainInfo.target_gnu_system_name.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.target_cpu"><code>target_cpu</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Deprecated: Use cpu based constraints instead. If the string is "k8", `target_cpu` will be omitted from the filename of raw FDO profile data.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.target_libc"><code>target_libc</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Deprecated: Use OS based constraints instead. The libc version string (e.g. "glibc-2.2.2"). If the string is "macosx", platform is assumed to be MacOS. Otherwise, Linux. The string is exposed to CcToolchainInfo.libc.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.compiler"><code>compiler</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The compiler string (e.g. "gcc"). The current toolchain's compiler is exposed to `@bazel_tools//tools/cpp:compiler (compiler_flag)` as a flag value. Targets that require compiler-specific flags can use the config_settings in https://github.com/bazelbuild/rules_cc/blob/main/cc/compiler/BUILD in select() statements or create custom config_setting if the existing settings don't suffice.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.abi_version"><code>abi_version</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The abi in use, which is a gcc version. E.g.: "gcc-3.4". The string is set to C++ toolchain variable ABI.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.abi_libc_version"><code>abi_libc_version</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The glibc version used by the abi we're using. The string is set to C++ toolchain variable ABI_LIBC_VERSION.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.tool_paths"><code>tool_paths</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Tool locations. -<p>Arguments:</p> -<p><code>name</code>: Name of the tool.</p> -<p><code>path</code>: Location of the tool; Can be absolute path (in case of non hermetic toolchain), or path relative to the cc_toolchain's package.</p></td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.make_variables"><code>make_variables</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -A make variable that is made accessible to rules.</td> -</tr> -<tr> -<td id="create_cc_toolchain_config_info.builtin_sysroot"><code>builtin_sysroot</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The built-in sysroot. If this attribute is not present, Bazel does not allow using a different sysroot, i.e. through the --grte_top option.</td> -</tr> -</tbody> -</table> - -## create_compilation_context - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `ctx` | [ctx](../builtins/ctx.mdx); required The rule context. | +| `features` | [sequence](../core/list.mdx); default is `[]` Contains all flag specifications for one feature. Arguments: `name`: The feature's name. It is possible to introduce a feature without a change to Bazel by adding a 'feature' section to the toolchain and adding the corresponding string as feature in the `BUILD` file. `enabled`: If 'True', this feature is enabled unless a rule type explicitly marks it as unsupported. `flag_sets`: A FlagSet list. If the given feature is enabled, the flag sets will be applied for the actions are specified for. `env_sets`: an EnvSet list. If the given feature is enabled, the env sets will be applied for the actions they are specified for. `requires`: A list of feature sets defining when this feature is supported by the toolchain. The feature is supported if any of the feature sets fully apply, that is, when all features of a feature set are enabled. If `requires` is omitted, the feature is supported independently of which other features are enabled. Use this for example to filter flags depending on the build mode enabled (opt / fastbuild / dbg). `implies`: A string list of features or action configs that are automatically enabled when this feature is enabled. If any of the implied features or action configs cannot be enabled, this feature will (silently) not be enabled either. `provides`: A list of names this feature conflicts with. A feature cannot be enabled if:- `provides` contains the name of a different feature or action config that we want to enable.- `provides` contains the same value as a 'provides' in a different feature or action config that we want to enable. Use this in order to ensure that incompatible features cannot be accidentally activated at the same time, leading to hard to diagnose compiler errors. | +| `action_configs` | [sequence](../core/list.mdx); default is `[]` An action config corresponds to a Bazel action, and allows selection of a tool based on activated features. Action config activation occurs by the same semantics as features: a feature can 'require' or 'imply' an action config in the same way that it would another feature. Arguments: `action_name`: The name of the Bazel action that this config applies to, e.g. 'c-compile' or 'c-module-compile'. `enabled`: If 'True', this action is enabled unless a rule type explicitly marks it as unsupported. `tools`: The tool applied to the action will be the first tool with a feature set that matches the feature configuration. An error will be thrown if no tool matches a provided feature configuration - for that reason, it's a good idea to provide a default tool with an empty feature set. `flag_sets`: If the given action config is enabled, the flag sets will be applied to the corresponding action. `implies`: A list of features or action configs that are automatically enabled when this action config is enabled. If any of the implied features or action configs cannot be enabled, this action config will (silently) not be enabled either. | +| `artifact_name_patterns` | [sequence](../core/list.mdx); default is `[]` The name for an artifact of a given category of input or output artifacts to an action. Arguments: `category_name`: The category of artifacts that this selection applies to. This field is compared against a list of categories defined in Bazel. Example categories include "linked\_output" or the artifact for this selection. Together with the extension it is used to create an artifact name based on the target name. `extension`: The extension for creating the artifact for this selection. Together with the prefix it is used to create an artifact name based on the target name. | +| `cxx_builtin_include_directories` | [sequence](../core/list.mdx); default is `[]` Built-in include directories for C++ compilation. These should be the exact paths used by the compiler, and are generally relative to the exec root. The paths used by the compiler can be determined by 'gcc -E -xc++ - -v'. We currently use the C++ paths also for C compilation, which is safe as long as there are no name clashes between C++ and C header files. Relative paths are resolved relative to the configuration file directory. If the compiler has --sysroot support, then these paths should use %sysroot% rather than the include path, and specify the sysroot attribute in order to give blaze the information necessary to make the correct replacements. | +| `toolchain_identifier` | [string](../core/string.mdx); required The unique identifier of the toolchain within the crosstool release. It must be possible to use this as a directory name in a path. It has to match the following regex: [a-zA-Z\_][\.\- \w]\* | +| `host_system_name` | [string](../core/string.mdx); or `None`; default is `None` Ignored. | +| `target_system_name` | [string](../core/string.mdx); or `None`; default is `None` Deprecated. The GNU System Name. The string is exposed to CcToolchainInfo.target\_gnu\_system\_name. | +| `target_cpu` | [string](../core/string.mdx); or `None`; default is `None` Deprecated: Use cpu based constraints instead. If the string is "k8", `target\_cpu` will be omitted from the filename of raw FDO profile data. | +| `target_libc` | [string](../core/string.mdx); or `None`; default is `None` Deprecated: Use OS based constraints instead. The libc version string (e.g. "glibc-2.2.2"). If the string is "macosx", platform is assumed to be MacOS. Otherwise, Linux. The string is exposed to CcToolchainInfo.libc. | +| `compiler` | [string](../core/string.mdx); required The compiler string (e.g. "gcc"). The current toolchain's compiler is exposed to `@bazel\_tools//tools/cpp:compiler (compiler\_flag)` as a flag value. Targets that require compiler-specific flags can use the config\_settings in https://github.com/bazelbuild/rules\_cc/blob/main/cc/compiler/BUILD in select() statements or create custom config\_setting if the existing settings don't suffice. | +| `abi_version` | [string](../core/string.mdx); or `None`; default is `None` The abi in use, which is a gcc version. E.g.: "gcc-3.4". The string is set to C++ toolchain variable ABI. | +| `abi_libc_version` | [string](../core/string.mdx); or `None`; default is `None` The glibc version used by the abi we're using. The string is set to C++ toolchain variable ABI\_LIBC\_VERSION. | +| `tool_paths` | [sequence](../core/list.mdx); default is `[]` Tool locations. Arguments: `name`: Name of the tool. `path`: Location of the tool; Can be absolute path (in case of non hermetic toolchain), or path relative to the cc\_toolchain's package. | +| `make_variables` | [sequence](../core/list.mdx); default is `[]` A make variable that is made accessible to rules. | +| `builtin_sysroot` | [string](../core/string.mdx); or `None`; default is `None` The built-in sysroot. If this attribute is not present, Bazel does not allow using a different sysroot, i.e. through the --grte\_top option. | + +## create\_compilation\_context + +``` CompilationContext cc_common.create_compilation_context(*, headers=unbound, system_includes=unbound, includes=unbound, quote_includes=unbound, framework_includes=unbound, defines=unbound, local_defines=unbound) ``` @@ -439,55 +148,19 @@ Creates a `CompilationContext`. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_compilation_context.headers"><code>headers</code></td> -<td>default is <code>unbound</code><br /> -Set of headers needed to compile this target</td> -</tr> -<tr> -<td id="create_compilation_context.system_includes"><code>system_includes</code></td> -<td>default is <code>unbound</code><br /> -Set of search paths for header files referenced by angle brackets, i.e. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem</td> -</tr> -<tr> -<td id="create_compilation_context.includes"><code>includes</code></td> -<td>default is <code>unbound</code><br /> -Set of search paths for header files referenced both by angle bracket and quotes.Usually passed with -I</td> -</tr> -<tr> -<td id="create_compilation_context.quote_includes"><code>quote_includes</code></td> -<td>default is <code>unbound</code><br /> -Set of search paths for header files referenced by quotes, i.e. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote</td> -</tr> -<tr> -<td id="create_compilation_context.framework_includes"><code>framework_includes</code></td> -<td>default is <code>unbound</code><br /> -Set of framework search paths for header files (Apple platform only)</td> -</tr> -<tr> -<td id="create_compilation_context.defines"><code>defines</code></td> -<td>default is <code>unbound</code><br /> -Set of defines needed to compile this target. Each define is a string. Propagated transitively to dependents.</td> -</tr> -<tr> -<td id="create_compilation_context.local_defines"><code>local_defines</code></td> -<td>default is <code>unbound</code><br /> -Set of defines needed to compile this target. Each define is a string. Not propagated transitively to dependents.</td> -</tr> -</tbody> -</table> - -## create_compilation_outputs - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `headers` | default is `unbound` Set of headers needed to compile this target | +| `system_includes` | default is `unbound` Set of search paths for header files referenced by angle brackets, i.e. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem | +| `includes` | default is `unbound` Set of search paths for header files referenced both by angle bracket and quotes.Usually passed with -I | +| `quote_includes` | default is `unbound` Set of search paths for header files referenced by quotes, i.e. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote | +| `framework_includes` | default is `unbound` Set of framework search paths for header files (Apple platform only) | +| `defines` | default is `unbound` Set of defines needed to compile this target. Each define is a string. Propagated transitively to dependents. | +| `local_defines` | default is `unbound` Set of defines needed to compile this target. Each define is a string. Not propagated transitively to dependents. | + +## create\_compilation\_outputs + +``` CcCompilationOutputs cc_common.create_compilation_outputs(*, objects=None, pic_objects=None) ``` @@ -495,32 +168,14 @@ Create compilation outputs object. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_compilation_outputs.objects"><code>objects</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -List of object files.</td> -</tr> -<tr> -<td id="create_compilation_outputs.pic_objects"><code>pic_objects</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -List of pic object files.</td> -</tr> -</tbody> -</table> - -## create_compile_variables - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `objects` | [depset](../builtins/depset.mdx); or `None`; default is `None` List of object files. | +| `pic_objects` | [depset](../builtins/depset.mdx); or `None`; default is `None` List of pic object files. | + +## create\_compile\_variables + +``` Variables cc_common.create_compile_variables(*, cc_toolchain, feature_configuration, source_file=None, output_file=None, user_compile_flags=None, include_directories=None, quote_include_directories=None, system_include_directories=None, framework_include_directories=None, preprocessor_defines=None, thinlto_index=None, thinlto_input_bitcode_file=None, thinlto_output_object_file=None, use_pic=False, add_legacy_cxx_options=False, variables_extension=unbound) ``` @@ -528,206 +183,54 @@ Returns variables used for compilation actions. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_compile_variables.cc_toolchain"><code>cc_toolchain</code></td> -<td>Info; -required<br /> -cc_toolchain for which we are creating build variables.</td> -</tr> -<tr> -<td id="create_compile_variables.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -Feature configuration to be queried.</td> -</tr> -<tr> -<td id="create_compile_variables.source_file"><code>source_file</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Optional source file path for the compilation. Please prefer passing source_file here over appending it to the end of the command line generated from cc_common.get_memory_inefficient_command_line, as then it's in the power of the toolchain author to properly specify and position compiler flags.</td> -</tr> -<tr> -<td id="create_compile_variables.output_file"><code>output_file</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Optional output file path of the compilation. Please prefer passing output_file here over appending it to the end of the command line generated from cc_common.get_memory_inefficient_command_line, as then it's in the power of the toolchain author to properly specify and position compiler flags.</td> -</tr> -<tr> -<td id="create_compile_variables.user_compile_flags"><code>user_compile_flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -List of additional compilation flags (copts).</td> -</tr> -<tr> -<td id="create_compile_variables.include_directories"><code>include_directories</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -Depset of include directories.</td> -</tr> -<tr> -<td id="create_compile_variables.quote_include_directories"><code>quote_include_directories</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -Depset of quote include directories.</td> -</tr> -<tr> -<td id="create_compile_variables.system_include_directories"><code>system_include_directories</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -Depset of system include directories.</td> -</tr> -<tr> -<td id="create_compile_variables.framework_include_directories"><code>framework_include_directories</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -Depset of framework include directories.</td> -</tr> -<tr> -<td id="create_compile_variables.preprocessor_defines"><code>preprocessor_defines</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; or <code>None</code>; -default is <code>None</code><br /> -Depset of preprocessor defines.</td> -</tr> -<tr> -<td id="create_compile_variables.thinlto_index"><code>thinlto_index</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -LTO index file path.</td> -</tr> -<tr> -<td id="create_compile_variables.thinlto_input_bitcode_file"><code>thinlto_input_bitcode_file</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Bitcode file that is input to LTO backend.</td> -</tr> -<tr> -<td id="create_compile_variables.thinlto_output_object_file"><code>thinlto_output_object_file</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -Object file that is output by LTO backend.</td> -</tr> -<tr> -<td id="create_compile_variables.use_pic"><code>use_pic</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -When true the compilation will generate position independent code.</td> -</tr> -<tr> -<td id="create_compile_variables.add_legacy_cxx_options"><code>add_legacy_cxx_options</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Unused.</td> -</tr> -<tr> -<td id="create_compile_variables.variables_extension"><code>variables_extension</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>unbound</code><br /> -A dictionary of additional variables used by compile actions.</td> -</tr> -</tbody> -</table> - -## create_library_to_link - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `cc_toolchain` | Info; required cc\_toolchain for which we are creating build variables. | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | +| `source_file` | [File](../builtins/File.mdx); or [string](../core/string.mdx); or `None`; default is `None` Optional source file path for the compilation. Please prefer passing source\_file here over appending it to the end of the command line generated from cc\_common.get\_memory\_inefficient\_command\_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. | +| `output_file` | [File](../builtins/File.mdx); or [string](../core/string.mdx); or `None`; default is `None` Optional output file path of the compilation. Please prefer passing output\_file here over appending it to the end of the command line generated from cc\_common.get\_memory\_inefficient\_command\_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. | +| `user_compile_flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` List of additional compilation flags (copts). | +| `include_directories` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of include directories. | +| `quote_include_directories` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of quote include directories. | +| `system_include_directories` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of system include directories. | +| `framework_include_directories` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of framework include directories. | +| `preprocessor_defines` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of preprocessor defines. | +| `thinlto_index` | [string](../core/string.mdx); or `None`; default is `None` LTO index file path. | +| `thinlto_input_bitcode_file` | [string](../core/string.mdx); or `None`; default is `None` Bitcode file that is input to LTO backend. | +| `thinlto_output_object_file` | [string](../core/string.mdx); or `None`; default is `None` Object file that is output by LTO backend. | +| `use_pic` | [bool](../core/bool.mdx); default is `False` When true the compilation will generate position independent code. | +| `add_legacy_cxx_options` | [bool](../core/bool.mdx); default is `False` Unused. | +| `variables_extension` | [dict](../core/dict.mdx); default is `unbound` A dictionary of additional variables used by compile actions. | + +## create\_library\_to\_link + +``` LibraryToLink cc_common.create_library_to_link(*, actions, feature_configuration=None, cc_toolchain=None, static_library=None, pic_static_library=None, dynamic_library=None, interface_library=None, pic_objects=unbound, objects=unbound, alwayslink=False, dynamic_library_symlink_path='', interface_library_symlink_path='') ``` Creates `LibraryToLink` + ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_library_to_link.actions"><code>actions</code></td> -<td>required<br /> -<code>actions</code> object.</td> -</tr> -<tr> -<td id="create_library_to_link.feature_configuration"><code>feature_configuration</code></td> -<td>default is <code>None</code><br /> -<code>feature_configuration</code> to be queried.</td> -</tr> -<tr> -<td id="create_library_to_link.cc_toolchain"><code>cc_toolchain</code></td> -<td>default is <code>None</code><br /> -<code>CcToolchainInfo</code> provider to be used.</td> -</tr> -<tr> -<td id="create_library_to_link.static_library"><code>static_library</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -<code>File</code> of static library to be linked.</td> -</tr> -<tr> -<td id="create_library_to_link.pic_static_library"><code>pic_static_library</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -<code>File</code> of pic static library to be linked.</td> -</tr> -<tr> -<td id="create_library_to_link.dynamic_library"><code>dynamic_library</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -<code>File</code> of dynamic library to be linked. Always used for runtime and used for linking if <code>interface_library</code> is not passed.</td> -</tr> -<tr> -<td id="create_library_to_link.interface_library"><code>interface_library</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -<code>File</code> of interface library to be linked.</td> -</tr> -<tr> -<td id="create_library_to_link.pic_objects"><code>pic_objects</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>unbound</code><br /> -Experimental, do not use</td> -</tr> -<tr> -<td id="create_library_to_link.objects"><code>objects</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>unbound</code><br /> -Experimental, do not use</td> -</tr> -<tr> -<td id="create_library_to_link.alwayslink"><code>alwayslink</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether to link the static library/objects in the --whole_archive block.</td> -</tr> -<tr> -<td id="create_library_to_link.dynamic_library_symlink_path"><code>dynamic_library_symlink_path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Override the default path of the dynamic library link in the solib directory. Empty string to use the default.</td> -</tr> -<tr> -<td id="create_library_to_link.interface_library_symlink_path"><code>interface_library_symlink_path</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>''</code><br /> -Override the default path of the interface library link in the solib directory. Empty string to use the default.</td> -</tr> -</tbody> -</table> - -## create_link_variables - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `actions` | required `actions` object. | +| `feature_configuration` | default is `None` `feature_configuration` to be queried. | +| `cc_toolchain` | default is `None` `CcToolchainInfo` provider to be used. | +| `static_library` | [File](../builtins/File.mdx); or `None`; default is `None` `File` of static library to be linked. | +| `pic_static_library` | [File](../builtins/File.mdx); or `None`; default is `None` `File` of pic static library to be linked. | +| `dynamic_library` | [File](../builtins/File.mdx); or `None`; default is `None` `File` of dynamic library to be linked. Always used for runtime and used for linking if `interface_library` is not passed. | +| `interface_library` | [File](../builtins/File.mdx); or `None`; default is `None` `File` of interface library to be linked. | +| `pic_objects` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `unbound` Experimental, do not use | +| `objects` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `unbound` Experimental, do not use | +| `alwayslink` | [bool](../core/bool.mdx); default is `False` Whether to link the static library/objects in the --whole\_archive block. | +| `dynamic_library_symlink_path` | [string](../core/string.mdx); default is `''` Override the default path of the dynamic library link in the solib directory. Empty string to use the default. | +| `interface_library_symlink_path` | [string](../core/string.mdx); default is `''` Override the default path of the interface library link in the solib directory. Empty string to use the default. | + +## create\_link\_variables + +``` Variables cc_common.create_link_variables(*, cc_toolchain, feature_configuration, library_search_directories=[], runtime_library_search_directories=[], user_link_flags=[], output_file=None, param_file=None, is_using_linker=True, is_linking_dynamic_library=False, must_keep_debug=True, use_test_only_flags=False, is_static_linking_mode=True) ``` @@ -735,90 +238,24 @@ Returns link variables used for linking actions. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_link_variables.cc_toolchain"><code>cc_toolchain</code></td> -<td>Info; -required<br /> -cc_toolchain for which we are creating build variables.</td> -</tr> -<tr> -<td id="create_link_variables.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -Feature configuration to be queried.</td> -</tr> -<tr> -<td id="create_link_variables.library_search_directories"><code>library_search_directories</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>[]</code><br /> -Depset of directories where linker will look for libraries at link time.</td> -</tr> -<tr> -<td id="create_link_variables.runtime_library_search_directories"><code>runtime_library_search_directories</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>[]</code><br /> -Depset of directories where loader will look for libraries at runtime.</td> -</tr> -<tr> -<td id="create_link_variables.user_link_flags"><code>user_link_flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of additional link flags (linkopts).</td> -</tr> -<tr> -<td id="create_link_variables.output_file"><code>output_file</code></td> -<td>default is <code>None</code><br /> -Optional output file path.</td> -</tr> -<tr> -<td id="create_link_variables.param_file"><code>param_file</code></td> -<td>default is <code>None</code><br /> -Optional param file path.</td> -</tr> -<tr> -<td id="create_link_variables.is_using_linker"><code>is_using_linker</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True when using linker, False when archiver. Caller is responsible for keeping this in sync with action name used (is_using_linker = True for linking executable or dynamic library, is_using_linker = False for archiving static library).</td> -</tr> -<tr> -<td id="create_link_variables.is_linking_dynamic_library"><code>is_linking_dynamic_library</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -True when creating dynamic library, False when executable or static library. Caller is responsible for keeping this in sync with action name used. This field will be removed once b/65151735 is fixed.</td> -</tr> -<tr> -<td id="create_link_variables.must_keep_debug"><code>must_keep_debug</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -When set to False, bazel will expose 'strip_debug_symbols' variable, which is usually used to use the linker to strip debug symbols from the output file.</td> -</tr> -<tr> -<td id="create_link_variables.use_test_only_flags"><code>use_test_only_flags</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -When set to true, 'is_cc_test' variable will be set.</td> -</tr> -<tr> -<td id="create_link_variables.is_static_linking_mode"><code>is_static_linking_mode</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -Unused.</td> -</tr> -</tbody> -</table> - -## create_linker_input - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `cc_toolchain` | Info; required cc\_toolchain for which we are creating build variables. | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | +| `library_search_directories` | [depset](../builtins/depset.mdx); default is `[]` Depset of directories where linker will look for libraries at link time. | +| `runtime_library_search_directories` | [depset](../builtins/depset.mdx); default is `[]` Depset of directories where loader will look for libraries at runtime. | +| `user_link_flags` | [sequence](../core/list.mdx); default is `[]` List of additional link flags (linkopts). | +| `output_file` | default is `None` Optional output file path. | +| `param_file` | default is `None` Optional param file path. | +| `is_using_linker` | [bool](../core/bool.mdx); default is `True` True when using linker, False when archiver. Caller is responsible for keeping this in sync with action name used (is\_using\_linker = True for linking executable or dynamic library, is\_using\_linker = False for archiving static library). | +| `is_linking_dynamic_library` | [bool](../core/bool.mdx); default is `False` True when creating dynamic library, False when executable or static library. Caller is responsible for keeping this in sync with action name used. This field will be removed once b/65151735 is fixed. | +| `must_keep_debug` | [bool](../core/bool.mdx); default is `True` When set to False, bazel will expose 'strip\_debug\_symbols' variable, which is usually used to use the linker to strip debug symbols from the output file. | +| `use_test_only_flags` | [bool](../core/bool.mdx); default is `False` When set to true, 'is\_cc\_test' variable will be set. | +| `is_static_linking_mode` | [bool](../core/bool.mdx); default is `True` Unused. | + +## create\_linker\_input + +``` LinkerInput cc_common.create_linker_input(*, owner, libraries=None, user_link_flags=None, additional_inputs=None) ``` @@ -826,44 +263,16 @@ Creates a `LinkerInput`. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_linker_input.owner"><code>owner</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; -required<br /> -The label of the target that produced all files used in this input.</td> -</tr> -<tr> -<td id="create_linker_input.libraries"><code>libraries</code></td> -<td><code>None</code>; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>None</code><br /> -List of <code>LibraryToLink</code>.</td> -</tr> -<tr> -<td id="create_linker_input.user_link_flags"><code>user_link_flags</code></td> -<td><code>None</code>; or <a href="../builtins/depset.html" class="anchor">depset</a> of <a href="../core/string.html" class="anchor">string</a>s; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>None</code><br /> -User link flags passed as strings. Accepts either [String], [[String]] or depset(String). The latter is discouraged as it's only kept for compatibility purposes, the depset is flattened. If you want to propagate user_link_flags via unflattened depsets() wrap them in a LinkerInput so that they are not flattened till the end.</td> -</tr> -<tr> -<td id="create_linker_input.additional_inputs"><code>additional_inputs</code></td> -<td><code>None</code>; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>None</code><br /> -For additional inputs to the linking action, e.g.: linking scripts.</td> -</tr> -</tbody> -</table> - -## create_linking_context - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `owner` | [Label](../builtins/Label.mdx); required The label of the target that produced all files used in this input. | +| `libraries` | `None`; or [depset](../builtins/depset.mdx); default is `None` List of `LibraryToLink`. | +| `user_link_flags` | `None`; or [depset](../builtins/depset.mdx) of [string](../core/string.mdx)s; or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `None` User link flags passed as strings. Accepts either [String], [[String]] or depset(String). The latter is discouraged as it's only kept for compatibility purposes, the depset is flattened. If you want to propagate user\_link\_flags via unflattened depsets() wrap them in a LinkerInput so that they are not flattened till the end. | +| `additional_inputs` | `None`; or [depset](../builtins/depset.mdx); default is `None` For additional inputs to the linking action, e.g.: linking scripts. | + +## create\_linking\_context + +``` LinkingContext cc_common.create_linking_context(*, linker_inputs) ``` @@ -871,26 +280,13 @@ Creates a `LinkingContext`. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_linking_context.linker_inputs"><code>linker_inputs</code></td> -<td><a href="../builtins/depset.html" class="anchor">depset</a>; -required<br /> -Depset of <code>LinkerInput</code>.</td> -</tr> -</tbody> -</table> - -## create_linking_context_from_compilation_outputs - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `linker_inputs` | [depset](../builtins/depset.mdx); required Depset of `LinkerInput`. | + +## create\_linking\_context\_from\_compilation\_outputs + +``` tuple cc_common.create_linking_context_from_compilation_outputs(*, actions, name, feature_configuration, cc_toolchain, language='c++', disallow_static_libraries=False, disallow_dynamic_library=False, compilation_outputs, linking_contexts=[], user_link_flags=[], alwayslink=False, additional_inputs=[], variables_extension=unbound) ``` @@ -898,133 +294,47 @@ Should be used for creating library rules that can propagate information downstr ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_linking_context_from_compilation_outputs.actions"><code>actions</code></td> -<td><a href="../builtins/actions.html" class="anchor">actions</a>; -required<br /> -<code>actions</code> object.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -This is used for naming the output artifacts of actions created by this method.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -<code>feature_configuration</code> to be queried.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.cc_toolchain"><code>cc_toolchain</code></td> -<td>Info; -required<br /> -<code>CcToolchainInfo</code> provider to be used.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.language"><code>language</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'c++'</code><br /> -Only C++ supported for now. Do not use this parameter.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.disallow_static_libraries"><code>disallow_static_libraries</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether static libraries should be created.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.disallow_dynamic_library"><code>disallow_dynamic_library</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether a dynamic library should be created.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.compilation_outputs"><code>compilation_outputs</code></td> -<td><a href="../builtins/CcCompilationOutputs.html" class="anchor">CcCompilationOutputs</a>; -required<br /> -Compilation outputs containing object files to link.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.linking_contexts"><code>linking_contexts</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Libraries from dependencies. These libraries will be linked into the output artifact of the link() call, be it a binary or a library.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.user_link_flags"><code>user_link_flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Additional list of linking options.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.alwayslink"><code>alwayslink</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether this library should always be linked.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.additional_inputs"><code>additional_inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -For additional inputs to the linking action, e.g.: linking scripts.</td> -</tr> -<tr> -<td id="create_linking_context_from_compilation_outputs.variables_extension"><code>variables_extension</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>unbound</code><br /> -Additional variables to pass to the toolchain configuration when creating link command line.</td> -</tr> -</tbody> -</table> - -## create_lto_compilation_context - -``` rule-signature -LtoCompilationContext cc_common.create_lto_compilation_context(*, objects={}) +| Parameter | Description | +| --- | --- | +| `actions` | [actions](../builtins/actions.mdx); required `actions` object. | +| `name` | [string](../core/string.mdx); required This is used for naming the output artifacts of actions created by this method. | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required `feature_configuration` to be queried. | +| `cc_toolchain` | Info; required `CcToolchainInfo` provider to be used. | +| `language` | [string](../core/string.mdx); default is `'c++'` Only C++ supported for now. Do not use this parameter. | +| `disallow_static_libraries` | [bool](../core/bool.mdx); default is `False` Whether static libraries should be created. | +| `disallow_dynamic_library` | [bool](../core/bool.mdx); default is `False` Whether a dynamic library should be created. | +| `compilation_outputs` | [CcCompilationOutputs](../builtins/CcCompilationOutputs.mdx); required Compilation outputs containing object files to link. | +| `linking_contexts` | [sequence](../core/list.mdx); default is `[]` Libraries from dependencies. These libraries will be linked into the output artifact of the link() call, be it a binary or a library. | +| `user_link_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of linking options. | +| `alwayslink` | [bool](../core/bool.mdx); default is `False` Whether this library should always be linked. | +| `additional_inputs` | [sequence](../core/list.mdx); default is `[]` For additional inputs to the linking action, e.g.: linking scripts. | +| `variables_extension` | [dict](../core/dict.mdx); default is `unbound` Additional variables to pass to the toolchain configuration when creating link command line. | + +## create\_lto\_compilation\_context + +``` +LtoCompilationContext cc_common.create_lto_compilation_context(*, objects=\{\}) ``` Create LTO compilation context ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="create_lto_compilation_context.objects"><code>objects</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -map of full object to index object</td> -</tr> -</tbody> -</table> - -## do_not_use_tools_cpp_compiler_present - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `objects` | [dict](../core/dict.mdx); default is `\{\}` map of full object to index object | + +## do\_not\_use\_tools\_cpp\_compiler\_present + +``` None cc_common.do_not_use_tools_cpp_compiler_present ``` -Do not use this field, its only purpose is to help with migration from config_setting.values{'compiler') to config_settings.flag_values{'@bazel_tools//tools/cpp:compiler'} +Do not use this field, its only purpose is to help with migration from config\_setting.values\{'compiler') to config\_settings.flag\_values\{'@bazel\_tools//tools/cpp:compiler'\} -## get_environment_variables +## get\_environment\_variables -``` rule-signature +``` dict cc_common.get_environment_variables(*, feature_configuration, action_name, variables) ``` @@ -1032,38 +342,15 @@ Returns environment variables to be set for given action. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="get_environment_variables.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -Feature configuration to be queried.</td> -</tr> -<tr> -<td id="get_environment_variables.action_name"><code>action_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl)</td> -</tr> -<tr> -<td id="get_environment_variables.variables"><code>variables</code></td> -<td>Variables; -required<br /> -Build variables to be used for template expansion.</td> -</tr> -</tbody> -</table> - -## get_execution_requirements - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | +| `action_name` | [string](../core/string.mdx); required Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) | +| `variables` | Variables; required Build variables to be used for template expansion. | + +## get\_execution\_requirements + +``` sequence cc_common.get_execution_requirements(*, feature_configuration, action_name) ``` @@ -1071,32 +358,14 @@ Returns execution requirements for given action. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="get_execution_requirements.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -Feature configuration to be queried.</td> -</tr> -<tr> -<td id="get_execution_requirements.action_name"><code>action_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl)</td> -</tr> -</tbody> -</table> - -## get_memory_inefficient_command_line - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | +| `action_name` | [string](../core/string.mdx); required Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) | + +## get\_memory\_inefficient\_command\_line + +``` sequence cc_common.get_memory_inefficient_command_line(*, feature_configuration, action_name, variables) ``` @@ -1104,38 +373,15 @@ Returns flattened command line flags for given action, using given variables for ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="get_memory_inefficient_command_line.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -Feature configuration to be queried.</td> -</tr> -<tr> -<td id="get_memory_inefficient_command_line.action_name"><code>action_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl)</td> -</tr> -<tr> -<td id="get_memory_inefficient_command_line.variables"><code>variables</code></td> -<td>Variables; -required<br /> -Build variables to be used for template expansions.</td> -</tr> -</tbody> -</table> - -## get_tool_for_action - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | +| `action_name` | [string](../core/string.mdx); required Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) | +| `variables` | Variables; required Build variables to be used for template expansions. | + +## get\_tool\_for\_action + +``` string cc_common.get_tool_for_action(*, feature_configuration, action_name) ``` @@ -1143,32 +389,14 @@ Returns tool path for given action. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="get_tool_for_action.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -Feature configuration to be queried.</td> -</tr> -<tr> -<td id="get_tool_for_action.action_name"><code>action_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of the action. Has to be one of the names in @bazel_tools//tools/build_defs/cc:action_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl)</td> -</tr> -</tbody> -</table> - -## is_enabled - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | +| `action_name` | [string](../core/string.mdx); required Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) | + +## is\_enabled + +``` bool cc_common.is_enabled(*, feature_configuration, feature_name) ``` @@ -1176,137 +404,41 @@ Returns True if given feature is enabled in the feature configuration. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="is_enabled.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -Feature configuration to be queried.</td> -</tr> -<tr> -<td id="is_enabled.feature_name"><code>feature_name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of the feature.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | +| `feature_name` | [string](../core/string.mdx); required Name of the feature. | ## link -``` rule-signature -CcLinkingOutputs cc_common.link(*, actions, name, feature_configuration, cc_toolchain, language='c++', output_type='executable', link_deps_statically=True, compilation_outputs=None, linking_contexts=[], user_link_flags=[], stamp=0, additional_inputs=[], additional_outputs=[], variables_extension={}) +``` +CcLinkingOutputs cc_common.link(*, actions, name, feature_configuration, cc_toolchain, language='c++', output_type='executable', link_deps_statically=True, compilation_outputs=None, linking_contexts=[], user_link_flags=[], stamp=0, additional_inputs=[], additional_outputs=[], variables_extension=\{\}) ``` Should be used for C++ transitive linking. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="link.actions"><code>actions</code></td> -<td><a href="../builtins/actions.html" class="anchor">actions</a>; -required<br /> -<code>actions</code> object.</td> -</tr> -<tr> -<td id="link.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -This is used for naming the output artifacts of actions created by this method.</td> -</tr> -<tr> -<td id="link.feature_configuration"><code>feature_configuration</code></td> -<td><a href="../builtins/FeatureConfiguration.html" class="anchor">FeatureConfiguration</a>; -required<br /> -<code>feature_configuration</code> to be queried.</td> -</tr> -<tr> -<td id="link.cc_toolchain"><code>cc_toolchain</code></td> -<td>Info; -required<br /> -<code>CcToolchainInfo</code> provider to be used.</td> -</tr> -<tr> -<td id="link.language"><code>language</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'c++'</code><br /> -Only C++ supported for now. Do not use this parameter.</td> -</tr> -<tr> -<td id="link.output_type"><code>output_type</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'executable'</code><br /> -Can be either 'executable' or 'dynamic_library'.</td> -</tr> -<tr> -<td id="link.link_deps_statically"><code>link_deps_statically</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -True to link dependencies statically, False dynamically.</td> -</tr> -<tr> -<td id="link.compilation_outputs"><code>compilation_outputs</code></td> -<td><a href="../builtins/CcCompilationOutputs.html" class="anchor">CcCompilationOutputs</a>; or <code>None</code>; -default is <code>None</code><br /> -Compilation outputs containing object files to link.</td> -</tr> -<tr> -<td id="link.linking_contexts"><code>linking_contexts</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Linking contexts from dependencies to be linked into the linking context generated by this rule.</td> -</tr> -<tr> -<td id="link.user_link_flags"><code>user_link_flags</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -Additional list of linker options.</td> -</tr> -<tr> -<td id="link.stamp"><code>stamp</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>0</code><br /> -Whether to include build information in the linked executable, if output_type is 'executable'. If 1, build information is always included. If 0 (the default build information is always excluded. If -1, uses the default behavior, which may be overridden by the --[no]stamp flag. This should be unset (or set to 0) when generating the executable output for test rules.</td> -</tr> -<tr> -<td id="link.additional_inputs"><code>additional_inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <a href="../builtins/depset.html" class="anchor">depset</a>; -default is <code>[]</code><br /> -For additional inputs to the linking action, e.g.: linking scripts.</td> -</tr> -<tr> -<td id="link.additional_outputs"><code>additional_outputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -For additional outputs to the linking action, e.g.: map files.</td> -</tr> -<tr> -<td id="link.variables_extension"><code>variables_extension</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -Additional variables to pass to the toolchain configuration when create link command line.</td> -</tr> -</tbody> -</table> - -## merge_cc_infos - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `actions` | [actions](../builtins/actions.mdx); required `actions` object. | +| `name` | [string](../core/string.mdx); required This is used for naming the output artifacts of actions created by this method. | +| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required `feature_configuration` to be queried. | +| `cc_toolchain` | Info; required `CcToolchainInfo` provider to be used. | +| `language` | [string](../core/string.mdx); default is `'c++'` Only C++ supported for now. Do not use this parameter. | +| `output_type` | [string](../core/string.mdx); default is `'executable'` Can be either 'executable' or 'dynamic\_library'. | +| `link_deps_statically` | [bool](../core/bool.mdx); default is `True` True to link dependencies statically, False dynamically. | +| `compilation_outputs` | [CcCompilationOutputs](../builtins/CcCompilationOutputs.mdx); or `None`; default is `None` Compilation outputs containing object files to link. | +| `linking_contexts` | [sequence](../core/list.mdx); default is `[]` Linking contexts from dependencies to be linked into the linking context generated by this rule. | +| `user_link_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of linker options. | +| `stamp` | [int](../core/int.mdx); default is `0` Whether to include build information in the linked executable, if output\_type is 'executable'. If 1, build information is always included. If 0 (the default build information is always excluded. If -1, uses the default behavior, which may be overridden by the --[no]stamp flag. This should be unset (or set to 0) when generating the executable output for test rules. | +| `additional_inputs` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `[]` For additional inputs to the linking action, e.g.: linking scripts. | +| `additional_outputs` | [sequence](../core/list.mdx); default is `[]` For additional outputs to the linking action, e.g.: map files. | +| `variables_extension` | [dict](../core/dict.mdx); default is `\{\}` Additional variables to pass to the toolchain configuration when create link command line. | + +## merge\_cc\_infos + +``` unknown cc_common.merge_cc_infos(*, direct_cc_infos=[], cc_infos=[]) ``` @@ -1314,32 +446,14 @@ Merges multiple `CcInfo`s into one. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="merge_cc_infos.direct_cc_infos"><code>direct_cc_infos</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of <code>CcInfo</code>s to be merged, whose headers will be exported by the direct fields in the returned provider.</td> -</tr> -<tr> -<td id="merge_cc_infos.cc_infos"><code>cc_infos</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of <code>CcInfo</code>s to be merged, whose headers will not be exported by the direct fields in the returned provider.</td> -</tr> -</tbody> -</table> - -## merge_compilation_contexts - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `direct_cc_infos` | [sequence](../core/list.mdx); default is `[]` List of `CcInfo`s to be merged, whose headers will be exported by the direct fields in the returned provider. | +| `cc_infos` | [sequence](../core/list.mdx); default is `[]` List of `CcInfo`s to be merged, whose headers will not be exported by the direct fields in the returned provider. | + +## merge\_compilation\_contexts + +``` CompilationContext cc_common.merge_compilation_contexts(*, compilation_contexts=[]) ``` @@ -1347,26 +461,13 @@ Merges multiple `CompilationContexts`s into one. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="merge_compilation_contexts.compilation_contexts"><code>compilation_contexts</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -List of <code>CompilationContexts</code>s to be merged. The headers of each context will be exported by the direct fields in the returned provider.</td> -</tr> -</tbody> -</table> - -## merge_compilation_outputs - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `compilation_contexts` | [sequence](../core/list.mdx); default is `[]` List of `CompilationContexts`s to be merged. The headers of each context will be exported by the direct fields in the returned provider. | + +## merge\_compilation\_outputs + +``` CcCompilationOutputs cc_common.merge_compilation_outputs(*, compilation_outputs=[]) ``` @@ -1374,19 +475,6 @@ Merge compilation outputs. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="merge_compilation_outputs.compilation_outputs"><code>compilation_outputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `compilation_outputs` | [sequence](../core/list.mdx); default is `[]` | \ No newline at end of file diff --git a/rules/lib/toplevel/config.mdx b/rules/lib/toplevel/config.mdx index 9429803..2b9b218 100644 --- a/rules/lib/toplevel/config.mdx +++ b/rules/lib/toplevel/config.mdx @@ -2,15 +2,12 @@ title: 'config' --- -# config -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/StarlarkConfigApi.java" %} -{% include "\_buttons.html" %} This is a top-level module for creating configuration transitions and build setting descriptors which describe what kind of build setting (if any) a rule is. ex: the following rule is marked as a build setting by setting the `build_setting` parameter of the `rule()` function. Specifically it is a build setting of type `int` and is a `flag` which means this build setting is callable on the command line. -``` python +``` my_rule = rule( implementation = _impl, build_setting = config.int(flag = True), @@ -20,18 +17,18 @@ ex: the following rule is marked as a build setting by setting the `build_settin ## Members -- [bool](#bool) -- [exec](#exec) -- [int](#int) -- [none](#none) -- [string](#string) -- [string_list](#string_list) -- [string_set](#string_set) -- [target](#target) +* [bool](#bool) +* [exec](#exec) +* [int](#int) +* [none](#none) +* [string](#string) +* [string\_list](#string_list) +* [string\_set](#string_set) +* [target](#target) ## bool -``` rule-signature +``` BuildSetting config.bool(*, flag=False) ``` @@ -39,26 +36,13 @@ A bool-typed build setting ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="bool.flag"><code>flag</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether or not this build setting is callable on the command line.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `flag` | [bool](../core/bool.mdx); default is `False` | ## exec -``` rule-signature +``` ExecTransitionFactory config.exec(exec_group=None) ``` @@ -66,26 +50,13 @@ Creates an execution transition. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="exec.exec_group"><code>exec_group</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <code>None</code>; -default is <code>None</code><br /> -The name of the exec group whose execution platform this transition will use. If not provided, this exec transition will use the target's default execution platform.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `exec_group` | [string](../core/string.mdx); or `None`; default is `None` The name of the exec group whose execution platform this transition will use. If not provided, this exec transition will use the target's default execution platform. | ## int -``` rule-signature +``` BuildSetting config.int(*, flag=False) ``` @@ -93,26 +64,13 @@ An integer-typed build setting ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="int.flag"><code>flag</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether or not this build setting is callable on the command line.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `flag` | [bool](../core/bool.mdx); default is `False` Whether or not this build setting is callable on the command line. | ## none -``` rule-signature +``` transition config.none() ``` @@ -120,7 +78,7 @@ Creates a transition which removes all configuration, unsetting all flags. Inten ## string -``` rule-signature +``` BuildSetting config.string(*, flag=False, allow_multiple=False) ``` @@ -128,32 +86,14 @@ A string-typed build setting ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="string.flag"><code>flag</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether or not this build setting is callable on the command line.</td> -</tr> -<tr> -<td id="string.allow_multiple"><code>allow_multiple</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Deprecated, use a <code>string_list</code> setting with <code>repeatable = True</code> instead. If set, this flag is allowed to be set multiple times on the command line. The Value of the flag as accessed in transitions and build setting implementation function will be a list of strings. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired.</td> -</tr> -</tbody> -</table> - -## string_list - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `flag` | [bool](../core/bool.mdx); default is `False` Whether or not this build setting is callable on the command line. | +| `allow_multiple` | [bool](../core/bool.mdx); default is `False` Deprecated, use a `string_list` setting with `repeatable = True` instead. If set, this flag is allowed to be set multiple times on the command line. The Value of the flag as accessed in transitions and build setting implementation function will be a list of strings. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. | + +## string\_list + +``` BuildSetting config.string_list(*, flag=False, repeatable=False) ``` @@ -161,32 +101,14 @@ A string list-typed build setting. On the command line pass a list using comma-s ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="string_list.flag"><code>flag</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether or not this build setting is callable on the command line.</td> -</tr> -<tr> -<td id="string_list.repeatable"><code>repeatable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the list value. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired.</td> -</tr> -</tbody> -</table> - -## string_set - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `flag` | [bool](../core/bool.mdx); default is `False` Whether or not this build setting is callable on the command line. | +| `repeatable` | [bool](../core/bool.mdx); default is `False` If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the list value. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. | + +## string\_set + +``` BuildSetting config.string_set(*, flag=False, repeatable=False) ``` @@ -196,33 +118,15 @@ Unlike with a `string_list`, the order of the elements doesn't matter and only a ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="string_set.flag"><code>flag</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether or not this build setting is callable on the command line.</td> -</tr> -<tr> -<td id="string_set.repeatable"><code>repeatable</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the set value. Only a single instance of repeated values is maintained and the insertion order does not matter.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `flag` | [bool](../core/bool.mdx); default is `False` Whether or not this build setting is callable on the command line. | +| `repeatable` | [bool](../core/bool.mdx); default is `False` If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the set value. Only a single instance of repeated values is maintained and the insertion order does not matter. | ## target -``` rule-signature +``` transition config.target() ``` -Creates a target transition. This is a no-op transition intended for the case where a transition object is needed, but doesn't want to actually change anything. Equivalent to `cfg = "target"` in `attr.label()`. +Creates a target transition. This is a no-op transition intended for the case where a transition object is needed, but doesn't want to actually change anything. Equivalent to `cfg = "target"` in `attr.label()`. \ No newline at end of file diff --git a/rules/lib/toplevel/config_common.mdx b/rules/lib/toplevel/config_common.mdx index 9d12b24..071e28f 100644 --- a/rules/lib/toplevel/config_common.mdx +++ b/rules/lib/toplevel/config_common.mdx @@ -2,28 +2,25 @@ title: 'config_common' --- -# config_common -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigStarlarkCommonApi.java" %} -{% include "\_buttons.html" %} Functions for Starlark to interact with Blaze's configurability APIs. ## Members -- [FeatureFlagInfo](#FeatureFlagInfo) -- [toolchain_type](#toolchain_type) +* [FeatureFlagInfo](#FeatureFlagInfo) +* [toolchain\_type](#toolchain_type) ## FeatureFlagInfo -``` rule-signature +``` Provider config_common.FeatureFlagInfo ``` -The key used to retrieve the provider containing config_feature_flag's value. +The key used to retrieve the provider containing config\_feature\_flag's value. -## toolchain_type +## toolchain\_type -``` rule-signature +``` toolchain_type config_common.toolchain_type(name, *, mandatory=True) ``` @@ -31,25 +28,7 @@ Declare a rule's dependency on a toolchain type. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="toolchain_type.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; -required<br /> -The toolchain type that is required.</td> -</tr> -<tr> -<td id="toolchain_type.mandatory"><code>mandatory</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -Whether the toolchain type is mandatory or optional.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); required The toolchain type that is required. | +| `mandatory` | [bool](../core/bool.mdx); default is `True` Whether the toolchain type is mandatory or optional. | \ No newline at end of file diff --git a/rules/lib/toplevel/coverage_common.mdx b/rules/lib/toplevel/coverage_common.mdx index 54ed6fa..372b7e2 100644 --- a/rules/lib/toplevel/coverage_common.mdx +++ b/rules/lib/toplevel/coverage_common.mdx @@ -2,69 +2,28 @@ title: 'coverage_common' --- -# coverage_common -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java" %} -{% include "\_buttons.html" %} Helper functions to access coverage-related infrastructure. ## Members -- [instrumented_files_info](#instrumented_files_info) +* [instrumented\_files\_info](#instrumented_files_info) -## instrumented_files_info +## instrumented\_files\_info -``` rule-signature +``` InstrumentedFilesInfo coverage_common.instrumented_files_info(ctx, *, source_attributes=[], dependency_attributes=[], extensions=None, metadata_files=[], baseline_coverage_files=None) ``` -Creates a new <a href="../providers/InstrumentedFilesInfo.html" class="anchor">InstrumentedFilesInfo</a> instance. Use this provider to communicate coverage-related attributes of the current build rule. +Creates a new [InstrumentedFilesInfo](../providers/InstrumentedFilesInfo.mdx) instance. Use this provider to communicate coverage-related attributes of the current build rule. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="instrumented_files_info.ctx"><code>ctx</code></td> -<td><a href="../builtins/ctx.html" class="anchor">ctx</a>; -required<br /> -The rule context.</td> -</tr> -<tr> -<td id="instrumented_files_info.source_attributes"><code>source_attributes</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -A list of attribute names which contain source files processed by this rule.</td> -</tr> -<tr> -<td id="instrumented_files_info.dependency_attributes"><code>dependency_attributes</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -A list of attribute names which might provide runtime dependencies (either code dependencies or runfiles).</td> -</tr> -<tr> -<td id="instrumented_files_info.extensions"><code>extensions</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -File extensions used to filter files from source_attributes. For example, 'js'. If not provided (or None), then all files from source_attributes will be added to instrumented files, if an empty list is provided, then no files from source attributes will be added.</td> -</tr> -<tr> -<td id="instrumented_files_info.metadata_files"><code>metadata_files</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -Additional files required to generate coverage LCOV files after code execution. e.g. .gcno files for C++.</td> -</tr> -<tr> -<td id="instrumented_files_info.baseline_coverage_files"><code>baseline_coverage_files</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; or <code>None</code>; -default is <code>None</code><br /> -</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `ctx` | [ctx](../builtins/ctx.mdx); required The rule context. | +| `source_attributes` | [sequence](../core/list.mdx); default is `[]` A list of attribute names which contain source files processed by this rule. | +| `dependency_attributes` | [sequence](../core/list.mdx); default is `[]` A list of attribute names which might provide runtime dependencies (either code dependencies or runfiles). | +| `extensions` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` File extensions used to filter files from source\_attributes. For example, 'js'. If not provided (or None), then all files from source\_attributes will be added to instrumented files, if an empty list is provided, then no files from source attributes will be added. | +| `metadata_files` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` Additional files required to generate coverage LCOV files after code execution. e.g. .gcno files for C++. | +| `baseline_coverage_files` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or `None`; default is `None` | \ No newline at end of file diff --git a/rules/lib/toplevel/java_common.mdx b/rules/lib/toplevel/java_common.mdx index 2290100..20f3f17 100644 --- a/rules/lib/toplevel/java_common.mdx +++ b/rules/lib/toplevel/java_common.mdx @@ -2,26 +2,23 @@ title: 'java_common' --- -# java_common -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java" %} -{% include "\_buttons.html" %} Utilities for Java compilation support in Starlark. ## Members -- [BootClassPathInfo](#BootClassPathInfo) -- [compile](#compile) -- [JavaRuntimeInfo](#JavaRuntimeInfo) -- [JavaToolchainInfo](#JavaToolchainInfo) -- [merge](#merge) -- [pack_sources](#pack_sources) -- [run_ijar](#run_ijar) -- [stamp_jar](#stamp_jar) +* [BootClassPathInfo](#BootClassPathInfo) +* [compile](#compile) +* [JavaRuntimeInfo](#JavaRuntimeInfo) +* [JavaToolchainInfo](#JavaToolchainInfo) +* [merge](#merge) +* [pack\_sources](#pack_sources) +* [run\_ijar](#run_ijar) +* [stamp\_jar](#stamp_jar) ## BootClassPathInfo -``` rule-signature +``` Provider java_common.BootClassPathInfo ``` @@ -29,7 +26,7 @@ The provider used to supply bootclasspath information ## compile -``` rule-signature +``` struct java_common.compile(ctx, *, source_jars=[], source_files=[], output, output_source_jar=None, javac_opts=[], deps=[], runtime_deps=[], exports=[], plugins=[], exported_plugins=[], native_libraries=[], annotation_processor_additional_inputs=[], annotation_processor_additional_outputs=[], strict_deps='ERROR', java_toolchain, bootclasspath=None, sourcepath=[], resources=[], resource_jars=[], classpath_resources=[], neverlink=False, enable_annotation_processing=True, enable_compile_jar_action=True, add_exports=[], add_opens=[]) ``` @@ -37,177 +34,38 @@ Compiles Java source files/jars from the implementation of a Starlark rule and r ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="compile.ctx"><code>ctx</code></td> -<td><a href="../builtins/ctx.html" class="anchor">ctx</a>; -required<br /> -The rule context.</td> -</tr> -<tr> -<td id="compile.source_jars"><code>source_jars</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -A list of the jars to be compiled. At least one of source_jars or source_files should be specified.</td> -</tr> -<tr> -<td id="compile.source_files"><code>source_files</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -A list of the Java source files to be compiled. At least one of source_jars or source_files should be specified.</td> -</tr> -<tr> -<td id="compile.output"><code>output</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -</td> -</tr> -<tr> -<td id="compile.output_source_jar"><code>output_source_jar</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -The output source jar. Defaults to `{output_jar}-src.jar` if unset.</td> -</tr> -<tr> -<td id="compile.javac_opts"><code>javac_opts</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A list of the desired javac options.</td> -</tr> -<tr> -<td id="compile.deps"><code>deps</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; -default is <code>[]</code><br /> -A list of dependencies.</td> -</tr> -<tr> -<td id="compile.runtime_deps"><code>runtime_deps</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; -default is <code>[]</code><br /> -A list of runtime dependencies.</td> -</tr> -<tr> -<td id="compile.exports"><code>exports</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; -default is <code>[]</code><br /> -A list of exports.</td> -</tr> -<tr> -<td id="compile.plugins"><code>plugins</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; -default is <code>[]</code><br /> -A list of plugins.</td> -</tr> -<tr> -<td id="compile.exported_plugins"><code>exported_plugins</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; or <a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; -default is <code>[]</code><br /> -A list of exported plugins.</td> -</tr> -<tr> -<td id="compile.native_libraries"><code>native_libraries</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../providers/CcInfo.html" class="anchor">CcInfo</a>s; -default is <code>[]</code><br /> -CC native library dependencies that are needed for this library.</td> -</tr> -<tr> -<td id="compile.annotation_processor_additional_inputs"><code>annotation_processor_additional_inputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -A list of inputs that the Java compilation action will take in addition to the Java sources for annotation processing.</td> -</tr> -<tr> -<td id="compile.annotation_processor_additional_outputs"><code>annotation_processor_additional_outputs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -A list of outputs that the Java compilation action will output in addition to the class jar from annotation processing.</td> -</tr> -<tr> -<td id="compile.strict_deps"><code>strict_deps</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -default is <code>'ERROR'</code><br /> -A string that specifies how to handle strict deps. Possible values: 'OFF', 'ERROR', 'WARN' and 'DEFAULT'. For more details see ---strict_java_deps -flag. By default 'ERROR'.</td> -</tr> -<tr> -<td id="compile.java_toolchain"><code>java_toolchain</code></td> -<td>Info; -required<br /> -A JavaToolchainInfo to be used for this compilation. Mandatory.</td> -</tr> -<tr> -<td id="compile.bootclasspath"><code>bootclasspath</code></td> -<td>default is <code>None</code><br /> -A BootClassPathInfo to be used for this compilation. If present, overrides the bootclasspath associated with the provided java_toolchain.</td> -</tr> -<tr> -<td id="compile.sourcepath"><code>sourcepath</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -</td> -</tr> -<tr> -<td id="compile.resources"><code>resources</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -</td> -</tr> -<tr> -<td id="compile.resource_jars"><code>resource_jars</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -</td> -</tr> -<tr> -<td id="compile.classpath_resources"><code>classpath_resources</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -</td> -</tr> -<tr> -<td id="compile.neverlink"><code>neverlink</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -</td> -</tr> -<tr> -<td id="compile.enable_annotation_processing"><code>enable_annotation_processing</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -Disables annotation processing in this compilation, causing any annotation processors provided in plugins or in exported_plugins of deps to be ignored.</td> -</tr> -<tr> -<td id="compile.enable_compile_jar_action"><code>enable_compile_jar_action</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>True</code><br /> -Enables header compilation or ijar creation. If set to False, it forces use of the full class jar in the compilation classpaths of any dependants. Doing so is intended for use by non-library targets such as binaries that do not have dependants.</td> -</tr> -<tr> -<td id="compile.add_exports"><code>add_exports</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Allow this library to access the given /.</td> -</tr> -<tr> -<td id="compile.add_opens"><code>add_opens</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Allow this library to reflectively access the given /.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `ctx` | [ctx](../builtins/ctx.mdx); required The rule context. | +| `source_jars` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of the jars to be compiled. At least one of source\_jars or source\_files should be specified. | +| `source_files` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of the Java source files to be compiled. At least one of source\_jars or source\_files should be specified. | +| `output` | [File](../builtins/File.mdx); required | +| `output_source_jar` | [File](../builtins/File.mdx); or `None`; default is `None` The output source jar. Defaults to `\{output\_jar\}-src.jar` if unset. | +| `javac_opts` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A list of the desired javac options. | +| `deps` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of dependencies. | +| `runtime_deps` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of runtime dependencies. | +| `exports` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of exports. | +| `plugins` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; or [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of plugins. | +| `exported_plugins` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; or [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of exported plugins. | +| `native_libraries` | [sequence](../core/list.mdx) of [CcInfo](../providers/CcInfo.mdx)s; default is `[]` CC native library dependencies that are needed for this library. | +| `annotation_processor_additional_inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of inputs that the Java compilation action will take in addition to the Java sources for annotation processing. | +| `annotation_processor_additional_outputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of outputs that the Java compilation action will output in addition to the class jar from annotation processing. | +| `strict_deps` | [string](../core/string.mdx); default is `'ERROR'` A string that specifies how to handle strict deps. Possible values: 'OFF', 'ERROR', 'WARN' and 'DEFAULT'. For more details see [`--strict_java_deps flag`](./docs/user-manual#flag--strict_java_deps). By default 'ERROR'. | +| `java_toolchain` | Info; required A JavaToolchainInfo to be used for this compilation. Mandatory. | +| `bootclasspath` | default is `None` A BootClassPathInfo to be used for this compilation. If present, overrides the bootclasspath associated with the provided java\_toolchain. | +| `sourcepath` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` | +| `resources` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` | +| `resource_jars` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` | +| `classpath_resources` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` | +| `neverlink` | [bool](../core/bool.mdx); default is `False` | +| `enable_annotation_processing` | [bool](../core/bool.mdx); default is `True` Disables annotation processing in this compilation, causing any annotation processors provided in plugins or in exported\_plugins of deps to be ignored. | +| `enable_compile_jar_action` | [bool](../core/bool.mdx); default is `True` Enables header compilation or ijar creation. If set to False, it forces use of the full class jar in the compilation classpaths of any dependants. Doing so is intended for use by non-library targets such as binaries that do not have dependants. | +| `add_exports` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Allow this library to access the given /. | +| `add_opens` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Allow this library to reflectively access the given /. | ## JavaRuntimeInfo -``` rule-signature +``` Provider java_common.JavaRuntimeInfo ``` @@ -215,7 +73,7 @@ The key used to retrieve the provider that contains information about the Java r ## JavaToolchainInfo -``` rule-signature +``` Provider java_common.JavaToolchainInfo ``` @@ -223,7 +81,7 @@ The key used to retrieve the provider that contains information about the Java t ## merge -``` rule-signature +``` struct java_common.merge(providers) ``` @@ -231,164 +89,62 @@ Merges the given providers into a single JavaInfo. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="merge.providers"><code>providers</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/struct.html" class="anchor">struct</a>s; -required<br /> -The list of providers to merge.</td> -</tr> -</tbody> -</table> - -## pack_sources - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `providers` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; required The list of providers to merge. | + +## pack\_sources + +``` File java_common.pack_sources(actions, *, output_source_jar=None, sources=[], source_jars=[], java_toolchain) ``` Packs sources and source jars into a single source jar file. The return value is typically passed to -<a href="../providers/JavaInfo.html" class="anchor"><code>JavaInfo</code></a>`#source_jar` +`JavaInfo#source_jar` -.At least one of parameters output_jar or output_source_jar is required. +.At least one of parameters output\_jar or output\_source\_jar is required. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="pack_sources.actions"><code>actions</code></td> -<td><a href="../builtins/actions.html" class="anchor">actions</a>; -required<br /> -ctx.actions</td> -</tr> -<tr> -<td id="pack_sources.output_source_jar"><code>output_source_jar</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; or <code>None</code>; -default is <code>None</code><br /> -The output source jar.</td> -</tr> -<tr> -<td id="pack_sources.sources"><code>sources</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -A list of Java source files to be packed into the source jar.</td> -</tr> -<tr> -<td id="pack_sources.source_jars"><code>source_jars</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../builtins/File.html" class="anchor">File</a>s; -default is <code>[]</code><br /> -A list of source jars to be packed into the source jar.</td> -</tr> -<tr> -<td id="pack_sources.java_toolchain"><code>java_toolchain</code></td> -<td>Info; -required<br /> -A JavaToolchainInfo to used to find the ijar tool.</td> -</tr> -</tbody> -</table> - -## run_ijar - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `actions` | [actions](../builtins/actions.mdx); required ctx.actions | +| `output_source_jar` | [File](../builtins/File.mdx); or `None`; default is `None` The output source jar. | +| `sources` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of Java source files to be packed into the source jar. | +| `source_jars` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of source jars to be packed into the source jar. | +| `java_toolchain` | Info; required A JavaToolchainInfo to used to find the ijar tool. | + +## run\_ijar + +``` File java_common.run_ijar(actions, *, jar, target_label=None, java_toolchain) ``` -Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding of dependent jars during any recompiles consisting only of simple changes to method implementations. The return value is typically passed to <a href="../providers/JavaInfo.html" class="anchor"><code>JavaInfo</code></a>`#compile_jar`. +Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding of dependent jars during any recompiles consisting only of simple changes to method implementations. The return value is typically passed to `JavaInfo#compile_jar`. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="run_ijar.actions"><code>actions</code></td> -<td><a href="../builtins/actions.html" class="anchor">actions</a>; -required<br /> -ctx.actions</td> -</tr> -<tr> -<td id="run_ijar.jar"><code>jar</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The jar to run ijar on.</td> -</tr> -<tr> -<td id="run_ijar.target_label"><code>target_label</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; or <code>None</code>; -default is <code>None</code><br /> -A target label to stamp the jar with. Used for <code>add_dep</code> support. Typically, you would pass <code>ctx.label</code> to stamp the jar with the current rule's label.</td> -</tr> -<tr> -<td id="run_ijar.java_toolchain"><code>java_toolchain</code></td> -<td>Info; -required<br /> -A JavaToolchainInfo to used to find the ijar tool.</td> -</tr> -</tbody> -</table> - -## stamp_jar - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `actions` | [actions](../builtins/actions.mdx); required ctx.actions | +| `jar` | [File](../builtins/File.mdx); required The jar to run ijar on. | +| `target_label` | [Label](../builtins/Label.mdx); or `None`; default is `None` A target label to stamp the jar with. Used for `add_dep` support. Typically, you would pass `ctx.label` to stamp the jar with the current rule's label. | +| `java_toolchain` | Info; required A JavaToolchainInfo to used to find the ijar tool. | + +## stamp\_jar + +``` File java_common.stamp_jar(actions, *, jar, target_label, java_toolchain) ``` -Stamps a jar with a target label for `add_dep` support. The return value is typically passed to <a href="../providers/JavaInfo.html" class="anchor"><code>JavaInfo</code></a>`#compile_jar`. Prefer to use <a href="#run_ijar" class="anchor"><code>run_ijar</code></a> when possible. +Stamps a jar with a target label for `add_dep` support. The return value is typically passed to `JavaInfo#compile_jar`. Prefer to use `run_ijar` when possible. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="stamp_jar.actions"><code>actions</code></td> -<td><a href="../builtins/actions.html" class="anchor">actions</a>; -required<br /> -ctx.actions</td> -</tr> -<tr> -<td id="stamp_jar.jar"><code>jar</code></td> -<td><a href="../builtins/File.html" class="anchor">File</a>; -required<br /> -The jar to run stamp_jar on.</td> -</tr> -<tr> -<td id="stamp_jar.target_label"><code>target_label</code></td> -<td><a href="../builtins/Label.html" class="anchor">Label</a>; -required<br /> -A target label to stamp the jar with. Used for <code>add_dep</code> support. Typically, you would pass <code>ctx.label</code> to stamp the jar with the current rule's label.</td> -</tr> -<tr> -<td id="stamp_jar.java_toolchain"><code>java_toolchain</code></td> -<td>Info; -required<br /> -A JavaToolchainInfo to used to find the stamp_jar tool.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `actions` | [actions](../builtins/actions.mdx); required ctx.actions | +| `jar` | [File](../builtins/File.mdx); required The jar to run stamp\_jar on. | +| `target_label` | [Label](../builtins/Label.mdx); required A target label to stamp the jar with. Used for `add_dep` support. Typically, you would pass `ctx.label` to stamp the jar with the current rule's label. | +| `java_toolchain` | Info; required A JavaToolchainInfo to used to find the stamp\_jar tool. | \ No newline at end of file diff --git a/rules/lib/toplevel/native.mdx b/rules/lib/toplevel/native.mdx index 6ca8dcf..8a11ae4 100644 --- a/rules/lib/toplevel/native.mdx +++ b/rules/lib/toplevel/native.mdx @@ -2,32 +2,29 @@ title: 'native' --- -# native -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java" %} -{% include "\_buttons.html" %} A built-in module to support native rules and other package helper functions. All native rules appear as functions in this module, e.g. `native.cc_library`. Note that the native module is only available in the loading phase (i.e. for macros, not for rule implementations). Attributes will ignore `None` values, and treat them as if the attribute was unset. The following functions are also available: ## Members -- [existing_rule](#existing_rule) -- [existing_rules](#existing_rules) -- [exports_files](#exports_files) -- [glob](#glob) -- [module_name](#module_name) -- [module_version](#module_version) -- [package_default_visibility](#package_default_visibility) -- [package_group](#package_group) -- [package_name](#package_name) -- [package_relative_label](#package_relative_label) -- [repo_name](#repo_name) -- [repository_name](#repository_name) -- [subpackages](#subpackages) - -## existing_rule - -``` rule-signature +* [existing\_rule](#existing_rule) +* [existing\_rules](#existing_rules) +* [exports\_files](#exports_files) +* [glob](#glob) +* [module\_name](#module_name) +* [module\_version](#module_version) +* [package\_default\_visibility](#package_default_visibility) +* [package\_group](#package_group) +* [package\_name](#package_name) +* [package\_relative\_label](#package_relative_label) +* [repo\_name](#repo_name) +* [repository\_name](#repository_name) +* [subpackages](#subpackages) + +## existing\_rule + +``` unknown native.existing_rule(name) ``` @@ -39,36 +36,23 @@ The result contains an entry for each attribute, with the exception of private o The values of the result represent attribute values as follows: -- Attributes of type str, int, and bool are represented as is. -- Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. -- Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. -- `select` values are returned with their contents transformed as described above. -- Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). +* Attributes of type str, int, and bool are represented as is. +* Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. +* Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. +* `select` values are returned with their contents transformed as described above. +* Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by `ctx.attr.foo`. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="existing_rule.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The name of the target.</td> -</tr> -</tbody> -</table> - -## existing_rules - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required | + +## existing\_rules + +``` unknown native.existing_rules() ``` @@ -78,9 +62,9 @@ Here, an *immutable dict-like object* means a deeply immutable object `x` suppor If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. -## exports_files +## exports\_files -``` rule-signature +``` None native.exports_files(srcs, visibility=None, licenses=None) ``` @@ -88,113 +72,63 @@ Specifies a list of files belonging to this package that are exported to other p ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="exports_files.srcs"><code>srcs</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The list of files to export.</td> -</tr> -<tr> -<td id="exports_files.visibility"><code>visibility</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; or <code>None</code>; -default is <code>None</code><br /> -A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package.</td> -</tr> -<tr> -<td id="exports_files.licenses"><code>licenses</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; or <code>None</code>; -default is <code>None</code><br /> -Licenses to be specified.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `srcs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The list of files to export. | +| `visibility` | [sequence](../core/list.mdx); or `None`; default is `None` A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. | +| `licenses` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Licenses to be specified. | ## glob -``` rule-signature +``` sequence native.glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound) ``` Glob returns a new, mutable, sorted list of every file in the current package that: -- Matches at least one pattern in `include`. -- Does not match any of the patterns in `exclude` (default `[]`). +* Matches at least one pattern in `include`. +* Does not match any of the patterns in `exclude` (default `[]`). If the `exclude_directories` argument is enabled (set to `1`), files of type directory will be omitted from the results (default `1`). ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="glob.include"><code>include</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -The list of glob patterns to include.</td> -</tr> -<tr> -<td id="glob.exclude"><code>exclude</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -The list of glob patterns to exclude.</td> -</tr> -<tr> -<td id="glob.exclude_directories"><code>exclude_directories</code></td> -<td><a href="../core/int.html" class="anchor">int</a>; -default is <code>1</code><br /> -A flag whether to exclude directories or not.</td> -</tr> -<tr> -<td id="glob.allow_empty"><code>allow_empty</code></td> -<td>default is <code>unbound</code><br /> -Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded).</td> -</tr> -</tbody> -</table> - -## module_name - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `include` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to include. | +| `exclude` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to exclude. | +| `exclude_directories` | [int](../core/int.mdx); default is `1` A flag whether to exclude directories or not. | +| `allow_empty` | default is `unbound` Whether we allow glob patterns to match nothing. If `allow\_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). | + +## module\_name + +``` string native.module_name() ``` The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the `module.name` field seen in `module_ctx.modules`. May return `None`. -## module_version +## module\_version -``` rule-signature +``` string native.module_version() ``` The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the `module.version` field seen in `module_ctx.modules`. May return `None`. -## package_default_visibility +## package\_default\_visibility -``` rule-signature +``` List native.package_default_visibility() ``` Returns the default visibility of the package being evaluated. This is the value of the `default_visibility` parameter of `package()`, extended to include the package itself. -## package_group +## package\_group -``` rule-signature +``` None native.package_group(*, name, packages=[], includes=[]) ``` @@ -202,50 +136,27 @@ This function defines a set of packages and assigns a label to the group. The la ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="package_group.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -The unique name for this rule.</td> -</tr> -<tr> -<td id="package_group.packages"><code>packages</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A complete enumeration of packages in this group.</td> -</tr> -<tr> -<td id="package_group.includes"><code>includes</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -Other package groups that are included in this one.</td> -</tr> -</tbody> -</table> - -## package_name - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required The unique name for this rule. | +| `packages` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A complete enumeration of packages in this group. | +| `includes` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Other package groups that are included in this one. | + +## package\_name + +``` string native.package_name() ``` The name of the package being evaluated, without the repository name. For example, in the BUILD file `some/package/BUILD`, its value will be `some/package`. If the BUILD file calls a function defined in a .bzl file, `package_name()` will match the caller BUILD file package. The value will always be an empty string for the root package. -## package_relative_label +## package\_relative\_label -``` rule-signature +``` Label native.package_relative_label(input) ``` -Converts the input string into a [Label](../builtins/Label.html) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. +Converts the input string into a [Label](../builtins/Label.mdx) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. @@ -255,77 +166,41 @@ The result of this function is the same `Label` value as would be produced by pa ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="package_relative_label.input"><code>input</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; or <a href="../builtins/Label.html" class="anchor">Label</a>; -required<br /> -The input label string or Label object. If a Label object is passed, it's returned as is.</td> -</tr> -</tbody> -</table> - -## repo_name - -``` rule-signature +| Parameter | Description | +| --- | --- | +| `input` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); required The input label string or Label object. If a Label object is passed, it's returned as is. | + +## repo\_name + +``` string native.repo_name() ``` The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. -## repository_name +## repository\_name -``` rule-signature +``` string native.repository_name() ``` -**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` +**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` **Deprecated.** Prefer to use [`repo_name`](#repo_name) instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise. The canonical name of the repository containing the package currently being evaluated, with a single at-sign (`@`) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza `local_repository(name='local', path=...)` it will be set to `@local`. In packages in the main repository, it will be set to `@`. ## subpackages -``` rule-signature +``` sequence native.subpackages(*, include, exclude=[], allow_empty=False) ``` -Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel_skylib.subpackages module rather than calling this function directly. +Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel\_skylib.subpackages module rather than calling this function directly. ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="subpackages.include"><code>include</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -required<br /> -The list of glob patterns to include in subpackages scan.</td> -</tr> -<tr> -<td id="subpackages.exclude"><code>exclude</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -The list of glob patterns to exclude from subpackages scan.</td> -</tr> -<tr> -<td id="subpackages.allow_empty"><code>allow_empty</code></td> -<td><a href="../core/bool.html" class="anchor">bool</a>; -default is <code>False</code><br /> -Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `include` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required | +| `exclude` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to exclude from subpackages scan. | +| `allow_empty` | [bool](../core/bool.mdx); default is `False` Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. | \ No newline at end of file diff --git a/rules/lib/toplevel/platform_common.mdx b/rules/lib/toplevel/platform_common.mdx index 54478bf..42c5234 100644 --- a/rules/lib/toplevel/platform_common.mdx +++ b/rules/lib/toplevel/platform_common.mdx @@ -2,59 +2,56 @@ title: 'platform_common' --- -# platform_common -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java" %} -{% include "\_buttons.html" %} Functions for Starlark to interact with the platform APIs. ## Members -- [ConstraintSettingInfo](#ConstraintSettingInfo) -- [ConstraintValueInfo](#ConstraintValueInfo) -- [PlatformInfo](#PlatformInfo) -- [TemplateVariableInfo](#TemplateVariableInfo) -- [ToolchainInfo](#ToolchainInfo) +* [ConstraintSettingInfo](#ConstraintSettingInfo) +* [ConstraintValueInfo](#ConstraintValueInfo) +* [PlatformInfo](#PlatformInfo) +* [TemplateVariableInfo](#TemplateVariableInfo) +* [ToolchainInfo](#ToolchainInfo) ## ConstraintSettingInfo -``` rule-signature +``` Provider platform_common.ConstraintSettingInfo ``` -The constructor/key for the [ConstraintSettingInfo](../providers/ConstraintSettingInfo.html) provider. +The constructor/key for the [ConstraintSettingInfo](../providers/ConstraintSettingInfo.mdx) provider. *Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* ## ConstraintValueInfo -``` rule-signature +``` Provider platform_common.ConstraintValueInfo ``` -The constructor/key for the [ConstraintValueInfo](../providers/ConstraintValueInfo.html) provider. +The constructor/key for the [ConstraintValueInfo](../providers/ConstraintValueInfo.mdx) provider. *Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* ## PlatformInfo -``` rule-signature +``` Provider platform_common.PlatformInfo ``` -The constructor/key for the [PlatformInfo](../providers/PlatformInfo.html) provider. +The constructor/key for the [PlatformInfo](../providers/PlatformInfo.mdx) provider. *Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* ## TemplateVariableInfo -``` rule-signature +``` Provider platform_common.TemplateVariableInfo ``` -The constructor/key for the [TemplateVariableInfo](../providers/TemplateVariableInfo.html) provider. +The constructor/key for the [TemplateVariableInfo](../providers/TemplateVariableInfo.mdx) provider. ## ToolchainInfo -``` rule-signature +``` Provider platform_common.ToolchainInfo ``` -The constructor/key for the [ToolchainInfo](../providers/ToolchainInfo.html) provider. +The constructor/key for the [ToolchainInfo](../providers/ToolchainInfo.mdx) provider. \ No newline at end of file diff --git a/rules/lib/toplevel/proto.mdx b/rules/lib/toplevel/proto.mdx index d293839..e13cd3c 100644 --- a/rules/lib/toplevel/proto.mdx +++ b/rules/lib/toplevel/proto.mdx @@ -2,19 +2,16 @@ title: 'proto' --- -# proto -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/packages/Proto.java" %} -{% include "\_buttons.html" %} A module for protocol message processing. ## Members -- [encode_text](#encode_text) +* [encode\_text](#encode_text) -## encode_text +## encode\_text -``` rule-signature +``` string proto.encode_text(x) ``` @@ -32,7 +29,7 @@ Entries are emitted in iteration (insertion) order. The dict's keys must be strings or ints, and its values must not be sequences or dicts. Examples: -``` python +``` proto.encode_text(struct(field=123)) # field: 123 @@ -48,51 +45,38 @@ proto.encode_text(struct(field='text', ignored_field=None)) # field: "text" proto.encode_text(struct(field=struct(inner_field='text', ignored_field=None))) -# field { +# field \{ # inner_field: "text" -# } +# \} proto.encode_text(struct(field=[struct(inner_field=1), struct(inner_field=2)])) -# field { +# field \{ # inner_field: 1 -# } -# field { +# \} +# field \{ # inner_field: 2 -# } +# \} proto.encode_text(struct(field=struct(inner_field=struct(inner_inner_field='text')))) -# field { -# inner_field { +# field \{ +# inner_field \{ # inner_inner_field: "text" -# } -# } +# \} +# \} -proto.encode_text(struct(foo={4: 3, 2: 1})) -# foo: { +proto.encode_text(struct(foo=\{4: 3, 2: 1\})) +# foo: \{ # key: 4 # value: 3 -# } -# foo: { +# \} +# foo: \{ # key: 2 # value: 1 -# } +# \} ``` ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="encode_text.x"><code>x</code></td> -<td>structure; or NativeInfo; -required<br /> -</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `x` | structure; or NativeInfo; required | \ No newline at end of file diff --git a/rules/lib/toplevel/testing.mdx b/rules/lib/toplevel/testing.mdx index a753964..df36391 100644 --- a/rules/lib/toplevel/testing.mdx +++ b/rules/lib/toplevel/testing.mdx @@ -2,22 +2,19 @@ title: 'testing' --- -# testing -{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java" %} -{% include "\_buttons.html" %} Helper methods for Starlark to access testing infrastructure. ## Members -- [analysis_test](#analysis_test) -- [ExecutionInfo](#ExecutionInfo) -- [TestEnvironment](#TestEnvironment) +* [analysis\_test](#analysis_test) +* [ExecutionInfo](#ExecutionInfo) +* [TestEnvironment](#TestEnvironment) -## analysis_test +## analysis\_test -``` rule-signature -None testing.analysis_test(name, implementation, attrs={}, fragments=[], toolchains=[], attr_values={}) +``` +None testing.analysis_test(name, implementation, attrs=\{\}, fragments=[], toolchains=[], attr_values=\{\}) ``` Creates a new analysis test target. @@ -26,64 +23,26 @@ The number of transitive dependencies of the test are limited. The limit is cont ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="analysis_test.name"><code>name</code></td> -<td><a href="../core/string.html" class="anchor">string</a>; -required<br /> -Name of the target. It should be a Starlark identifier, matching pattern '[A-Za-z_][A-Za-z0-9_]*'.</td> -</tr> -<tr> -<td id="analysis_test.implementation"><code>implementation</code></td> -<td><a href="../core/function.html" class="anchor">function</a>; -required<br /> -The Starlark function implementing this analysis test. It must have exactly one parameter: <a href="../builtins/ctx.html">ctx</a>. The function is called during the analysis phase. It can access the attributes declared by <code>attrs</code> and populated via <code>attr_values</code>. The implementation function may not register actions. Instead, it must register a pass/fail result via providing <a href="../providers/AnalysisTestResultInfo.html">AnalysisTestResultInfo</a>.</td> -</tr> -<tr> -<td id="analysis_test.attrs"><code>attrs</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -default is <code>{}</code><br /> -Dictionary declaring the attributes. See the <a href="../globals/bzl.html#rule">rule</a> call. Attributes are allowed to use configuration transitions defined using <a href="../globals/bzl.html#analysis_test_transition">analysis_test_transition</a>.</td> -</tr> -<tr> -<td id="analysis_test.fragments"><code>fragments</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -List of configuration fragments that are available to the implementation of the analysis test.</td> -</tr> -<tr> -<td id="analysis_test.toolchains"><code>toolchains</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a>; -default is <code>[]</code><br /> -The set of toolchains the test requires. See the <a href="../globals/bzl.html#rule">rule</a> call.</td> -</tr> -<tr> -<td id="analysis_test.attr_values"><code>attr_values</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>{}</code><br /> -Dictionary of attribute values to pass to the implementation.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `name` | [string](../core/string.mdx); required Name of the target. It should be a Starlark identifier, matching pattern '[A-Za-z\_][A-Za-z0-9\_]\*'. | +| `implementation` | [function](../core/function.mdx); required The Starlark function implementing this analysis test. It must have exactly one parameter: [ctx](../builtins/ctx.mdx). The function is called during the analysis phase. It can access the attributes declared by `attrs` and populated via `attr_values`. The implementation function may not register actions. Instead, it must register a pass/fail result via providing [AnalysisTestResultInfo](../providers/AnalysisTestResultInfo.mdx). | +| `attrs` | [dict](../core/dict.mdx); default is `\{\}` Dictionary declaring the attributes. See the [rule](../globals/bzl.html#rule) call. Attributes are allowed to use configuration transitions defined using [analysis\_test\_transition](../globals/bzl.html#analysis_test_transition). | +| `fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of configuration fragments that are available to the implementation of the analysis test. | +| `toolchains` | [sequence](../core/list.mdx); default is `[]` The set of toolchains the test requires. See the [rule](../globals/bzl.html#rule) call. | +| `attr_values` | [dict](../core/dict.mdx) of [string](../core/string.mdx)s; default is `\{\}` Dictionary of attribute values to pass to the implementation. | ## ExecutionInfo -``` rule-signature +``` ExecutionInfo testing.ExecutionInfo ``` -[testing.ExecutionInfo](../providers/ExecutionInfo.html) provider key/constructor +[testing.ExecutionInfo](../providers/ExecutionInfo.mdx) provider key/constructor ## TestEnvironment -``` rule-signature +``` RunEnvironmentInfo testing.TestEnvironment(environment, inherited_environment=[]) ``` @@ -91,25 +50,7 @@ RunEnvironmentInfo testing.TestEnvironment(environment, inherited_environment=[] ### Parameters -<table class="table table-bordered table-condensed table-params"> -<thead> -<tr> -<th>Parameter</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td id="TestEnvironment.environment"><code>environment</code></td> -<td><a href="../core/dict.html" class="anchor">dict</a>; -required<br /> -A map of string keys and values that represent environment variables and their values. These will be made available during the test execution.</td> -</tr> -<tr> -<td id="TestEnvironment.inherited_environment"><code>inherited_environment</code></td> -<td><a href="../core/list.html" class="anchor">sequence</a> of <a href="../core/string.html" class="anchor">string</a>s; -default is <code>[]</code><br /> -A sequence of names of environment variables. These variables are made available during the test execution with their current value taken from the shell environment. If a variable is contained in both <code>environment</code> and <code>inherited_environment</code>, the value inherited from the shell environment will take precedence if set.</td> -</tr> -</tbody> -</table> +| Parameter | Description | +| --- | --- | +| `environment` | [dict](../core/dict.mdx); required A map of string keys and values that represent environment variables and their values. These will be made available during the test execution. | +| `inherited_environment` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A sequence of names of environment variables. These variables are made available during the test execution with their current value taken from the shell environment. If a variable is contained in both `environment` and `inherited_environment`, the value inherited from the shell environment will take precedence if set. | \ No newline at end of file From aa9e000a50b6661eb069d9f1263b418b5cea750f Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sun, 12 Oct 2025 16:53:23 -0700 Subject: [PATCH 07/14] golang converter from html to md --- html2md_converter/main.go | 174 ++++++++++++++++++++++++++++++++++++++ local_test.sh | 86 +++++++++++++++++++ 2 files changed, 260 insertions(+) create mode 100644 html2md_converter/main.go create mode 100755 local_test.sh diff --git a/html2md_converter/main.go b/html2md_converter/main.go new file mode 100644 index 0000000..7245367 --- /dev/null +++ b/html2md_converter/main.go @@ -0,0 +1,174 @@ +package main + +import ( + "archive/zip" + "flag" + "fmt" + "io" + "os" + "path/filepath" + "strings" + + md "github.com/JohannesKaufmann/html-to-markdown" +) + +func main() { + zipPath := flag.String("zip", "", "Path to the zip file containing HTML files") + outputDir := flag.String("output", "output", "Output directory for markdown files") + flag.Parse() + + if *zipPath == "" { + fmt.Println("Error: -zip flag is required") + flag.Usage() + os.Exit(1) + } + + if err := convertZipToMarkdown(*zipPath, *outputDir); err != nil { + fmt.Printf("Error: %v\n", err) + os.Exit(1) + } + + fmt.Println("Conversion completed successfully!") +} + +func convertZipToMarkdown(zipPath, outputDir string) error { + // Open the zip file + r, err := zip.OpenReader(zipPath) + if err != nil { + return fmt.Errorf("failed to open zip file: %w", err) + } + defer r.Close() + + // Create markdown converter + converter := md.NewConverter("", true, nil) + + // Process each file in the zip + for _, f := range r.File { + if err := processZipFile(f, outputDir, converter); err != nil { + return fmt.Errorf("failed to process %s: %w", f.Name, err) + } + } + + return nil +} + +func processZipFile(f *zip.File, outputDir string, converter *md.Converter) error { + // Skip directories + if f.FileInfo().IsDir() { + return nil + } + + // Handle markdown files - copy them as-is + if isMarkdownFile(f.Name) { + return copyMarkdownFile(f, outputDir) + } + + // Handle YAML/YML files - copy them as-is + if isYAMLFile(f.Name) { + return copyYAMLFile(f, outputDir) + } + + // Only process HTML files + if !isHTMLFile(f.Name) { + fmt.Printf("Skipping file: %s\n", f.Name) + return nil + } + + fmt.Printf("Processing: %s\n", f.Name) + + // Open the file from zip + rc, err := f.Open() + if err != nil { + return fmt.Errorf("failed to open file in zip: %w", err) + } + defer rc.Close() + + // Read HTML content + htmlBytes, err := io.ReadAll(rc) + if err != nil { + return fmt.Errorf("failed to read HTML content: %w", err) + } + + // Convert HTML to Markdown + markdown, err := converter.ConvertString(string(htmlBytes)) + if err != nil { + return fmt.Errorf("failed to convert HTML to markdown: %w", err) + } + + // Create output path (replace .html with .md) + outputPath := filepath.Join(outputDir, changeExtension(f.Name, ".md")) + + // Create directory structure + if err := os.MkdirAll(filepath.Dir(outputPath), 0755); err != nil { + return fmt.Errorf("failed to create output directory: %w", err) + } + + // Write markdown file + if err := os.WriteFile(outputPath, []byte(markdown), 0644); err != nil { + return fmt.Errorf("failed to write markdown file: %w", err) + } + + fmt.Printf(" -> Created: %s\n", outputPath) + return nil +} + +func isHTMLFile(filename string) bool { + ext := strings.ToLower(filepath.Ext(filename)) + return ext == ".html" || ext == ".htm" +} + +func isMarkdownFile(filename string) bool { + ext := strings.ToLower(filepath.Ext(filename)) + return ext == ".md" || ext == ".markdown" +} + +func isYAMLFile(filename string) bool { + ext := strings.ToLower(filepath.Ext(filename)) + return ext == ".yaml" || ext == ".yml" +} + +func copyMarkdownFile(f *zip.File, outputDir string) error { + fmt.Printf("Copying markdown file: %s\n", f.Name) + return copyFile(f, outputDir, f.Name) +} + +func copyYAMLFile(f *zip.File, outputDir string) error { + fmt.Printf("Copying YAML file: %s\n", f.Name) + return copyFile(f, outputDir, f.Name) +} + +func copyFile(f *zip.File, outputDir string, outputPath string) error { + // Open the file from zip + rc, err := f.Open() + if err != nil { + return fmt.Errorf("failed to open file in zip: %w", err) + } + defer rc.Close() + + // Read content + content, err := io.ReadAll(rc) + if err != nil { + return fmt.Errorf("failed to read content: %w", err) + } + + // Create output path + fullOutputPath := filepath.Join(outputDir, outputPath) + + // Create directory structure + if err := os.MkdirAll(filepath.Dir(fullOutputPath), 0755); err != nil { + return fmt.Errorf("failed to create output directory: %w", err) + } + + // Write file + if err := os.WriteFile(fullOutputPath, content, 0644); err != nil { + return fmt.Errorf("failed to write file: %w", err) + } + + fmt.Printf(" -> Created: %s\n", fullOutputPath) + return nil +} + +func changeExtension(filename, newExt string) string { + ext := filepath.Ext(filename) + return filename[:len(filename)-len(ext)] + newExt +} \ No newline at end of file diff --git a/local_test.sh b/local_test.sh new file mode 100755 index 0000000..3c90892 --- /dev/null +++ b/local_test.sh @@ -0,0 +1,86 @@ +#!/bin/bash + +# Local test script for HTML to Markdown converter +# This runs the converter in a Go Docker container + +set -e # Exit on error + +# Colors for output +GREEN='\033[0;32m' +BLUE='\033[0;34m' +RED='\033[0;31m' +NC='\033[0m' # No Color + +echo -e "${BLUE}=== Testing HTML to Markdown Converter with Docker ===${NC}\n" + +# Check if Docker is running +if ! docker info > /dev/null 2>&1; then + echo -e "${RED}Error: Docker is not running. Please start Docker and try again.${NC}" + exit 1 +fi + +# Check if zip file exists +ZIP_FILE="${1:-reference-docs.zip}" +if [ ! -f "$ZIP_FILE" ]; then + echo -e "${RED}Error: Zip file '$ZIP_FILE' not found${NC}" + echo "Usage: $0 [path-to-zip-file]" + echo "Example: $0 upstream/bazel-bin/src/main/java/com/google/devtools/build/lib/reference-docs.zip" + exit 1 +fi + +# Get absolute path to zip file +ZIP_FILE_ABS=$(cd "$(dirname "$ZIP_FILE")" && pwd)/$(basename "$ZIP_FILE") + +echo -e "${GREEN}✓${NC} Found zip file: $ZIP_FILE_ABS" + +# Create output directory +OUTPUT_DIR="reference-docs-temp" +rm -rf "$OUTPUT_DIR" +mkdir -p "$OUTPUT_DIR" + +echo -e "${GREEN}✓${NC} Created output directory: $OUTPUT_DIR" + +# Run converter in Docker container +echo -e "\n${BLUE}Running converter in Go Docker container...${NC}\n" + +docker run --rm \ + -v "$(pwd)/html2md_converter:/app" \ + -v "$ZIP_FILE_ABS:/input/reference-docs.zip:ro" \ + -v "$(pwd)/$OUTPUT_DIR:/output" \ + -w /app \ + golang:1.21 \ + bash -c " + echo '==> Initializing Go module...' + go mod init html-to-md-converter + go get github.com/JohannesKaufmann/html-to-markdown + + echo '==> Building converter...' + go build -o html-to-md main.go + + echo '==> Running conversion...' + ./html-to-md -zip /input/reference-docs.zip -output /output + + echo '==> Done!' + " + +echo -e "\n${GREEN}✓${NC} Conversion complete!" + +# Show results +echo -e "\n${BLUE}=== Results ===${NC}" +echo "Output directory: $OUTPUT_DIR" +echo "" +echo "Directory structure:" +tree -L 3 "$OUTPUT_DIR" 2>/dev/null || find "$OUTPUT_DIR" -type f | head -20 + +echo -e "\n${BLUE}=== Sample converted file ===${NC}" +SAMPLE_FILE=$(find "$OUTPUT_DIR" -name "*.md" -type f | head -1) +if [ -n "$SAMPLE_FILE" ]; then + echo "File: $SAMPLE_FILE" + echo "---" + head -30 "$SAMPLE_FILE" + echo "..." +else + echo "No markdown files found" +fi + +echo -e "\n${GREEN}✓${NC} Test complete! Check $OUTPUT_DIR for results" \ No newline at end of file From e92c52e0c8b09a08a8c282d55c9ff8cbecb445e1 Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sun, 12 Oct 2025 16:55:00 -0700 Subject: [PATCH 08/14] remove reference files --- reference/be/be-nav.mdx | 34 - reference/be/c-cpp.mdx | 907 -- reference/be/common-definitions.mdx | 212 - reference/be/extra-actions.mdx | 107 - reference/be/functions.mdx | 533 - reference/be/general.mdx | 579 - reference/be/java.mdx | 530 - reference/be/make-variables.mdx | 332 - reference/be/objective-c.mdx | 75 - reference/be/overview.mdx | 54 - reference/be/platforms-and-toolchains.mdx | 357 - reference/be/protocol-buffer.mdx | 279 - reference/be/python.mdx | 169 - reference/be/shell.mdx | 129 - reference/command-line-reference.mdx | 12159 -------------------- reference/glossary.mdx | 715 -- reference/skyframe.mdx | 198 - 17 files changed, 17369 deletions(-) delete mode 100644 reference/be/be-nav.mdx delete mode 100644 reference/be/c-cpp.mdx delete mode 100644 reference/be/common-definitions.mdx delete mode 100644 reference/be/extra-actions.mdx delete mode 100644 reference/be/functions.mdx delete mode 100644 reference/be/general.mdx delete mode 100644 reference/be/java.mdx delete mode 100644 reference/be/make-variables.mdx delete mode 100644 reference/be/objective-c.mdx delete mode 100644 reference/be/overview.mdx delete mode 100644 reference/be/platforms-and-toolchains.mdx delete mode 100644 reference/be/protocol-buffer.mdx delete mode 100644 reference/be/python.mdx delete mode 100644 reference/be/shell.mdx delete mode 100644 reference/command-line-reference.mdx delete mode 100644 reference/glossary.mdx delete mode 100644 reference/skyframe.mdx diff --git a/reference/be/be-nav.mdx b/reference/be/be-nav.mdx deleted file mode 100644 index 4a59290..0000000 --- a/reference/be/be-nav.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: 'be-nav' ---- - -\*\*Build Encyclopedia\*\* - -* [Overview](./reference/be/overview.mdx) -* [Concepts](#be-menu) - + [Common Definitions](./reference/be/common-definitions.mdx) - + ["Make" variables](./reference/be/make-variables.mdx) -* [Rules](#be-rules) - + [Functions](./reference/be/functions.mdx) - + [C / C++](./reference/be/c-cpp.mdx) - + [Java](./reference/be/java.mdx) - + [Objective-C](./reference/be/objective-c.mdx) - + [Protocol Buffer](./reference/be/protocol-buffer.mdx) - + [Python](./reference/be/python.mdx) - + [Shell](./reference/be/shell.mdx) - + [Extra Actions](./reference/be/extra-actions.mdx) - + [General](./reference/be/general.mdx) - + [Platforms and Toolchains](./reference/be/platforms-and-toolchains.mdx) - + [AppEngine](https://github.com/bazelbuild/rules_appengine) - + [Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)](https://github.com/bazelbuild/rules_apple) - + [C#](https://github.com/bazelbuild/rules_dotnet) - + [D](https://github.com/bazelbuild/rules_d) - + [Docker](https://github.com/bazelbuild/rules_docker) - + [Groovy](https://github.com/bazelbuild/rules_groovy) - + [Go](https://github.com/bazelbuild/rules_go) - + [JavaScript (Closure)](https://github.com/bazelbuild/rules_closure) - + [Jsonnet](https://github.com/bazelbuild/rules_jsonnet) - + [Packaging](./reference/be/pkg.mdx) - + [Rust](https://github.com/bazelbuild/rules_rust) - + [Sass](https://github.com/bazelbuild/rules_sass) - + [Scala](https://github.com/bazelbuild/rules_scala) \ No newline at end of file diff --git a/reference/be/c-cpp.mdx b/reference/be/c-cpp.mdx deleted file mode 100644 index c8e11fd..0000000 --- a/reference/be/c-cpp.mdx +++ /dev/null @@ -1,907 +0,0 @@ ---- -title: 'c-cpp' ---- - - -## Rules - -* [cc\_binary](#cc_binary) -* [cc\_import](#cc_import) -* [cc\_library](#cc_library) -* [cc\_shared\_library](#cc_shared_library) -* [cc\_static\_library](#cc_static_library) -* [cc\_test](#cc_test) -* [cc\_toolchain](#cc_toolchain) -* [fdo\_prefetch\_hints](#fdo_prefetch_hints) -* [fdo\_profile](#fdo_profile) -* [memprof\_profile](#memprof_profile) -* [propeller\_optimize](#propeller_optimize) - -## cc\_binary - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_binary.bzl) - -``` -cc_binary(name, deps, srcs, data, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local_defines, malloc, module_interfaces, nocopts, output_licenses, package_metadata, reexport_deps, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file) -``` - -It produces an executable binary. - - -The `name` of the target should be the same as the name of the -source file that is the main entry point of the application (minus the extension). -For example, if your entry point is in `main.cc`, then your name should -be `main`. - -#### Implicit output targets - -* `name.stripped` (only built if explicitly requested): A stripped - version of the binary. `strip -g` is run on the binary to remove debug - symbols. Additional strip options can be provided on the command line using - `--stripopt=-foo`. -* `name.dwp` (only built if explicitly requested): If - [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug - information package file suitable for debugging remotely deployed binaries. Else: an - empty file. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets. It is also allowed to put linker scripts (.lds) into deps, and reference them in [linkopts](#cc_binary.linkopts). | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | -| `additional_linker_inputs` | List of [labels](./concepts/labels); default is `[]` Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target. | -| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | -| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](./reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | -| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | -| `defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | -| `distribs` | List of strings; default is `[]` | -| `dynamic_deps` | List of [labels](./concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | -| `hdrs_check` | String; default is `""` Deprecated, no-op. | -| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](./reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | -| `link_extra_lib` | [Label](./concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` Control linking of extra libraries. By default, C++ binaries are linked against `//tools/cpp:link_extra_lib`, which by default depends on the label flag `//tools/cpp:link_extra_libs`. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer `malloc` or `--custom_malloc`). Setting this attribute to `None` disables this behaviour. | -| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables.mdx) substitution, [Bourne shell tokenization](common-definitions.html#sh-tokenization) and [label expansion](common-definitions.html#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | -| `linkshared` | Boolean; default is `False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. The presence of this flag means that linking occurs with the `-shared` flag to `gcc`, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a [cc\_binary](#cc_binary) rule are only loaded manually by other programs, so it should not be considered a substitute for the [cc\_library](#cc_library) rule. For sake of scalability we recommend avoiding this approach altogether and simply letting `java_library` depend on `cc_library` rules instead. If you specify both `linkopts=['-static']` and `linkshared=True`, you get a single completely self-contained unit. If you specify both `linkstatic=True` and `linkshared=True`, you get a single, mostly self-contained unit. | -| `linkstatic` | Boolean; default is `True` For [`cc_binary`](./reference/be/c-cpp.html#cc_binary) and [`cc_test`](./reference/be/c-cpp.html#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](./reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](./reference/be/c-cpp.html#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | -| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. | -| `malloc` | [Label](./concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` Override the default dependency on malloc. By default, C++ binaries are linked against `//tools/cpp:malloc`, which is an empty library so the binary ends up using libc malloc. This label must refer to a `cc_library`. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if `linkshared=True` is specified. | -| `module_interfaces` | List of [labels](./concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | -| `nocopts` | String; default is `""` Remove matching options from the C++ compilation command. Subject to ["Make" variable](./reference/be/make-variables) substitution. The value of this attribute is interpreted as a regular expression. Any preexisting `COPTS` that match this regular expression (including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) will be removed from `COPTS` for purposes of compiling this rule. This attribute should not be needed or used outside of `third_party`. The values are not preprocessed in any way other than the "Make" variable substitution. | -| `reexport_deps` | List of [labels](./concepts/labels); default is `[]` | -| `stamp` | Integer; default is `-1` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](./docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | -| `win_def_file` | [Label](./concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | - -## cc\_import - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_import.bzl) - -``` -cc_import(name, deps, data, hdrs, alwayslink, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, includes, interface_library, linkopts, objects, package_metadata, pic_objects, pic_static_library, restricted_to, shared_library, static_library, strip_include_prefix, system_provided, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -`cc_import` rules allows users to import precompiled C/C++ libraries. - -The following are the typical use cases: -1. Linking a static library - -``` -cc_import( - name = "mylib", - hdrs = ["mylib.h"], - static_library = "libmylib.a", - # If alwayslink is turned on, - # libmylib.a will be forcely linked into any binary that depends on it. - # alwayslink = 1, -) -``` - -2. Linking a shared library (Unix) - -``` -cc_import( - name = "mylib", - hdrs = ["mylib.h"], - shared_library = "libmylib.so", -) -``` - -3. Linking a shared library with interface library - -On Unix: - -``` -cc_import( - name = "mylib", - hdrs = ["mylib.h"], - # libmylib.ifso is an interface library for libmylib.so which will be passed to linker - interface_library = "libmylib.ifso", - # libmylib.so will be available for runtime - shared_library = "libmylib.so", -) -``` - -On Windows: - -``` -cc_import( - name = "mylib", - hdrs = ["mylib.h"], - # mylib.lib is an import library for mylib.dll which will be passed to linker - interface_library = "mylib.lib", - # mylib.dll will be available for runtime - shared_library = "mylib.dll", -) -``` - -4. Linking a shared library with `system_provided=True` - -On Unix: - -``` -cc_import( - name = "mylib", - hdrs = ["mylib.h"], - interface_library = "libmylib.ifso", # Or we can also use libmylib.so as its own interface library - # libmylib.so is provided by system environment, for example it can be found in LD_LIBRARY_PATH. - # This indicates that Bazel is not responsible for making libmylib.so available. - system_provided = 1, -) -``` - -On Windows: - -``` -cc_import( - name = "mylib", - hdrs = ["mylib.h"], - # mylib.lib is an import library for mylib.dll which will be passed to linker - interface_library = "mylib.lib", - # mylib.dll is provided by system environment, for example it can be found in PATH. - # This indicates that Bazel is not responsible for making mylib.dll available. - system_provided = 1, -) -``` - -5. Linking to static or shared library - -On Unix: - -``` -cc_import( - name = "mylib", - hdrs = ["mylib.h"], - static_library = "libmylib.a", - shared_library = "libmylib.so", -) -``` - -On Windows: - -``` -cc_import( - name = "mylib", - hdrs = ["mylib.h"], - static_library = "libmylib.lib", # A normal static library - interface_library = "mylib.lib", # An import library for mylib.dll - shared_library = "mylib.dll", -) -``` - -The remaining is the same on Unix and Windows: - -``` -# first will link to libmylib.a (or libmylib.lib) -cc_binary( - name = "first", - srcs = ["first.cc"], - deps = [":mylib"], - linkstatic = 1, # default value -) - -# second will link to libmylib.so (or libmylib.lib) -cc_binary( - name = "second", - srcs = ["second.cc"], - deps = [":mylib"], - linkstatic = 0, -) -``` - -`cc_import` supports an include attribute. For example: - -``` -cc_import( - name = "curl_lib", - hdrs = glob(["vendor/curl/include/curl/*.h"]), - includes = ["vendor/curl/include"], - shared_library = "vendor/curl/lib/.libs/libcurl.dylib", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries that the target depends upon. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). | -| `hdrs` | List of [labels](./concepts/labels); default is `[]` The list of header files published by this precompiled library to be directly included by sources in dependent rules. | -| `alwayslink` | Boolean; default is `False` If 1, any binary that depends (directly or indirectly) on this C++ precompiled library will link in all the object files archived in the static library, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. If alwayslink doesn't work with VS 2017 on Windows, that is due to a [known issue](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version. | -| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](./reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The default `include` path doesn't include generated files. If you need to `#include` a generated header file, list it in the `srcs`. | -| `interface_library` | [Label](./concepts/labels); default is `None` A single interface library for linking the shared library. Permitted file types: `.ifso`, `.tbd`, `.lib`, `.so` or `.dylib` | -| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables.mdx) substitution, [Bourne shell tokenization](common-definitions.html#sh-tokenization) and [label expansion](common-definitions.html#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | -| `objects` | List of [labels](./concepts/labels); default is `[]` | -| `pic_objects` | List of [labels](./concepts/labels); default is `[]` | -| `pic_static_library` | [Label](./concepts/labels); default is `None` | -| `shared_library` | [Label](./concepts/labels); default is `None` A single precompiled shared library. Bazel ensures it is available to the binary that depends on it during runtime. Permitted file types: `.so`, `.dll` or `.dylib` | -| `static_library` | [Label](./concepts/labels); default is `None` A single precompiled static library. Permitted file types: `.a`, `.pic.a` or `.lib` | -| `strip_include_prefix` | String; default is `""` The prefix to strip from the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `include_prefix` attribute is added after this prefix is stripped. This attribute is only legal under `third_party`. | -| `system_provided` | Boolean; default is `False` If 1, it indicates the shared library required at runtime is provided by the system. In this case, `interface_library` should be specified and `shared_library` should be empty. | - -## cc\_library - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_library.bzl) - -``` -cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, module_interfaces, package_metadata, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file) -``` - -Use `cc_library()` for C++-compiled libraries. -The result is either a `.so`, `.lo`, -or `.a`, depending on what is needed. - -If you build something with static linking that depends on -a `cc_library`, the output of a depended-on library rule -is the `.a` file. If you specify -`alwayslink=True`, you get the `.lo` file. - -The actual output file name is `libfoo.so` for -the shared library, where *foo* is the name of the rule. The -other kinds of libraries end with `.lo` and `.a`, -respectively. If you need a specific shared library name, for -example, to define a Python module, use a genrule to copy the library -to the desired name. - -#### Header inclusion checking - -All header files that are used in the build must be declared in -the `hdrs` or `srcs` of `cc_*` rules. -This is enforced. - -For `cc_library` rules, headers in `hdrs` comprise the -public interface of the library and can be directly included both -from the files in `hdrs` and `srcs` of the library -itself as well as from files in `hdrs` and `srcs` -of `cc_*` rules that list the library in their `deps`. -Headers in `srcs` must only be directly included from the files -in `hdrs` and `srcs` of the library itself. When -deciding whether to put a header into `hdrs` or `srcs`, -you should ask whether you want consumers of this library to be able to -directly include it. This is roughly the same decision as -between `public` and `private` visibility in programming languages. - -`cc_binary` and `cc_test` rules do not have an exported -interface, so they also do not have a `hdrs` attribute. All headers -that belong to the binary or test directly should be listed in -the `srcs`. - -To illustrate these rules, look at the following example. - -``` -cc_binary( - name = "foo", - srcs = [ - "foo.cc", - "foo.h", - ], - deps = [":bar"], -) - -cc_library( - name = "bar", - srcs = [ - "bar.cc", - "bar-impl.h", - ], - hdrs = ["bar.h"], - deps = [":baz"], -) - -cc_library( - name = "baz", - srcs = [ - "baz.cc", - "baz-impl.h", - ], - hdrs = ["baz.h"], -) -``` - -The allowed direct inclusions in this example are listed in the table below. -For example `foo.cc` is allowed to directly -include `foo.h` and `bar.h`, but not `baz.h`. - -| Including file | Allowed inclusions | -| --- | --- | -| foo.h | bar.h | -| foo.cc | foo.h bar.h | -| bar.h | bar-impl.h baz.h | -| bar-impl.h | bar.h baz.h | -| bar.cc | bar.h bar-impl.h baz.h | -| baz.h | baz-impl.h | -| baz-impl.h | baz.h | -| baz.cc | baz.h baz-impl.h | - -The inclusion checking rules only apply to *direct* -inclusions. In the example above `foo.cc` is allowed to -include `bar.h`, which may include `baz.h`, which in -turn is allowed to include `baz-impl.h`. Technically, the -compilation of a `.cc` file may transitively include any header -file in the `hdrs` or `srcs` in -any `cc_library` in the transitive `deps` closure. In -this case the compiler may read `baz.h` and `baz-impl.h` -when compiling `foo.cc`, but `foo.cc` must not -contain `#include "baz.h"`. For that to be -allowed, `baz` must be added to the `deps` -of `foo`. - -Bazel depends on toolchain support to enforce the inclusion checking rules. -The `layering_check` feature has to be supported by the toolchain -and requested explicitly, for example via the -`--features=layering_check` command-line flag or the -`features` parameter of the -[`package`](./reference/be/functions.html#package) function. The toolchains -provided by Bazel only support this feature with clang on Unix and macOS. - -#### Examples - -We use the `alwayslink` flag to force the linker to link in -this code although the main binary code doesn't reference it. - -``` -cc_library( - name = "ast_inspector_lib", - srcs = ["ast_inspector_lib.cc"], - hdrs = ["ast_inspector_lib.h"], - visibility = ["//visibility:public"], - deps = ["//third_party/llvm/llvm/tools/clang:frontend"], - # alwayslink as we want to be able to call things in this library at - # debug time, even if they aren't used anywhere in the code. - alwayslink = 1, -) -``` - -The following example comes from -`third_party/python2_4_3/BUILD`. -Some of the code uses the `dl` library (to load -another, dynamic library), so this -rule specifies the `-ldl` link option to link the -`dl` library. - -``` -cc_library( - name = "python2_4_3", - linkopts = [ - "-ldl", - "-lutil", - ], - deps = ["//third_party/expat"], -) -``` - -The following example comes from `third_party/kde/BUILD`. -We keep pre-built `.so` files in the depot. -The header files live in a subdirectory named `include`. - -``` -cc_library( - name = "kde", - srcs = [ - "lib/libDCOP.so", - "lib/libkdesu.so", - "lib/libkhtml.so", - "lib/libkparts.so", - ...more .so files..., - ], - includes = ["include"], - deps = ["//third_party/X11"], -) -``` - -The following example comes from `third_party/gles/BUILD`. -Third-party code often needs some `defines` and -`linkopts`. - -``` -cc_library( - name = "gles", - srcs = [ - "GLES/egl.h", - "GLES/gl.h", - "ddx.c", - "egl.c", - ], - defines = [ - "USE_FLOAT", - "__GL_FLOAT", - "__GL_COMMON", - ], - linkopts = ["-ldl"], # uses dlopen(), dl library - deps = [ - "es", - "//third_party/X11", - ], -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries that the library target depends upon. These can be `cc_library` or `objc_library` targets. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). These should be names of C++ library rules. When you build a binary that links this rule's library, you will also link the libraries in `deps`. Despite the "deps" name, not all of this library's clients belong here. Run-time data dependencies belong in `data`. Source files generated by other rules belong in `srcs`. To link in a pre-compiled third-party library, add its name to the `srcs` instead. To depend on something without linking it to this library, add its name to the `data` instead. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | -| `hdrs` | List of [labels](./concepts/labels); default is `[]` The list of header files published by this library to be directly included by sources in dependent rules. This is the strongly preferred location for declaring header files that describe the interface for the library. These headers will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the `srcs` attribute instead, even if they are included by a published header. See ["Header inclusion checking"](#hdrs) for a more detailed description. Permitted `headers` file types: `.h`, `.hh`, `.hpp`, `.hxx`. | -| `additional_compiler_inputs` | List of [labels](./concepts/labels); default is `[]` Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function. | -| `additional_linker_inputs` | List of [labels](./concepts/labels); default is `[]` Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target. | -| `alwayslink` | Boolean; default is `False` If 1, any binary that depends (directly or indirectly) on this C++ library will link in all the object files for the files listed in `srcs`, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. If alwayslink doesn't work with VS 2017 on Windows, that is due to a [known issue](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version. | -| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | -| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](./reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | -| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | -| `defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | -| `hdrs_check` | String; default is `""` Deprecated, no-op. | -| `implementation_deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries that the library target depends on. Unlike with `deps`, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with `implementation_deps` are still linked in binary targets that depend on this library. | -| `include_prefix` | String; default is `""` The prefix to add to the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the `strip_include_prefix` attribute is removed before this prefix is added. This attribute is only legal under `third_party`. | -| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](./reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | -| `linkopts` | List of strings; default is `[]` See [`cc_binary.linkopts`](./reference/be/c-cpp.html#cc_binary.linkopts). The `linkopts` attribute is also applied to any target that depends, directly or indirectly, on this library via `deps` attributes (or via other attributes that are treated similarly: the [`malloc`](./reference/be/c-cpp.html#cc_binary.malloc) attribute of [`cc_binary`](./reference/be/c-cpp.html#cc_binary)). Dependency linkopts take precedence over dependent linkopts (i.e. dependency linkopts appear later in the command line). Linkopts specified in [`--linkopt`](../user-manual.html#flag--linkopt) take precedence over rule linkopts. | - -Note that the `linkopts` attribute only applies -when creating `.so` files or executables, not -when creating `.a` or `.lo` files. -So if the `linkstatic=True` attribute is set, the -`linkopts` attribute has no effect on the creation of -this library, only on other targets which depend on this library. - -Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" -options are not supported and should never be specified in this attribute. - -The `.so` files produced by `cc_library` -rules are not linked against the libraries that they depend -on. If you're trying to create a shared library for use -outside of the main repository, e.g. for manual use -with `dlopen()` or `LD_PRELOAD`, -it may be better to use a `cc_binary` rule -with the `linkshared=True` attribute. -See [`cc_binary.linkshared`](./reference/be/c-cpp.html#cc_binary.linkshared). - -| `linkstamp` | [Label](./concepts/labels); default is `None` Simultaneously compiles and links the specified C++ source file into the final binary. This trickery is required to introduce timestamp information into binaries; if we compiled the source file to an object file in the usual way, the timestamp would be incorrect. A linkstamp compilation may not include any particular set of compiler flags and so should not depend on any particular header, compiler option, or other build variable. *This option should only be needed in the `base` package.* | -| `linkstatic` | Boolean; default is `False` For [`cc_binary`](./reference/be/c-cpp.html#cc_binary) and [`cc_test`](./reference/be/c-cpp.html#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](./reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](./reference/be/c-cpp.html#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | -| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. | -| `module_interfaces` | List of [labels](./concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | -| `strip_include_prefix` | String; default is `""` The prefix to strip from the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `include_prefix` attribute is added after this prefix is stripped. This attribute is only legal under `third_party`. | -| `textual_hdrs` | List of [labels](./concepts/labels); default is `[]` The list of header files published by this library to be textually included by sources in dependent rules. This is the location for declaring header files that cannot be compiled on their own; that is, they always need to be textually included by other source files to build valid code. | -| `win_def_file` | [Label](./concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | - - -## cc\_shared\_library - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_shared_library.bzl) - -``` -cc_shared_library(name, deps, additional_linker_inputs, aspect_hints, compatible_with, deprecation, dynamic_deps, exec_compatible_with, exec_group_compatible_with, exec_properties, experimental_disable_topo_sort_do_not_use_remove_before_7_0, exports_filter, features, package_metadata, restricted_to, roots, shared_lib_name, static_deps, tags, target_compatible_with, testonly, toolchains, user_link_flags, visibility, win_def_file) -``` - -It produces a shared library. - -#### Example - -``` -cc_shared_library( - name = "foo_shared", - deps = [ - ":foo", - ], - dynamic_deps = [ - ":bar_shared", - ], - additional_linker_inputs = [ - ":foo.lds", - ], - user_link_flags = [ - "-Wl,--version-script=$(location :foo.lds)", - ], -) -cc_library( - name = "foo", - srcs = ["foo.cc"], - hdrs = ["foo.h"], - deps = [ - ":bar", - ":baz", - ], -) -cc_shared_library( - name = "bar_shared", - shared_lib_name = "bar.so", - deps = [":bar"], -) -cc_library( - name = "bar", - srcs = ["bar.cc"], - hdrs = ["bar.h"], -) -cc_library( - name = "baz", - srcs = ["baz.cc"], - hdrs = ["baz.h"], -) -``` - -In the example `foo_shared` statically links `foo` -and `baz`, the latter being a transitive dependency. It doesn't -link `bar` because it is already provided dynamically by the -`dynamic_dep` `bar_shared`. - -`foo_shared` uses a linker script \*.lds file to control which -symbols should be exported. The `cc_shared_library` rule logic does -not control which symbols get exported, it only uses what is assumed to be -exported to give errors during analysis phase if two shared libraries export the -same targets. - -Every direct dependency of `cc_shared_library` is assumed to be -exported. Therefore, Bazel assumes during analysis that `foo` is being -exported by `foo_shared`. `baz` is not assumed to be exported -by `foo_shared`. Every target matched by the `exports_filter` -is also assumed to be exported. - -Every single `cc_library` in the example should appear at most in one -`cc_shared_library`. If we wanted to link `baz` also into -`bar_shared` we would need to add -`tags = ["LINKABLE_MORE_THAN_ONCE"]` to `baz`. - -Due to the `shared_lib_name` attribute, the file produced by -`bar_shared` will have the name `bar.so` as opposed -to the name `libbar.so` that it would have by default on Linux. - -#### Errors - -##### `Two shared libraries in dependencies export the same symbols.` - -This will happen whenever you are creating a target with two different -`cc_shared_library` dependencies that export the same target. To fix this -you need to stop the libraries from being exported in one of the -`cc_shared_library` dependencies. - -##### `Two shared libraries in dependencies link the same library statically` - -This will happen whenever you are creating a new `cc_shared_library` with two -different `cc_shared_library` dependencies that link the same target statically. -Similar to the error with exports. - -One way to fix this is to stop linking the library into one of the -`cc_shared_library` dependencies. At the same time, the one that still links it -needs to export the library so that the one not linking it keeps visibility to -the symbols. Another way is to pull out a third library that exports the target. -A third way is to tag the culprit `cc_library` with `LINKABLE_MORE_THAN_ONCE` -but this fix should be rare and you should absolutely make sure that the -`cc_library` is indeed safe to link more than once. - -##### `` '//foo:foo' is already linked statically in '//bar:bar' but not exported` `` - -This means that a library in the transitive closure of your `deps` is reachable -without going through one of the `cc_shared_library` dependencies but is already -linked into a different `cc_shared_library` in `dynamic_deps` and is not -exported. - -The solution is to export it from the `cc_shared_library` dependency or pull out -a third `cc_shared_library` that exports it. - -##### `Do not place libraries which only contain a precompiled dynamic library in deps.` - -If you have a precompiled dynamic library, this doesn't need to and cannot be -linked statically into the current `cc_shared_library` target that you are -currently creating. Therefore, it doesn't belong in `deps` of the -`cc_shared_library`. If this precompiled dynamic library is a dependency of one -of your `cc_libraries`, then the `cc_library` needs to depend on it -directly. - -##### `Trying to export a library already exported by a different shared library` - -You will see this error if on the current rule you are claiming to export a -target that is already being exported by one of your dynamic dependencies. - -To fix this, remove the target from `deps` and just rely on it from the dynamic -dependency or make sure that the `exports_filter` doesn't catch this target. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` Top level libraries that will unconditionally be statically linked into the shared library after being whole-archived. Any transitive library dependency of these direct deps will be linked into this shared library as long as they have not already been linked by a `cc_shared_library` in `dynamic_deps`. During analysis, the rule implementation will consider any target listed in `deps` as being exported by the shared library in order to give errors when multiple `cc_shared_libraries` export the same targets. The rule implementation does not take care of informing the linker about which symbols should be exported by the shared object. The user should take care of this via linker scripts or visibility declarations in the source code. The implementation will also trigger errors whenever the same library is linked statically into more than one `cc_shared_library`. This can be avoided by adding `"LINKABLE_MORE_THAN_ONCE"` to the `cc_library.tags` or by listing the `cc\_library` as an export of one of the shared libraries so that one can be made a `dynamic_dep` of the other. | -| `additional_linker_inputs` | List of [labels](./concepts/labels); default is `[]` Any additional files that you may want to pass to the linker, for example, linker scripts. You have to separately pass any linker flags that the linker needs in order to be aware of this file. You can do so via the `user_link_flags` attribute. | -| `dynamic_deps` | List of [labels](./concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | -| `experimental_disable_topo_sort_do_not_use_remove_before_7_0` | Boolean; default is `False` | -| `exports_filter` | List of strings; default is `[]` This attribute contains a list of targets that are claimed to be exported by the current shared library. Any target `deps` is already understood to be exported by the shared library. This attribute should be used to list any targets that are exported by the shared library but are transitive dependencies of `deps`. Note that this attribute is not actually adding a dependency edge to those targets, the dependency edge should instead be created by `deps`.The entries in this attribute are just strings. Keep in mind that when placing a target in this attribute, this is considered a claim that the shared library exports the symbols from that target. The `cc_shared_library` logic doesn't actually handle telling the linker which symbols should be exported. The following syntax is allowed: `//foo:__pkg__` to account for any target in foo/BUILD `//foo:__subpackages__` to account for any target in foo/BUILD or any other package below foo/ like foo/bar/BUILD | -| `roots` | List of [labels](./concepts/labels); default is `[]` | -| `shared_lib_name` | String; default is `""` By default cc\_shared\_library will use a name for the shared library output file based on the target's name and the platform. This includes an extension and sometimes a prefix. Sometimes you may not want the default name, for example, when loading C++ shared libraries for Python the default lib\* prefix is often not desired, in which case you can use this attribute to choose a custom name. | -| `static_deps` | List of strings; default is `[]` | -| `user_link_flags` | List of strings; default is `[]` Any additional flags that you may want to pass to the linker. For example, to make the linker aware of a linker script passed via additional\_linker\_inputs you can use the following: ``` cc_shared_library( name = "foo_shared", additional_linker_inputs = select(\{ "//src/conditions:linux": [ ":foo.lds", ":additional_script.txt", ], "//conditions:default": []\}), user_link_flags = select(\{ "//src/conditions:linux": [ "-Wl,-rpath,kittens", "-Wl,--version-script=$(location :foo.lds)", "-Wl,--script=$(location :additional_script.txt)", ], "//conditions:default": []\}), ... ) ``` | -| `win_def_file` | [Label](./concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | - -## cc\_static\_library - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_static_library.bzl) - -``` -cc_static_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Produces a static library from a list of targets and their transitive dependencies. - -The resulting static library contains the object files of the targets listed in -`deps` as well as their transitive dependencies, with preference given to -`PIC` objects. - -#### Output groups - -##### `linkdeps` - -A text file containing the labels of those transitive dependencies of targets listed in -`deps` that did not contribute any object files to the static library, but do -provide at least one static, dynamic or interface library. The resulting static library -may require these libraries to be available at link time. - -##### `linkopts` - -A text file containing the user-provided `linkopts` of all transitive -dependencies of targets listed in `deps`. - -#### Duplicate symbols - -By default, the `cc_static_library` rule checks that the resulting static -library does not contain any duplicate symbols. If it does, the build fails with an error -message that lists the duplicate symbols and the object files containing them. - -This check can be disabled per target or per package by setting -`features = ["-symbol_check"]` or globally via -`--features=-symbol_check`. - -##### Toolchain support for `symbol_check` - -The auto-configured C++ toolchains shipped with Bazel support the -`symbol_check` feature on all platforms. Custom toolchains can add support for -it in one of two ways: - -* Implementing the `ACTION_NAMES.validate_static_library` action and - enabling it with the `symbol_check` feature. The tool set in the action is - invoked with two arguments, the static library to check for duplicate symbols and the - path of a file that must be created if the check passes. -* Having the `symbol_check` feature add archiver flags that cause the - action creating the static library to fail on duplicate symbols. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of targets to combine into a static library, including all their transitive dependencies. Dependencies that do not provide any object files are not included in the static library, but their labels are collected in the file provided by the `linkdeps` output group. | - -## cc\_test - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_test.bzl) - -``` -cc_test(name, deps, srcs, data, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local, local_defines, malloc, module_interfaces, nocopts, package_metadata, reexport_deps, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file) -``` - -A `cc_test()` rule compiles a test. Here, a test -is a binary wrapper around some testing code. - -*By default, C++ tests are dynamically linked.* -To statically link a unit test, specify -[`linkstatic=True`](./reference/be/c-cpp.html#cc_binary.linkstatic). -It would probably be good to comment why your test needs -`linkstatic`; this is probably not obvious. - -#### Implicit output targets - -* `name.stripped` (only built if explicitly requested): A stripped - version of the binary. `strip -g` is run on the binary to remove debug - symbols. Additional strip options can be provided on the command line using - `--stripopt=-foo`. -* `name.dwp` (only built if explicitly requested): If - [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug - information package file suitable for debugging remotely deployed binaries. Else: an - empty file. - -See the [cc\_binary()](./reference/be/c-cpp.html#cc_binary_args) arguments, except that -the `stamp` argument is set to 0 by default for tests and -that `cc_test` has extra [attributes common to all test rules (\*\_test)](./reference/be/common-definitions#common-attributes-tests). - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets. It is also allowed to put linker scripts (.lds) into deps, and reference them in [linkopts](#cc_binary.linkopts). | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | -| `additional_linker_inputs` | List of [labels](./concepts/labels); default is `[]` Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target. | -| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | -| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](./reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | -| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | -| `defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | -| `distribs` | List of strings; default is `[]` | -| `dynamic_deps` | List of [labels](./concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | -| `hdrs_check` | String; default is `""` Deprecated, no-op. | -| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](./reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | -| `link_extra_lib` | [Label](./concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` Control linking of extra libraries. By default, C++ binaries are linked against `//tools/cpp:link_extra_lib`, which by default depends on the label flag `//tools/cpp:link_extra_libs`. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer `malloc` or `--custom_malloc`). Setting this attribute to `None` disables this behaviour. | -| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables.mdx) substitution, [Bourne shell tokenization](common-definitions.html#sh-tokenization) and [label expansion](common-definitions.html#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | -| `linkshared` | Boolean; default is `False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. The presence of this flag means that linking occurs with the `-shared` flag to `gcc`, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a [cc\_binary](#cc_binary) rule are only loaded manually by other programs, so it should not be considered a substitute for the [cc\_library](#cc_library) rule. For sake of scalability we recommend avoiding this approach altogether and simply letting `java_library` depend on `cc_library` rules instead. If you specify both `linkopts=['-static']` and `linkshared=True`, you get a single completely self-contained unit. If you specify both `linkstatic=True` and `linkshared=True`, you get a single, mostly self-contained unit. | -| `linkstatic` | Boolean; default is `False` For [`cc_binary`](./reference/be/c-cpp.html#cc_binary) and [`cc_test`](./reference/be/c-cpp.html#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](./reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](./reference/be/c-cpp.html#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | -| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. | -| `malloc` | [Label](./concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` Override the default dependency on malloc. By default, C++ binaries are linked against `//tools/cpp:malloc`, which is an empty library so the binary ends up using libc malloc. This label must refer to a `cc_library`. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if `linkshared=True` is specified. | -| `module_interfaces` | List of [labels](./concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | -| `nocopts` | String; default is `""` Remove matching options from the C++ compilation command. Subject to ["Make" variable](./reference/be/make-variables) substitution. The value of this attribute is interpreted as a regular expression. Any preexisting `COPTS` that match this regular expression (including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) will be removed from `COPTS` for purposes of compiling this rule. This attribute should not be needed or used outside of `third_party`. The values are not preprocessed in any way other than the "Make" variable substitution. | -| `reexport_deps` | List of [labels](./concepts/labels); default is `[]` | -| `stamp` | Integer; default is `0` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](./docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | -| `win_def_file` | [Label](./concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | - -## cc\_toolchain - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_toolchain.bzl) - -``` -cc_toolchain(name, all_files, ar_files, as_files, aspect_hints, compatible_with, compiler_files, compiler_files_without_includes, coverage_files, deprecation, dwp_files, dynamic_runtime_lib, exec_compatible_with, exec_group_compatible_with, exec_properties, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, output_licenses, package_metadata, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, toolchains, visibility) -``` - -Represents a C++ toolchain. - -This rule is responsible for: - -* Collecting all artifacts needed for C++ actions to run. This is done by - attributes such as `all_files`, `compiler_files`, - `linker_files`, or other attributes ending with `_files`). These are - most commonly filegroups globbing all required files. -* Generating correct command lines for C++ actions. This is done using - `CcToolchainConfigInfo` provider (details below). - -Use `toolchain_config` attribute to configure the C++ toolchain. -See also this -[page](https://bazel.build/docs/cc-toolchain-config-reference) for elaborate C++ toolchain configuration and toolchain selection documentation. - -Use `tags = ["manual"]` in order to prevent toolchains from being built and configured -unnecessarily when invoking `bazel build //...` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `all_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts. These artifacts will be added as inputs to all rules\_cc related actions (with the exception of actions that are using more precise sets of artifacts from attributes below). Bazel assumes that `all_files` is a superset of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile and link files, so it takes `all_files`). This is what `cc_toolchain.files` contains, and this is used by all Starlark rules using C++ toolchain. | -| `ar_files` | [Label](./concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for archiving actions. | -| `as_files` | [Label](./concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for assembly actions. | -| `compiler_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for compile actions. | -| `compiler_files_without_includes` | [Label](./concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for compile actions in case when input discovery is supported (currently Google-only). | -| `coverage_files` | [Label](./concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for coverage actions. If not specified, all\_files are used. | -| `dwp_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for dwp actions. | -| `dynamic_runtime_lib` | [Label](./concepts/labels); default is `None` Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking dependencies dynamically. | -| `exec_transition_for_inputs` | Boolean; default is `False` Deprecated. No-op. | -| `libc_top` | [Label](./concepts/labels); default is `None` A collection of artifacts for libc passed as inputs to compile/linking actions. | -| `linker_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for linking actions. | -| `module_map` | [Label](./concepts/labels); default is `None` Module map artifact to be used for modular builds. | -| `objcopy_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for objcopy actions. | -| `output_licenses` | List of strings; default is `[]` | -| `static_runtime_lib` | [Label](./concepts/labels); default is `None` Static library artifact for the C++ runtime library (e.g. libstdc++.a). This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking dependencies statically. | -| `strip_files` | [Label](./concepts/labels); required Collection of all cc\_toolchain artifacts required for strip actions. | -| `supports_header_parsing` | Boolean; default is `False` Set to True when cc\_toolchain supports header parsing actions. | -| `supports_param_files` | Boolean; default is `True` Set to True when cc\_toolchain supports using param files for linking actions. | -| `toolchain_config` | [Label](./concepts/labels); required The label of the rule providing `cc_toolchain_config_info`. | -| `toolchain_identifier` | String; default is `""` The identifier used to match this cc\_toolchain with the corresponding crosstool\_config.toolchain. Until issue [#5380](https://github.com/bazelbuild/bazel/issues/5380) is fixed this is the recommended way of associating `cc_toolchain` with `CROSSTOOL.toolchain`. It will be replaced by the `toolchain_config` attribute ([#5380](https://github.com/bazelbuild/bazel/issues/5380)). | - -## fdo\_prefetch\_hints - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_prefetch_hints.bzl) - -``` -fdo_prefetch_hints(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Represents an FDO prefetch hints profile that is either in the workspace. -Examples: - -``` -fdo_prefetch_hints( - name = "hints", - profile = "//path/to/hints:profile.afdo", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `profile` | [Label](./concepts/labels); required Label of the hints profile. The hints file has the .afdo extension The label can also point to an fdo\_absolute\_path\_profile rule. | - -## fdo\_profile - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_profile.bzl) - -``` -fdo_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, memprof_profile, package_metadata, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Represents an FDO profile that is in the workspace. -Example: - -``` -fdo_profile( - name = "fdo", - profile = "//path/to/fdo:profile.zip", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `memprof_profile` | [Label](./concepts/labels); default is `None` Label of the MemProf profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file. | -| `profile` | [Label](./concepts/labels); required Label of the FDO profile or a rule which generates it. The FDO file can have one of the following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for XBinary profile. The label can also point to an fdo\_absolute\_path\_profile rule. | -| `proto_profile` | [Label](./concepts/labels); default is `None` Label of the protobuf profile. | - -## memprof\_profile - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/memprof_profile.bzl) - -``` -memprof_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Represents a MEMPROF profile that is in the workspace. -Example: - -``` -memprof_profile( - name = "memprof", - profile = "//path/to/memprof:profile.afdo", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `profile` | [Label](./concepts/labels); required Label of the MEMPROF profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file. The label can also point to an fdo\_absolute\_path\_profile rule. | - -## propeller\_optimize - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/propeller_optimize.bzl) - -``` -propeller_optimize(name, aspect_hints, cc_profile, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, ld_profile, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Represents a Propeller optimization profile in the workspace. -Example: - -``` -propeller_optimize( - name = "layout", - cc_profile = "//path:cc_profile.txt", - ld_profile = "//path:ld_profile.txt" -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `cc_profile` | [Label](./concepts/labels); required Label of the profile passed to the various compile actions. This file has the .txt extension. | -| `ld_profile` | [Label](./concepts/labels); required Label of the profile passed to the link action. This file has the .txt extension. | \ No newline at end of file diff --git a/reference/be/common-definitions.mdx b/reference/be/common-definitions.mdx deleted file mode 100644 index a035d0a..0000000 --- a/reference/be/common-definitions.mdx +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: 'common-definitions' ---- - - -This section defines various terms and concepts that are common to -many functions or build rules. - -## Contents - -* [Bourne shell tokenization](#sh-tokenization) -* [Label Expansion](#label-expansion) -* [Typical attributes defined by most build rules](#typical-attributes) -* [Attributes common to all build rules](#common-attributes) -* [Attributes common to all test rules (\*\_test)](#common-attributes-tests) -* [Attributes common to all binary rules (\*\_binary)](#common-attributes-binaries) -* [Configurable attributes](#configurable-attributes) -* [Implicit output targets](#implicit-outputs) - -## Bourne shell tokenization - -Certain string attributes of some rules are split into multiple -words according to the tokenization rules of the Bourne shell: -unquoted spaces delimit separate words, and single- and -double-quotes characters and backslashes are used to prevent -tokenization. - -Those attributes that are subject to this tokenization are -explicitly indicated as such in their definitions in this document. - -Attributes subject to "Make" variable expansion and Bourne shell -tokenization are typically used for passing arbitrary options to -compilers and other tools. Examples of such attributes are -`cc_library.copts` and `java_library.javacopts`. -Together these substitutions allow a -single string variable to expand into a configuration-specific list -of option words. - -## Label expansion - -Some string attributes of a very few rules are subject to label -expansion: if those strings contain a valid label as a -substring, such as `//mypkg:target`, and that label is a -declared prerequisite of the current rule, it is expanded into the -pathname of the file represented by the -[target](https://bazel.build/reference/glossary#target) -`//mypkg:target`. - -Example attributes include `genrule.cmd` and -`cc_binary.linkopts`. The details may vary significantly in -each case, over such issues as: whether relative labels are -expanded; how labels that expand to multiple files are -treated, etc. Consult the rule attribute documentation for -specifics. - -## Typical attributes defined by most build rules - -This section describes attributes that are defined by many build rules, -but not all. - -| Attribute | Description | -| --- | --- | -| `data` | List of [labels](./concepts/labels); default is `[]` Files needed by this rule at runtime. May list file or rule targets. Generally allows any target. The default outputs and runfiles of targets in the `data` attribute should appear in the `*.runfiles` area of any executable which is output by or has a runtime dependency on this target. This may include data files or binaries used when this target's [`srcs`](#typical.srcs) are executed. See the [data dependencies](./concepts/dependencies#data-dependencies) section for more information about how to depend on and use data files. New rules should define a `data` attribute if they process inputs which might use other inputs at runtime. Rules' implementation functions must also [populate the target's runfiles](https://bazel.build/rules/rules#runfiles) from the outputs and runfiles of any `data` attribute, as well as runfiles from any dependency attribute which provides either source code or runtime dependencies. | -| `deps` | List of [labels](./concepts/labels); default is `[]` Dependencies for this target. Generally should only list rule targets. (Though some rules permit files to be listed directly in `deps`, this should be avoided when possible.) Language-specific rules generally limit the listed targets to those with specific [providers](https://bazel.build/extending/rules#providers). The precise semantics of what it means for a target to depend on another using `deps` are specific to the kind of rule, and the rule-specific documentation goes into more detail. For rules which process source code, `deps` generally specifies code dependencies used by the code in [`srcs`](#typical.srcs). Most often, a `deps` dependency is used to allow one module to use symbols defined in another module written in the same programming language and separately compiled. Cross-language dependencies are also permitted in many cases: For example, a `java_library` target may depend on C++ code in a `cc_library` target, by listing the latter in the `deps` attribute. See the definition of [dependencies](./concepts/build-ref#deps) for more information. | -| `licenses` | List of strings; [nonconfigurable](#configurable-attributes); default is `["none"]` A list of license-type strings to be used for this particular target. This is part of a deprecated licensing API that Bazel no longer uses. Don't use this. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` Files processed or included by this rule. Generally lists files directly, but may list rule targets (like `filegroup` or `genrule`) to include their default outputs. Language-specific rules often require that the listed files have particular file extensions. | - -## Attributes common to all build rules - -This section describes attributes that are implicitly added to all build -rules. - -| Attribute | Description | -| --- | --- | -| `aspect_hints` | List of [labels](./concepts/labels); default is `[]` A list of arbitrary labels which is exposed to [aspects](./extending/aspects) (in particular - aspects invoked by this rule's reverse dependencies), but isn't exposed to this rule's own implementation. Consult documentation for language-specific rule sets for details about what effect a particular aspect hint would have. You could think of an aspect hint as a richer alternative to a [tag](#common.tags): while a tag conveys only a boolean state (the tag is either present or absent in the `tags` list), an aspect hint can convey arbitrary structured information in its [providers](./extending/rules#providers). In practice, aspect hints are used for interoperability between different language-specific rule sets. For example, imagine you have a `mylang_binary` target which needs to depend on an `otherlang_library` target. The MyLang-specific logic needs some additional information about the OtherLang target in order to use it, but `otherlang_library` doesn't provide this information because it knows nothing about MyLang. One solution might be for the MyLang rule set to define a `mylang_hint` rule which can be used to encode that additional information; the user can add the hint to their `otherlang_library`'s `aspect_hints`, and `mylang_binary` can use an aspect to collect the additional information from a MyLang-specific provider in the `mylang_hint`. For a concrete example, see [`swift_interop_hint`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_interop_hint) and [`swift_overlay`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_overlay) in `rules_swift`. Best practices: * Targets listed in `aspect_hints` should be lightweight and minimal. * Language-specific logic should consider only aspect hints having providers relevant to that language, and should ignore any other aspect hints. | -| `compatible_with` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The list of environments this target can be built for, in addition to default-supported environments. This is part of Bazel's constraint system, which lets users declare which targets can and cannot depend on each other. For example, externally deployable binaries shouldn't depend on libraries with company-secret code. See [ConstraintSemantics](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46) for details. | -| `deprecation` | String; [nonconfigurable](#configurable-attributes); default is `None` An explanatory warning message associated with this target. Typically this is used to notify users that a target has become obsolete, or has become superseded by another rule, is private to a package, or is perhaps considered harmful for some reason. It is a good idea to include some reference (like a webpage, a bug number or example migration CLs) so that one can easily find out what changes are required to avoid the message. If there is a new target that can be used as a drop in replacement, it is a good idea to just migrate all users of the old target. This attribute has no effect on the way things are built, but it may affect a build tool's diagnostic output. The build tool issues a warning when a rule with a `deprecation` attribute is depended upon by a target in another package. Intra-package dependencies are exempt from this warning, so that, for example, building the tests of a deprecated rule does not encounter a warning. If a deprecated target depends on another deprecated target, no warning message is issued. Once people have stopped using it, the target can be removed. | -| `exec_compatible_with` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` A list of `constraint_values` that must be present in the execution platform of this target's default exec group. This is in addition to any constraints already set by the rule type. Constraints are used to restrict the list of available execution platforms. For more details, see the description of [toolchain resolution](./docs/toolchains#toolchain-resolution). and [exec groups](./extending/exec-groups) | -| `exec_group_compatible_with` | Dictionary of strings to lists of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `\{\}` A dictionary of exec group names to lists of `constraint_values` that must be present in the execution platform for the given exec group. This is in addition to any constraints already set on the exec group's definition. Constraints are used to restrict the list of available execution platforms. For more details, see the description of [toolchain resolution](./docs/toolchains#toolchain-resolution). and [exec groups](./extending/exec-groups) | -| `exec_properties` | Dictionary of strings; default is `\{\}` A dictionary of strings that will be added to the `exec_properties` of a platform selected for this target. See `exec_properties` of the [platform](platforms-and-toolchains.html#platform) rule. If a key is present in both the platform and target-level properties, the value will be taken from the target. Keys can be prefixed with the name of an execution group followed by a `.` to apply them only to that particular exec group. | -| `features` | List of *feature* strings; default is `[]` A feature is string tag that can be enabled or disabled on a target. The meaning of a feature depends on the rule itself. This `features` attribute is combined with the [package](./reference/be/functions.html#package) level `features` attribute. For example, if the features ["a", "b"] are enabled on the package level, and a target's `features` attribute contains ["-a", "c"], the features enabled for the rule will be "b" and "c". [See example](https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD). | -| `package_metadata` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is the package's `default_package_metadata` A list of labels that are associated metadata about this target. Typically, the labels are simple rules that return a provider of constant values. Rules and aspects may use these labels to perform some additional analysis on the build graph. The canonical use case is that of [rules\_license](https://github.com/bazelbuild/rules_license). For that use case, `package_metadata` and `default_package_metadata` is used to attach information about a package's licence or version to targets. An aspect applied to a top-level binary can be used to gather those and produce compliance reports. | -| `restricted_to` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The list of environments this target can be built for, *instead* of default-supported environments. This is part of Bazel's constraint system. See `compatible_with` for details. | -| `tags` | List of strings; [nonconfigurable](#configurable-attributes); default is `[]` *Tags* can be used on any rule. *Tags* on test and `test_suite` rules are useful for categorizing the tests. *Tags* on non-test targets are used to control sandboxed execution of `genrule`s and [Starlark](./rules/concepts) actions, and for parsing by humans and/or external tools. Bazel modifies the behavior of its sandboxing code if it finds the following keywords in the `tags` attribute of any test or `genrule` target, or the keys of `execution_requirements` for any Starlark action. * `no-sandbox` keyword results in the action or test never being sandboxed; it can still be cached or run remotely - use `no-cache` or `no-remote` to prevent either or both of those. * `no-cache` keyword results in the action or test never being cached (locally or remotely). Note: for the purposes of this tag, the disk cache is considered a local cache, whereas the HTTP and gRPC caches are considered remote. Other caches, such as Skyframe or the persistent action cache, are not affected. * `no-remote-cache` keyword results in the action or test never being cached remotely (but it may be cached locally; it may also be executed remotely). Note: for the purposes of this tag, the disk cache is considered a local cache, whereas the HTTP and gRPC caches are considered remote. Other caches, such as Skyframe or the persistent action cache, are not affected. If a combination of local disk cache and remote cache are used (combined cache), it's treated as a remote cache and disabled entirely unless `--incompatible_remote_results_ignore_disk` is set in which case the local components will be used. * `no-remote-exec` keyword results in the action or test never being executed remotely (but it may be cached remotely). * `no-remote` keyword prevents the action or test from being executed remotely or cached remotely. This is equivalent to using both `no-remote-cache` and `no-remote-exec`. * `no-remote-cache-upload` keyword disables upload part of remote caching of a spawn. it does not disable remote execution. * `local` keyword precludes the action or test from being remotely cached, remotely executed, or run inside the sandbox. For genrules and tests, marking the rule with the `local = True` attribute has the same effect. * `requires-network` keyword allows access to the external network from inside the sandbox. This tag only has an effect if sandboxing is enabled. * `block-network` keyword blocks access to the external network from inside the sandbox. In this case, only communication with localhost is allowed. This tag only has an effect if sandboxing is enabled. * `requires-fakeroot` runs the test or action as uid and gid 0 (i.e., the root user). This is only supported on Linux. This tag takes precedence over the `--sandbox_fake_username` command-line option. *Tags* on tests are generally used to annotate a test's role in your debug and release process. Typically, tags are most useful for C++ and Python tests, which lack any runtime annotation ability. The use of tags and size elements gives flexibility in assembling suites of tests based around codebase check-in policy. Bazel modifies test running behavior if it finds the following keywords in the `tags` attribute of the test rule: * `exclusive` will force the test to be run in the "exclusive" mode, ensuring that no other tests are running at the same time. Such tests will be executed in serial fashion after all build activity and non-exclusive tests have been completed. Remote execution is disabled for such tests because Bazel doesn't have control over what's running on a remote machine. * `exclusive-if-local` will force the test to be run in the "exclusive" mode if it is executed locally, but will run the test in parallel if it's executed remotely. * `manual` keyword will exclude the target from expansion of target pattern wildcards (`...`, `:*`, `:all`, etc.) and `test_suite` rules which do not list the test explicitly when computing the set of top-level targets to build/run for the `build`, `test`, and `coverage` commands. It does not affect target wildcard or test suite expansion in other contexts, including the `query` command. Note that `manual` does not imply that a target should not be built/run automatically by continuous build/test systems. For example, it may be desirable to exclude a target from `bazel test ...` because it requires specific Bazel flags, but still have it included in properly-configured presubmit or continuous test runs. * `external` keyword will force test to be unconditionally executed (regardless of `--cache_test_results` value). See [Tag Conventions](./reference/test-encyclopedia#tag-conventions) in the Test Encyclopedia for more conventions on tags attached to test targets. | -| `target_compatible_with` | List of [labels](./concepts/labels); default is `[]` A list of `constraint_value`s that must be present in the target platform for this target to be considered *compatible*. This is in addition to any constraints already set by the rule type. If the target platform does not satisfy all listed constraints then the target is considered *incompatible*. Incompatible targets are skipped for building and testing when the target pattern is expanded (e.g. `//...`, `:all`). When explicitly specified on the command line, incompatible targets cause Bazel to print an error and cause a build or test failure. Targets that transitively depend on incompatible targets are themselves considered incompatible. They are also skipped for building and testing. An empty list (which is the default) signifies that the target is compatible with all platforms. All rules other than [Workspace Rules](workspace.mdx) support this attribute. For some rules this attribute has no effect. For example, specifying `target_compatible_with` for a `cc_toolchain` is not useful. See the [Platforms](./docs/platforms#skipping-incompatible-targets) page for more information about incompatible target skipping. | -| `testonly` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` except for test and test suite targets If `True`, only testonly targets (such as tests) can depend on this target. Equivalently, a rule that is not `testonly` is not allowed to depend on any rule that is `testonly`. Tests (`*_test` rules) and test suites ([test\_suite](./reference/be/general.html#test_suite) rules) are `testonly` by default. This attribute is intended to mean that the target should not be contained in binaries that are released to production. Because testonly is enforced at build time, not run time, and propagates virally through the dependency tree, it should be applied judiciously. For example, stubs and fakes that are useful for unit tests may also be useful for integration tests involving the same binaries that will be released to production, and therefore should probably not be marked testonly. Conversely, rules that are dangerous to even link in, perhaps because they unconditionally override normal behavior, should definitely be marked testonly. | -| `toolchains` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The set of targets whose [Make variables](./reference/be/make-variables) this target is allowed to access. These targets are either instances of rules that provide `TemplateVariableInfo` or special targets for toolchain types built into Bazel. These include: * `@bazel_tools//tools/cpp:toolchain_type`* `@rules_java//toolchains:current_java_runtime` Note that this is distinct from the concept of [toolchain resolution](./docs/toolchains#toolchain-resolution) that is used by rule implementations for platform-dependent configuration. You cannot use this attribute to determine which specific `cc_toolchain` or `java_toolchain` a target will use. | -| `visibility` | List of [labels](./concepts/labels); [nonconfigurable](#configurable-attributes); default varies The `visibility` attribute controls whether the target can be depended on by targets in other locations. See the documentation for [visibility](./concepts/visibility). For targets declared directly in a BUILD file or in legacy macros called from a BUILD file, the default value is the package's `default_visibility` if specified, or else `["//visibility:private"]`. For targets declared in one or more symbolic macros, the default value is always just `["//visibility:private"]` (which makes it useable only within the package containing the macro's code). | - -## Attributes common to all test rules (\*\_test) - -This section describes attributes that are common to all test rules. - -| Attribute | Description | -| --- | --- | -| `args` | List of strings; subject to [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make variable"](./reference/be/make-variables) substitution, and [Bourne shell tokenization](#sh-tokenization); default is `[]` Command line arguments that Bazel passes to the target when it is executed with `bazel test`. These arguments are passed before any `--test_arg` values specified on the `bazel test` command line. | -| `env` | Dictionary of strings; values are subject to [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make variable"](./reference/be/make-variables) substitution; default is `\{\}` Specifies additional environment variables to set when the test is executed by `bazel test`. This attribute only applies to native rules, like `cc_test`, `py_test`, and `sh_test`. It does not apply to Starlark-defined test rules. For your own Starlark rules, you can add an "env" attribute and use it to populate a [RunEnvironmentInfo](./rules/lib/providers/RunEnvironmentInfo.mdx) Provider. [TestEnvironment](./rules/lib/toplevel/testing#TestEnvironment) Provider. | -| `env_inherit` | List of strings; default is `[]` Specifies additional environment variables to inherit from the external environment when the test is executed by `bazel test`. This attribute only applies to native rules, like `cc_test`, `py_test`, and `sh_test`. It does not apply to Starlark-defined test rules. | -| `size` | String `"enormous"`, `"large"`, `"medium"`, or `"small"`; [nonconfigurable](#configurable-attributes); default is `"medium"` Specifies a test target's "heaviness": how much time/resources it needs to run. Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or "enormous". Bazel uses the size to determine a default timeout, which can be overridden using the `timeout` attribute. The timeout is for all tests in the BUILD target, not for each individual test. When the test is run locally, the `size` is additionally used for scheduling purposes: Bazel tries to respect `--local_\{ram,cpu\}_resources` and not overwhelm the local machine by running lots of heavy tests at the same time. Test sizes correspond to the following default timeouts and assumed peak local resource usages: | Size | RAM (in MB) | CPU (in CPU cores) | Default timeout | | --- | --- | --- | --- | | small | 20 | 1 | short (1 minute) | | medium | 100 | 1 | moderate (5 minutes) | | large | 300 | 1 | long (15 minutes) | | enormous | 800 | 1 | eternal (60 minutes) | The environment variable `TEST_SIZE` will be set to the value of this attribute when spawning the test. | -| `timeout` | String `"short"`, `"moderate"`, `"long"`, or `"eternal"`; [nonconfigurable](#configurable-attributes); default is derived from the test's `size` attribute How long the test is expected to run before returning. While a test's size attribute controls resource estimation, a test's timeout may be set independently. If not explicitly specified, the timeout is based on the [test's size](#test.size). The test timeout can be overridden with the `--test_timeout` flag, e.g. for running under certain conditions which are known to be slow. Test timeout values correspond to the following time periods: | Timeout Value | Time Period | | --- | --- | | short | 1 minute | | moderate | 5 minutes | | long | 15 minutes | | eternal | 60 minutes | For times other than the above, the test timeout can be overridden with the `--test_timeout` bazel flag, e.g. for manually running under conditions which are known to be slow. The `--test_timeout` values are in seconds. For example `--test_timeout=120` will set the test timeout to two minutes. The environment variable `TEST_TIMEOUT` will be set to the test timeout (in seconds) when spawning the test. | -| `flaky` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` Marks test as flaky. If set, executes the test up to three times, marking it as failed only if it fails each time. By default, this attribute is set to False and the test is executed only once. Note, that use of this attribute is generally discouraged - tests should pass reliably when their assertions are upheld. | -| `shard_count` | Non-negative integer less than or equal to 50; default is `-1` Specifies the number of parallel shards to use to run the test. If set, this value will override any heuristics used to determine the number of parallel shards with which to run the test. Note that for some test rules, this parameter may be required to enable sharding in the first place. Also see `--test_sharding_strategy`. If test sharding is enabled, the environment variable `TEST_TOTAL_SHARDS` will be set to this value when spawning the test. Sharding requires the test runner to support the test sharding protocol. If it does not, then it will most likely run every test in every shard, which is not what you want. See [Test Sharding](./reference/test-encyclopedia#test-sharding) in the Test Encyclopedia for details on sharding. | -| `local` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` Forces the test to be run locally, without sandboxing. Setting this to True is equivalent to providing "local" as a tag (`tags=["local"]`). | - -## Attributes common to all binary rules (\*\_binary) - -This section describes attributes that are common to all binary rules. - -| Attribute | Description | -| --- | --- | -| `args` | List of strings; subject to [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make variable"](./reference/be/make-variables) substitution, and [Bourne shell tokenization](#sh-tokenization); [nonconfigurable](#configurable-attributes); default is `[]` Command line arguments that Bazel will pass to the target when it is executed either by the `run` command or as a test. These arguments are passed before the ones that are specified on the `bazel run` or `bazel test` command line. *NOTE: The arguments are not passed when you run the target outside of Bazel (for example, by manually executing the binary in `bazel-bin/`).* | -| `env` | Dictionary of strings; values are subject to [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make variable"](./reference/be/make-variables) substitution; default is `\{\}` Specifies additional environment variables to set when the target is executed by `bazel run`. This attribute only applies to native rules, like `cc_binary`, `py_binary`, and `sh_binary`. It does not apply to Starlark-defined executable rules. For your own Starlark rules, you can add an "env" attribute and use it to populate a [RunEnvironmentInfo](./rules/lib/providers/RunEnvironmentInfo.mdx) Provider. *NOTE: The environment variables are not set when you run the target outside of Bazel (for example, by manually executing the binary in `bazel-bin/`).* | -| `output_licenses` | List of strings; default is `[]` The licenses of the output files that this binary generates. This is part of a deprecated licensing API that Bazel no longer uses. Don't use this. | - -## Configurable attributes - -Most attributes are "configurable", meaning that their values may change when -the target is built in different ways. Specifically, configurable attributes -may vary based on the flags passed to the Bazel command line, or what -downstream dependency is requesting the target. This can be used, for -instance, to customize the target for multiple platforms or compilation modes. - -The following example declares different sources for different target -architectures. Running `bazel build :multiplatform_lib --cpu x86` -will build the target using `x86_impl.cc`, while substituting -`--cpu arm` will instead cause it to use `arm_impl.cc`. - -``` -cc_library( - name = "multiplatform_lib", - srcs = select(\{ - ":x86_mode": ["x86_impl.cc"], - ":arm_mode": ["arm_impl.cc"] - \}) -) -config_setting( - name = "x86_mode", - values = \{ "cpu": "x86" \} -) -config_setting( - name = "arm_mode", - values = \{ "cpu": "arm" \} -) -``` - -The [`select()`](./reference/be/functions.html#select) function -chooses among different alternative values for a configurable attribute based -on which [`config_setting`](./reference/be/general.html#config_setting) -or [`constraint_value`](./reference/be/platforms-and-toolchains.html#constraint_value) -criteria the target's configuration satisfies. - -Bazel evaluates configurable attributes after processing macros and before -processing rules (technically, between the -[loading and analysis phases](https://bazel.build/rules/concepts#evaluation-model)). -Any processing before `select()` evaluation doesn't know which -branch the `select()` chooses. Macros, for example, can't change -their behavior based on the chosen branch, and `bazel query` can -only make conservative guesses about a target's configurable dependencies. See -[this FAQ](https://bazel.build/docs/configurable-attributes#faq) -for more on using `select()` with rules and macros. - -Attributes marked `nonconfigurable` in their documentation cannot -use this feature. Usually an attribute is nonconfigurable because Bazel -internally needs to know its value before it can determine how to resolve a -`select()`. - -See [Configurable Build Attributes](https://bazel.build/docs/configurable-attributes) for a detailed overview. - -## Implicit output targets - -*Implicit outputs in C++ are deprecated. Please refrain from using it -in other languages where possible. We don't have a deprecation path yet -but they will eventually be deprecated too.* - -When you define a build rule in a BUILD file, you are explicitly -declaring a new, named rule target in a package. Many build rule -functions also *implicitly* entail one or more output file -targets, whose contents and meaning are rule-specific. -For example, when you explicitly declare a -`java_binary(name='foo', ...)` rule, you are also -*implicitly* declaring an output file -target `foo_deploy.jar` as a member of the same package. -(This particular target is a self-contained Java archive suitable -for deployment.) - -Implicit output targets are first-class members of the global -target graph. Just like other targets, they are built on demand, -either when specified in the top-level built command, or when they -are necessary prerequisites for other build targets. They can be -referenced as dependencies in BUILD files, and can be observed in -the output of analysis tools such as `bazel query`. - -For each kind of build rule, the rule's documentation contains a -special section detailing the names and contents of any implicit -outputs entailed by a declaration of that kind of rule. - -An important but somewhat subtle distinction between the -two namespaces used by the build system: -[labels](./concepts/labels) identify *targets*, -which may be rules or files, and file targets may be divided into -either source (or input) file targets and derived (or output) file -targets. These are the things you can mention in BUILD files, -build from the command-line, or examine using `bazel query`; -this is the *target namespace*. Each file target corresponds -to one actual file on disk (the "file system namespace"); each rule -target may correspond to zero, one or more actual files on disk. -There may be files on disk that have no corresponding target; for -example, `.o` object files produced during C++ compilation -cannot be referenced from within BUILD files or from the command line. -In this way, the build tool may hide certain implementation details of -how it does its job. This is explained more fully in -the [BUILD Concept Reference](./concepts/build-ref). \ No newline at end of file diff --git a/reference/be/extra-actions.mdx b/reference/be/extra-actions.mdx deleted file mode 100644 index 89ea49f..0000000 --- a/reference/be/extra-actions.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: 'extra-actions' ---- - - -## Rules - -* [action\_listener](#action_listener) -* [extra\_action](#extra_action) - -## action\_listener - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java) - -``` -action_listener(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, extra_actions, features, licenses, mnemonics, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) -``` - -**WARNING:** Extra actions are deprecated. Use -[aspects](https://bazel.build/rules/aspects) -instead. - -An `action_listener` rule doesn't produce any output itself. -Instead, it allows tool developers to insert -[`extra_action`](./reference/be/extra-actions.html#extra_action)s into the build system, -by providing a mapping from action to [`extra_action`](./reference/be/extra-actions.html#extra_action). - -This rule's arguments map action mnemonics to -[`extra_action`](./reference/be/extra-actions.html#extra_action) rules. - -By specifying the option [`--experimental_action_listener=<label>`](./docs/user-manual#flag--experimental_action_listener), -the build will use the specified `action_listener` to insert -[`extra_action`](./reference/be/extra-actions.html#extra_action)s into the build graph. - -#### Example - -``` -action_listener( - name = "index_all_languages", - mnemonics = [ - "Javac", - "CppCompile", - "Python", - ], - extra_actions = [":indexer"], -) - -action_listener( - name = "index_java", - mnemonics = ["Javac"], - extra_actions = [":indexer"], -) - -extra_action( - name = "indexer", - tools = ["//my/tools:indexer"], - cmd = "$(location //my/tools:indexer)" + - "--extra_action_file=$(EXTRA_ACTION_FILE)", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `extra_actions` | List of [labels](./concepts/labels); required A list of `extra_action` targets this `action_listener` should add to the build graph. E.g. `[ "//my/tools:analyzer" ]`. | -| `mnemonics` | List of strings; required A list of action mnemonics this `action_listener` should listen for, e.g. `[ "Javac" ]`. Mnemonics are not a public interface. There's no guarantee that the mnemonics and their actions don't change. | - -## extra\_action - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ExtraActionRule.java) - -``` -extra_action(name, data, aspect_hints, cmd, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, out_templates, package_metadata, requires_action_output, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility) -``` - -**WARNING:** Extra actions are deprecated. Use -[aspects](https://bazel.build/rules/aspects) -instead. - -An `extra_action` rule doesn't produce any meaningful output -when specified as a regular build target. Instead, it allows tool developers -to insert additional actions into the build graph that shadow existing actions. - -See [`action_listener`](./reference/be/extra-actions.html#action_listener) for details -on how to enable `extra_action`s. - -The `extra_action`s run as a command-line. The command-line tool gets -access to a file containing a protocol buffer as $(EXTRA\_ACTION\_FILE) -with detailed information on the original action it is shadowing. -It also has access to all the input files the original action has access to. -See extra\_actions\_base.proto -for details on the data stored inside the protocol buffer. Each proto file -contains an ExtraActionInfo message. - -Just like all other actions, extra actions are sandboxed, and should be designed to handle that. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. You may refer to this rule by `label` in the `extra_actions` argument of [`action_listener`](./reference/be/extra-actions.html#action_listener) rules. | -| `cmd` | String; required The command to run. Like [genrule cmd attribute](./reference/be/general.html#genrule.cmd) with the following differences: 1. No heuristic label expansion. Only labels using $(location ...) are expanded. 2. An additional pass is applied to the string to replace all occurrences of the outputs created from the `out_templates` attribute. All occurrences of `$(output out_template)` are replaced with the path to the file denoted by `label`. E.g. out\_template `$(ACTION_ID).analysis` can be matched with `$(output $(ACTION_ID).analysis)`. In effect, this is the same substitution as `$(location)` but with a different scope. | -| `out_templates` | List of strings; default is `[]` A list of templates for files generated by the `extra_action` command. The template can use the following variables: * $(ACTION\_ID), an id uniquely identifying this `extra_action`. Used to generate a unique output file. | -| `requires_action_output` | Boolean; default is `False` Indicates this `extra_action` requires the output of the original action to be present as input to this `extra_action`. When true (default false), the extra\_action can assume that the original action outputs are available as part of its inputs. | -| `tools` | List of [labels](./concepts/labels); default is `[]` A list of `tool` dependencies for this rule. See the definition of [dependencies](./concepts/build-ref#deps) for more information. The build system ensures these prerequisites are built before running the `extra_action` command; they are built using the [`exec`configuration](./docs/user-manual#configurations), since they must run as a tool during the build itself. The path of an individual `tools` target `//x:y` can be obtained using `$(location //x:y)`. All tools and their data dependencies are consolidated into a single tree within which the command can use relative paths. The working directory will be the root of that unified tree. | \ No newline at end of file diff --git a/reference/be/functions.mdx b/reference/be/functions.mdx deleted file mode 100644 index f7162c1..0000000 --- a/reference/be/functions.mdx +++ /dev/null @@ -1,533 +0,0 @@ ---- -title: 'functions' ---- - - -## Contents - -* [package](#package) -* [package\_group](#package_group) -* [exports\_files](#exports_files) -* [glob](#glob) -* [select](#select) -* [subpackages](#subpackages) - -## package - -``` -package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features) -``` - -This function declares metadata that applies to every rule in the -package. It is used at most once within a package (BUILD file). - -For the counterpart that declares metadata applying to every rule in the whole -*repository*, use the `repo()` function in the -[`REPO.bazel` file](./external/overview#repo.bazel) at the root of your repo. -The `repo()` function takes exactly the same arguments as `package()`. - -The package() function should be called right after all the load() statements at the top of the -file, before any rule. - -### Arguments - -| Attribute | Description | -| --- | --- | -| `default_applicable_licenses` | Alias for [`default_package_metadata`](#package.default_package_metadata). | -| `default_visibility` | List of [labels](./concepts/labels); default is `[]` The default visibility of the top-level rule targets and symbolic macros in this package — that is, the targets and symbolic macros that are not themselves declared inside a symbolic macro. This attribute is ignored if the target or macro specifies a `visibility` value. For detailed information about the syntax of this attribute, see the documentation of [visibility](./concepts/visibility). The package default visibility does not apply to [exports\_files](#exports_files), which is public by default. | -| `default_deprecation` | String; default is `""` Sets the default [`deprecation`](common-definitions.html#common.deprecation) message for all rules in this package. | -| `default_package_metadata` | List of [labels](./concepts/labels); default is `[]` Sets a default list of metadata targets which apply to all other targets in the package. These are typically targets related to OSS package and license declarations. See [rules\_license](https://github.com/bazelbuild/rules_license) for examples. | -| `default_testonly` | Boolean; default is `False` except as noted Sets the default [`testonly`](common-definitions.html#common.testonly) property for all rules in this package. In packages under `javatests` the default value is `True`. | -| `features` | List strings; default is `[]` Sets various flags that affect the semantics of this BUILD file. This feature is mainly used by the people working on the build system to tag packages that need some kind of special handling. Do not use this unless explicitly requested by someone working on the build system. | - -### Examples - -The declaration below declares that the rules in this package are -visible only to members of package -group `//foo:target`. Individual visibility declarations -on a rule, if present, override this specification. - -``` -package(default_visibility = ["//foo:target"]) -``` - -## package\_group - -``` -package_group(name, packages, includes) -``` - -This function defines a set of [packages](./concepts/build-ref#packages) -and associates a label with the set. The label can be referenced in -`visibility` attributes. - -Package groups are primarily used for visibility control. A publicly visible -target can be referenced from every package in the source tree. A privately -visible target can only be referenced within its own package (not subpackages). -In between these extremes, a target may allow access to its own package plus any -of the packages described by one or more package groups. For a more detailed -explanation of the visibility system, see the -[visibility](common-definitions.html#common.visibility) -attribute. - -A given package is considered to be in the group if it either matches the -`packages` attribute, or is already contained in one of the other -package groups mentioned in the `includes` attribute. - -Package groups are technically targets, but are not created by rules, and do -not themselves have any visibility protection. - -### Arguments - -| Attribute | Description | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `packages` | List of strings; default is `[]` A list of zero or more package specifications. Each package specification string can have one of the following forms: 1. The full name of a package, without its repository, starting with a double slash. For example, `//foo/bar` specifies the package having that name and which lives in the same repository as the package group.- As above, but with a trailing `/...`. For example, `//foo/...` specifies the set of `//foo` and all its subpackages. `//...` specifies all packages in the current repository.- The strings `public` or `private`, which respectively specify every package or no package. (This form requires the flag `--incompatible_package_group_has_public_syntax` to be set.) In addition, the first two kinds of package specifications may also be prefixed with `-` to indicate that they are negated. The package group contains any package that matches at least one of its positive specifications and none of its negative specifications For instance, the value `[//foo/..., -//foo/tests/...]` includes all subpackages of `//foo` that are not also subpackages of `//foo/tests`. (`//foo` itself is included while //foo/tests itself is not.) Aside from public visibility, there is no way to directly specify packages outside the current repository. If this attribute is missing, it is the same as setting it to an empty list, which is also the same as setting it to a list containing only `private`. *Note:* Prior to Bazel 6.0, the specification `//...` had a legacy behavior of being the same as `public`. This behavior is fixed when `--incompatible_fix_package_group_reporoot_syntax` is enabled, which is the default after Bazel 6.0. *Note:* Prior to Bazel 6.0, when this attribute is serialized as part of `bazel query --output=proto` (or `--output=xml`), the leading slashes are omitted. For instance, `//pkg/foo/...` will output as `\"pkg/foo/...\"`. This behavior is fixed when `--incompatible_package_group_includes_double_slash` is enabled, which is the default after Bazel 6.0. | -| `includes` | List of [labels](./concepts/labels); default is `[]` Other package groups that are included in this one. The labels in this attribute must refer to other package groups. Packages in referenced package groups are taken to be part of this package group. This is transitive — if package group `a` includes package group `b`, and `b` includes package group `c`, then every package in `c` will also be a member of `a`. When used together with negated package specifications, note that the set of packages for each group is first computed independently and the results are then unioned together. This means that negated specifications in one group have no effect on the specifications in another group. | - -### Examples - -The following `package_group` declaration specifies a -package group called "tropical" that contains tropical fruits. - -``` -package_group( - name = "tropical", - packages = [ - "//fruits/mango", - "//fruits/orange", - "//fruits/papaya/...", - ], -) -``` - -The following declarations specify the package groups of a fictional -application: - -``` -package_group( - name = "fooapp", - includes = [ - ":controller", - ":model", - ":view", - ], -) - -package_group( - name = "model", - packages = ["//fooapp/database"], -) - -package_group( - name = "view", - packages = [ - "//fooapp/swingui", - "//fooapp/webui", - ], -) - -package_group( - name = "controller", - packages = ["//fooapp/algorithm"], -) -``` - -## exports\_files - -``` -exports_files([label, ...], visibility, licenses) -``` - -`exports_files()` specifies a list of files belonging to -this package that are exported to other packages. - -The BUILD file for a package may only refer directly to source files belonging -to another package if they are explicitly exported with an -`exports_files()` statement. Read more about -[visibility of files](./concepts/visibility#source-file-target-visibility). - -As a legacy behaviour, also files mentioned as input to a rule are exported -with the default visibility until the flag -[`--incompatible_no_implicit_file_export`](https://github.com/bazelbuild/bazel/issues/10225) -is flipped. However, this behavior should not be relied upon and actively -migrated away from. - -### Arguments - -The argument is a list of names of files within the current package. A -visibility declaration can also be specified; in this case, the files will be -visible to the targets specified. If no visibility is specified, the files -will be visible to every package, even if a package default visibility was -specified in the `package` -function. The [licenses](common-definitions.html#common.licenses) -can also be specified. - -### Example - -The following example exports `golden.txt`, a -text file from the `test_data` package, so that other -packages may use it, for example, in the `data` attribute -of tests. - -``` -# from //test_data/BUILD - -exports_files(["golden.txt"]) -``` - -## glob - -``` -glob(include, exclude=[], exclude_directories=1, allow_empty=True) -``` - -Glob is a helper function that finds all files that match certain path patterns, -and returns a new, mutable, sorted list of their paths. Glob only searches files -in its own package, and looks only for source files (not generated files nor -other targets). - -A source file's Label is included in the result if the file's package-relative -path matches any of the `include` patterns and none of the -`exclude` patterns. - -The `include` and `exclude` lists contain path patterns -that are relative to the current package. Every pattern may consist of one or -more path segments. As usual with Unix paths, these segments are separated by -`/`. The segments in the pattern are matched against the segments of -the path. Segments may contain the `*` wildcard: this matches -any substring in the path segment (even the empty substring), excluding the -directory separator `/`. This wildcard can be used multiple times -within one path segment. Additionally, the `**` wildcard can match -zero or more complete path segments, but it must be declared as a standalone -path segment. - -Examples: - -* `foo/bar.txt` matches exactly the `foo/bar.txt` file - in this package (unless `foo/` is a subpackage) -* `foo/*.txt` matches every file in the `foo/` directory - if the file ends with `.txt` (unless `foo/` is a - subpackage) -* `foo/a*.htm*` matches every file in the `foo/` - directory that starts with `a`, then has an arbitrary string (could - be empty), then has `.htm`, and ends with another arbitrary string - (unless `foo/` is a subpackage); such as `foo/axx.htm` - and `foo/a.html` or `foo/axxx.html` -* `foo/*` matches every file in the `foo/` directory, - (unless `foo/` is a subpackage); it does not match `foo` - directory itself even if `exclude_directories` is set to - 0 -* `foo/**` matches every file in every non-subpackage subdirectory - under package's first level subdirectory `foo/`; if - `exclude_directories` is set to 0, `foo` - directory itself also matches the pattern; in this case, `**` is - considered to match zero path segments -* `**/a.txt` matches `a.txt` files in this package's - directory plus non-subpackage subdirectories. -* `**/bar/**/*.txt` matches every `.txt` file in every - non-subpackage subdirectory of this package, if at least one directory on the - resulting path is called `bar`, such as - `xxx/bar/yyy/zzz/a.txt` or `bar/a.txt` (remember that - `**` also matches zero segments) or `bar/zzz/a.txt` -* `**` matches every file in every non-subpackage subdirectory of - this package -* `foo**/a.txt` is an invalid pattern, because `**` must - stand on its own as a segment -* `foo/` is an invalid pattern, because the second segment defined - after `/` is an empty string - -If the `exclude_directories` argument is enabled (set to 1), files of -type directory will be omitted from the results (default 1). - -If the `allow_empty` argument is set to `False`, the -`glob` function will error-out if the result would otherwise be the -empty list. - -There are several important limitations and caveats: - -1. Since `glob()` runs during BUILD file evaluation, - `glob()` matches files only in your source tree, never - generated files. If you are building a target that requires both - source and generated files, you must append an explicit list of generated - files to the glob. See the [example](#glob_example) - below with `:mylib` and `:gen_java_srcs`. -2. If a rule has the same name as a matched source file, the rule will - "shadow" the file. - - To understand this, remember that `glob()` returns a list of - paths, so using `glob()` in other rules' attribute (e.g. - `srcs = glob(["*.cc"])`) has the same effect as listing the - matched paths explicitly. If for example `glob()` yields - `["Foo.java", "bar/Baz.java"]` but there's also a rule in the - package called "Foo.java" (which is allowed, though Bazel warns about it), - then the consumer of the `glob()` will use the "Foo.java" rule - (its outputs) instead of the "Foo.java" file. See - [GitHub - issue #10395](https://github.com/bazelbuild/bazel/issues/10395#issuecomment-583714657) for more details. -3. Globs may match files in subdirectories. And subdirectory names - may be wildcarded. However... -4. Labels are not allowed to cross the package boundary and glob does - not match files in subpackages. - - For example, the glob expression `**/*.cc` in package - `x` does not include `x/y/z.cc` if - `x/y` exists as a package (either as - `x/y/BUILD`, or somewhere else on the package-path). This - means that the result of the glob expression actually depends on the - existence of BUILD files — that is, the same glob expression would - include `x/y/z.cc` if there was no package called - `x/y` or it was marked as deleted using the - [--deleted\_packages](./docs/user-manual#flag--deleted_packages) - flag. -5. The restriction above applies to all glob expressions, - no matter which wildcards they use. -6. A hidden file with filename starting with `.` is completely matched by - both the `**` and the `*` wildcards. If you want to match a hidden file - with a compound pattern, your pattern needs to begin with a `.`. For example, - `*` and `.*.txt` will match `.foo.txt`, but `*.txt` - will not. - Hidden directories are also matched in the same manner. Hidden directories - may include files that are not required as inputs, and can increase the - number of unnecessarily globbed files and memory consumption. To exclude - hidden directories, add them to the "exclude" list argument. -7. The "\*\*" wildcard has one corner case: the pattern - `"**"` doesn't match the package's directory path. That is to - say, `glob(["**"], exclude_directories = False)` matches all files - and directories transitively strictly under the current package's directory - (but of course not going into directories of subpackages - see the previous - note about that). - -In general, you should **try to provide an appropriate extension (e.g. \*.mdx) -instead of using a bare '\*'** for a glob pattern. The more explicit name -is both self documenting and ensures that you don't accidentally match backup -files, or emacs/vi/... auto-save files. - -When writing build rules you can enumerate the elements of the glob. This -enables generating individual rules for every input, for example. See the -[expanded glob example](#expanded_glob_example) section below. - -### Glob Examples - -Create a Java library built from all java files in this directory, -and all files generated by the `:gen_java_srcs` rule. - -``` -java_library( - name = "mylib", - srcs = glob(["*.java"]) + [":gen_java_srcs"], - deps = "...", -) - -genrule( - name = "gen_java_srcs", - outs = [ - "Foo.java", - "Bar.java", - ], - ... -) -``` - -Include all txt files in directory testdata except experimental.txt. -Note that files in subdirectories of testdata will not be included. If -you want those files to be included, use a recursive glob (\*\*). - -``` -sh_test( - name = "mytest", - srcs = ["mytest.sh"], - data = glob( - ["testdata/*.txt"], - exclude = ["testdata/experimental.txt"], - ), -) -``` - -### Recursive Glob Examples - -Make the test depend on all txt files in the testdata directory and any -of its subdirectories (and their subdirectories, and so on). -Subdirectories containing a BUILD file are ignored. (See limitations -and caveats above.) - -``` -sh_test( - name = "mytest", - srcs = ["mytest.sh"], - data = glob(["testdata/**/*.txt"]), -) -``` - -Create a library built from all java files in this directory and all -subdirectories except those whose path includes a directory named testing. -**This pattern should be avoided if possible, as it can reduce build -incrementality and therefore increase build times.** - -``` -java_library( - name = "mylib", - srcs = glob( - ["**/*.java"], - exclude = ["**/testing/**"], - ), -) -``` - -### Expanded Glob Examples - -Create an individual genrule for \*\_test.cc in the current directory -that counts the number of lines in the file. - -``` -# Conveniently, the build language supports list comprehensions. -[genrule( - name = "count_lines_" + f[:-3], # strip ".cc" - srcs = [f], - outs = ["%s-linecount.txt" % f[:-3]], - cmd = "wc -l $< >$@", - ) for f in glob(["*_test.cc"])] -``` - -If the BUILD file above is in package //foo and the package contains three -matching files, a\_test.cc, b\_test.cc and c\_test.cc then running -`bazel query '//foo:all'` will list all rules that were generated: - -``` -$ bazel query '//foo:all' | sort -//foo:count_lines_a_test -//foo:count_lines_b_test -//foo:count_lines_c_test -``` - -## select - -``` -select( - \{conditionA: valuesA, conditionB: valuesB, ...\}, - no_match_error = "custom message" -) -``` - -`select()` is the helper function that makes a rule attribute -[configurable](common-definitions.html#configurable-attributes). -It can replace the right-hand side of -*almost* -any attribute assignment so its value depends on command-line Bazel flags. -You can use this, for example, to define platform-specific dependencies or to -embed different resources depending on whether a rule is built in "developer" -vs. "release" mode. - -Basic use is as follows: - -``` -sh_binary( - name = "mytarget", - srcs = select(\{ - ":conditionA": ["mytarget_a.sh"], - ":conditionB": ["mytarget_b.sh"], - "//conditions:default": ["mytarget_default.sh"] - \}) -) -``` - -This makes the `srcs` attribute of -a `sh_binary` configurable by replacing its normal label -list assignment with a `select` call that maps -configuration conditions to matching values. Each condition is a label -reference to -a `config_setting` or -`constraint_value`, -which "matches" if the target's configuration matches an expected set of -values. The value of `mytarget#srcs` then becomes whichever -label list matches the current invocation. - -Notes: - -* Exactly one condition is selected on any invocation. -* 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 and constraint - values as A plus some additional flags or constraint values. This also - means that specialization resolution is not designed to create an ordering as - demonstrated in Example 2 below. -* If multiple conditions match and one is not a specialization of all the - others, Bazel fails with an error, unless all conditions resolve to the same value. -* The special pseudo-label `//conditions:default` is - considered to match if no other condition matches. If this condition - is left out, some other rule must match to avoid an error. -* `select` can be embedded *inside* a larger - attribute assignment. So `srcs = ["common.sh"] - + select(\{ ":conditionA": ["myrule_a.sh"], ...\})` and `srcs = select(\{ ":conditionA": ["a.sh"]\}) + select(\{ ":conditionB": - ["b.sh"]\})` are valid expressions. -* `select` works with most, but not all, attributes. Incompatible - attributes are marked `nonconfigurable` in their documentation. - - ## subpackages - - ``` - subpackages(include, exclude=[], allow_empty=True) - ``` - - `subpackages()` is a helper function, similar to `glob()` - that lists subpackages instead of files and directories. It uses the same - path patterns as `glob()` and can match any subpackage that is a - direct descendant of the currently loading BUILD file. See [glob](#glob) for a detailed explanation and examples of include and - exclude patterns. - - The resulting list of subpackages returned is in sorted order and contains - paths relative to the current loading package that match the given patterns in - `include` and not those in `exclude`. - - ### Example - - The following example lists all the direct subpackages for the package `foo/BUILD` - - ``` - # The following BUILD files exist: - # foo/BUILD - # foo/bar/baz/BUILD - # foo/bar/but/bad/BUILD - # foo/sub/BUILD - # foo/sub/deeper/BUILD - # - # In foo/BUILD a call to - subs1 = subpackages(include = ["**"]) - - # results in subs1 == ["sub", "bar/baz", "bar/but/bad"] - # - # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of - # 'foo' - - subs2 = subpackages(include = ["bar/*"]) - # results in subs2 = ["bar/baz"] - # - # Since 'bar' is not a subpackage itself, this looks for any subpackages under - # all first level subdirectories of 'bar'. - - subs3 = subpackages(include = ["bar/**"]) - # results in subs3 = ["bar/baz", "bar/but/bad"] - # - # Since bar is not a subpackage itself, this looks for any subpackages which are - # (1) under all subdirectories of 'bar' which can be at any level, (2) not a - # subpackage of another subpackages. - - subs4 = subpackages(include = ["sub"]) - subs5 = subpackages(include = ["sub/*"]) - subs6 = subpackages(include = ["sub/**"]) - # results in subs4 and subs6 being ["sub"] - # results in subs5 = []. - # - # In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a - # subpackage of 'foo'). - # In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since - # 'foo/sub' is already a subpackage itself, the subdirectories will not be - # traversed anymore. - # In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it - # is returned. But the subdirectories of 'foo/sub' will not be traversed - # anymore. - ``` - - In general it is preferred that instead of calling this function directly - that users use the 'subpackages' module of - [skylib](https://github.com/bazelbuild/bazel-skylib). \ No newline at end of file diff --git a/reference/be/general.mdx b/reference/be/general.mdx deleted file mode 100644 index 608dcff..0000000 --- a/reference/be/general.mdx +++ /dev/null @@ -1,579 +0,0 @@ ---- -title: 'general' ---- - - -## Rules - -* [alias](#alias) -* [config\_setting](#config_setting) -* [filegroup](#filegroup) -* [genquery](#genquery) -* [genrule](#genrule) -* [starlark\_doc\_extract](#starlark_doc_extract) -* [test\_suite](#test_suite) - -## alias - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/Alias.java) - -``` -alias(name, actual, aspect_hints, compatible_with, deprecation, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) -``` - -The `alias` rule creates another name a rule can be referred to as. - -Aliasing only works for "regular" targets. In particular, `package_group` -and `test_suite` cannot be aliased. - -Aliasing may be of help in large repositories where renaming a target would require making -changes to lots of files. You can also use alias rule to store a -[select](./reference/be/functions.html#select) function call if you want to reuse that logic for -multiple targets. - -The alias rule has its own visibility declaration. In all other respects, it behaves -like the rule it references (e.g. testonly *on the alias* is ignored; the testonly-ness -of the referenced rule is used instead) with some minor exceptions: - -* Tests are not run if their alias is mentioned on the command line. To define an alias - that runs the referenced test, use a [`test_suite`](#test_suite) - rule with a single target in its [`tests`](#test_suite.tests) - attribute. -* When defining environment groups, the aliases to `environment` rules are not - supported. They are not supported in the `--target_environment` command line - option, either. - -#### Examples - -``` -filegroup( - name = "data", - srcs = ["data.txt"], -) - -alias( - name = "other", - actual = ":data", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `actual` | [Label](./concepts/labels); required The target this alias refers to. It does not need to be a rule, it can also be an input file. | - -## config\_setting - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java) - -``` -config_setting(name, aspect_hints, constraint_values, define_values, deprecation, features, flag_values, licenses, package_metadata, tags, testonly, values, visibility) -``` - -Matches an expected configuration state (expressed as build flags or platform constraints) for -the purpose of triggering configurable attributes. See [select](./reference/be/functions.html#select) for -how to consume this rule and [Configurable attributes](./reference/be/common-definitions#configurable-attributes) for an overview of the general feature. - -#### Examples - -The following matches any build that sets `--compilation_mode=opt` or -`-c opt` (either explicitly at the command line or implicitly from .bazelrc files): - -``` - config_setting( - name = "simple", - values = \{"compilation_mode": "opt"\} - ) -``` - -The following matches any build that targets ARM and applies the custom define -`FOO=bar` (for instance, `bazel build --cpu=arm --define FOO=bar ...`): - -``` - config_setting( - name = "two_conditions", - values = \{ - "cpu": "arm", - "define": "FOO=bar" - \} - ) -``` - -The following matches any build that sets -[user-defined flag](https://bazel.build/rules/config#user-defined-build-settings) -`--//custom_flags:foo=1` (either explicitly at the command line or implicitly from -.bazelrc files): - -``` - config_setting( - name = "my_custom_flag_is_set", - flag_values = \{ "//custom_flags:foo": "1" \}, - ) -``` - -The following matches any build that targets a platform with an x86\_64 architecture and glibc -version 2.25, assuming the existence of a `constraint_value` with label -`//example:glibc_2_25`. Note that a platform still matches if it defines additional -constraint values beyond these two. - -``` - config_setting( - name = "64bit_glibc_2_25", - constraint_values = [ - "@platforms//cpu:x86_64", - "//example:glibc_2_25", - ] - ) -``` - -In all these cases, it's possible for the configuration to change within the build, for example if -a target needs to be built for a different platform than its dep. This means that even when a -`config_setting` doesn't match the top-level command-line flags, it may still match -some build targets. - -#### Notes - -* See [select](./reference/be/functions.html#select) for what happens when multiple - `config_setting`s match the current configuration state. -* For flags that support shorthand forms (e.g. `--compilation_mode` vs. - `-c`), `values` definitions must use the full form. These automatically - match invocations using either form. -* If a flag takes multiple values (like `--copt=-Da --copt=-Db` or a list-typed - [Starlark flag](https://bazel.build/rules/config#user-defined-build-settings)), `values = \{ "flag": "a" \}` matches if `"a"` is - present *anywhere* in the actual list. - - `values = \{ "myflag": "a,b" \}` works the same way: this matches - `--myflag=a --myflag=b`, `--myflag=a --myflag=b --myflag=c`, - `--myflag=a,b`, and `--myflag=c,b,a`. Exact semantics vary between - flags. For example, `--copt` doesn't support multiple values *in the same - instance*: `--copt=a,b` produces `["a,b"]` while `--copt=a - --copt=b` produces `["a", "b"]` (so `values = \{ "copt": "a,b" \}` - matches the former but not the latter). But `--ios_multi_cpus` (for Apple rules) - *does*: `-ios_multi_cpus=a,b` and `ios_multi_cpus=a --ios_multi_cpus=b` both produce `["a", "b"]`. Check flag definitions and test your - conditions carefully to verify exact expectations. -* If you need to define conditions that aren't modeled by built-in build flags, use - [Starlark-defined flags](https://bazel.build/rules/config#user-defined-build-settings). You can also use `--define`, but this offers weaker - support and is not recommended. See - [here](./reference/be/common-definitions#configurable-attributes) for more discussion. -* Avoid repeating identical `config_setting` definitions in different packages. - Instead, reference a common `config_setting` that defined in a canonical package. -* [`values`](general.html#config_setting.values), - [`define_values`](general.html#config_setting.define_values), and - [`constraint_values`](general.html#config_setting.constraint_values) - can be used in any combination in the same `config_setting` but at least one must - be set for any given `config_setting`. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `constraint_values` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` The minimum set of `constraint_values` that the target platform must specify in order to match this `config_setting`. (The execution platform is not considered here.) Any additional constraint values that the platform has are ignored. See [Configurable Build Attributes](https://bazel.build/docs/configurable-attributes#platforms) for details. If two `config_setting`s match in the same `select` and one has all the same flags and `constraint_setting`s as the other plus additional ones, the one with more settings is chosen. This is known as "specialization". For example, a `config_setting` matching `x86` and `Linux` specializes a `config_setting` matching `x86`. If two `config_setting`s match and both have `constraint_value`s not present in the other, this is an error. | -| `define_values` | Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `\{\}` The same as [`values`](./reference/be/general.html#config_setting.values) but specifically for the `--define` flag. `--define` is special because its syntax (`--define KEY=VAL`) means `KEY=VAL` is a *value* from a Bazel flag perspective. That means: ``` config_setting( name = "a_and_b", values = \{ "define": "a=1", "define": "b=2", \}) ``` doesn't work because the same key (`define`) appears twice in the dictionary. This attribute solves that problem: ``` config_setting( name = "a_and_b", define_values = \{ "a": "1", "b": "2", \}) ``` correctly matches `bazel build //foo --define a=1 --define b=2`. `--define` can still appear in [`values`](./reference/be/general.html#config_setting.values) with normal flag syntax, and can be mixed freely with this attribute as long as dictionary keys remain distinct. | -| `flag_values` | Dictionary: [label](./concepts/labels) -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `\{\}` The same as [`values`](./reference/be/general.html#config_setting.values) but for [user-defined build flags](https://bazel.build/rules/config#user-defined-build-settings). This is a distinct attribute because user-defined flags are referenced as labels while built-in flags are referenced as arbitrary strings. | -| `values` | Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `\{\}` The set of configuration values that match this rule (expressed as build flags) This rule inherits the configuration of the configured target that references it in a `select` statement. It is considered to "match" a Bazel invocation if, for every entry in the dictionary, its configuration matches the entry's expected value. For example `values = \{"compilation_mode": "opt"\}` matches the invocations `bazel build --compilation_mode=opt ...` and `bazel build -c opt ...` on target-configured rules. For convenience's sake, configuration values are specified as build flags (without the preceding `"--"`). But keep in mind that the two are not the same. This is because targets can be built in multiple configurations within the same build. For example, an exec configuration's "cpu" matches the value of `--host_cpu`, not `--cpu`. So different instances of the same `config_setting` may match the same invocation differently depending on the configuration of the rule using them. If a flag is not explicitly set at the command line, its default value is used. If a key appears multiple times in the dictionary, only the last instance is used. If a key references a flag that can be set multiple times on the command line (e.g. `bazel build --copt=foo --copt=bar --copt=baz ...`), a match occurs if *any* of those settings match. | - -## filegroup - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/filegroup/FilegroupRule.java) - -``` -filegroup(name, srcs, data, aspect_hints, compatible_with, deprecation, features, licenses, output_group, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) -``` - -Use `filegroup` to gather the outputs of a set of targets under a single -label. - -`filegroup` is not a substitute for listing targets on the command line or -in an attribute of another rule, because targets have many properties other than their -outputs, which are not collected in the same way. However, it's still useful in quite -a few cases, for example, in the `srcs` attribute of a genrule, or -the `data` attribute of a \*\_binary rule. - -Using `filegroup` is encouraged instead of referencing directories directly. -Directly referencing directories is discouraged because the build system does not have -full knowledge of all files below the directory, so it may not rebuild when these files change. -When combined with [glob](./reference/be/functions.html#glob), `filegroup` can ensure that all -files are explicitly known to the build system. - -#### Examples - -To create a `filegroup` consisting of two source files, do - -``` -filegroup( - name = "mygroup", - srcs = [ - "a_file.txt", - "//a/library:target", - "//a/binary:target", - ], -) -``` - -Or, use a `glob` to fully crawl a testdata directory: - -``` -filegroup( - name = "exported_testdata", - srcs = glob([ - "testdata/*.dat", - "testdata/logs/**/*.log", - ]), -) -``` - -To make use of these definitions, reference the `filegroup` with a label from any rule: - -``` -cc_library( - name = "my_library", - srcs = ["foo.cc"], - data = [ - "//my_package:exported_testdata", - "//my_package:mygroup", - ], -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of targets that are members of the file group. It is common to use the result of a [glob](./reference/be/functions.html#glob) expression for the value of the `srcs` attribute. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this rule at runtime. Targets named in the `data` attribute will be added to the `runfiles` of this `filegroup` rule. When the `filegroup` is referenced in the `data` attribute of another rule its `runfiles` will be added to the `runfiles` of the depending rule. See the [data dependencies](./concepts/dependencies#data-dependencies) section and [general documentation of `data`](./reference/be/common-definitions#common.data) for more information about how to depend on and use data files. | -| `output_group` | String; default is `""` The output group from which to gather artifacts from sources. If this attribute is specified, artifacts from the specified output group of the dependencies will be exported instead of the default output group. An "output group" is a category of output artifacts of a target, specified in that rule's implementation. | - -## genquery - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java) - -``` -genquery(name, deps, data, aspect_hints, compatible_with, compressed_output, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, expression, features, licenses, opts, package_metadata, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility) -``` - -`genquery()` runs a query specified in the -[Bazel query language](./reference/query) and dumps the result -into a file. - -In order to keep the build consistent, the query is allowed only to visit -the transitive closure of the targets specified in the `scope` -attribute. Queries violating this rule will fail during execution if -`strict` is unspecified or true (if `strict` is false, -the out of scope targets will simply be skipped with a warning). The -easiest way to make sure this does not happen is to mention the same labels -in the scope as in the query expression. - -The only difference between the queries allowed here and on the command -line is that queries containing wildcard target specifications (e.g. -`//pkg:*` or `//pkg:all`) are not allowed here. -The reasons for this are two-fold: first, because `genquery` has -to specify a scope to prevent targets outside the transitive closure of the -query to influence its output; and, second, because `BUILD` files -do not support wildcard dependencies (e.g. `deps=["//a/..."]` -is not allowed). - -The genquery's output is ordered lexicographically in order to enforce deterministic output, -with the exception of `--output=graph|minrank|maxrank` or when `somepath` -is used as the top-level function. - -The name of the output file is the name of the rule. - -#### Examples - -This example writes the list of the labels in the transitive closure of the -specified target to a file. - -``` -genquery( - name = "kiwi-deps", - expression = "deps(//kiwi:kiwi_lib)", - scope = ["//kiwi:kiwi_lib"], -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `compressed_output` | Boolean; default is `False` If `True`, query output is written in GZIP file format. This setting can be used to avoid spikes in Bazel's memory use when the query output is expected to be large. Bazel already internally compresses query outputs greater than 220 bytes regardless of the value of this setting, so setting this to `True` may not reduce retained heap. However, it allows Bazel to skip *decompression* when writing the output file, which can be memory-intensive. | -| `expression` | String; required The query to be executed. In contrast to the command line and other places in BUILD files, labels here are resolved relative to the root directory of the workspace. For example, the label `:b` in this attribute in the file `a/BUILD` will refer to the target `//:b`. | -| `opts` | List of strings; default is `[]` The options that are passed to the query engine. These correspond to the command line options that can be passed to `bazel query`. Some query options are not allowed here: `--keep_going`, `--query_file`, `--universe_scope`, `--order_results` and `--order_output`. Options not specified here will have their default values just like on the command line of `bazel query`. | -| `scope` | List of [labels](./concepts/labels); required The scope of the query. The query is not allowed to touch targets outside the transitive closure of these targets. | -| `strict` | Boolean; default is `True` If true, targets whose queries escape the transitive closure of their scopes will fail to build. If false, Bazel will print a warning and skip whatever query path led it outside of the scope, while completing the rest of the query. | - -## genrule - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java) - -``` -genrule(name, srcs, outs, aspect_hints, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility) -``` - -A `genrule` generates one or more files using a user-defined Bash command. - -Genrules are generic build rules that you can use if there's no specific rule for the task. -For example, you could run a Bash one-liner. If however you need to compile C++ files, stick -to the existing `cc_*` rules, because all the heavy lifting has already been done -for you. - -Note that genrule requires a shell to interpret the command argument. -It is also easy to reference arbitrary programs available on the PATH, however this makes the -command non-hermetic and may not be reproducible. -If you only need to run a single tool, consider using -[run\_binary](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/run_binary_doc.md) -instead. - -Like every other action, the action created by genrules should not assume anything about their -working directory; all Bazel guarantees is that their declared inputs will be available at the -path that `$(location)` returns for their label. For example, if the action is run in a -sandbox or remotely, the implementation of the sandbox or the remote execution will determine the -working directory. If run directly (using the `standalone` strategy), the working -directory will be the execution root, i.e. the result of `bazel info execution_root`. - -Do not use a genrule for running tests. There are special dispensations for tests and test -results, including caching policies and environment variables. Tests generally need to be run -after the build is complete and on the target architecture, whereas genrules are executed during -the build and on the exec architecture (the two may be different). If you need a general purpose -testing rule, use [`sh_test`](./reference/be/shell.html#sh_test). - -#### Cross-compilation Considerations - -*See [the user manual](./docs/user-manual#configurations) for more info about -cross-compilation.* - -While genrules run during a build, their outputs are often used after the build, for deployment or -testing. Consider the example of compiling C code for a microcontroller: the compiler accepts C -source files and generates code that runs on a microcontroller. The generated code obviously -cannot run on the CPU that was used for building it, but the C compiler (if compiled from source) -itself has to. - -The build system uses the exec configuration to describe the machine(s) on which the build runs -and the target configuration to describe the machine(s) on which the output of the build is -supposed to run. It provides options to configure each of these and it segregates the -corresponding files into separate directories to avoid conflicts. - -For genrules, the build system ensures that dependencies are built appropriately: -`srcs` are built (if necessary) for the *target* configuration, -`tools` are built for the *exec* configuration, and the output is considered to -be for the *target* configuration. It also provides ["Make" variables](./reference/be/make-variables) that genrule commands can pass to the corresponding tools. - -It is intentional that genrule defines no `deps` attribute: other built-in rules use -language-dependent meta information passed between the rules to automatically determine how to -handle dependent rules, but this level of automation is not possible for genrules. Genrules work -purely at the file and runfiles level. - -#### Special Cases - -*Exec-exec compilation*: in some cases, the build system needs to run genrules such that the -output can also be executed during the build. If for example a genrule builds some custom compiler -which is subsequently used by another genrule, the first one has to produce its output for the -exec configuration, because that's where the compiler will run in the other genrule. In this case, -the build system does the right thing automatically: it builds the `srcs` and -`outs` of the first genrule for the exec configuration instead of the target -configuration. See [the user manual](./docs/user-manual#configurations) for more -info. - -*JDK & C++ Tooling*: to use a tool from the JDK or the C++ compiler suite, the build system -provides a set of variables to use. See ["Make" variable](./reference/be/make-variables) for -details. - -#### Genrule Environment - -The genrule command is executed by a Bash shell that is configured to fail when a command -or a pipeline fails, using `set -e -o pipefail`. - -The build tool executes the Bash command in a sanitized process environment that -defines only core variables such as `PATH`, `PWD`, -`TMPDIR`, and a few others. -To ensure that builds are reproducible, most variables defined in the user's shell -environment are not passed though to the genrule's command. However, Bazel (but not -Blaze) passes through the value of the user's `PATH` environment variable. -Any change to the value of `PATH` will cause Bazel to re-execute the command -on the next build. - -A genrule command should not access the network except to connect processes that are -children of the command itself, though this is not currently enforced. - -The build system automatically deletes any existing output files, but creates any necessary parent -directories before it runs a genrule. It also removes any output files in case of a failure. - -#### General Advice - -* Do ensure that tools run by a genrule are deterministic and hermetic. They should not write - timestamps to their output, and they should use stable ordering for sets and maps, as well as - write only relative file paths to the output, no absolute paths. Not following this rule will - lead to unexpected build behavior (Bazel not rebuilding a genrule you thought it would) and - degrade cache performance. -* Do use `$(location)` extensively, for outputs, tools and sources. Due to the - segregation of output files for different configurations, genrules cannot rely on hard-coded - and/or absolute paths. -* Do write a common Starlark macro in case the same or very similar genrules are used in - multiple places. If the genrule is complex, consider implementing it in a script or as a - Starlark rule. This improves readability as well as testability. -* Do make sure that the exit code correctly indicates success or failure of the genrule. -* Do not write informational messages to stdout or stderr. While useful for debugging, this can - easily become noise; a successful genrule should be silent. On the other hand, a failing genrule - should emit good error messages. -* `$$` evaluates to a `$`, a literal dollar-sign, so in order to invoke a - shell command containing dollar-signs such as `ls $(dirname $x)`, one must escape it - thus: `ls $$(dirname $$x)`. -* Avoid creating symlinks and directories. Bazel doesn't copy over the directory/symlink - structure created by genrules and its dependency checking of directories is unsound. -* When referencing the genrule in other rules, you can use either the genrule's label or the - labels of individual output files. Sometimes the one approach is more readable, sometimes the - other: referencing outputs by name in a consuming rule's `srcs` will avoid - unintentionally picking up other outputs of the genrule, but can be tedious if the genrule - produces many outputs. - -#### Examples - -This example generates `foo.h`. There are no sources, because the command doesn't take -any input. The "binary" run by the command is a perl script in the same package as the genrule. - -``` -genrule( - name = "foo", - srcs = [], - outs = ["foo.h"], - cmd = "./$(location create_foo.pl) > \"$@\"", - tools = ["create_foo.pl"], -) -``` - -The following example shows how to use a [`filegroup`](./reference/be/general.html#filegroup) and the outputs of another `genrule`. Note that using `$(SRCS)` instead -of explicit `$(location)` directives would also work; this example uses the latter for -sake of demonstration. - -``` -genrule( - name = "concat_all_files", - srcs = [ - "//some:files", # a filegroup with multiple files in it ==> $(locations) - "//other:gen", # a genrule with a single output ==> $(location) - ], - outs = ["concatenated.txt"], - cmd = "cat $(locations //some:files) $(location //other:gen) > $@", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. You may refer to this rule by name in the `srcs` or `deps` section of other `BUILD` rules. If the rule generates source files, you should use the `srcs` attribute. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` A list of inputs for this rule, such as source files to process. *This attributes is not suitable to list tools executed by the `cmd`; use the [`tools`](./reference/be/general.html#genrule.tools) attribute for them instead.* The build system ensures these prerequisites are built before running the genrule command; they are built using the same configuration as the original build request. The names of the files of these prerequisites are available to the command as a space-separated list in `$(SRCS)`; alternatively the path of an individual `srcs` target `//x:y` can be obtained using `$(location //x:y)`, or using `$<` provided it's the only entry in `srcs`. | -| `outs` | List of [filenames](./concepts/build-ref#filename); [nonconfigurable](common-definitions.html#configurable-attributes); required A list of files generated by this rule. Output files must not cross package boundaries. Output filenames are interpreted as relative to the package. If the `executable` flag is set, `outs` must contain exactly one label. The genrule command is expected to create each output file at a predetermined location. The location is available in `cmd` using [genrule-specific "Make" variables](./reference/be/make-variables#predefined_genrule_variables) (`$@`, `$(OUTS)`, `$(@D)` or `$(RULEDIR)`) or using [`$(location)`](./reference/be/make-variables#predefined_label_variables) substitution. | -| `cmd` | String; default is `""` The command to run. Subject to [`$(location)`](./reference/be/make-variables#predefined_label_variables) and ["Make" variable](./reference/be/make-variables) substitution. 1. First [`$(location)`](./reference/be/make-variables#predefined_label_variables) substitution is applied, replacing all occurrences of `$(location label)` and of `$(locations label)` (and similar constructions using related variables `execpath`, `execpaths`, `rootpath` and `rootpaths`). 2. Next, ["Make" variables](./reference/be/make-variables) are expanded. Note that predefined variables `$(JAVA)`, `$(JAVAC)` and `$(JAVABASE)` expand under the *exec* configuration, so Java invocations that run as part of a build step can correctly load shared libraries and other dependencies. 3. Finally, the resulting command is executed using the Bash shell. If its exit code is non-zero the command is considered to have failed. This is the fallback of `cmd_bash`, `cmd_ps` and `cmd_bat`, if none of them are applicable. | - -If the command line length exceeds the platform limit (64K on Linux/macOS, 8K on Windows), -then genrule will write the command to a script and execute that script to work around. This -applies to all cmd attributes (`cmd`, `cmd_bash`, `cmd_ps`, -`cmd_bat`). - -| `cmd_bash` | String; default is `""` The Bash command to run. This attribute has higher priority than `cmd`. The command is expanded and runs in the exact same way as the `cmd` attribute. | -| `cmd_bat` | String; default is `""` The Batch command to run on Windows. This attribute has higher priority than `cmd` and `cmd_bash`. The command runs in the similar way as the `cmd` attribute, with the following differences: * This attribute only applies on Windows. * The command runs with `cmd.exe /c` with the following default arguments: + `/S` - strip first and last quotes and execute everything else as is. + `/E:ON` - enable extended command set. + `/V:ON` - enable delayed variable expansion + `/D` - ignore AutoRun registry entries. * After [$(location)](./reference/be/make-variables#predefined_label_variables) and ["Make" variable](./reference/be/make-variables) substitution, the paths will be expanded to Windows style paths (with backslash). | -| `cmd_ps` | String; default is `""` The Powershell command to run on Windows. This attribute has higher priority than `cmd`, `cmd_bash` and `cmd_bat`. The command runs in the similar way as the `cmd` attribute, with the following differences: * This attribute only applies on Windows. * The command runs with `powershell.exe /c`. To make Powershell easier to use and less error-prone, we run the following commands to set up the environment before executing Powershell command in genrule. * `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` - allow running unsigned scripts. * `$errorActionPreference='Stop'` - In case there are multiple commands separated by `;`, the action exits immediately if a Powershell CmdLet fails, but this does **NOT** work for external command. * `$PSDefaultParameterValues['*:Encoding'] = 'utf8'` - change the default encoding from utf-16 to utf-8. | -| `executable` | Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` Declare output to be executable. Setting this flag to True means the output is an executable file and can be run using the `run` command. The genrule must produce exactly one output in this case. If this attribute is set, `run` will try executing the file regardless of its content. Declaring data dependencies for the generated executable is not supported. | -| `local` | Boolean; default is `False` If set to True, this option forces this `genrule` to run using the "local" strategy, which means no remote execution, no sandboxing, no persistent workers. This is equivalent to providing 'local' as a tag (`tags=["local"]`). | -| `message` | String; default is `""` A progress message. A progress message that will be printed as this build step is executed. By default, the message is "Generating *output*" (or something equally bland) but you may provide a more specific one. Use this attribute instead of `echo` or other print statements in your `cmd` command, as this allows the build tool to control whether such progress messages are printed or not. | -| `output_licenses` | List of strings; default is `[]` See [`common attributes`](./reference/be/common-definitions#binary.output_licenses) | -| `output_to_bindir` | Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` If set to True, this option causes output files to be written into the `bin` directory instead of the `genfiles` directory. | -| `toolchains` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` The set of targets whose [Make variables](./reference/be/make-variables) this genrule is allowed to access, or the [`toolchain_type`](./docs/toolchains) targets that this genrule will access. Toolchains accessed via `toolchain_type` must also provide a `TemplateVariableInfo` provider, which the target can use to access toolchain details. | -| `tools` | List of [labels](./concepts/labels); default is `[]` A list of *tool* dependencies for this rule. See the definition of [dependencies](./concepts/build-ref#deps) for more information. The build system ensures these prerequisites are built before running the genrule command; they are built using the [*exec* configuration](./contribute/guide#configurations), since these tools are executed as part of the build. The path of an individual `tools` target `//x:y` can be obtained using `$(location //x:y)`. Any `*_binary` or tool to be executed by `cmd` must appear in this list, not in `srcs`, to ensure they are built in the correct configuration. | - - -## starlark\_doc\_extract - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/starlarkdocextract/StarlarkDocExtractRule.java) - -``` -starlark_doc_extract(name, deps, src, data, allow_unused_doc_comments, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility) -``` - -`starlark_doc_extract()` extracts documentation for rules, functions (including -macros), aspects, and providers defined or re-exported in a given `.bzl` or -`.scl` file. The output of this rule is a `ModuleInfo` binary proto as defined -in -[stardoc\_output.proto](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto) -in the Bazel source tree. - -#### Implicit output targets - -* `name.binaryproto` (the default output): A - `ModuleInfo` binary proto. -* `name.textproto` (only built if explicitly requested): the text - proto version of `name.binaryproto`. - -Warning: the output format of this rule is not guaranteed to be stable. It is intended mainly for -internal use by [Stardoc](https://github.com/bazelbuild/stardoc). - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` A list of targets wrapping the Starlark files which are `load()`-ed by `src`. These targets *should* under normal usage be [`bzl_library`](https://github.com/bazelbuild/bazel-skylib/blob/main/bzl_library.bzl) targets, but the `starlark_doc_extract` rule does not enforce that, and accepts any target which provides Starlark files in its `DefaultInfo`. Note that the wrapped Starlark files must be files in the source tree; Bazel cannot `load()` generated files. | -| `src` | [Label](./concepts/labels); required A Starlark file from which to extract documentation. Note that this must be a file in the source tree; Bazel cannot `load()` generated files. | -| `allow_unused_doc_comments` | Boolean; default is `False` If true, allow and silently ignore doc comments (comments starting with `#:`) which are not attached to any global variable, or which are attached to a variable whose value's documentation should be provided in a different way (for example, in a docstring for a function, or via `rule(doc = ...)` for a rule). | -| `render_main_repo_name` | Boolean; default is `False` If true, render labels in the main repository in emitted documentation with a repo component (in other words, `//foo:bar.bzl` will be emitted as `@main_repo_name//foo:bar.bzl`). The name to use for the main repository is obtained from `module(name = ...)` in the main repository's `MODULE.bazel` file (if Bzlmod is enabled), or from `workspace(name = ...)` in the main repository's `WORKSPACE` file. This attribute should be set to `False` when generating documentation for Starlark files which are intended to be used only within the same repository, and to `True` when generating documentation for Starlark files which are intended to be used from other repositories. | -| `symbol_names` | List of strings; default is `[]` An optional list of qualified names of exported functions, rules, providers, or aspects (or structs in which they are nested) for which to extract documentation. Here, a *qualified name* means the name under which an entity is made available to a user of the module, including any structs in which the entity is nested for namespacing. `starlark_doc_extract` emits documentation for an entity if and only if 1. each component of the entity's qualified name is public (in other words, the first character of each component of the qualified name is alphabetic, not `"_"`); *and* 2. 1. *either* the `symbol_names` list is empty (which is the default case), *or* 2. the entity's qualified name, or the qualified name of a struct in which the entity is nested, is in the `symbol_names` list. | - -## test\_suite - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java) - -``` -test_suite(name, aspect_hints, compatible_with, deprecation, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, tests, visibility) -``` - -A `test_suite` defines a set of tests that are considered "useful" to humans. This -allows projects to define sets of tests, such as "tests you must run before checkin", "our -project's stress tests" or "all small tests." The `bazel test` command respects this sort -of organization: For an invocation like `bazel test //some/test:suite`, Bazel first -enumerates all test targets transitively included by the `//some/test:suite` target (we -call this "test\_suite expansion"), then Bazel builds and tests those targets. - -#### Examples - -A test suite to run all of the small tests in the current package. - -``` -test_suite( - name = "small_tests", - tags = ["small"], -) -``` - -A test suite that runs a specified set of tests: - -``` -test_suite( - name = "smoke_tests", - tests = [ - "system_unittest", - "public_api_unittest", - ], -) -``` - -A test suite to run all tests in the current package which are not flaky. - -``` -test_suite( - name = "non_flaky_test", - tags = ["-flaky"], -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `tags` | List of strings; [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` List of text tags such as "small" or "database" or "-flaky". Tags may be any valid string. Tags which begin with a "-" character are considered negative tags. The preceding "-" character is not considered part of the tag, so a suite tag of "-small" matches a test's "small" size. All other tags are considered positive tags. Optionally, to make positive tags more explicit, tags may also begin with the "+" character, which will not be evaluated as part of the text of the tag. It merely makes the positive and negative distinction easier to read. Only test rules that match **all** of the positive tags and **none** of the negative tags will be included in the test suite. Note that this does not mean that error checking for dependencies on tests that are filtered out is skipped; the dependencies on skipped tests still need to be legal (e.g. not blocked by visibility constraints). The `manual` tag keyword is treated differently than the above by the "test\_suite expansion" performed by the `bazel test` command on invocations involving wildcard [target patterns](https://bazel.build/docs/build#specifying-build-targets). There, `test_suite` targets tagged "manual" are filtered out (and thus not expanded). This behavior is consistent with how `bazel build` and `bazel test` handle wildcard target patterns in general. Note that this is explicitly different from how `bazel query 'tests(E)'` behaves, as suites are always expanded by the `tests` query function, regardless of the `manual` tag. Note that a test's `size` is considered a tag for the purpose of filtering. If you need a `test_suite` that contains tests with mutually exclusive tags (e.g. all small and medium tests), you'll have to create three `test_suite` rules: one for all small tests, one for all medium tests, and one that includes the previous two. | -| `tests` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` A list of test suites and test targets of any language. Any `*_test` is accepted here, independent of the language. No `*_binary` targets are accepted however, even if they happen to run a test. Filtering by the specified `tags` is only done for tests listed directly in this attribute. If this attribute contains `test_suite`s, the tests inside those will not be filtered by this `test_suite` (they are considered to be filtered already). If the `tests` attribute is unspecified or empty, the rule will default to including all test rules in the current BUILD file that are not tagged as `manual`. These rules are still subject to `tag` filtering. | \ No newline at end of file diff --git a/reference/be/java.mdx b/reference/be/java.mdx deleted file mode 100644 index ec9893e..0000000 --- a/reference/be/java.mdx +++ /dev/null @@ -1,530 +0,0 @@ ---- -title: 'java' ---- - - -## Rules - -* [java\_binary](#java_binary) -* [java\_import](#java_import) -* [java\_library](#java_library) -* [java\_test](#java_test) -* [java\_package\_configuration](#java_package_configuration) -* [java\_plugin](#java_plugin) -* [java\_runtime](#java_runtime) -* [java\_single\_jar](#java_single_jar) -* [java\_toolchain](#java_toolchain) - -## java\_binary - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_binary.bzl) - -``` -java_binary(name, deps, srcs, data, resources, add_exports, add_opens, args, aspect_hints, bootclasspath, classpath_resources, compatible_with, create_executable, deploy_env, deploy_manifest_lines, deprecation, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, javacopts, jvm_flags, launcher, licenses, main_class, neverlink, output_licenses, package_metadata, plugins, resource_strip_prefix, restricted_to, runtime_deps, stamp, tags, target_compatible_with, testonly, toolchains, use_launcher, use_testrunner, visibility) -``` - -Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. -The wrapper shell script uses a classpath that includes, among other things, a jar file for each -library on which the binary depends. When running the wrapper shell script, any nonempty -`JAVABIN` environment variable will take precedence over the version specified via -Bazel's `--java_runtime_version` flag. - -The wrapper script accepts several unique flags. Refer to -`java_stub_template.txt` -for a list of configurable flags and environment variables accepted by the wrapper. - -#### Implicit output targets - -* `name.jar`: A Java archive, containing the class files and other - resources corresponding to the binary's direct dependencies. -* `name-src.jar`: An archive containing the sources ("source - jar"). -* `name_deploy.jar`: A Java archive suitable for deployment (only - built if explicitly requested). - - Building the `<name>_deploy.jar` target for your rule - creates a self-contained jar file with a manifest that allows it to be run with the - `java -jar` command or with the wrapper script's `--singlejar` - option. Using the wrapper script is preferred to `java -jar` because it - also passes the [JVM flags](#java_binary-jvm_flags) and the options - to load native libraries. - - The deploy jar contains all the classes that would be found by a classloader that - searched the classpath from the binary's wrapper script from beginning to end. It also - contains the native libraries needed for dependencies. These are automatically loaded - into the JVM at runtime. - - If your target specifies a [launcher](#java_binary.launcher) - attribute, then instead of being a normal JAR file, the \_deploy.jar will be a - native binary. This will contain the launcher plus any native (C++) dependencies of - your rule, all linked into a static binary. The actual jar file's bytes will be - appended to that native binary, creating a single binary blob containing both the - executable and the Java code. You can execute the resulting jar file directly - like you would execute any native binary. -* `name_deploy-src.jar`: An archive containing the sources - collected from the transitive closure of the target. These will match the classes in the - `deploy.jar` except where jars have no matching source jar. - -It is good practice to use the name of the source file that is the main entry point of the -application (minus the extension). For example, if your entry point is called -`Main.java`, then your name could be `Main`. - -A `deps` attribute is not allowed in a `java_binary` rule without -[`srcs`](#java_binary-srcs); such a rule requires a -[`main_class`](#java_binary-main_class) provided by -[`runtime_deps`](#java_binary-runtime_deps). - -The following code snippet illustrates a common mistake: - -``` -java_binary( - name = "DontDoThis", - srcs = [ - ..., - "GeneratedJavaFile.java", # a generated .java file - ], - deps = [":generating_rule",], # rule that generates that file -) -``` - -Do this instead: - -``` -java_binary( - name = "DoThisInstead", - srcs = [ - ..., - ":generating_rule", - ], -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the target. See general comments about `deps` at [Typical attributes defined by most build rules](common-definitions.html#typical-attributes). | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. Source files of type `.java` are compiled. In case of generated `.java` files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the `outs` of the generating rule. You should not list the generating rule in `deps` because it is a no-op. Source files of type `.srcjar` are unpacked and compiled. (This is useful if you need to generate a set of `.java` files with a genrule.) Rules: if the rule (typically `genrule` or `filegroup`) generates any of the files listed above, they will be used the same way as described for source files. This argument is almost always required, except if a [`main_class`](#java_binary.main_class) attribute specifies a class on the runtime classpath or you specify the `runtime_deps` argument. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). | -| `resources` | List of [labels](./concepts/labels); default is `[]` A list of data files to include in a Java jar. Resources may be source files or generated files. If resources are specified, they will be bundled in the jar along with the usual `.class` files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's [standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.mdx), (a "src" directory followed by a "resources" directory grandchild). If that is not found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for example, if a resource is at `\<workspace root\>/x/java/y/java/z`, the path of the resource will be `y/java/z`. This heuristic cannot be overridden, however, the `resource_strip_prefix` attribute can be used to specify a specific alternative directory for resource files. | -| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | -| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | -| `bootclasspath` | [Label](./concepts/labels); default is `None` Restricted API, do not use! | -| `classpath_resources` | List of [labels](./concepts/labels); default is `[]` *DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)* A list of resources that must be located at the root of the java tree. This attribute's only purpose is to support third-party libraries that require that their resources be found on the classpath as exactly `"myconfig.xml"`. It is only allowed on binaries and not libraries, due to the danger of namespace conflicts. | -| `create_executable` | Boolean; default is `True` Deprecated, use `java_single_jar` instead. | -| `deploy_env` | List of [labels](./concepts/labels); default is `[]` A list of other `java_binary` targets which represent the deployment environment for this binary. Set this attribute when building a plugin which will be loaded by another `java_binary`. Setting this attribute excludes all dependencies from the runtime classpath (and the deploy jar) of this binary that are shared between this binary and the targets specified in `deploy_env`. | -| `deploy_manifest_lines` | List of strings; default is `[]` A list of lines to add to the `META-INF/manifest.mf` file generated for the `*_deploy.jar` target. The contents of this attribute are *not* subject to ["Make variable"](make-variables.mdx) substitution. | -| `javacopts` | List of strings; default is `[]` Extra compiler options for this binary. Subject to ["Make variable"](make-variables.mdx) substitution and [Bourne shell tokenization](common-definitions.html#sh-tokenization). These compiler options are passed to javac after the global compiler options. | -| `jvm_flags` | List of strings; default is `[]` A list of flags to embed in the wrapper script generated for running this binary. Subject to [$(location)](./reference/be/make-variables#location) and ["Make variable"](make-variables.mdx) substitution, and [Bourne shell tokenization](common-definitions.html#sh-tokenization). The wrapper script for a Java binary includes a CLASSPATH definition (to find all the dependent jars) and invokes the right Java interpreter. The command line generated by the wrapper script includes the name of the main class followed by a `"$@"` so you can pass along other arguments after the classname. However, arguments intended for parsing by the JVM must be specified *before* the classname on the command line. The contents of `jvm_flags` are added to the wrapper script before the classname is listed. Note that this attribute has *no effect* on `*_deploy.jar` outputs. | -| `launcher` | [Label](./concepts/labels); default is `None` Specify a binary that will be used to run your Java program instead of the normal `bin/java` program included with the JDK. The target must be a `cc_binary`. Any `cc_binary` that implements the [Java Invocation API](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.mdx) can be specified as a value for this attribute. By default, Bazel will use the normal JDK launcher (bin/java or java.exe). The related [`--java_launcher`](./docs/user-manual#flag--java_launcher) Bazel flag affects only those `java_binary` and `java_test` targets that have *not* specified a `launcher` attribute. Note that your native (C++, SWIG, JNI) dependencies will be built differently depending on whether you are using the JDK launcher or another launcher: * If you are using the normal JDK launcher (the default), native dependencies are built as a shared library named `\{name\}_nativedeps.so`, where `\{name\}` is the `name` attribute of this java\_binary rule. Unused code is *not* removed by the linker in this configuration. * If you are using any other launcher, native (C++) dependencies are statically linked into a binary named `\{name\}_nativedeps`, where `\{name\}` is the `name` attribute of this java\_binary rule. In this case, the linker will remove any code it thinks is unused from the resulting binary, which means any C++ code accessed only via JNI may not be linked in unless that `cc_library` target specifies `alwayslink = True`. When using any launcher other than the default JDK launcher, the format of the `*_deploy.jar` output changes. See the main [java\_binary](#java_binary) docs for details. | -| `main_class` | String; default is `""` Name of class with `main()` method to use as entry point. If a rule uses this option, it does not need a `srcs=[...]` list. Thus, with this attribute one can make an executable from a Java library that already contains one or more `main()` methods. The value of this attribute is a class name, not a source file. The class must be available at runtime: it may be compiled by this rule (from `srcs`) or provided by direct or transitive dependencies (through `runtime_deps` or `deps`). If the class is unavailable, the binary will fail at runtime; there is no build-time check. | -| `neverlink` | Boolean; default is `False` | -| `plugins` | List of [labels](./concepts/labels); default is `[]` Java compiler plugins to run at compile-time. Every `java_plugin` specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use `exported_plugins`. Resources generated by the plugin will be included in the resulting jar of this rule. | -| `resource_strip_prefix` | String; default is `""` The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at `stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. | -| `runtime_deps` | List of [labels](./concepts/labels); default is `[]` Libraries to make available to the final binary or test at runtime only. Like ordinary `deps`, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both `runtime_deps` and `deps`. | -| `stamp` | Integer; default is `-1` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](./docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | -| `use_launcher` | Boolean; default is `True` Whether the binary should use a custom launcher. If this attribute is set to false, the [launcher](./reference/be/java.html#java_binary.launcher) attribute and the related [`--java_launcher`](./docs/user-manual#flag--java_launcher) flag will be ignored for this target. | -| `use_testrunner` | Boolean; default is `False` Use the test runner (by default `com.google.testing.junit.runner.BazelTestRunner`) class as the main entry point for a Java program, and provide the test class to the test runner as a value of `bazel.test_suite` system property. You can use this to override the default behavior, which is to use test runner for `java_test` rules, and not use it for `java_binary` rules. It is unlikely you will want to do this. One use is for `AllTest` rules that are invoked by another rule (to set up a database before running the tests, for example). The `AllTest` rule must be declared as a `java_binary`, but should still use the test runner as its main entry point. The name of a test runner class can be overridden with `main_class` attribute. | - -## java\_import - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_import.bzl) - -``` -java_import(name, deps, data, add_exports, add_opens, aspect_hints, compatible_with, constraints, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exports, features, jars, licenses, neverlink, package_metadata, proguard_specs, restricted_to, runtime_deps, srcjar, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -This rule allows the use of precompiled `.jar` files as -libraries for `java_library` and -`java_binary` rules. - -#### Examples - -``` - java_import( - name = "maven_model", - jars = [ - "maven_model/maven-aether-provider-3.2.3.jar", - "maven_model/maven-model-3.2.3.jar", - "maven_model/maven-model-builder-3.2.3.jar", - ], - ) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the target. See [java\_library.deps](./reference/be/java.html#java_library.deps). | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this rule at runtime. | -| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | -| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | -| `constraints` | List of strings; default is `[]` Extra constraints imposed on this rule as a Java library. | -| `exports` | List of [labels](./concepts/labels); default is `[]` Targets to make available to users of this rule. See [java\_library.exports](./reference/be/java.html#java_library.exports). | -| `jars` | List of [labels](./concepts/labels); required The list of JAR files provided to Java targets that depend on this target. | -| `neverlink` | Boolean; default is `False` Only use this library for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of libraries like this are IDE APIs for IDE plug-ins or `tools.jar` for anything running on a standard JDK. | -| `proguard_specs` | List of [labels](./concepts/labels); default is `[]` Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any `android_binary` target depending on this library. The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in `android_binary`'s proguard\_specs, to ensure non-tautological merges. | -| `runtime_deps` | List of [labels](./concepts/labels); default is `[]` Libraries to make available to the final binary or test at runtime only. See [java\_library.runtime\_deps](./reference/be/java.html#java_library.runtime_deps). | -| `srcjar` | [Label](./concepts/labels); default is `None` A JAR file that contains source code for the compiled JAR files. | - -## java\_library - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_library.bzl) - -``` -java_library(name, deps, srcs, data, resources, add_exports, add_opens, aspect_hints, bootclasspath, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exported_plugins, exports, features, javabuilder_jvm_flags, javacopts, licenses, neverlink, package_metadata, plugins, proguard_specs, resource_strip_prefix, restricted_to, runtime_deps, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -This rule compiles and links sources into a `.jar` file. - -#### Implicit outputs - -* `libname.jar`: A Java archive containing the class files. -* `libname-src.jar`: An archive containing the sources ("source - jar"). - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of libraries to link into this library. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). The jars built by `java_library` rules listed in `deps` will be on the compile-time classpath of this rule. Furthermore the transitive closure of their `deps`, `runtime_deps` and `exports` will be on the runtime classpath. By contrast, targets in the `data` attribute are included in the runfiles but on neither the compile-time nor runtime classpath. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. Source files of type `.java` are compiled. In case of generated `.java` files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the `outs` of the generating rule. You should not list the generating rule in `deps` because it is a no-op. Source files of type `.srcjar` are unpacked and compiled. (This is useful if you need to generate a set of `.java` files with a genrule.) Rules: if the rule (typically `genrule` or `filegroup`) generates any of the files listed above, they will be used the same way as described for source files. Source files of type `.properties` are treated as resources. All other files are ignored, as long as there is at least one file of a file type described above. Otherwise an error is raised. This argument is almost always required, except if you specify the `runtime_deps` argument. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). When building a `java_library`, Bazel doesn't put these files anywhere; if the `data` files are generated files then Bazel generates them. When building a test that depends on this `java_library` Bazel copies or links the `data` files into the runfiles area. | -| `resources` | List of [labels](./concepts/labels); default is `[]` A list of data files to include in a Java jar. Resources may be source files or generated files. If resources are specified, they will be bundled in the jar along with the usual `.class` files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's [standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.mdx), (a "src" directory followed by a "resources" directory grandchild). If that is not found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for example, if a resource is at `\<workspace root\>/x/java/y/java/z`, the path of the resource will be `y/java/z`. This heuristic cannot be overridden, however, the `resource_strip_prefix` attribute can be used to specify a specific alternative directory for resource files. | -| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | -| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | -| `bootclasspath` | [Label](./concepts/labels); default is `None` Restricted API, do not use! | -| `exported_plugins` | List of [labels](./concepts/labels); default is `[]` The list of `java_plugin`s (e.g. annotation processors) to export to libraries that directly depend on this library. The specified list of `java_plugin`s will be applied to any library which directly depends on this library, just as if that library had explicitly declared these labels in `plugins`. | -| `exports` | List of [labels](./concepts/labels); default is `[]` Exported libraries. Listing rules here will make them available to parent rules, as if the parents explicitly depended on these rules. This is not true for regular (non-exported) `deps`. Summary: a rule *X* can access the code in *Y* if there exists a dependency path between them that begins with a `deps` edge followed by zero or more `exports` edges. Let's see some examples to illustrate this. Assume *A* depends on *B* and *B* depends on *C*. In this case C is a *transitive* dependency of A, so changing C's sources and rebuilding A will correctly rebuild everything. However A will not be able to use classes in C. To allow that, either A has to declare C in its `deps`, or B can make it easier for A (and anything that may depend on A) by declaring C in its (B's) `exports` attribute. The closure of exported libraries is available to all direct parent rules. Take a slightly different example: A depends on B, B depends on C and D, and also exports C but not D. Now A has access to C but not to D. Now, if C and D exported some libraries, C' and D' respectively, A could only access C' but not D'. Important: an exported rule is not a regular dependency. Sticking to the previous example, if B exports C and wants to also use C, it has to also list it in its own `deps`. | -| `javabuilder_jvm_flags` | List of strings; default is `[]` Restricted API, do not use! | -| `javacopts` | List of strings; default is `[]` Extra compiler options for this library. Subject to ["Make variable"](make-variables.mdx) substitution and [Bourne shell tokenization](common-definitions.html#sh-tokenization). These compiler options are passed to javac after the global compiler options. | -| `neverlink` | Boolean; default is `False` Whether this library should only be used for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of such libraries are the IDE APIs for IDE plug-ins or `tools.jar` for anything running on a standard JDK. Note that `neverlink = True` does not prevent the compiler from inlining material from this library into compilation targets that depend on it, as permitted by the Java Language Specification (e.g., `static final` constants of `String` or of primitive types). The preferred use case is therefore when the runtime library is identical to the compilation library. If the runtime library differs from the compilation library then you must ensure that it differs only in places that the JLS forbids compilers to inline (and that must hold for all future versions of the JLS). | -| `plugins` | List of [labels](./concepts/labels); default is `[]` Java compiler plugins to run at compile-time. Every `java_plugin` specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use `exported_plugins`. Resources generated by the plugin will be included in the resulting jar of this rule. | -| `proguard_specs` | List of [labels](./concepts/labels); default is `[]` Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any `android_binary` target depending on this library. The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in `android_binary`'s proguard\_specs, to ensure non-tautological merges. | -| `resource_strip_prefix` | String; default is `""` The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at `stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. | -| `runtime_deps` | List of [labels](./concepts/labels); default is `[]` Libraries to make available to the final binary or test at runtime only. Like ordinary `deps`, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both `runtime_deps` and `deps`. | - -## java\_test - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_test.bzl) - -``` -java_test(name, deps, srcs, data, resources, add_exports, add_opens, args, aspect_hints, bootclasspath, classpath_resources, compatible_with, create_executable, deploy_manifest_lines, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, javacopts, jvm_flags, launcher, licenses, local, main_class, neverlink, package_metadata, plugins, resource_strip_prefix, restricted_to, runtime_deps, shard_count, size, stamp, tags, target_compatible_with, test_class, testonly, timeout, toolchains, use_launcher, use_testrunner, visibility) -``` - -A `java_test()` rule compiles a Java test. A test is a binary wrapper around your -test code. The test runner's main method is invoked instead of the main class being compiled. - -#### Implicit output targets - -* `name.jar`: A Java archive. -* `name_deploy.jar`: A Java archive suitable - for deployment. (Only built if explicitly requested.) See the description of the - `name_deploy.jar` output from - [java\_binary](#java_binary) for more details. - -See the section on `java_binary()` arguments. This rule also -supports all [attributes common -to all test rules (\*\_test)](https://bazel.build/reference/be/common-definitions#common-attributes-tests). - -#### Examples - -``` -java_library( - name = "tests", - srcs = glob(["*.java"]), - deps = [ - "//java/com/foo/base:testResources", - "//java/com/foo/testing/util", - ], -) - -java_test( - name = "AllTests", - size = "small", - runtime_deps = [ - ":tests", - "//util/mysql", - ], -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries to be linked in to the target. See general comments about `deps` at [Typical attributes defined by most build rules](common-definitions.html#typical-attributes). | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. Source files of type `.java` are compiled. In case of generated `.java` files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the `outs` of the generating rule. You should not list the generating rule in `deps` because it is a no-op. Source files of type `.srcjar` are unpacked and compiled. (This is useful if you need to generate a set of `.java` files with a genrule.) Rules: if the rule (typically `genrule` or `filegroup`) generates any of the files listed above, they will be used the same way as described for source files. This argument is almost always required, except if a [`main_class`](#java_binary.main_class) attribute specifies a class on the runtime classpath or you specify the `runtime_deps` argument. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). | -| `resources` | List of [labels](./concepts/labels); default is `[]` A list of data files to include in a Java jar. Resources may be source files or generated files. If resources are specified, they will be bundled in the jar along with the usual `.class` files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's [standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.mdx), (a "src" directory followed by a "resources" directory grandchild). If that is not found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for example, if a resource is at `\<workspace root\>/x/java/y/java/z`, the path of the resource will be `y/java/z`. This heuristic cannot be overridden, however, the `resource_strip_prefix` attribute can be used to specify a specific alternative directory for resource files. | -| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | -| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | -| `bootclasspath` | [Label](./concepts/labels); default is `None` Restricted API, do not use! | -| `classpath_resources` | List of [labels](./concepts/labels); default is `[]` *DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)* A list of resources that must be located at the root of the java tree. This attribute's only purpose is to support third-party libraries that require that their resources be found on the classpath as exactly `"myconfig.xml"`. It is only allowed on binaries and not libraries, due to the danger of namespace conflicts. | -| `create_executable` | Boolean; default is `True` Deprecated, use `java_single_jar` instead. | -| `deploy_manifest_lines` | List of strings; default is `[]` A list of lines to add to the `META-INF/manifest.mf` file generated for the `*_deploy.jar` target. The contents of this attribute are *not* subject to ["Make variable"](make-variables.mdx) substitution. | -| `javacopts` | List of strings; default is `[]` Extra compiler options for this binary. Subject to ["Make variable"](make-variables.mdx) substitution and [Bourne shell tokenization](common-definitions.html#sh-tokenization). These compiler options are passed to javac after the global compiler options. | -| `jvm_flags` | List of strings; default is `[]` A list of flags to embed in the wrapper script generated for running this binary. Subject to [$(location)](./reference/be/make-variables#location) and ["Make variable"](make-variables.mdx) substitution, and [Bourne shell tokenization](common-definitions.html#sh-tokenization). The wrapper script for a Java binary includes a CLASSPATH definition (to find all the dependent jars) and invokes the right Java interpreter. The command line generated by the wrapper script includes the name of the main class followed by a `"$@"` so you can pass along other arguments after the classname. However, arguments intended for parsing by the JVM must be specified *before* the classname on the command line. The contents of `jvm_flags` are added to the wrapper script before the classname is listed. Note that this attribute has *no effect* on `*_deploy.jar` outputs. | -| `launcher` | [Label](./concepts/labels); default is `None` Specify a binary that will be used to run your Java program instead of the normal `bin/java` program included with the JDK. The target must be a `cc_binary`. Any `cc_binary` that implements the [Java Invocation API](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.mdx) can be specified as a value for this attribute. By default, Bazel will use the normal JDK launcher (bin/java or java.exe). The related [`--java_launcher`](./docs/user-manual#flag--java_launcher) Bazel flag affects only those `java_binary` and `java_test` targets that have *not* specified a `launcher` attribute. Note that your native (C++, SWIG, JNI) dependencies will be built differently depending on whether you are using the JDK launcher or another launcher: * If you are using the normal JDK launcher (the default), native dependencies are built as a shared library named `\{name\}_nativedeps.so`, where `\{name\}` is the `name` attribute of this java\_binary rule. Unused code is *not* removed by the linker in this configuration. * If you are using any other launcher, native (C++) dependencies are statically linked into a binary named `\{name\}_nativedeps`, where `\{name\}` is the `name` attribute of this java\_binary rule. In this case, the linker will remove any code it thinks is unused from the resulting binary, which means any C++ code accessed only via JNI may not be linked in unless that `cc_library` target specifies `alwayslink = True`. When using any launcher other than the default JDK launcher, the format of the `*_deploy.jar` output changes. See the main [java\_binary](#java_binary) docs for details. | -| `main_class` | String; default is `""` Name of class with `main()` method to use as entry point. If a rule uses this option, it does not need a `srcs=[...]` list. Thus, with this attribute one can make an executable from a Java library that already contains one or more `main()` methods. The value of this attribute is a class name, not a source file. The class must be available at runtime: it may be compiled by this rule (from `srcs`) or provided by direct or transitive dependencies (through `runtime_deps` or `deps`). If the class is unavailable, the binary will fail at runtime; there is no build-time check. | -| `neverlink` | Boolean; default is `False` | -| `plugins` | List of [labels](./concepts/labels); default is `[]` Java compiler plugins to run at compile-time. Every `java_plugin` specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use `exported_plugins`. Resources generated by the plugin will be included in the resulting jar of this rule. | -| `resource_strip_prefix` | String; default is `""` The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at `stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. | -| `runtime_deps` | List of [labels](./concepts/labels); default is `[]` Libraries to make available to the final binary or test at runtime only. Like ordinary `deps`, these will appear on the runtime classpath, but unlike them, not on the compile-time classpath. Dependencies needed only at runtime should be listed here. Dependency-analysis tools should ignore targets that appear in both `runtime_deps` and `deps`. | -| `stamp` | Integer; default is `0` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](https://bazel.build/docs/user-manual#stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](https://bazel.build/docs/user-manual#stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | -| `test_class` | String; default is `""` The Java class to be loaded by the test runner. By default, if this argument is not defined then the legacy mode is used and the test arguments are used instead. Set the `--nolegacy_bazel_java_test` flag to not fallback on the first argument. This attribute specifies the name of a Java class to be run by this test. It is rare to need to set this. If this argument is omitted, it will be inferred using the target's `name` and its source-root-relative path. If the test is located outside a known source root, Bazel will report an error if `test_class` is unset. For JUnit3, the test class needs to either be a subclass of `junit.framework.TestCase` or it needs to have a public static `suite()` method that returns a `junit.framework.Test` (or a subclass of `Test`). This attribute allows several `java_test` rules to share the same `Test` (`TestCase`, `TestSuite`, ...). Typically additional information is passed to it (e.g. via `jvm_flags=['-Dkey=value']`) so that its behavior differs in each case, such as running a different subset of the tests. This attribute also enables the use of Java tests outside the `javatests` tree. | -| `use_launcher` | Boolean; default is `True` Whether the binary should use a custom launcher. If this attribute is set to false, the [launcher](./reference/be/java.html#java_binary.launcher) attribute and the related [`--java_launcher`](./docs/user-manual#flag--java_launcher) flag will be ignored for this target. | -| `use_testrunner` | Boolean; default is `True` Use the test runner (by default `com.google.testing.junit.runner.BazelTestRunner`) class as the main entry point for a Java program, and provide the test class to the test runner as a value of `bazel.test_suite` system property. You can use this to override the default behavior, which is to use test runner for `java_test` rules, and not use it for `java_binary` rules. It is unlikely you will want to do this. One use is for `AllTest` rules that are invoked by another rule (to set up a database before running the tests, for example). The `AllTest` rule must be declared as a `java_binary`, but should still use the test runner as its main entry point. The name of a test runner class can be overridden with `main_class` attribute. | - -## java\_package\_configuration - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_package_configuration.bzl) - -``` -java_package_configuration(name, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, javacopts, output_licenses, package_metadata, packages, restricted_to, system, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Configuration to apply to a set of packages. -Configurations can be added to -`java_toolchain.javacopts`s. - -#### Example: - -``` -java_package_configuration( - name = "my_configuration", - packages = [":my_packages"], - javacopts = ["-Werror"], -) - -package_group( - name = "my_packages", - packages = [ - "//com/my/project/...", - "-//com/my/project/testing/...", - ], -) - -java_toolchain( - ..., - package_configuration = [ - ":my_configuration", - ] -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this configuration at runtime. | -| `javacopts` | List of strings; default is `[]` Java compiler flags. | -| `output_licenses` | List of strings; default is `[]` | -| `packages` | List of [labels](./concepts/labels); default is `[]` The set of `package_group`s the configuration should be applied to. | -| `system` | [Label](./concepts/labels); default is `None` Corresponds to javac's --system flag. | - -## java\_plugin - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_plugin.bzl) - -``` -java_plugin(name, deps, srcs, data, resources, add_exports, add_opens, aspect_hints, bootclasspath, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, generates_api, javabuilder_jvm_flags, javacopts, licenses, neverlink, output_licenses, package_metadata, plugins, processor_class, proguard_specs, resource_strip_prefix, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -`java_plugin` defines plugins for the Java compiler run by Bazel. The -only supported kind of plugins are annotation processors. A `java_library` or -`java_binary` rule can run plugins by depending on them via the `plugins` -attribute. A `java_library` can also automatically export plugins to libraries that -directly depend on it using -`exported_plugins`. - -#### Implicit output targets - -* `libname.jar`: A Java archive. - -Arguments are a subset of (and with identical semantics to) those of -[java\_library()](./reference/be/java.html#java_library), -except for the addition of the `processor_class` and -`generates_api` arguments. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of libraries to link into this library. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). The jars built by `java_library` rules listed in `deps` will be on the compile-time classpath of this rule. Furthermore the transitive closure of their `deps`, `runtime_deps` and `exports` will be on the runtime classpath. By contrast, targets in the `data` attribute are included in the runfiles but on neither the compile-time nor runtime classpath. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of source files that are processed to create the target. This attribute is almost always required; see exceptions below. Source files of type `.java` are compiled. In case of generated `.java` files it is generally advisable to put the generating rule's name here instead of the name of the file itself. This not only improves readability but makes the rule more resilient to future changes: if the generating rule generates different files in the future, you only need to fix one place: the `outs` of the generating rule. You should not list the generating rule in `deps` because it is a no-op. Source files of type `.srcjar` are unpacked and compiled. (This is useful if you need to generate a set of `.java` files with a genrule.) Rules: if the rule (typically `genrule` or `filegroup`) generates any of the files listed above, they will be used the same way as described for source files. Source files of type `.properties` are treated as resources. All other files are ignored, as long as there is at least one file of a file type described above. Otherwise an error is raised. This argument is almost always required, except if you specify the `runtime_deps` argument. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical-attributes). When building a `java_library`, Bazel doesn't put these files anywhere; if the `data` files are generated files then Bazel generates them. When building a test that depends on this `java_library` Bazel copies or links the `data` files into the runfiles area. | -| `resources` | List of [labels](./concepts/labels); default is `[]` A list of data files to include in a Java jar. Resources may be source files or generated files. If resources are specified, they will be bundled in the jar along with the usual `.class` files produced by compilation. The location of the resources inside of the jar file is determined by the project structure. Bazel first looks for Maven's [standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.mdx), (a "src" directory followed by a "resources" directory grandchild). If that is not found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for example, if a resource is at `\<workspace root\>/x/java/y/java/z`, the path of the resource will be `y/java/z`. This heuristic cannot be overridden, however, the `resource_strip_prefix` attribute can be used to specify a specific alternative directory for resource files. | -| `add_exports` | List of strings; default is `[]` Allow this library to access the given `module` or `package`. This corresponds to the javac and JVM --add-exports= flags. | -| `add_opens` | List of strings; default is `[]` Allow this library to reflectively access the given `module` or `package`. This corresponds to the javac and JVM --add-opens= flags. | -| `bootclasspath` | [Label](./concepts/labels); default is `None` Restricted API, do not use! | -| `generates_api` | Boolean; default is `False` This attribute marks annotation processors that generate API code. If a rule uses an API-generating annotation processor, other rules depending on it can refer to the generated code only if their compilation actions are scheduled after the generating rule. This attribute instructs Bazel to introduce scheduling constraints when --java\_header\_compilation is enabled. *WARNING: This attribute affects build performance, use it only if necessary.* | -| `javabuilder_jvm_flags` | List of strings; default is `[]` Restricted API, do not use! | -| `javacopts` | List of strings; default is `[]` Extra compiler options for this library. Subject to ["Make variable"](make-variables.mdx) substitution and [Bourne shell tokenization](common-definitions.html#sh-tokenization). These compiler options are passed to javac after the global compiler options. | -| `neverlink` | Boolean; default is `False` Whether this library should only be used for compilation and not at runtime. Useful if the library will be provided by the runtime environment during execution. Examples of such libraries are the IDE APIs for IDE plug-ins or `tools.jar` for anything running on a standard JDK. Note that `neverlink = True` does not prevent the compiler from inlining material from this library into compilation targets that depend on it, as permitted by the Java Language Specification (e.g., `static final` constants of `String` or of primitive types). The preferred use case is therefore when the runtime library is identical to the compilation library. If the runtime library differs from the compilation library then you must ensure that it differs only in places that the JLS forbids compilers to inline (and that must hold for all future versions of the JLS). | -| `output_licenses` | List of strings; default is `[]` | -| `plugins` | List of [labels](./concepts/labels); default is `[]` Java compiler plugins to run at compile-time. Every `java_plugin` specified in this attribute will be run whenever this rule is built. A library may also inherit plugins from dependencies that use `exported_plugins`. Resources generated by the plugin will be included in the resulting jar of this rule. | -| `processor_class` | String; default is `""` The processor class is the fully qualified type of the class that the Java compiler should use as entry point to the annotation processor. If not specified, this rule will not contribute an annotation processor to the Java compiler's annotation processing, but its runtime classpath will still be included on the compiler's annotation processor path. (This is primarily intended for use by [Error Prone plugins](https://errorprone.info/docs/plugins), which are loaded from the annotation processor path using [java.util.ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.mdx).) | -| `proguard_specs` | List of [labels](./concepts/labels); default is `[]` Files to be used as Proguard specification. These will describe the set of specifications to be used by Proguard. If specified, they will be added to any `android_binary` target depending on this library. The files included here must only have idempotent rules, namely -dontnote, -dontwarn, assumenosideeffects, and rules that start with -keep. Other options can only appear in `android_binary`'s proguard\_specs, to ensure non-tautological merges. | -| `resource_strip_prefix` | String; default is `""` The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory. If not specified (the default), the path of resource file is determined according to the same logic as the Java package of source files. For example, a source file at `stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. | - -## java\_runtime - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_runtime.bzl) - -``` -java_runtime(name, srcs, aspect_hints, compatible_with, default_cds, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hermetic_srcs, hermetic_static_libs, java, java_home, lib_ct_sym, lib_modules, output_licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, version, visibility) -``` - -Specifies the configuration for a Java runtime. - -#### Example: - -``` -java_runtime( - name = "jdk-9-ea+153", - srcs = glob(["jdk9-ea+153/**"]), - java_home = "jdk9-ea+153", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` All files in the runtime. | -| `default_cds` | [Label](./concepts/labels); default is `None` Default CDS archive for hermetic `java_runtime`. When hermetic is enabled for a `java_binary` target the `java_runtime` default CDS is packaged in the hermetic deploy JAR. | -| `hermetic_srcs` | List of [labels](./concepts/labels); default is `[]` Files in the runtime needed for hermetic deployments. | -| `hermetic_static_libs` | List of [labels](./concepts/labels); default is `[]` The libraries that are statically linked with the launcher for hermetic deployments | -| `java` | [Label](./concepts/labels); default is `None` The path to the java executable. | -| `java_home` | String; default is `""` The path to the root of the runtime. Subject to ["Make" variable](./reference/be/make-variables) substitution. If this path is absolute, the rule denotes a non-hermetic Java runtime with a well-known path. In that case, the `srcs` and `java` attributes must be empty. | -| `lib_ct_sym` | [Label](./concepts/labels); default is `None` The lib/ct.sym file needed for compilation with `--release`. If not specified and there is exactly one file in `srcs` whose path ends with `/lib/ct.sym`, that file is used. | -| `lib_modules` | [Label](./concepts/labels); default is `None` The lib/modules file needed for hermetic deployments. | -| `output_licenses` | List of strings; default is `[]` | -| `version` | Integer; default is `0` The feature version of the Java runtime. I.e., the integer returned by `Runtime.version().feature()`. | - -## java\_single\_jar - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/java_single_jar.bzl) - -``` -java_single_jar(name, deps, aspect_hints, compatible_with, compress, deploy_env, deploy_manifest_lines, deprecation, exclude_build_data, exec_compatible_with, exec_group_compatible_with, exec_properties, features, multi_release, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Collects Java dependencies and jar files into a single jar -`java\_single\_jar` collects Java dependencies and jar files into a single jar. -This is similar to java\_binary with everything related to executables disabled, -and provides an alternative to the java\_binary "deploy jar hack". -## Example -```skylark -load("//tools/build\_defs/java\_single\_jar:java\_single\_jar.bzl", "java\_single\_jar") -java\_single\_jar( -name = "my\_single\_jar", -deps = [ -"//java/com/google/foo", -"//java/com/google/bar", -], -) -``` -Outputs: -\{name\}.jar: A single jar containing all of the inputs. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The Java targets (including java\_import and java\_library) to collect transitive dependencies from. Runtime dependencies are collected via deps, exports, and runtime\_deps. Resources are also collected. Native cc\_library or java\_wrap\_cc dependencies are not. | -| `compress` | String; default is `"preserve"` Whether to always deflate ("yes"), always store ("no"), or pass through unmodified ("preserve"). The default is "preserve", and is the most efficient option -- no extra work is done to inflate or deflate. | -| `deploy_env` | List of [labels](./concepts/labels); default is `[]` A list of `java\_binary` or `java\_single\_jar` targets which represent the deployment environment for this binary. Set this attribute when building a plugin which will be loaded by another `java\_binary`. `deploy\_env` dependencies are excluded from the jar built by this rule. | -| `deploy_manifest_lines` | List of strings; default is `[]` A list of lines to add to the `META-INF/manifest.mf` file. | -| `exclude_build_data` | Boolean; default is `True` Whether to omit the build-data.properties file generated by default. | -| `multi_release` | Boolean; default is `True` Whether to enable Multi-Release output jars. | - -## java\_toolchain - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_toolchain.bzl) - -``` -java_toolchain(name, android_lint_data, android_lint_jvm_opts, android_lint_opts, android_lint_package_configuration, android_lint_runner, aspect_hints, bootclasspath, compatible_javacopts, compatible_with, deprecation, deps_checker, exec_compatible_with, exec_group_compatible_with, exec_properties, features, forcibly_disable_header_compilation, genclass, header_compiler, header_compiler_builtin_processors, header_compiler_direct, ijar, jacocorunner, java_runtime, javabuilder, javabuilder_data, javabuilder_jvm_opts, javac_supports_multiplex_workers, javac_supports_worker_cancellation, javac_supports_worker_multiplex_sandboxing, javac_supports_workers, javacopts, jspecify_implicit_deps, jspecify_javacopts, jspecify_packages, jspecify_processor, jspecify_processor_class, jspecify_stubs, jvm_opts, licenses, misc, oneversion, oneversion_allowlist, oneversion_allowlist_for_tests, oneversion_whitelist, package_configuration, package_metadata, proguard_allowlister, reduced_classpath_incompatible_processors, restricted_to, singlejar, source_version, tags, target_compatible_with, target_version, testonly, timezone_data, toolchains, tools, turbine_data, turbine_jvm_opts, visibility, xlint) -``` - -Specifies the configuration for the Java compiler. Which toolchain to be used can be changed through -the --java\_toolchain argument. Normally you should not write those kind of rules unless you want to -tune your Java compiler. - -#### Examples - -A simple example would be: - -``` -java_toolchain( - name = "toolchain", - source_version = "7", - target_version = "7", - bootclasspath = ["//tools/jdk:bootclasspath"], - xlint = [ "classfile", "divzero", "empty", "options", "path" ], - javacopts = [ "-g" ], - javabuilder = ":JavaBuilder_deploy.jar", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `android_lint_data` | List of [labels](./concepts/labels); default is `[]` Labels of tools available for label-expansion in android\_lint\_jvm\_opts. | -| `android_lint_jvm_opts` | List of strings; default is `[]` The list of arguments for the JVM when invoking Android Lint. | -| `android_lint_opts` | List of strings; default is `[]` The list of Android Lint arguments. | -| `android_lint_package_configuration` | List of [labels](./concepts/labels); default is `[]` Android Lint Configuration that should be applied to the specified package groups. | -| `android_lint_runner` | [Label](./concepts/labels); default is `None` Label of the Android Lint runner, if any. | -| `bootclasspath` | List of [labels](./concepts/labels); default is `[]` The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. | -| `compatible_javacopts` | null; default is `\{\}` Internal API, do not use! | -| `deps_checker` | [Label](./concepts/labels); default is `None` Label of the ImportDepsChecker deploy jar. | -| `forcibly_disable_header_compilation` | Boolean; default is `False` Overrides --java\_header\_compilation to disable header compilation on platforms that do not support it, e.g. JDK 7 Bazel. | -| `genclass` | [Label](./concepts/labels); default is `None` Label of the GenClass deploy jar. | -| `header_compiler` | [Label](./concepts/labels); default is `None` Label of the header compiler. Required if --java\_header\_compilation is enabled. | -| `header_compiler_builtin_processors` | List of strings; default is `[]` Internal API, do not use! | -| `header_compiler_direct` | [Label](./concepts/labels); default is `None` Optional label of the header compiler to use for direct classpath actions that do not include any API-generating annotation processors. This tool does not support annotation processing. | -| `ijar` | [Label](./concepts/labels); default is `None` Label of the ijar executable. | -| `jacocorunner` | [Label](./concepts/labels); default is `None` Label of the JacocoCoverageRunner deploy jar. | -| `java_runtime` | [Label](./concepts/labels); default is `None` The java\_runtime to use with this toolchain. It defaults to java\_runtime in execution configuration. | -| `javabuilder` | [Label](./concepts/labels); default is `None` Label of the JavaBuilder deploy jar. | -| `javabuilder_data` | List of [labels](./concepts/labels); default is `[]` Labels of data available for label-expansion in javabuilder\_jvm\_opts. | -| `javabuilder_jvm_opts` | List of strings; default is `[]` The list of arguments for the JVM when invoking JavaBuilder. | -| `javac_supports_multiplex_workers` | Boolean; default is `True` True if JavaBuilder supports running as a multiplex persistent worker, false if it doesn't. | -| `javac_supports_worker_cancellation` | Boolean; default is `True` True if JavaBuilder supports cancellation of persistent workers, false if it doesn't. | -| `javac_supports_worker_multiplex_sandboxing` | Boolean; default is `False` True if JavaBuilder supports running as a multiplex persistent worker with sandboxing, false if it doesn't. | -| `javac_supports_workers` | Boolean; default is `True` True if JavaBuilder supports running as a persistent worker, false if it doesn't. | -| `javacopts` | List of strings; default is `[]` The list of extra arguments for the Java compiler. Please refer to the Java compiler documentation for the extensive list of possible Java compiler flags. | -| `jspecify_implicit_deps` | [Label](./concepts/labels); default is `None` Experimental, do not use! | -| `jspecify_javacopts` | List of strings; default is `[]` Experimental, do not use! | -| `jspecify_packages` | List of [labels](./concepts/labels); default is `[]` Experimental, do not use! | -| `jspecify_processor` | [Label](./concepts/labels); default is `None` Experimental, do not use! | -| `jspecify_processor_class` | String; default is `""` Experimental, do not use! | -| `jspecify_stubs` | List of [labels](./concepts/labels); default is `[]` Experimental, do not use! | -| `jvm_opts` | List of strings; default is `[]` The list of arguments for the JVM when invoking the Java compiler. Please refer to the Java virtual machine documentation for the extensive list of possible flags for this option. | -| `misc` | List of strings; default is `[]` Deprecated: use javacopts instead | -| `oneversion` | [Label](./concepts/labels); default is `None` Label of the one-version enforcement binary. | -| `oneversion_allowlist` | [Label](./concepts/labels); default is `None` Label of the one-version allowlist. | -| `oneversion_allowlist_for_tests` | [Label](./concepts/labels); default is `None` Label of the one-version allowlist for tests. | -| `oneversion_whitelist` | [Label](./concepts/labels); default is `None` Deprecated: use oneversion\_allowlist instead | -| `package_configuration` | List of [labels](./concepts/labels); default is `[]` Configuration that should be applied to the specified package groups. | -| `proguard_allowlister` | [Label](./concepts/labels); default is `"@bazel_tools//tools/jdk:proguard_whitelister"` Label of the Proguard allowlister. | -| `reduced_classpath_incompatible_processors` | List of strings; default is `[]` Internal API, do not use! | -| `singlejar` | [Label](./concepts/labels); default is `None` Label of the SingleJar deploy jar. | -| `source_version` | String; default is `""` The Java source version (e.g., '6' or '7'). It specifies which set of code structures are allowed in the Java source code. | -| `target_version` | String; default is `""` The Java target version (e.g., '6' or '7'). It specifies for which Java runtime the class should be build. | -| `timezone_data` | [Label](./concepts/labels); default is `None` Label of a resource jar containing timezone data. If set, the timezone data is added as an implicitly runtime dependency of all java\_binary rules. | -| `tools` | List of [labels](./concepts/labels); default is `[]` Labels of tools available for label-expansion in jvm\_opts. | -| `turbine_data` | List of [labels](./concepts/labels); default is `[]` Labels of data available for label-expansion in turbine\_jvm\_opts. | -| `turbine_jvm_opts` | List of strings; default is `[]` The list of arguments for the JVM when invoking turbine. | -| `xlint` | List of strings; default is `[]` The list of warning to add or removes from default list. Precedes it with a dash to removes it. Please see the Javac documentation on the -Xlint options for more information. | \ No newline at end of file diff --git a/reference/be/make-variables.mdx b/reference/be/make-variables.mdx deleted file mode 100644 index 098a8d6..0000000 --- a/reference/be/make-variables.mdx +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: 'make-variables' ---- - - -* [Use](#use) -* [Predefined variables](#predefined_variables) -* [Predefined genrule variables](#predefined_genrule_variables) -* [Predefined source/output path variables](#predefined_label_variables) -* [Custom variables](#custom_variables) - -"Make" variables are a special class of expandable string variables available -to attributes marked as *"Subject to 'Make variable' substitution"*. - -These can be used, for example, to inject specific toolchain paths into -user-constructed build actions. - -Bazel provides both *predefined* variables, which are available to all -targets, and *custom* variables, which are defined in dependency targets -and only available to targets that depend on them. - -The reason for the term "Make" is historical: the syntax and semantics of -these variables were originally intended to match [GNU -Make](https://www.gnu.org/software/make/manual/html_node/Using-Variables.mdx). - -## Use - -Attributes marked as *"Subject to 'Make variable' substitution"* can -reference the "Make" variable `FOO` as follows: - -`my_attr = "prefix $(FOO) suffix"` - -In other words, any substring matching `$(FOO)` gets expanded -to `FOO`'s value. If that value is `"bar"`, the final -string becomes: - -`my_attr = "prefix bar suffix"` - -If `FOO` doesn't correspond to a variable known to the consuming -target, Bazel fails with an error. - -"Make" variables whose names are non-letter symbols, such as -`@`, can also be referenced using only a dollar sign, without -the parentheses. For example: - -`my_attr = "prefix $@ suffix"` - -To write `$` as a string literal (i.e. to prevent variable -expansion), write `$$`. - -## Predefined variables - -Predefined "Make" variables can be referenced by any attribute marked as -*"Subject to 'Make variable' substitution"* on any target. - -To see the list of these variables and their values for a given set of build -options, run - -`bazel info --show_make_env [build options]` - -and look at the top output lines with capital letters. - -[See an example of predefined variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-variables). - -**Toolchain option variables** - -* `COMPILATION_MODE`: - `fastbuild`, `dbg`, or `opt`. ([more - details](https://bazel.build/docs/user-manual#flag--compilation_mode)) - -**Path variables** - -* `BINDIR`: The base of the generated binary tree for the target - architecture. - - Note that a different tree may be used for programs that run during the - build on the host architecture, to support cross-compiling. - - If you want to run a tool from within a `genrule`, the - recommended way to get its path is `$(execpath toolname)`, - where *toolname* must be listed in the `genrule`'s - `tools` attribute. -* `GENDIR`: - The base of the generated code tree for the target architecture. - -**Machine architecture variables** - -* `TARGET_CPU`: - The target architecture's CPU, e.g. `k8`. - -## Predefined genrule variables - -The following are specially available to `genrule`'s -`cmd` attribute and are -generally important for making that attribute work. - -[See an example of predefined genrule variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-genrule-variables). - -* `OUTS`: The `genrule`'s `outs` list. If you have - only one output file, you can also use `$@`. -* `SRCS`: The `genrule`'s `srcs` list (or more - precisely: the path names of the files corresponding to labels in the - `srcs` list). - If you have only one source file, you can also use `$<`. -* `<`: `SRCS`, if it is a single file. Else triggers - a build error. -* `@`: `OUTS`, if it is a single file. Else triggers a - build error. -* `RULEDIR`: The output directory of the target, that is, the - directory corresponding to the name of the package containing the target - under the `genfiles` or `bin` tree. For - `//my/pkg:my_genrule` this always ends in `my/pkg`, - even if `//my/pkg:my_genrule`'s outputs are in subdirectories. -* `@D`: The output directory. If - [outs](./reference/be/general.html#genrule.outs) has one entry, - this expands to the directory containing that file. If it has multiple - entries, this expands to the package's root directory in the - `genfiles` tree, *even if all output files are in the same - subdirectory*! - - **Note:** Use `RULEDIR` over `@D` because - `RULEDIR` has simpler semantics and behaves the same way - regardless of the number of output files. - - If the genrule needs to generate temporary intermediate files (perhaps as - a result of using some other tool like a compiler), it should attempt to - write them to `@D` (although `/tmp` will also - be writable) and remove them before finishing. - - Especially avoid writing to directories containing inputs. They may be on - read-only filesystems. Even if not, doing so would trash the source tree. - -**Note:** If the filenames corresponding to the input labels or the output -filenames contain spaces, `'`, or other special characters (or your -genrule is part of a Starlark macro which downstream users may invoke on such -files), then `$(SRCS)` and `$(OUTS)` are not suitable -for interpolation into a command line, as they do not have the semantics that -`"$\{@\}"` would in Bash. - -One workaround is to convert to a Bash array, with - -``` -mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion' -$(SRC) -genrule_srcs_expansion -) -``` - -and then use `"$$\{SRCS[@]\}"` in subsequent command lines in place -of `$(SRCS)`. A more robust option is to write a Starlark rule -instead. - -## Predefined source/output path variables - -The predefined variables `execpath`, `execpaths`, -`rootpath`, `rootpaths`, `location`, and -`locations` take label parameters (e.g. `$(execpath -//foo:bar)`) and substitute the file paths denoted by that label. - -For source files, this is the path relative to your workspace root. -For files that are outputs of rules, this is the file's *output path* -(see the explanation of *output files* below). - -[See an example of predefined path variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-path-variables). - -* `execpath`: Denotes the path beneath the - [execroot](./docs/output_directories) - where Bazel runs build actions. - - In the above example, Bazel runs all build actions in the directory linked - by the `bazel-myproject` symlink in your workspace root. The - source file `empty.source` is linked at the path - `bazel-myproject/testapp/empty.source`. So its exec path (which - is the subpath below the root) is `testapp/empty.source`. This - is the path build actions can use to find the file. - - Output files are staged similarly, but are also prefixed with the subpath - `bazel-out/cpu-compilation_mode/bin` (or for the outputs of - tools: `bazel-out/cpu-opt-exec-hash/bin`). In the above example, - `//testapp:app` is a tool because it appears in - `show_app_output`'s `tools` attribute. - So its output file `app` is written to - `bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app`. - The exec path is thus `bazel-out/cpu-opt-exec-hash/bin/testapp/app`. This extra prefix - makes it possible to build the same target for, say, two different CPUs in - the same build without the results clobbering each other. - - The label passed to this variable must represent exactly one file. For - labels representing source files, this is automatically true. For labels - representing rules, the rule must generate exactly one output. If this is - false or the label is malformed, the build fails with an error. -* `rootpath`: Denotes the path that a built binary can use to - find a dependency at runtime relative to the subdirectory of its runfiles - directory corresponding to the main repository. - **Note:** This only works if [`--enable_runfiles`](./reference/command-line-reference#flag--enable_runfiles) is enabled, which is not the case on - Windows by default. Use `rlocationpath` instead for - cross-platform support. - - This is similar to `execpath` but strips the configuration - prefixes described above. In the example from above this means both - `empty.source` and `app` use pure workspace-relative - paths: `testapp/empty.source` and `testapp/app`. - - The `rootpath` of a file in an external repository - `repo` will start with `../repo/`, followed by the - repository-relative path. - - This has the same "one output only" requirements as `execpath`. -* `rlocationpath`: The path a built binary can pass to the `Rlocation` function of a runfiles library to find a dependency at - runtime, either in the runfiles directory (if available) or using the - runfiles manifest. - - This is similar to `rootpath` in that it does not contain - configuration prefixes, but differs in that it always starts with the - name of the repository. In the example from above this means that `empty.source` and `app` result in the following - paths: `myproject/testapp/empty.source` and `myproject/testapp/app`. - - The `rlocationpath` of a file in an external repository - `repo` will start with `repo/`, followed by the - repository-relative path. - - Passing this path to a binary and resolving it to a file system path using - the runfiles libraries is the preferred approach to find dependencies at - runtime. Compared to `rootpath`, it has the advantage that it - works on all platforms and even if the runfiles directory is not - available. - - This has the same "one output only" requirements as `execpath`. -* `location`: A synonym for either `execpath` or - `rootpath`, depending on the attribute being expanded. This is - legacy pre-Starlark behavior and not recommended unless you really know what - it does for a particular rule. See [#2475](https://github.com/bazelbuild/bazel/issues/2475#issuecomment-339318016) - for details. - -`execpaths`, `rootpaths`, `rlocationpaths`, -and `locations` are the plural variations of `execpath`, -`rootpath`, `rlocationpath`, and`location`, -respectively. They support labels producing multiple outputs, in which case -each output is listed separated by a space. Zero-output rules and malformed -labels produce build errors. - -All referenced labels must appear in the consuming target's `srcs`, -output files, or `deps`. Otherwise the build fails. C++ targets can -also reference labels in `data`. - -Labels don't have to be in canonical form: `foo`, `:foo` -and `//somepkg:foo` are all fine. - -## Custom variables - -Custom "Make" variables can be referenced by any attribute marked as -*"Subject to 'Make variable' substitution"*, but only on targets that -depend on other targets that *define* these variables. - -As best practice all variables should be custom unless there's a really good -reason to bake them into core Bazel. This saves Bazel from having to load -potentially expensive dependencies to supply variables consuming tarets may -not care about. - -**C++ toolchain variables** - -The following are defined in C++ toolchain rules and available to any rule -that sets `toolchains = -["@bazel_tools//tools/cpp:toolchain_type"]` -Some rules, like `java_binary`, implicitly -include the C++ toolchain in their rule definition. They inherit these variables -automatically. - -The built-in C++ rules are much more sophisticated than "run the compiler on -it". In order to support compilation modes as diverse as \*SAN, ThinLTO, -with/without modules, and carefully optimized binaries at the same time as -fast running tests on multiple platforms, the built-in rules go to great -lengths to ensure the correct inputs, outputs, and command-line flags are set -on each of potentially multiple internally generated actions. - -These variables are a fallback mechanism to be used by language experts in -rare cases. If you are tempted to use them, please [contact the Bazel devs](https://bazel.build/help) first. - -* `ABI`: The C++ ABI version. -* `AR`: The "ar" command from crosstool. -* `C_COMPILER`: - The C/C++ compiler identifier, e.g. `llvm`. -* `CC`: The C and C++ compiler command. - - We strongly recommended always using `CC_FLAGS` in - combination with `CC`. Fail to do so at your own risk. -* `CC_FLAGS`: A minimal set of flags for the C/C++ - compiler to be usable by genrules. In particular, this contains flags to - select the correct architecture if `CC` supports multiple - architectures. -* `DUMPBIN`: Microsoft COFF Binary File Dumper (dumpbin.exe) from - from Microsoft Visual Studio. -* `NM`: The "nm" command from crosstool. -* `OBJCOPY`: The objcopy command from the same suite as the C/C++ - compiler. -* `STRIP`: The strip command from the same suite as the C/C++ - compiler. - -**Java toolchain variables** - -The following are defined in Java toolchain rules and available to any rule -that sets `toolchains = -["@rules_java//toolchains:current_java_runtime"]` (or -`"@rules_java//toolchains:current_host_java_runtime"` -for the host toolchain equivalent). - -Most of the tools in the JDK should not be used directly. The built-in Java -rules use much more sophisticated approaches to Java compilation and packaging -than upstream tools can express, such as interface Jars, header interface -Jars, and highly optimized Jar packaging and merging implementations. - -These variables are a fallback mechanism to be used by language experts in -rare cases. If you are tempted to use them, please [contact the Bazel devs](https://bazel.build/help) first. - -* `JAVA`: The "java" command (a Java virtual - machine). Avoid this, and use a `java_binary` rule - instead where possible. May be a relative path. If you must change - directories before invoking `java`, you need to capture the - working directory before changing it. -* `JAVABASE`: The base directory containing the - Java utilities. May be a relative path. It will have a "bin" - subdirectory. - -**Starlark-defined variables** - -Rule and [toolchain](./docs/toolchains) writers can define -completely custom variables by returning a -[TemplateVariableInfo](./rules/lib/TemplateVariableInfo) -provider. Any rules depending on these through the -`toolchains` attribute can then read their values: - -[See an example of Starlark-defined variables](https://github.com/bazelbuild/examples/tree/main/make-variables#custom-starlark-defined-variables). \ No newline at end of file diff --git a/reference/be/objective-c.mdx b/reference/be/objective-c.mdx deleted file mode 100644 index 32b38c1..0000000 --- a/reference/be/objective-c.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: 'objective-c' ---- - - -## Rules - -* [objc\_import](#objc_import) -* [objc\_library](#objc_library) - -## objc\_import - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_import.bzl) - -``` -objc_import(name, deps, hdrs, alwayslink, archives, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, includes, package_metadata, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) -``` - -This rule encapsulates an already-compiled static library in the form of an -`.a` file. It also allows exporting headers and resources using the same -attributes supported by `objc_library`. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of targets that this target depend on. | -| `hdrs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ header files published by this library to be included by sources in dependent rules. These headers describe the public interface for the library and will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the srcs attribute instead. These will be compiled separately from the source if modules are enabled. | -| `alwayslink` | Boolean; default is `False` If 1, any bundle or binary that depends (directly or indirectly) on this library will link in all the object files for the files listed in `srcs` and `non_arc_srcs`, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. | -| `archives` | List of [labels](./concepts/labels); required The list of `.a` files provided to Objective-C targets that depend on this target. | -| `includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets. This is to support third party and open-sourced libraries that do not specify the entire workspace path in their `#import/#include` statements. The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. `blaze-genfiles/pkg/includedir` and `blaze-out/pkg/includedir`) are included in addition to the actual client root. Unlike [COPTS](./reference/be/objective-c.html#objc_library.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-iquote" flags to [COPTS](./reference/be/objective-c.html#objc_library.copts) instead. | -| `sdk_dylibs` | List of strings; default is `[]` Names of SDK .dylib libraries to link with. For instance, "libz" or "libarchive". "libc++" is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are used. | -| `sdk_frameworks` | List of strings; default is `[]` Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). When linking a top level Apple binary, all SDK frameworks listed in that binary's transitive dependency graph are linked. | -| `sdk_includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets, where each path is relative to `$(SDKROOT)/usr/include`. | -| `textual_hdrs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ files that are included as headers by source files in this rule or by users of this library. Unlike hdrs, these will not be compiled separately from the sources. | -| `weak_sdk_frameworks` | List of strings; default is `[]` Names of SDK frameworks to weakly link with. For instance, "MediaAccessibility". In difference to regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause an error if they are not present at runtime. | - -## objc\_library - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_library.bzl) - -``` -objc_library(name, deps, srcs, data, hdrs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, enable_modules, exec_compatible_with, exec_group_compatible_with, exec_properties, features, implementation_deps, includes, linkopts, module_map, module_name, non_arc_srcs, package_metadata, pch, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, stamp, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) -``` - -This rule produces a static library from the given Objective-C source files. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of targets that this target depend on. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ source and header files, and/or (`.s`, `.S`, or `.asm`) assembly source files, that are processed to create the library target. These are your checked-in files, plus any generated files. Source files are compiled into .o files with Clang. Header files may be included/imported by any source or header in the srcs attribute of this target, but not by headers in hdrs or any targets that depend on this rule. Additionally, precompiled .o files may be given as srcs. Be careful to ensure consistency in the architecture of provided .o files and that of the build to avoid missing symbol linker errors. | -| `hdrs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ header files published by this library to be included by sources in dependent rules. These headers describe the public interface for the library and will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the srcs attribute instead. These will be compiled separately from the source if modules are enabled. | -| `alwayslink` | Boolean; default is `False` If 1, any bundle or binary that depends (directly or indirectly) on this library will link in all the object files for the files listed in `srcs` and `non_arc_srcs`, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. | -| `conlyopts` | List of strings; default is `[]` Extra flags to pass to the compiler for C files. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). These flags will only apply to this target, and not those upon which it depends, or those which depend on it. Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and added to the header search paths for the associated Xcode target. | -| `copts` | List of strings; default is `[]` Extra flags to pass to the compiler. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). These flags will only apply to this target, and not those upon which it depends, or those which depend on it. Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and added to the header search paths for the associated Xcode target. | -| `cxxopts` | List of strings; default is `[]` Extra flags to pass to the compiler for Objective-C++ and C++ files. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). These flags will only apply to this target, and not those upon which it depends, or those which depend on it. Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and added to the header search paths for the associated Xcode target. | -| `defines` | List of strings; default is `[]` Extra `-D` flags to pass to the compiler. They should be in the form `KEY=VALUE` or simply `KEY` and are passed not only to the compiler for this target (as `copts` are) but also to all `objc_` dependers of this target. Subject to ["Make variable"](./reference/be/make-variables) substitution and [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization). | -| `enable_modules` | Boolean; default is `False` Enables clang module support (via -fmodules). Setting this to 1 will allow you to @import system headers and other targets: @import UIKit; @import path\_to\_package\_target; | -| `implementation_deps` | List of [labels](./concepts/labels); default is `[]` The list of other libraries that the library target depends on. Unlike with `deps`, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with `implementation_deps` are still linked in binary targets that depend on this library. | -| `includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets. This is to support third party and open-sourced libraries that do not specify the entire workspace path in their `#import/#include` statements. The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. `blaze-genfiles/pkg/includedir` and `blaze-out/pkg/includedir`) are included in addition to the actual client root. Unlike [COPTS](./reference/be/objective-c.html#objc_library.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-iquote" flags to [COPTS](./reference/be/objective-c.html#objc_library.copts) instead. | -| `linkopts` | List of strings; default is `[]` Extra flags to pass to the linker. | -| `module_map` | [Label](./concepts/labels); default is `None` custom Clang module map for this target. Use of a custom module map is discouraged. Most users should use module maps generated by Bazel. If specified, Bazel will not generate a module map for this target, but will pass the provided module map to the compiler. | -| `module_name` | String; default is `""` Sets the module name for this target. By default the module name is the target path with all special symbols replaced by \_, e.g. //foo/baz:bar can be imported as foo\_baz\_bar. | -| `non_arc_srcs` | List of [labels](./concepts/labels); default is `[]` The list of Objective-C files that are processed to create the library target that DO NOT use ARC. The files in this attribute are treated very similar to those in the srcs attribute, but are compiled without ARC enabled. | -| `pch` | [Label](./concepts/labels); default is `None` Header file to prepend to every source file being compiled (both arc and non-arc). Use of pch files is actively discouraged in BUILD files, and this should be considered deprecated. Since pch files are not actually precompiled this is not a build-speed enhancement, and instead is just a global dependency. From a build efficiency point of view you are actually better including what you need directly in your sources where you need it. | -| `sdk_dylibs` | List of strings; default is `[]` Names of SDK .dylib libraries to link with. For instance, "libz" or "libarchive". "libc++" is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are used. | -| `sdk_frameworks` | List of strings; default is `[]` Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). When linking a top level Apple binary, all SDK frameworks listed in that binary's transitive dependency graph are linked. | -| `sdk_includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets, where each path is relative to `$(SDKROOT)/usr/include`. | -| `stamp` | Boolean; default is `False` | -| `textual_hdrs` | List of [labels](./concepts/labels); default is `[]` The list of C, C++, Objective-C, and Objective-C++ files that are included as headers by source files in this rule or by users of this library. Unlike hdrs, these will not be compiled separately from the sources. | -| `weak_sdk_frameworks` | List of strings; default is `[]` Names of SDK frameworks to weakly link with. For instance, "MediaAccessibility". In difference to regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause an error if they are not present at runtime. | \ No newline at end of file diff --git a/reference/be/overview.mdx b/reference/be/overview.mdx deleted file mode 100644 index 1e07111..0000000 --- a/reference/be/overview.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: 'overview' ---- - - -## Concepts and terminology - -* [Common definitions](./reference/be/common-definitions) - + [Bourne shell tokenization](./reference/be/common-definitions#sh-tokenization) - + [Label expansion](./reference/be/common-definitions#label-expansion) - + [Typical attributes for most rules](./reference/be/common-definitions#typical-attributes) - + [Common attributes for all rules](./reference/be/common-definitions#common-attributes) - + [Common attributes for tests](./reference/be/common-definitions#common-attributes-tests) - + [Common attributes for binaries](./reference/be/common-definitions#common-attributes-binaries) - + [Configurable attributes](./reference/be/common-definitions#configurable-attributes) - + [Implicit output targets](./reference/be/common-definitions#implicit-outputs) -* ["Make" variables](./reference/be/make-variables) - + [Use](./reference/be/make-variables#use) - -## Functions - -* [package](./reference/be/functions.html#package) -* [package\_group](./reference/be/functions.html#package_group) -* [exports\_files](./reference/be/functions.html#exports_files) -* [glob](./reference/be/functions.html#glob) -* [select](./reference/be/functions.html#select) -* [workspace](./rules/lib/globals/workspace#workspace) - -## Rules - -Native rules ship with the Bazel binary and do not require a `load` statement. -Native rules are available globally in BUILD files. In .bzl files, you can find them in -the `native` module. -For non-native Starlark rules that ship separately from Bazel, see the list of -[recommended rules](./rules/rules#recommended-rules). - -### Language-specific native rules - -| Language | Flags | Binary rules | Library rules | Test rules | Other rules | -| --- | --- | --- | --- | --- | --- | -| C / C++ | | [cc\_binary](c-cpp.html#cc_binary) | [cc\_import](c-cpp.html#cc_import) [cc\_library](c-cpp.html#cc_library) [cc\_shared\_library](c-cpp.html#cc_shared_library) [cc\_static\_library](c-cpp.html#cc_static_library) | [cc\_test](c-cpp.html#cc_test) | [cc\_toolchain](c-cpp.html#cc_toolchain) [fdo\_prefetch\_hints](c-cpp.html#fdo_prefetch_hints) [fdo\_profile](c-cpp.html#fdo_profile) [memprof\_profile](c-cpp.html#memprof_profile) [propeller\_optimize](c-cpp.html#propeller_optimize) | -| Java | | [java\_binary](java.html#java_binary) | [java\_import](java.html#java_import) [java\_library](java.html#java_library) | [java\_test](java.html#java_test) | [java\_package\_configuration](java.html#java_package_configuration) [java\_plugin](java.html#java_plugin) [java\_runtime](java.html#java_runtime) [java\_single\_jar](java.html#java_single_jar) [java\_toolchain](java.html#java_toolchain) | -| Objective-C | | | [objc\_import](objective-c.html#objc_import) [objc\_library](objective-c.html#objc_library) | | | -| Protocol Buffer | | | [cc\_proto\_library](protocol-buffer.html#cc_proto_library) [java\_lite\_proto\_library](protocol-buffer.html#java_lite_proto_library) [java\_proto\_library](protocol-buffer.html#java_proto_library) [proto\_library](protocol-buffer.html#proto_library) [py\_proto\_library](protocol-buffer.html#py_proto_library) | | [proto\_lang\_toolchain](protocol-buffer.html#proto_lang_toolchain) [proto\_toolchain](protocol-buffer.html#proto_toolchain) | -| Python | | [py\_binary](python.html#py_binary) | [py\_library](python.html#py_library) | [py\_test](python.html#py_test) | [py\_runtime](python.html#py_runtime) | -| Shell | | [sh\_binary](shell.html#sh_binary) | [sh\_library](shell.html#sh_library) | [sh\_test](shell.html#sh_test) | | - -### Language-agnostic native rules - -| Family | Rules | -| --- | --- | -| Extra Actions | * [action\_listener](extra-actions.html#action_listener)* [extra\_action](extra-actions.html#extra_action) | -| General | * [alias](general.html#alias)* [config\_setting](general.html#config_setting)* [filegroup](general.html#filegroup)* [genquery](general.html#genquery)* [genrule](general.html#genrule)* [starlark\_doc\_extract](general.html#starlark_doc_extract)* [test\_suite](general.html#test_suite) | -| Platforms and Toolchains | * [constraint\_setting](platforms-and-toolchains.html#constraint_setting)* [constraint\_value](platforms-and-toolchains.html#constraint_value)* [platform](platforms-and-toolchains.html#platform)* [toolchain](platforms-and-toolchains.html#toolchain)* [toolchain\_type](platforms-and-toolchains.html#toolchain_type) | \ No newline at end of file diff --git a/reference/be/platforms-and-toolchains.mdx b/reference/be/platforms-and-toolchains.mdx deleted file mode 100644 index f6a7b70..0000000 --- a/reference/be/platforms-and-toolchains.mdx +++ /dev/null @@ -1,357 +0,0 @@ ---- -title: 'platforms-and-toolchains' ---- - - -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 [here](./extending/platforms). - -## Rules - -* [constraint\_setting](#constraint_setting) -* [constraint\_value](#constraint_value) -* [platform](#platform) -* [toolchain](#toolchain) -* [toolchain\_type](#toolchain_type) - -## constraint\_setting - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintSettingRule.java) - -``` -constraint_setting(name, aspect_hints, default_constraint_value, deprecation, features, licenses, tags, testonly, visibility) -``` - -This rule is used to introduce a new constraint type for which a platform may specify a value. -For instance, you might define a `constraint_setting` named "glibc\_version" to represent -the capability for platforms to have different versions of the glibc library installed. -For more details, see the -[Platforms](https://bazel.build/docs/platforms) page. - -Each `constraint_setting` has an extensible set of associated -`constraint_value`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 `@platforms//cpu:cpu` can be extended with a custom value in order to -define a platform targeting an obscure cpu architecture. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `default_constraint_value` | [Name](./concepts/labels#target-names); [nonconfigurable](common-definitions.html#configurable-attributes); default is `None` The label of the default value for this setting, to be used if no value is given. If this attribute is present, the `constraint_value` it points to must be defined in the same package as this `constraint_setting`. 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 `config_setting`) that requires a particular value for that setting. | - -## constraint\_value - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintValueRule.java) - -``` -constraint_value(name, aspect_hints, constraint_setting, deprecation, features, licenses, tags, testonly, visibility) -``` - -This rule introduces a new value for a given constraint type. -For more details, see the -[Platforms](https://bazel.build/docs/platforms) page. - -#### Example - -The following creates a new possible value for the predefined `constraint_value` -representing cpu architecture. - -``` -constraint_value( - name = "mips", - constraint_setting = "@platforms//cpu:cpu", -) -``` - -Platforms can then declare that they have the `mips` architecture as an alternative to -`x86_64`, `arm`, and so on. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `constraint_setting` | [Label](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); required The `constraint_setting` for which this `constraint_value` is a possible choice. | - -## platform - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformRule.java) - -``` -platform(name, aspect_hints, constraint_values, deprecation, exec_properties, features, flags, licenses, missing_toolchain_error, parents, remote_execution_properties, required_settings, tags, testonly, visibility) -``` - -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 [Platforms](./extending/platforms) page. - -#### Example - -This defines a platform that describes any environment running Linux on ARM. - -``` -platform( - name = "linux_arm", - constraint_values = [ - "@platforms//os:linux", - "@platforms//cpu:arm", - ], -) -``` - -### Platform Flags - -Platforms may use the `flags` attribute to specify a list of flags that will be added -to the configuration whenever the platform is used as the target platform (i.e., as the value of -the `--platforms` flag). - -Flags set from the platform effectively have the highest precedence and overwrite any previous -value for that flag, from the command line, rc file, or transition. - -#### Example - -``` -platform( - name = "foo", - flags = [ - "--dynamic_mode=fully", - "--//bool_flag", - "--no//package:other_bool_flag", - ], -) -``` - -This defines a platform named `foo`. When this is the target platform (either because -the user specified `--platforms//:foo`, because a transition set the -`//command_line_option:platforms` flag to `["//:foo"]`, or because -`//:foo` was used as an execution platform), then the given flags will be set in the -configuration. - -#### Platforms and Repeatable Flags - -Some flags will accumulate values when they are repeated, such as `--features`, -`--copt`, any Starlark flag created as `config.string(repeatable = True)`. -These flags are not compatible with setting the flags from the platform: instead, all previous -values will be removed and overwritten with the values from the platform. - -As an example, given the following platform, the invocation `build --platforms=//:repeat_demo ---features feature_a --features feature_b` will end up with the value of the -`--feature` flag being `["feature_c", "feature_d"]`, removing the features -set on the command line. - -``` -platform( - name = "repeat_demo", - flags = [ - "--features=feature_c", - "--features=feature_d", - ], -) -``` - -For this reason, it is discouraged to use repeatable flags in the `flags` attribute. - -### Platform Inheritance - -Platforms may use the `parents` attribute to specify another platform that they will -inherit constraint values from. Although the `parents` attribute takes a list, no -more than a single value is currently supported, and specifying multiple parents is an error. - -When checking for the value of a constraint setting in a platform, first the values directly set -(via the `constraint_values` 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. - -Platforms inherit the `exec_properties` attribute from the parent platform. -The dictionary entries in `exec_properties` of the parent and child platforms -will be combined. -If the same key appears in both the parent's and the child's `exec_properties`, -the child's value will be used. If the child platform specifies an empty string as a value, the -corresponding property will be unset. - -Platforms can also inherit the (deprecated) `remote_execution_properties` attribute -from the parent platform. Note: new code should use `exec_properties` 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 `remote_execution_platform` is as follows when there -is a parent platform: - -1. If `remote_execution_property` is not set on the child platform, the parent's - `remote_execution_properties` will be used. -2. If `remote_execution_property` is set on the child platform, and contains the - literal string \{PARENT\_REMOTE\_EXECUTION\_PROPERTIES\}, that macro will be - replaced with the contents of the parent's `remote_execution_property` attribute. -3. If `remote_execution_property` is set on the child platform, and does not contain - the macro, the child's `remote_execution_property` will be used unchanged. - -*Since `remote_execution_properties` is deprecated and will be phased out, mixing -`remote_execution_properties` and `exec_properties` in the same -inheritance chain is not allowed.* -Prefer to use `exec_properties` over the deprecated -`remote_execution_properties`. - -#### Example: Constraint Values - -``` -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"], -) -``` - -In this example, the child platforms have the following properties: - -* `child_a` has the constraint values `@platforms//os:linux` (inherited - from the parent) and `@platforms//cpu:x86_64` (set directly on the platform). -* `child_b` inherits all constraint values from the parent, and doesn't set any of - its own. - -#### Example: Execution properties - -``` -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" - \} -) -``` - -In this example, the child platforms have the following properties: - -* `child_a` inherits the "exec\_properties" of the parent and does not set its own. -* `child_b` inherits the parent's `exec_properties` and overrides the - value of `k1`. Its `exec_properties` will be: - `\{ "k1": "child", "k2": "v2" \}`. -* `child_c` inherits the parent's `exec_properties` and unsets - `k1`. Its `exec_properties` will be: - `\{ "k2": "v2" \}`. -* `child_d` inherits the parent's `exec_properties` and adds a new - property. Its `exec_properties` will be: - `\{ "k1": "v1", "k2": "v2", "k3": "v3" \}`. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `constraint_values` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` 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. Each `constraint_value` in this list must be for a different `constraint_setting`. For example, you cannot define a platform that requires the cpu architecture to be both `@platforms//cpu:x86_64` and `@platforms//cpu:arm`. | -| `exec_properties` | Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `\{\}` 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 [remote execution protocol](https://github.com/bazelbuild/remote-apis). This includes any data from the parent platform's `exec_properties` 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 `remote_execution_properties`. | -| `flags` | List of strings; [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` A list of flags that will be enabled when this platform is used as the target platform in a configuration. Only flags that are part of the configuration can be set, such as those that can be used in transitions, or the `--define` flag. | -| `missing_toolchain_error` | String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `"For more information on platforms or toolchains see https://bazel.build/concepts/platforms-intro."` A custom error message that is displayed when a mandatory toolchain requirement cannot be satisfied for this target platform. Intended to point to relevant documentation users can read to understand why their toolchains are misconfigured. Not inherited from parent platforms. | -| `parents` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` The label of a `platform` 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 [Platform Inheritance](#platform_inheritance) for details. | -| `remote_execution_properties` | String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `""` 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 [Platform Inheritance](#platform_inheritance) for details. | -| `required_settings` | List of [labels](./concepts/labels); default is `[]` A list of `config_setting`s that must be satisfied by the target configuration in order for this platform to be used as an execution platform during toolchain resolution. Required settings are not inherited from parent platforms. | - -## toolchain - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ToolchainRule.java) - -``` -toolchain(name, aspect_hints, deprecation, exec_compatible_with, features, licenses, package_metadata, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, use_target_platform_constraints, visibility) -``` - -This rule declares a specific toolchain's type and constraints so that it can be selected -during toolchain resolution. See the -[Toolchains](https://bazel.build/docs/toolchains) page for more -details. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `exec_compatible_with` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` A list of `constraint_value`s that must be satisfied by an execution platform in order for this toolchain to be selected for a target building on that platform. | -| `target_compatible_with` | List of [labels](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` A list of `constraint_value`s that must be satisfied by the target platform in order for this toolchain to be selected for a target building for that platform. | -| `target_settings` | List of [labels](./concepts/labels); default is `[]` A list of `config_setting`s that must be satisfied by the target configuration in order for this toolchain to be selected during toolchain resolution. | -| `toolchain` | [Name](./concepts/labels#target-names); required The target representing the actual tool or tool suite that is made available when this toolchain is selected. | -| `toolchain_type` | [Label](./concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); required The label of a `toolchain_type` target that represents the role that this toolchain serves. | -| `use_target_platform_constraints` | Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` If `True`, this toolchain behaves as if its `exec_compatible_with` and `target_compatible_with` constraints are set to those of the current target platform. `exec_compatible_with` and `target_compatible_with` must not be set in that case. | - -## toolchain\_type - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/ToolchainType.java) - -``` -toolchain_type(name, aspect_hints, compatible_with, deprecation, features, no_match_error, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) -``` - -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. - -See the [Toolchains](./docs/toolchains) page for more details. - -#### Example - -This defines a toolchain type for a custom rule. - -``` -toolchain_type( - name = "bar_toolchain_type", -) -``` - -This can be used in a bzl file. - -``` -bar_binary = rule( - implementation = _bar_binary_impl, - attrs = \{ - "srcs": attr.label_list(allow_files = True), - ... - # No `_compiler` attribute anymore. - \}, - toolchains = ["//bar_tools:toolchain_type"] -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `no_match_error` | String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `""` A custom error message to display when no matching toolchain is found for this type. | \ No newline at end of file diff --git a/reference/be/protocol-buffer.mdx b/reference/be/protocol-buffer.mdx deleted file mode 100644 index 48095d3..0000000 --- a/reference/be/protocol-buffer.mdx +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: 'protocol-buffer' ---- - - -## Rules - -* [cc\_proto\_library](#cc_proto_library) -* [java\_lite\_proto\_library](#java_lite_proto_library) -* [java\_proto\_library](#java_proto_library) -* [proto\_library](#proto_library) -* [py\_proto\_library](#py_proto_library) -* [proto\_lang\_toolchain](#proto_lang_toolchain) -* [proto\_toolchain](#proto_toolchain) - -## cc\_proto\_library - -[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_cc_proto_library.bzl) - -``` -cc_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -`cc_proto_library` generates C++ code from `.proto` files. - -`deps` must point to [`proto_library`](protocol-buffer.html#proto_library) rules. - -Example: - -``` -cc_library( - name = "lib", - deps = [":foo_cc_proto"], -) - -cc_proto_library( - name = "foo_cc_proto", - deps = [":foo_proto"], -) - -proto_library( - name = "foo_proto", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of [`proto_library`](protocol-buffer.html#proto_library) rules to generate C++ code for. | - -## java\_lite\_proto\_library - -[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/java_lite_proto_library.bzl) - -``` -java_lite_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -`java_lite_proto_library` generates Java code from `.proto` files. - -`deps` must point to [`proto_library`](protocol-buffer.html#proto_library) rules. - -Example: - -``` -java_library( - name = "lib", - runtime_deps = [":foo"], -) - -java_lite_proto_library( - name = "foo", - deps = [":bar"], -) - -proto_library( - name = "bar", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of [`proto_library`](protocol-buffer.html#proto_library) rules to generate Java code for. | - -## java\_proto\_library - -[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_java_proto_library_rule.bzl) - -``` -java_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -`java_proto_library` generates Java code from `.proto` files. - -`deps` must point to [`proto_library`](protocol-buffer.html#proto_library) rules. - -Example: - -``` -java_library( - name = "lib", - runtime_deps = [":foo_java_proto"], -) - -java_proto_library( - name = "foo_java_proto", - deps = [":foo_proto"], -) - -proto_library( - name = "foo_proto", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of [`proto_library`](protocol-buffer.html#proto_library) rules to generate Java code for. | - -## proto\_library - -[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_library_rule.bzl) - -``` -proto_library(name, deps, srcs, data, allow_exports, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exports, features, import_prefix, licenses, option_deps, package_metadata, restricted_to, strip_import_prefix, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Use `proto_library` to define libraries of protocol buffers which -may be used from multiple languages. A `proto_library` may be listed -in the `deps` clause of supported rules, such as -`java_proto_library`. - -When compiled on the command-line, a `proto_library` creates a file -named `foo-descriptor-set.proto.bin`, which is the descriptor set for -the messages the rule srcs. The file is a serialized -`FileDescriptorSet`, which is described in -[https://developers.google.com/protocol-buffers/docs/techniques#self-description](https://developers.google.com/protocol-buffers/docs/techniques#self-description). - -It only contains information about the `.proto` files directly -mentioned by a `proto_library` rule; the collection of transitive -descriptor sets is available through the -`[ProtoInfo].transitive_descriptor_sets` Starlark provider. -See documentation in `proto_info.bzl`. - -Recommended code organization: - -* One `proto_library` rule per `.proto` file.* A file named `foo.proto` will be in a rule named `foo_proto`, - which is located in the same package.* A `[language]_proto_library` that wraps a `proto_library` - named `foo_proto` should be called `foo_[language]_proto`, - and be located in the same package. - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of other `proto_library` rules that the target depends upon. A `proto_library` may only depend on other `proto_library` targets. It may not depend on language-specific libraries. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of `.proto` and `.protodevel` files that are processed to create the target. This is usually a non empty list. One usecase where `srcs` can be empty is an *alias-library*. This is a proto\_library rule having one or more other proto\_library in `deps`. This pattern can be used to e.g. export a public api under a persistent name. | -| `allow_exports` | [Label](./concepts/labels); default is `None` An optional allowlist that prevents proto library to be reexported or used in lang\_proto\_library that is not in one of the listed packages. | -| `exports` | List of [labels](./concepts/labels); default is `[]` List of proto\_library targets that can be referenced via "import public" in the proto source. It's an error if you use "import public" but do not list the corresponding library in the exports attribute. Note that you have list the library both in deps and exports since not all lang\_proto\_library implementations have been changed yet. | -| `import_prefix` | String; default is `""` The prefix to add to the paths of the .proto files in this rule. When set, the .proto source files in the `srcs` attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the `strip_import_prefix` attribute is removed before this prefix is added. | -| `option_deps` | List of [labels](./concepts/labels); default is `[]` The list of other `proto_library` rules that the target depends upon for options only. A `proto_library` may only depend on other `proto_library` targets. It may not depend on language-specific libraries. | -| `strip_import_prefix` | String; default is `"/"` The prefix to strip from the paths of the .proto files in this rule. When set, .proto source files in the `srcs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path (not starting with a slash), it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `import_prefix` attribute is added after this prefix is stripped. | - -## py\_proto\_library - -[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/py_proto_library.bzl) - -``` -py_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -Use `py\_proto\_library` to generate Python libraries from `.proto` files. -The convention is to name the `py\_proto\_library` rule `foo\_py\_pb2`, -when it is wrapping `proto\_library` rule `foo\_proto`. -`deps` must point to a `proto\_library` rule. -Example: -```starlark -py\_library( -name = "lib", -deps = [":foo\_py\_pb2"], -) -py\_proto\_library( -name = "foo\_py\_pb2", -deps = [":foo\_proto"], -) -proto\_library( -name = "foo\_proto", -srcs = ["foo.proto"], -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of `proto\_library` rules to generate Python libraries for. Usually this is just the one target: the proto library of interest. It can be any target providing `ProtoInfo`. | - -## proto\_lang\_toolchain - -[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_lang_toolchain_rule.bzl) - -``` -proto_lang_toolchain(name, allowlist_different_package, aspect_hints, blacklisted_protos, command_line, compatible_with, denylisted_protos, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, mnemonic, output_files, package_metadata, plugin, plugin_format_flag, progress_message, protoc_minimal_do_not_use, restricted_to, runtime, tags, target_compatible_with, testonly, toolchain_type, toolchains, visibility) -``` - -If using Bazel, please load the rule from [https://github.com/bazelbuild/rules_proto](https://github.com/bazelbuild/rules_proto). - -Specifies how a LANG\_proto\_library rule (e.g., `java_proto_library`) should invoke the -proto-compiler. -Some LANG\_proto\_library rules allow specifying which toolchain to use using command-line flags; -consult their documentation. - -Normally you should not write those kind of rules unless you want to -tune your Java compiler. - -There's no compiler. The proto-compiler is taken from the proto\_library rule we attach to. It is -passed as a command-line flag to Blaze. -Several features require a proto-compiler to be invoked on the proto\_library rule itself. -It's beneficial to enforce the compiler that LANG\_proto\_library uses is the same as the one -`proto_library` does. - -#### Examples - -A simple example would be: - -``` -proto_lang_toolchain( - name = "javalite_toolchain", - command_line = "--javalite_out=shared,immutable:$(OUT)", - plugin = ":javalite_plugin", - runtime = ":protobuf_lite", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `allowlist_different_package` | [Label](./concepts/labels); default is `None` | -| `blacklisted_protos` | List of [labels](./concepts/labels); default is `[]` Deprecated. Alias for `denylisted_protos`. Will be removed in a future release. | -| `command_line` | String; required This value will be passed to proto-compiler to generate the code. Only include the parts specific to this code-generator/plugin (e.g., do not include -I parameters) * `$(OUT)` is LANG\_proto\_library-specific. The rules are expected to define how they interpret this variable. For Java, for example, $(OUT) will be replaced with the src-jar filename to create. | -| `denylisted_protos` | List of [labels](./concepts/labels); default is `[]` No code will be generated for files in the `srcs` attribute of `denylisted_protos`. This is used for .proto files that are already linked into proto runtimes, such as `any.proto`. | -| `mnemonic` | String; default is `"GenProto"` This value will be set as the mnemonic on protoc action. | -| `output_files` | String; default is `"legacy"` Controls how `$(OUT)` in `command_line` is formatted, either by a path to a single file or output directory in case of multiple files. Possible values are: "single", "multiple". | -| `plugin` | [Label](./concepts/labels); default is `None` If provided, will be made available to the action that calls the proto-compiler, and will be passed to the proto-compiler: `--plugin=protoc-gen-PLUGIN=<executable>.` | -| `plugin_format_flag` | String; default is `""` If provided, this value will be passed to proto-compiler to use the plugin. The value must contain a single %s which is replaced with plugin executable. `--plugin=protoc-gen-PLUGIN=<executable>.` | -| `progress_message` | String; default is `"Generating proto_library %\{label\}"` This value will be set as the progress message on protoc action. | -| `protoc_minimal_do_not_use` | [Label](./concepts/labels); default is `None` | -| `runtime` | [Label](./concepts/labels); default is `None` A language-specific library that the generated code is compiled against. The exact behavior is LANG\_proto\_library-specific. Java, for example, should compile against the runtime. | -| `toolchain_type` | [Label](./concepts/labels); default is `None` | - -## proto\_toolchain - -[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_toolchain_rule.bzl) - -``` -proto_toolchain(name, aspect_hints, command_line, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, mnemonic, output_files, package_metadata, progress_message, proto_compiler, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `command_line` | String; default is `"--descriptor_set_out=%s"` | -| `mnemonic` | String; default is `"GenProtoDescriptorSet"` | -| `output_files` | String; default is `"single"` | -| `progress_message` | String; default is `"Generating Descriptor Set proto_library %\{label\}"` | -| `proto_compiler` | [Label](./concepts/labels); default is `None` | \ No newline at end of file diff --git a/reference/be/python.mdx b/reference/be/python.mdx deleted file mode 100644 index 47b4a30..0000000 --- a/reference/be/python.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: 'python' ---- - - -## Rules - -* [py\_binary](#py_binary) -* [py\_library](#py_library) -* [py\_test](#py_test) -* [py\_runtime](#py_runtime) - -## py\_binary - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_binary_rule.bzl) - -``` -py_binary(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, distribs, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, imports, interpreter_args, legacy_create_init, licenses, main, main_module, output_licenses, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, pyi_deps, pyi_srcs, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py\_library` rules. Targets that only provide data files used at runtime belong in the `data` attribute. :::\{note\} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. \* \{obj\}`PyInfo.site\_packages\_symlinks` uses topological ordering. See \{obj\}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. ::: | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of Python source files that are processed to create the target. This includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary files that may be needed at run time belong in `data`. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). There is no `py\_embed\_data` like there is `cc\_embed\_data` and `go\_embed\_data`. This is because Python has a concept of runtime resources. | -| `distribs` | List of strings; default is `[]` | -| `imports` | List of strings; default is `[]` List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py\_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, Absolute paths (paths that start with `/`) and paths that references a path above the execution root are not allowed and will result in an error. | -| `interpreter_args` | List of strings; default is `[]` Arguments that are only applicable to the interpreter. The args an interpreter supports are specific to the interpreter. For CPython, see https://docs.python.org/3/using/cmdline.html. :::\{note\} Only supported for \{obj\}`--bootstrap\_impl=script`. Ignored otherwise. ::: :::\{seealso\} The \{any\}`RULES\_PYTHON\_ADDITIONAL\_INTERPRETER\_ARGS` environment variable ::: :::\{versionadded\} 1.3.0 ::: | -| `legacy_create_init` | Integer; default is `-1` Whether to implicitly create empty `\_\_init\_\_.py` files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default, `-1` (auto), means true unless `--incompatible\_default\_to\_explicit\_init\_py` is used. If false, the user is responsible for creating (possibly empty) `\_\_init\_\_.py` files and adding them to the `srcs` of Python targets as required. | -| `main` | [Label](./concepts/labels); default is `None` Optional; the name of the source file that is the main entry point of the application. This file must also be listed in `srcs`. If left unspecified, `name`, with `.py` appended, is used instead. If `name` does not match any filename in `srcs`, `main` must be specified. This is mutually exclusive with \{obj\}`main\_module`. | -| `main_module` | String; default is `""` Module name to execute as the main program. When set, `srcs` is not required, and it is assumed the module is provided by a dependency. See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more information about running modules as the main program. This is mutually exclusive with \{obj\}`main`. :::\{versionadded\} 1.3.0 ::: | -| `precompile` | String; default is `"inherit"` Whether py source files \*\*for this target\*\* should be precompiled. Values: \* `inherit`: Allow the downstream binary decide if precompiled files are used. \* `enabled`: Compile Python source files at build time. \* `disabled`: Don't compile Python source files at build time. :::\{seealso\} \* The \{flag\}`--precompile` flag, which can override this attribute in some cases and will affect all targets when building. \* The \{obj\}`pyc\_collection` attribute for transitively enabling precompiling on a per-target basis. \* The [Precompiling](precompiling) docs for a guide about using precompiling. ::: | -| `precompile_invalidation_mode` | String; default is `"auto"` How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: \* `auto`: The effective value will be automatically determined by other build settings. \* `checked\_hash`: Use the pyc file if the hash of the source file matches the hash recorded in the pyc file. This is most useful when working with code that you may modify. \* `unchecked\_hash`: Always use the pyc file; don't check the pyc's hash against the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode | -| `precompile_optimize_level` | Integer; default is `0` The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile NOTE: The value `-1` means "current interpreter", which will be the interpreter used \_at build time when pycs are generated\_, not the interpreter used at runtime when the code actually runs. | -| `precompile_source_retention` | String; default is `"inherit"` Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: \* `inherit`: Inherit the value from the \{flag\}`--precompile\_source\_retention` flag. \* `keep\_source`: Include the original Python source. \* `omit\_source`: Don't include the original py source. | -| `pyc_collection` | String; default is `"inherit"` Determines whether pyc files from dependencies should be manually included. Valid values are: \* `inherit`: Inherit the value from \{flag\}`--precompile`. \* `include\_pyc`: Add implicitly generated pyc files from dependencies. i.e. pyc files for targets that specify \{attr\}`precompile="inherit"`. \* `disabled`: Don't add implicitly generated pyc files. Note that pyc files may still come from dependencies that enable precompiling at the target level. | -| `pyi_deps` | List of [labels](./concepts/labels); default is `[]` Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE\_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | -| `pyi_srcs` | List of [labels](./concepts/labels); default is `[]` Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | -| `python_version` | String; default is `""` The Python version this target should use. The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or unspecified, the incoming configuration's \{obj\}`--python\_version` flag is inherited. For backwards compatibility, the values `PY2` and `PY3` are accepted, but treated as an empty/unspecified value. :::\{note\} In order for the requested version to be used, there must be a toolchain configured to match the Python version. If there isn't, then it may be silently ignored, or an error may occur, depending on the toolchain configuration. ::: :::\{versionchanged\} 1.1.0 This attribute was changed from only accepting `PY2` and `PY3` values to accepting arbitrary Python versions. ::: | -| `srcs_version` | String; default is `""` Defunct, unused, does nothing. | -| `stamp` | Integer; default is `-1` Whether to encode build information into the binary. Possible values: \* `stamp = 1`: Always stamp the build information into the binary, even in `--nostamp` builds. \*\*This setting should be avoided\*\*, since it potentially kills remote caching for the binary and any downstream actions that depend on it. \* `stamp = 0`: Always replace build information by constant values. This gives good build result caching. \* `stamp = -1`: Embedding of build information is controlled by the `--[no]stamp` flag. Stamped binaries are not rebuilt unless their dependencies change. WARNING: Stamping can harm build performance by reducing cache hits and should be avoided if possible. | - -## py\_library - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_library_rule.bzl) - -``` -py_library(name, deps, srcs, data, aspect_hints, compatible_with, deprecation, distribs, exec_compatible_with, exec_group_compatible_with, exec_properties, experimental_venvs_site_packages, features, imports, licenses, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyi_deps, pyi_srcs, restricted_to, srcs_version, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -A library of Python code that can be depended upon. -Default outputs: -\* The input Python sources -\* The precompiled artifacts from the sources. -NOTE: Precompilation affects which of the default outputs are included in the -resulting runfiles. See the precompile-related attributes and flags for -more information. -:::\{versionchanged\} 0.37.0 -Source files are no longer added to the runfiles directly. -::: - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py\_library` rules. Targets that only provide data files used at runtime belong in the `data` attribute. :::\{note\} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. \* \{obj\}`PyInfo.site\_packages\_symlinks` uses topological ordering. See \{obj\}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. ::: | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of Python source files that are processed to create the target. This includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary files that may be needed at run time belong in `data`. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). There is no `py\_embed\_data` like there is `cc\_embed\_data` and `go\_embed\_data`. This is because Python has a concept of runtime resources. | -| `distribs` | List of strings; default is `[]` | -| `experimental_venvs_site_packages` | [Label](./concepts/labels); default is `None` \*\*INTERNAL ATTRIBUTE. SHOULD ONLY BE SET BY rules\_python-INTERNAL CODE.\*\* :::\{include\} /\_includes/experimental\_api.md ::: A flag that decides whether the library should treat its sources as a site-packages layout. When the flag is `yes`, then the `srcs` files are treated as a site-packages layout that is relative to the `imports` attribute. The `imports` attribute can have only a single element. It is a repo-relative runfiles path. For example, in the `my/pkg/BUILD.bazel` file, given `srcs=["site-packages/foo/bar.py"]`, specifying `imports=["my/pkg/site-packages"]` means `foo/bar.py` is the file path under the binary's venv site-packages directory that should be made available (i.e. `import foo.bar` will work). `\_\_init\_\_.py` files are treated specially to provide basic support for [implicit namespace packages]( https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages). However, the \*content\* of the files cannot be taken into account, merely their presence or absense. Stated another way: [pkgutil-style namespace packages]( https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages) won't be understood as namespace packages; they'll be seen as regular packages. This will likely lead to conflicts with other targets that contribute to the namespace. :::\{tip\} This attributes populates \{obj\}`PyInfo.site\_packages\_symlinks`, which is a topologically ordered depset. This means dependencies closer and earlier to a consumer have precedence. See \{obj\}`PyInfo.site\_packages\_symlinks` for more information. ::: :::\{versionadded\} 1.4.0 ::: | -| `imports` | List of strings; default is `[]` List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py\_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, Absolute paths (paths that start with `/`) and paths that references a path above the execution root are not allowed and will result in an error. | -| `precompile` | String; default is `"inherit"` Whether py source files \*\*for this target\*\* should be precompiled. Values: \* `inherit`: Allow the downstream binary decide if precompiled files are used. \* `enabled`: Compile Python source files at build time. \* `disabled`: Don't compile Python source files at build time. :::\{seealso\} \* The \{flag\}`--precompile` flag, which can override this attribute in some cases and will affect all targets when building. \* The \{obj\}`pyc\_collection` attribute for transitively enabling precompiling on a per-target basis. \* The [Precompiling](precompiling) docs for a guide about using precompiling. ::: | -| `precompile_invalidation_mode` | String; default is `"auto"` How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: \* `auto`: The effective value will be automatically determined by other build settings. \* `checked\_hash`: Use the pyc file if the hash of the source file matches the hash recorded in the pyc file. This is most useful when working with code that you may modify. \* `unchecked\_hash`: Always use the pyc file; don't check the pyc's hash against the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode | -| `precompile_optimize_level` | Integer; default is `0` The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile NOTE: The value `-1` means "current interpreter", which will be the interpreter used \_at build time when pycs are generated\_, not the interpreter used at runtime when the code actually runs. | -| `precompile_source_retention` | String; default is `"inherit"` Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: \* `inherit`: Inherit the value from the \{flag\}`--precompile\_source\_retention` flag. \* `keep\_source`: Include the original Python source. \* `omit\_source`: Don't include the original py source. | -| `pyi_deps` | List of [labels](./concepts/labels); default is `[]` Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE\_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | -| `pyi_srcs` | List of [labels](./concepts/labels); default is `[]` Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | -| `srcs_version` | String; default is `""` Defunct, unused, does nothing. | - -## py\_test - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_test_rule.bzl) - -``` -py_test(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, imports, interpreter_args, legacy_create_init, licenses, local, main, main_module, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, pyi_deps, pyi_srcs, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` List of additional libraries to be linked in to the target. See comments about the [`deps` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). These are typically `py\_library` rules. Targets that only provide data files used at runtime belong in the `data` attribute. :::\{note\} The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged. \* \{obj\}`PyInfo.site\_packages\_symlinks` uses topological ordering. See \{obj\}`PyInfo` for more information about the ordering of its depsets and how its fields are merged. ::: | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of Python source files that are processed to create the target. This includes all your checked-in code and may include generated source files. The `.py` files belong in `srcs` and library targets belong in `deps`. Other binary files that may be needed at run time belong in `data`. | -| `data` | List of [labels](./concepts/labels); default is `[]` The list of files need by this library at runtime. See comments about the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). There is no `py\_embed\_data` like there is `cc\_embed\_data` and `go\_embed\_data`. This is because Python has a concept of runtime resources. | -| `distribs` | List of strings; default is `[]` | -| `imports` | List of strings; default is `[]` List of import directories to be added to the PYTHONPATH. Subject to "Make variable" substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to `PYTHONPATH` by `py\_binary` rules that depend on this rule. The strings are repo-runfiles-root relative, Absolute paths (paths that start with `/`) and paths that references a path above the execution root are not allowed and will result in an error. | -| `interpreter_args` | List of strings; default is `[]` Arguments that are only applicable to the interpreter. The args an interpreter supports are specific to the interpreter. For CPython, see https://docs.python.org/3/using/cmdline.html. :::\{note\} Only supported for \{obj\}`--bootstrap\_impl=script`. Ignored otherwise. ::: :::\{seealso\} The \{any\}`RULES\_PYTHON\_ADDITIONAL\_INTERPRETER\_ARGS` environment variable ::: :::\{versionadded\} 1.3.0 ::: | -| `legacy_create_init` | Integer; default is `-1` Whether to implicitly create empty `\_\_init\_\_.py` files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default, `-1` (auto), means true unless `--incompatible\_default\_to\_explicit\_init\_py` is used. If false, the user is responsible for creating (possibly empty) `\_\_init\_\_.py` files and adding them to the `srcs` of Python targets as required. | -| `main` | [Label](./concepts/labels); default is `None` Optional; the name of the source file that is the main entry point of the application. This file must also be listed in `srcs`. If left unspecified, `name`, with `.py` appended, is used instead. If `name` does not match any filename in `srcs`, `main` must be specified. This is mutually exclusive with \{obj\}`main\_module`. | -| `main_module` | String; default is `""` Module name to execute as the main program. When set, `srcs` is not required, and it is assumed the module is provided by a dependency. See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more information about running modules as the main program. This is mutually exclusive with \{obj\}`main`. :::\{versionadded\} 1.3.0 ::: | -| `precompile` | String; default is `"inherit"` Whether py source files \*\*for this target\*\* should be precompiled. Values: \* `inherit`: Allow the downstream binary decide if precompiled files are used. \* `enabled`: Compile Python source files at build time. \* `disabled`: Don't compile Python source files at build time. :::\{seealso\} \* The \{flag\}`--precompile` flag, which can override this attribute in some cases and will affect all targets when building. \* The \{obj\}`pyc\_collection` attribute for transitively enabling precompiling on a per-target basis. \* The [Precompiling](precompiling) docs for a guide about using precompiling. ::: | -| `precompile_invalidation_mode` | String; default is `"auto"` How precompiled files should be verified to be up-to-date with their associated source files. Possible values are: \* `auto`: The effective value will be automatically determined by other build settings. \* `checked\_hash`: Use the pyc file if the hash of the source file matches the hash recorded in the pyc file. This is most useful when working with code that you may modify. \* `unchecked\_hash`: Always use the pyc file; don't check the pyc's hash against the source file. This is most useful when the code won't be modified. For more information on pyc invalidation modes, see https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode | -| `precompile_optimize_level` | Integer; default is `0` The optimization level for precompiled files. For more information about optimization levels, see the `compile()` function's `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile NOTE: The value `-1` means "current interpreter", which will be the interpreter used \_at build time when pycs are generated\_, not the interpreter used at runtime when the code actually runs. | -| `precompile_source_retention` | String; default is `"inherit"` Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are: \* `inherit`: Inherit the value from the \{flag\}`--precompile\_source\_retention` flag. \* `keep\_source`: Include the original Python source. \* `omit\_source`: Don't include the original py source. | -| `pyc_collection` | String; default is `"inherit"` Determines whether pyc files from dependencies should be manually included. Valid values are: \* `inherit`: Inherit the value from \{flag\}`--precompile`. \* `include\_pyc`: Add implicitly generated pyc files from dependencies. i.e. pyc files for targets that specify \{attr\}`precompile="inherit"`. \* `disabled`: Don't add implicitly generated pyc files. Note that pyc files may still come from dependencies that enable precompiling at the target level. | -| `pyi_deps` | List of [labels](./concepts/labels); default is `[]` Dependencies providing type definitions the library needs. These are dependencies that satisfy imports guarded by `typing.TYPE\_CHECKING`. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | -| `pyi_srcs` | List of [labels](./concepts/labels); default is `[]` Type definition files for the library. These are typically `.pyi` files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however). :::\{versionadded\} 1.1.0 ::: | -| `python_version` | String; default is `""` The Python version this target should use. The value should be in `X.Y` or `X.Y.Z` (or compatible) format. If empty or unspecified, the incoming configuration's \{obj\}`--python\_version` flag is inherited. For backwards compatibility, the values `PY2` and `PY3` are accepted, but treated as an empty/unspecified value. :::\{note\} In order for the requested version to be used, there must be a toolchain configured to match the Python version. If there isn't, then it may be silently ignored, or an error may occur, depending on the toolchain configuration. ::: :::\{versionchanged\} 1.1.0 This attribute was changed from only accepting `PY2` and `PY3` values to accepting arbitrary Python versions. ::: | -| `srcs_version` | String; default is `""` Defunct, unused, does nothing. | -| `stamp` | Integer; default is `0` Whether to encode build information into the binary. Possible values: \* `stamp = 1`: Always stamp the build information into the binary, even in `--nostamp` builds. \*\*This setting should be avoided\*\*, since it potentially kills remote caching for the binary and any downstream actions that depend on it. \* `stamp = 0`: Always replace build information by constant values. This gives good build result caching. \* `stamp = -1`: Embedding of build information is controlled by the `--[no]stamp` flag. Stamped binaries are not rebuilt unless their dependencies change. WARNING: Stamping can harm build performance by reducing cache hits and should be avoided if possible. | - -## py\_runtime - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_runtime_rule.bzl) - -``` -py_runtime(name, abi_flags, aspect_hints, bootstrap_template, compatible_with, coverage_tool, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, files, implementation_name, interpreter, interpreter_path, interpreter_version_info, package_metadata, pyc_tag, python_version, restricted_to, site_init_template, stage2_bootstrap_template, stub_shebang, tags, target_compatible_with, testonly, toolchains, visibility, zip_main_template) -``` - -Represents a Python runtime used to execute Python code. -A `py\_runtime` target can represent either a \*platform runtime\* or an \*in-build -runtime\*. A platform runtime accesses a system-installed interpreter at a known -path, whereas an in-build runtime points to an executable target that acts as -the interpreter. In both cases, an "interpreter" means any executable binary or -wrapper script that is capable of running a Python script passed on the command -line, following the same conventions as the standard CPython interpreter. -A platform runtime is by its nature non-hermetic. It imposes a requirement on -the target platform to have an interpreter located at a specific path. An -in-build runtime may or may not be hermetic, depending on whether it points to -a checked-in interpreter or a wrapper script that accesses the system -interpreter. -Example -``` -load("@rules\_python//python:py\_runtime.bzl", "py\_runtime") -py\_runtime( -name = "python-2.7.12", -files = glob(["python-2.7.12/\*\*"]), -interpreter = "python-2.7.12/bin/python", -) -py\_runtime( -name = "python-3.6.0", -interpreter\_path = "/opt/pyenv/versions/3.6.0/bin/python", -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `abi_flags` | String; default is `""` The runtime's ABI flags, i.e. `sys.abiflags`. If not set, then it will be set based on flags. | -| `bootstrap_template` | [Label](./concepts/labels); default is `"@rules_python//python/private:bootstrap_template"` The bootstrap script template file to use. Should have %python\_binary%, %workspace\_name%, %main%, and %imports%. This template, after expansion, becomes the executable file used to start the process, so it is responsible for initial bootstrapping actions such as finding the Python interpreter, runfiles, and constructing an environment to run the intended Python application. While this attribute is currently optional, it will become required when the Python rules are moved out of Bazel itself. The exact variable names expanded is an unstable API and is subject to change. The API will become more stable when the Python rules are moved out of Bazel itself. See @bazel\_tools//tools/python:python\_bootstrap\_template.txt for more variables. | -| `coverage_tool` | [Label](./concepts/labels); default is `None` This is a target to use for collecting code coverage information from \{rule\}`py\_binary` and \{rule\}`py\_test` targets. If set, the target must either produce a single file or be an executable target. The path to the single file, or the executable if the target is executable, determines the entry point for the python coverage tool. The target and its runfiles will be added to the runfiles when coverage is enabled. The entry point for the tool must be loadable by a Python interpreter (e.g. a `.py` or `.pyc` file). It must accept the command line arguments of [`coverage.py`](https://coverage.readthedocs.io), at least including the `run` and `lcov` subcommands. | -| `files` | List of [labels](./concepts/labels); default is `[]` For an in-build runtime, this is the set of files comprising this runtime. These files will be added to the runfiles of Python binaries that use this runtime. For a platform runtime this attribute must not be set. | -| `implementation_name` | String; default is `"cpython"` The Python implementation name (`sys.implementation.name`) | -| `interpreter` | [Label](./concepts/labels); default is `None` For an in-build runtime, this is the target to invoke as the interpreter. It can be either of: \* A single file, which will be the interpreter binary. It's assumed such interpreters are either self-contained single-file executables or any supporting files are specified in `files`. \* An executable target. The target's executable will be the interpreter binary. Any other default outputs (`target.files`) and plain files runfiles (`runfiles.files`) will be automatically included as if specified in the `files` attribute. NOTE: the runfiles of the target may not yet be properly respected/propagated to consumers of the toolchain/interpreter, see bazel-contrib/rules\_python/issues/1612 For a platform runtime (i.e. `interpreter\_path` being set) this attribute must not be set. | -| `interpreter_path` | String; default is `""` For a platform runtime, this is the absolute path of a Python interpreter on the target platform. For an in-build runtime this attribute must not be set. | -| `interpreter_version_info` | Dictionary: String -> String; default is `\{\}` Version information about the interpreter this runtime provides. If not specified, uses \{obj\}`--python\_version` The supported keys match the names for `sys.version\_info`. While the input values are strings, most are converted to ints. The supported keys are: \* major: int, the major version number \* minor: int, the minor version number \* micro: optional int, the micro version number \* releaselevel: optional str, the release level \* serial: optional int, the serial number of the release :::\{versionchanged\} 0.36.0 \{obj\}`--python\_version` determines the default value. ::: | -| `pyc_tag` | String; default is `""` Optional string; the tag portion of a pyc filename, e.g. the `cpython-39` infix of `foo.cpython-39.pyc`. See PEP 3147. If not specified, it will be computed from `implementation\_name` and `interpreter\_version\_info`. If no pyc\_tag is available, then only source-less pyc generation will function correctly. | -| `python_version` | String; default is `"PY3"` Whether this runtime is for Python major version 2 or 3. Valid values are `"PY2"` and `"PY3"`. The default value is controlled by the `--incompatible\_py3\_is\_default` flag. However, in the future this attribute will be mandatory and have no default value. | -| `site_init_template` | [Label](./concepts/labels); default is `"@rules_python//python/private:site_init_template"` The template to use for the binary-specific site-init hook run by the interpreter at startup. :::\{versionadded\} 0.41.0 ::: | -| `stage2_bootstrap_template` | [Label](./concepts/labels); default is `"@rules_python//python/private:stage2_bootstrap_template"` The template to use when two stage bootstrapping is enabled :::\{seealso\} \{obj\}`PyRuntimeInfo.stage2\_bootstrap\_template` and \{obj\}`--bootstrap\_impl` ::: | -| `stub_shebang` | String; default is `"#!/usr/bin/env python3"` "Shebang" expression prepended to the bootstrapping Python stub script used when executing \{rule\}`py\_binary` targets. See https://github.com/bazelbuild/bazel/issues/8685 for motivation. Does not apply to Windows. | -| `zip_main_template` | [Label](./concepts/labels); default is `"@rules_python//python/private:zip_main_template"` The template to use for a zip's top-level `\_\_main\_\_.py` file. This becomes the entry point executed when `python foo.zip` is run. :::\{seealso\} The \{obj\}`PyRuntimeInfo.zip\_main\_template` field. ::: | \ No newline at end of file diff --git a/reference/be/shell.mdx b/reference/be/shell.mdx deleted file mode 100644 index 5818423..0000000 --- a/reference/be/shell.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: 'shell' ---- - - -## Rules - -* [sh\_binary](#sh_binary) -* [sh\_library](#sh_library) -* [sh\_test](#sh_test) - -## sh\_binary - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_binary.bzl) - -``` -sh_binary(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, output_licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, use_bash_launcher, visibility) -``` - -The `sh_binary` rule is used to declare executable shell scripts. -(`sh_binary` is a misnomer: its outputs aren't necessarily binaries.) This rule ensures -that all dependencies are built, and appear in the `runfiles` area at execution time. -We recommend that you name your `sh_binary()` rules after the name of the script minus -the extension (e.g. `.sh`); the rule name and the file name must be distinct. -`sh_binary` respects shebangs, so any available interpreter may be used (eg. -`#!/bin/zsh`) - -#### Example - -For a simple shell script with no dependencies and some data files: - -``` -sh_binary( - name = "foo", - srcs = ["foo.sh"], - data = glob(["datafiles/*.txt"]), -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of "library" targets to be aggregated into this target. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical.deps). This attribute should be used to list other `sh_library` rules that provide interpreted program source code depended on by the code in `srcs`. The files provided by these rules will be present among the `runfiles` of this target. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The file containing the shell script. This attribute must be a singleton list, whose element is the shell script. This script must be executable, and may be a source file or a generated file. All other files required at runtime (whether scripts or data) belong in the `data` attribute. | -| `env_inherit` | List of strings; default is `[]` | -| `use_bash_launcher` | Boolean; default is `False` Use a bash launcher initializing the runfiles library | - -## sh\_library - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_library.bzl) - -``` -sh_library(name, deps, srcs, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) -``` - -The main use for this rule is to aggregate together a logical -"library" consisting of related scripts—programs in an -interpreted language that does not require compilation or linking, -such as the Bourne shell—and any data those programs need at -run-time. Such "libraries" can then be used from -the `data` attribute of one or -more `sh_binary` rules. - -You can use the [`filegroup`](./reference/be/general.html#filegroup) rule to aggregate data -files. - -In interpreted programming languages, there's not always a clear -distinction between "code" and "data": after all, the program is -just "data" from the interpreter's point of view. For this reason -this rule has three attributes which are all essentially equivalent: -`srcs`, `deps` and `data`. -The current implementation does not distinguish between the elements of these lists. -All three attributes accept rules, source files and generated files. -It is however good practice to use the attributes for their usual purpose (as with other rules). - -#### Examples - -``` -sh_library( - name = "foo", - data = [ - ":foo_service_script", # an sh_binary with srcs - ":deploy_foo", # another sh_binary with srcs - ], -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of "library" targets to be aggregated into this target. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical.deps). This attribute should be used to list other `sh_library` rules that provide interpreted program source code depended on by the code in `srcs`. The files provided by these rules will be present among the `runfiles` of this target. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The list of input files. This attribute should be used to list shell script source files that belong to this library. Scripts can load other scripts using the shell's `source` or `.` command. | - -## sh\_test - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_test.bzl) - -``` -sh_test(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, local, package_metadata, restricted_to, shard_count, size, tags, target_compatible_with, testonly, timeout, toolchains, use_bash_launcher, visibility) -``` - -A `sh_test()` rule creates a test written as a Bourne shell script. - -See the [attributes common to all test rules (\*\_test)](./reference/be/common-definitions#common-attributes-tests). - -#### Examples - -``` -sh_test( - name = "foo_integration_test", - size = "small", - srcs = ["foo_integration_test.sh"], - deps = [":foo_sh_lib"], - data = glob(["testdata/*.txt"]), -) -``` - -### Arguments - -| Attributes | | -| --- | --- | -| `name` | [Name](./concepts/labels#target-names); required A unique name for this target. | -| `deps` | List of [labels](./concepts/labels); default is `[]` The list of "library" targets to be aggregated into this target. See general comments about `deps` at [Typical attributes defined by most build rules](./reference/be/common-definitions#typical.deps). This attribute should be used to list other `sh_library` rules that provide interpreted program source code depended on by the code in `srcs`. The files provided by these rules will be present among the `runfiles` of this target. | -| `srcs` | List of [labels](./concepts/labels); default is `[]` The file containing the shell script. This attribute must be a singleton list, whose element is the shell script. This script must be executable, and may be a source file or a generated file. All other files required at runtime (whether scripts or data) belong in the `data` attribute. | -| `use_bash_launcher` | Boolean; default is `False` Use a bash launcher initializing the runfiles library | \ No newline at end of file diff --git a/reference/command-line-reference.mdx b/reference/command-line-reference.mdx deleted file mode 100644 index 8a6bb76..0000000 --- a/reference/command-line-reference.mdx +++ /dev/null @@ -1,12159 +0,0 @@ ---- -title: 'command-line-reference' ---- - - -``` -bazel [<startup options>] \<command\> [\<args\>] -``` - -or - -``` -bazel [<startup options>] \<command\> [\<args\>] -- [<target patterns>] -``` - -See the [User's Guide](./docs/build#specifying-build-targets) for the -target patterns syntax. - -## Option Syntax - -Options can be passed to Bazel in different ways. Options that require a value -can be passed with either an equals sign or a space: - -``` ---\<option>=<value\> ---\<option\> \<value\> -``` - -Some options have a single character short form; in that case, the short form -has to be passed with a single dash and a space. - -``` --\<short_form\> \<value\> -``` - -Boolean options can be enabled as follows: - -``` ---\<option\> ---<option>=[true|yes|1] -``` - -and disabled as follows: - -``` ---no\<option\> ---<option>=[false|no|0] -``` - -Tristate options are usually set to automatic by default, and can be -force-enabled as follows: - -``` ---<option>=[true|yes|1] -``` - -or force-disabled as follows: - -``` ---no\<option\> ---<option>=[false|no|0] -``` - -## Commands - -| | | -| --- | --- | -| [`aquery`](#aquery) | Analyzes the given targets and queries the action graph. | -| [`build`](#build) | Builds the specified targets. | -| [`canonicalize-flags`](#canonicalize-flags) | Canonicalizes a list of bazel options. | -| [`clean`](#clean) | Removes output files and optionally stops the server. | -| [`coverage`](#coverage) | Generates code coverage report for specified test targets. | -| [`cquery`](#cquery) | Loads, analyzes, and queries the specified targets w/ configurations. | -| [`dump`](#dump) | Dumps the internal state of the bazel server process. | -| [`fetch`](#fetch) | Fetches external repositories that are prerequisites to the targets. | -| [`help`](#help) | Prints help for commands, or the index. | -| [`info`](#info) | Displays runtime info about the bazel server. | -| [`license`](#license) | Prints the license of this software. | -| [`mobile-install`](#mobile-install) | Installs targets to mobile devices. | -| [`mod`](#mod) | Queries the Bzlmod external dependency graph | -| [`print_action`](#print_action) | Prints the command line args for compiling a file. | -| [`query`](#query) | Executes a dependency graph query. | -| [`run`](#run) | Runs the specified target. | -| [`shutdown`](#shutdown) | Stops the bazel server. | -| [`test`](#test) | Builds and runs the specified test targets. | -| [`vendor`](#vendor) | Fetches external repositories into a folder specified by the flag --vendor\_dir. | -| [`version`](#version) | Prints version information for bazel. | - -## Startup Options - -Options that appear before the command and are parsed by the client: - -`--[no]autodetect_server_javabase` default: "true" -: When --noautodetect\_server\_javabase is passed, Bazel does not fall back to the local JDK for running the bazel server and instead exits. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]batch` default: "false" -: If set, Bazel will be run as just a client process without a server, instead of in the standard client/server mode. This is deprecated and will be removed, please prefer shutting down the server explicitly if you wish to avoid lingering servers. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`deprecated`](#metadata_tag_DEPRECATED) - -`--[no]batch_cpu_scheduling` default: "false" -: Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched\_setscheduler'. If false, then Bazel does not perform a system call. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--bazelrc=<path>` multiple uses are accumulated -: The location of the user .bazelrc file containing default values of Bazel options. /dev/null indicates that all further `--bazelrc`s will be ignored, which is useful to disable the search for a user rc file, e.g. in release builds. - This option can also be specified multiple times. - E.g. with `--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc`, - - 1. x.rc and y.rc are read. - 2. z.rc is ignored due to the prior /dev/null. - If unspecified, Bazel uses the first .bazelrc file it finds in the following two locations: the workspace directory, then the user's home directory. - Note: command line options will always supersede any option in bazelrc. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--[no]block_for_lock` default: "true" -: When --noblock\_for\_lock is passed, Bazel does not wait for a running command to complete, but instead exits immediately. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]client_debug` default: "false" -: If true, log debug information from the client to stderr. Changing this option will not cause the server to restart. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--connect_timeout_secs=<an integer>` default: "30" -: The amount of time the client waits for each attempt to connect to the server - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--digest_function=<hash function>` default: see description -: The hash function to use when computing file digests. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--experimental_cgroup_parent=<path>` default: see description -: The cgroup where to start the bazel server as an absolute path. The server process will be started in the specified cgroup for each supported controller. For example, if the value of this flag is /build/bazel and the cpu and memory controllers are mounted respectively on /sys/fs/cgroup/cpu and /sys/fs/cgroup/memory, the server will be started in the cgroups /sys/fs/cgroup/cpu/build/bazel and /sys/fs/cgroup/memory/build/bazel.It is not an error if the specified cgroup is not writable for one or more of the controllers. This options does not have any effect on platforms that do not support cgroups. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_run_in_user_cgroup` default: "false" -: If true, the Bazel server will be run with systemd-run, and the user will own the cgroup. This flag only takes effect on Linux. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) - -`--failure_detail_out=<path>` default: see description -: If set, specifies a location to write a failure\_detail protobuf message if the server experiences a failure and cannot report it via gRPC, as normal. Otherwise, the location will be $\{OUTPUT\_BASE\}/failure\_detail.rawproto. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]home_rc` default: "true" -: Whether or not to look for the home bazelrc file at $HOME/.bazelrc - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--[no]idle_server_tasks` default: "true" -: Run System.gc() when the server is idle - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]ignore_all_rc_files` default: "false" -: Disables all rc files, regardless of the values of other rc-modifying flags, even if these flags come later in the list of startup options. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--io_nice_level=\{-1,0,1,2,3,4,5,6,7\}` default: "-1" -: Only on Linux; set a level from 0-7 for best-effort IO scheduling using the sys\_ioprio\_set system call. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. If set to a negative value, then Bazel does not perform a system call. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--local_startup_timeout_secs=<an integer>` default: "120" -: The maximum amount of time the client waits to connect to the server - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--macos_qos_class=<a string>` default: "default" -: Sets the QoS service class of the bazel server when running on macOS. This flag has no effect on all other platforms but is supported to ensure rc files can be shared among them without changes. Possible values are: user-interactive, user-initiated, default, utility, and background. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--max_idle_secs=<integer>` default: "10800" -: The number of seconds the build server will wait idling before shutting down. Zero means that the server will never shutdown. This is only read on server-startup, changing this option will not cause the server to restart. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--output_base=<path>` default: see description -: If set, specifies the output location to which all build output will be written. Otherwise, the location will be $\{OUTPUT\_ROOT\}/*blaze*$\{USER\}/$\{MD5\_OF\_WORKSPACE\_ROOT\}. Note: If you specify a different option from one to the next Bazel invocation for this value, you'll likely start up a new, additional Bazel server. Bazel starts exactly one server per specified output base. Typically there is one output base per workspace - however, with this option you may have multiple output bases per workspace and thereby run multiple builds for the same client on the same machine concurrently. See 'bazel help shutdown' on how to shutdown a Bazel server. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--output_user_root=<path>` default: see description -: The user-specific directory beneath which all build outputs are written; by default, this is a function of $USER, but by specifying a constant, build outputs can be shared between collaborating users. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]preemptible` default: "false" -: If true, the command can be preempted if another command is started. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]quiet` default: "false" -: If true, no informational messages are emitted on the console, only errors. Changing this option will not cause the server to restart. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--server_jvm_out=<path>` default: see description -: The location to write the server's JVM's output. If unset then defaults to a location in output\_base. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]shutdown_on_low_sys_mem` default: "false" -: If max\_idle\_secs is set and the build server has been idle for a while, shut down the server when the system is low on free RAM. Linux and MacOS only. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]system_rc` default: "true" -: Whether or not to look for the system-wide bazelrc. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--[no]unlimit_coredumps` default: "false" -: Raises the soft coredump limit to the hard limit to make coredumps of the server (including the JVM) and the client possible under common conditions. Stick this flag in your bazelrc once and forget about it so that you get coredumps when you actually encounter a condition that triggers them. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--[no]windows_enable_symlinks` default: "false" -: If true, real symbolic links will be created on Windows instead of file copying. Requires Windows developer mode to be enabled and Windows 10 version 1703 or greater. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--[no]workspace_rc` default: "true" -: Whether or not to look for the workspace bazelrc file at $workspace/.bazelrc - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Miscellaneous options, not otherwise categorized.: - -`--host_jvm_args=<jvm_arg>` multiple uses are accumulated -: Flags to pass to the JVM executing Blaze. - -`--host_jvm_debug` -: Convenience option to add some additional JVM startup flags, which cause the JVM to wait during startup until you connect from a JDWP-compliant debugger (like Eclipse) to port 5005. - - Expands to: - -   `--host_jvm_args=-agentlib:jdwp=transport=dt_socket,server=y,address=5005` - -`--server_javabase=<jvm path>` default: "" -: Path to the JVM used to execute Bazel itself. - -## Options Common to all Commands - -Options that appear before the command and are parsed by the client: - -`--distdir=<a path>` multiple uses are accumulated -: Additional places to search for archives before accessing the network to download them. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--[no]experimental_repository_cache_hardlinks` default: "false" -: If set, the repository cache will hardlink the file in case of a cache hit, rather than copying. This is intended to save disk space. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--experimental_repository_downloader_retries=<an integer>` default: "5" -: The maximum number of attempts to retry a download error. If set to 0, retries are disabled. - - Tags: - [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_scale_timeouts=<a double>` default: "1.0" -: Scale all timeouts in Starlark repository rules by this factor. In this way, external repositories can be made working on machines that are slower than the rule author expected, without changing the source code - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--http_connector_attempts=<an integer>` default: "8" -: The maximum number of attempts for http downloads. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--http_connector_retry_max_timeout=<An immutable length of time.>` default: "0s" -: The maximum timeout for http download retries. With a value of 0, no timeout maximum is defined. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--http_max_parallel_downloads=<an integer>` default: "8" -: The maximum number parallel http downloads. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--http_timeout_scaling=<a double>` default: "1.0" -: Scale all timeouts related to http downloads by the given factor - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--repo_contents_cache=<a path>` default: see description -: Specifies the location of the repo contents cache, which contains fetched repo directories shareable across workspaces. An empty string as argument requests the repo contents cache to be disabled, otherwise the default of '\<--repository\_cache\>/contents' is used. Note that this means setting '--repository\_cache=' would by default disable the repo contents cache as well, unless '--repo\_contents\_cache=\<some\_path\>' is also set. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--repo_contents_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" -: Specifies the amount of time the server must remain idle before garbage collection happens - to the repo contents cache. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--repo_contents_cache_gc_max_age=<An immutable length of time.>` default: "14d" -: Specifies the amount of time an entry in the repo contents cache can stay unused before it's garbage collected. If set to zero, only duplicate entries will be garbage collected. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--repository_cache=<a path>` default: see description -: Specifies the cache location of the downloaded values obtained during the fetching of external repositories. An empty string as argument requests the cache to be disabled, otherwise the default of '\<--output\_user\_root\>/cache/repos/v1' is used - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--[no]repository_disable_download` default: "false" -: If set, downloading using ctx.download\{,\_and\_extract\} is not allowed during repository fetching. Note that network access is not completely disabled; ctx.execute could still run an arbitrary executable that accesses the Internet. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -Options that control build execution: - -`--experimental_ui_max_stdouterr_bytes=<an integer in (-1)-1073741819 range>` default: "1048576" -: The maximum size of the stdout / stderr files that will be printed to the console. -1 implies no limit. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--gc_churning_threshold=<an integer in 0-100 range>` default: "100" -: At any point after an invocation has been running for at least one minute, if Blaze has spent at least this percentage of the invocation's wall time doing full GCs, Blaze will give up and fail with an OOM. A value of 100 effectively means to never give up for this reason. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--gc_churning_threshold_if_multiple_top_level_targets=<an integer>` default: "-1" -: If set to a value in [0, 100] and this is a command that takes top-level targets (e.g. build but not query) and there are multiple such top-level targets, overrides --gc\_churning\_threshold. Useful to configure more aggressive OOMing behavior (i.e. a lower value than --gc\_churning\_threshold) when they are multiple top-level targets so that the invoker of Bazel can split and retry while still having less aggressive behavior when there is a single top-level target. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--gc_thrashing_threshold=<an integer in 0-100 range>` default: "100" -: The percent of tenured space occupied (0-100) above which GcThrashingDetector considers memory pressure events against its limits (--gc\_thrashing\_limits). If set to 100, GcThrashingDetector is disabled. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -Options that configure the toolchain used for action execution: - -`--[no]incompatible_enable_proto_toolchain_resolution` default: "false" -: If true, proto lang rules define toolchains from protobuf repository. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--bep_maximum_open_remote_upload_files=<an integer>` default: "-1" -: Maximum number of open files allowed during BEP artifact upload. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_all` -: Downloads all remote outputs to the local machine. This flag is an alias for --remote\_download\_outputs=all. - - Expands to: - -   `--remote_download_outputs=all` - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_minimal` -: Does not download any remote build outputs to the local machine. This flag is an alias for --remote\_download\_outputs=minimal. - - Expands to: - -   `--remote_download_outputs=minimal` - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_outputs=<all, minimal or toplevel>` default: "toplevel" -: If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_symlink_template=<a string>` default: "" -: Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain \{hash\} and \{size\_bytes\} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_toplevel` -: Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote\_download\_outputs=toplevel. - - Expands to: - -   `--remote_download_outputs=toplevel` - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--repo_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies additional environment variables to be available only for repository rules. Note that repository rules see the full environment anyway, but in this way variables can be set via command-line flags and \<code\>.bazelrc\</code\> entries. The special syntax \<code>=NAME</code\> can be used to explicitly unset a variable. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]allow_experimental_loads` default: "false" -: If enabled, issue only a warning instead of an error for loads of experimental .bzls. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]check_bzl_visibility` default: "true" -: If disabled, .bzl load visibility errors are demoted to warnings. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]incompatible_enforce_starlark_utf8` default: "warning" -: If enabled (or set to 'error'), fail if Starlark files are not UTF-8 encoded. If set to 'warning', emit a warning instead. If set to 'off', Bazel assumes that Starlark files are UTF-8 encoded but does not verify this assumption. Note that Starlark files which are not UTF-8 encoded can cause Bazel to behave inconsistently. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]experimental_bzl_visibility` default: "true" -: If enabled, adds a `visibility()` function that .bzl files may call during top-level evaluation to set their visibility for the purpose of load() statements. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_cc_shared_library` default: "false" -: If set to true, rule attributes and Starlark API methods needed for the rule cc\_shared\_library will be available - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_disable_external_package` default: "false" -: If set to true, the auto-generated //external package will not be available anymore. Bazel will still be unable to parse the file 'external/BUILD', but globs reaching into external/ from the unnamed package will work. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_dormant_deps` default: "false" -: If set to true, attr.label(materializer=), attr(for\_dependency\_resolution=), attr.dormant\_label(), attr.dormant\_label\_list() and rule(for\_dependency\_resolution=) are allowed. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_enable_android_migration_apis` default: "false" -: If set to true, enables the APIs required to support the Android Starlark migration. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]experimental_enable_first_class_macros` default: "true" -: If set to true, enables the `macro()` construct for defining symbolic macros. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]experimental_enable_scl_dialect` default: "true" -: If set to true, .scl files may be used in load() statements. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]experimental_enable_starlark_set` default: "true" -: If true, enable the set data type and set() constructor in Starlark. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_google_legacy_api` default: "false" -: If set to true, exposes a number of experimental pieces of Starlark build API pertaining to Google legacy code. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_isolated_extension_usages` default: "false" -: If true, enables the \<code\>isolate\</code\> parameter in the <a href="https://bazel.build/rules/lib/globals/module#use\_extension">\<code\>use\_extension\</code\>\</a\> function. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]experimental_platforms_api` default: "false" -: If set to true, enables a number of platform-related Starlark APIs useful for debugging. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_repo_remote_exec` default: "false" -: If set to true, repository\_rule gains some remote execution capabilities. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_repository_ctx_execute_wasm` default: "false" -: If true enables the repository\_ctx `load_wasm` and `execute_wasm` methods. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_sibling_repository_layout` default: "false" -: If set to true, non-main repositories are planted as symlinks to the main repository in the execution root. That is, all repositories are direct children of the $output\_base/execution\_root directory. This has the side effect of freeing up $output\_base/execution\_root/**main**/external for the real top-level 'external' directory. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_single_package_toolchain_binding` default: "false" -: If enabled, the register\_toolchain function may not include target patterns which may refer to more than one package. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]experimental_starlark_types` default: "false" -: Enables type annotations and type checking. Locations where the annotations are allowed is further controlled by `--experimental_starlark_types_allowed_paths`. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_starlark_types_allowed_paths=<comma-separated list of options>` default: "" -: List of canonical Label prefixes under which Starlark type annotations are allowed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_allow_tags_propagation` default: "true" -: If set to true, tags will be propagated from a target to the actions' execution requirements; otherwise tags are not propagated. See https://github.com/bazelbuild/bazel/issues/8830 for details. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_always_check_depset_elements` default: "true" -: Check the validity of elements added to depsets, in all constructors. Elements must be immutable, but historically the depset(direct=...) constructor forgot to check. Use tuples instead of lists in depset elements. See https://github.com/bazelbuild/bazel/issues/10313 for details. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_autoload_externally=<comma-separated set of options>` default: "+@rules\_cc" -: A comma-separated list of rules (or other symbols) that were previously part of Bazel and which are now to be retrieved from their respective external repositories. This flag is intended to be used to facilitate migration of rules out of Bazel. See also https://github.com/bazelbuild/bazel/issues/23043. - A symbol that is autoloaded within a file behaves as if its built-into-Bazel definition were replaced by its canonical new definition in an external repository. For a BUILD file, this essentially means implicitly adding a load() statement. For a .bzl file, it's either a load() statement or a change to a field of the `native` object, depending on whether the autoloaded symbol is a rule. - Bazel maintains a hardcoded list of all symbols that may be autoloaded; only those symbols may appear in this flag. For each symbol, Bazel knows the new definition location in an external repository, as well as a set of special-cased repositories that must not autoload it to avoid creating cycles. - A list item of "+foo" in this flag causes symbol foo to be autoloaded, except in foo's exempt repositories, within which the Bazel-defined version of foo is still available. - A list item of "foo" triggers autoloading as above, but the Bazel-defined version of foo is not made available to the excluded repositories. This ensures that foo's external repository does not depend on the old Bazel implementation of foo - A list item of "-foo" does not trigger any autoloading, but makes the Bazel-defined version of foo inaccessible throughout the workspace. This is used to validate that the workspace is ready for foo's definition to be deleted from Bazel. - If a symbol is not named in this flag then it continues to work as normal -- no autoloading is done, nor is the Bazel-defined version suppressed. For configuration see https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/packages/AutoloadSymbols.java As a shortcut also whole repository may be used, for example +@rules\_python will autoload all Python rules. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_autoloads_in_main_repo` default: "true" -: Controls if the autoloads (set by --incompatible\_autoload\_externally) are enabled in themain repository. When enabled the rules (or other symbols) that were previously part of Bazel need to have load statements. Use buildifier to add them. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_objc_library_transition` default: "true" -: Disable objc\_library's custom transition and inherit from the top level target instead (No-op in Bazel) - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_starlark_host_transitions` default: "false" -: If set to true, rule attributes cannot set 'cfg = "host"'. Rules should set 'cfg = "exec"' instead. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_target_default_provider_fields` default: "false" -: If set to true, disable the ability to utilize the default provider via field syntax. Use provider-key syntax instead. For example, instead of using `ctx.attr.dep.files` to access `files`, utilize `ctx.attr.dep[DefaultInfo].files See https://github.com/bazelbuild/bazel/issues/9014 for details. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_disable_transitions_on=<comma-separated set of options>` default: "" -: A comma-separated list of flags that cannot be used in transitions inputs or outputs. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_disallow_ctx_resolve_tools` default: "true" -: If set to true, calling the deprecated ctx.resolve\_tools API always fails. Uses of this API should be replaced by an executable or tools argument to ctx.actions.run or ctx.actions.run\_shell. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disallow_empty_glob` default: "true" -: If set to true, the default value of the `allow_empty` argument of glob() is False. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enable_deprecated_label_apis` default: "true" -: If enabled, certain deprecated APIs (native.repository\_name, Label.workspace\_name, Label.relative) can be used. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]incompatible_fail_on_unknown_attributes` default: "true" -: If enabled, targets that have unknown attributes set to None fail. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_fix_package_group_reporoot_syntax` default: "true" -: In package\_group's `packages` attribute, changes the meaning of the value "//..." to refer to all packages in the current repository instead of all packages in any repository. You can use the special value "public" in place of "//..." to obtain the old behavior. This flag requires that --incompatible\_package\_group\_has\_public\_syntax also be enabled. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_locations_prefers_executable` default: "true" -: Whether a target that provides an executable expands to the executable rather than the files in \<code\>DefaultInfo.files\</code\> under $(locations ...) expansion if the number of files is not 1. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_no_attr_license` default: "true" -: If set to true, disables the function `attr.license`. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_no_implicit_file_export` default: "false" -: If set, (used) source files are package private unless exported explicitly. See https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_no_implicit_watch_label` default: "true" -: If true, then methods on \<code\>repository\_ctx\</code\> that are passed a Label will no longer automatically watch the file under that label for changes even if \<code\>watch = "no"\</code\>, and \<code\>repository\_ctx.path\</code\> no longer causes the returned path to be watched. Use \<code\>repository\_ctx.watch\</code\> instead. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_no_rule_outputs_param` default: "false" -: If set to true, disables the `outputs` parameter of the `rule()` Starlark function. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_package_group_has_public_syntax` default: "true" -: In package\_group's `packages` attribute, allows writing "public" or "private" to refer to all packages or no packages respectively. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_resolve_select_keys_eagerly` default: "false" -: If enabled, string keys in dicts passed to select() in .bzl files are immediately resolved to Labels relative to the file instead of being interpreted relative to the BUILD file they are ultimately loaded from. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_run_shell_command_string` default: "true" -: If set to true, the command parameter of actions.run\_shell will only accept string - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_simplify_unconditional_selects_in_rule_attrs` default: "true" -: If true, simplify configurable rule attributes which contain only unconditional selects; for example, if ["a"] + select("//conditions:default", ["b"]) is assigned to a rule attribute, it is stored as ["a", "b"]. This option does not affect attributes of symbolic macros or attribute default values. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_stop_exporting_build_file_path` default: "false" -: If set to true, deprecated ctx.build\_file\_path will not be available. ctx.label.package + '/BUILD' can be used instead. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_stop_exporting_language_modules` default: "false" -: If enabled, certain language-specific modules (such as `cc_common`) are unavailable in user .bzl files and may only be called from their respective rules repositories. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_unambiguous_label_stringification` default: "true" -: When true, Bazel will stringify the label @//foo:bar to @//foo:bar, instead of //foo:bar. This only affects the behavior of str(), the % operator, and so on; the behavior of repr() is unchanged. See https://github.com/bazelbuild/bazel/issues/15916 for more information. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_use_cc_configure_from_rules_cc` default: "false" -: When true, Bazel will no longer allow using cc\_configure from @bazel\_tools. Please see https://github.com/bazelbuild/bazel/issues/10134 for details and migration instructions. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--max_computation_steps=<a long integer>` default: "0" -: The maximum number of Starlark computation steps that may be executed by a BUILD file (zero means no limit). - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--nested_set_depth_limit=<an integer>` default: "3500" -: The maximum depth of the graph internal to a depset (also known as NestedSet), above which the depset() constructor will fail. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--repositories_without_autoloads=<comma-separated set of options>` default: "" -: A list of additional repositories (beyond the hardcoded ones Bazel knows about) where autoloads are not to be added. This should typically contain repositories that are transitively depended on by a repository that may be loaded automatically (and which can therefore potentially create a cycle). - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options relating to Bzlmod output and semantics: - -`--allow_yanked_versions=<a string>` multiple uses are accumulated -: Specified the module versions in the form of `<module1>@<version1>,<module2>@<version2>` that will be allowed in the resolved dependency graph even if they are declared yanked in the registry where they come from (if they are not coming from a NonRegistryOverride). Otherwise, yanked versions will cause the resolution to fail. You can also define allowed yanked version with the `BZLMOD_ALLOW_YANKED_VERSIONS` environment variable. You can disable this check by using the keyword 'all' (not recommended). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--check_bazel_compatibility=<error, warning or off>` default: "error" -: Check bazel version compatibility of Bazel modules. Valid values are `error` to escalate it to a resolution failure, `off` to disable the check, or `warning` to print a warning when mismatch detected. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--check_direct_dependencies=<off, warning or error>` default: "warning" -: Check if the direct `bazel_dep` dependencies declared in the root module are the same versions you get in the resolved dependency graph. Valid values are `off` to disable the check, `warning` to print a warning when mismatch detected or `error` to escalate it to a resolution failure. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]ignore_dev_dependency` default: "false" -: If true, Bazel ignores `bazel_dep` and `use_extension` declared as `dev_dependency` in the MODULE.bazel of the root module. Note that, those dev dependencies are always ignored in the MODULE.bazel if it's not the root module regardless of the value of this flag. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--lockfile_mode=<off, update, refresh or error>` default: "update" -: Specifies how and whether or not to use the lockfile. Valid values are `update` to use the lockfile and update it if there are changes, `refresh` to additionally refresh mutable information (yanked versions and previously missing modules) from remote registries from time to time, `error` to use the lockfile but throw an error if it's not up-to-date, or `off` to neither read from or write to the lockfile. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--module_mirrors=<comma-separated list of options>` default: see description -: A comma-separated list of URLs under which the source URLs of Bazel modules can be found, - in addition to and taking precedence over any registry-provided mirror URLs. Set this to - an empty value to disable the use of any mirrors not specified by the registries. The - default set of mirrors may change over time, but all downloads from mirrors are verified - by hashes stored in the registry (and thus pinned by the lockfile). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--override_module=<an equals-separated mapping of module name to path>` multiple uses are accumulated -: Override a module with a local path in the form of <module name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. - -`--registry=<a string>` multiple uses are accumulated -: Specifies the registries to use to locate Bazel module dependencies. The order is important: modules will be looked up in earlier registries first, and only fall back to later registries when they're missing from the earlier ones. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--vendor_dir=<a path>` default: see description -: Specifies the directory that should hold the external repositories in vendor mode, whether for the purpose of fetching them into it or using them while building. The path can be specified as either an absolute path or a path relative to the workspace directory. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options that trigger optimizations of the build time: - -`--gc_thrashing_limits=<comma separated pairs of <period>:<count>>` default: "1s:2,20s:3,1m:5" -: Limits which, if reached, cause GcThrashingDetector to crash Bazel with an OOM. Each limit is specified as \<period\>:\<count\> where period is a duration and count is a positive integer. If more than --gc\_thrashing\_threshold percent of tenured space (old gen heap) remains occupied after \<count\> consecutive full GCs within \<period\>, an OOM is triggered. Multiple limits can be specified separated by commas. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]heuristically_drop_nodes` default: "false" -: If true, Blaze will remove FileState and DirectoryListingState nodes after related File and DirectoryListing node is done to save memory. We expect that it is less likely that these nodes will be needed again. If so, the program will re-evaluate them. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]incompatible_do_not_split_linking_cmdline` default: "true" -: When true, Bazel no longer modifies command line flags used for linking, and also doesn't selectively decide which flags go to the param file and which don't. See https://github.com/bazelbuild/bazel/issues/7670 for details. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]keep_state_after_build` default: "true" -: If false, Blaze will discard the inmemory state from this build when the build finishes. Subsequent builds will not have any incrementality with respect to this one. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--skyframe_high_water_mark_full_gc_drops_per_invocation=<an integer, >= 0>` default: "10" -: Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe\_high\_water\_mark\_threshold, when a full GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that full GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a full GC event occurs and that retained heap percentage threshold is exceeded. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--skyframe_high_water_mark_minor_gc_drops_per_invocation=<an integer, >= 0>` default: "10" -: Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe\_high\_water\_mark\_threshold, when a minor GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that minor GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a minor GC event occurs and that retained heap percentage threshold is exceeded. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--skyframe_high_water_mark_threshold=<an integer>` default: "85" -: Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage is at least this threshold, it will drop unnecessary temporary Skyframe state. Tweaking this may let you mitigate wall time impact of GC thrashing, when the GC thrashing is (i) caused by the memory usage of this temporary state and (ii) more costly than reconstituting the state when it is needed. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]track_incremental_state` default: "true" -: If false, Blaze will not persist data that allows for invalidation and re-evaluation on incremental builds in order to save memory on this build. Subsequent builds will not have any incrementality with respect to this one. Usually you will want to specify --batch when setting this to false. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -Options that affect the verbosity, format or location of logging: - -`--[no]announce_rc` default: "false" -: Whether to announce rc options. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]attempt_to_print_relative_paths` default: "false" -: When printing the location part of messages, attempt to use a path relative to the workspace directory or one of the directories specified by --package\_path. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--bes_backend=<a string>` default: "" -: Specifies the build event service (BES) backend endpoint in the form [SCHEME://]HOST[:PORT]. The default is to disable BES uploads. Supported schemes are grpc and grpcs (grpc with TLS enabled). If no scheme is provided, Bazel assumes grpcs. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]bes_check_preceding_lifecycle_events` default: "false" -: Sets the field check\_preceding\_lifecycle\_events\_present on PublishBuildToolEventStreamRequest which tells BES to check whether it previously received InvocationAttemptStarted and BuildEnqueued events matching the current tool event. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--bes_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header in NAME=VALUE form that will be included in BES requests. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--bes_instance_name=<a string>` default: see description -: Specifies the instance name under which the BES will persist uploaded BEP. Defaults to null. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--bes_keywords=<comma-separated list of options>` multiple uses are accumulated -: Specifies a list of notification keywords to be added the default set of keywords published to BES ("command\_name=\<command\_name\> ", "protocol\_name=BEP"). Defaults to none. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]bes_lifecycle_events` default: "true" -: Specifies whether to publish BES lifecycle events. (defaults to 'true'). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--bes_oom_finish_upload_timeout=<An immutable length of time.>` default: "10m" -: Specifies how long bazel should wait for the BES/BEP upload to complete while OOMing. This flag ensures termination when the JVM is severely GC thrashing and cannot make progress on any user thread. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--bes_outerr_buffer_size=<an integer>` default: "10240" -: Specifies the maximal size of stdout or stderr to be buffered in BEP, before it is reported as a progress event. Individual writes are still reported in a single event, even if larger than the specified value up to --bes\_outerr\_chunk\_size. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--bes_outerr_chunk_size=<an integer>` default: "1048576" -: Specifies the maximal size of stdout or stderr to be sent to BEP in a single message. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--bes_proxy=<a string>` default: see description -: Connect to the Build Event Service through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). - -`--bes_results_url=<a string>` default: "" -: Specifies the base URL where a user can view the information streamed to the BES backend. Bazel will output the URL appended by the invocation id to the terminal. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--bes_system_keywords=<comma-separated list of options>` multiple uses are accumulated -: Specifies a list of notification keywords to be included directly, without the "user\_keyword=" prefix included for keywords supplied via --bes\_keywords. Intended for Build service operators that set --bes\_lifecycle\_events=false and include keywords when calling PublishLifecycleEvent. Build service operators using this flag should prevent users from overriding the flag value. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--bes_timeout=<An immutable length of time.>` default: "0s" -: Specifies how long bazel should wait for the BES/BEP upload to complete after the build and tests have finished. A valid timeout is a natural number followed by a unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The default value is '0' which means that there is no timeout. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--bes_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" -: Specifies whether the Build Event Service upload should block the build completion or should end the invocation immediately and finish the upload in the background. - - * `wait_for_upload_complete`: blocks at the end of the current invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. - * `nowait_for_upload_complete`: blocks at the beginning of the next invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. - * `fully_async`: blocks at the beginning of the next invocation until all events are uploaded but does not wait for acknowledgements. Events may be lost in case of (transient) failures and backends may report streams as incomplete in this mode. There is no guarantee that `FinishInvocationAttempt` or `FinishBuild` lifecycle events are sent. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--build_event_binary_file=<a string>` default: "" -: If non-empty, write a varint delimited binary representation of representation of the build event protocol to that file. This option implies --bes\_upload\_mode=wait\_for\_upload\_complete. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_event_binary_file_path_conversion` default: "true" -: Convert paths in the binary file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--build_event_binary_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" -: Specifies whether the Build Event Service upload for --build\_event\_binary\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--build_event_json_file=<a string>` default: "" -: If non-empty, write a JSON serialisation of the build event protocol to that file. This option implies --bes\_upload\_mode=wait\_for\_upload\_complete. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_event_json_file_path_conversion` default: "true" -: Convert paths in the json file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--build_event_json_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" -: Specifies whether the Build Event Service upload for --build\_event\_json\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--build_event_max_named_set_of_file_entries=<an integer>` default: "5000" -: The maximum number of entries for a single named\_set\_of\_files event; values smaller than 2 are ignored and no event splitting is performed. This is intended for limiting the maximum event size in the build event protocol, although it does not directly control event size. The total event size is a function of the structure of the set as well as the file and uri lengths, which may in turn depend on the hash function. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_event_publish_all_actions` default: "false" -: Whether all actions should be published. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--build_event_text_file=<a string>` default: "" -: If non-empty, write a textual representation of the build event protocol to that file - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_event_text_file_path_conversion` default: "true" -: Convert paths in the text file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--build_event_text_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" -: Specifies whether the Build Event Service upload for --build\_event\_text\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--build_event_upload_max_retries=<an integer>` default: "4" -: The maximum number of times Bazel should retry uploading a build event. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--[no]experimental_bep_target_summary` default: "false" -: Whether to publish TargetSummary events. - -`--[no]experimental_build_event_expand_filesets` default: "false" -: If true, expand Filesets in the BEP when presenting output files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--experimental_build_event_output_group_mode=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated -: Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED\_SET\_OF\_FILES\_ONLY', 'INLINE\_ONLY', or 'BOTH'. The default value is 'NAMED\_SET\_OF\_FILES\_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental\_build\_event\_output\_group\_mode=baseline.lcov=both - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--experimental_build_event_upload_retry_minimum_delay=<An immutable length of time.>` default: "1s" -: Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--experimental_build_event_upload_strategy=<a string>` default: see description -: Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_collect_load_average_in_profiler` default: "true" -: If enabled, the profiler collects the system's overall load average. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_collect_pressure_stall_indicators` default: "false" -: If enabled, the profiler collects the Linux PSI data. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_collect_resource_estimation` default: "false" -: If enabled, the profiler collects CPU and memory usage estimation for local actions. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_collect_skyframe_counts_in_profiler` default: "false" -: If enabled, the profiler collects SkyFunction counts in the Skyframe graph over time for key function types, like configured targets and action executions. May have a performance hit as this visits the ENTIRE Skyframe graph at every profiling time unit. Do not use this flag with performance-critical measurements. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_collect_system_network_usage` default: "true" -: If enabled, the profiler collects the system's network usage. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_collect_worker_data_in_profiler` default: "true" -: If enabled, the profiler collects worker's aggregated resource data. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--experimental_command_profile=<cpu, wall, alloc or lock>` default: see description -: Records a Java Flight Recorder profile for the duration of the command. One of the supported profiling event types (cpu, wall, alloc or lock) must be given as an argument. The profile is written to a file named after the event type under the output base directory. The syntax and semantics of this flag might change in the future to support additional profile types or output formats; use at your own risk. - -`--experimental_profile_additional_tasks=<phase, action, discover_inputs, action_check, action_lock, action_update, action_complete, action_rewinding, bzlmod, info, create_package, remote_execution, local_execution, scanner, local_parse, upload_time, remote_process_time, remote_queue, remote_setup, fetch, local_process_time, vfs_stat, vfs_dir, vfs_readlink, vfs_md5, vfs_xattr, vfs_delete, vfs_open, vfs_read, vfs_write, vfs_glob, vfs_vmfs_stat, vfs_vmfs_dir, vfs_vmfs_read, wait, thread_name, thread_sort_index, skyframe_eval, skyfunction, critical_path, critical_path_component, handle_gc_notification, local_action_counts, starlark_parser, starlark_user_fn, starlark_builtin_fn, starlark_user_compiled_fn, starlark_repository_fn, action_fs_staging, remote_cache_check, remote_download, remote_network, filesystem_traversal, worker_execution, worker_setup, worker_borrow, worker_working, worker_copying_outputs, credential_helper, conflict_check, dynamic_lock, repository_fetch, repository_vendor, repo_cache_gc_wait, spawn_log, rpc, skycache, wasm_load, wasm_exec or unknown>` multiple uses are accumulated -: Specifies additional profile tasks to be included in the profile. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_profile_include_primary_output` default: "false" -: Includes the extra "out" attribute in action events that contains the exec path to the action's primary output. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_profile_include_target_configuration` default: "false" -: Includes target configuration hash in action events' JSON profile data. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_profile_include_target_label` default: "false" -: Includes target label in action events' JSON profile data. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_record_metrics_for_all_mnemonics` default: "false" -: Controls the output of BEP ActionSummary and BuildGraphMetrics, limiting the number of mnemonics in ActionData and number of entries reported in BuildGraphMetrics.AspectCount/RuleClassCount. By default the number of types is limited to the top 20, by number of executed actions for ActionData, and instances for RuleClass and Asepcts. Setting this option will write statistics for all mnemonics, rule classes and aspects. - -`--[no]experimental_record_skyframe_metrics` default: "false" -: Controls the output of BEP BuildGraphMetrics, including expensiveto compute skyframe metrics about Skykeys, RuleClasses and Aspects.With this flag set to false BuildGraphMetrics.rule\_count and aspectfields will not be populated in the BEP. - -`--[no]experimental_run_bep_event_include_residue` default: "false" -: Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_stream_log_file_uploads` default: "false" -: Stream log file uploads directly to the remote storage rather than writing them to disk. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--experimental_workspace_rules_log_file=<a path>` default: see description -: Log certain Workspace Rules events into this file as delimited WorkspaceEvent protos. - -`--[no]generate_json_trace_profile` default: "auto" -: If enabled, Bazel profiles the build and writes a JSON-format profile into a file in the output base. View profile by loading into chrome://tracing. By default Bazel writes the profile for all build-like commands and query. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]heap_dump_on_oom` default: "false" -: Whether to manually output a heap dump if an OOM is thrown (including manual OOMs due to reaching --gc\_thrashing\_limits). The dump will be written to \<output\_base\>/\<invocation\_id\>.heapdump.hprof. This option effectively replaces -XX:+HeapDumpOnOutOfMemoryError, which has no effect for manual OOMs. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--jvm_heap_histogram_internal_object_pattern=<a valid Java regular expression>` default: "jdk\.internal\.vm\.Filler.+" -: Regex for overriding the matching logic for JDK21+ JVM heap memory collection. We are relying on volatile internal G1 GC implemenation details to get a clean memory metric, this option allows us to adapt to changes in that internal implementation without having to wait for a binary release. Passed to JDK Matcher.find() - -`--[no]legacy_important_outputs` default: "false" -: Use this to suppress generation of the legacy important\_outputs field in the TargetComplete event. important\_outputs are required for Bazel to ResultStore/BTX integration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--logging=<0 <= an integer <= 6>` default: "3" -: The logging level. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--memory_profile=<a path>` default: see description -: If set, write memory usage data to the specified file at phase ends and stable heap to master log at end of build. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--memory_profile_stable_heap_parameters=<integers, separated by a comma expected in pairs>` default: "1,0" -: Tune memory profile's computation of stable heap at end of build. Should be and even number of integers separated by commas. In each pair the first integer is the number of GCs to perform. The second integer in each pair is the number of seconds to wait between GCs. Ex: 2,4,4,0 would 2 GCs with a 4sec pause, followed by 4 GCs with zero second pause - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--profile=<a path>` default: see description -: If set, profile Bazel and write data to the specified file. See https://bazel.build/advanced/performance/json-trace-profile for more information. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--profiles_to_retain=<an integer>` default: "5" -: Number of profiles to retain in the output base. If there are more than this number of profiles in the output base, the oldest are deleted until the total is under the limit. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]record_full_profiler_data` default: "false" -: By default, Bazel profiler will record only aggregated data for fast but numerous events (such as statting the file). If this option is enabled, profiler will record each event - resulting in more precise profiling data but LARGE performance hit. Option only has effect if --profile used as well. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]redirect_local_instrumentation_output_writes` default: "false" -: If true and supported, instrumentation output is redirected to be written locally on a different machine than where bazel is running on. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--remote_print_execution_messages=<failure, success or all>` default: "failure" -: Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]slim_profile` default: "true" -: Slims down the size of the JSON profile by merging events if the profile gets too large. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--starlark_cpu_profile=<a string>` default: "" -: Writes into the specified file a pprof profile of CPU usage by all Starlark threads. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--tool_tag=<a string>` default: "" -: A tool name to attribute this Bazel invocation to. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--ui_event_filters=<Convert list of comma separated event kind to list of filters>` multiple uses are accumulated -: Specifies which events to show in the UI. It is possible to add or remove events to the default ones using leading +/-, or override the default set completely with direct assignment. The set of supported event kinds include INFO, DEBUG, ERROR and more. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]write_command_log` default: "false" -: Whether or not to write the command.log file - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -Remote caching and execution options: - -`--downloader_config=<a path>` default: see description -: Specify a file to configure the remote downloader with. This file consists of lines, each of which starts with a directive (`allow`, `block` or `rewrite`) followed by either a host name (for `allow` and `block`) or two patterns, one to match against, and one to use as a substitute URL, with back-references starting from `$1`. It is possible for multiple `rewrite` directives for the same URL to be given, and in this case multiple URLs will be returned. - -`--experimental_circuit_breaker_strategy=<failure>` default: see description -: Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_remote_cache_compression_threshold=<an integer>` default: "100" -: The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote\_cache\_compression is set. - -`--[no]experimental_remote_cache_lease_extension` default: "false" -: If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. - -`--experimental_remote_cache_ttl=<An immutable length of time.>` default: "3h" -: The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_remote_capture_corrupted_outputs=<a path>` default: see description -: A path to a directory where the corrupted outputs will be captured to. - -`--[no]experimental_remote_discard_merkle_trees` default: "true" -: If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. - -`--experimental_remote_downloader=<a string>` default: see description -: A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote\_asset.proto - -`--[no]experimental_remote_downloader_local_fallback` default: "false" -: Whether to fall back to the local downloader if remote downloader fails. - -`--[no]experimental_remote_downloader_propagate_credentials` default: "false" -: Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. - -`--[no]experimental_remote_execution_keepalive` default: "false" -: Whether to use keepalive for remote execution calls. - -`--experimental_remote_failure_rate_threshold=<an integer in 0-100 range>` default: "10" -: Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_remote_failure_window_interval=<An immutable length of time.>` default: "60s" -: The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_remote_mark_tool_inputs` default: "false" -: If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. - -`--[no]experimental_remote_merkle_tree_cache` default: "false" -: If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental\_remote\_merkle\_tree\_cache\_size. - -`--experimental_remote_merkle_tree_cache_size=<a long integer>` default: "1000" -: The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. - -`--experimental_remote_output_service=<a string>` default: see description -: HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. - -`--experimental_remote_output_service_output_path_prefix=<a string>` default: "" -: The path under which the contents of output directories managed by the --experimental\_remote\_output\_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. - -`--[no]experimental_remote_require_cached` default: "false" -: If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. - -`--experimental_remote_scrubbing_config=<Converts to a Scrubber>` default: see description -: Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote\_scrubbing.proto). - - This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. - - Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. - - Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. - - In order to successfully use this feature, you likely want to set a custom --host\_platform together with --experimental\_platform\_in\_output\_dir (to normalize output prefixes) and --incompatible\_strict\_action\_env (to normalize environment variables). - -`--[no]guard_against_concurrent_changes` default: "lite" -: Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]remote_accept_cached` default: "true" -: Whether to accept remotely cached action results. - -`--remote_build_event_upload=<all or minimal>` default: "minimal" -: If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. - If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. - Default to 'minimal'. - -`--remote_bytestream_uri_prefix=<a string>` default: see description -: The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote\_executor and --remote\_instance\_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "$\{hostname\}/$\{instance\_name\}". - -`--remote_cache=<a string>` default: see description -: A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching - -`--[no]remote_cache_async` default: "true" -: If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. - -`--[no]remote_cache_compression` default: "false" -: If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental\_remote\_cache\_compression\_threshold. - -`--remote_cache_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header that will be included in cache requests: --remote\_cache\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - -`--remote_default_exec_properties=<a 'name=value' assignment>` multiple uses are accumulated -: Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec\_properties. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_default_platform_properties=<a string>` default: "" -: Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote\_execution\_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. - -`--remote_download_regex=<a valid Java regular expression>` multiple uses are accumulated -: Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote\_download\_outputs. Multiple patterns may be specified by repeating this flag. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_downloader_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header that will be included in remote downloader requests: --remote\_downloader\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - -`--remote_exec_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header that will be included in execution requests: --remote\_exec\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - -`--remote_execution_priority=<an integer>` default: "0" -: The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. - -`--remote_executor=<a string>` default: see description -: HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. - -`--remote_grpc_log=<a path>` default: see description -: If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). - -`--remote_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header that will be included in requests: --remote\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - -`--remote_instance_name=<a string>` default: "" -: Value to pass as instance\_name in the remote execution API. - -`--[no]remote_local_fallback` default: "false" -: Whether to fall back to standalone local execution strategy if remote execution fails. - -`--remote_local_fallback_strategy=<a string>` default: "local" -: Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. - -`--remote_max_connections=<an integer>` default: "100" -: Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. - For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote\_max\_connections concurrent requests. - For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--remote_proxy=<a string>` default: see description -: Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). - -`--remote_result_cache_priority=<an integer>` default: "0" -: The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. - -`--remote_retries=<an integer>` default: "5" -: The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. - -`--remote_retry_max_delay=<An immutable length of time.>` default: "5s" -: The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. - -`--remote_timeout=<An immutable length of time.>` default: "60s" -: The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. - -`--[no]remote_upload_local_results` default: "true" -: Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. - -`--[no]remote_verify_downloads` default: "true" -: If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. - -Miscellaneous options, not otherwise categorized.: - -`--build_metadata=<a 'name=value' assignment>` multiple uses are accumulated -: Custom key-value string pairs to supply in a build event. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--color=<yes, no or auto>` default: "auto" -: Use terminal controls to colorize output. - -`--config=<a string>` multiple uses are accumulated -: Selects additional config sections from the rc files; for every \<command\>, it also pulls in the options from \<command\>:\<config\> if such a section exists; if this section doesn't exist in any .rc file, Blaze fails with an error. The config sections and flag combinations they are equivalent to are located in the tools/\*.blazerc config files. - -`--credential_helper=<Path to a credential helper. It may be absolute, relative to the PATH environment variable, or %workspace%-relative. The path be optionally prefixed by a scope followed by an '='. The scope is a domain name, optionally with a single leading '*' wildcard component. A helper applies to URIs matching its scope, with more specific scopes preferred. If a helper has no scope, it applies to every URI.>` multiple uses are accumulated -: Configures a credential helper conforming to the <a href="https://github.com/EngFlow/credential-helper-spec">Credential Helper Specification\</a\> to use for retrieving authorization credentials for repository fetching, remote caching and execution, and the build event service. - - Credentials supplied by a helper take precedence over credentials supplied by `--google_default_credentials`, `--google_credentials`, a `.netrc` file, or the auth parameter to `repository_ctx.download()` and `repository_ctx.download_and_extract()`. - - May be specified multiple times to set up multiple helpers. - - See https://blog.engflow.com/2023/10/09/configuring-bazels-credential-helper/ for instructions. - -`--credential_helper_cache_duration=<An immutable length of time.>` default: "30m" -: How long to cache credentials for if the credential helper doesn't return an expiration time. Changing the value of this flag clears the cache. - -`--credential_helper_timeout=<An immutable length of time.>` default: "10s" -: Configures the timeout for a credential helper. - - Credential helpers failing to respond within this timeout will fail the invocation. - -`--curses=<yes, no or auto>` default: "auto" -: Use terminal cursor controls to minimize scrolling output. - -`--disk_cache=<a path>` default: see description -: A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. - -`--[no]enable_platform_specific_config` default: "true" -: If true, Bazel picks up host-OS-specific config lines from bazelrc files. For example, if the host OS is Linux and you run bazel build, Bazel picks up lines starting with build:linux. Supported OS identifiers are linux, macos, windows, freebsd, and openbsd. Enabling this flag is equivalent to using --config=linux on Linux, --config=windows on Windows, etc. - -`--experimental_action_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" -: How long the server must remain idle before a garbage collection of the action cache is attempted. Ineffectual unless --experimental\_action\_cache\_gc\_max\_age is nonzero. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--experimental_action_cache_gc_max_age=<An immutable length of time.>` default: "0" -: If set to a nonzero value, the action cache will be periodically garbage collected to remove entries older than this age. Garbage collection occurs in the background once the server has become idle, as determined by the --experimental\_action\_cache\_gc\_idle\_delay and --experimental\_action\_cache\_gc\_threshold flags. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--experimental_action_cache_gc_threshold=<an integer in 0-100 range>` default: "10" -: The percentage of stale action cache entries required for garbage collection to be triggered. Ineffectual unless --experimental\_action\_cache\_gc\_max\_age is nonzero. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--experimental_disk_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" -: How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental\_disk\_cache\_gc\_max\_size and/or --experimental\_disk\_cache\_gc\_max\_age. - -`--experimental_disk_cache_gc_max_age=<An immutable length of time.>` default: "0" -: If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. - -`--experimental_disk_cache_gc_max_size=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" -: If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. - -`--[no]experimental_enable_thread_dump` default: "false" -: Whether to enable thread dumps. If true, Bazel will dump the state of all threads (including virtual threads) to a file every --experimental\_thread\_dump\_interval, or after action execution being inactive for --experimental\_thread\_dump\_action\_execution\_inactivity\_duration. The dumps will be written to the \<output\_base\>/server/thread\_dumps/ directory. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--experimental_install_base_gc_max_age=<An immutable length of time.>` default: "30d" -: How long an install base must go unused before it's eligible for garbage collection. If nonzero, the server will attempt to garbage collect other install bases when idle. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]experimental_rule_extension_api` default: "true" -: Enable experimental rule extension API and subrule APIs - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_thread_dump_action_execution_inactivity_duration=<An immutable length of time.>` default: "0" -: Dump the threads when action execution being inactive for this duration. If zero, no thread dumps are written for action execution being inactive. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--experimental_thread_dump_interval=<An immutable length of time.>` default: "0" -: How often to dump the threads periodically. If zero, no thread dumps are written periodically. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]experimental_windows_watchfs` default: "false" -: If true, experimental Windows support for --watchfs is enabled. Otherwise --watchfsis a non-op on Windows. Make sure to also enable --watchfs. - -`--google_auth_scopes=<comma-separated list of options>` default: "https://www.googleapis.com/auth/cloud-platform" -: A comma-separated list of Google Cloud authentication scopes. - -`--google_credentials=<a string>` default: see description -: Specifies the file to get authentication credentials from. See https://cloud.google.com/docs/authentication for details. - -`--[no]google_default_credentials` default: "false" -: Whether to use 'Google Application Default Credentials' for authentication. See https://cloud.google.com/docs/authentication for details. Disabled by default. - -`--grpc_keepalive_time=<An immutable length of time.>` default: see description -: Configures keep-alive pings for outgoing gRPC connections. If this is set, then Bazel sends pings after this much time of no read operations on the connection, but only if there is at least one pending gRPC call. Times are treated as second granularity; it is an error to set a value less than one second. By default, keep-alive pings are disabled. You should coordinate with the service owner before enabling this setting. For example to set a value of 30 seconds to this flag, it should be done as this --grpc\_keepalive\_time=30s - -`--grpc_keepalive_timeout=<An immutable length of time.>` default: "20s" -: Configures a keep-alive timeout for outgoing gRPC connections. If keep-alive pings are enabled with --grpc\_keepalive\_time, then Bazel times out a connection if it does not receive a ping reply after this much time. Times are treated as second granularity; it is an error to set a value less than one second. If keep-alive pings are disabled, then this setting is ignored. - -`--[no]incompatible_disable_non_executable_java_binary` default: "false" -: If true, java\_binary is always executable. create\_executable attribute is removed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_repo_env_ignores_action_env` default: "true" -: If true, \<code\>--action\_env=NAME=VALUE\</code\> will no longer affect repository rule and module extension environments. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--inject_repository=<an equals-separated mapping of repository name to path>` multiple uses are accumulated -: Adds a new repository with a local path in the form of <repository name>=<path>. This only takes effect with --enable\_bzlmod and is equivalent to adding a corresponding `local_repository` to the root module's MODULE.bazel file via `use_repo_rule`. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%', it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous injections. - -`--invocation_id=<a UUID>` default: "" -: Unique identifier, in UUID format, for the command being run. If explicitly specified uniqueness must be ensured by the caller. The UUID is printed to stderr, the BEP and remote execution protocol. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--override_repository=<an equals-separated mapping of repository name to path>` multiple uses are accumulated -: Override a repository with a local path in the form of <repository name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. - -`--[no]progress_in_terminal_title` default: "false" -: Show the command progress in the terminal title. Useful to see what bazel is doing when having multiple terminal tabs. - -`--[no]show_progress` default: "true" -: Display progress messages during a build. - -`--show_progress_rate_limit=<a double>` default: "0.2" -: Minimum number of seconds between progress messages in the output. - -`--[no]show_timestamps` default: "false" -: Include timestamps in messages - -`--tls_certificate=<a string>` default: see description -: Specify a path to a TLS certificate that is trusted to sign server certificates. - -`--tls_client_certificate=<a string>` default: see description -: Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication. - -`--tls_client_key=<a string>` default: see description -: Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication. - -`--ui_actions_shown=<an integer>` default: "8" -: Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]watchfs` default: "false" -: On Linux/macOS: If true, bazel tries to use the operating system's file watch service for local changes instead of scanning every file for a change. On Windows: this flag currently is a non-op but can be enabled in conjunction with --experimental\_windows\_watchfs. On any OS: The behavior is undefined if your workspace is on a network file system, and files are edited on a remote machine. - -## Aquery Options - -Inherits all options from [build](#build). - -Options relating to query output and semantics: - -`--aspect_deps=<off, conservative or precise>` default: "conservative" -: How to resolve aspect dependencies when the output format is one of \{xml,proto,record\}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]consistent_labels` default: "false" -: If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]experimental_explicit_aspects` default: "false" -: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]graph:factored` default: "true" -: If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--graph:node_limit=<an integer>` default: "512" -: The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]implicit_deps` default: "true" -: If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]include_artifacts` default: "true" -: Includes names of the action inputs and outputs in the output (potentially large). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]include_aspects` default: "true" -: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]include_commandline` default: "true" -: Includes the content of the action command lines in the output (potentially large). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]include_file_write_contents` default: "false" -: Include the file contents for the FileWrite, SourceSymlinkManifest, and RepoMappingManifest actions (potentially large). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]include_param_files` default: "false" -: Include the content of the param files used in the command (potentially large). Note: Enabling this flag will automatically enable the --include\_commandline flag. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]include_pruned_inputs` default: "true" -: Includes action inputs that were pruned during action execution. Only affects actions that discover inputs and have been executed in a previous invocation. Only takes effect if --include\_artifacts is also set. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]incompatible_package_group_includes_double_slash` default: "true" -: If enabled, when outputting package\_group's `packages` attribute, the leading `//` will not be omitted. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]infer_universe_scope` default: "false" -: If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]line_terminator_null` default: "false" -: Whether each format is terminated with \0 instead of newline. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]nodep_deps` default: "true" -: If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--output=<a string>` default: "text" -: The format in which the aquery results should be printed. Allowed values for aquery are: text, textproto, proto, streamed\_proto, jsonproto. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--output_file=<a string>` default: "" -: When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:default_values` default: "true" -: If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:definition_stack` default: "false" -: Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:flatten_selects` default: "true" -: If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]proto:include_attribute_source_aspects` default: "false" -: Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:include_starlark_rule_env` default: "true" -: Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:include_synthetic_attribute_hash` default: "false" -: Whether or not to calculate and populate the $internal\_attr\_hash attribute. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:instantiation_stack` default: "false" -: Populate the instantiation call stack of each rule. Note that this requires the stack to be present - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:locations` default: "true" -: Whether to output location information in proto output at all. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" -: Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:rule_classes` default: "false" -: Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:rule_inputs_and_outputs` default: "true" -: Whether or not to populate the rule\_input and rule\_output fields. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--query_file=<a string>` default: "" -: If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--[no]relative_locations` default: "false" -: If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]skyframe_state` default: "false" -: Without performing extra analysis, dump the current Action Graph from Skyframe. Note: Specifying a target with --skyframe\_state is currently not supported. This flag is only available with --output=proto or --output=textproto. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]tool_deps` default: "true" -: Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. - Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--universe_scope=<comma-separated list of options>` default: "" -: A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. - For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options that control build execution: - -`--[no]experimental_persistent_aar_extractor` default: "false" -: Enable persistent aar extractor by using workers. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_remotable_source_manifests` default: "false" -: Whether to make source manifest actions remotable - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_split_coverage_postprocessing` default: "false" -: If true, then Bazel will run coverage postprocessing for test in a new spawn. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_strict_fileset_output` default: "false" -: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_modify_execution_info_additive` default: "true" -: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. - - Syntax: "regex=[+-]key,regex=[+-]key,...". - - Examples: - '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. - 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. - '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--persistent_android_dex_desugar` -: Enable persistent Android dex and desugar actions by using workers. - - Expands to: - -   `--internal_persistent_android_dex_desugar` - -   `--strategy=Desugar=worker` - -   `--strategy=DexBuilder=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_android_resource_processor` -: Enable persistent Android resource processor by using workers. - - Expands to: - -   `--internal_persistent_busybox_tools` - -   `--strategy=AaptPackage=worker` - -   `--strategy=AndroidResourceParser=worker` - -   `--strategy=AndroidResourceValidator=worker` - -   `--strategy=AndroidResourceCompiler=worker` - -   `--strategy=RClassGenerator=worker` - -   `--strategy=AndroidResourceLink=worker` - -   `--strategy=AndroidAapt2=worker` - -   `--strategy=AndroidAssetMerger=worker` - -   `--strategy=AndroidResourceMerger=worker` - -   `--strategy=AndroidCompiledResourceMerger=worker` - -   `--strategy=ManifestMerger=worker` - -   `--strategy=AndroidManifestMerger=worker` - -   `--strategy=Aapt2Optimize=worker` - -   `--strategy=AARGenerator=worker` - -   `--strategy=ProcessDatabinding=worker` - -   `--strategy=GenerateDataBindingBaseClasses=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_dex_desugar` -: Enable persistent multiplexed Android dex and desugar actions by using workers. - - Expands to: - -   `--persistent_android_dex_desugar` - -   `--internal_persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_resource_processor` -: Enable persistent multiplexed Android resource processor by using workers. - - Expands to: - -   `--persistent_android_resource_processor` - -   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` - -   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` - -   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_tools` -: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). - - Expands to: - -   `--internal_persistent_multiplex_busybox_tools` - -   `--persistent_multiplex_android_resource_processor` - -   `--persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--[no]use_target_platform_for_tests` default: "false" -: If true, use the target platform for running tests rather than the test exec group. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -Options that configure the toolchain used for action execution: - -`--android_compiler=<a string>` default: see description -: The Android target compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_manifest_merger=<legacy, android or force_android>` default: "android" -: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_platforms=<a build target label>` default: "" -: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--cc_output_directory_tag=<a string>` default: "" -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compiler=<a string>` default: see description -: The C++ compiler to use for compiling the target. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" -: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" -: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" -: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--custom_malloc=<a build target label>` default: see description -: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_include_xcode_execution_requirements` default: "false" -: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_prefer_mutual_xcode` default: "true" -: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--extra_execution_platforms=<comma-separated list of options>` default: "" -: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated -: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--grte_top=<a label>` default: see description -: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_compiler=<a string>` default: see description -: No-op flag. Will be removed in a future release. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--host_grte_top=<a label>` default: see description -: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" -: The label of a platform rule that describes the host system. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]incompatible_bazel_test_exec_run_under` default: "true" -: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_builtin_objc_strip_action` default: "true" -: Whether to emit a strip action as part of objc linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" -: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" -: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_remove_legacy_whole_archive` default: "true" -: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strip_executable_safely` default: "false" -: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]interface_shared_objects` default: "true" -: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--minimum_os_version=<a string>` default: see description -: The minimum OS version which your compilation targets. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_mappings=<a main workspace-relative path>` default: "" -: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--platforms=<a build target label>` default: "" -: The labels of the platform rules describing the target platforms for the current command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_path=<a string>` default: see description -: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]use_platforms_in_apple_crosstool_transition` default: "false" -: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version=<a string>` default: see description -: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" -: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options that control the output of the command: - -`--[no]apple_generate_dsym` default: "false" -: Whether to generate debug symbol(.dSYM) file(s). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]build_runfile_links` default: "true" -: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_runfile_manifests` default: "true" -: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_test_dwp` default: "false" -: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" -: Sets the suffixes of header files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" -: Sets the suffixes of source files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" -: Run extra actions for alternative Java api versions in a proto\_library. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_save_feature_state` default: "false" -: Save the state of enabled and requested feautres as an output of compilation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fission=<a set of compilation modes>` default: "no" -: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_always_include_files_in_data` default: "true" -: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_compact_repo_mapping_manifest` default: "false" -: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_disable_select_on=<comma-separated set of options>` default: "" -: List of flags for which the use in select() is disabled. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_filegroup_runfiles_for_data` default: "true" -: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]objc_generate_linkmap` default: "false" -: Specifies whether to generate a linkmap file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]save_temps` default: "false" -: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case - the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - \<br\> - Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--allowed_cpu_values=<comma-separated set of options>` default: "" -: Allowed values for the --cpu flag. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]android_databinding_use_androidx` default: "true" -: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]android_databinding_use_v3_4_args` default: "true" -: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--android_dynamic_mode=<off, default or fully>` default: "off" -: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) - -`--[no]android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]build_python_zip` default: "auto" -: Build python executable zip; on on Windows, off on other platforms - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple Catalyst binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]collect_code_coverage` default: "false" -: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" -: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--copt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cpu=<a string>` default: "" -: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_absolute_path=<a string>` default: see description -: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_instrument=<a string>` default: see description -: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_profile=<a build target label>` default: see description -: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cxxopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--define=<a 'name=value' assignment>` multiple uses are accumulated -: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--dynamic_mode=<off, default or fully>` default: "default" -: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_propeller_optimize_absolute_paths` default: "true" -: If set, any use of absolute paths for propeller optimize will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_remaining_fdo_absolute_paths` default: "true" -: If set, any use of absolute paths for FDO will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_runfiles` default: "auto" -: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_action_listener=<a build target label>` multiple uses are accumulated -: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_compress_java_resources` default: "false" -: Compress Java resources in APKs - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_databinding_v2` default: "true" -: Use android databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" -: use rex tool to rewrite dex files - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" -: If specified, Bazel will also generate collect coverage information for generated files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -: Uses these strings as objc fastbuild compiler options. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]experimental_omitfp` default: "false" -: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_output_paths=<off or strip>` default: "off" -: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated -: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_platform_in_output_dir` default: "false" -: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_py_binaries_include_label` default: "false" -: py\_binary targets include their label even when stamping is disabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_llvm_covmap` default: "false" -: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" -: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fdo_instrument=<a string>` default: see description -: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_optimize=<a string>` default: see description -: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_prefetch_hints=<a build target label>` default: see description -: Use cache prefetch hints. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_profile=<a build target label>` default: see description -: The fdo\_profile representing the profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]force_pic` default: "false" -: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" -: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_copt=<a string>` multiple uses are accumulated -: Additional options to pass to the C compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cpu=<a string>` default: "" -: The host CPU. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cxxopt=<a string>` multiple uses are accumulated -: Additional options to pass to C++ compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to linker when linking tools in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_auto_exec_groups` default: "false" -: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_merge_genfiles_directory` default: "true" -: If true, the genfiles directory is folded into the bin directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_target_cpu_from_platform` default: "true" -: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]instrument_test_targets` default: "false" -: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" -: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]legacy_whole_archive` default: "true" -: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) - -`--linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltobackendopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO backend step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltoindexopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO indexing step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple macOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--memprof_profile=<a build target label>` default: see description -: Use memprof profile. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]objc_debug_with_GLIBCXX` default: "false" -: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]objc_enable_binary_stripping` default: "false" -: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--objccopt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc when compiling Objective-C/C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_suffix=<a string>` default: see description -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--propeller_optimize=<a build target label>` default: see description -: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_cc_profile=<a string>` default: see description -: Absolute path name of cc\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_ld_profile=<a string>` default: see description -: Absolute path name of ld\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--run_under=<a prefix in front of command>` default: see description -: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]share_native_deps` default: "true" -: If true, native libraries that contain identical functionality will be shared among different targets - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]stamp` default: "false" -: Stamp binaries with the date, username, hostname, workspace information, etc. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--strip=<always, sometimes or never>` default: "sometimes" -: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--stripopt=<a string>` multiple uses are accumulated -: Additional options to pass to strip when generating a '\<name\>.stripped' binary. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple tvOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple visionOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple watchOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xbinary_fdo=<a build target label>` default: see description -: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]check_visibility` default: "true" -: If disabled, visibility errors in target dependencies are demoted to warnings. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]desugar_for_android` default: "true" -: Whether to desugar Java 8 bytecode before dexing. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]desugar_java8_libs` default: "false" -: Whether to include supported Java 8 libraries in apps for legacy devices. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]enforce_constraints` default: "true" -: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments - - 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. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" -: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" -: If true, checks that a Java target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]incompatible_check_testonly_for_output_files` default: "false" -: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_android_rules` default: "false" -: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_apple_binary_rule` default: "false" -: No-op. Kept here for backwards compatibility. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]one_version_enforcement_on_java_tests` default: "true" -: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_native_rules_allowlist=<a build target label>` default: see description -: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]strict_filesets` default: "false" -: If this option is enabled, filesets crossing package boundaries are reported as errors. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" -: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--strict_public_imports=<off, warn, error, strict or default>` default: "off" -: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]strict_system_includes` default: "false" -: If true, headers found through system include paths (-isystem) are also required to be declared. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--target_environment=<a build target label>` multiple uses are accumulated -: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Options that affect the signing outputs of a build: - -`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" -: Implementation to use to sign APKs - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]device_debug_entitlements` default: "true" -: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--ios_signing_cert_name=<a string>` default: see description -: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" -: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_objc_alwayslink_by_default` default: "false" -: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_python_disallow_native_rules` default: "false" -: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that govern the behavior of the test environment or test runner: - -`--[no]allow_analysis_failures` default: "false" -: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--analysis_testing_deps_limit=<an integer>` default: "2000" -: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]break_build_on_parallel_dex2oat_failure` default: "false" -: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. - -`--[no]experimental_android_use_parallel_dex2oat` default: "false" -: Use dex2oat in parallel to possibly speed up android\_test. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]ios_memleaks` default: "false" -: Enable checking for memory leaks in ios\_test targets. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--ios_simulator_device=<a string>` default: see description -: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. - -`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" -: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. - -`--[no]zip_undeclared_test_outputs` default: "false" -: If true, undeclared test outputs will be archived in a zip file. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -Options that trigger optimizations of the build time: - -`--[no]experimental_filter_library_jar_with_program_jar` default: "false" -: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_dotd_files` default: "true" -: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_jdeps_files` default: "true" -: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_retain_test_configuration_across_testonly` default: "false" -: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" -: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. - - 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. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]process_headers_in_dependencies` default: "false" -: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]trim_test_configuration` default: "true" -: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -Options that affect the verbosity, format or location of logging: - -`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]verbose_visibility_errors` default: "false" -: If enabled, visibility errors include additional diagnostic information. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated -: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_default_to_explicit_init_py` default: "false" -: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Miscellaneous options, not otherwise categorized.: - -`--[no]cache_test_results` [`-t`] default: "auto" -: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. - -`--[no]experimental_cancel_concurrent_tests` default: "never" -: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_fetch_all_coverage_outputs` default: "false" -: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_generate_llvm_lcov` default: "false" -: If true, coverage for clang will generate an LCOV report. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -: Enables reduced classpaths for Java compilations. - -`--[no]experimental_run_android_lint_on_java_rules` default: "false" -: Whether to validate java\_\* sources. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[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. - -`--host_java_launcher=<a build target label>` default: see description -: The Java launcher used by tools that are executed during a build. - -`--host_javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac when building tools that are executed during a build. - -`--host_jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. - -`--[no]incompatible_check_sharding_support` default: "true" -: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_exclusive_test_sandboxed` default: "true" -: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strict_action_env` default: "false" -: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated -: Additional options to pass to the J2ObjC tool. - -`--java_debug` -: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. - - Expands to: - -   `--test_arg=--wrapper_script_flag=--debug` - -   `--test_output=streamed` - -   `--test_strategy=exclusive` - -   `--test_timeout=9999` - -   `--nocache_test_results` - -`--[no]java_deps` default: "true" -: Generate dependency information (for now, compile-time classpath) per Java target. - -`--[no]java_header_compilation` default: "true" -: Compile ijars directly from source. - -`--java_language_version=<a string>` default: "" -: The Java language version - -`--java_launcher=<a build target label>` default: see description -: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. - -`--java_runtime_version=<a string>` default: "local\_jdk" -: The Java runtime version - -`--javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac. - -`--jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. - -`--legacy_main_dex_list_generator=<a build target label>` default: see description -: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. - -`--optimizing_dexer=<a build target label>` default: see description -: Specifies a binary to use to do dexing without sharding. - -`--plugin=<a build target label>` multiple uses are accumulated -: Plugins to use in the build. Currently works with java\_plugin. - -`--proguard_top=<a build target label>` default: see description -: Specifies which version of ProGuard to use for code removal when building a Java binary. - -`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" -: The label of the proto-compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]proto_profile` default: "true" -: Whether to pass profile\_path to the proto compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_profile_path=<a build target label>` default: see description -: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile C++ protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile Java protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--protocopt=<a string>` multiple uses are accumulated -: Additional options to pass to the protobuf compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]runs_per_test_detects_flakes` default: "false" -: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. - -`--shell_executable=<a path>` default: see description -: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--test_arg=<a string>` multiple uses are accumulated -: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. - -`--test_filter=<a string>` default: see description -: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. - -`--test_result_expiration=<an integer>` default: "-1" -: This option is deprecated and has no effect. - -`--[no]test_runner_fail_fast` default: "false" -: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. - -`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. - -`--tool_java_language_version=<a string>` default: "" -: The Java language version used to execute the tools that are needed during a build - -`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" -: The Java runtime version used to execute tools during the build - -`--[no]use_ijars` default: "true" -: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. - -## Build Options - -Options that control build execution: - -`--[no]allow_one_action_on_resource_unavailable` default: "true" -: If set, allow at least one action to run even if the resource is not enough or unavailable. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]check_up_to_date` default: "false" -: Don't perform the build, just check if it is up-to-date. If all targets are up-to-date, the build completes successfully. If any step needs to be executed an error is reported and the build fails. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--dynamic_local_execution_delay=<an integer>` default: "1000" -: How many milliseconds should local execution be delayed, if remote execution was faster during a build at least once? - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--dynamic_local_strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated -: The local strategies, in order, to use for the given mnemonic - the first applicable strategy is used. For example, `worker,sandboxed` runs actions that support persistent workers using the worker strategy, and all others using the sandboxed strategy. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `worker,sandboxed`, or`worker,sandboxed,standalone` if `experimental_local_lockfree_output` is set. Takes [mnemonic=]local\_strategy[,local\_strategy,...] - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--dynamic_remote_strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated -: The remote strategies, in order, to use for the given mnemonic - the first applicable strategy is used. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `remote`, so this flag usually does not need to be set explicitly. Takes [mnemonic=]remote\_strategy[,remote\_strategy,...] - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]experimental_async_execution` default: "false" -: If set to true, Bazel is allowed to run action in a virtual thread. The number of actions in flight is still capped with --jobs. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--experimental_async_execution_max_concurrent_actions=<an integer>` default: "5000" -: The number of maximum concurrent actions to run with async execution. If the value is less than --jobs, it is clamped to --jobs. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_docker_image=<a string>` default: "" -: Specify a Docker image name (e.g. "ubuntu:latest") that should be used to execute a sandboxed action when using the docker strategy and the action itself doesn't already have a container-image attribute in its remote\_execution\_properties in the platform description. The value of this flag is passed verbatim to 'docker run', so it supports the same syntax and mechanisms as Docker itself. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_docker_use_customized_images` default: "true" -: If enabled, injects the uid and gid of the current user into the Docker image before using it. This is required if your build / tests depend on the user having a name and home directory inside the container. This is on by default, but you can disable it in case the automatic image customization feature doesn't work in your case or you know that you don't need it. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_dynamic_exclude_tools` default: "true" -: When set, targets that are build "for tool" are not subject to dynamic execution. Such targets are extremely unlikely to be built incrementally and thus not worth spending local cycles on. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--experimental_dynamic_local_load_factor=<a double>` default: "0" -: Controls how much load from dynamic execution to put on the local machine. This flag adjusts how many actions in dynamic execution we will schedule concurrently. It is based on the number of CPUs Blaze thinks is available, which can be controlled with the --local\_resources=cpu= flag. - If this flag is 0, all actions are scheduled locally immediately. If > 0, the amount of actions scheduled locally is limited by the number of CPUs available. If < 1, the load factor is used to reduce the number of locally scheduled actions when the number of actions waiting to schedule is high. This lessens the load on the local machine in the clean build case, where the local machine does not contribute much. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--experimental_dynamic_slow_remote_time=<An immutable length of time.>` default: "0" -: If >0, the time a dynamically run action must run remote-only before we prioritize its local execution to avoid remote timeouts. This may hide some problems on the remote execution system. Do not turn this on without monitoring of remote execution issues. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]experimental_enable_docker_sandbox` default: "false" -: Enable Docker-based sandboxing. This option has no effect if Docker is not installed. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_inmemory_sandbox_stashes` default: "false" -: If set to true, the contents of stashed sandboxes for reuse\_sandbox\_directories will be tracked in memory. This reduces the amount of I/O needed during reuse. Depending on the build this flag may improve wall time. Depending on the build as well this flag may use a significant amount of additional memory. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_sandbox_async_tree_delete_idle_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "4" -: If 0, sandboxes are deleted as soon as actions finish, blocking action completion. If greater than 0, sandboxes are deleted asynchronously in the background without blocking action completion. Asynchronous deletion uses a single thread while a command is running, but ramps up to as many threads as the value of this flag once the server becomes idle. Set to `auto` to use as many threads as the number of CPUs. A server shutdown blocks on any pending asynchronous deletions. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_sandbox_enforce_resources_regexp=<a valid Java regular expression>` default: "" -: If true, actions whose mnemonic matches the input regex will have their resources request enforced as limits, overriding the value of --experimental\_sandbox\_limits, if the resource type supports it. For example a test that declares cpu:3 and resources:memory:10, will run with at most 3 cpus and 10 megabytes of memory. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_sandbox_limits=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated -: If > 0, each Linux sandbox will be limited to the given amount for the specified resource. Requires --incompatible\_use\_new\_cgroup\_implementation and overrides --experimental\_sandbox\_memory\_limit\_mb. Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_sandbox_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" -: If > 0, each Linux sandbox will be limited to the given amount of memory (in MB). Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_shrink_worker_pool` default: "false" -: If enabled, could shrink worker pool if worker memory pressure is high. This flag works only when flag experimental\_total\_worker\_memory\_limit\_mb is enabled. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--experimental_total_worker_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" -: If this limit is greater than zero idle workers might be killed if the total memory usage of all workers exceed the limit. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]experimental_use_hermetic_linux_sandbox` default: "false" -: If set to true, do not mount root, only mount whats provided with sandbox\_add\_mount\_pair. Input files will be hardlinked to the sandbox instead of symlinked to from the sandbox. If action input files are located on a filesystem different from the sandbox, then the input files will be copied instead. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_use_windows_sandbox` default: "false" -: Use Windows sandbox to run actions. If "yes", the binary provided by --experimental\_windows\_sandbox\_path must be valid and correspond to a supported version of sandboxfs. If "auto", the binary may be missing or not compatible. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_windows_sandbox_path=<a string>` default: "BazelSandbox.exe" -: Path to the Windows sandbox binary to use when --experimental\_use\_windows\_sandbox is true. If a bare name, use the first binary of that name found in the PATH. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_worker_allowlist=<comma-separated set of options>` default: see description -: If non-empty, only allow using persistent workers with the given worker key mnemonic. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]experimental_worker_cancellation` default: "false" -: If enabled, Bazel may send cancellation requests to workers that support them. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_worker_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" -: If this limit is greater than zero, workers might be killed if the memory usage of the worker exceeds the limit. If not used together with dynamic execution and `--experimental_dynamic_ignore_local_signals=9`, this may crash your build. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--experimental_worker_metrics_poll_interval=<An immutable length of time.>` default: "5s" -: The interval between collecting worker metrics and possibly attempting evictions. Cannot effectively be less than 1s for performance reasons. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]experimental_worker_multiplex_sandboxing` default: "false" -: If enabled, multiplex workers with a 'supports-multiplex-sandboxing' execution requirement will run in a sandboxed environment, using a separate sandbox directory per work request. Multiplex workers with the execution requirement are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_worker_sandbox_hardening` default: "false" -: If enabled, workers are run in a hardened sandbox, if the implementation allows it. If hardening is enabled then tmp directories are distinct for different workers. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_worker_sandbox_inmemory_tracking=<a string>` multiple uses are accumulated -: A worker key mnemonic for which the contents of the sandbox directory are tracked in memory. This may improve build performance at the cost of additional memory usage. Only affects sandboxed workers. May be specified multiple times for different mnemonics. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_worker_strict_flagfiles` default: "false" -: If enabled, actions arguments for workers that do not follow the worker specification will cause an error. Worker arguments must have exactly one @flagfile argument as the last of its list of arguments. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--genrule_strategy=<comma-separated list of options>` default: "" -: Specify how to execute genrules. This flag will be phased out. Instead, use --spawn\_strategy=\<value\> to control all actions or --strategy=Genrule=\<value\> to control genrules only. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]incompatible_use_new_cgroup_implementation` default: "true" -: If true, use the new implementation for cgroups. The old implementation only supports the memory controller and ignores the value of --experimental\_sandbox\_limits. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]internal_spawn_scheduler` default: "true" -: Placeholder option so that we can tell in Blaze whether the spawn scheduler was enabled. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--jobs=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` [`-j`] default: "auto" -: The number of concurrent jobs to run. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". Values must be between 1 and 5000. Values above 2500 may cause memory issues. "auto" calculates a reasonable default based on host resources. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--[no]keep_going` [`-k`] default: "false" -: Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--[no]reuse_sandbox_directories` default: "true" -: If set to true, directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--sandbox_base=<a string>` default: "" -: Lets the sandbox create its sandbox directories underneath this path. Specify a path on tmpfs (like /run/shm) to possibly improve performance a lot when your build / tests have many input files. Note: You need enough RAM and free space on the tmpfs to hold output and intermediate files generated by running actions. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--[no]sandbox_enable_loopback_device` default: "true" -: If true, a loopback device will be set up in the linux-sandbox network namespace for local actions. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]sandbox_explicit_pseudoterminal` default: "false" -: Explicitly enable the creation of pseudoterminals for sandboxed actions. Some linux distributions require setting the group id of the process to 'tty' inside the sandbox in order for pseudoterminals to function. If this is causing issues, this flag can be disabled to enable other groups to be used. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--sandbox_tmpfs_path=<an absolute path>` multiple uses are accumulated -: For sandboxed actions, mount an empty, writable directory at this absolute path (if supported by the sandboxing implementation, ignored otherwise). - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--[no]skip_incompatible_explicit_targets` default: "false" -: Skip incompatible targets that are explicitly listed on the command line. By default, building such targets results in an error but they are silently skipped when this option is enabled. See: https://bazel.build/extending/platforms#skipping-incompatible-targets - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--spawn_strategy=<comma-separated list of options>` default: "" -: Specify how spawn actions are executed by default. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". See https://blog.bazel.build/2019/06/19/list-strategy.html for details. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated -: Specify how to distribute compilation of other spawn actions. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". This flag overrides the values set by --spawn\_strategy (and --genrule\_strategy if used with mnemonic Genrule). See https://blog.bazel.build/2019/06/19/list-strategy.html for details. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--strategy_regexp=<a '<RegexFilter>=value[,value]' assignment>` multiple uses are accumulated -: Override which spawn strategy should be used to execute spawn actions that have descriptions matching a certain regex\_filter. See --per\_file\_copt for details onregex\_filter matching. The last regex\_filter that matches the description is used. This option overrides other flags for specifying strategy. Example: --strategy\_regexp=//foo.*.cc,-//foo/bar=local means to run actions using local strategy if their descriptions match //foo.*.cc but not //foo/bar. Example: --strategy\_regexp='Compiling.\*/bar=local --strategy\_regexp=Compiling=sandboxed will run 'Compiling //foo/bar/baz' with the 'local' strategy, but reversing the order would run it with 'sandboxed'. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--worker_extra_flag=<a 'name=value' assignment>` multiple uses are accumulated -: Extra command-flags that will be passed to worker processes in addition to --persistent\_worker, keyed by mnemonic (e.g. --worker\_extra\_flag=Javac=--debug. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--worker_max_instances=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated -: How many instances of each kind of persistent worker may be launched if you use the 'worker' strategy. May be specified as [name=value] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--worker_max_multiplex_instances=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated -: How many WorkRequests a multiplex worker process may receive in parallel if you use the 'worker' strategy with --worker\_multiplex. May be specified as [name=value] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]worker_multiplex` default: "true" -: If enabled, workers will use multiplexing if they support it. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]worker_quit_after_build` default: "false" -: If enabled, all workers quit after a build is done. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]worker_sandboxing` default: "false" -: If enabled, singleplex workers will run in a sandboxed environment. Singleplex workers are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]worker_verbose` default: "false" -: If enabled, prints verbose messages when workers are started, shutdown, ... - -Options that control the output of the command: - -`--[no]build` default: "true" -: Execute the build; this is the usual behaviour. Specifying --nobuild causes the build to stop before executing the build actions, returning zero iff the package loading and analysis phases completed successfully; this mode is useful for testing those phases. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_use_validation_aspect` default: "false" -: Whether to run validation actions using aspect (for parallelism with tests). - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--output_groups=<comma-separated list of options>` multiple uses are accumulated -: A list of comma-separated output group names, each of which optionally prefixed by a + or a -. A group prefixed by + is added to the default set of output groups, while a group prefixed by - is removed from the default set. If at least one group is not prefixed, the default set of output groups is omitted. For example, --output\_groups=+foo,+bar builds the union of the default set, foo, and bar, while --output\_groups=foo,bar overrides the default set such that only foo and bar are built. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]run_validations` default: "true" -: Whether to run validation actions as part of the build. See https://bazel.build/extending/rules#validation\_actions - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--serialized_frontier_profile=<a string>` default: "" -: Dump a profile of serialized frontier bytes. Specifies the output path. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--aspects=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of aspects to be applied to top-level targets. In the list, if aspect some\_aspect specifies required aspect providers via required\_aspect\_providers, some\_aspect will run after every aspect that was mentioned before it in the aspects list whose advertised providers satisfy some\_aspect required aspect providers. Moreover, some\_aspect will run after all its required aspects specified by requires attribute. some\_aspect will then have access to the values of those aspects' providers. \<bzl-file-label\>%\<aspect\_name\>, for example '//tools:my\_def.bzl%my\_aspect', where 'my\_aspect' is a top-level value from a file tools/my\_def.bzl - -`--bep_maximum_open_remote_upload_files=<an integer>` default: "-1" -: Maximum number of open files allowed during BEP artifact upload. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_convenience_symlinks` default: "normal" -: This flag controls how the convenience symlinks (the symlinks that appear in the workspace after the build) will be managed. Possible values: - normal (default): Each kind of convenience symlink will be created or deleted, as determined by the build. - clean: All symlinks will be unconditionally deleted. - ignore: Symlinks will not be created or cleaned up. - log\_only: Generate log messages as if 'normal' were passed, but don't actually perform any filesystem operations (useful for tools). - Note that only symlinks whose names are generated by the current value of --symlink\_prefix can be affected; if the prefix changes, any pre-existing symlinks will be left alone. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_convenience_symlinks_bep_event` default: "true" -: This flag controls whether or not we will post the build eventConvenienceSymlinksIdentified to the BuildEventProtocol. If the value is true, the BuildEventProtocol will have an entry for convenienceSymlinksIdentified, listing all of the convenience symlinks created in your workspace. If false, then the convenienceSymlinksIdentified entry in the BuildEventProtocol will be empty. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_all` -: Downloads all remote outputs to the local machine. This flag is an alias for --remote\_download\_outputs=all. - - Expands to: - -   `--remote_download_outputs=all` - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_minimal` -: Does not download any remote build outputs to the local machine. This flag is an alias for --remote\_download\_outputs=minimal. - - Expands to: - -   `--remote_download_outputs=minimal` - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_outputs=<all, minimal or toplevel>` default: "toplevel" -: If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_symlink_template=<a string>` default: "" -: Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain \{hash\} and \{size\_bytes\} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_download_toplevel` -: Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote\_download\_outputs=toplevel. - - Expands to: - -   `--remote_download_outputs=toplevel` - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--symlink_prefix=<a string>` default: see description -: The prefix that is prepended to any of the convenience symlinks that are created after a build. If omitted, the default value is the name of the build tool followed by a hyphen. If '/' is passed, then no symlinks are created and no warning is emitted. Warning: the special functionality for '/' will be deprecated soon; use --experimental\_convenience\_symlinks=ignore instead. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]experimental_docker_privileged` default: "false" -: If enabled, Bazel will pass the --privileged flag to 'docker run' when running actions. This might be required by your build, but it might also result in reduced hermeticity. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_sandboxfs_map_symlink_targets` default: "false" -: No-op - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--sandbox_add_mount_pair=<a single path or a 'source:target' pair>` multiple uses are accumulated -: Add additional path pair to mount in sandbox. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--sandbox_block_path=<a string>` multiple uses are accumulated -: For sandboxed actions, disallow access to this path. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]sandbox_default_allow_network` default: "true" -: Allow network access by default for actions; this may not work with all sandboxing implementations. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]sandbox_fake_hostname` default: "false" -: Change the current hostname to 'localhost' for sandboxed actions. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]sandbox_fake_username` default: "false" -: Change the current username to 'nobody' for sandboxed actions. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--sandbox_writable_path=<a string>` multiple uses are accumulated -: For sandboxed actions, make an existing directory writable in the sandbox (if supported by the sandboxing implementation, ignored otherwise). - - Tags: - [`execution`](#effect_tag_EXECUTION) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_config_setting_private_default_visibility` default: "false" -: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enforce_config_setting_visibility` default: "true" -: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that govern the behavior of the test environment or test runner: - -`--[no]check_tests_up_to_date` default: "false" -: Don't run tests, just check if they are up-to-date. If all tests results are up-to-date, the testing completes successfully. If any test needs to be built or executed, an error is reported and the testing fails. This option implies --check\_up\_to\_date behavior. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--flaky_test_attempts=<a positive integer, the string "default", or test_regex@attempts. This flag may be passed more than once>` multiple uses are accumulated -: Each test will be retried up to the specified number of times in case of any test failure. Tests that required more than one attempt to pass are marked as 'FLAKY' in the test summary. Normally the value specified is just an integer or the string 'default'. If an integer, then all tests will be run up to N times. If 'default', then only a single test attempt will be made for regular tests and three for tests marked explicitly as flaky by their rule (flaky=1 attribute). Alternate syntax: regex\_filter@flaky\_test\_attempts. Where flaky\_test\_attempts is as above and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --runs\_per\_test). Example: --flaky\_test\_attempts=//foo/.*,-//foo/bar/.*@3 deflakes all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, behavior is as if 'default' above. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--local_test_jobs=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -: The max number of local test jobs to run concurrently. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". 0 means local resources will limit the number of local test jobs to run concurrently instead. Setting this greater than the value for --jobs is ineffectual. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]test_keep_going` default: "true" -: When disabled, any non-passing test will cause the entire build to stop. By default all tests are run, even if some do not pass. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--test_strategy=<a string>` default: "" -: Specifies which strategy to use when running tests. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--test_tmpdir=<a path>` default: see description -: Specifies the base temporary directory for 'bazel test' to use. - -Options that trigger optimizations of the build time: - -`--cache_computed_file_digests=<a long integer>` default: "50000" -: If greater than 0, configures Bazel to cache file digests in memory based on their metadata instead of recomputing the digests from disk every time they are needed. Setting this to 0 ensures correctness because not all file changes can be noted from file metadata. When not 0, the number indicates the size of the cache as the number of file digests to be cached. - -`--experimental_active_directories=<comma-separated list of options>` default: "" -: Active directories for Skyfocus and remote analysis caching. Specify as comma-separated workspace root-relative paths. This is a stateful flag. Defining one persists it for subsequent invocations, until it is redefined with a new set. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]experimental_cpu_load_scheduling` default: "false" -: Enables the experimental local execution scheduling based on CPU load, not estimation of actions one by one. Experimental scheduling have showed the large benefit on a large local builds on a powerful machines with the large number of cores. Reccommended to use with --local\_resources=cpu=HOST\_CPUS - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_dynamic_ignore_local_signals=<a comma-separated list of signal numbers>` default: see description -: Takes a list of OS signal numbers. If a local branch of dynamic execution gets killed with any of these signals, the remote branch will be allowed to finish instead. For persistent workers, this only affects signals that kill the worker process. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_enable_skyfocus` default: "false" -: If true, enable the use of --experimental\_active\_directories to reduce Bazel's memory footprint for incremental builds. This feature is known as Skyfocus. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--local_cpu_resources=<an integer, or "HOST_CPUS", optionally followed by [-|*]<float>.>` default: "HOST\_CPUS" -: Explicitly set the total number of local CPU cores available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST\_CPUS", optionally followed by [-|*]\<float\> (eg. HOST\_CPUS*.5 to use half the available CPU cores). By default, ("HOST\_CPUS"), Bazel will query system configuration to estimate the number of CPU cores available. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--local_extra_resources=<a named float, 'name=value'>` multiple uses are accumulated -: Set the number of extra resources available to Bazel. Takes in a string-float pair. Can be used multiple times to specify multiple types of extra resources. Bazel will limit concurrently running actions based on the available extra resources and the extra resources required. Tests can declare the amount of extra resources they need by using a tag of the "resources:\<resoucename\>:\<amount\>" format. Available CPU, RAM and resources cannot be set with this flag. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--local_ram_resources=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "HOST\_RAM\*.67" -: Explicitly set the total amount of local host RAM (in MB) available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST\_RAM", optionally followed by [-|*]\<float\> (eg. HOST\_RAM*.5 to use half the available RAM). By default, ("HOST\_RAM\*.67"), Bazel will query system configuration to estimate the amount of RAM available and will use 67% of it. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--local_resources=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated -: Set the number of resources available to Bazel. Takes in an assignment to a float or HOST\_RAM/HOST\_CPUS, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.5 to use half the available RAM). Can be used multiple times to specify multiple types of resources. Bazel will limit concurrently running actions based on the available resources and the resources required. Tests can declare the amount of resources they need by using a tag of the "resources:<resource name>:\<amount\>" format. Overrides resources specified by --local\_\{cpu|ram|extra\}\_resources. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -Options that affect the verbosity, format or location of logging: - -`--build_event_upload_max_retries=<an integer>` default: "4" -: The maximum number of times Bazel should retry uploading a build event. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--[no]debug_spawn_scheduler` default: "false" - - -`--[no]experimental_bep_target_summary` default: "false" -: Whether to publish TargetSummary events. - -`--[no]experimental_build_event_expand_filesets` default: "false" -: If true, expand Filesets in the BEP when presenting output files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--experimental_build_event_output_group_mode=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated -: Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED\_SET\_OF\_FILES\_ONLY', 'INLINE\_ONLY', or 'BOTH'. The default value is 'NAMED\_SET\_OF\_FILES\_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental\_build\_event\_output\_group\_mode=baseline.lcov=both - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--experimental_build_event_upload_retry_minimum_delay=<An immutable length of time.>` default: "1s" -: Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--experimental_build_event_upload_strategy=<a string>` default: see description -: Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_docker_verbose` default: "false" -: If enabled, Bazel will print more verbose messages about the Docker sandbox strategy. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_frontier_violation_check=<strict, warn or disabled_for_testing>` default: "strict" -: Strategies to handle potential incorrectness from changes beyond the frontier (i.e. outside the active directories) - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]experimental_frontier_violation_verbose` default: "false" -: If true, Bazel will print instructions for fixing Skycache violations - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]experimental_materialize_param_files_directly` default: "false" -: If materializing param files, do so with direct writes to disk. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_run_bep_event_include_residue` default: "false" -: Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--experimental_skyfocus_dump_keys=<none, count or verbose>` default: "none" -: For debugging Skyfocus. Dump the focused SkyKeys (roots, leafs, focused deps, focused rdeps). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]experimental_skyfocus_dump_post_gc_stats` default: "false" -: For debugging Skyfocus. If enabled, trigger manual GC before/after focusing to report heap sizes reductions. This will increase the Skyfocus latency. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]experimental_stream_log_file_uploads` default: "false" -: Stream log file uploads directly to the remote storage rather than writing them to disk. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--explain=<a path>` default: see description -: Causes the build system to explain each executed step of the build. The explanation is written to the specified log file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]ignore_unsupported_sandboxing` default: "false" -: Do not print a warning when sandboxed execution is not supported on this system. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]legacy_important_outputs` default: "false" -: Use this to suppress generation of the legacy important\_outputs field in the TargetComplete event. important\_outputs are required for Bazel to ResultStore/BTX integration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]materialize_param_files` default: "false" -: Writes intermediate parameter files to output tree even when using remote action execution or caching. Useful when debugging actions. This is implied by --subcommands and --verbose\_failures. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--max_config_changes_to_show=<an integer>` default: "3" -: When discarding the analysis cache due to a change in the build options, displays up to the given number of changed option names. If the number given is -1, all changed options will be displayed. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--max_test_output_bytes=<an integer>` default: "-1" -: Specifies maximum per-test-log size that can be emitted when --test\_output is 'errors' or 'all'. Useful for avoiding overwhelming the output with excessively noisy test output. The test header is included in the log size. Negative values imply no limit. Output is all or nothing. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) - -`--output_filter=<a valid Java regular expression>` default: see description -: Only shows warnings and action outputs for rules with a name matching the provided regular expression. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--progress_report_interval=<an integer in 0-3600 range>` default: "0" -: The number of seconds to wait between reports on still running jobs. The default value 0 means the first report will be printed after 10 seconds, then 30 seconds and after that progress is reported once every minute. When --curses is enabled, progress is reported every second. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_analysis_json_log=<a string>` default: see description -: If set, a JSON file is written to this location that contains a detailed log of the behavior of remote analysis caching. It's interpreted as a path relative to the current working directory. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--remote_print_execution_messages=<failure, success or all>` default: "failure" -: Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]sandbox_debug` default: "false" -: Enables debugging features for the sandboxing feature. This includes two things: first, the sandbox root contents are left untouched after a build; and second, prints extra debugging information on execution. This can help developers of Bazel or Starlark rules with debugging failures due to missing input files, etc. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--show_result=<an integer>` default: "1" -: Show the results of the build. For each target, state whether or not it was brought up-to-date, and if so, a list of output files that were built. The printed files are convenient strings for copy+pasting to the shell, to execute them. - This option requires an integer argument, which is the threshold number of targets above which result information is not printed. Thus zero causes suppression of the message and MAX\_INT causes printing of the result to occur always. The default is one. - If nothing was built for a target its results may be omitted to keep the output under the threshold. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]subcommands` [`-s`] default: "false" -: Display the subcommands executed during a build. Related flags: --execution\_log\_json\_file, --execution\_log\_binary\_file (for logging subcommands to a file in a tool-friendly format). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--test_output=<summary, errors, all or streamed>` default: "summary" -: Specifies desired output mode. Valid values are 'summary' to output only test status summary, 'errors' to also print test logs for failed tests, 'all' to print logs for all tests and 'streamed' to output logs for all tests in real time (this will force tests to be executed locally one at a time regardless of --test\_strategy value). - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) - -`--test_summary=<short, terse, detailed, none or testcase>` default: "short" -: Specifies the desired format of the test summary. Valid values are 'short' to print information only about tests executed, 'terse', to print information only about unsuccessful tests that were run, 'detailed' to print detailed information about failed test cases, 'testcase' to print summary in test case resolution, do not print detailed information about failed test cases and 'none' to omit the summary. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]verbose_failures` default: "false" -: If a command fails, print out the full command line. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--aspects_parameters=<a 'name=value' assignment>` multiple uses are accumulated -: Specifies the values of the command-line aspects parameters. Each parameter value is specified via \<param\_name>=<param\_value\>, for example 'my\_param=my\_val' where 'my\_param' is a parameter of some aspect in --aspects list or required by an aspect in the list. This option can be used multiple times. However, it is not allowed to assign values to the same parameter more than once. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--target_pattern_file=<a string>` default: "" -: If set, build will read patterns from the file named here, rather than on the command line. It is an error to specify a file here as well as command-line patterns. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Remote caching and execution options: - -`--experimental_circuit_breaker_strategy=<failure>` default: see description -: Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_remote_cache_compression_threshold=<an integer>` default: "100" -: The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote\_cache\_compression is set. - -`--experimental_remote_cache_eviction_retries=<an integer>` default: "5" -: The maximum number of attempts to retry if the build encountered a transient remote cache error that would otherwise fail the build. Applies for example when artifacts are evicted from the remote cache, or in certain cache failure conditions. A new invocation id will be generated for each attempt. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_remote_cache_lease_extension` default: "false" -: If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. - -`--experimental_remote_cache_ttl=<An immutable length of time.>` default: "3h" -: The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_remote_capture_corrupted_outputs=<a path>` default: see description -: A path to a directory where the corrupted outputs will be captured to. - -`--[no]experimental_remote_discard_merkle_trees` default: "true" -: If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. - -`--experimental_remote_downloader=<a string>` default: see description -: A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote\_asset.proto - -`--[no]experimental_remote_downloader_local_fallback` default: "false" -: Whether to fall back to the local downloader if remote downloader fails. - -`--[no]experimental_remote_downloader_propagate_credentials` default: "false" -: Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. - -`--[no]experimental_remote_execution_keepalive` default: "false" -: Whether to use keepalive for remote execution calls. - -`--experimental_remote_failure_rate_threshold=<an integer in 0-100 range>` default: "10" -: Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--experimental_remote_failure_window_interval=<An immutable length of time.>` default: "60s" -: The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]experimental_remote_mark_tool_inputs` default: "false" -: If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. - -`--[no]experimental_remote_merkle_tree_cache` default: "false" -: If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental\_remote\_merkle\_tree\_cache\_size. - -`--experimental_remote_merkle_tree_cache_size=<a long integer>` default: "1000" -: The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. - -`--experimental_remote_output_service=<a string>` default: see description -: HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. - -`--experimental_remote_output_service_output_path_prefix=<a string>` default: "" -: The path under which the contents of output directories managed by the --experimental\_remote\_output\_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. - -`--[no]experimental_remote_require_cached` default: "false" -: If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. - -`--experimental_remote_scrubbing_config=<Converts to a Scrubber>` default: see description -: Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote\_scrubbing.proto). - - This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. - - Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. - - Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. - - In order to successfully use this feature, you likely want to set a custom --host\_platform together with --experimental\_platform\_in\_output\_dir (to normalize output prefixes) and --incompatible\_strict\_action\_env (to normalize environment variables). - -`--[no]guard_against_concurrent_changes` default: "lite" -: Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]remote_accept_cached` default: "true" -: Whether to accept remotely cached action results. - -`--remote_build_event_upload=<all or minimal>` default: "minimal" -: If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. - If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. - Default to 'minimal'. - -`--remote_bytestream_uri_prefix=<a string>` default: see description -: The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote\_executor and --remote\_instance\_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "$\{hostname\}/$\{instance\_name\}". - -`--remote_cache=<a string>` default: see description -: A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching - -`--[no]remote_cache_async` default: "true" -: If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. - -`--[no]remote_cache_compression` default: "false" -: If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental\_remote\_cache\_compression\_threshold. - -`--remote_cache_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header that will be included in cache requests: --remote\_cache\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - -`--remote_default_exec_properties=<a 'name=value' assignment>` multiple uses are accumulated -: Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec\_properties. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_default_platform_properties=<a string>` default: "" -: Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote\_execution\_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. - -`--remote_download_regex=<a valid Java regular expression>` multiple uses are accumulated -: Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote\_download\_outputs. Multiple patterns may be specified by repeating this flag. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--remote_downloader_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header that will be included in remote downloader requests: --remote\_downloader\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - -`--remote_exec_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header that will be included in execution requests: --remote\_exec\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - -`--remote_execution_priority=<an integer>` default: "0" -: The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. - -`--remote_executor=<a string>` default: see description -: HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. - -`--remote_grpc_log=<a path>` default: see description -: If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). - -`--remote_header=<a 'name=value' assignment>` multiple uses are accumulated -: Specify a header that will be included in requests: --remote\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. - -`--remote_instance_name=<a string>` default: "" -: Value to pass as instance\_name in the remote execution API. - -`--[no]remote_local_fallback` default: "false" -: Whether to fall back to standalone local execution strategy if remote execution fails. - -`--remote_local_fallback_strategy=<a string>` default: "local" -: Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. - -`--remote_max_connections=<an integer>` default: "100" -: Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. - For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote\_max\_connections concurrent requests. - For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--remote_proxy=<a string>` default: see description -: Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). - -`--remote_result_cache_priority=<an integer>` default: "0" -: The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. - -`--remote_retries=<an integer>` default: "5" -: The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. - -`--remote_retry_max_delay=<An immutable length of time.>` default: "5s" -: The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. - -`--remote_timeout=<An immutable length of time.>` default: "60s" -: The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. - -`--[no]remote_upload_local_results` default: "true" -: Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. - -`--[no]remote_verify_downloads` default: "true" -: If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. - -Miscellaneous options, not otherwise categorized.: - -`--[no]allow_analysis_cache_discard` default: "true" -: If discarding the analysis cache due to a change in the build system, setting this option to false will cause bazel to exit, rather than continuing with the build. This option has no effect when 'discard\_analysis\_cache' is also set. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--auto_output_filter=<none, all, packages or subpackages>` default: "none" -: If --output\_filter is not specified, then the value for this option is used create a filter automatically. Allowed values are 'none' (filter nothing / show everything), 'all' (filter everything / show nothing), 'packages' (include output from rules in packages mentioned on the Blaze command line), and 'subpackages' (like 'packages', but also include subpackages). For the 'packages' and 'subpackages' values //java/foo and //javatests/foo are treated as one package)'. - -`--[no]build_manual_tests` default: "false" -: Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from processing. This option forces them to be built (but not executed). - -`--build_tag_filters=<comma-separated list of options>` default: "" -: Specifies a comma-separated list of tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those targets will be built that contain at least one included tag and do not contain any excluded tags. This option does not affect the set of tests executed with the 'test' command; those are be governed by the test filtering options, for example '--test\_tag\_filters' - -`--[no]build_tests_only` default: "false" -: If specified, only \*\_test and test\_suite rules will be built and other targets specified on the command line will be ignored. By default everything that was requested will be built. - -`--combined_report=<none or lcov>` default: "lcov" -: Specifies desired cumulative coverage report type. At this point only LCOV is supported. - -`--[no]compile_one_dependency` default: "false" -: Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single target that depends on the source file to detect errors as early as possible in the edit/build/test cycle. This argument affects the way all non-flag arguments are interpreted; instead of being targets to build they are source filenames. For each source filename an arbitrary target that depends on it will be built. - -`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated -: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. - Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. - -`--[no]discard_analysis_cache` default: "false" -: Discard the analysis cache immediately after the analysis phase completes. Reduces memory usage by ~10%, but makes further incremental builds slower. - -`--disk_cache=<a path>` default: see description -: A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. - -`--embed_label=<a one-line string>` default: "" -: Embed source control revision or release label in binary - -`--execution_log_binary_file=<a path>` default: see description -: Log the executed spawns into this file as length-delimited SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution\_log\_compact\_file, which is significantly smaller and cheaper to produce. Related flags: --execution\_log\_compact\_file (compact format; mutually exclusive), --execution\_log\_json\_file (text JSON format; mutually exclusive), --execution\_log\_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). - -`--execution_log_compact_file=<a path>` default: see description -: Log the executed spawns into this file as length-delimited ExecLogEntry protos, according to src/main/protobuf/spawn.proto. The entire file is zstd compressed. Related flags: --execution\_log\_binary\_file (binary protobuf format; mutually exclusive), --execution\_log\_json\_file (text JSON format; mutually exclusive), --subcommands (for displaying subcommands in terminal output). - -`--execution_log_json_file=<a path>` default: see description -: Log the executed spawns into this file as newline-delimited JSON representations of SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution\_log\_compact\_file, which is significantly smaller and cheaper to produce. Related flags: --execution\_log\_compact\_file (compact format; mutually exclusive), --execution\_log\_binary\_file (binary protobuf format; mutually exclusive), --execution\_log\_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). - -`--[no]execution_log_sort` default: "true" -: Whether to sort the execution log, making it easier to compare logs across invocations. Set to false to avoid potentially significant CPU and memory usage at the end of the invocation, at the cost of producing the log in nondeterministic execution order. Only applies to the binary and JSON formats; the compact format is never sorted. - -`--[no]expand_test_suites` default: "true" -: Expand test\_suite targets into their constituent tests before analysis. When this flag is turned on (the default), negative target patterns will apply to the tests belonging to the test suite, otherwise they will not. Turning off this flag is useful when top-level aspects are applied at command line: then they can analyze test\_suite targets. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_disk_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" -: How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental\_disk\_cache\_gc\_max\_size and/or --experimental\_disk\_cache\_gc\_max\_age. - -`--experimental_disk_cache_gc_max_age=<An immutable length of time.>` default: "0" -: If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. - -`--experimental_disk_cache_gc_max_size=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" -: If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. - -`--experimental_extra_action_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "" -: Deprecated in favor of aspects. Filters set of targets to schedule extra\_actions for. - -`--[no]experimental_extra_action_top_level_only` default: "false" -: Deprecated in favor of aspects. Only schedules extra\_actions for top level targets. - -`--experimental_spawn_scheduler` -: Enable dynamic execution by running actions locally and remotely in parallel. Bazel spawns each action locally and remotely and picks the one that completes first. If an action supports workers, the local action will be run in the persistent worker mode. To enable dynamic execution for an individual action mnemonic, use the `--internal_spawn_scheduler` and `--strategy=<mnemonic>=dynamic` flags instead. - - Expands to: - -   `--internal_spawn_scheduler` - -   `--spawn_strategy=dynamic` - -`--[no]fetch` default: "true" -: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. - -`--local_termination_grace_seconds=<an integer>` default: "15" -: Time to wait between terminating a local process due to timeout and forcefully shutting it down. - -`--package_path=<colon-separated list of options>` default: "%workspace%" -: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. - -`--[no]show_loading_progress` default: "true" -: If enabled, causes Bazel to print "Loading package:" messages. - -`--test_lang_filters=<comma-separated list of options>` default: "" -: Specifies a comma-separated list of test languages. Each language can be optionally preceded with '-' to specify excluded languages. Only those test targets will be found that are written in the specified languages. The name used for each language should be the same as the language prefix in the \*\_test rule, e.g. one of 'cc', 'java', 'py', etc. This option affects --build\_tests\_only behavior and the test command. - -`--test_size_filters=<comma-separated list of values: small, medium, large, or enormous>` default: "" -: Specifies a comma-separated list of test sizes. Each size can be optionally preceded with '-' to specify excluded sizes. Only those test targets will be found that contain at least one included size and do not contain any excluded sizes. This option affects --build\_tests\_only behavior and the test command. - -`--test_tag_filters=<comma-separated list of options>` default: "" -: Specifies a comma-separated list of test tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those test targets will be found that contain at least one included tag and do not contain any excluded tags. This option affects --build\_tests\_only behavior and the test command. - -`--test_timeout_filters=<comma-separated list of values: short, moderate, long, or eternal>` default: "" -: Specifies a comma-separated list of test timeouts. Each timeout can be optionally preceded with '-' to specify excluded timeouts. Only those test targets will be found that contain at least one included timeout and do not contain any excluded timeouts. This option affects --build\_tests\_only behavior and the test command. - -`--workspace_status_command=<path>` default: "" -: A command invoked at the beginning of the build to provide status information about the workspace in the form of key/value pairs. See the User's Manual for the full specification. Also see tools/buildstamp/get\_workspace\_status for an example. - -Options that control build execution: - -`--[no]experimental_persistent_aar_extractor` default: "false" -: Enable persistent aar extractor by using workers. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_remotable_source_manifests` default: "false" -: Whether to make source manifest actions remotable - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_split_coverage_postprocessing` default: "false" -: If true, then Bazel will run coverage postprocessing for test in a new spawn. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_strict_fileset_output` default: "false" -: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_modify_execution_info_additive` default: "true" -: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. - - Syntax: "regex=[+-]key,regex=[+-]key,...". - - Examples: - '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. - 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. - '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--persistent_android_dex_desugar` -: Enable persistent Android dex and desugar actions by using workers. - - Expands to: - -   `--internal_persistent_android_dex_desugar` - -   `--strategy=Desugar=worker` - -   `--strategy=DexBuilder=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_android_resource_processor` -: Enable persistent Android resource processor by using workers. - - Expands to: - -   `--internal_persistent_busybox_tools` - -   `--strategy=AaptPackage=worker` - -   `--strategy=AndroidResourceParser=worker` - -   `--strategy=AndroidResourceValidator=worker` - -   `--strategy=AndroidResourceCompiler=worker` - -   `--strategy=RClassGenerator=worker` - -   `--strategy=AndroidResourceLink=worker` - -   `--strategy=AndroidAapt2=worker` - -   `--strategy=AndroidAssetMerger=worker` - -   `--strategy=AndroidResourceMerger=worker` - -   `--strategy=AndroidCompiledResourceMerger=worker` - -   `--strategy=ManifestMerger=worker` - -   `--strategy=AndroidManifestMerger=worker` - -   `--strategy=Aapt2Optimize=worker` - -   `--strategy=AARGenerator=worker` - -   `--strategy=ProcessDatabinding=worker` - -   `--strategy=GenerateDataBindingBaseClasses=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_dex_desugar` -: Enable persistent multiplexed Android dex and desugar actions by using workers. - - Expands to: - -   `--persistent_android_dex_desugar` - -   `--internal_persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_resource_processor` -: Enable persistent multiplexed Android resource processor by using workers. - - Expands to: - -   `--persistent_android_resource_processor` - -   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` - -   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` - -   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_tools` -: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). - - Expands to: - -   `--internal_persistent_multiplex_busybox_tools` - -   `--persistent_multiplex_android_resource_processor` - -   `--persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--[no]use_target_platform_for_tests` default: "false" -: If true, use the target platform for running tests rather than the test exec group. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -Options that configure the toolchain used for action execution: - -`--android_compiler=<a string>` default: see description -: The Android target compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_manifest_merger=<legacy, android or force_android>` default: "android" -: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_platforms=<a build target label>` default: "" -: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--cc_output_directory_tag=<a string>` default: "" -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compiler=<a string>` default: see description -: The C++ compiler to use for compiling the target. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" -: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" -: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" -: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--custom_malloc=<a build target label>` default: see description -: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_include_xcode_execution_requirements` default: "false" -: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_prefer_mutual_xcode` default: "true" -: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--extra_execution_platforms=<comma-separated list of options>` default: "" -: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated -: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--grte_top=<a label>` default: see description -: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_compiler=<a string>` default: see description -: No-op flag. Will be removed in a future release. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--host_grte_top=<a label>` default: see description -: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" -: The label of a platform rule that describes the host system. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]incompatible_bazel_test_exec_run_under` default: "true" -: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_builtin_objc_strip_action` default: "true" -: Whether to emit a strip action as part of objc linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" -: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" -: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_remove_legacy_whole_archive` default: "true" -: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strip_executable_safely` default: "false" -: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]interface_shared_objects` default: "true" -: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--minimum_os_version=<a string>` default: see description -: The minimum OS version which your compilation targets. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_mappings=<a main workspace-relative path>` default: "" -: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--platforms=<a build target label>` default: "" -: The labels of the platform rules describing the target platforms for the current command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_path=<a string>` default: see description -: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]use_platforms_in_apple_crosstool_transition` default: "false" -: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version=<a string>` default: see description -: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" -: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options that control the output of the command: - -`--[no]apple_generate_dsym` default: "false" -: Whether to generate debug symbol(.dSYM) file(s). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]build_runfile_links` default: "true" -: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_runfile_manifests` default: "true" -: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_test_dwp` default: "false" -: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" -: Sets the suffixes of header files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" -: Sets the suffixes of source files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" -: Run extra actions for alternative Java api versions in a proto\_library. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_save_feature_state` default: "false" -: Save the state of enabled and requested feautres as an output of compilation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fission=<a set of compilation modes>` default: "no" -: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_always_include_files_in_data` default: "true" -: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_compact_repo_mapping_manifest` default: "false" -: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_disable_select_on=<comma-separated set of options>` default: "" -: List of flags for which the use in select() is disabled. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_filegroup_runfiles_for_data` default: "true" -: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]objc_generate_linkmap` default: "false" -: Specifies whether to generate a linkmap file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]save_temps` default: "false" -: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case - the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - \<br\> - Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--allowed_cpu_values=<comma-separated set of options>` default: "" -: Allowed values for the --cpu flag. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]android_databinding_use_androidx` default: "true" -: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]android_databinding_use_v3_4_args` default: "true" -: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--android_dynamic_mode=<off, default or fully>` default: "off" -: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) - -`--[no]android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]build_python_zip` default: "auto" -: Build python executable zip; on on Windows, off on other platforms - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple Catalyst binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]collect_code_coverage` default: "false" -: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" -: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--copt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cpu=<a string>` default: "" -: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_absolute_path=<a string>` default: see description -: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_instrument=<a string>` default: see description -: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_profile=<a build target label>` default: see description -: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cxxopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--define=<a 'name=value' assignment>` multiple uses are accumulated -: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--dynamic_mode=<off, default or fully>` default: "default" -: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_propeller_optimize_absolute_paths` default: "true" -: If set, any use of absolute paths for propeller optimize will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_remaining_fdo_absolute_paths` default: "true" -: If set, any use of absolute paths for FDO will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_runfiles` default: "auto" -: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_action_listener=<a build target label>` multiple uses are accumulated -: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_compress_java_resources` default: "false" -: Compress Java resources in APKs - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_databinding_v2` default: "true" -: Use android databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" -: use rex tool to rewrite dex files - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" -: If specified, Bazel will also generate collect coverage information for generated files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -: Uses these strings as objc fastbuild compiler options. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]experimental_omitfp` default: "false" -: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_output_paths=<off or strip>` default: "off" -: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated -: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_platform_in_output_dir` default: "false" -: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_py_binaries_include_label` default: "false" -: py\_binary targets include their label even when stamping is disabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_llvm_covmap` default: "false" -: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" -: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fdo_instrument=<a string>` default: see description -: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_optimize=<a string>` default: see description -: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_prefetch_hints=<a build target label>` default: see description -: Use cache prefetch hints. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_profile=<a build target label>` default: see description -: The fdo\_profile representing the profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]force_pic` default: "false" -: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" -: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_copt=<a string>` multiple uses are accumulated -: Additional options to pass to the C compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cpu=<a string>` default: "" -: The host CPU. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cxxopt=<a string>` multiple uses are accumulated -: Additional options to pass to C++ compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to linker when linking tools in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_auto_exec_groups` default: "false" -: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_merge_genfiles_directory` default: "true" -: If true, the genfiles directory is folded into the bin directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_target_cpu_from_platform` default: "true" -: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]instrument_test_targets` default: "false" -: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" -: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]legacy_whole_archive` default: "true" -: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) - -`--linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltobackendopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO backend step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltoindexopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO indexing step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple macOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--memprof_profile=<a build target label>` default: see description -: Use memprof profile. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]objc_debug_with_GLIBCXX` default: "false" -: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]objc_enable_binary_stripping` default: "false" -: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--objccopt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc when compiling Objective-C/C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_suffix=<a string>` default: see description -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--propeller_optimize=<a build target label>` default: see description -: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_cc_profile=<a string>` default: see description -: Absolute path name of cc\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_ld_profile=<a string>` default: see description -: Absolute path name of ld\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--run_under=<a prefix in front of command>` default: see description -: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]share_native_deps` default: "true" -: If true, native libraries that contain identical functionality will be shared among different targets - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]stamp` default: "false" -: Stamp binaries with the date, username, hostname, workspace information, etc. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--strip=<always, sometimes or never>` default: "sometimes" -: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--stripopt=<a string>` multiple uses are accumulated -: Additional options to pass to strip when generating a '\<name\>.stripped' binary. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple tvOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple visionOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple watchOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xbinary_fdo=<a build target label>` default: see description -: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]check_visibility` default: "true" -: If disabled, visibility errors in target dependencies are demoted to warnings. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]desugar_for_android` default: "true" -: Whether to desugar Java 8 bytecode before dexing. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]desugar_java8_libs` default: "false" -: Whether to include supported Java 8 libraries in apps for legacy devices. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]enforce_constraints` default: "true" -: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments - - 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. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" -: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" -: If true, checks that a Java target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]incompatible_check_testonly_for_output_files` default: "false" -: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_android_rules` default: "false" -: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_apple_binary_rule` default: "false" -: No-op. Kept here for backwards compatibility. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]one_version_enforcement_on_java_tests` default: "true" -: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_native_rules_allowlist=<a build target label>` default: see description -: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]strict_filesets` default: "false" -: If this option is enabled, filesets crossing package boundaries are reported as errors. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" -: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--strict_public_imports=<off, warn, error, strict or default>` default: "off" -: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]strict_system_includes` default: "false" -: If true, headers found through system include paths (-isystem) are also required to be declared. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--target_environment=<a build target label>` multiple uses are accumulated -: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Options that affect the signing outputs of a build: - -`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" -: Implementation to use to sign APKs - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]device_debug_entitlements` default: "true" -: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--ios_signing_cert_name=<a string>` default: see description -: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" -: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_objc_alwayslink_by_default` default: "false" -: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_python_disallow_native_rules` default: "false" -: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that govern the behavior of the test environment or test runner: - -`--[no]allow_analysis_failures` default: "false" -: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--analysis_testing_deps_limit=<an integer>` default: "2000" -: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]break_build_on_parallel_dex2oat_failure` default: "false" -: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. - -`--[no]experimental_android_use_parallel_dex2oat` default: "false" -: Use dex2oat in parallel to possibly speed up android\_test. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]ios_memleaks` default: "false" -: Enable checking for memory leaks in ios\_test targets. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--ios_simulator_device=<a string>` default: see description -: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. - -`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" -: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. - -`--[no]zip_undeclared_test_outputs` default: "false" -: If true, undeclared test outputs will be archived in a zip file. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -Options that trigger optimizations of the build time: - -`--[no]experimental_filter_library_jar_with_program_jar` default: "false" -: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_dotd_files` default: "true" -: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_jdeps_files` default: "true" -: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_retain_test_configuration_across_testonly` default: "false" -: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" -: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. - - 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. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]process_headers_in_dependencies` default: "false" -: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]trim_test_configuration` default: "true" -: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -Options that affect the verbosity, format or location of logging: - -`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]verbose_visibility_errors` default: "false" -: If enabled, visibility errors include additional diagnostic information. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated -: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_default_to_explicit_init_py` default: "false" -: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Miscellaneous options, not otherwise categorized.: - -`--[no]cache_test_results` [`-t`] default: "auto" -: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. - -`--[no]experimental_cancel_concurrent_tests` default: "never" -: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_fetch_all_coverage_outputs` default: "false" -: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_generate_llvm_lcov` default: "false" -: If true, coverage for clang will generate an LCOV report. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -: Enables reduced classpaths for Java compilations. - -`--[no]experimental_run_android_lint_on_java_rules` default: "false" -: Whether to validate java\_\* sources. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[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. - -`--host_java_launcher=<a build target label>` default: see description -: The Java launcher used by tools that are executed during a build. - -`--host_javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac when building tools that are executed during a build. - -`--host_jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. - -`--[no]incompatible_check_sharding_support` default: "true" -: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_exclusive_test_sandboxed` default: "true" -: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strict_action_env` default: "false" -: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated -: Additional options to pass to the J2ObjC tool. - -`--java_debug` -: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. - - Expands to: - -   `--test_arg=--wrapper_script_flag=--debug` - -   `--test_output=streamed` - -   `--test_strategy=exclusive` - -   `--test_timeout=9999` - -   `--nocache_test_results` - -`--[no]java_deps` default: "true" -: Generate dependency information (for now, compile-time classpath) per Java target. - -`--[no]java_header_compilation` default: "true" -: Compile ijars directly from source. - -`--java_language_version=<a string>` default: "" -: The Java language version - -`--java_launcher=<a build target label>` default: see description -: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. - -`--java_runtime_version=<a string>` default: "local\_jdk" -: The Java runtime version - -`--javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac. - -`--jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. - -`--legacy_main_dex_list_generator=<a build target label>` default: see description -: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. - -`--optimizing_dexer=<a build target label>` default: see description -: Specifies a binary to use to do dexing without sharding. - -`--plugin=<a build target label>` multiple uses are accumulated -: Plugins to use in the build. Currently works with java\_plugin. - -`--proguard_top=<a build target label>` default: see description -: Specifies which version of ProGuard to use for code removal when building a Java binary. - -`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" -: The label of the proto-compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]proto_profile` default: "true" -: Whether to pass profile\_path to the proto compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_profile_path=<a build target label>` default: see description -: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile C++ protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile Java protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--protocopt=<a string>` multiple uses are accumulated -: Additional options to pass to the protobuf compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]runs_per_test_detects_flakes` default: "false" -: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. - -`--shell_executable=<a path>` default: see description -: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--test_arg=<a string>` multiple uses are accumulated -: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. - -`--test_filter=<a string>` default: see description -: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. - -`--test_result_expiration=<an integer>` default: "-1" -: This option is deprecated and has no effect. - -`--[no]test_runner_fail_fast` default: "false" -: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. - -`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. - -`--tool_java_language_version=<a string>` default: "" -: The Java language version used to execute the tools that are needed during a build - -`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" -: The Java runtime version used to execute tools during the build - -`--[no]use_ijars` default: "true" -: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. - -## Canonicalize-flags Options - -Inherits all options from [build](#build). - -Options that control the output of the command: - -`--[no]canonicalize_policy` default: "false" -: Output the canonical policy, after expansion and filtering. To keep the output clean, the canonicalized command arguments will NOT be shown when this option is set to true. Note that the command specified by --for\_command affects the filtered policy, and if none is specified, the default command is 'build'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]experimental_include_default_values` default: "true" -: Whether Starlark options set to their default values are included in the output. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_config_setting_private_default_visibility` default: "false" -: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enforce_config_setting_visibility` default: "true" -: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--for_command=<a string>` default: "build" -: The command for which the options should be canonicalized. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--invocation_policy=<a string>` default: "" -: Applies an invocation policy to the options to be canonicalized. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -Miscellaneous options, not otherwise categorized.: - -`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated -: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. - Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. - -`--[no]fetch` default: "true" -: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. - -`--package_path=<colon-separated list of options>` default: "%workspace%" -: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. - -`--[no]show_loading_progress` default: "true" -: If enabled, causes Bazel to print "Loading package:" messages. - -## Clean Options - -Inherits all options from [build](#build). - -Options that control the output of the command: - -`--[no]async` default: "false" -: If true, output cleaning is asynchronous. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--[no]expunge` default: "false" -: If true, clean removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -`--expunge_async` -: If specified, clean asynchronously removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. - - Expands to: - -   `--expunge` - -   `--async` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) - -## Config Options - -## Coverage Options - -Inherits all options from [test](#test). - -## Cquery Options - -Inherits all options from [test](#test). - -Options relating to query output and semantics: - -`--aspect_deps=<off, conservative or precise>` default: "conservative" -: How to resolve aspect dependencies when the output format is one of \{xml,proto,record\}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]consistent_labels` default: "false" -: If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]experimental_explicit_aspects` default: "false" -: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]graph:factored` default: "true" -: If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--graph:node_limit=<an integer>` default: "512" -: The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]implicit_deps` default: "true" -: If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]include_aspects` default: "true" -: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]incompatible_package_group_includes_double_slash` default: "true" -: If enabled, when outputting package\_group's `packages` attribute, the leading `//` will not be omitted. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]infer_universe_scope` default: "false" -: If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]line_terminator_null` default: "false" -: Whether each format is terminated with \0 instead of newline. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]nodep_deps` default: "true" -: If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--output=<a string>` default: "label" -: The format in which the cquery results should be printed. Allowed values for cquery are: label, label\_kind, textproto, transitions, proto, streamed\_proto, jsonproto. If you select 'transitions', you also have to specify the --transitions=(lite|full) option. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--output_file=<a string>` default: "" -: When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:default_values` default: "true" -: If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:definition_stack` default: "false" -: Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:flatten_selects` default: "true" -: If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]proto:include_attribute_source_aspects` default: "false" -: Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:include_configurations` default: "true" -: if enabled, proto output will include information about configurations. When disabled,cquery proto output format resembles query output format. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]proto:include_starlark_rule_env` default: "true" -: Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:include_synthetic_attribute_hash` default: "false" -: Whether or not to calculate and populate the $internal\_attr\_hash attribute. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:instantiation_stack` default: "false" -: Populate the instantiation call stack of each rule. Note that this requires the stack to be present - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:locations` default: "true" -: Whether to output location information in proto output at all. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" -: Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:rule_classes` default: "false" -: Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:rule_inputs_and_outputs` default: "true" -: Whether or not to populate the rule\_input and rule\_output fields. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--query_file=<a string>` default: "" -: If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--[no]relative_locations` default: "false" -: If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--show_config_fragments=<off, direct or transitive>` default: "off" -: Shows the configuration fragments required by a rule and its transitive dependencies. This can be useful for evaluating how much a configured target graph can be trimmed. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--starlark:expr=<a string>` default: "" -: A Starlark expression to format each configured target in cquery's --output=starlark mode. The configured target is bound to 'target'. If neither --starlark:expr nor --starlark:file is specified, this option will default to 'str(target.label)'. It is an error to specify both --starlark:expr and --starlark:file. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--starlark:file=<a string>` default: "" -: The name of a file that defines a Starlark function called 'format', of one argument, that is applied to each configured target to format it as a string. It is an error to specify both --starlark:expr and --starlark:file. See help for --output=starlark for additional detail. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]tool_deps` default: "true" -: Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. - Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--transitions=<full, lite or none>` default: "none" -: The format in which cquery will print transition information. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--universe_scope=<comma-separated list of options>` default: "" -: A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. - For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options that control build execution: - -`--[no]experimental_persistent_aar_extractor` default: "false" -: Enable persistent aar extractor by using workers. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_remotable_source_manifests` default: "false" -: Whether to make source manifest actions remotable - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_split_coverage_postprocessing` default: "false" -: If true, then Bazel will run coverage postprocessing for test in a new spawn. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_strict_fileset_output` default: "false" -: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_modify_execution_info_additive` default: "true" -: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. - - Syntax: "regex=[+-]key,regex=[+-]key,...". - - Examples: - '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. - 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. - '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--persistent_android_dex_desugar` -: Enable persistent Android dex and desugar actions by using workers. - - Expands to: - -   `--internal_persistent_android_dex_desugar` - -   `--strategy=Desugar=worker` - -   `--strategy=DexBuilder=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_android_resource_processor` -: Enable persistent Android resource processor by using workers. - - Expands to: - -   `--internal_persistent_busybox_tools` - -   `--strategy=AaptPackage=worker` - -   `--strategy=AndroidResourceParser=worker` - -   `--strategy=AndroidResourceValidator=worker` - -   `--strategy=AndroidResourceCompiler=worker` - -   `--strategy=RClassGenerator=worker` - -   `--strategy=AndroidResourceLink=worker` - -   `--strategy=AndroidAapt2=worker` - -   `--strategy=AndroidAssetMerger=worker` - -   `--strategy=AndroidResourceMerger=worker` - -   `--strategy=AndroidCompiledResourceMerger=worker` - -   `--strategy=ManifestMerger=worker` - -   `--strategy=AndroidManifestMerger=worker` - -   `--strategy=Aapt2Optimize=worker` - -   `--strategy=AARGenerator=worker` - -   `--strategy=ProcessDatabinding=worker` - -   `--strategy=GenerateDataBindingBaseClasses=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_dex_desugar` -: Enable persistent multiplexed Android dex and desugar actions by using workers. - - Expands to: - -   `--persistent_android_dex_desugar` - -   `--internal_persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_resource_processor` -: Enable persistent multiplexed Android resource processor by using workers. - - Expands to: - -   `--persistent_android_resource_processor` - -   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` - -   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` - -   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_tools` -: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). - - Expands to: - -   `--internal_persistent_multiplex_busybox_tools` - -   `--persistent_multiplex_android_resource_processor` - -   `--persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--[no]use_target_platform_for_tests` default: "false" -: If true, use the target platform for running tests rather than the test exec group. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -Options that configure the toolchain used for action execution: - -`--android_compiler=<a string>` default: see description -: The Android target compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_manifest_merger=<legacy, android or force_android>` default: "android" -: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_platforms=<a build target label>` default: "" -: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--cc_output_directory_tag=<a string>` default: "" -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compiler=<a string>` default: see description -: The C++ compiler to use for compiling the target. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" -: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" -: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" -: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--custom_malloc=<a build target label>` default: see description -: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_include_xcode_execution_requirements` default: "false" -: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_prefer_mutual_xcode` default: "true" -: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--extra_execution_platforms=<comma-separated list of options>` default: "" -: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated -: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--grte_top=<a label>` default: see description -: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_compiler=<a string>` default: see description -: No-op flag. Will be removed in a future release. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--host_grte_top=<a label>` default: see description -: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" -: The label of a platform rule that describes the host system. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]incompatible_bazel_test_exec_run_under` default: "true" -: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_builtin_objc_strip_action` default: "true" -: Whether to emit a strip action as part of objc linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" -: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" -: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_remove_legacy_whole_archive` default: "true" -: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strip_executable_safely` default: "false" -: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]interface_shared_objects` default: "true" -: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--minimum_os_version=<a string>` default: see description -: The minimum OS version which your compilation targets. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_mappings=<a main workspace-relative path>` default: "" -: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--platforms=<a build target label>` default: "" -: The labels of the platform rules describing the target platforms for the current command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_path=<a string>` default: see description -: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]use_platforms_in_apple_crosstool_transition` default: "false" -: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version=<a string>` default: see description -: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" -: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options that control the output of the command: - -`--[no]apple_generate_dsym` default: "false" -: Whether to generate debug symbol(.dSYM) file(s). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]build_runfile_links` default: "true" -: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_runfile_manifests` default: "true" -: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_test_dwp` default: "false" -: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" -: Sets the suffixes of header files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" -: Sets the suffixes of source files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" -: Run extra actions for alternative Java api versions in a proto\_library. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_save_feature_state` default: "false" -: Save the state of enabled and requested feautres as an output of compilation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fission=<a set of compilation modes>` default: "no" -: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_always_include_files_in_data` default: "true" -: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_compact_repo_mapping_manifest` default: "false" -: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_disable_select_on=<comma-separated set of options>` default: "" -: List of flags for which the use in select() is disabled. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_filegroup_runfiles_for_data` default: "true" -: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]objc_generate_linkmap` default: "false" -: Specifies whether to generate a linkmap file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]save_temps` default: "false" -: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case - the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - \<br\> - Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--allowed_cpu_values=<comma-separated set of options>` default: "" -: Allowed values for the --cpu flag. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]android_databinding_use_androidx` default: "true" -: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]android_databinding_use_v3_4_args` default: "true" -: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--android_dynamic_mode=<off, default or fully>` default: "off" -: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) - -`--[no]android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]build_python_zip` default: "auto" -: Build python executable zip; on on Windows, off on other platforms - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple Catalyst binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]collect_code_coverage` default: "false" -: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" -: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--copt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cpu=<a string>` default: "" -: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_absolute_path=<a string>` default: see description -: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_instrument=<a string>` default: see description -: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_profile=<a build target label>` default: see description -: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cxxopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--define=<a 'name=value' assignment>` multiple uses are accumulated -: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--dynamic_mode=<off, default or fully>` default: "default" -: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_propeller_optimize_absolute_paths` default: "true" -: If set, any use of absolute paths for propeller optimize will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_remaining_fdo_absolute_paths` default: "true" -: If set, any use of absolute paths for FDO will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_runfiles` default: "auto" -: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_action_listener=<a build target label>` multiple uses are accumulated -: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_compress_java_resources` default: "false" -: Compress Java resources in APKs - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_databinding_v2` default: "true" -: Use android databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" -: use rex tool to rewrite dex files - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" -: If specified, Bazel will also generate collect coverage information for generated files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -: Uses these strings as objc fastbuild compiler options. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]experimental_omitfp` default: "false" -: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_output_paths=<off or strip>` default: "off" -: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated -: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_platform_in_output_dir` default: "false" -: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_py_binaries_include_label` default: "false" -: py\_binary targets include their label even when stamping is disabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_llvm_covmap` default: "false" -: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" -: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fdo_instrument=<a string>` default: see description -: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_optimize=<a string>` default: see description -: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_prefetch_hints=<a build target label>` default: see description -: Use cache prefetch hints. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_profile=<a build target label>` default: see description -: The fdo\_profile representing the profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]force_pic` default: "false" -: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" -: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_copt=<a string>` multiple uses are accumulated -: Additional options to pass to the C compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cpu=<a string>` default: "" -: The host CPU. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cxxopt=<a string>` multiple uses are accumulated -: Additional options to pass to C++ compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to linker when linking tools in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_auto_exec_groups` default: "false" -: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_merge_genfiles_directory` default: "true" -: If true, the genfiles directory is folded into the bin directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_target_cpu_from_platform` default: "true" -: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]instrument_test_targets` default: "false" -: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" -: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]legacy_whole_archive` default: "true" -: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) - -`--linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltobackendopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO backend step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltoindexopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO indexing step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple macOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--memprof_profile=<a build target label>` default: see description -: Use memprof profile. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]objc_debug_with_GLIBCXX` default: "false" -: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]objc_enable_binary_stripping` default: "false" -: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--objccopt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc when compiling Objective-C/C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_suffix=<a string>` default: see description -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--propeller_optimize=<a build target label>` default: see description -: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_cc_profile=<a string>` default: see description -: Absolute path name of cc\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_ld_profile=<a string>` default: see description -: Absolute path name of ld\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--run_under=<a prefix in front of command>` default: see description -: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]share_native_deps` default: "true" -: If true, native libraries that contain identical functionality will be shared among different targets - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]stamp` default: "false" -: Stamp binaries with the date, username, hostname, workspace information, etc. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--strip=<always, sometimes or never>` default: "sometimes" -: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--stripopt=<a string>` multiple uses are accumulated -: Additional options to pass to strip when generating a '\<name\>.stripped' binary. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple tvOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple visionOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple watchOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xbinary_fdo=<a build target label>` default: see description -: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]check_visibility` default: "true" -: If disabled, visibility errors in target dependencies are demoted to warnings. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]desugar_for_android` default: "true" -: Whether to desugar Java 8 bytecode before dexing. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]desugar_java8_libs` default: "false" -: Whether to include supported Java 8 libraries in apps for legacy devices. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]enforce_constraints` default: "true" -: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments - - 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. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" -: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" -: If true, checks that a Java target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]incompatible_check_testonly_for_output_files` default: "false" -: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_android_rules` default: "false" -: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_apple_binary_rule` default: "false" -: No-op. Kept here for backwards compatibility. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]one_version_enforcement_on_java_tests` default: "true" -: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_native_rules_allowlist=<a build target label>` default: see description -: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]strict_filesets` default: "false" -: If this option is enabled, filesets crossing package boundaries are reported as errors. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" -: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--strict_public_imports=<off, warn, error, strict or default>` default: "off" -: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]strict_system_includes` default: "false" -: If true, headers found through system include paths (-isystem) are also required to be declared. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--target_environment=<a build target label>` multiple uses are accumulated -: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Options that affect the signing outputs of a build: - -`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" -: Implementation to use to sign APKs - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]device_debug_entitlements` default: "true" -: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--ios_signing_cert_name=<a string>` default: see description -: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" -: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_objc_alwayslink_by_default` default: "false" -: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_python_disallow_native_rules` default: "false" -: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that govern the behavior of the test environment or test runner: - -`--[no]allow_analysis_failures` default: "false" -: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--analysis_testing_deps_limit=<an integer>` default: "2000" -: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]break_build_on_parallel_dex2oat_failure` default: "false" -: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. - -`--[no]experimental_android_use_parallel_dex2oat` default: "false" -: Use dex2oat in parallel to possibly speed up android\_test. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]ios_memleaks` default: "false" -: Enable checking for memory leaks in ios\_test targets. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--ios_simulator_device=<a string>` default: see description -: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. - -`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" -: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. - -`--[no]zip_undeclared_test_outputs` default: "false" -: If true, undeclared test outputs will be archived in a zip file. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -Options that trigger optimizations of the build time: - -`--[no]experimental_filter_library_jar_with_program_jar` default: "false" -: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_dotd_files` default: "true" -: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_jdeps_files` default: "true" -: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_retain_test_configuration_across_testonly` default: "false" -: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" -: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. - - 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. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]process_headers_in_dependencies` default: "false" -: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]trim_test_configuration` default: "true" -: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -Options that affect the verbosity, format or location of logging: - -`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]verbose_visibility_errors` default: "false" -: If enabled, visibility errors include additional diagnostic information. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated -: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_default_to_explicit_init_py` default: "false" -: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Miscellaneous options, not otherwise categorized.: - -`--[no]cache_test_results` [`-t`] default: "auto" -: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. - -`--[no]experimental_cancel_concurrent_tests` default: "never" -: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_fetch_all_coverage_outputs` default: "false" -: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_generate_llvm_lcov` default: "false" -: If true, coverage for clang will generate an LCOV report. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -: Enables reduced classpaths for Java compilations. - -`--[no]experimental_run_android_lint_on_java_rules` default: "false" -: Whether to validate java\_\* sources. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[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. - -`--host_java_launcher=<a build target label>` default: see description -: The Java launcher used by tools that are executed during a build. - -`--host_javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac when building tools that are executed during a build. - -`--host_jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. - -`--[no]incompatible_check_sharding_support` default: "true" -: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_exclusive_test_sandboxed` default: "true" -: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strict_action_env` default: "false" -: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated -: Additional options to pass to the J2ObjC tool. - -`--java_debug` -: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. - - Expands to: - -   `--test_arg=--wrapper_script_flag=--debug` - -   `--test_output=streamed` - -   `--test_strategy=exclusive` - -   `--test_timeout=9999` - -   `--nocache_test_results` - -`--[no]java_deps` default: "true" -: Generate dependency information (for now, compile-time classpath) per Java target. - -`--[no]java_header_compilation` default: "true" -: Compile ijars directly from source. - -`--java_language_version=<a string>` default: "" -: The Java language version - -`--java_launcher=<a build target label>` default: see description -: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. - -`--java_runtime_version=<a string>` default: "local\_jdk" -: The Java runtime version - -`--javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac. - -`--jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. - -`--legacy_main_dex_list_generator=<a build target label>` default: see description -: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. - -`--optimizing_dexer=<a build target label>` default: see description -: Specifies a binary to use to do dexing without sharding. - -`--plugin=<a build target label>` multiple uses are accumulated -: Plugins to use in the build. Currently works with java\_plugin. - -`--proguard_top=<a build target label>` default: see description -: Specifies which version of ProGuard to use for code removal when building a Java binary. - -`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" -: The label of the proto-compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]proto_profile` default: "true" -: Whether to pass profile\_path to the proto compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_profile_path=<a build target label>` default: see description -: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile C++ protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile Java protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--protocopt=<a string>` multiple uses are accumulated -: Additional options to pass to the protobuf compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]runs_per_test_detects_flakes` default: "false" -: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. - -`--shell_executable=<a path>` default: see description -: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--test_arg=<a string>` multiple uses are accumulated -: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. - -`--test_filter=<a string>` default: see description -: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. - -`--test_result_expiration=<an integer>` default: "-1" -: This option is deprecated and has no effect. - -`--[no]test_runner_fail_fast` default: "false" -: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. - -`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. - -`--tool_java_language_version=<a string>` default: "" -: The Java language version used to execute the tools that are needed during a build - -`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" -: The Java runtime version used to execute tools during the build - -`--[no]use_ijars` default: "true" -: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. - -## Dump Options - -Options that control the output of the command: - -`--[no]action_cache` default: "false" -: Dump action cache content. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--memory=<memory mode>` default: see description -: Dump the memory use of the given Skyframe node. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]packages` default: "false" -: Dump package cache content. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]rule_classes` default: "false" -: Dump rule classes. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--[no]rules` default: "false" -: Dump rules, including counts and memory usage (if memory is tracked). - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--skyframe=<off, summary, count, value, deps, rdeps, function_graph, active_directories or active_directories_frontier_deps>` default: "off" -: Dump the Skyframe graph. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--skykey_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: ".\*" -: Regex filter of SkyKey names to output. Only used with --skyframe=deps, rdeps, function\_graph. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -`--skylark_memory=<a string>` default: see description -: Dumps a pprof-compatible memory profile to the specified path. To learn more please see https://github.com/google/pprof. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -## Fetch Options - -Inherits all options from [test](#test). - -Options that control build execution: - -`--[no]all` default: "false" -: Fetches all external repositories necessary for building any target or repository. This is the default if no other flags and arguments are provided. Only works when --enable\_bzlmod is on. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--[no]keep_going` [`-k`] default: "false" -: Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_config_setting_private_default_visibility` default: "false" -: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enforce_config_setting_visibility` default: "true" -: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options relating to Bzlmod output and semantics: - -`--[no]configure` default: "false" -: Only fetches repositories marked as 'configure' for system-configuration purpose. Only works when --enable\_bzlmod is on. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--[no]force` default: "false" -: Ignore existing repository if any and force fetch the repository again. Only works when --enable\_bzlmod is on. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--repo=<a string>` multiple uses are accumulated -: Only fetches the specified repository, which can be either \{@apparent\_repo\_name\} or \{@@canonical\_repo\_name\}. Only works when --enable\_bzlmod is on. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Miscellaneous options, not otherwise categorized.: - -`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated -: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. - Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. - -`--[no]fetch` default: "true" -: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. - -`--package_path=<colon-separated list of options>` default: "%workspace%" -: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. - -`--[no]show_loading_progress` default: "true" -: If enabled, causes Bazel to print "Loading package:" messages. - -Options that control build execution: - -`--[no]experimental_persistent_aar_extractor` default: "false" -: Enable persistent aar extractor by using workers. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_remotable_source_manifests` default: "false" -: Whether to make source manifest actions remotable - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_split_coverage_postprocessing` default: "false" -: If true, then Bazel will run coverage postprocessing for test in a new spawn. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_strict_fileset_output` default: "false" -: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_modify_execution_info_additive` default: "true" -: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. - - Syntax: "regex=[+-]key,regex=[+-]key,...". - - Examples: - '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. - 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. - '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--persistent_android_dex_desugar` -: Enable persistent Android dex and desugar actions by using workers. - - Expands to: - -   `--internal_persistent_android_dex_desugar` - -   `--strategy=Desugar=worker` - -   `--strategy=DexBuilder=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_android_resource_processor` -: Enable persistent Android resource processor by using workers. - - Expands to: - -   `--internal_persistent_busybox_tools` - -   `--strategy=AaptPackage=worker` - -   `--strategy=AndroidResourceParser=worker` - -   `--strategy=AndroidResourceValidator=worker` - -   `--strategy=AndroidResourceCompiler=worker` - -   `--strategy=RClassGenerator=worker` - -   `--strategy=AndroidResourceLink=worker` - -   `--strategy=AndroidAapt2=worker` - -   `--strategy=AndroidAssetMerger=worker` - -   `--strategy=AndroidResourceMerger=worker` - -   `--strategy=AndroidCompiledResourceMerger=worker` - -   `--strategy=ManifestMerger=worker` - -   `--strategy=AndroidManifestMerger=worker` - -   `--strategy=Aapt2Optimize=worker` - -   `--strategy=AARGenerator=worker` - -   `--strategy=ProcessDatabinding=worker` - -   `--strategy=GenerateDataBindingBaseClasses=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_dex_desugar` -: Enable persistent multiplexed Android dex and desugar actions by using workers. - - Expands to: - -   `--persistent_android_dex_desugar` - -   `--internal_persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_resource_processor` -: Enable persistent multiplexed Android resource processor by using workers. - - Expands to: - -   `--persistent_android_resource_processor` - -   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` - -   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` - -   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_tools` -: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). - - Expands to: - -   `--internal_persistent_multiplex_busybox_tools` - -   `--persistent_multiplex_android_resource_processor` - -   `--persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--[no]use_target_platform_for_tests` default: "false" -: If true, use the target platform for running tests rather than the test exec group. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -Options that configure the toolchain used for action execution: - -`--android_compiler=<a string>` default: see description -: The Android target compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_manifest_merger=<legacy, android or force_android>` default: "android" -: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_platforms=<a build target label>` default: "" -: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--cc_output_directory_tag=<a string>` default: "" -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compiler=<a string>` default: see description -: The C++ compiler to use for compiling the target. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" -: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" -: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" -: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--custom_malloc=<a build target label>` default: see description -: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_include_xcode_execution_requirements` default: "false" -: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_prefer_mutual_xcode` default: "true" -: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--extra_execution_platforms=<comma-separated list of options>` default: "" -: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated -: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--grte_top=<a label>` default: see description -: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_compiler=<a string>` default: see description -: No-op flag. Will be removed in a future release. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--host_grte_top=<a label>` default: see description -: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" -: The label of a platform rule that describes the host system. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]incompatible_bazel_test_exec_run_under` default: "true" -: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_builtin_objc_strip_action` default: "true" -: Whether to emit a strip action as part of objc linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" -: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" -: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_remove_legacy_whole_archive` default: "true" -: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strip_executable_safely` default: "false" -: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]interface_shared_objects` default: "true" -: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--minimum_os_version=<a string>` default: see description -: The minimum OS version which your compilation targets. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_mappings=<a main workspace-relative path>` default: "" -: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--platforms=<a build target label>` default: "" -: The labels of the platform rules describing the target platforms for the current command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_path=<a string>` default: see description -: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]use_platforms_in_apple_crosstool_transition` default: "false" -: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version=<a string>` default: see description -: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" -: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options that control the output of the command: - -`--[no]apple_generate_dsym` default: "false" -: Whether to generate debug symbol(.dSYM) file(s). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]build_runfile_links` default: "true" -: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_runfile_manifests` default: "true" -: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_test_dwp` default: "false" -: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" -: Sets the suffixes of header files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" -: Sets the suffixes of source files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" -: Run extra actions for alternative Java api versions in a proto\_library. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_save_feature_state` default: "false" -: Save the state of enabled and requested feautres as an output of compilation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fission=<a set of compilation modes>` default: "no" -: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_always_include_files_in_data` default: "true" -: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_compact_repo_mapping_manifest` default: "false" -: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_disable_select_on=<comma-separated set of options>` default: "" -: List of flags for which the use in select() is disabled. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_filegroup_runfiles_for_data` default: "true" -: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]objc_generate_linkmap` default: "false" -: Specifies whether to generate a linkmap file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]save_temps` default: "false" -: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case - the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - \<br\> - Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--allowed_cpu_values=<comma-separated set of options>` default: "" -: Allowed values for the --cpu flag. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]android_databinding_use_androidx` default: "true" -: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]android_databinding_use_v3_4_args` default: "true" -: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--android_dynamic_mode=<off, default or fully>` default: "off" -: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) - -`--[no]android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]build_python_zip` default: "auto" -: Build python executable zip; on on Windows, off on other platforms - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple Catalyst binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]collect_code_coverage` default: "false" -: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" -: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--copt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cpu=<a string>` default: "" -: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_absolute_path=<a string>` default: see description -: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_instrument=<a string>` default: see description -: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_profile=<a build target label>` default: see description -: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cxxopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--define=<a 'name=value' assignment>` multiple uses are accumulated -: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--dynamic_mode=<off, default or fully>` default: "default" -: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_propeller_optimize_absolute_paths` default: "true" -: If set, any use of absolute paths for propeller optimize will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_remaining_fdo_absolute_paths` default: "true" -: If set, any use of absolute paths for FDO will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_runfiles` default: "auto" -: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_action_listener=<a build target label>` multiple uses are accumulated -: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_compress_java_resources` default: "false" -: Compress Java resources in APKs - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_databinding_v2` default: "true" -: Use android databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" -: use rex tool to rewrite dex files - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" -: If specified, Bazel will also generate collect coverage information for generated files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -: Uses these strings as objc fastbuild compiler options. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]experimental_omitfp` default: "false" -: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_output_paths=<off or strip>` default: "off" -: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated -: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_platform_in_output_dir` default: "false" -: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_py_binaries_include_label` default: "false" -: py\_binary targets include their label even when stamping is disabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_llvm_covmap` default: "false" -: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" -: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fdo_instrument=<a string>` default: see description -: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_optimize=<a string>` default: see description -: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_prefetch_hints=<a build target label>` default: see description -: Use cache prefetch hints. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_profile=<a build target label>` default: see description -: The fdo\_profile representing the profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]force_pic` default: "false" -: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" -: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_copt=<a string>` multiple uses are accumulated -: Additional options to pass to the C compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cpu=<a string>` default: "" -: The host CPU. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cxxopt=<a string>` multiple uses are accumulated -: Additional options to pass to C++ compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to linker when linking tools in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_auto_exec_groups` default: "false" -: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_merge_genfiles_directory` default: "true" -: If true, the genfiles directory is folded into the bin directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_target_cpu_from_platform` default: "true" -: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]instrument_test_targets` default: "false" -: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" -: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]legacy_whole_archive` default: "true" -: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) - -`--linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltobackendopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO backend step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltoindexopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO indexing step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple macOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--memprof_profile=<a build target label>` default: see description -: Use memprof profile. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]objc_debug_with_GLIBCXX` default: "false" -: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]objc_enable_binary_stripping` default: "false" -: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--objccopt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc when compiling Objective-C/C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_suffix=<a string>` default: see description -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--propeller_optimize=<a build target label>` default: see description -: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_cc_profile=<a string>` default: see description -: Absolute path name of cc\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_ld_profile=<a string>` default: see description -: Absolute path name of ld\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--run_under=<a prefix in front of command>` default: see description -: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]share_native_deps` default: "true" -: If true, native libraries that contain identical functionality will be shared among different targets - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]stamp` default: "false" -: Stamp binaries with the date, username, hostname, workspace information, etc. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--strip=<always, sometimes or never>` default: "sometimes" -: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--stripopt=<a string>` multiple uses are accumulated -: Additional options to pass to strip when generating a '\<name\>.stripped' binary. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple tvOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple visionOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple watchOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xbinary_fdo=<a build target label>` default: see description -: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]check_visibility` default: "true" -: If disabled, visibility errors in target dependencies are demoted to warnings. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]desugar_for_android` default: "true" -: Whether to desugar Java 8 bytecode before dexing. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]desugar_java8_libs` default: "false" -: Whether to include supported Java 8 libraries in apps for legacy devices. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]enforce_constraints` default: "true" -: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments - - 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. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" -: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" -: If true, checks that a Java target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]incompatible_check_testonly_for_output_files` default: "false" -: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_android_rules` default: "false" -: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_apple_binary_rule` default: "false" -: No-op. Kept here for backwards compatibility. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]one_version_enforcement_on_java_tests` default: "true" -: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_native_rules_allowlist=<a build target label>` default: see description -: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]strict_filesets` default: "false" -: If this option is enabled, filesets crossing package boundaries are reported as errors. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" -: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--strict_public_imports=<off, warn, error, strict or default>` default: "off" -: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]strict_system_includes` default: "false" -: If true, headers found through system include paths (-isystem) are also required to be declared. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--target_environment=<a build target label>` multiple uses are accumulated -: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Options that affect the signing outputs of a build: - -`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" -: Implementation to use to sign APKs - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]device_debug_entitlements` default: "true" -: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--ios_signing_cert_name=<a string>` default: see description -: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" -: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_objc_alwayslink_by_default` default: "false" -: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_python_disallow_native_rules` default: "false" -: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that govern the behavior of the test environment or test runner: - -`--[no]allow_analysis_failures` default: "false" -: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--analysis_testing_deps_limit=<an integer>` default: "2000" -: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]break_build_on_parallel_dex2oat_failure` default: "false" -: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. - -`--[no]experimental_android_use_parallel_dex2oat` default: "false" -: Use dex2oat in parallel to possibly speed up android\_test. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]ios_memleaks` default: "false" -: Enable checking for memory leaks in ios\_test targets. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--ios_simulator_device=<a string>` default: see description -: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. - -`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" -: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. - -`--[no]zip_undeclared_test_outputs` default: "false" -: If true, undeclared test outputs will be archived in a zip file. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -Options that trigger optimizations of the build time: - -`--[no]experimental_filter_library_jar_with_program_jar` default: "false" -: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_dotd_files` default: "true" -: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_jdeps_files` default: "true" -: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_retain_test_configuration_across_testonly` default: "false" -: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" -: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. - - 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. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]process_headers_in_dependencies` default: "false" -: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]trim_test_configuration` default: "true" -: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -Options that affect the verbosity, format or location of logging: - -`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]verbose_visibility_errors` default: "false" -: If enabled, visibility errors include additional diagnostic information. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated -: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_default_to_explicit_init_py` default: "false" -: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Miscellaneous options, not otherwise categorized.: - -`--[no]cache_test_results` [`-t`] default: "auto" -: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. - -`--[no]experimental_cancel_concurrent_tests` default: "never" -: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_fetch_all_coverage_outputs` default: "false" -: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_generate_llvm_lcov` default: "false" -: If true, coverage for clang will generate an LCOV report. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -: Enables reduced classpaths for Java compilations. - -`--[no]experimental_run_android_lint_on_java_rules` default: "false" -: Whether to validate java\_\* sources. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[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. - -`--host_java_launcher=<a build target label>` default: see description -: The Java launcher used by tools that are executed during a build. - -`--host_javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac when building tools that are executed during a build. - -`--host_jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. - -`--[no]incompatible_check_sharding_support` default: "true" -: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_exclusive_test_sandboxed` default: "true" -: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strict_action_env` default: "false" -: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated -: Additional options to pass to the J2ObjC tool. - -`--java_debug` -: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. - - Expands to: - -   `--test_arg=--wrapper_script_flag=--debug` - -   `--test_output=streamed` - -   `--test_strategy=exclusive` - -   `--test_timeout=9999` - -   `--nocache_test_results` - -`--[no]java_deps` default: "true" -: Generate dependency information (for now, compile-time classpath) per Java target. - -`--[no]java_header_compilation` default: "true" -: Compile ijars directly from source. - -`--java_language_version=<a string>` default: "" -: The Java language version - -`--java_launcher=<a build target label>` default: see description -: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. - -`--java_runtime_version=<a string>` default: "local\_jdk" -: The Java runtime version - -`--javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac. - -`--jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. - -`--legacy_main_dex_list_generator=<a build target label>` default: see description -: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. - -`--optimizing_dexer=<a build target label>` default: see description -: Specifies a binary to use to do dexing without sharding. - -`--plugin=<a build target label>` multiple uses are accumulated -: Plugins to use in the build. Currently works with java\_plugin. - -`--proguard_top=<a build target label>` default: see description -: Specifies which version of ProGuard to use for code removal when building a Java binary. - -`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" -: The label of the proto-compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]proto_profile` default: "true" -: Whether to pass profile\_path to the proto compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_profile_path=<a build target label>` default: see description -: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile C++ protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile Java protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--protocopt=<a string>` multiple uses are accumulated -: Additional options to pass to the protobuf compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]runs_per_test_detects_flakes` default: "false" -: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. - -`--shell_executable=<a path>` default: see description -: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--test_arg=<a string>` multiple uses are accumulated -: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. - -`--test_filter=<a string>` default: see description -: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. - -`--test_result_expiration=<an integer>` default: "-1" -: This option is deprecated and has no effect. - -`--[no]test_runner_fail_fast` default: "false" -: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. - -`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. - -`--tool_java_language_version=<a string>` default: "" -: The Java language version used to execute the tools that are needed during a build - -`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" -: The Java runtime version used to execute tools during the build - -`--[no]use_ijars` default: "true" -: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. - -## Help Options - -Options that affect the verbosity, format or location of logging: - -`--help_verbosity=<long, medium or short>` default: "medium" -: Select the verbosity of the help command. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--long` [`-l`] -: Show full description of each option, instead of just its name. - - Expands to: - -   `--help_verbosity=long` - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--short` -: Show only the names of the options, not their types or meanings. - - Expands to: - -   `--help_verbosity=short` - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -## Info Options - -Inherits all options from [build](#build). - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--info_output_type=<stdout or response_proto>` default: "stdout" -: If stdout, results are directly printed to the console. If response\_proto, the info command results are packed in response extensions. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -Options that affect the verbosity, format or location of logging: - -`--[no]show_make_env` default: "false" -: Include the "Make" environment in the output. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -## License Options - -## Mobile-install Options - -Inherits all options from [build](#build). - -Options that control build execution: - -`--mode=<classic, classic_internal_test_do_not_use or skylark>` default: "skylark" -: Deprecated no-effect flag. Only skylark mode is still supported. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that configure the toolchain used for action execution: - -`--adb=<a string>` default: "" -: adb binary to use for the 'mobile-install' command. If unspecified, the one in the Android SDK specified by the --android\_sdk\_channel command line option (or the default SDK if --android\_sdk\_channel is not specified) is used. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Options that control the output of the command: - -`--[no]incremental` default: "false" -: Whether to do an incremental install. If true, try to avoid unnecessary additional work by reading the state of the device the code is to be installed on and using that information to avoid unnecessary work. If false (the default), always do a full install. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]split_apks` default: "false" -: Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--adb_arg=<a string>` multiple uses are accumulated -: Extra arguments to pass to adb. Usually used to designate a device to install to. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--debug_app` -: Whether to wait for the debugger before starting the app. - - Expands to: - -   `--start=DEBUG` - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--device=<a string>` default: "" -: The adb device serial number. If not specified, the first device will be used. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--start=<no, cold, warm or debug>` default: "NO" -: How the app should be started after installing it. Set to WARM to preserve and restore application state on incremental installs. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--start_app` -: Whether to start the app after installing it. - - Expands to: - -   `--start=COLD` - - Tags: - [`execution`](#effect_tag_EXECUTION) - -Options that affect the verbosity, format or location of logging: - -`--incremental_install_verbosity=<a string>` default: "" -: The verbosity for incremental install. Set to 1 for debug logging. - - Tags: - [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) - -## Mod Options - -Options that control build execution: - -`--[no]experimental_remotable_source_manifests` default: "false" -: Whether to make source manifest actions remotable - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_strict_fileset_output` default: "false" -: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_modify_execution_info_additive` default: "true" -: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. - - Syntax: "regex=[+-]key,regex=[+-]key,...". - - Examples: - '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. - 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. - '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]use_target_platform_for_tests` default: "false" -: If true, use the target platform for running tests rather than the test exec group. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -Options that configure the toolchain used for action execution: - -`--[no]incompatible_bazel_test_exec_run_under` default: "true" -: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that control the output of the command: - -`--[no]build_runfile_links` default: "true" -: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_runfile_manifests` default: "true" -: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_always_include_files_in_data` default: "true" -: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_compact_repo_mapping_manifest` default: "false" -: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_disable_select_on=<comma-separated set of options>` default: "" -: List of flags for which the use in select() is disabled. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_filegroup_runfiles_for_data` default: "true" -: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case - the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - \<br\> - Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--allowed_cpu_values=<comma-separated set of options>` default: "" -: Allowed values for the --cpu flag. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]collect_code_coverage` default: "false" -: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" -: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--cpu=<a string>` default: "" -: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--define=<a 'name=value' assignment>` multiple uses are accumulated -: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_runfiles` default: "auto" -: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_action_listener=<a build target label>` multiple uses are accumulated -: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" -: If specified, Bazel will also generate collect coverage information for generated files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_output_paths=<off or strip>` default: "off" -: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated -: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_platform_in_output_dir` default: "false" -: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" -: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" -: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_cpu=<a string>` default: "" -: The host CPU. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_auto_exec_groups` default: "false" -: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_merge_genfiles_directory` default: "true" -: If true, the genfiles directory is folded into the bin directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_target_cpu_from_platform` default: "true" -: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]instrument_test_targets` default: "false" -: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" -: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_suffix=<a string>` default: see description -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--run_under=<a prefix in front of command>` default: see description -: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]stamp` default: "false" -: Stamp binaries with the date, username, hostname, workspace information, etc. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]check_visibility` default: "true" -: If disabled, visibility errors in target dependencies are demoted to warnings. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]enforce_constraints` default: "true" -: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[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. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_check_testonly_for_output_files` default: "false" -: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]strict_filesets` default: "false" -: If this option is enabled, filesets crossing package boundaries are reported as errors. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--target_environment=<a build target label>` multiple uses are accumulated -: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_config_setting_private_default_visibility` default: "false" -: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enforce_config_setting_visibility` default: "true" -: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that govern the behavior of the test environment or test runner: - -`--[no]allow_analysis_failures` default: "false" -: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--analysis_testing_deps_limit=<an integer>` default: "2000" -: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options relating to the output and semantics of the `mod` subcommand: - -`--base_module=<"<root>" for the root module; <module>@<version> for a specific version of a module; <module> for all versions of a module; @<name> for a repo with the given apparent name; or @@<name> for a repo with the given canonical name>` default: "<root>" -: Specify a module relative to which the specified target repos will be interpreted. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--charset=<utf8 or ascii>` default: "utf8" -: Chooses the character set to use for the tree. Only affects text output. Valid values are "utf8" or "ascii". Default is "utf8" - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]cycles` default: "true" -: Points out dependency cycles inside the displayed tree. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--depth=<an integer>` default: "-1" -: Maximum display depth of the dependency tree. A depth of 1 displays the direct dependencies, for example. For tree, path and all\_paths it defaults to Integer.MAX\_VALUE, while for deps and explain it defaults to 1 (only displays direct deps of the root besides the target leaves and their parents). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--extension_filter=<a comma-separated list of <extension>s>` default: see description -: Only display the usages of these module extensions and the repos generated by them if their respective flags are set. If set, the result graph will only include paths that contain modules using the specified extensions. An empty list disables the filter, effectively specifying all possible extensions. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--extension_info=<hidden, usages, repos or all>` default: "hidden" -: Specify how much detail about extension usages to include in the query result. "Usages" will only show the extensions names, "repos" will also include repos imported with use\_repo, and "all" will also show the other repositories generated by extensions. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--extension_usages=<a comma-separated list of <module>s>` default: "" -: Specify modules whose extension usages will be displayed in the show\_extension query. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--from=<a comma-separated list of <module>s>` default: "<root>" -: The module(s) starting from which the dependency graph query will be displayed. Check each query’s description for the exact semantics. Defaults to \<root\>. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]include_builtin` default: "false" -: Include built-in modules in the dependency graph. Disabled by default because it is quite noisy. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]include_unused` default: "false" -: The queries will also take into account and display the unused modules, which are not present in the module resolution graph after selection (due to the Minimal-Version Selection or override rules). This can have different effects for each of the query types i.e. include new paths in the all\_paths command, or extra dependants in the explain command. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--output=<text, json or graph>` default: "text" -: The format in which the query results should be printed. Allowed values for query are: text, json, graph - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]verbose` default: "false" -: The queries will also display the reason why modules were resolved to their current version (if changed). Defaults to true only for the explain query. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -Options that affect the verbosity, format or location of logging: - -`--[no]verbose_visibility_errors` default: "false" -: If enabled, visibility errors include additional diagnostic information. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated -: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Miscellaneous options, not otherwise categorized.: - -`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated -: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. - Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. - -`--[no]fetch` default: "true" -: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. - -`--package_path=<colon-separated list of options>` default: "%workspace%" -: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. - -`--[no]show_loading_progress` default: "true" -: If enabled, causes Bazel to print "Loading package:" messages. - -## Print\_action Options - -Inherits all options from [build](#build). - -Miscellaneous options, not otherwise categorized.: - -`--print_action_mnemonics=<a string>` multiple uses are accumulated -: Lists which mnemonics to filter print\_action data by, no filtering takes place when left empty. - -## Query Options - -Options that control build execution: - -`--[no]experimental_remotable_source_manifests` default: "false" -: Whether to make source manifest actions remotable - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_strict_fileset_output` default: "false" -: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_modify_execution_info_additive` default: "true" -: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]keep_going` [`-k`] default: "false" -: Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. - - Syntax: "regex=[+-]key,regex=[+-]key,...". - - Examples: - '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. - 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. - '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]use_target_platform_for_tests` default: "false" -: If true, use the target platform for running tests rather than the test exec group. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -Options that configure the toolchain used for action execution: - -`--[no]incompatible_bazel_test_exec_run_under` default: "true" -: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that control the output of the command: - -`--[no]build_runfile_links` default: "true" -: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_runfile_manifests` default: "true" -: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_always_include_files_in_data` default: "true" -: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_compact_repo_mapping_manifest` default: "false" -: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_disable_select_on=<comma-separated set of options>` default: "" -: List of flags for which the use in select() is disabled. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_filegroup_runfiles_for_data` default: "true" -: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case - the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - \<br\> - Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--allowed_cpu_values=<comma-separated set of options>` default: "" -: Allowed values for the --cpu flag. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]collect_code_coverage` default: "false" -: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" -: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--cpu=<a string>` default: "" -: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--define=<a 'name=value' assignment>` multiple uses are accumulated -: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_runfiles` default: "auto" -: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_action_listener=<a build target label>` multiple uses are accumulated -: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" -: If specified, Bazel will also generate collect coverage information for generated files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_output_paths=<off or strip>` default: "off" -: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated -: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_platform_in_output_dir` default: "false" -: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" -: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" -: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_cpu=<a string>` default: "" -: The host CPU. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_auto_exec_groups` default: "false" -: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_merge_genfiles_directory` default: "true" -: If true, the genfiles directory is folded into the bin directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_target_cpu_from_platform` default: "true" -: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]instrument_test_targets` default: "false" -: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" -: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_suffix=<a string>` default: see description -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--run_under=<a prefix in front of command>` default: see description -: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]stamp` default: "false" -: Stamp binaries with the date, username, hostname, workspace information, etc. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]check_visibility` default: "true" -: If disabled, visibility errors in target dependencies are demoted to warnings. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]enforce_constraints` default: "true" -: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[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. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_check_testonly_for_output_files` default: "false" -: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]strict_filesets` default: "false" -: If this option is enabled, filesets crossing package boundaries are reported as errors. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--target_environment=<a build target label>` multiple uses are accumulated -: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_config_setting_private_default_visibility` default: "false" -: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enforce_config_setting_visibility` default: "true" -: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that govern the behavior of the test environment or test runner: - -`--[no]allow_analysis_failures` default: "false" -: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--analysis_testing_deps_limit=<an integer>` default: "2000" -: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options relating to query output and semantics: - -`--aspect_deps=<off, conservative or precise>` default: "conservative" -: How to resolve aspect dependencies when the output format is one of \{xml,proto,record\}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]consistent_labels` default: "false" -: If enabled, every query command emits labels as if by the Starlark \<code\>str\</code\> function applied to a \<code\>Label\</code\> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]experimental_explicit_aspects` default: "false" -: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]experimental_graphless_query` default: "auto" -: If true, uses a Query implementation that does not make a copy of the graph. The new implementation only supports --order\_output=no, as well as only a subset of output formatters. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--graph:conditional_edges_limit=<an integer>` default: "4" -: The maximum number of condition labels to show. -1 means no truncation and 0 means no annotation. This option is only applicable to --output=graph. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]graph:factored` default: "true" -: If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--graph:node_limit=<an integer>` default: "512" -: The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]implicit_deps` default: "true" -: If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]include_aspects` default: "true" -: aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]incompatible_lexicographical_output` default: "true" -: If this option is set, sorts --order\_output=auto output in lexicographical order. - - 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. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]infer_universe_scope` default: "false" -: If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g.`allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]line_terminator_null` default: "false" -: Whether each format is terminated with \0 instead of newline. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]nodep_deps` default: "true" -: If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--noorder_results` -: Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. - - Expands to: - -   `--order_output=no` - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--null` -: Whether each format is terminated with \0 instead of newline. - - Expands to: - -   `--line_terminator_null=true` - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--order_output=<no, deps, auto or full>` default: "auto" -: Output the results unordered (no), dependency-ordered (deps), or fully ordered (full). The default is 'auto', meaning that results are output either dependency-ordered or fully ordered, depending on the output formatter (dependency-ordered for proto, minrank, maxrank, and graph, fully ordered for all others). When output is fully ordered, nodes are printed in a fully deterministic (total) order. First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a post-order depth-first search in which outgoing edges to unvisited nodes are traversed in alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order in which they were visited. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--order_results` -: Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. - - Expands to: - -   `--order_output=auto` - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--output=<a string>` default: "label" -: The format in which the query results should be printed. Allowed values for query are: build, graph, streamed\_jsonproto, label, label\_kind, location, maxrank, minrank, package, proto, streamed\_proto, xml. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--output_file=<a string>` default: "" -: When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than \<code\>bazel query > file\</code\>. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:default_values` default: "true" -: If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:definition_stack` default: "false" -: Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:flatten_selects` default: "true" -: If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--[no]proto:include_attribute_source_aspects` default: "false" -: Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:include_starlark_rule_env` default: "true" -: Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:include_synthetic_attribute_hash` default: "false" -: Whether or not to calculate and populate the $internal\_attr\_hash attribute. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:instantiation_stack` default: "false" -: Populate the instantiation call stack of each rule. Note that this requires the stack to be present - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:locations` default: "true" -: Whether to output location information in proto output at all. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" -: Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:rule_classes` default: "false" -: Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]proto:rule_inputs_and_outputs` default: "true" -: Whether or not to populate the rule\_input and rule\_output fields. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--query_file=<a string>` default: "" -: If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--[no]relative_locations` default: "false" -: If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]strict_test_suite` default: "false" -: If true, the tests() expression gives an error if it encounters a test\_suite containing non-test targets. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]tool_deps` default: "true" -: Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. - Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) - -`--universe_scope=<comma-separated list of options>` default: "" -: A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. - For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]xml:default_values` default: "false" -: If true, rule attributes whose value is not explicitly specified in the BUILD file are printed; otherwise they are omitted. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]xml:line_numbers` default: "true" -: If true, XML output contains line numbers. Disabling this option may make diffs easier to read. This option is only applicable to --output=xml. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -Options that affect the verbosity, format or location of logging: - -`--[no]verbose_visibility_errors` default: "false" -: If enabled, visibility errors include additional diagnostic information. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated -: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Miscellaneous options, not otherwise categorized.: - -`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated -: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. - Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. - -`--[no]fetch` default: "true" -: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. - -`--package_path=<colon-separated list of options>` default: "%workspace%" -: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. - -`--[no]show_loading_progress` default: "true" -: If enabled, causes Bazel to print "Loading package:" messages. - -## Run Options - -Inherits all options from [build](#build). - -Options that appear before the command and are parsed by the client: - -`--[no]portable_paths` default: "false" -: If true, includes paths to replace in ExecRequest to make the resulting paths portable. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]run` default: "true" -: If false, skip running the command line constructed for the built target. Note that this flag is ignored for all --script\_path builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--run_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to the target to run. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. Note that the executed target will generally see the full environment of the host except for those variables that have been explicitly unset. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--script_path=<a path>` default: see description -: If set, write a shell script to the given file which invokes the target. If this option is set, the target is not run from bazel. Use 'bazel run --script\_path=foo //foo && ./foo' to invoke target '//foo' This differs from 'bazel run //foo' in that the bazel lock is released and the executable is connected to the terminal's stdin. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -## Shutdown Options - -Options that control the output of the command: - -`--iff_heap_size_greater_than=<an integer>` default: "0" -: Iff non-zero, then shutdown will only shut down the server if the total memory (in MB) consumed by the JVM exceeds this value. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -## Test Options - -Inherits all options from [build](#build). - -Options that affect the verbosity, format or location of logging: - -`--[no]print_relative_test_log_paths` default: "false" -: If true, when printing the path to a test log, use relative path that makes use of the 'testlogs' convenience symlink. N.B. - A subsequent 'build'/'test'/etc invocation with a different configuration can cause the target of this symlink to change, making the path printed previously no longer useful. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]test_verbose_timeout_warnings` default: "false" -: If true, print additional warnings when the actual test execution time does not match the timeout defined by the test (whether implied or explicit). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]verbose_test_summary` default: "true" -: If true, print additional information (timing, number of failed runs, etc) in the test summary. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -## Vendor Options - -Inherits all options from [test](#test). - -Options that control build execution: - -`--[no]keep_going` [`-k`] default: "false" -: Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" -: Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation ([-|*]\<float\>) eg. "auto", "HOST\_CPUS*.5". "auto" sets a reasonable default based on host resources. Must be at least 1. - - Tags: - [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_config_setting_private_default_visibility` default: "false" -: If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enforce_config_setting_visibility` default: "true" -: If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options relating to Bzlmod output and semantics: - -`--repo=<a string>` multiple uses are accumulated -: Only vendors the specified repository, which can be either `@apparent_repo_name` or `@@canonical_repo_name`. This option can be set multiple times - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Miscellaneous options, not otherwise categorized.: - -`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated -: A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. - Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. - -`--[no]fetch` default: "true" -: Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. - -`--package_path=<colon-separated list of options>` default: "%workspace%" -: A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. - -`--[no]show_loading_progress` default: "true" -: If enabled, causes Bazel to print "Loading package:" messages. - -Options that control build execution: - -`--[no]experimental_persistent_aar_extractor` default: "false" -: Enable persistent aar extractor by using workers. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_remotable_source_manifests` default: "false" -: Whether to make source manifest actions remotable - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_split_coverage_postprocessing` default: "false" -: If true, then Bazel will run coverage postprocessing for test in a new spawn. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_strict_fileset_output` default: "false" -: If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]incompatible_modify_execution_info_additive` default: "true" -: When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated -: Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. - - Syntax: "regex=[+-]key,regex=[+-]key,...". - - Examples: - '.*=+x,.*=-y,.*=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions. - 'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions. - '(?!Genrule).*=-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--persistent_android_dex_desugar` -: Enable persistent Android dex and desugar actions by using workers. - - Expands to: - -   `--internal_persistent_android_dex_desugar` - -   `--strategy=Desugar=worker` - -   `--strategy=DexBuilder=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_android_resource_processor` -: Enable persistent Android resource processor by using workers. - - Expands to: - -   `--internal_persistent_busybox_tools` - -   `--strategy=AaptPackage=worker` - -   `--strategy=AndroidResourceParser=worker` - -   `--strategy=AndroidResourceValidator=worker` - -   `--strategy=AndroidResourceCompiler=worker` - -   `--strategy=RClassGenerator=worker` - -   `--strategy=AndroidResourceLink=worker` - -   `--strategy=AndroidAapt2=worker` - -   `--strategy=AndroidAssetMerger=worker` - -   `--strategy=AndroidResourceMerger=worker` - -   `--strategy=AndroidCompiledResourceMerger=worker` - -   `--strategy=ManifestMerger=worker` - -   `--strategy=AndroidManifestMerger=worker` - -   `--strategy=Aapt2Optimize=worker` - -   `--strategy=AARGenerator=worker` - -   `--strategy=ProcessDatabinding=worker` - -   `--strategy=GenerateDataBindingBaseClasses=worker` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_dex_desugar` -: Enable persistent multiplexed Android dex and desugar actions by using workers. - - Expands to: - -   `--persistent_android_dex_desugar` - -   `--internal_persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_resource_processor` -: Enable persistent multiplexed Android resource processor by using workers. - - Expands to: - -   `--persistent_android_resource_processor` - -   `--modify_execution_info=AaptPackage=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` - -   `--modify_execution_info=RClassGenerator=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` - -   `--modify_execution_info=ManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` - -   `--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` - -   `--modify_execution_info=AARGenerator=+supports-multiplex-workers` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--persistent_multiplex_android_tools` -: Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). - - Expands to: - -   `--internal_persistent_multiplex_busybox_tools` - -   `--persistent_multiplex_android_resource_processor` - -   `--persistent_multiplex_android_dex_desugar` - - Tags: - [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) - -`--[no]use_target_platform_for_tests` default: "false" -: If true, use the target platform for running tests rather than the test exec group. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -Options that configure the toolchain used for action execution: - -`--android_compiler=<a string>` default: see description -: The Android target compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_manifest_merger=<legacy, android or force_android>` default: "android" -: Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--android_platforms=<a build target label>` default: "" -: Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--cc_output_directory_tag=<a string>` default: "" -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compiler=<a string>` default: see description -: The C++ compiler to use for compiling the target. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" -: Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" -: Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" -: Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--custom_malloc=<a build target label>` default: see description -: Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]experimental_include_xcode_execution_requirements` default: "false" -: If set, add a "requires-xcode:\{version\}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:\{version\_label\}" execution requirement. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_prefer_mutual_xcode` default: "true" -: If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--extra_execution_platforms=<comma-separated list of options>` default: "" -: The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated -: The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--grte_top=<a label>` default: see description -: A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_compiler=<a string>` default: see description -: No-op flag. Will be removed in a future release. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) - -`--host_grte_top=<a label>` default: see description -: If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" -: The label of a platform rule that describes the host system. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]incompatible_bazel_test_exec_run_under` default: "true" -: If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "`--run\_under=//foo" in the target configuration. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_builtin_objc_strip_action` default: "true" -: Whether to emit a strip action as part of objc linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" -: If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" -: Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_remove_legacy_whole_archive` default: "true" -: If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strip_executable_safely` default: "false" -: If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]interface_shared_objects` default: "true" -: Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--minimum_os_version=<a string>` default: see description -: The minimum OS version which your compilation targets. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_mappings=<a main workspace-relative path>` default: "" -: The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--platforms=<a build target label>` default: "" -: The labels of the platform rules describing the target platforms for the current command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_path=<a string>` default: see description -: The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]use_platforms_in_apple_crosstool_transition` default: "false" -: Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version=<a string>` default: see description -: If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" -: The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -Options that control the output of the command: - -`--[no]apple_generate_dsym` default: "false" -: Whether to generate debug symbol(.dSYM) file(s). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]build_runfile_links` default: "true" -: If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_runfile_manifests` default: "true" -: If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]build_test_dwp` default: "false" -: If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" -: Sets the suffixes of header files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" -: Sets the suffixes of source files that a cc\_proto\_library creates. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" -: Run extra actions for alternative Java api versions in a proto\_library. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_save_feature_state` default: "false" -: Save the state of enabled and requested feautres as an output of compilation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fission=<a set of compilation modes>` default: "no" -: Specifies which compilation modes use fission for C++ compilations and links. May be any combination of \{'fastbuild', 'dbg', 'opt'\} or the special values 'yes' to enable all modes and 'no' to disable all modes. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_always_include_files_in_data` default: "true" -: If true, native rules add \<code\>DefaultInfo.files\</code\> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_compact_repo_mapping_manifest` default: "false" -: If enabled, the \<binary\>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--incompatible_disable_select_on=<comma-separated set of options>` default: "" -: List of flags for which the use in select() is disabled. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_filegroup_runfiles_for_data` default: "true" -: If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]objc_generate_linkmap` default: "false" -: Specifies whether to generate a linkmap file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]save_temps` default: "false" -: If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by \<code\>name\</code\>, in which case - the value will be taken from the invocation environment, by the \<code\>name=value\</code\> pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - \<br\> - Note that unless \<code\>--incompatible\_repo\_env\_ignores\_action\_env\</code\> is true, all \<code\>name=value\</code\> pairs will be available to repository rules. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--allowed_cpu_values=<comma-separated set of options>` default: "" -: Allowed values for the --cpu flag. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]android_databinding_use_androidx` default: "true" -: Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]android_databinding_use_v3_4_args` default: "true" -: Use android databinding v2 with 3.4.0 argument. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--android_dynamic_mode=<off, default or fully>` default: "off" -: Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" -: Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) - -`--[no]android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]build_python_zip` default: "auto" -: Build python executable zip; on on Windows, off on other platforms - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple Catalyst binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]collect_code_coverage` default: "false" -: If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--compilation_mode=<fastbuild, dbg or opt>` [`-c`] default: "fastbuild" -: Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--copt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cpu=<a string>` default: "" -: Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_absolute_path=<a string>` default: see description -: Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_instrument=<a string>` default: see description -: Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cs_fdo_profile=<a build target label>` default: see description -: The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--cxxopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when compiling C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--define=<a 'name=value' assignment>` multiple uses are accumulated -: Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--dynamic_mode=<off, default or fully>` default: "default" -: Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_propeller_optimize_absolute_paths` default: "true" -: If set, any use of absolute paths for propeller optimize will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_remaining_fdo_absolute_paths` default: "true" -: If set, any use of absolute paths for FDO will raise an error. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]enable_runfiles` default: "auto" -: Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_action_listener=<a build target label>` multiple uses are accumulated -: Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. - - Tags: - [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_compress_java_resources` default: "false" -: Compress Java resources in APKs - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_databinding_v2` default: "true" -: Use android databinding v2. This flag is a no-op. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_resource_shrinking` default: "false" -: Enables resource shrinking for android\_binary APKs that use ProGuard. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" -: use rex tool to rewrite dex files - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" -: If specified, Bazel will also generate collect coverage information for generated files. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" -: Uses these strings as objc fastbuild compiler options. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]experimental_omitfp` default: "false" -: If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_output_paths=<off or strip>` default: "off" -: Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated -: Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_platform_in_output_dir` default: "false" -: If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_py_binaries_include_label` default: "false" -: py\_binary targets include their label even when stamping is disabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_llvm_covmap` default: "false" -: If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" -: Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--fdo_instrument=<a string>` default: see description -: Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_optimize=<a string>` default: see description -: Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` - you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_prefetch_hints=<a build target label>` default: see description -: Use cache prefetch hints. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--fdo_profile=<a build target label>` default: see description -: The fdo\_profile representing the profile to be used for optimization. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. See also --host\_features - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]force_pic` default: "false" -: If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by \<code>=name</code\>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" -: Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--host_conlyopt=<a string>` multiple uses are accumulated -: Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_copt=<a string>` multiple uses are accumulated -: Additional options to pass to the C compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cpu=<a string>` default: "" -: The host CPU. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_cxxopt=<a string>` multiple uses are accumulated -: Additional options to pass to C++ compiler for tools built in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_features=<a string>` multiple uses are accumulated -: The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -\<feature\> will disable the feature. Negative features always override positive ones. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to linker when linking tools in the exec configurations. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]incompatible_auto_exec_groups` default: "false" -: When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_merge_genfiles_directory` default: "true" -: If true, the genfiles directory is folded into the bin directory. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_target_cpu_from_platform` default: "true" -: If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]instrument_test_targets` default: "false" -: When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests[/:],-/test/java[/:]" -: When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]legacy_whole_archive` default: "true" -: Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) - -`--linkopt=<a string>` multiple uses are accumulated -: Additional option to pass to gcc when linking. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltobackendopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO backend step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--ltoindexopt=<a string>` multiple uses are accumulated -: Additional option to pass to the LTO indexing step (under --features=thin\_lto). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple macOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--memprof_profile=<a build target label>` default: see description -: Use memprof profile. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]objc_debug_with_GLIBCXX` default: "false" -: If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]objc_enable_binary_stripping` default: "false" -: Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--objccopt=<a string>` multiple uses are accumulated -: Additional options to pass to gcc when compiling Objective-C/C++ source files. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated -: Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--platform_suffix=<a string>` default: see description -: Specifies a suffix to be added to the configuration directory. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--propeller_optimize=<a build target label>` default: see description -: Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_cc_profile=<a string>` default: see description -: Absolute path name of cc\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--propeller_optimize_absolute_ld_profile=<a string>` default: see description -: Absolute path name of ld\_profile file for Propeller Optimized builds. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--run_under=<a prefix in front of command>` default: see description -: Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--[no]share_native_deps` default: "true" -: If true, native libraries that contain identical functionality will be shared among different targets - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]stamp` default: "false" -: Stamp binaries with the date, username, hostname, workspace information, etc. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--strip=<always, sometimes or never>` default: "sometimes" -: Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--stripopt=<a string>` multiple uses are accumulated -: Additional options to pass to strip when generating a '\<name\>.stripped' binary. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple tvOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple visionOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated -: Comma-separated list of architectures for which to build Apple watchOS binaries. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. - - Tags: - [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--xbinary_fdo=<a build target label>` default: see description -: Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): - -`--[no]check_visibility` default: "true" -: If disabled, visibility errors in target dependencies are demoted to warnings. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]desugar_for_android` default: "true" -: Whether to desugar Java 8 bytecode before dexing. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -`--[no]desugar_java8_libs` default: "false" -: Whether to include supported Java 8 libraries in apps for legacy devices. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]enforce_constraints` default: "true" -: Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments - - 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. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" -: When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" -: If true, checks that a Java target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--[no]incompatible_check_testonly_for_output_files` default: "false" -: If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_android_rules` default: "false" -: If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_disable_native_apple_binary_rule` default: "false" -: No-op. Kept here for backwards compatibility. - - Tags: - [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]one_version_enforcement_on_java_tests` default: "true" -: When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--python_native_rules_allowlist=<a build target label>` default: see description -: An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]strict_filesets` default: "false" -: If this option is enabled, filesets crossing package boundaries are reported as errors. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" -: Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--strict_public_imports=<off, warn, error, strict or default>` default: "off" -: Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]strict_system_includes` default: "false" -: If true, headers found through system include paths (-isystem) are also required to be declared. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) - -`--target_environment=<a build target label>` multiple uses are accumulated -: Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -Options that affect the signing outputs of a build: - -`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" -: Implementation to use to sign APKs - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]device_debug_entitlements` default: "true" -: If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS) - -`--ios_signing_cert_name=<a string>` default: see description -: Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: - -`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" -: If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_objc_alwayslink_by_default` default: "false" -: If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_python_disallow_native_rules` default: "false" -: When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Options that govern the behavior of the test environment or test runner: - -`--[no]allow_analysis_failures` default: "false" -: If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--analysis_testing_deps_limit=<an integer>` default: "2000" -: Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]break_build_on_parallel_dex2oat_failure` default: "false" -: If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated -: Override the default resources amount for tests. The expected format is \<resource>=<value\>. If a single positive number is specified as \<value\> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by [-|*]\<float\> (eg. memory=HOST\_RAM*.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. - -`--[no]experimental_android_use_parallel_dex2oat` default: "false" -: Use dex2oat in parallel to possibly speed up android\_test. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]ios_memleaks` default: "false" -: Enable checking for memory leaks in ios\_test targets. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) - -`--ios_simulator_device=<a string>` default: see description -: The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description -: The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated -: Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. - -`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated -: Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by \<code\>name\</code\>, in which case its value will be read from the Bazel client environment, or by the \<code\>name=value\</code\> pair. Previously set variables can be unset via \<code>=name</code\>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" -: Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. - -`--[no]zip_undeclared_test_outputs` default: "false" -: If true, undeclared test outputs will be archived in a zip file. - - Tags: - [`test_runner`](#effect_tag_TEST_RUNNER) - -Options that trigger optimizations of the build time: - -`--[no]experimental_filter_library_jar_with_program_jar` default: "false" -: Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. - - Tags: - [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_dotd_files` default: "true" -: If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_inmemory_jdeps_files` default: "true" -: If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_retain_test_configuration_across_testonly` default: "false" -: When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" -: Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. - - 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. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]process_headers_in_dependencies` default: "false" -: When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). - - Tags: - [`execution`](#effect_tag_EXECUTION) - -`--[no]trim_test_configuration` default: "true" -: When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) - -Options that affect the verbosity, format or location of logging: - -`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" -: Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - -`--[no]verbose_visibility_errors` default: "false" -: If enabled, visibility errors include additional diagnostic information. - - Tags: - [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: - -`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated -: Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "\<key>=<value\>" as an argument. - - Tags: - [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) - -`--[no]incompatible_default_to_explicit_init_py` default: "false" -: This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -Miscellaneous options, not otherwise categorized.: - -`--[no]cache_test_results` [`-t`] default: "auto" -: If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. - -`--[no]experimental_cancel_concurrent_tests` default: "never" -: If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_fetch_all_coverage_outputs` default: "false" -: If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[no]experimental_generate_llvm_lcov` default: "false" -: If true, coverage for clang will generate an LCOV report. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" -: Enables reduced classpaths for Java compilations. - -`--[no]experimental_run_android_lint_on_java_rules` default: "false" -: Whether to validate java\_\* sources. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) - -`--[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. - -`--host_java_launcher=<a build target label>` default: see description -: The Java launcher used by tools that are executed during a build. - -`--host_javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac when building tools that are executed during a build. - -`--host_jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. - -`--[no]incompatible_check_sharding_support` default: "true" -: If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_exclusive_test_sandboxed` default: "true" -: If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally - - Tags: - [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--[no]incompatible_strict_action_env` default: "false" -: If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) - -`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated -: Additional options to pass to the J2ObjC tool. - -`--java_debug` -: Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. - - Expands to: - -   `--test_arg=--wrapper_script_flag=--debug` - -   `--test_output=streamed` - -   `--test_strategy=exclusive` - -   `--test_timeout=9999` - -   `--nocache_test_results` - -`--[no]java_deps` default: "true" -: Generate dependency information (for now, compile-time classpath) per Java target. - -`--[no]java_header_compilation` default: "true" -: Compile ijars directly from source. - -`--java_language_version=<a string>` default: "" -: The Java language version - -`--java_launcher=<a build target label>` default: see description -: The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. - -`--java_runtime_version=<a string>` default: "local\_jdk" -: The Java runtime version - -`--javacopt=<a string>` multiple uses are accumulated -: Additional options to pass to javac. - -`--jvmopt=<a string>` multiple uses are accumulated -: Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. - -`--legacy_main_dex_list_generator=<a build target label>` default: see description -: Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. - -`--optimizing_dexer=<a build target label>` default: see description -: Specifies a binary to use to do dexing without sharding. - -`--plugin=<a build target label>` multiple uses are accumulated -: Plugins to use in the build. Currently works with java\_plugin. - -`--proguard_top=<a build target label>` default: see description -: Specifies which version of ProGuard to use for code removal when building a Java binary. - -`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" -: The label of the proto-compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--[no]proto_profile` default: "true" -: Whether to pass profile\_path to the proto compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_profile_path=<a build target label>` default: see description -: The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile C++ protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile j2objc protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile Java protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" -: Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--protocopt=<a string>` multiple uses are accumulated -: Additional options to pass to the protobuf compiler. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) - -`--[no]runs_per_test_detects_flakes` default: "false" -: If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. - -`--shell_executable=<a path>` default: see description -: Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. - - Tags: - [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) - -`--test_arg=<a string>` multiple uses are accumulated -: Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. - -`--test_filter=<a string>` default: see description -: Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. - -`--test_result_expiration=<an integer>` default: "-1" -: This option is deprecated and has no effect. - -`--[no]test_runner_fail_fast` default: "false" -: Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. - -`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" -: Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. - -`--tool_java_language_version=<a string>` default: "" -: The Java language version used to execute the tools that are needed during a build - -`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" -: The Java runtime version used to execute tools during the build - -`--[no]use_ijars` default: "true" -: If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. - -## Version Options - -Options that let the user configure the intended output, affecting its value, as opposed to its existence: - -`--[no]gnu_format` default: "false" -: If set, write the version to stdout using the conventions described in the GNU standards. - - Tags: - [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) - -### Option Effect Tags - -| | | -| --- | --- | -| `unknown` | This option has unknown, or undocumented, effect. | -| `no_op` | This option has literally no effect. | -| `loses_incremental_state` | Changing the value of this option can cause significant loss of incremental state, which slows builds. State could be lost due to a server restart or to invalidation of a large part of the dependency graph. | -| `changes_inputs` | This option actively changes the inputs that bazel considers for the build, such as filesystem restrictions, repository versions, or other options. | -| `affects_outputs` | This option affects bazel's outputs. This tag is intentionally broad, can include transitive affects, and does not specify the type of output it affects. | -| `build_file_semantics` | This option affects the semantics of BUILD or .bzl files. | -| `bazel_internal_configuration` | This option affects settings of bazel-internal machinery. This tag does not, on its own, mean that build artifacts are affected. | -| `loading_and_analysis` | This option affects the loading and analysis of dependencies, and the building of the dependency graph. | -| `execution` | This option affects the execution phase, such as sandboxing or remote execution related options. | -| `host_machine_resource_optimizations` | This option triggers an optimization that may be machine specific and is not guaranteed to work on all machines. The optimization could include a tradeoff with other aspects of performance, such as memory or cpu cost. | -| `eagerness_to_exit` | This option changes how eagerly bazel will exit from a failure, where a choice between continuing despite the failure and ending the invocation exists. | -| `bazel_monitoring` | This option is used to monitor bazel's behavior and performance. | -| `terminal_output` | This option affects bazel's terminal output. | -| `action_command_lines` | This option changes the command line arguments of one or more build actions. | -| `test_runner` | This option changes the testrunner environment of the build. | - -### Option Metadata Tags - -| | | -| --- | --- | -| `experimental` | This option triggers an experimental feature with no guarantees of functionality. | -| `incompatible_change` | This option triggers a breaking change. Use this option to test your migration readiness or get early access to the new feature | -| `deprecated` | This option is deprecated. It might be that the feature it affects is deprecated, or that another method of supplying the information is preferred. | -| `non_configurable` | This option cannot be changed in a transition or be used in a select() statement. | - - - - - \ No newline at end of file diff --git a/reference/glossary.mdx b/reference/glossary.mdx deleted file mode 100644 index e526000..0000000 --- a/reference/glossary.mdx +++ /dev/null @@ -1,715 +0,0 @@ ---- -title: 'Bazel Glossary' ---- - - - -### Action - -A command to run during the build, for example, a call to a compiler that takes -[artifacts](#artifact) as inputs and produces other artifacts as outputs. -Includes metadata like the command line arguments, action key, environment -variables, and declared input/output artifacts. - -**See also:** [Rules documentation](/extending/rules#actions) - -### Action cache - -An on-disk cache that stores a mapping of executed [actions](#action) to the -outputs they created. The cache key is known as the [action key](#action-key). A -core component for Bazel's incrementality model. The cache is stored in the -output base directory and thus survives Bazel server restarts. - -### Action graph - -An in-memory graph of [actions](#action) and the [artifacts](#artifact) that -these actions read and generate. The graph might include artifacts that exist as -source files (for example, in the file system) as well as generated -intermediate/final artifacts that are not mentioned in `BUILD` files. Produced -during the [analysis phase](#analysis-phase) and used during the [execution -phase](#execution-phase). - -### Action graph query (aquery) - -A [query](#query-concept) tool that can query over build [actions](#action). -This provides the ability to analyze how [build rules](#rule) translate into the -actual work builds do. - -### Action key - -The cache key of an [action](#action). Computed based on action metadata, which -might include the command to be executed in the action, compiler flags, library -locations, or system headers, depending on the action. Enables Bazel to cache or -invalidate individual actions deterministically. - -### Analysis phase - -The second phase of a build. Processes the [target graph](#target-graph) -specified in [`BUILD` files](#build-file) to produce an in-memory [action -graph](#action-graph) that determines the order of actions to run during the -[execution phase](#execution-phase). This is the phase in which rule -implementations are evaluated. - -### Artifact - -A source file or a generated file. Can also be a directory of files, known as -[tree artifacts](#tree-artifact). - -An artifact may be an input to multiple actions, but must only be generated by -at most one action. - -An artifact that corresponds to a [file target](#target) can be addressed by a -label. - -### Aspect - -A mechanism for rules to create additional [actions](#action) in their -dependencies. For example, if target A depends on B, one can apply an aspect on -A that traverses *up* a dependency edge to B, and runs additional actions in B -to generate and collect additional output files. These additional actions are -cached and reused between targets requiring the same aspect. Created with the -`aspect()` Starlark Build API function. Can be used, for example, to generate -metadata for IDEs, and create actions for linting. - -**See also:** [Aspects documentation](/extending/aspects) - -### Aspect-on-aspect - -A composition mechanism whereby aspects can be applied to the results -of other aspects. For example, an aspect that generates information for use by -IDEs can be applied on top of an aspect that generates `.java` files from a -proto. - -For an aspect `A` to apply on top of aspect `B`, the [providers](#provider) that -`B` advertises in its [`provides`](/rules/lib/globals#aspect.provides) attribute -must match what `A` declares it wants in its [`required_aspect_providers`](/rules/lib/globals#aspect.required_aspect_providers) -attribute. - -### Attribute - -A parameter to a [rule](#rule), used to express per-target build information. -Examples include `srcs`, `deps`, and `copts`, which respectively declare a -target's source files, dependencies, and custom compiler options. The particular -attributes available for a given target depend on its rule type. - -### .bazelrc - -Bazel’s configuration file used to change the default values for [startup -flags](#startup-flags) and [command flags](#command-flags), and to define common -groups of options that can then be set together on the Bazel command line using -a `--config` flag. Bazel can combine settings from multiple bazelrc files -(systemwide, per-workspace, per-user, or from a custom location), and a -`bazelrc` file may also import settings from other `bazelrc` files. - -### Blaze - -The Google-internal version of Bazel. Google’s main build system for its -mono-repository. - -### BUILD File - -A `BUILD` file is the main configuration file that tells Bazel what software -outputs to build, what their dependencies are, and how to build them. Bazel -takes a `BUILD` file as input and uses the file to create a graph of dependencies -and to derive the actions that must be completed to build intermediate and final -software outputs. A `BUILD` file marks a directory and any sub-directories not -containing a `BUILD` file as a [package](#package), and can contain -[targets](#target) created by [rules](#rule). The file can also be named -`BUILD.bazel`. - -### BUILD.bazel File - -See [`BUILD` File](#build-file). Takes precedence over a `BUILD` file in the same -directory. - -### .bzl File - -A file that defines rules, [macros](#macro), and constants written in -[Starlark](#starlark). These can then be imported into [`BUILD` -files](#build-file) using the `load()` function. - -// TODO: ### Build event protocol - -// TODO: ### Build flag - -### Build graph - -The dependency graph that Bazel constructs and traverses to perform a build. -Includes nodes like [targets](#target), [configured -targets](#configured-target), [actions](#action), and [artifacts](#artifact). A -build is considered complete when all [artifacts](#artifact) on which a set of -requested targets depend are verified as up-to-date. - -### Build setting - -A Starlark-defined piece of [configuration](#configuration). -[Transitions](#transition) can set build settings to change a subgraph's -configuration. If exposed to the user as a [command-line flag](#command-flags), -also known as a build flag. - -### Clean build - -A build that doesn't use the results of earlier builds. This is generally slower -than an [incremental build](#incremental-build) but commonly considered to be -more [correct](#correctness). Bazel guarantees both clean and incremental builds -are always correct. - -### Client-server model - -The `bazel` command-line client automatically starts a background server on the -local machine to execute Bazel [commands](#command). The server persists across -commands but automatically stops after a period of inactivity (or explicitly via -bazel shutdown). Splitting Bazel into a server and client helps amortize JVM -startup time and supports faster [incremental builds](#incremental-build) -because the [action graph](#action-graph) remains in memory across commands. - -### Command - -Used on the command line to invoke different Bazel functions, like `bazel -build`, `bazel test`, `bazel run`, and `bazel query`. - -### Command flags - -A set of flags specific to a [command](#command). Command flags are specified -*after* the command (`bazel build <command flags>`). Flags can be applicable to -one or more commands. For example, `--configure` is a flag exclusively for the -`bazel sync` command, but `--keep_going` is applicable to `sync`, `build`, -`test` and more. Flags are often used for [configuration](#configuration) -purposes, so changes in flag values can cause Bazel to invalidate in-memory -graphs and restart the [analysis phase](#analysis-phase). - -### Configuration - -Information outside of [rule](#rule) definitions that impacts how rules generate -[actions](#action). Every build has at least one configuration specifying the -target platform, action environment variables, and command-line [build -flags](#command-flags). [Transitions](#transition) may create additional -configurations, such as for host tools or cross-compilation. - -**See also:** [Configurations](/extending/rules#configurations) - -// TODO: ### Configuration fragment - -### Configuration trimming - -The process of only including the pieces of [configuration](#configuration) a -target actually needs. For example, if you build Java binary `//:j` with C++ -dependency `//:c`, it's wasteful to include the value of `--javacopt` in the -configuration of `//:c` because changing `--javacopt` unnecessarily breaks C++ -build cacheability. - -### Configured query (cquery) - -A [query](#query-concept) tool that queries over [configured -targets](#configured-target) (after the [analysis phase](#analysis-phase) -completes). This means `select()` and [build flags](#command-flags) (such as -`--platforms`) are accurately reflected in the results. - -**See also:** [cquery documentation](/query/cquery) - -### Configured target - -The result of evaluating a [target](#target) with a -[configuration](#configuration). The [analysis phase](#analysis-phase) produces -this by combining the build's options with the targets that need to be built. -For example, if `//:foo` builds for two different architectures in the same -build, it has two configured targets: `<//:foo, x86>` and `<//:foo, arm>`. - -### Correctness - -A build is correct when its output faithfully reflects the state of its -transitive inputs. To achieve correct builds, Bazel strives to be -[hermetic](#hermeticity), reproducible, and making [build -analysis](#analysis-phase) and [action execution](#execution-phase) -deterministic. - -### Dependency - -A directed edge between two [targets](#target). A target `//:foo` has a *target -dependency* on target `//:bar` if `//:foo`'s attribute values contain a -reference to `//:bar`. `//:foo` has an *action dependency* on `//:bar` if an -action in `//:foo` depends on an input [artifact](#artifact) created by an -action in `//:bar`. - -In certain contexts, it could also refer to an _external dependency_; see -[modules](#module). - -### Depset - -A data structure for collecting data on transitive dependencies. Optimized so -that merging depsets is time and space efficient, because it’s common to have -very large depsets (hundreds of thousands of files). Implemented to -recursively refer to other depsets for space efficiency reasons. [Rule](#rule) -implementations should not "flatten" depsets by converting them to lists unless -the rule is at the top level of the build graph. Flattening large depsets incurs -huge memory consumption. Also known as *nested sets* in Bazel's internal -implementation. - -**See also:** [Depset documentation](/extending/depsets) - -### Disk cache - -A local on-disk blob store for the remote caching feature. Can be used in -conjunction with an actual remote blob store. - -### Distdir - -A read-only directory containing files that Bazel would otherwise fetch from the -internet using repository rules. Enables builds to run fully offline. - -### Dynamic execution - -An execution strategy that selects between local and remote execution based on -various heuristics, and uses the execution results of the faster successful -method. Certain [actions](#action) are executed faster locally (for example, -linking) and others are faster remotely (for example, highly parallelizable -compilation). A dynamic execution strategy can provide the best possible -incremental and clean build times. - -### Execution phase - -The third phase of a build. Executes the [actions](#action) in the [action -graph](#action-graph) created during the [analysis phase](#analysis-phase). -These actions invoke executables (compilers, scripts) to read and write -[artifacts](#artifact). *Spawn strategies* control how these actions are -executed: locally, remotely, dynamically, sandboxed, docker, and so on. - -### Execution root - -A directory in the [workspace](#workspace)’s [output base](#output-base) -directory where local [actions](#action) are executed in -non-[sandboxed](#sandboxing) builds. The directory contents are mostly symlinks -of input [artifacts](#artifact) from the workspace. The execution root also -contains symlinks to external repositories as other inputs and the `bazel-out` -directory to store outputs. Prepared during the [loading phase](#loading-phase) -by creating a *symlink forest* of the directories that represent the transitive -closure of packages on which a build depends. Accessible with `bazel info -execution_root` on the command line. - -### File - -See [Artifact](#artifact). - -### Hermeticity - -A build is hermetic if there are no external influences on its build and test -operations, which helps to make sure that results are deterministic and -[correct](#correctness). For example, hermetic builds typically disallow network -access to actions, restrict access to declared inputs, use fixed timestamps and -timezones, restrict access to environment variables, and use fixed seeds for -random number generators - -### Incremental build - -An incremental build reuses the results of earlier builds to reduce build time -and resource usage. Dependency checking and caching aim to produce correct -results for this type of build. An incremental build is the opposite of a clean -build. - -// TODO: ### Install base - -### Label - -An identifier for a [target](#target). Generally has the form -`@repo//path/to/package:target`, where `repo` is the (apparent) name of the -[repository](#repository) containing the target, `path/to/package` is the path -to the directory that contains the [`BUILD` file](#build-file) declaring the -target (this directory is also known as the [package](#package)), and `target` -is the name of the target itself. Depending on the situation, parts of this -syntax may be omitted. - -**See also**: [Labels](/concepts/labels) - -### Loading phase - -The first phase of a build where Bazel executes [`BUILD` files](#build-file) to -create [packages](#package). [Macros](#macro) and certain functions like -`glob()` are evaluated in this phase. Interleaved with the second phase of the -build, the [analysis phase](#analysis-phase), to build up a [target -graph](#target-graph). - -### Legacy macro - -A flavor of [macro](#macro) which is declared as an ordinary -[Starlark](#starlark) function, and which runs as a side effect of executing a -`BUILD` file. - -Legacy macros can do anything a function can. This means they can be convenient, -but they can also be harder to read, write, and use. A legacy macro might -unexpectedly mutate its arguments or fail when given a `select()` or ill-typed -argument. - -Contrast with [symbolic macros](#symbolic-macro). - -**See also:** [Legacy macro documentation](/extending/legacy-macros) - -### Macro - -A mechanism to compose multiple [rule](#rule) target declarations together under -a single [Starlark](#starlark) callable. Enables reusing common rule declaration -patterns across `BUILD` files. Expanded to the underlying rule target -declarations during the [loading phase](#loading-phase). - -Comes in two flavors: [symbolic macros](#symbolic-macro) (since Bazel 8) and -[legacy macros](#legacy-macro). - -### Mnemonic - -A short, human-readable string selected by a rule author to quickly understand -what an [action](#action) in the rule is doing. Mnemonics can be used as -identifiers for *spawn strategy* selections. Some examples of action mnemonics -are `Javac` from Java rules, `CppCompile` from C++ rules, and -`AndroidManifestMerger` from Android rules. - -### Module - -A Bazel project that can have multiple versions, each of which can have -dependencies on other modules. This is analogous to familiar concepts in other -dependency management systems, such as a Maven _artifact_, an npm _package_, a -Go _module_, or a Cargo _crate_. Modules form the backbone of Bazel's external -dependency management system. - -Each module is backed by a [repo](#repository) with a `MODULE.bazel` file at its -root. This file contains metadata about the module itself (such as its name and -version), its direct dependencies, and various other data including toolchain -registrations and [module extension](#module-extension) input. - -Module metadata is hosted in Bazel registries. - -**See also:** [Bazel modules](/external/module) - -### Module Extension - -A piece of logic that can be run to generate [repos](#repository) by reading -inputs from across the [module](#module) dependency graph and invoking [repo -rules](#repository-rule). Module extensions have capabilities similar to repo -rules, allowing them to access the internet, perform file I/O, and so on. - -**See also:** [Module extensions](/external/extension) - -### Native rules - -[Rules](#rule) that are built into Bazel and implemented in Java. Such rules -appear in [`.bzl` files](#bzl-file) as functions in the native module (for -example, `native.cc_library` or `native.java_library`). User-defined rules -(non-native) are created using [Starlark](#starlark). - -### Output base - -A [workspace](#workspace)-specific directory to store Bazel output files. Used -to separate outputs from the *workspace*'s source tree (the [main -repo](#repository)). Located in the [output user root](#output-user-root). - -### Output groups - -A group of files that is expected to be built when Bazel finishes building a -target. [Rules](#rule) put their usual outputs in the "default output group" -(e.g the `.jar` file of a `java_library`, `.a` and `.so` for `cc_library` -targets). The default output group is the output group whose -[artifacts](#artifact) are built when a target is requested on the command line. -Rules can define more named output groups that can be explicitly specified in -[`BUILD` files](#build-file) (`filegroup` rule) or the command line -(`--output_groups` flag). - -### Output user root - -A user-specific directory to store Bazel's outputs. The directory name is -derived from the user's system username. Prevents output file collisions if -multiple users are building the same project on the system at the same time. -Contains subdirectories corresponding to build outputs of individual workspaces, -also known as [output bases](#output-base). - -### Package - -The set of [targets](#target) defined by a [`BUILD` file](#build-file). A -package's name is the `BUILD` file's path relative to the [repo](#repository) -root. A package can contain subpackages, or subdirectories containing `BUILD` -files, thus forming a package hierarchy. - -### Package group - -A [target](#target) representing a set of packages. Often used in `visibility` -attribute values. - -### Platform - -A "machine type" involved in a build. This includes the machine Bazel runs on -(the "host" platform), the machines build tools execute on ("exec" platforms), -and the machines targets are built for ("target platforms"). - -### Provider - -A schema describing a unit of information to pass between -[rule targets](#rule-target) along dependency relationships. Typically this -contains information like compiler options, transitive source or output files, -and build metadata. Frequently used in conjunction with [depsets](#depset) to -efficiently store accumulated transitive data. An example of a built-in provider -is `DefaultInfo`. - -Note: The object holding specific data for a given rule target is -referred to as a "provider instance", although sometimes this is conflated with -"provider". - -**See also:** [Provider documentation](/extending/rules#providers) - -### Query (concept) - -The process of analyzing a [build graph](#build-graph) to understand -[target](#target) properties and dependency structures. Bazel supports three -query variants: [query](#query-command), [cquery](#configured-query), and -[aquery](#action-graph-query). - -### query (command) - -A [query](#query-concept) tool that operates over the build's post-[loading -phase](#loading-phase) [target graph](#target-graph). This is relatively fast, -but can't analyze the effects of `select()`, [build flags](#command-flags), -[artifacts](#artifact), or build [actions](#action). - -**See also:** [Query how-to](/query/guide), [Query reference](/query/language) - -### Repository - -A directory tree with a boundary marker file at its root, containing source -files that can be used in a Bazel build. Often shortened to just **repo**. - -A repo boundary marker file can be `MODULE.bazel` (signaling that this repo -represents a Bazel module), `REPO.bazel`, or in legacy contexts, `WORKSPACE` or -`WORKSPACE.bazel`. Any repo boundary marker file will signify the boundary of a -repo; multiple such files can coexist in a directory. - -The *main repo* is the repo in which the current Bazel command is being run. - -*External repos* are defined by specifying [modules](#module) in `MODULE.bazel` -files, or invoking [repo rules](#repository-rule) in [module -extensions](#module-extension). They can be fetched on demand to a predetermined -"magical" location on disk. - -Each repo has a unique, constant *canonical* name, and potentially different -*apparent* names when viewed from other repos. - -**See also**: [External dependencies overview](/external/overview) - -### Repository cache - -A shared content-addressable cache of files downloaded by Bazel for builds, -shareable across [workspaces](#workspace). Enables offline builds after the -initial download. Commonly used to cache files downloaded through [repository -rules](#repository-rule) like `http_archive` and repository rule APIs like -`repository_ctx.download`. Files are cached only if their SHA-256 checksums are -specified for the download. - -### Repository rule - -A schema for repository definitions that tells Bazel how to materialize (or -"fetch") a [repository](#repository). Often shortened to just **repo rule**. -Repo rules are invoked by Bazel internally to define repos backed by -[modules](#module), or can be invoked by [module extensions](#module-extension). -Repo rules can access the internet or perform file I/O; the most common repo -rule is `http_archive` to download an archive containing source files from the -internet. - -**See also:** [Repo rule documentation](/external/repo) - -### Reproducibility - -The property of a build or test that a set of inputs to the build or test will -always produce the same set of outputs every time, regardless of time, method, -or environment. Note that this does not necessarily imply that the outputs are -[correct](#correctness) or the desired outputs. - -### Rule - -A schema for defining [rule targets](#rule-target) in a `BUILD` file, such as -`cc_library`. From the perspective of a `BUILD` file author, a rule consists of -a set of [attributes](#attributes) and black box logic. The logic tells the -rule target how to produce output [artifacts](#artifact) and pass information to -other rule targets. From the perspective of `.bzl` authors, rules are the -primary way to extend Bazel to support new programming languages and -environments. - -Rules are instantiated to produce rule targets in the -[loading phase](#loading-phase). In the [analysis phase](#analysis-phase) rule -targets communicate information to their downstream dependencies in the form of -[providers](#provider), and register [actions](#action) describing how to -generate their output artifacts. These actions are run in the [execution -phase](#execution-phase). - -Note: Historically the term "rule" has been used to refer to a rule target. -This usage was inherited from tools like Make, but causes confusion and should -be avoided for Bazel. - -**See also:** [Rules documentation](/extending/rules) - -### Rule target - -A [target](#target) that is an instance of a rule. Contrasts with file targets -and package groups. Not to be confused with [rule](#rule). - -### Runfiles - -The runtime dependencies of an executable [target](#target). Most commonly, the -executable is the executable output of a test rule, and the runfiles are runtime -data dependencies of the test. Before the invocation of the executable (during -bazel test), Bazel prepares the tree of runfiles alongside the test executable -according to their source directory structure. - -**See also:** [Runfiles documentation](/extending/rules#runfiles) - -### Sandboxing - -A technique to isolate a running [action](#action) inside a restricted and -temporary [execution root](#execution-root), helping to ensure that it doesn’t -read undeclared inputs or write undeclared outputs. Sandboxing greatly improves -[hermeticity](#hermeticity), but usually has a performance cost, and requires -support from the operating system. The performance cost depends on the platform. -On Linux, it's not significant, but on macOS it can make sandboxing unusable. - -### Skyframe - -[Skyframe](/reference/skyframe) is the core parallel, functional, and incremental evaluation framework of Bazel. - -// TODO: ### Spawn strategy - -### Stamping - -A feature to embed additional information into Bazel-built -[artifacts](#artifact). For example, this can be used for source control, build -time and other workspace or environment-related information for release builds. -Enable through the `--workspace_status_command` flag and [rules](/extending/rules) that -support the stamp attribute. - -### Starlark - -The extension language for writing [rules](/extending/rules) and [macros](#macro). A -restricted subset of Python (syntactically and grammatically) aimed for the -purpose of configuration, and for better performance. Uses the [`.bzl` -file](#bzl-file) extension. [`BUILD` files](#build-file) use an even more -restricted version of Starlark (such as no `def` function definitions), formerly -known as Skylark. - -**See also:** [Starlark language documentation](/rules/language) - -// TODO: ### Starlark rules - -// TODO: ### Starlark rule sandwich - -### Startup flags - -The set of flags specified between `bazel` and the [command](#query-command), -for example, bazel `--host_jvm_debug` build. These flags modify the -[configuration](#configuration) of the Bazel server, so any modification to -startup flags causes a server restart. Startup flags are not specific to any -command. - -### Symbolic macro - -A flavor of [macro](#macro) which is declared with a [rule](#rule)-like -[attribute](#attribute) schema, allows hiding internal declared -[targets](#target) from their own package, and enforces a predictable naming -pattern on the targets that the macro declares. Designed to avoid some of the -problems seen in large [legacy macro](#legacy-macro) codebases. - -**See also:** [Symbolic macro documentation](/extending/macros) - -### Target - -An object that is defined in a [`BUILD` file](#build-file) and identified by a -[label](#label). Targets represent the buildable units of a workspace from -the perspective of the end user. - -A target that is declared by instantiating a [rule](#rule) is called a [rule -target](#rule-target). Depending on the rule, these may be runnable (like -`cc_binary`) or testable (like `cc_test`). Rule targets typically depend on -other targets via their [attributes](#attribute) (such as `deps`); these -dependencies form the basis of the [target graph](#target-graph). - -Aside from rule targets, there are also file targets and [package group](#package-group) -targets. File targets correspond to [artifacts](#artifact) that are referenced -within a `BUILD` file. As a special case, the `BUILD` file of any package is -always considered a source file target in that package. - -Targets are discovered during the [loading phase](#loading-phase). During the -[analysis phase](#analysis-phase), targets are associated with [build -configurations](#configuration) to form [configured -targets](#configured-target). - -### Target graph - -An in-memory graph of [targets](#target) and their dependencies. Produced during -the [loading phase](#loading-phase) and used as an input to the [analysis -phase](#analysis-phase). - -### Target pattern - -A way to specify a group of [targets](#target) on the command line. Commonly -used patterns are `:all` (all rule targets), `:*` (all rule + file targets), -`...` (current [package](#package) and all subpackages recursively). Can be used -in combination, for example, `//...:*` means all rule and file targets in all -packages recursively from the root of the [workspace](#workspace). - -### Tests - -Rule [targets](#target) instantiated from test rules, and therefore contains a -test executable. A return code of zero from the completion of the executable -indicates test success. The exact contract between Bazel and tests (such as test -environment variables, test result collection methods) is specified in the [Test -Encyclopedia](/reference/test-encyclopedia). - -### Toolchain - -A set of tools to build outputs for a language. Typically, a toolchain includes -compilers, linkers, interpreters or/and linters. A toolchain can also vary by -platform, that is, a Unix compiler toolchain's components may differ for the -Windows variant, even though the toolchain is for the same language. Selecting -the right toolchain for the platform is known as toolchain resolution. - -### Top-level target - -A build [target](#target) is top-level if it’s requested on the Bazel command -line. For example, if `//:foo` depends on `//:bar`, and `bazel build //:foo` is -called, then for this build, `//:foo` is top-level, and `//:bar` isn’t -top-level, although both targets will need to be built. An important difference -between top-level and non-top-level targets is that [command -flags](#command-flags) set on the Bazel command line (or via -[.bazelrc](#bazelrc)) will set the [configuration](#configuration) for top-level -targets, but might be modified by a [transition](#transition) for non-top-level -targets. - -### Transition - -A mapping of [configuration](#configuration) state from one value to another. -Enables [targets](#target) in the [build graph](#build-graph) to have different -configurations, even if they were instantiated from the same [rule](#rule). A -common usage of transitions is with *split* transitions, where certain parts of -the [target graph](#target-graph) is forked with distinct configurations for -each fork. For example, one can build an Android APK with native binaries -compiled for ARM and x86 using split transitions in a single build. - -**See also:** [User-defined transitions](/extending/config#user-defined-transitions) - -### Tree artifact - -An [artifact](#artifact) that represents a collection of files. Since these -files are not themselves artifacts, an [action](#action) operating on them must -instead register the tree artifact as its input or output. - -### Visibility - -One of two mechanisms for preventing unwanted dependencies in the build system: -*target visibility* for controlling whether a [target](#target) can be depended -upon by other targets; and *load visibility* for controlling whether a `BUILD` -or `.bzl` file may load a given `.bzl` file. Without context, usually -"visibility" refers to target visibility. - -**See also:** [Visibility documentation](/concepts/visibility) - -### Workspace - -The environment shared by all Bazel commands run from the same [main -repository](#repository). - -Note that historically the concepts of "repository" and "workspace" have been -conflated; the term "workspace" has often been used to refer to the main -repository, and sometimes even used as a synonym of "repository". Such usage -should be avoided for clarity. diff --git a/reference/skyframe.mdx b/reference/skyframe.mdx deleted file mode 100644 index ba9149f..0000000 --- a/reference/skyframe.mdx +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: 'Skyframe' ---- - - - -The parallel evaluation and incrementality model of Bazel. - -## Data model - -The data model consists of the following items: - -* `SkyValue`. Also called nodes. `SkyValues` are immutable objects that - contain all the data built over the course of the build and the inputs of - the build. Examples are: input files, output files, targets and configured - targets. -* `SkyKey`. A short immutable name to reference a `SkyValue`, for example, - `FILECONTENTS:/tmp/foo` or `PACKAGE://foo`. -* `SkyFunction`. Builds nodes based on their keys and dependent nodes. -* Node graph. A data structure containing the dependency relationship between - nodes. -* `Skyframe`. Code name for the incremental evaluation framework Bazel is - based on. - -## Evaluation - -A build is achieved by evaluating the node that represents the build request. - -First, Bazel finds the `SkyFunction` corresponding to the key of the top-level -`SkyKey`. The function then requests the evaluation of the nodes it needs to -evaluate the top-level node, which in turn result in other `SkyFunction` calls, -until the leaf nodes are reached. Leaf nodes are usually ones that represent -input files in the file system. Finally, Bazel ends up with the value of the -top-level `SkyValue`, some side effects (such as output files in the file -system) and a directed acyclic graph of the dependencies between the nodes -involved in the build. - -A `SkyFunction` can request `SkyKeys` in multiple passes if it cannot tell in -advance all of the nodes it needs to do its job. A simple example is evaluating -an input file node that turns out to be a symlink: the function tries to read -the file, realizes that it is a symlink, and thus fetches the file system node -representing the target of the symlink. But that itself can be a symlink, in -which case the original function will need to fetch its target, too. - -The functions are represented in the code by the interface `SkyFunction` and the -services provided to it by an interface called `SkyFunction.Environment`. These -are the things functions can do: - -* Request the evaluation of another node by way of calling `env.getValue`. If - the node is available, its value is returned, otherwise, `null` is returned - and the function itself is expected to return `null`. In the latter case, - the dependent node is evaluated, and then the original node builder is - invoked again, but this time the same `env.getValue` call will return a - non-`null` value. -* Request the evaluation of multiple other nodes by calling `env.getValues()`. - This does essentially the same, except that the dependent nodes are - evaluated in parallel. -* Do computation during their invocation -* Have side effects, for example, writing files to the file system. Care needs - to be taken that two different functions avoid stepping on each other's - toes. In general, write side effects (where data flows outwards from Bazel) - are okay, read side effects (where data flows inwards into Bazel without a - registered dependency) are not, because they are an unregistered dependency - and as such, can cause incorrect incremental builds. - -Well-behaved `SkyFunction` implementations avoid accessing data in any other way -than requesting dependencies (such as by directly reading the file system), -because that results in Bazel not registering the data dependency on the file -that was read, thus resulting in incorrect incremental builds. - -Once a function has enough data to do its job, it should return a non-`null` -value indicating completion. - -This evaluation strategy has a number of benefits: - -* Hermeticity. If functions only request input data by way of depending on - other nodes, Bazel can guarantee that if the input state is the same, the - same data is returned. If all sky functions are deterministic, this means - that the whole build will also be deterministic. -* Correct and perfect incrementality. If all the input data of all functions - is recorded, Bazel can invalidate only the exact set of nodes that need to - be invalidated when the input data changes. -* Parallelism. Since functions can only interact with each other by way of - requesting dependencies, functions that don't depend on each other can be - run in parallel and Bazel can guarantee that the result is the same as if - they were run sequentially. - -## Incrementality - -Since functions can only access input data by depending on other nodes, Bazel -can build up a complete data flow graph from the input files to the output -files, and use this information to only rebuild those nodes that actually need -to be rebuilt: the reverse transitive closure of the set of changed input files. - -In particular, two possible incrementality strategies exist: the bottom-up one -and the top-down one. Which one is optimal depends on how the dependency graph -looks like. - -* During bottom-up invalidation, after a graph is built and the set of changed - inputs is known, all the nodes are invalidated that transitively depend on - changed files. This is optimal if the same top-level node will be built - again. Note that bottom-up invalidation requires running `stat()` on all - input files of the previous build to determine if they were changed. This - can be improved by using `inotify` or a similar mechanism to learn about - changed files. - -* During top-down invalidation, the transitive closure of the top-level node - is checked and only those nodes are kept whose transitive closure is clean. - This is better if the node graph is large, but the next build only needs a - small subset of it: bottom-up invalidation would invalidate the larger graph - of the first build, unlike top-down invalidation, which just walks the small - graph of second build. - -Bazel only does bottom-up invalidation. - -To get further incrementality, Bazel uses _change pruning_: if a node is -invalidated, but upon rebuild, it is discovered that its new value is the same -as its old value, the nodes that were invalidated due to a change in this node -are "resurrected". - -This is useful, for example, if one changes a comment in a C++ file: then the -`.o` file generated from it will be the same, thus, it is unnecessary to call -the linker again. - -## Incremental Linking / Compilation - -The main limitation of this model is that the invalidation of a node is an -all-or-nothing affair: when a dependency changes, the dependent node is always -rebuilt from scratch, even if a better algorithm would exist that would mutate -the old value of the node based on the changes. A few examples where this would -be useful: - -* Incremental linking -* When a single class file changes in a JAR file, it is possible - modify the JAR file in-place instead of building it from scratch again. - -The reason why Bazel does not support these things in a principled way -is twofold: - -* There were limited performance gains. -* Difficulty to validate that the result of the mutation is the same as that - of a clean rebuild would be, and Google values builds that are bit-for-bit - repeatable. - -Until now, it was possible to achieve good enough performance by decomposing an -expensive build step and achieving partial re-evaluation that way. For example, -in an Android app, you can split all the classes into multiple groups and dex -them separately. This way, if classes in a group are unchanged, the dexing does -not have to be redone. - -## Mapping to Bazel concepts - -This is high level summary of the key `SkyFunction` and `SkyValue` -implementations Bazel uses to perform a build: - -* **FileStateValue**. The result of an `lstat()`. For existent files, the - function also computes additional information in order to detect changes to - the file. This is the lowest level node in the Skyframe graph and has no - dependencies. -* **FileValue**. Used by anything that cares about the actual contents or - resolved path of a file. Depends on the corresponding `FileStateValue` and - any symlinks that need to be resolved (such as the `FileValue` for `a/b` - needs the resolved path of `a` and the resolved path of `a/b`). The - distinction between `FileValue` and `FileStateValue` is important because - the latter can be used in cases where the contents of the file are not - actually needed. For example, the file contents are irrelevant when - evaluating file system globs (such as `srcs=glob(["*/*.java"])`). -* **DirectoryListingStateValue**. The result of `readdir()`. Like - `FileStateValue`, this is the lowest level node and has no dependencies. -* **DirectoryListingValue**. Used by anything that cares about the entries of - a directory. Depends on the corresponding `DirectoryListingStateValue`, as - well as the associated `FileValue` of the directory. -* **PackageValue**. Represents the parsed version of a BUILD file. Depends on - the `FileValue` of the associated `BUILD` file, and also transitively on any - `DirectoryListingValue` that is used to resolve the globs in the package - (the data structure representing the contents of a `BUILD` file internally). -* **ConfiguredTargetValue**. Represents a configured target, which is a tuple - of the set of actions generated during the analysis of a target and - information provided to dependent configured targets. Depends on the - `PackageValue` the corresponding target is in, the `ConfiguredTargetValues` - of direct dependencies, and a special node representing the build - configuration. -* **ArtifactValue**. Represents a file in the build, be it a source or an - output artifact. Artifacts are almost equivalent to files, and are used to - refer to files during the actual execution of build steps. Source files - depends on the `FileValue` of the associated node, and output artifacts - depend on the `ActionExecutionValue` of whatever action generates the - artifact. -* **ActionExecutionValue**. Represents the execution of an action. Depends on - the `ArtifactValues` of its input files. The action it executes is contained - within its SkyKey, which is contrary to the concept that SkyKeys should be - small. Note that `ActionExecutionValue` and `ArtifactValue` are unused if - the execution phase does not run. - -As a visual aid, this diagram shows the relationships between -SkyFunction implementations after a build of Bazel itself: - -![A graph of SkyFunction implementation relationships](/reference/skyframe.png) From 2948dbb8c4c7c849a1005abed845ba177e4be181 Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sun, 12 Oct 2025 17:04:56 -0700 Subject: [PATCH 09/14] test better converter --- .github/workflows/pull-from-bazel-build.yml | 7 +- html_mdx_converter_test.sh | 180 + local_test.sh | 86 - reference/be/_toc.yaml | 33 + reference/be/be-nav.mdx | 27 + reference/be/c-cpp.mdx | 2460 +++ reference/be/common-definitions.mdx | 794 + reference/be/extra-actions.mdx | 210 + reference/be/functions.mdx | 708 + reference/be/general.mdx | 1200 ++ reference/be/java.mdx | 1901 +++ reference/be/make-variables.mdx | 393 + reference/be/objective-c.mdx | 384 + reference/be/overview.mdx | 134 + reference/be/platforms-and-toolchains.mdx | 544 + reference/be/protocol-buffer.mdx | 484 + reference/be/python.mdx | 984 ++ reference/be/shell.mdx | 218 + reference/command-line-reference.mdx | 13974 ++++++++++++++++ rules/bzl-style.mdx | 212 - rules/challenges.mdx | 223 - rules/deploying.mdx | 223 - rules/errors/read-only-variable.mdx | 30 - rules/faq.mdx | 80 - rules/index.mdx | 85 - rules/legacy-macro-tutorial.mdx | 98 - rules/lib/_toc.yaml | 297 + rules/lib/builtins.mdx | 122 +- rules/lib/builtins/Action.mdx | 55 +- rules/lib/builtins/Args.mdx | 219 +- rules/lib/builtins/Aspect.mdx | 3 +- rules/lib/builtins/Attribute.mdx | 3 +- rules/lib/builtins/BuildSetting.mdx | 3 +- rules/lib/builtins/CcCompilationOutputs.mdx | 11 +- rules/lib/builtins/CcLinkingOutputs.mdx | 15 +- rules/lib/builtins/CompilationContext.mdx | 77 +- rules/lib/builtins/DirectoryExpander.mdx | 13 +- rules/lib/builtins/DottedVersion.mdx | 13 +- rules/lib/builtins/ExecGroupCollection.mdx | 3 +- rules/lib/builtins/ExecGroupContext.mdx | 5 +- rules/lib/builtins/ExecTransitionFactory.mdx | 3 +- rules/lib/builtins/ExpandedDirectory.mdx | 11 +- rules/lib/builtins/FeatureConfiguration.mdx | 3 +- rules/lib/builtins/File.mdx | 69 +- rules/lib/builtins/Label.mdx | 76 +- rules/lib/builtins/LateBoundDefault.mdx | 3 +- rules/lib/builtins/LibraryToLink.mdx | 85 +- rules/lib/builtins/License.mdx | 3 +- rules/lib/builtins/LinkerInput.mdx | 23 +- rules/lib/builtins/LinkingContext.mdx | 5 +- rules/lib/builtins/Provider.mdx | 13 +- rules/lib/builtins/Subrule.mdx | 3 +- rules/lib/builtins/SymlinkEntry.mdx | 11 +- rules/lib/builtins/Target.mdx | 14 +- rules/lib/builtins/TemplateDict.mdx | 62 +- rules/lib/builtins/ToolchainContext.mdx | 3 +- rules/lib/builtins/actions.mdx | 543 +- rules/lib/builtins/apple_platform.mdx | 47 +- rules/lib/builtins/bazel_module.mdx | 25 +- rules/lib/builtins/bazel_module_tags.mdx | 6 +- rules/lib/builtins/configuration.mdx | 49 +- rules/lib/builtins/ctx.mdx | 357 +- rules/lib/builtins/depset.mdx | 31 +- rules/lib/builtins/exec_result.mdx | 19 +- rules/lib/builtins/extension_metadata.mdx | 5 +- rules/lib/builtins/fragments.mdx | 3 +- .../builtins/java_annotation_processing.mdx | 47 +- rules/lib/builtins/macro.mdx | 3 +- rules/lib/builtins/mapped_root.mdx | 7 +- rules/lib/builtins/module_ctx.mdx | 431 +- rules/lib/builtins/path.mdx | 66 +- rules/lib/builtins/propagation_ctx.mdx | 13 +- rules/lib/builtins/repo_metadata.mdx | 5 +- rules/lib/builtins/repository_ctx.mdx | 552 +- rules/lib/builtins/repository_os.mdx | 19 +- rules/lib/builtins/repository_rule.mdx | 5 +- rules/lib/builtins/root.mdx | 5 +- rules/lib/builtins/rule.mdx | 3 +- rules/lib/builtins/rule_attributes.mdx | 55 +- rules/lib/builtins/runfiles.mdx | 53 +- rules/lib/builtins/struct.mdx | 12 +- rules/lib/builtins/subrule_ctx.mdx | 25 +- rules/lib/builtins/tag_class.mdx | 5 +- rules/lib/builtins/template_ctx.mdx | 73 +- rules/lib/builtins/toolchain_type.mdx | 13 +- rules/lib/builtins/transition.mdx | 31 +- rules/lib/builtins/wasm_exec_result.mdx | 21 +- rules/lib/builtins/wasm_module.mdx | 7 +- rules/lib/core.mdx | 26 +- rules/lib/core/bool.mdx | 3 +- rules/lib/core/builtin_function_or_method.mdx | 5 +- rules/lib/core/dict.mdx | 145 +- rules/lib/core/float.mdx | 3 +- rules/lib/core/function.mdx | 3 +- rules/lib/core/int.mdx | 6 +- rules/lib/core/json.mdx | 91 +- rules/lib/core/list.mdx | 106 +- rules/lib/core/range.mdx | 7 +- rules/lib/core/set.mdx | 216 +- rules/lib/core/string.mdx | 433 +- rules/lib/core/tuple.mdx | 9 +- rules/lib/fragments.mdx | 26 +- rules/lib/fragments/apple.mdx | 24 +- rules/lib/fragments/bazel_android.mdx | 7 +- rules/lib/fragments/bazel_py.mdx | 13 +- rules/lib/fragments/coverage.mdx | 17 +- rules/lib/fragments/cpp.mdx | 65 +- rules/lib/fragments/j2objc.mdx | 5 +- rules/lib/fragments/java.mdx | 83 +- rules/lib/fragments/objc.mdx | 65 +- rules/lib/fragments/platform.mdx | 11 +- rules/lib/fragments/proto.mdx | 3 +- rules/lib/fragments/py.mdx | 41 +- rules/lib/globals.mdx | 14 +- rules/lib/globals/all.mdx | 450 +- rules/lib/globals/build.mdx | 252 +- rules/lib/globals/bzl.mdx | 904 +- rules/lib/globals/module.mdx | 422 +- rules/lib/globals/repo.mdx | 25 +- rules/lib/globals/vendor.mdx | 28 +- rules/lib/overview.mdx | 271 +- rules/lib/providers.mdx | 58 +- .../lib/providers/AnalysisTestResultInfo.mdx | 29 +- rules/lib/providers/CcInfo.mdx | 32 +- rules/lib/providers/CcToolchainConfigInfo.mdx | 3 +- rules/lib/providers/CcToolchainInfo.mdx | 134 +- rules/lib/providers/ConstraintCollection.mdx | 6 +- rules/lib/providers/ConstraintSettingInfo.mdx | 10 +- rules/lib/providers/ConstraintValueInfo.mdx | 6 +- rules/lib/providers/DebugPackageInfo.mdx | 57 +- rules/lib/providers/DefaultInfo.mdx | 69 +- rules/lib/providers/ExecutionInfo.mdx | 31 +- rules/lib/providers/FeatureFlagInfo.mdx | 28 +- rules/lib/providers/FilesToRunProvider.mdx | 23 +- .../IncompatiblePlatformProvider.mdx | 3 +- rules/lib/providers/InstrumentedFilesInfo.mdx | 11 +- rules/lib/providers/JavaRuntimeInfo.mdx | 71 +- rules/lib/providers/JavaToolchainInfo.mdx | 69 +- rules/lib/providers/MaterializedDepsInfo.mdx | 5 +- rules/lib/providers/ObjcProvider.mdx | 41 +- rules/lib/providers/OutputGroupInfo.mdx | 20 +- .../providers/PackageSpecificationInfo.mdx | 13 +- rules/lib/providers/PlatformInfo.mdx | 6 +- rules/lib/providers/RunEnvironmentInfo.mdx | 11 +- rules/lib/providers/TemplateVariableInfo.mdx | 7 +- rules/lib/providers/ToolchainInfo.mdx | 3 +- rules/lib/providers/ToolchainTypeInfo.mdx | 10 +- rules/lib/providers/file_provider.mdx | 5 +- rules/lib/providers/java_compilation_info.mdx | 25 +- rules/lib/providers/java_output_jars.mdx | 23 +- rules/lib/repo/cache.mdx | 79 + rules/lib/repo/git.mdx | 760 + rules/lib/repo/http.mdx | 1104 ++ rules/lib/repo/index.mdx | 12 + rules/lib/repo/local.mdx | 204 + rules/lib/repo/utils.mdx | 747 + rules/lib/toplevel.mdx | 24 +- rules/lib/toplevel/apple_common.mdx | 103 +- rules/lib/toplevel/attr.mdx | 679 +- rules/lib/toplevel/cc_common.mdx | 981 +- rules/lib/toplevel/config.mdx | 106 +- rules/lib/toplevel/config_common.mdx | 26 +- rules/lib/toplevel/coverage_common.mdx | 38 +- rules/lib/toplevel/java_common.mdx | 258 +- rules/lib/toplevel/native.mdx | 195 +- rules/lib/toplevel/platform_common.mdx | 34 +- rules/lib/toplevel/proto.mdx | 44 +- rules/lib/toplevel/testing.mdx | 64 +- rules/macro-tutorial.mdx | 116 - rules/performance.mdx | 302 - rules/rules-tutorial.mdx | 367 - rules/testing.mdx | 474 - rules/verbs-tutorial.mdx | 177 - 173 files changed, 35209 insertions(+), 5707 deletions(-) create mode 100755 html_mdx_converter_test.sh delete mode 100755 local_test.sh create mode 100644 reference/be/_toc.yaml create mode 100644 reference/be/be-nav.mdx create mode 100644 reference/be/c-cpp.mdx create mode 100644 reference/be/common-definitions.mdx create mode 100644 reference/be/extra-actions.mdx create mode 100644 reference/be/functions.mdx create mode 100644 reference/be/general.mdx create mode 100644 reference/be/java.mdx create mode 100644 reference/be/make-variables.mdx create mode 100644 reference/be/objective-c.mdx create mode 100644 reference/be/overview.mdx create mode 100644 reference/be/platforms-and-toolchains.mdx create mode 100644 reference/be/protocol-buffer.mdx create mode 100644 reference/be/python.mdx create mode 100644 reference/be/shell.mdx create mode 100644 reference/command-line-reference.mdx delete mode 100644 rules/bzl-style.mdx delete mode 100644 rules/challenges.mdx delete mode 100644 rules/deploying.mdx delete mode 100644 rules/errors/read-only-variable.mdx delete mode 100644 rules/faq.mdx delete mode 100644 rules/index.mdx delete mode 100644 rules/legacy-macro-tutorial.mdx create mode 100644 rules/lib/_toc.yaml create mode 100644 rules/lib/repo/cache.mdx create mode 100644 rules/lib/repo/git.mdx create mode 100644 rules/lib/repo/http.mdx create mode 100644 rules/lib/repo/index.mdx create mode 100644 rules/lib/repo/local.mdx create mode 100644 rules/lib/repo/utils.mdx delete mode 100644 rules/macro-tutorial.mdx delete mode 100644 rules/performance.mdx delete mode 100644 rules/rules-tutorial.mdx delete mode 100644 rules/testing.mdx delete mode 100644 rules/verbs-tutorial.mdx diff --git a/.github/workflows/pull-from-bazel-build.yml b/.github/workflows/pull-from-bazel-build.yml index f4afaf0..4dd1c33 100644 --- a/.github/workflows/pull-from-bazel-build.yml +++ b/.github/workflows/pull-from-bazel-build.yml @@ -47,12 +47,7 @@ jobs: with: bazelisk-cache: true repository-cache: true - - - name: Install pandoc - run: | - sudo apt-get update - sudo apt-get install -y pandoc - + - name: Build reference documentation working-directory: upstream run: > diff --git a/html_mdx_converter_test.sh b/html_mdx_converter_test.sh new file mode 100755 index 0000000..fb668f7 --- /dev/null +++ b/html_mdx_converter_test.sh @@ -0,0 +1,180 @@ +#!/bin/bash + +# Local test script for HTML to Markdown converter +# This runs the converter in a Go Docker container + +set -e # Exit on error + +# Colors for output +GREEN='\033[0;32m' +BLUE='\033[0;34m' +RED='\033[0;31m' +NC='\033[0m' # No Color + +echo -e "${BLUE}=== Testing HTML to Markdown Converter with Docker ===${NC}\n" + +# Check if Docker is running +if ! docker info > /dev/null 2>&1; then + echo -e "${RED}Error: Docker is not running. Please start Docker and try again.${NC}" + exit 1 +fi + +# Check if zip file exists +ZIP_FILE="${1:-reference-docs.zip}" +if [ ! -f "$ZIP_FILE" ]; then + echo -e "${RED}Error: Zip file '$ZIP_FILE' not found${NC}" + echo "Usage: $0 [path-to-zip-file]" + echo "Example: $0 upstream/bazel-bin/src/main/java/com/google/devtools/build/lib/reference-docs.zip" + exit 1 +fi + +# Get absolute path to zip file +ZIP_FILE_ABS=$(cd "$(dirname "$ZIP_FILE")" && pwd)/$(basename "$ZIP_FILE") + +echo -e "${GREEN}✓${NC} Found zip file: $ZIP_FILE_ABS" + +# Create output directory +OUTPUT_DIR="reference-docs-temp" +rm -rf "$OUTPUT_DIR" +mkdir -p "$OUTPUT_DIR" + +echo -e "${GREEN}✓${NC} Created output directory: $OUTPUT_DIR" + +# Run converter in Docker container +echo -e "\n${BLUE}Running converter in Go Docker container...${NC}\n" + +docker run --rm \ + -v "$(pwd)/html2md_converter:/app" \ + -v "$ZIP_FILE_ABS:/input/reference-docs.zip:ro" \ + -v "$(pwd)/$OUTPUT_DIR:/output" \ + -w /app \ + golang:1.21 \ + bash -c " + echo '==> Initializing Go module...' + go mod init html-to-md-converter + go get github.com/JohannesKaufmann/html-to-markdown + + echo '==> Building converter...' + go build -o html-to-md main.go + + echo '==> Running conversion...' + ./html-to-md -zip /input/reference-docs.zip -output /output + + echo '==> Done!' + " + +echo -e "\n${GREEN}✓${NC} Conversion complete!" + +# Show results +echo -e "\n${BLUE}=== Results ===${NC}" +echo "Output directory: $OUTPUT_DIR" +echo "" +echo "Directory structure:" +tree -L 3 "$OUTPUT_DIR" 2>/dev/null || find "$OUTPUT_DIR" -type f | head -20 + +echo -e "\n${BLUE}=== Sample converted file (before AWK) ===${NC}" +SAMPLE_FILE=$(find "$OUTPUT_DIR" -name "*.md" -type f | head -1) +if [ -n "$SAMPLE_FILE" ]; then + echo "File: $SAMPLE_FILE" + echo "---" + head -30 "$SAMPLE_FILE" + echo "..." +else + echo "No markdown files found" +fi + +# Run AWK transformation +echo -e "\n${BLUE}=== Running AWK transformation (MD -> MDX) ===${NC}" + +if [ ! -f "transform-docs.awk" ]; then + echo -e "${RED}Error: transform-docs.awk not found in current directory${NC}" + echo "Skipping AWK transformation step" +else + echo "Transforming to root-level reference/ and rules/ directories..." + echo "(This matches the GitHub workflow output structure)" + echo "" + + # Clean up any existing output directories + rm -rf reference rules + + echo "Transforming reference/ directory..." + find "$OUTPUT_DIR/reference" -name "*.md" -type f 2>/dev/null | while read -r file; do + # Extract path relative to reference-docs-temp/ + rel_path="${file#$OUTPUT_DIR/}" + output_file="$rel_path" + output_file="${output_file%.md}.mdx" + + # Create directory structure + mkdir -p "$(dirname "$output_file")" + + # Transform file + awk -f transform-docs.awk "$file" > "$output_file" + echo " ✓ $rel_path -> $output_file" + done + + # Copy YAML files from reference/ + find "$OUTPUT_DIR/reference" -name "*.yaml" -type f 2>/dev/null | while read -r file; do + rel_path="${file#$OUTPUT_DIR/}" + output_file="$rel_path" + mkdir -p "$(dirname "$output_file")" + cp "$file" "$output_file" + echo " ✓ Copied $rel_path" + done + + echo "" + echo "Transforming rules/ directory..." + find "$OUTPUT_DIR/rules" -name "*.md" -type f 2>/dev/null | while read -r file; do + # Extract path relative to reference-docs-temp/ + rel_path="${file#$OUTPUT_DIR/}" + output_file="$rel_path" + output_file="${output_file%.md}.mdx" + + mkdir -p "$(dirname "$output_file")" + awk -f transform-docs.awk "$file" > "$output_file" + echo " ✓ $rel_path -> $output_file" + done + + # Copy YAML files from rules/ + find "$OUTPUT_DIR/rules" -name "*.yaml" -type f 2>/dev/null | while read -r file; do + rel_path="${file#$OUTPUT_DIR/}" + output_file="$rel_path" + mkdir -p "$(dirname "$output_file")" + cp "$file" "$output_file" + echo " ✓ Copied $rel_path" + done + + echo -e "\n${GREEN}✓${NC} AWK transformation complete!" + + # Show MDX output + echo -e "\n${BLUE}=== MDX Output Directories (Root Level) ===${NC}" + echo "Output directories:" + echo " - reference/" + echo " - rules/" + echo "" + echo "Directory structure:" + echo "" + echo "reference/:" + tree -L 3 reference 2>/dev/null || find reference -type f | head -20 + echo "" + echo "rules/:" + tree -L 3 rules 2>/dev/null || find rules -type f | head -20 + + echo -e "\n${BLUE}=== Sample MDX file (after AWK) ===${NC}" + SAMPLE_MDX=$(find reference -name "*.mdx" -type f 2>/dev/null | head -1) + if [ -z "$SAMPLE_MDX" ]; then + SAMPLE_MDX=$(find rules -name "*.mdx" -type f 2>/dev/null | head -1) + fi + if [ -n "$SAMPLE_MDX" ]; then + echo "File: $SAMPLE_MDX" + echo "---" + head -40 "$SAMPLE_MDX" + echo "..." + fi +fi + +echo -e "\n${GREEN}✓${NC} Test complete!" +echo -e "\nOutput directories:" +echo " - Markdown (HTML->MD): $OUTPUT_DIR" +if [ -d "reference" ] && [ -d "rules" ]; then + echo " - MDX (MD->MDX): reference/ and rules/ (at repo root)" +fi \ No newline at end of file diff --git a/local_test.sh b/local_test.sh deleted file mode 100755 index 3c90892..0000000 --- a/local_test.sh +++ /dev/null @@ -1,86 +0,0 @@ -#!/bin/bash - -# Local test script for HTML to Markdown converter -# This runs the converter in a Go Docker container - -set -e # Exit on error - -# Colors for output -GREEN='\033[0;32m' -BLUE='\033[0;34m' -RED='\033[0;31m' -NC='\033[0m' # No Color - -echo -e "${BLUE}=== Testing HTML to Markdown Converter with Docker ===${NC}\n" - -# Check if Docker is running -if ! docker info > /dev/null 2>&1; then - echo -e "${RED}Error: Docker is not running. Please start Docker and try again.${NC}" - exit 1 -fi - -# Check if zip file exists -ZIP_FILE="${1:-reference-docs.zip}" -if [ ! -f "$ZIP_FILE" ]; then - echo -e "${RED}Error: Zip file '$ZIP_FILE' not found${NC}" - echo "Usage: $0 [path-to-zip-file]" - echo "Example: $0 upstream/bazel-bin/src/main/java/com/google/devtools/build/lib/reference-docs.zip" - exit 1 -fi - -# Get absolute path to zip file -ZIP_FILE_ABS=$(cd "$(dirname "$ZIP_FILE")" && pwd)/$(basename "$ZIP_FILE") - -echo -e "${GREEN}✓${NC} Found zip file: $ZIP_FILE_ABS" - -# Create output directory -OUTPUT_DIR="reference-docs-temp" -rm -rf "$OUTPUT_DIR" -mkdir -p "$OUTPUT_DIR" - -echo -e "${GREEN}✓${NC} Created output directory: $OUTPUT_DIR" - -# Run converter in Docker container -echo -e "\n${BLUE}Running converter in Go Docker container...${NC}\n" - -docker run --rm \ - -v "$(pwd)/html2md_converter:/app" \ - -v "$ZIP_FILE_ABS:/input/reference-docs.zip:ro" \ - -v "$(pwd)/$OUTPUT_DIR:/output" \ - -w /app \ - golang:1.21 \ - bash -c " - echo '==> Initializing Go module...' - go mod init html-to-md-converter - go get github.com/JohannesKaufmann/html-to-markdown - - echo '==> Building converter...' - go build -o html-to-md main.go - - echo '==> Running conversion...' - ./html-to-md -zip /input/reference-docs.zip -output /output - - echo '==> Done!' - " - -echo -e "\n${GREEN}✓${NC} Conversion complete!" - -# Show results -echo -e "\n${BLUE}=== Results ===${NC}" -echo "Output directory: $OUTPUT_DIR" -echo "" -echo "Directory structure:" -tree -L 3 "$OUTPUT_DIR" 2>/dev/null || find "$OUTPUT_DIR" -type f | head -20 - -echo -e "\n${BLUE}=== Sample converted file ===${NC}" -SAMPLE_FILE=$(find "$OUTPUT_DIR" -name "*.md" -type f | head -1) -if [ -n "$SAMPLE_FILE" ]; then - echo "File: $SAMPLE_FILE" - echo "---" - head -30 "$SAMPLE_FILE" - echo "..." -else - echo "No markdown files found" -fi - -echo -e "\n${GREEN}✓${NC} Test complete! Check $OUTPUT_DIR for results" \ No newline at end of file diff --git a/reference/be/_toc.yaml b/reference/be/_toc.yaml new file mode 100644 index 0000000..b1cb8b0 --- /dev/null +++ b/reference/be/_toc.yaml @@ -0,0 +1,33 @@ +toc: +- title: Build encyclopedia + section: + - title: Overview + path: /reference/be/overview + - title: Common definitions + path: /reference/be/common-definitions + - title: Make variables + path: /reference/be/make-variables + - title: Functions + path: /reference/be/functions + - title: Core rules + section: + - title: Extra Actions + path: /reference/be/extra-actions + - title: General + path: /reference/be/general + - title: Platforms and Toolchains + path: /reference/be/platforms-and-toolchains + - title: Language Specific rules + section: + - title: C / C++ + path: /reference/be/c-cpp + - title: Java + path: /reference/be/java + - title: Objective-C + path: /reference/be/objective-c + - title: Protocol Buffer + path: /reference/be/protocol-buffer + - title: Python + path: /reference/be/python + - title: Shell + path: /reference/be/shell diff --git a/reference/be/be-nav.mdx b/reference/be/be-nav.mdx new file mode 100644 index 0000000..fbf211d --- /dev/null +++ b/reference/be/be-nav.mdx @@ -0,0 +1,27 @@ +\*\*Build Encyclopedia\*\* +- [Overview](/reference/be/overview.html) +- [Concepts](#be-menu) - [Common Definitions](/reference/be/common-definitions.html) + - ["Make" variables](/reference/be/make-variables.html) +- [Rules](#be-rules) - [Functions](/reference/be/functions.html) + - [C / C++](/reference/be/c-cpp.html) + - [Java](/reference/be/java.html) + - [Objective-C](/reference/be/objective-c.html) + - [Protocol Buffer](/reference/be/protocol-buffer.html) + - [Python](/reference/be/python.html) + - [Shell](/reference/be/shell.html) + - [Extra Actions](/reference/be/extra-actions.html) + - [General](/reference/be/general.html) + - [Platforms and Toolchains](/reference/be/platforms-and-toolchains.html) + - [AppEngine](https://github.com/bazelbuild/rules_appengine) + - [Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)](https://github.com/bazelbuild/rules_apple) + - [C#](https://github.com/bazelbuild/rules_dotnet) + - [D](https://github.com/bazelbuild/rules_d) + - [Docker](https://github.com/bazelbuild/rules_docker) + - [Groovy](https://github.com/bazelbuild/rules_groovy) + - [Go](https://github.com/bazelbuild/rules_go) + - [JavaScript (Closure)](https://github.com/bazelbuild/rules_closure) + - [Jsonnet](https://github.com/bazelbuild/rules_jsonnet) + - [Packaging](/reference/be/pkg.html) + - [Rust](https://github.com/bazelbuild/rules_rust) + - [Sass](https://github.com/bazelbuild/rules_sass) + - [Scala](https://github.com/bazelbuild/rules_scala) diff --git a/reference/be/c-cpp.mdx b/reference/be/c-cpp.mdx new file mode 100644 index 0000000..01cacc9 --- /dev/null +++ b/reference/be/c-cpp.mdx @@ -0,0 +1,2460 @@ +--- +title: 'C / C++ Rules' +--- + + + +## Rules + +- [cc\_binary](#cc_binary) +- [cc\_import](#cc_import) +- [cc\_library](#cc_library) +- [cc\_shared\_library](#cc_shared_library) +- [cc\_static\_library](#cc_static_library) +- [cc\_test](#cc_test) +- [cc\_toolchain](#cc_toolchain) +- [fdo\_prefetch\_hints](#fdo_prefetch_hints) +- [fdo\_profile](#fdo_profile) +- [memprof\_profile](#memprof_profile) +- [propeller\_optimize](#propeller_optimize) + +## cc\_binary + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_binary.bzl) + +``` +cc_binary(name, deps, srcs, data, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local_defines, malloc, module_interfaces, nocopts, output_licenses, package_metadata, reexport_deps, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file) +``` + +It produces an executable binary. + +The `name` of the target should be the same as the name of the +source file that is the main entry point of the application (minus the extension). +For example, if your entry point is in `main.cc`, then your name should +be `main`. + +#### Implicit output targets + +- `name.stripped` (only built if explicitly requested): A stripped + version of the binary. `strip -g` is run on the binary to remove debug + symbols. Additional strip options can be provided on the command line using + `--stripopt=-foo`. +- `name.dwp` (only built if explicitly requested): If + [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug + information package file suitable for debugging remotely deployed binaries. Else: an + empty file. + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries to be linked in to the binary target. + +These can be `cc_library` or `objc_library` +targets. + +It is also allowed to +put linker scripts (.lds) into deps, and reference them in +[linkopts](#cc_binary.linkopts). + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of C and C++ files that are processed to create the library target. +These are C/C++ source and header files, either non-generated (normal source +code) or generated. + +All `.cc`, `.c`, and `.cpp` files will +be compiled. These might be generated files: if a named file is in +the `outs` of some other rule, this `cc_library` +will automatically depend on that other rule. + +Pure assembler files (.s, .asm) are not preprocessed and are typically built using +the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built +using the C/C++ compiler. + +A `.h` file will not be compiled, but will be available for +inclusion by sources in this rule. Both `.cc` and +`.h` files can directly include headers listed in +these `srcs` or in the `hdrs` of this rule or any +rule listed in the `deps` argument. + +All `#include` d files must be mentioned in the +`hdrs` attribute of this or referenced `cc_library` +rules, or they should be listed in `srcs` if they are private +to this library. See ["Header inclusion checking"](#hdrs) for +a more detailed description. + +`.so`, `.lo`, and `.a` files are +pre-compiled files. Your library might have these as +`srcs` if it uses third-party code for which we don't +have source code. + +If the `srcs` attribute includes the label of another rule, +`cc_library` will use the output files of that rule as source files to +compile. This is useful for one-off generation of source code (for more than occasional +use, it's better to implement a Starlark rule class and use the `cc_common` +API) + +Permitted `srcs` file types: + +- C and C++ source files: `.c`, `.cc`, `.cpp`, + `.cxx`, `.c++`, `.C` +- C and C++ header files: `.h`, `.hh`, `.hpp`, + `.hxx`, `.inc`, `.inl`, `.H` +- Assembler with C preprocessor: `.S` +- Archive: `.a`, `.pic.a` +- "Always link" library: `.lo`, `.pic.lo` +- Shared library, versioned or unversioned: `.so`, + `.so.version` +- Object file: `.o`, `.pic.o` + +... and any rules that produce those files (e.g. `cc_embed_data`). +Different extensions denote different programming languages in +accordance with gcc convention. + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this library at runtime. + +See general comments about `data` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + +If a `data` is the name of a generated file, then this +`cc_library` rule automatically depends on the generating +rule. + +If a `data` is a rule name, then this +`cc_library` rule automatically depends on that rule, +and that rule's `outs` are automatically added to +this `cc_library`'s data files. + +Your C++ code can access these data files like so: + +```lang-starlark + + const std::string path = devtools_build::GetDataDependencyFilepath( + "my/test/data/file"); + +``` + +`additional_linker_inputs` + +List of [labels](/concepts/labels); default is `[]` + + Pass these files to the C++ linker command. + +For example, compiled Windows .res files can be provided here to be embedded in +the binary target. + +`conlyopts` + +List of strings; default is `[]` + + Add these options to the C compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + `copts` + +List of strings; default is `[]` + + Add these options to the C/C++ compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + +Each string in this attribute is added in the given order to `COPTS` before +compiling the binary target. The flags take effect only for compiling this target, not +its dependencies, so be careful about header files included elsewhere. +All paths should be relative to the workspace, not to the current package. +This attribute should not be needed outside of `third_party`. + +If the package declares the [feature](/reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings +that consist of a single "Make" variable. + +`cxxopts` + +List of strings; default is `[]` + + Add these options to the C++ compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + `defines` + +List of strings; default is `[]` + + List of defines to add to the compile line. +Subject to ["Make" variable](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +Each string, which must consist of a single Bourne shell token, +is prepended with `-D` and added to the compile command line to this target, +as well as to every rule that depends on it. Be very careful, since this may have +far-reaching effects. When in doubt, add define values to +[`local_defines`](#cc_binary.local_defines) instead. + `distribs` + +List of strings; default is `[]` + +`dynamic_deps` + +List of [labels](/concepts/labels); default is `[]` + + These are other `cc_shared_library` dependencies the current target depends on. + +The `cc_shared_library` implementation will use the list of +`dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the +current target's `dynamic_deps`) to decide which `cc_libraries` in +the transitive `deps` should not be linked in because they are already provided +by a different `cc_shared_library`. + + +`hdrs_check` + +String; default is `""` + + Deprecated, no-op. + `includes` + +List of strings; default is `[]` + + List of include dirs to be added to the compile line. +Subject to ["Make variable"](/reference/be/make-variables) substitution. +Each string is prepended with the package path and passed to the C++ toolchain for +expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system +with typical feature definitions will produce +`-isystem path_to_package/include_entry`. +This should only be used for third-party libraries that +do not conform to the Google style of writing #include statements. +Unlike [COPTS](#cc_binary.copts), these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-I" flags to [COPTS](#cc_binary.copts) instead. + +The added `include` paths will include generated files as well as +files in the source tree. + +`link_extra_lib` + +[Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` + + Control linking of extra libraries. + +By default, C++ binaries are linked against `//tools/cpp:link_extra_lib`, +which by default depends on the label flag `//tools/cpp:link_extra_libs`. +Without setting the flag, this library is empty by default. Setting the label flag +allows linking optional dependencies, such as overrides for weak symbols, interceptors +for shared library functions, or special runtime libraries (for malloc replacements, +prefer `malloc` or `--custom_malloc`). Setting this attribute to +`None` disables this behaviour. + +`linkopts` + +List of strings; default is `[]` + + Add these flags to the C++ linker command. +Subject to ["Make" variable](make-variables.html) substitution, +[Bourne shell tokenization](common-definitions.html#sh-tokenization) and +[label expansion](common-definitions.html#label-expansion). +Each string in this attribute is added to `LINKOPTS` before +linking the binary target. + +Each element of this list that does not start with `$` or `-` is +assumed to be the label of a target in `deps`. The +list of files generated by that target is appended to the linker +options. An error is reported if the label is invalid, or is +not declared in `deps`. + +`linkshared` + +Boolean; default is `False` + + Create a shared library. +To enable this attribute, include `linkshared=True` in your rule. By default +this option is off. + +The presence of this flag means that linking occurs with the `-shared` flag +to `gcc`, and the resulting shared library is suitable for loading into for +example a Java program. However, for build purposes it will never be linked into the +dependent binary, as it is assumed that shared libraries built with a +[cc\_binary](#cc_binary) rule are only loaded manually by other programs, so +it should not be considered a substitute for the [cc\_library](#cc_library) +rule. For sake of scalability we recommend avoiding this approach altogether and +simply letting `java_library` depend on `cc_library` rules +instead. + +If you specify both `linkopts=['-static']` and `linkshared=True`, +you get a single completely self-contained unit. If you specify both +`linkstatic=True` and `linkshared=True`, you get a single, mostly +self-contained unit. + +`linkstatic` + +Boolean; default is `True` + + For [`cc_binary`](/reference/be/c-cpp.html#cc_binary) and +[`cc_test`](/reference/be/c-cpp.html#cc_test): link the binary in static +mode. For `cc_library.link_static`: see below. + +By default this option is on for `cc_binary` and off for the rest. + +If enabled and this is a binary or test, this option tells the build tool to link in +`.a`'s instead of `.so`'s for user libraries whenever possible. +System libraries such as libc (but _not_ the C/C++ runtime libraries, +see below) are still linked dynamically, as are libraries for which +there is no static library. So the resulting executable will still be dynamically +linked, hence only _mostly_ static. + +There are really three different ways to link an executable: + +- STATIC with fully\_static\_link feature, in which everything is linked statically; + e.g. " `gcc -static foo.o libbar.a libbaz.a -lm`". + + + This mode is enabled by specifying `fully_static_link` in the + [`features`](/reference/be/common-definitions#features) attribute. +- STATIC, in which all user libraries are linked statically (if a static + version is available), but where system libraries (excluding C/C++ runtime libraries) + are linked dynamically, e.g. " `gcc foo.o libfoo.a libbaz.a -lm`". + + + This mode is enabled by specifying `linkstatic=True`. +- DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is + available), e.g. " `gcc foo.o libfoo.so libbaz.so -lm`". + + + This mode is enabled by specifying `linkstatic=False`. + +If the `linkstatic` attribute or `fully_static_link` in +`features` is used outside of `//third_party` +please include a comment near the rule to explain why. + +The `linkstatic` attribute has a different meaning if used on a +[`cc_library()`](/reference/be/c-cpp.html#cc_library) rule. +For a C++ library, `linkstatic=True` indicates that only +static linking is allowed, so no `.so` will be produced. linkstatic=False does +not prevent static libraries from being created. The attribute is meant to control the +creation of dynamic libraries. + +There should be very little code built with `linkstatic=False` in production. +If `linkstatic=False`, then the build tool will create symlinks to +depended-upon shared libraries in the `*.runfiles` area. + +`local_defines` + +List of strings; default is `[]` + + List of defines to add to the compile line. +Subject to ["Make" variable](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +Each string, which must consist of a single Bourne shell token, +is prepended with `-D` and added to the compile command line for this target, +but not to its dependents. + `malloc` + +[Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` + + Override the default dependency on malloc. + +By default, C++ binaries are linked against `//tools/cpp:malloc`, +which is an empty library so the binary ends up using libc malloc. +This label must refer to a `cc_library`. If compilation is for a non-C++ +rule, this option has no effect. The value of this attribute is ignored if +`linkshared=True` is specified. + +`module_interfaces` + +List of [labels](/concepts/labels); default is `[]` + + The list of files are regarded as C++20 Modules Interface. + +C++ Standard has no restriction about module interface file extension + +- Clang use cppm +- GCC can use any source file extension +- MSVC use ixx + +The use is guarded by the flag +`--experimental_cpp_modules`. + +`nocopts` + +String; default is `""` + + Remove matching options from the C++ compilation command. +Subject to ["Make" variable](/reference/be/make-variables) substitution. +The value of this attribute is interpreted as a regular expression. +Any preexisting `COPTS` that match this regular expression +(including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) +will be removed from `COPTS` for purposes of compiling this rule. +This attribute should not be needed or used +outside of `third_party`. The values are not preprocessed +in any way other than the "Make" variable substitution. + `reexport_deps` + +List of [labels](/concepts/labels); default is `[]` + +`stamp` + +Integer; default is `-1` + + Whether to encode build information into the binary. Possible values: + +- `stamp = 1`: Always stamp the build information into the binary, even in + [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This** + **setting should be avoided**, since it potentially kills remote caching for the + binary and any downstream actions that depend on it. + +- `stamp = 0`: Always replace build information by constant values. This + gives good build result caching. + +- `stamp = -1`: Embedding of build information is controlled by the + [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. + + +Stamped binaries are _not_ rebuilt unless their dependencies change. + +`win_def_file` + +[Label](/concepts/labels); default is `None` + + The Windows DEF file to be passed to linker. + +This attribute should only be used when Windows is the target platform. +It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. + +## cc\_import + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_import.bzl) + +``` +cc_import(name, deps, data, hdrs, alwayslink, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, includes, interface_library, linkopts, objects, package_metadata, pic_objects, pic_static_library, restricted_to, shared_library, static_library, strip_include_prefix, system_provided, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`cc_import` rules allows users to import precompiled C/C++ libraries. + +The following are the typical use cases: + +1\. Linking a static library + +```lang-starlark + +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + static_library = "libmylib.a", + # If alwayslink is turned on, + # libmylib.a will be forcely linked into any binary that depends on it. + # alwayslink = 1, +) + +``` + +2\. Linking a shared library (Unix) + +```lang-starlark + +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + shared_library = "libmylib.so", +) + +``` + +3\. Linking a shared library with interface library + +On Unix: + +```lang-starlark + +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + # libmylib.ifso is an interface library for libmylib.so which will be passed to linker + interface_library = "libmylib.ifso", + # libmylib.so will be available for runtime + shared_library = "libmylib.so", +) + +``` + +On Windows: + +```lang-starlark + +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + # mylib.lib is an import library for mylib.dll which will be passed to linker + interface_library = "mylib.lib", + # mylib.dll will be available for runtime + shared_library = "mylib.dll", +) + +``` + +4\. Linking a shared library with `system_provided=True` + +On Unix: + +```lang-starlark + +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + interface_library = "libmylib.ifso", # Or we can also use libmylib.so as its own interface library + # libmylib.so is provided by system environment, for example it can be found in LD_LIBRARY_PATH. + # This indicates that Bazel is not responsible for making libmylib.so available. + system_provided = 1, +) + +``` + +On Windows: + +```lang-starlark + +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + # mylib.lib is an import library for mylib.dll which will be passed to linker + interface_library = "mylib.lib", + # mylib.dll is provided by system environment, for example it can be found in PATH. + # This indicates that Bazel is not responsible for making mylib.dll available. + system_provided = 1, +) + +``` + +5\. Linking to static or shared library + +On Unix: + +```lang-starlark + +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + static_library = "libmylib.a", + shared_library = "libmylib.so", +) + +``` + +On Windows: + +```lang-starlark + +cc_import( + name = "mylib", + hdrs = ["mylib.h"], + static_library = "libmylib.lib", # A normal static library + interface_library = "mylib.lib", # An import library for mylib.dll + shared_library = "mylib.dll", +) + +``` + +The remaining is the same on Unix and Windows: + +```lang-starlark + +# first will link to libmylib.a (or libmylib.lib) +cc_binary( + name = "first", + srcs = ["first.cc"], + deps = [":mylib"], + linkstatic = 1, # default value +) + +# second will link to libmylib.so (or libmylib.lib) +cc_binary( + name = "second", + srcs = ["second.cc"], + deps = [":mylib"], + linkstatic = 0, +) + +``` + +`cc_import` supports an include attribute. For example: + +```lang-starlark + +cc_import( + name = "curl_lib", + hdrs = glob(["vendor/curl/include/curl/*.h"]), + includes = ["vendor/curl/include"], + shared_library = "vendor/curl/lib/.libs/libcurl.dylib", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries that the target depends upon. +See general comments about `deps` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + `hdrs` + +List of [labels](/concepts/labels); default is `[]` + + The list of header files published by +this precompiled library to be directly included by sources in dependent rules. + `alwayslink` + +Boolean; default is `False` + + If 1, any binary that depends (directly or indirectly) on this C++ +precompiled library will link in all the object files archived in the static library, +even if some contain no symbols referenced by the binary. +This is useful if your code isn't explicitly called by code in +the binary, e.g., if your code registers to receive some callback +provided by some service. + +If alwayslink doesn't work with VS 2017 on Windows, that is due to a +[known issue](https://github.com/bazelbuild/bazel/issues/3949), +please upgrade your VS 2017 to the latest version. + +`includes` + +List of strings; default is `[]` + + List of include dirs to be added to the compile line. +Subject to ["Make variable"](/reference/be/make-variables) substitution. +Each string is prepended with the package path and passed to the C++ toolchain for +expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system +with typical feature definitions will produce +`-isystem path_to_package/include_entry`. +This should only be used for third-party libraries that +do not conform to the Google style of writing #include statements. +Unlike [COPTS](#cc_binary.copts), these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-I" flags to [COPTS](#cc_binary.copts) instead. + +The default `include` path doesn't include generated +files. If you need to `#include` a generated header +file, list it in the `srcs`. + +`interface_library` + +[Label](/concepts/labels); default is `None` + + A single interface library for linking the shared library. + +Permitted file types: +`.ifso`, +`.tbd`, +`.lib`, +`.so` +or `.dylib` + +`linkopts` + +List of strings; default is `[]` + + Add these flags to the C++ linker command. +Subject to ["Make" variable](make-variables.html) substitution, +[Bourne shell tokenization](common-definitions.html#sh-tokenization) and +[label expansion](common-definitions.html#label-expansion). +Each string in this attribute is added to `LINKOPTS` before +linking the binary target. + +Each element of this list that does not start with `$` or `-` is +assumed to be the label of a target in `deps`. The +list of files generated by that target is appended to the linker +options. An error is reported if the label is invalid, or is +not declared in `deps`. + +`objects` + +List of [labels](/concepts/labels); default is `[]` + +`pic_objects` + +List of [labels](/concepts/labels); default is `[]` + +`pic_static_library` + +[Label](/concepts/labels); default is `None` + +`shared_library` + +[Label](/concepts/labels); default is `None` + + A single precompiled shared library. Bazel ensures it is available to the +binary that depends on it during runtime. + +Permitted file types: +`.so`, +`.dll` +or `.dylib` + +`static_library` + +[Label](/concepts/labels); default is `None` + + A single precompiled static library. + +Permitted file types: +`.a`, +`.pic.a` +or `.lib` + +`strip_include_prefix` + +String; default is `""` + + The prefix to strip from the paths of the headers of this rule. + +When set, the headers in the `hdrs` attribute of this rule are accessible +at their path with this prefix cut off. + +If it's a relative path, it's taken as a package-relative one. If it's an absolute one, +it's understood as a repository-relative path. + +The prefix in the `include_prefix` attribute is added after this prefix is +stripped. + +This attribute is only legal under `third_party`. + + +`system_provided` + +Boolean; default is `False` + + If 1, it indicates the shared library required at runtime is provided by the system. In +this case, `interface_library` should be specified and +`shared_library` should be empty. + + +## cc\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_library.bzl) + +``` +cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, module_interfaces, package_metadata, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file) +``` + +Use `cc_library()` for C++-compiled libraries. +The result is either a `.so`, `.lo`, +or `.a`, depending on what is needed. + +If you build something with static linking that depends on +a `cc_library`, the output of a depended-on library rule +is the `.a` file. If you specify +`alwayslink=True`, you get the `.lo` file. + +The actual output file name is `libfoo.so` for +the shared library, where _foo_ is the name of the rule. The +other kinds of libraries end with `.lo` and `.a`, +respectively. If you need a specific shared library name, for +example, to define a Python module, use a genrule to copy the library +to the desired name. + +#### Header inclusion checking + +All header files that are used in the build must be declared in +the `hdrs` or `srcs` of `cc_*` rules. +This is enforced. + +For `cc_library` rules, headers in `hdrs` comprise the +public interface of the library and can be directly included both +from the files in `hdrs` and `srcs` of the library +itself as well as from files in `hdrs` and `srcs` +of `cc_*` rules that list the library in their `deps`. +Headers in `srcs` must only be directly included from the files +in `hdrs` and `srcs` of the library itself. When +deciding whether to put a header into `hdrs` or `srcs`, +you should ask whether you want consumers of this library to be able to +directly include it. This is roughly the same decision as +between `public` and `private` visibility in programming languages. + +`cc_binary` and `cc_test` rules do not have an exported +interface, so they also do not have a `hdrs` attribute. All headers +that belong to the binary or test directly should be listed in +the `srcs`. + +To illustrate these rules, look at the following example. + +```lang-starlark + +cc_binary( + name = "foo", + srcs = [ + "foo.cc", + "foo.h", + ], + deps = [":bar"], +) + +cc_library( + name = "bar", + srcs = [ + "bar.cc", + "bar-impl.h", + ], + hdrs = ["bar.h"], + deps = [":baz"], +) + +cc_library( + name = "baz", + srcs = [ + "baz.cc", + "baz-impl.h", + ], + hdrs = ["baz.h"], +) + +``` + +The allowed direct inclusions in this example are listed in the table below. +For example `foo.cc` is allowed to directly +include `foo.h` and `bar.h`, but not `baz.h`. + +Including fileAllowed inclusionsfoo.hbar.hfoo.ccfoo.h bar.hbar.hbar-impl.h baz.hbar-impl.hbar.h baz.hbar.ccbar.h bar-impl.h baz.hbaz.hbaz-impl.hbaz-impl.hbaz.hbaz.ccbaz.h baz-impl.h + +The inclusion checking rules only apply to _direct_ +inclusions. In the example above `foo.cc` is allowed to +include `bar.h`, which may include `baz.h`, which in +turn is allowed to include `baz-impl.h`. Technically, the +compilation of a `.cc` file may transitively include any header +file in the `hdrs` or `srcs` in +any `cc_library` in the transitive `deps` closure. In +this case the compiler may read `baz.h` and `baz-impl.h` +when compiling `foo.cc`, but `foo.cc` must not +contain `#include "baz.h"`. For that to be +allowed, `baz` must be added to the `deps` +of `foo`. + +Bazel depends on toolchain support to enforce the inclusion checking rules. +The `layering_check` feature has to be supported by the toolchain +and requested explicitly, for example via the +`--features=layering_check` command-line flag or the +`features` parameter of the +[`package`](/reference/be/functions.html#package) function. The toolchains +provided by Bazel only support this feature with clang on Unix and macOS. + +#### Examples + +We use the `alwayslink` flag to force the linker to link in +this code although the main binary code doesn't reference it. + +```lang-starlark + +cc_library( + name = "ast_inspector_lib", + srcs = ["ast_inspector_lib.cc"], + hdrs = ["ast_inspector_lib.h"], + visibility = ["//visibility:public"], + deps = ["//third_party/llvm/llvm/tools/clang:frontend"], + # alwayslink as we want to be able to call things in this library at + # debug time, even if they aren't used anywhere in the code. + alwayslink = 1, +) + +``` + +The following example comes from +`third_party/python2_4_3/BUILD`. +Some of the code uses the `dl` library (to load +another, dynamic library), so this +rule specifies the `-ldl` link option to link the +`dl` library. + +```lang-starlark + +cc_library( + name = "python2_4_3", + linkopts = [ + "-ldl", + "-lutil", + ], + deps = ["//third_party/expat"], +) + +``` + +The following example comes from `third_party/kde/BUILD`. +We keep pre-built `.so` files in the depot. +The header files live in a subdirectory named `include`. + +```lang-starlark + +cc_library( + name = "kde", + srcs = [ + "lib/libDCOP.so", + "lib/libkdesu.so", + "lib/libkhtml.so", + "lib/libkparts.so", + ...more .so files..., + ], + includes = ["include"], + deps = ["//third_party/X11"], +) + +``` + +The following example comes from `third_party/gles/BUILD`. +Third-party code often needs some `defines` and +`linkopts`. + +```lang-starlark + +cc_library( + name = "gles", + srcs = [ + "GLES/egl.h", + "GLES/gl.h", + "ddx.c", + "egl.c", + ], + defines = [ + "USE_FLOAT", + "__GL_FLOAT", + "__GL_COMMON", + ], + linkopts = ["-ldl"], # uses dlopen(), dl library + deps = [ + "es", + "//third_party/X11", + ], +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries that the library target depends upon. + +These can be `cc_library` or `objc_library` targets. + +See general comments about `deps` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + +These should be names of C++ library rules. +When you build a binary that links this rule's library, +you will also link the libraries in `deps`. + +Despite the "deps" name, not all of this library's clients +belong here. Run-time data dependencies belong in `data`. +Source files generated by other rules belong in `srcs`. + +To link in a pre-compiled third-party library, add its name to +the `srcs` instead. + +To depend on something without linking it to this library, add its +name to the `data` instead. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of C and C++ files that are processed to create the library target. +These are C/C++ source and header files, either non-generated (normal source +code) or generated. + +All `.cc`, `.c`, and `.cpp` files will +be compiled. These might be generated files: if a named file is in +the `outs` of some other rule, this `cc_library` +will automatically depend on that other rule. + +Pure assembler files (.s, .asm) are not preprocessed and are typically built using +the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built +using the C/C++ compiler. + +A `.h` file will not be compiled, but will be available for +inclusion by sources in this rule. Both `.cc` and +`.h` files can directly include headers listed in +these `srcs` or in the `hdrs` of this rule or any +rule listed in the `deps` argument. + +All `#include` d files must be mentioned in the +`hdrs` attribute of this or referenced `cc_library` +rules, or they should be listed in `srcs` if they are private +to this library. See ["Header inclusion checking"](#hdrs) for +a more detailed description. + +`.so`, `.lo`, and `.a` files are +pre-compiled files. Your library might have these as +`srcs` if it uses third-party code for which we don't +have source code. + +If the `srcs` attribute includes the label of another rule, +`cc_library` will use the output files of that rule as source files to +compile. This is useful for one-off generation of source code (for more than occasional +use, it's better to implement a Starlark rule class and use the `cc_common` +API) + +Permitted `srcs` file types: + +- C and C++ source files: `.c`, `.cc`, `.cpp`, + `.cxx`, `.c++`, `.C` +- C and C++ header files: `.h`, `.hh`, `.hpp`, + `.hxx`, `.inc`, `.inl`, `.H` +- Assembler with C preprocessor: `.S` +- Archive: `.a`, `.pic.a` +- "Always link" library: `.lo`, `.pic.lo` +- Shared library, versioned or unversioned: `.so`, + `.so.version` +- Object file: `.o`, `.pic.o` + +... and any rules that produce those files (e.g. `cc_embed_data`). +Different extensions denote different programming languages in +accordance with gcc convention. + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this library at runtime. + +See general comments about `data` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + +If a `data` is the name of a generated file, then this +`cc_library` rule automatically depends on the generating +rule. + +If a `data` is a rule name, then this +`cc_library` rule automatically depends on that rule, +and that rule's `outs` are automatically added to +this `cc_library`'s data files. + +Your C++ code can access these data files like so: + +```lang-starlark + + const std::string path = devtools_build::GetDataDependencyFilepath( + "my/test/data/file"); + +``` + +`hdrs` + +List of [labels](/concepts/labels); default is `[]` + + The list of header files published by +this library to be directly included by sources in dependent rules. + +This is the strongly preferred location for declaring header files that +describe the interface for the library. These headers will be made +available for inclusion by sources in this rule or in dependent rules. +Headers not meant to be included by a client of this library should be +listed in the `srcs` attribute instead, even if they are +included by a published header. See ["Header inclusion\ +checking"](#hdrs) for a more detailed description. + +Permitted `headers` file types: +`.h`, +`.hh`, +`.hpp`, +`.hxx`. + +`additional_compiler_inputs` + +List of [labels](/concepts/labels); default is `[]` + + Any additional files you might want to pass to the compiler command line, such as sanitizer +ignorelists, for example. Files specified here can then be used in copts with the +$(location) function. + `additional_linker_inputs` + +List of [labels](/concepts/labels); default is `[]` + + Pass these files to the C++ linker command. + +For example, compiled Windows .res files can be provided here to be embedded in +the binary target. + +`alwayslink` + +Boolean; default is `False` + + If 1, any binary that depends (directly or indirectly) on this C++ +library will link in all the object files for the files listed in +`srcs`, even if some contain no symbols referenced by the binary. +This is useful if your code isn't explicitly called by code in +the binary, e.g., if your code registers to receive some callback +provided by some service. + +If alwayslink doesn't work with VS 2017 on Windows, that is due to a +[known issue](https://github.com/bazelbuild/bazel/issues/3949), +please upgrade your VS 2017 to the latest version. + +`conlyopts` + +List of strings; default is `[]` + + Add these options to the C compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + `copts` + +List of strings; default is `[]` + + Add these options to the C/C++ compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + +Each string in this attribute is added in the given order to `COPTS` before +compiling the binary target. The flags take effect only for compiling this target, not +its dependencies, so be careful about header files included elsewhere. +All paths should be relative to the workspace, not to the current package. +This attribute should not be needed outside of `third_party`. + +If the package declares the [feature](/reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings +that consist of a single "Make" variable. + +`cxxopts` + +List of strings; default is `[]` + + Add these options to the C++ compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + `defines` + +List of strings; default is `[]` + + List of defines to add to the compile line. +Subject to ["Make" variable](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +Each string, which must consist of a single Bourne shell token, +is prepended with `-D` and added to the compile command line to this target, +as well as to every rule that depends on it. Be very careful, since this may have +far-reaching effects. When in doubt, add define values to +[`local_defines`](#cc_binary.local_defines) instead. + `hdrs_check` + +String; default is `""` + + Deprecated, no-op. + `implementation_deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries that the library target depends on. Unlike with +`deps`, the headers and include paths of these libraries (and all their +transitive deps) are only used for compilation of this library, and not libraries that +depend on it. Libraries specified with `implementation_deps` are still linked in +binary targets that depend on this library. + `include_prefix` + +String; default is `""` + + The prefix to add to the paths of the headers of this rule. + +When set, the headers in the `hdrs` attribute of this rule are accessible +at is the value of this attribute prepended to their repository-relative path. + +The prefix in the `strip_include_prefix` attribute is removed before this +prefix is added. + +This attribute is only legal under `third_party`. + + +`includes` + +List of strings; default is `[]` + + List of include dirs to be added to the compile line. +Subject to ["Make variable"](/reference/be/make-variables) substitution. +Each string is prepended with the package path and passed to the C++ toolchain for +expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system +with typical feature definitions will produce +`-isystem path_to_package/include_entry`. +This should only be used for third-party libraries that +do not conform to the Google style of writing #include statements. +Unlike [COPTS](#cc_binary.copts), these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-I" flags to [COPTS](#cc_binary.copts) instead. + +The added `include` paths will include generated files as well as +files in the source tree. + +`linkopts` + +List of strings; default is `[]` + + See [`cc_binary.linkopts`](/reference/be/c-cpp.html#cc_binary.linkopts). +The `linkopts` attribute is also applied to any target that +depends, directly or indirectly, on this library via `deps` +attributes (or via other attributes that are treated similarly: +the [`malloc`](/reference/be/c-cpp.html#cc_binary.malloc) +attribute of [`cc_binary`](/reference/be/c-cpp.html#cc_binary)). Dependency +linkopts take precedence over dependent linkopts (i.e. dependency linkopts +appear later in the command line). Linkopts specified in +[`--linkopt`](../user-manual.html#flag--linkopt) +take precedence over rule linkopts. + +Note that the `linkopts` attribute only applies +when creating `.so` files or executables, not +when creating `.a` or `.lo` files. +So if the `linkstatic=True` attribute is set, the +`linkopts` attribute has no effect on the creation of +this library, only on other targets which depend on this library. + +Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" +options are not supported and should never be specified in this attribute. + +The `.so` files produced by `cc_library` +rules are not linked against the libraries that they depend +on. If you're trying to create a shared library for use +outside of the main repository, e.g. for manual use +with `dlopen()` or `LD_PRELOAD`, +it may be better to use a `cc_binary` rule +with the `linkshared=True` attribute. +See [`cc_binary.linkshared`](/reference/be/c-cpp.html#cc_binary.linkshared). + +`linkstamp` + +[Label](/concepts/labels); default is `None` + + Simultaneously compiles and links the specified C++ source file into the final +binary. This trickery is required to introduce timestamp +information into binaries; if we compiled the source file to an +object file in the usual way, the timestamp would be incorrect. +A linkstamp compilation may not include any particular set of +compiler flags and so should not depend on any particular +header, compiler option, or other build variable. +_This option should only be needed in the_ +_`base` package._`linkstatic` + +Boolean; default is `False` + + For [`cc_binary`](/reference/be/c-cpp.html#cc_binary) and +[`cc_test`](/reference/be/c-cpp.html#cc_test): link the binary in static +mode. For `cc_library.link_static`: see below. + +By default this option is on for `cc_binary` and off for the rest. + +If enabled and this is a binary or test, this option tells the build tool to link in +`.a`'s instead of `.so`'s for user libraries whenever possible. +System libraries such as libc (but _not_ the C/C++ runtime libraries, +see below) are still linked dynamically, as are libraries for which +there is no static library. So the resulting executable will still be dynamically +linked, hence only _mostly_ static. + +There are really three different ways to link an executable: + +- STATIC with fully\_static\_link feature, in which everything is linked statically; + e.g. " `gcc -static foo.o libbar.a libbaz.a -lm`". + + + This mode is enabled by specifying `fully_static_link` in the + [`features`](/reference/be/common-definitions#features) attribute. +- STATIC, in which all user libraries are linked statically (if a static + version is available), but where system libraries (excluding C/C++ runtime libraries) + are linked dynamically, e.g. " `gcc foo.o libfoo.a libbaz.a -lm`". + + + This mode is enabled by specifying `linkstatic=True`. +- DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is + available), e.g. " `gcc foo.o libfoo.so libbaz.so -lm`". + + + This mode is enabled by specifying `linkstatic=False`. + +If the `linkstatic` attribute or `fully_static_link` in +`features` is used outside of `//third_party` +please include a comment near the rule to explain why. + +The `linkstatic` attribute has a different meaning if used on a +[`cc_library()`](/reference/be/c-cpp.html#cc_library) rule. +For a C++ library, `linkstatic=True` indicates that only +static linking is allowed, so no `.so` will be produced. linkstatic=False does +not prevent static libraries from being created. The attribute is meant to control the +creation of dynamic libraries. + +There should be very little code built with `linkstatic=False` in production. +If `linkstatic=False`, then the build tool will create symlinks to +depended-upon shared libraries in the `*.runfiles` area. + +`local_defines` + +List of strings; default is `[]` + + List of defines to add to the compile line. +Subject to ["Make" variable](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +Each string, which must consist of a single Bourne shell token, +is prepended with `-D` and added to the compile command line for this target, +but not to its dependents. + `module_interfaces` + +List of [labels](/concepts/labels); default is `[]` + + The list of files are regarded as C++20 Modules Interface. + +C++ Standard has no restriction about module interface file extension + +- Clang use cppm +- GCC can use any source file extension +- MSVC use ixx + +The use is guarded by the flag +`--experimental_cpp_modules`. + +`strip_include_prefix` + +String; default is `""` + + The prefix to strip from the paths of the headers of this rule. + +When set, the headers in the `hdrs` attribute of this rule are accessible +at their path with this prefix cut off. + +If it's a relative path, it's taken as a package-relative one. If it's an absolute one, +it's understood as a repository-relative path. + +The prefix in the `include_prefix` attribute is added after this prefix is +stripped. + +This attribute is only legal under `third_party`. + + +`textual_hdrs` + +List of [labels](/concepts/labels); default is `[]` + + The list of header files published by +this library to be textually included by sources in dependent rules. + +This is the location for declaring header files that cannot be compiled on their own; +that is, they always need to be textually included by other source files to build valid +code. + +`win_def_file` + +[Label](/concepts/labels); default is `None` + + The Windows DEF file to be passed to linker. + +This attribute should only be used when Windows is the target platform. +It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. + +## cc\_shared\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_shared_library.bzl) + +``` +cc_shared_library(name, deps, additional_linker_inputs, aspect_hints, compatible_with, deprecation, dynamic_deps, exec_compatible_with, exec_group_compatible_with, exec_properties, experimental_disable_topo_sort_do_not_use_remove_before_7_0, exports_filter, features, package_metadata, restricted_to, roots, shared_lib_name, static_deps, tags, target_compatible_with, testonly, toolchains, user_link_flags, visibility, win_def_file) +``` + +It produces a shared library. + +#### Example + +``` +cc_shared_library( + name = "foo_shared", + deps = [ + ":foo", + ], + dynamic_deps = [ + ":bar_shared", + ], + additional_linker_inputs = [ + ":foo.lds", + ], + user_link_flags = [ + "-Wl,--version-script=$(location :foo.lds)", + ], +) +cc_library( + name = "foo", + srcs = ["foo.cc"], + hdrs = ["foo.h"], + deps = [ + ":bar", + ":baz", + ], +) +cc_shared_library( + name = "bar_shared", + shared_lib_name = "bar.so", + deps = [":bar"], +) +cc_library( + name = "bar", + srcs = ["bar.cc"], + hdrs = ["bar.h"], +) +cc_library( + name = "baz", + srcs = ["baz.cc"], + hdrs = ["baz.h"], +) + +``` + +In the example `foo_shared` statically links `foo` +and `baz`, the latter being a transitive dependency. It doesn't +link `bar` because it is already provided dynamically by the +`dynamic_dep` `bar_shared`. + +`foo_shared` uses a linker script \*.lds file to control which +symbols should be exported. The `cc_shared_library` rule logic does +not control which symbols get exported, it only uses what is assumed to be +exported to give errors during analysis phase if two shared libraries export the +same targets. + +Every direct dependency of `cc_shared_library` is assumed to be +exported. Therefore, Bazel assumes during analysis that `foo` is being +exported by `foo_shared`. `baz` is not assumed to be exported +by `foo_shared`. Every target matched by the `exports_filter` +is also assumed to be exported. + +Every single `cc_library` in the example should appear at most in one +`cc_shared_library`. If we wanted to link `baz` also into +`bar_shared` we would need to add +`tags = ["LINKABLE_MORE_THAN_ONCE"]` to `baz`. + +Due to the `shared_lib_name` attribute, the file produced by +`bar_shared` will have the name `bar.so` as opposed +to the name `libbar.so` that it would have by default on Linux. + +#### Errors + +##### `Two shared libraries in dependencies export the same symbols.` + +This will happen whenever you are creating a target with two different +`cc_shared_library` dependencies that export the same target. To fix this +you need to stop the libraries from being exported in one of the +`cc_shared_library` dependencies. + +##### `Two shared libraries in dependencies link the same library statically` + +This will happen whenever you are creating a new `cc_shared_library` with two +different `cc_shared_library` dependencies that link the same target statically. +Similar to the error with exports. + +One way to fix this is to stop linking the library into one of the +`cc_shared_library` dependencies. At the same time, the one that still links it +needs to export the library so that the one not linking it keeps visibility to +the symbols. Another way is to pull out a third library that exports the target. +A third way is to tag the culprit `cc_library` with `LINKABLE_MORE_THAN_ONCE` +but this fix should be rare and you should absolutely make sure that the +`cc_library` is indeed safe to link more than once. + +##### ``'//foo:foo' is already linked statically in '//bar:bar' but not exported` `` + +This means that a library in the transitive closure of your `deps` is reachable +without going through one of the `cc_shared_library` dependencies but is already +linked into a different `cc_shared_library` in `dynamic_deps` and is not +exported. + +The solution is to export it from the `cc_shared_library` dependency or pull out +a third `cc_shared_library` that exports it. + +##### `Do not place libraries which only contain a precompiled dynamic library in deps. ` + +If you have a precompiled dynamic library, this doesn't need to and cannot be +linked statically into the current `cc_shared_library` target that you are +currently creating. Therefore, it doesn't belong in `deps` of the +`cc_shared_library`. If this precompiled dynamic library is a dependency of one +of your `cc_libraries`, then the `cc_library` needs to depend on it +directly. + +##### `Trying to export a library already exported by a different shared library` + +You will see this error if on the current rule you are claiming to export a +target that is already being exported by one of your dynamic dependencies. + +To fix this, remove the target from `deps` and just rely on it from the dynamic +dependency or make sure that the `exports_filter` doesn't catch this target. + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + Top level libraries that will unconditionally be statically linked into the shared library +after being whole-archived. + +Any transitive library dependency of these direct deps will be linked into this shared +library as long as they have not already been linked by a `cc_shared_library` +in `dynamic_deps`. + +During analysis, the rule implementation will consider any target listed in +`deps` as being exported by the shared library in order to give errors when +multiple `cc_shared_libraries` export the same targets. The rule implementation +does not take care of informing the linker about which symbols should be exported by the +shared object. The user should take care of this via linker scripts or visibility +declarations in the source code. + +The implementation will also trigger errors whenever the same library is linked statically +into more than one `cc_shared_library`. This can be avoided by adding +`"LINKABLE_MORE_THAN_ONCE"` to the `cc_library.tags` or by listing +the \`cc\_library\` as an export of one of the shared libraries so that one can be made a +`dynamic_dep` of the other. + +`additional_linker_inputs` + +List of [labels](/concepts/labels); default is `[]` + + Any additional files that you may want to pass to the linker, for example, linker scripts. +You have to separately pass any linker flags that the linker needs in order to be aware +of this file. You can do so via the `user_link_flags` attribute. + `dynamic_deps` + +List of [labels](/concepts/labels); default is `[]` + + These are other `cc_shared_library` dependencies the current target depends on. + +The `cc_shared_library` implementation will use the list of +`dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the +current target's `dynamic_deps`) to decide which `cc_libraries` in +the transitive `deps` should not be linked in because they are already provided +by a different `cc_shared_library`. + +`experimental_disable_topo_sort_do_not_use_remove_before_7_0` + +Boolean; default is `False` + +`exports_filter` + +List of strings; default is `[]` + + This attribute contains a list of targets that are claimed to be exported by the current +shared library. + +Any target `deps` is already understood to be exported by the shared library. +This attribute should be used to list any targets that are exported by the shared library +but are transitive dependencies of `deps`. + +Note that this attribute is not actually adding a dependency edge to those targets, the +dependency edge should instead be created by `deps`.The entries in this +attribute are just strings. Keep in mind that when placing a target in this attribute, +this is considered a claim that the shared library exports the symbols from that target. +The `cc_shared_library` logic doesn't actually handle telling the linker which +symbols should be exported. + +The following syntax is allowed: + +`//foo:__pkg__` to account for any target in foo/BUILD + +`//foo:__subpackages__` to account for any target in foo/BUILD or any other +package below foo/ like foo/bar/BUILD + +`roots` + +List of [labels](/concepts/labels); default is `[]` + +`shared_lib_name` + +String; default is `""` + + By default cc\_shared\_library will use a name for the shared library output file based on +the target's name and the platform. This includes an extension and sometimes a prefix. +Sometimes you may not want the default name, for example, when loading C++ shared libraries +for Python the default lib\* prefix is often not desired, in which case you can use this +attribute to choose a custom name. + `static_deps` + +List of strings; default is `[]` + +`user_link_flags` + +List of strings; default is `[]` + + Any additional flags that you may want to pass to the linker. For example, to make the +linker aware of a linker script passed via additional\_linker\_inputs you can use the +following: + +```lang-starlark + + cc_shared_library( + name = "foo_shared", + additional_linker_inputs = select({ + "//src/conditions:linux": [ + ":foo.lds", + ":additional_script.txt", + ], + "//conditions:default": []}), + user_link_flags = select({ + "//src/conditions:linux": [ + "-Wl,-rpath,kittens", + "-Wl,--version-script=$(location :foo.lds)", + "-Wl,--script=$(location :additional_script.txt)", + ], + "//conditions:default": []}), + ... + ) + +``` + +`win_def_file` + +[Label](/concepts/labels); default is `None` + + The Windows DEF file to be passed to linker. + +This attribute should only be used when Windows is the target platform. +It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. + +## cc\_static\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_static_library.bzl) + +``` +cc_static_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + + Produces a static library from a list of targets and their transitive dependencies. + +The resulting static library contains the object files of the targets listed in +`deps` as well as their transitive dependencies, with preference given to +`PIC` objects. + +#### Output groups + +##### `linkdeps` + +A text file containing the labels of those transitive dependencies of targets listed in +`deps` that did not contribute any object files to the static library, but do +provide at least one static, dynamic or interface library. The resulting static library +may require these libraries to be available at link time. + +##### `linkopts` + +A text file containing the user-provided `linkopts` of all transitive +dependencies of targets listed in `deps`. + +#### Duplicate symbols + +By default, the `cc_static_library` rule checks that the resulting static +library does not contain any duplicate symbols. If it does, the build fails with an error +message that lists the duplicate symbols and the object files containing them. + +This check can be disabled per target or per package by setting +`features = ["-symbol_check"]` or globally via +`--features=-symbol_check`. + +##### Toolchain support for `symbol_check` + +The auto-configured C++ toolchains shipped with Bazel support the +`symbol_check` feature on all platforms. Custom toolchains can add support for +it in one of two ways: + +- Implementing the `ACTION_NAMES.validate_static_library` action and + enabling it with the `symbol_check` feature. The tool set in the action is + invoked with two arguments, the static library to check for duplicate symbols and the + path of a file that must be created if the check passes. +- Having the `symbol_check` feature add archiver flags that cause the + action creating the static library to fail on duplicate symbols. + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of targets to combine into a static library, including all their transitive +dependencies. + +Dependencies that do not provide any object files are not included in the static +library, but their labels are collected in the file provided by the +`linkdeps` output group. + +## cc\_test + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_test.bzl) + +``` +cc_test(name, deps, srcs, data, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local, local_defines, malloc, module_interfaces, nocopts, package_metadata, reexport_deps, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file) +``` + +A `cc_test()` rule compiles a test. Here, a test +is a binary wrapper around some testing code. + +_By default, C++ tests are dynamically linked._ + +To statically link a unit test, specify +[`linkstatic=True`](/reference/be/c-cpp.html#cc_binary.linkstatic). +It would probably be good to comment why your test needs +`linkstatic`; this is probably not obvious. + +#### Implicit output targets + +- `name.stripped` (only built if explicitly requested): A stripped + version of the binary. `strip -g` is run on the binary to remove debug + symbols. Additional strip options can be provided on the command line using + `--stripopt=-foo`. +- `name.dwp` (only built if explicitly requested): If + [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug + information package file suitable for debugging remotely deployed binaries. Else: an + empty file. + +See the [cc\_binary()](/reference/be/c-cpp.html#cc_binary_args) arguments, except that +the `stamp` argument is set to 0 by default for tests and +that `cc_test` has extra [attributes common to all test rules (\*\_test)](/reference/be/common-definitions#common-attributes-tests). + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries to be linked in to the binary target. + +These can be `cc_library` or `objc_library` +targets. + +It is also allowed to +put linker scripts (.lds) into deps, and reference them in +[linkopts](#cc_binary.linkopts). + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of C and C++ files that are processed to create the library target. +These are C/C++ source and header files, either non-generated (normal source +code) or generated. + +All `.cc`, `.c`, and `.cpp` files will +be compiled. These might be generated files: if a named file is in +the `outs` of some other rule, this `cc_library` +will automatically depend on that other rule. + +Pure assembler files (.s, .asm) are not preprocessed and are typically built using +the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built +using the C/C++ compiler. + +A `.h` file will not be compiled, but will be available for +inclusion by sources in this rule. Both `.cc` and +`.h` files can directly include headers listed in +these `srcs` or in the `hdrs` of this rule or any +rule listed in the `deps` argument. + +All `#include` d files must be mentioned in the +`hdrs` attribute of this or referenced `cc_library` +rules, or they should be listed in `srcs` if they are private +to this library. See ["Header inclusion checking"](#hdrs) for +a more detailed description. + +`.so`, `.lo`, and `.a` files are +pre-compiled files. Your library might have these as +`srcs` if it uses third-party code for which we don't +have source code. + +If the `srcs` attribute includes the label of another rule, +`cc_library` will use the output files of that rule as source files to +compile. This is useful for one-off generation of source code (for more than occasional +use, it's better to implement a Starlark rule class and use the `cc_common` +API) + +Permitted `srcs` file types: + +- C and C++ source files: `.c`, `.cc`, `.cpp`, + `.cxx`, `.c++`, `.C` +- C and C++ header files: `.h`, `.hh`, `.hpp`, + `.hxx`, `.inc`, `.inl`, `.H` +- Assembler with C preprocessor: `.S` +- Archive: `.a`, `.pic.a` +- "Always link" library: `.lo`, `.pic.lo` +- Shared library, versioned or unversioned: `.so`, + `.so.version` +- Object file: `.o`, `.pic.o` + +... and any rules that produce those files (e.g. `cc_embed_data`). +Different extensions denote different programming languages in +accordance with gcc convention. + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this library at runtime. + +See general comments about `data` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + +If a `data` is the name of a generated file, then this +`cc_library` rule automatically depends on the generating +rule. + +If a `data` is a rule name, then this +`cc_library` rule automatically depends on that rule, +and that rule's `outs` are automatically added to +this `cc_library`'s data files. + +Your C++ code can access these data files like so: + +```lang-starlark + + const std::string path = devtools_build::GetDataDependencyFilepath( + "my/test/data/file"); + +``` + +`additional_linker_inputs` + +List of [labels](/concepts/labels); default is `[]` + + Pass these files to the C++ linker command. + +For example, compiled Windows .res files can be provided here to be embedded in +the binary target. + +`conlyopts` + +List of strings; default is `[]` + + Add these options to the C compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + `copts` + +List of strings; default is `[]` + + Add these options to the C/C++ compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + +Each string in this attribute is added in the given order to `COPTS` before +compiling the binary target. The flags take effect only for compiling this target, not +its dependencies, so be careful about header files included elsewhere. +All paths should be relative to the workspace, not to the current package. +This attribute should not be needed outside of `third_party`. + +If the package declares the [feature](/reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings +that consist of a single "Make" variable. + +`cxxopts` + +List of strings; default is `[]` + + Add these options to the C++ compilation command. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + `defines` + +List of strings; default is `[]` + + List of defines to add to the compile line. +Subject to ["Make" variable](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +Each string, which must consist of a single Bourne shell token, +is prepended with `-D` and added to the compile command line to this target, +as well as to every rule that depends on it. Be very careful, since this may have +far-reaching effects. When in doubt, add define values to +[`local_defines`](#cc_binary.local_defines) instead. + `distribs` + +List of strings; default is `[]` + +`dynamic_deps` + +List of [labels](/concepts/labels); default is `[]` + + These are other `cc_shared_library` dependencies the current target depends on. + +The `cc_shared_library` implementation will use the list of +`dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the +current target's `dynamic_deps`) to decide which `cc_libraries` in +the transitive `deps` should not be linked in because they are already provided +by a different `cc_shared_library`. + + +`hdrs_check` + +String; default is `""` + + Deprecated, no-op. + `includes` + +List of strings; default is `[]` + + List of include dirs to be added to the compile line. +Subject to ["Make variable"](/reference/be/make-variables) substitution. +Each string is prepended with the package path and passed to the C++ toolchain for +expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system +with typical feature definitions will produce +`-isystem path_to_package/include_entry`. +This should only be used for third-party libraries that +do not conform to the Google style of writing #include statements. +Unlike [COPTS](#cc_binary.copts), these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-I" flags to [COPTS](#cc_binary.copts) instead. + +The added `include` paths will include generated files as well as +files in the source tree. + +`link_extra_lib` + +[Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` + + Control linking of extra libraries. + +By default, C++ binaries are linked against `//tools/cpp:link_extra_lib`, +which by default depends on the label flag `//tools/cpp:link_extra_libs`. +Without setting the flag, this library is empty by default. Setting the label flag +allows linking optional dependencies, such as overrides for weak symbols, interceptors +for shared library functions, or special runtime libraries (for malloc replacements, +prefer `malloc` or `--custom_malloc`). Setting this attribute to +`None` disables this behaviour. + +`linkopts` + +List of strings; default is `[]` + + Add these flags to the C++ linker command. +Subject to ["Make" variable](make-variables.html) substitution, +[Bourne shell tokenization](common-definitions.html#sh-tokenization) and +[label expansion](common-definitions.html#label-expansion). +Each string in this attribute is added to `LINKOPTS` before +linking the binary target. + +Each element of this list that does not start with `$` or `-` is +assumed to be the label of a target in `deps`. The +list of files generated by that target is appended to the linker +options. An error is reported if the label is invalid, or is +not declared in `deps`. + +`linkshared` + +Boolean; default is `False` + + Create a shared library. +To enable this attribute, include `linkshared=True` in your rule. By default +this option is off. + +The presence of this flag means that linking occurs with the `-shared` flag +to `gcc`, and the resulting shared library is suitable for loading into for +example a Java program. However, for build purposes it will never be linked into the +dependent binary, as it is assumed that shared libraries built with a +[cc\_binary](#cc_binary) rule are only loaded manually by other programs, so +it should not be considered a substitute for the [cc\_library](#cc_library) +rule. For sake of scalability we recommend avoiding this approach altogether and +simply letting `java_library` depend on `cc_library` rules +instead. + +If you specify both `linkopts=['-static']` and `linkshared=True`, +you get a single completely self-contained unit. If you specify both +`linkstatic=True` and `linkshared=True`, you get a single, mostly +self-contained unit. + +`linkstatic` + +Boolean; default is `False` + + For [`cc_binary`](/reference/be/c-cpp.html#cc_binary) and +[`cc_test`](/reference/be/c-cpp.html#cc_test): link the binary in static +mode. For `cc_library.link_static`: see below. + +By default this option is on for `cc_binary` and off for the rest. + +If enabled and this is a binary or test, this option tells the build tool to link in +`.a`'s instead of `.so`'s for user libraries whenever possible. +System libraries such as libc (but _not_ the C/C++ runtime libraries, +see below) are still linked dynamically, as are libraries for which +there is no static library. So the resulting executable will still be dynamically +linked, hence only _mostly_ static. + +There are really three different ways to link an executable: + +- STATIC with fully\_static\_link feature, in which everything is linked statically; + e.g. " `gcc -static foo.o libbar.a libbaz.a -lm`". + + + This mode is enabled by specifying `fully_static_link` in the + [`features`](/reference/be/common-definitions#features) attribute. +- STATIC, in which all user libraries are linked statically (if a static + version is available), but where system libraries (excluding C/C++ runtime libraries) + are linked dynamically, e.g. " `gcc foo.o libfoo.a libbaz.a -lm`". + + + This mode is enabled by specifying `linkstatic=True`. +- DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is + available), e.g. " `gcc foo.o libfoo.so libbaz.so -lm`". + + + This mode is enabled by specifying `linkstatic=False`. + +If the `linkstatic` attribute or `fully_static_link` in +`features` is used outside of `//third_party` +please include a comment near the rule to explain why. + +The `linkstatic` attribute has a different meaning if used on a +[`cc_library()`](/reference/be/c-cpp.html#cc_library) rule. +For a C++ library, `linkstatic=True` indicates that only +static linking is allowed, so no `.so` will be produced. linkstatic=False does +not prevent static libraries from being created. The attribute is meant to control the +creation of dynamic libraries. + +There should be very little code built with `linkstatic=False` in production. +If `linkstatic=False`, then the build tool will create symlinks to +depended-upon shared libraries in the `*.runfiles` area. + +`local_defines` + +List of strings; default is `[]` + + List of defines to add to the compile line. +Subject to ["Make" variable](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +Each string, which must consist of a single Bourne shell token, +is prepended with `-D` and added to the compile command line for this target, +but not to its dependents. + `malloc` + +[Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` + + Override the default dependency on malloc. + +By default, C++ binaries are linked against `//tools/cpp:malloc`, +which is an empty library so the binary ends up using libc malloc. +This label must refer to a `cc_library`. If compilation is for a non-C++ +rule, this option has no effect. The value of this attribute is ignored if +`linkshared=True` is specified. + +`module_interfaces` + +List of [labels](/concepts/labels); default is `[]` + + The list of files are regarded as C++20 Modules Interface. + +C++ Standard has no restriction about module interface file extension + +- Clang use cppm +- GCC can use any source file extension +- MSVC use ixx + +The use is guarded by the flag +`--experimental_cpp_modules`. + +`nocopts` + +String; default is `""` + + Remove matching options from the C++ compilation command. +Subject to ["Make" variable](/reference/be/make-variables) substitution. +The value of this attribute is interpreted as a regular expression. +Any preexisting `COPTS` that match this regular expression +(including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) +will be removed from `COPTS` for purposes of compiling this rule. +This attribute should not be needed or used +outside of `third_party`. The values are not preprocessed +in any way other than the "Make" variable substitution. + `reexport_deps` + +List of [labels](/concepts/labels); default is `[]` + +`stamp` + +Integer; default is `0` + + Whether to encode build information into the binary. Possible values: + +- `stamp = 1`: Always stamp the build information into the binary, even in + [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This** + **setting should be avoided**, since it potentially kills remote caching for the + binary and any downstream actions that depend on it. + +- `stamp = 0`: Always replace build information by constant values. This + gives good build result caching. + +- `stamp = -1`: Embedding of build information is controlled by the + [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. + + +Stamped binaries are _not_ rebuilt unless their dependencies change. + +`win_def_file` + +[Label](/concepts/labels); default is `None` + + The Windows DEF file to be passed to linker. + +This attribute should only be used when Windows is the target platform. +It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. + +## cc\_toolchain + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_toolchain.bzl) + +``` +cc_toolchain(name, all_files, ar_files, as_files, aspect_hints, compatible_with, compiler_files, compiler_files_without_includes, coverage_files, deprecation, dwp_files, dynamic_runtime_lib, exec_compatible_with, exec_group_compatible_with, exec_properties, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, output_licenses, package_metadata, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, toolchains, visibility) +``` + +Represents a C++ toolchain. + +This rule is responsible for: + + + +- Collecting all artifacts needed for C++ actions to run. This is done by + attributes such as `all_files`, `compiler_files`, + `linker_files`, or other attributes ending with `_files`). These are + most commonly filegroups globbing all required files. + +- Generating correct command lines for C++ actions. This is done using + `CcToolchainConfigInfo` provider (details below). + + +Use `toolchain_config` attribute to configure the C++ toolchain. +See also this +[page](https://bazel.build/docs/cc-toolchain-config-reference) for elaborate C++ toolchain configuration and toolchain selection documentation. + +Use `tags = ["manual"]` in order to prevent toolchains from being built and configured +unnecessarily when invoking `bazel build //...` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`all_files` + +[Label](/concepts/labels); required + + Collection of all cc\_toolchain artifacts. These artifacts will be added as inputs to all +rules\_cc related actions (with the exception of actions that are using more precise sets of +artifacts from attributes below). Bazel assumes that `all_files` is a superset +of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile +and link files, so it takes `all_files`). + +This is what `cc_toolchain.files` contains, and this is used by all Starlark +rules using C++ toolchain. + +`ar_files` + +[Label](/concepts/labels); default is `None` + + Collection of all cc\_toolchain artifacts required for archiving actions. + `as_files` + +[Label](/concepts/labels); default is `None` + + Collection of all cc\_toolchain artifacts required for assembly actions. + `compiler_files` + +[Label](/concepts/labels); required + + Collection of all cc\_toolchain artifacts required for compile actions. + `compiler_files_without_includes` + +[Label](/concepts/labels); default is `None` + + Collection of all cc\_toolchain artifacts required for compile actions in case when +input discovery is supported (currently Google-only). + `coverage_files` + +[Label](/concepts/labels); default is `None` + + Collection of all cc\_toolchain artifacts required for coverage actions. If not specified, +all\_files are used. + `dwp_files` + +[Label](/concepts/labels); required + + Collection of all cc\_toolchain artifacts required for dwp actions. + `dynamic_runtime_lib` + +[Label](/concepts/labels); default is `None` + + Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). + +This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking +dependencies dynamically. + +`exec_transition_for_inputs` + +Boolean; default is `False` + + Deprecated. No-op. + `libc_top` + +[Label](/concepts/labels); default is `None` + + A collection of artifacts for libc passed as inputs to compile/linking actions. + `linker_files` + +[Label](/concepts/labels); required + + Collection of all cc\_toolchain artifacts required for linking actions. + `module_map` + +[Label](/concepts/labels); default is `None` + + Module map artifact to be used for modular builds. + `objcopy_files` + +[Label](/concepts/labels); required + + Collection of all cc\_toolchain artifacts required for objcopy actions. + `output_licenses` + +List of strings; default is `[]` + +`static_runtime_lib` + +[Label](/concepts/labels); default is `None` + + Static library artifact for the C++ runtime library (e.g. libstdc++.a). + +This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking +dependencies statically. + +`strip_files` + +[Label](/concepts/labels); required + + Collection of all cc\_toolchain artifacts required for strip actions. + `supports_header_parsing` + +Boolean; default is `False` + + Set to True when cc\_toolchain supports header parsing actions. + `supports_param_files` + +Boolean; default is `True` + + Set to True when cc\_toolchain supports using param files for linking actions. + `toolchain_config` + +[Label](/concepts/labels); required + + The label of the rule providing `cc_toolchain_config_info`. + `toolchain_identifier` + +String; default is `""` + + The identifier used to match this cc\_toolchain with the corresponding +crosstool\_config.toolchain. + +Until issue [#5380](https://github.com/bazelbuild/bazel/issues/5380) is fixed +this is the recommended way of associating `cc_toolchain` with +`CROSSTOOL.toolchain`. It will be replaced by the `toolchain_config` +attribute ( [#5380](https://github.com/bazelbuild/bazel/issues/5380)). + +## fdo\_prefetch\_hints + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_prefetch_hints.bzl) + +``` +fdo_prefetch_hints(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Represents an FDO prefetch hints profile that is either in the workspace. +Examples: + +```lang-starlark + +fdo_prefetch_hints( + name = "hints", + profile = "//path/to/hints:profile.afdo", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`profile` + +[Label](/concepts/labels); required + + Label of the hints profile. The hints file has the .afdo extension +The label can also point to an fdo\_absolute\_path\_profile rule. + + +## fdo\_profile + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_profile.bzl) + +``` +fdo_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, memprof_profile, package_metadata, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Represents an FDO profile that is in the workspace. +Example: + +```lang-starlark + +fdo_profile( + name = "fdo", + profile = "//path/to/fdo:profile.zip", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`memprof_profile` + +[Label](/concepts/labels); default is `None` + + Label of the MemProf profile. The profile is expected to have +either a .profdata extension (for an indexed/symbolized memprof +profile), or a .zip extension for a zipfile containing a memprof.profdata +file. + `profile` + +[Label](/concepts/labels); required + + Label of the FDO profile or a rule which generates it. The FDO file can have one of the +following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM +profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for +XBinary profile. The label can also point to an fdo\_absolute\_path\_profile rule. + `proto_profile` + +[Label](/concepts/labels); default is `None` + + Label of the protobuf profile. + + +## memprof\_profile + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/memprof_profile.bzl) + +``` +memprof_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Represents a MEMPROF profile that is in the workspace. +Example: + +```lang-starlark + +memprof_profile( + name = "memprof", + profile = "//path/to/memprof:profile.afdo", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`profile` + +[Label](/concepts/labels); required + + Label of the MEMPROF profile. The profile is expected to have +either a .profdata extension (for an indexed/symbolized memprof +profile), or a .zip extension for a zipfile containing a memprof.profdata +file. +The label can also point to an fdo\_absolute\_path\_profile rule. + + +## propeller\_optimize + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/propeller_optimize.bzl) + +``` +propeller_optimize(name, aspect_hints, cc_profile, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, ld_profile, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Represents a Propeller optimization profile in the workspace. +Example: + +```lang-starlark + +propeller_optimize( + name = "layout", + cc_profile = "//path:cc_profile.txt", + ld_profile = "//path:ld_profile.txt" +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`cc_profile` + +[Label](/concepts/labels); required + + Label of the profile passed to the various compile actions. This file has +the .txt extension. + `ld_profile` + +[Label](/concepts/labels); required + + Label of the profile passed to the link action. This file has +the .txt extension. diff --git a/reference/be/common-definitions.mdx b/reference/be/common-definitions.mdx new file mode 100644 index 0000000..4c9db5e --- /dev/null +++ b/reference/be/common-definitions.mdx @@ -0,0 +1,794 @@ +--- +title: 'Common definitions' +--- + + + +This section defines various terms and concepts that are common to +many functions or build rules. + +## Contents + +- [Bourne shell tokenization](#sh-tokenization) +- [Label Expansion](#label-expansion) +- [Typical attributes defined by most build rules](#typical-attributes) +- [Attributes common to all build rules](#common-attributes) +- [Attributes common to all test rules (\*\_test)](#common-attributes-tests) +- [Attributes common to all binary rules (\*\_binary)](#common-attributes-binaries) +- [Configurable attributes](#configurable-attributes) +- [Implicit output targets](#implicit-outputs) + +## Bourne shell tokenization + +Certain string attributes of some rules are split into multiple +words according to the tokenization rules of the Bourne shell: +unquoted spaces delimit separate words, and single- and +double-quotes characters and backslashes are used to prevent +tokenization. + +Those attributes that are subject to this tokenization are +explicitly indicated as such in their definitions in this document. + +Attributes subject to "Make" variable expansion and Bourne shell +tokenization are typically used for passing arbitrary options to +compilers and other tools. Examples of such attributes are +`cc_library.copts` and `java_library.javacopts`. +Together these substitutions allow a +single string variable to expand into a configuration-specific list +of option words. + +## Label expansion + +Some string attributes of a very few rules are subject to label +expansion: if those strings contain a valid label as a +substring, such as `//mypkg:target`, and that label is a +declared prerequisite of the current rule, it is expanded into the +pathname of the file represented by the +[target](https://bazel.build/reference/glossary#target) `//mypkg:target`. + +Example attributes include `genrule.cmd` and +`cc_binary.linkopts`. The details may vary significantly in +each case, over such issues as: whether relative labels are +expanded; how labels that expand to multiple files are +treated, etc. Consult the rule attribute documentation for +specifics. + +## Typical attributes defined by most build rules + +This section describes attributes that are defined by many build rules, +but not all. + +AttributeDescription`data` + +List of [labels](/concepts/labels); default is `[]` + +Files needed by this rule at runtime. May list file or rule targets. Generally +allows any target. + +The default outputs and runfiles of targets in the `data` attribute +should appear in the `*.runfiles` area of any executable which is +output by or has a runtime dependency on this target. This may include data +files or binaries used when this target's +[`srcs`](#typical.srcs) are executed. See the +[data dependencies](/concepts/dependencies#data-dependencies) +section for more information about how to depend on and use data files. + +New rules should define a `data` attribute if they process +inputs which might use other inputs at runtime. Rules' implementation functions +must also [populate the target's\ +runfiles](https://bazel.build/rules/rules#runfiles) from the outputs and runfiles of any `data` attribute, +as well as runfiles from any dependency attribute which provides either +source code or runtime dependencies. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + +Dependencies for this target. Generally should only list rule targets. (Though +some rules permit files to be listed directly in `deps`, this +should be avoided when possible.) + +Language-specific rules generally limit the listed targets to those with +specific [providers](https://bazel.build/extending/rules#providers). + +The precise semantics of what it means for a target to depend on another using +`deps` are specific to the kind of rule, and the rule-specific +documentation goes into more detail. For rules which process source code, +`deps` generally specifies code dependencies used by the code in +[`srcs`](#typical.srcs). + +Most often, a `deps` dependency is used to allow one module to use +symbols defined in another module written in the same programming language and +separately compiled. Cross-language dependencies are also permitted in many +cases: For example, a `java_library` target may depend on C++ code +in a `cc_library` target, by listing the latter in the +`deps` attribute. See the definition of +[dependencies](/concepts/build-ref#deps) +for more information. + +`licenses` + +List of strings; [nonconfigurable](#configurable-attributes); +default is `["none"]` + +A list of license-type strings to be used for this particular target. + +This is part of a deprecated licensing API that Bazel no longer uses. Don't +use this. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + +Files processed or included by this rule. Generally lists files directly, but +may list rule targets (like `filegroup` or `genrule`) to +include their default outputs. + +Language-specific rules often require that the listed files have particular +file extensions. + +## Attributes common to all build rules + +This section describes attributes that are implicitly added to all build +rules. + +AttributeDescription`aspect_hints` + +List of [labels](/concepts/labels); default is `[]` + +A list of arbitrary labels which is exposed to [aspects](/extending/aspects) (in +particular - aspects invoked by this rule's reverse dependencies), but isn't exposed to this rule's +own implementation. Consult documentation for language-specific rule sets for details about what +effect a particular aspect hint would have. + +You could think of an aspect hint as a richer alternative to a [tag](#common.tags): +while a tag conveys only a boolean state (the tag is either present or absent in the +`tags` list), an aspect hint can convey arbitrary structured information in its +[providers](/extending/rules#providers). + +In practice, aspect hints are used for interoperability between different language-specific +rule sets. For example, imagine you have a `mylang_binary` target which needs to depend +on an `otherlang_library` target. The MyLang-specific logic needs some additional +information about the OtherLang target in order to use it, but `otherlang_library` +doesn't provide this information because it knows nothing about MyLang. One solution might be for +the MyLang rule set to define a `mylang_hint` rule which can be used to encode that +additional information; the user can add the hint to their `otherlang_library`'s +`aspect_hints`, and `mylang_binary` can use an aspect to collect the +additional information from a MyLang-specific provider in the `mylang_hint`. + +For a concrete example, see +[`swift_interop_hint`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_interop_hint) +and [`swift_overlay`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_overlay) +in `rules_swift`. + +Best practices: + +- Targets listed in `aspect_hints` should be lightweight and minimal. +- Language-specific logic should consider only aspect hints having providers relevant to that + language, and should ignore any other aspect hints. + +`compatible_with` + +List of [labels](/concepts/labels); +[nonconfigurable](#configurable-attributes); default is `[]` + +The list of environments this target can be built for, in addition to +default-supported environments. + +This is part of Bazel's constraint system, which lets users declare which +targets can and cannot depend on each other. For example, externally deployable +binaries shouldn't depend on libraries with company-secret code. See +[ConstraintSemantics](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46) for details. + +`deprecation` + +String; [nonconfigurable](#configurable-attributes); default is `None` + +An explanatory warning message associated with this target. +Typically this is used to notify users that a target has become obsolete, +or has become superseded by another rule, is private to a package, or is +perhaps considered harmful for some reason. It is a good idea to include +some reference (like a webpage, a bug number or example migration CLs) so +that one can easily find out what changes are required to avoid the message. +If there is a new target that can be used as a drop in replacement, it is a +good idea to just migrate all users of the old target. + +This attribute has no effect on the way things are built, but it +may affect a build tool's diagnostic output. The build tool issues a +warning when a rule with a `deprecation` attribute is +depended upon by a target in another package. + +Intra-package dependencies are exempt from this warning, so that, +for example, building the tests of a deprecated rule does not +encounter a warning. + +If a deprecated target depends on another deprecated target, no warning +message is issued. + +Once people have stopped using it, the target can be removed. + +`exec_compatible_with` + +List of [labels](/concepts/labels); +[nonconfigurable](#configurable-attributes); default is `[]` + +A list of +`constraint_values` +that must be present in the execution platform of this target's default exec +group. This is in addition to any constraints already set by the rule type. +Constraints are used to restrict the list of available execution platforms. + +For more details, see +the description of +[toolchain resolution](/docs/toolchains#toolchain-resolution). +and +[exec groups](/extending/exec-groups) + +`exec_group_compatible_with` + +Dictionary of strings to lists of [labels](/concepts/labels); +[nonconfigurable](#configurable-attributes); default is `{}` + +A dictionary of exec group names to lists of +`constraint_values` +that must be present in the execution platform for the given exec group. This +is in addition to any constraints already set on the exec group's definition. +Constraints are used to restrict the list of available execution platforms. + +For more details, see +the description of +[toolchain resolution](/docs/toolchains#toolchain-resolution). +and +[exec groups](/extending/exec-groups) + +`exec_properties` + +Dictionary of strings; default is `{}` + +A dictionary of strings that will be added to the `exec_properties` of a platform selected for this target. See `exec_properties` of the [platform](platforms-and-toolchains.html#platform) rule. + +If a key is present in both the platform and target-level properties, the value will be taken from the target. + +Keys can be prefixed with the name of an execution group followed by a `.` to apply them only to that particular exec group. + +`features` + +List of _feature_ strings; default is `[]` + +A feature is string tag that can be enabled or disabled on a target. The +meaning of a feature depends on the rule itself. + +This `features` attribute is combined with the [package](/reference/be/functions.html#package) level `features` attribute. For example, if +the features \["a", "b"\] are enabled on the package level, and a target's +`features` attribute contains \["-a", "c"\], the features enabled for the +rule will be "b" and "c". +[See example](https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD). + +`package_metadata` + +List of [labels](/concepts/labels); +[nonconfigurable](#configurable-attributes); default is the package's +`default_package_metadata` + +A list of labels that are associated metadata about this target. +Typically, the labels are simple rules that return a provider of +constant values. Rules and aspects may use these labels to perform some +additional analysis on the build graph. + +The canonical use case is that of +[rules\_license](https://github.com/bazelbuild/rules_license). +For that use case, `package_metadata` and +`default_package_metadata` is used to attach information +about a package's licence or version to targets. An aspect applied +to a top-level binary can be used to gather those and produce +compliance reports. + +`restricted_to` + +List of [labels](/concepts/labels); +[nonconfigurable](#configurable-attributes); default is `[]` + +The list of environments this target can be built for, _instead_ of +default-supported environments. + +This is part of Bazel's constraint system. See +`compatible_with` +for details. + +`tags` + +List of strings; [nonconfigurable](#configurable-attributes); +default is `[]` + +_Tags_ can be used on any rule. _Tags_ on test and +`test_suite` rules are useful for categorizing the tests. +_Tags_ on non-test targets are used to control sandboxed execution of +`genrule` s and + +[Starlark](/rules/concepts) +actions, and for parsing by humans and/or external tools. + +Bazel modifies the behavior of its sandboxing code if it finds the following +keywords in the `tags` attribute of any test or `genrule` +target, or the keys of `execution_requirements` for any Starlark +action. + +- `no-sandbox` keyword results in the action or test never being + sandboxed; it can still be cached or run remotely - use `no-cache` + or `no-remote` to prevent either or both of those. + +- `no-cache` keyword results in the action or test never being + cached (locally or remotely). Note: for the purposes of this tag, the disk cache + is considered a local cache, whereas the HTTP and gRPC caches are considered + remote. Other caches, such as Skyframe or the persistent action cache, are not + affected. + +- `no-remote-cache` keyword results in the action or test never being + cached remotely (but it may be cached locally; it may also be executed remotely). + Note: for the purposes of this tag, the disk cache is considered a local cache, + whereas the HTTP and gRPC caches are considered remote. Other caches, such as + Skyframe or the persistent action cache, are not affected. + If a combination of local disk cache and remote cache are used (combined cache), + it's treated as a remote cache and disabled entirely unless `--incompatible_remote_results_ignore_disk` + is set in which case the local components will be used. + +- `no-remote-exec` keyword results in the action or test never being + executed remotely (but it may be cached remotely). + +- `no-remote` keyword prevents the action or test from being executed remotely or + cached remotely. This is equivalent to using both + `no-remote-cache` and `no-remote-exec`. + +- `no-remote-cache-upload` keyword disables upload part of remote caching of a spawn. + it does not disable remote execution. + +- `local` keyword precludes the action or test from being remotely cached, + remotely executed, or run inside the sandbox. + For genrules and tests, marking the rule with the `local = True` + attribute has the same effect. + +- `requires-network` keyword allows access to the external + network from inside the sandbox. This tag only has an effect if sandboxing + is enabled. + +- `block-network` keyword blocks access to the external + network from inside the sandbox. In this case, only communication + with localhost is allowed. This tag only has an effect if sandboxing is + enabled. + +- `requires-fakeroot` runs the test or action as uid and gid 0 (i.e., the root + user). This is only supported on Linux. This tag takes precedence over the + `--sandbox_fake_username` command-line option. + + +_Tags_ on tests are generally used to annotate a test's role in your +debug and release process. Typically, tags are most useful for C++ and Python +tests, which lack any runtime annotation ability. The use of tags and size +elements gives flexibility in assembling suites of tests based around codebase +check-in policy. + +Bazel modifies test running behavior if it finds the following keywords in the +`tags` attribute of the test rule: + +- `exclusive` will force the test to be run in the + "exclusive" mode, ensuring that no other tests are running at the + same time. Such tests will be executed in serial fashion after all build + activity and non-exclusive tests have been completed. Remote execution is + disabled for such tests because Bazel doesn't have control over what's + running on a remote machine. + +- `exclusive-if-local` will force the test to be run in the + "exclusive" mode if it is executed locally, but will run the test in parallel if it's + executed remotely. + +- `manual` keyword will exclude the target from expansion of target pattern wildcards + ( `...`, `:*`, `:all`, etc.) and `test_suite` rules + which do not list the test explicitly when computing the set of top-level targets to build/run + for the `build`, `test`, and `coverage` commands. It does not + affect target wildcard or test suite expansion in other contexts, including the + `query` command. Note that `manual` does not imply that a target should + not be built/run automatically by continuous build/test systems. For example, it may be + desirable to exclude a target from `bazel test ...` because it requires specific + Bazel flags, but still have it included in properly-configured presubmit or continuous test + runs. + + +- `external` keyword will force test to be unconditionally + executed (regardless of `--cache_test_results` + value). + + +See +[Tag Conventions](/reference/test-encyclopedia#tag-conventions) + in the Test Encyclopedia for more conventions on tags attached to test targets. +`target_compatible_with` + +List of [labels](/concepts/labels); default is `[]` + +A list of +`constraint_value` s +that must be present in the target platform for this target to be considered +_compatible_. This is in addition to any constraints already set by the +rule type. If the target platform does not satisfy all listed constraints then +the target is considered _incompatible_. Incompatible targets are +skipped for building and testing when the target pattern is expanded +(e.g. `//...`, `:all`). When explicitly specified on the +command line, incompatible targets cause Bazel to print an error and cause a +build or test failure. + +Targets that transitively depend on incompatible targets are themselves +considered incompatible. They are also skipped for building and testing. + +An empty list (which is the default) signifies that the target is compatible +with all platforms. + +All rules other than [Workspace Rules](workspace.html) support this +attribute. +For some rules this attribute has no effect. For example, specifying +`target_compatible_with` for a +`cc_toolchain` is not useful. + +See the +[Platforms](/docs/platforms#skipping-incompatible-targets) +page for more information about incompatible target skipping. + +`testonly` + +Boolean; [nonconfigurable](#configurable-attributes); default is `False` +except for test and test suite targets + +If `True`, only testonly targets (such as tests) can depend on this target. + +Equivalently, a rule that is not `testonly` is not allowed to +depend on any rule that is `testonly`. + +Tests ( `*_test` rules) +and test suites ( [test\_suite](/reference/be/general.html#test_suite) rules) +are `testonly` by default. + +This attribute is intended to mean that the target should not be +contained in binaries that are released to production. + +Because testonly is enforced at build time, not run time, and propagates +virally through the dependency tree, it should be applied judiciously. For +example, stubs and fakes that +are useful for unit tests may also be useful for integration tests +involving the same binaries that will be released to production, and +therefore should probably not be marked testonly. Conversely, rules that +are dangerous to even link in, perhaps because they unconditionally +override normal behavior, should definitely be marked testonly. + +`toolchains` + +List of [labels](/concepts/labels); +[nonconfigurable](#configurable-attributes); default is `[]` + +The set of targets whose [Make variables](/reference/be/make-variables) this target is +allowed to access. These targets are either instances of rules that provide +`TemplateVariableInfo` or special targets for toolchain types built into Bazel. These +include: + +- `@bazel_tools//tools/cpp:toolchain_type` +- `@rules_java//toolchains:current_java_runtime` + +Note that this is distinct from the concept of +[toolchain resolution](/docs/toolchains#toolchain-resolution) +that is used by rule implementations for platform-dependent configuration. You cannot use this +attribute to determine which specific `cc_toolchain` or `java_toolchain` a +target will use. + +`visibility` + +List of [labels](/concepts/labels); +[nonconfigurable](#configurable-attributes); +default varies + +The `visibility` attribute controls whether the target can be +depended on by targets in other locations. See the documentation for +[visibility](/concepts/visibility). + +For targets declared directly in a BUILD file or in legacy macros called from +a BUILD file, the default value is the package's +`default_visibility` +if specified, or else `["//visibility:private"]`. For targets +declared in one or more symbolic macros, the default value is always just +`["//visibility:private"]` (which makes it useable only within the +package containing the macro's code). + +## Attributes common to all test rules (\*\_test) + +This section describes attributes that are common to all test rules. + +AttributeDescription`args` + +List of strings; subject to +[$(location)](/reference/be/make-variables#predefined_label_variables) and +["Make variable"](/reference/be/make-variables) substitution, and +[Bourne shell tokenization](#sh-tokenization); default is `[]` + +Command line arguments that Bazel passes to the target when it is +executed with `bazel test`. + +These arguments are passed before any `--test_arg` values +specified on the `bazel test` command line. + +`env` + +Dictionary of strings; values are subject to +[$(location)](/reference/be/make-variables#predefined_label_variables) and +["Make variable"](/reference/be/make-variables) substitution; default is `{}` + +Specifies additional environment variables to set when the test is executed by +`bazel test`. + +This attribute only applies to native rules, like `cc_test`, +`py_test`, and `sh_test`. It does not apply to +Starlark-defined test rules. For your own Starlark rules, you can add an "env" +attribute and use it to populate a + +[RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo.html) +Provider. + +[TestEnvironment](/rules/lib/toplevel/testing#TestEnvironment) + + Provider. + +`env_inherit` + +List of strings; default is `[]` + +Specifies additional environment variables to inherit from the +external environment when the test is executed by `bazel test`. + +This attribute only applies to native rules, like `cc_test`, `py_test`, +and `sh_test`. It does not apply to Starlark-defined test rules. + +`size` + +String `"enormous"`, `"large"`, `"medium"`, or +`"small"`; [nonconfigurable](#configurable-attributes); +default is `"medium"` + +Specifies a test target's "heaviness": how much time/resources it needs to run. + +Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or +"enormous". Bazel uses the size to determine a default timeout, which can be overridden using the +`timeout` attribute. The timeout is for all tests in the BUILD target, not for each +individual test. When the test is run locally, the `size` is additionally used for +scheduling purposes: Bazel tries to respect `--local_{ram,cpu}_resources` and not +overwhelm the local machine by running lots of heavy tests at the same time. + +Test sizes correspond to the following default timeouts and assumed peak local resource +usages: + +SizeRAM (in MB)CPU (in CPU cores)Default timeoutsmall201short (1 minute)medium1001moderate (5 minutes)large3001long (15 minutes)enormous8001eternal (60 minutes) + +The environment variable +`TEST_SIZE` will be set to +the value of this attribute when spawning the test. + +`timeout` + +String `"short"`, `"moderate"`, `"long"`, or +`"eternal"`; [nonconfigurable](#configurable-attributes); default is derived +from the test's `size` attribute + +How long the test is expected to run before returning. + +While a test's size attribute controls resource estimation, a test's +timeout may be set independently. If not explicitly specified, the +timeout is based on the [test's size](#test.size). The test +timeout can be overridden with the `--test_timeout` flag, e.g. for +running under certain conditions which are known to be slow. Test timeout values +correspond to the following time periods: + +Timeout ValueTime Periodshort1 minutemoderate5 minuteslong15 minuteseternal60 minutes + +For times other than the above, the test timeout can be overridden with the +`--test_timeout` bazel flag, e.g. for manually running under +conditions which are known to be slow. The `--test_timeout` values +are in seconds. For example `--test_timeout=120` will set the test +timeout to two minutes. + +The environment variable +`TEST_TIMEOUT` will be set +to the test timeout (in seconds) when spawning the test. + +`flaky` + +Boolean; [nonconfigurable](#configurable-attributes); +default is `False` + +Marks test as flaky. + +If set, executes the test up to three times, marking it as failed only if it +fails each time. By default, this attribute is set to False and the test is +executed only once. Note, that use of this attribute is generally discouraged - +tests should pass reliably when their assertions are upheld. + +`shard_count` + +Non-negative integer less than or equal to 50; default is `-1` + +Specifies the number of parallel shards +to use to run the test. + +If set, this value will override any heuristics used to determine the number of +parallel shards with which to run the test. Note that for some test +rules, this parameter may be required to enable sharding +in the first place. Also see `--test_sharding_strategy`. + +If test sharding is enabled, the environment variable ` +TEST_TOTAL_SHARDS +` will be set to this value when spawning the test. + +Sharding requires the test runner to support the test sharding protocol. +If it does not, then it will most likely run every test in every shard, which +is not what you want. + +See +[Test Sharding](/reference/test-encyclopedia#test-sharding) +in the Test Encyclopedia for details on sharding. + +`local` + +Boolean; [nonconfigurable](#configurable-attributes); +default is `False` + +Forces the test to be run locally, without sandboxing. + +Setting this to True is equivalent to providing "local" as a tag +( `tags=["local"]`). + +## Attributes common to all binary rules (\*\_binary) + +This section describes attributes that are common to all binary rules. + +AttributeDescription`args` + +List of strings; subject to +[$(location)](/reference/be/make-variables#predefined_label_variables) and +["Make variable"](/reference/be/make-variables) substitution, and +[Bourne shell tokenization](#sh-tokenization); +[nonconfigurable](#configurable-attributes); +default is `[]` + +Command line arguments that Bazel will pass to the target when it is executed +either by the `run` command or as a test. These arguments are +passed before the ones that are specified on the `bazel run` or +`bazel test` command line. + +_NOTE: The arguments are not passed when you run the target_ +_outside of Bazel (for example, by manually executing the binary in_ +_`bazel-bin/`)._ + +`env` + +Dictionary of strings; values are subject to +[$(location)](/reference/be/make-variables#predefined_label_variables) and +["Make variable"](/reference/be/make-variables) substitution; default is `{}` + +Specifies additional environment variables to set when the target is +executed by `bazel run`. + +This attribute only applies to native rules, like `cc_binary`, `py_binary`, +and `sh_binary`. It does not apply to Starlark-defined executable rules. For your own +Starlark rules, you can add an "env" attribute and use it to populate a + +[RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo.html) + +Provider. + +_NOTE: The environment variables are not set when you run the target_ +_outside of Bazel (for example, by manually executing the binary in_ +_`bazel-bin/`)._ + +`output_licenses` + +List of strings; default is `[]` + +The licenses of the output files that this binary generates. + +This is part of a deprecated licensing API that Bazel no longer uses. Don't +use this. + +## Configurable attributes + +Most attributes are "configurable", meaning that their values may change when +the target is built in different ways. Specifically, configurable attributes +may vary based on the flags passed to the Bazel command line, or what +downstream dependency is requesting the target. This can be used, for +instance, to customize the target for multiple platforms or compilation modes. + +The following example declares different sources for different target +architectures. Running `bazel build :multiplatform_lib --cpu x86` +will build the target using `x86_impl.cc`, while substituting +`--cpu arm` will instead cause it to use `arm_impl.cc`. + +``` +cc_library( + name = "multiplatform_lib", + srcs = select({ + ":x86_mode": ["x86_impl.cc"], + ":arm_mode": ["arm_impl.cc"] + }) +) +config_setting( + name = "x86_mode", + values = { "cpu": "x86" } +) +config_setting( + name = "arm_mode", + values = { "cpu": "arm" } +) + +``` + +The [`select()`](/reference/be/functions.html#select) function +chooses among different alternative values for a configurable attribute based +on which [`config_setting`](/reference/be/general.html#config_setting) +or [`constraint_value`](/reference/be/platforms-and-toolchains.html#constraint_value) +criteria the target's configuration satisfies. + +Bazel evaluates configurable attributes after processing macros and before +processing rules (technically, between the +[loading and analysis phases](https://bazel.build/rules/concepts#evaluation-model)). +Any processing before `select()` evaluation doesn't know which +branch the `select()` chooses. Macros, for example, can't change +their behavior based on the chosen branch, and `bazel query` can +only make conservative guesses about a target's configurable dependencies. See +[this FAQ](https://bazel.build/docs/configurable-attributes#faq) +for more on using `select()` with rules and macros. + +Attributes marked `nonconfigurable` in their documentation cannot +use this feature. Usually an attribute is nonconfigurable because Bazel +internally needs to know its value before it can determine how to resolve a +`select()`. + +See [Configurable Build Attributes](https://bazel.build/docs/configurable-attributes) for a detailed overview. + +## Implicit output targets + +_Implicit outputs in C++ are deprecated. Please refrain from using it_ +_in other languages where possible. We don't have a deprecation path yet_ +_but they will eventually be deprecated too._ + +When you define a build rule in a BUILD file, you are explicitly +declaring a new, named rule target in a package. Many build rule +functions also _implicitly_ entail one or more output file +targets, whose contents and meaning are rule-specific. + +For example, when you explicitly declare a +`java_binary(name='foo', ...)` rule, you are also +_implicitly_ declaring an output file +target `foo_deploy.jar` as a member of the same package. +(This particular target is a self-contained Java archive suitable +for deployment.) + +Implicit output targets are first-class members of the global +target graph. Just like other targets, they are built on demand, +either when specified in the top-level built command, or when they +are necessary prerequisites for other build targets. They can be +referenced as dependencies in BUILD files, and can be observed in +the output of analysis tools such as `bazel query`. + +For each kind of build rule, the rule's documentation contains a +special section detailing the names and contents of any implicit +outputs entailed by a declaration of that kind of rule. + +An important but somewhat subtle distinction between the +two namespaces used by the build system: +[labels](/concepts/labels) identify _targets_, +which may be rules or files, and file targets may be divided into +either source (or input) file targets and derived (or output) file +targets. These are the things you can mention in BUILD files, +build from the command-line, or examine using `bazel query`; +this is the _target namespace_. Each file target corresponds +to one actual file on disk (the "file system namespace"); each rule +target may correspond to zero, one or more actual files on disk. +There may be files on disk that have no corresponding target; for +example, `.o` object files produced during C++ compilation +cannot be referenced from within BUILD files or from the command line. +In this way, the build tool may hide certain implementation details of +how it does its job. This is explained more fully in +the [BUILD Concept Reference](/concepts/build-ref). diff --git a/reference/be/extra-actions.mdx b/reference/be/extra-actions.mdx new file mode 100644 index 0000000..0c16bd9 --- /dev/null +++ b/reference/be/extra-actions.mdx @@ -0,0 +1,210 @@ +--- +title: 'Extra Actions Rules' +--- + + + +## Rules + +- [action\_listener](#action_listener) +- [extra\_action](#extra_action) + +## action\_listener + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java) + +``` +action_listener(name, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, extra_actions, features, licenses, mnemonics, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) +``` + +**WARNING:** Extra actions are deprecated. Use +[aspects](https://bazel.build/rules/aspects) +instead. + +An `action_listener` rule doesn't produce any output itself. +Instead, it allows tool developers to insert +[`extra_action`](/reference/be/extra-actions.html#extra_action) s into the build system, +by providing a mapping from action to [`extra_action`](/reference/be/extra-actions.html#extra_action). + +This rule's arguments map action mnemonics to +[`extra_action`](/reference/be/extra-actions.html#extra_action) rules. + +By specifying the option [`--experimental_action_listener=<label>`](/docs/user-manual#flag--experimental_action_listener), +the build will use the specified `action_listener` to insert +[`extra_action`](/reference/be/extra-actions.html#extra_action) s into the build graph. + +#### Example + +``` +action_listener( + name = "index_all_languages", + mnemonics = [ + "Javac", + "CppCompile", + "Python", + ], + extra_actions = [":indexer"], +) + +action_listener( + name = "index_java", + mnemonics = ["Javac"], + extra_actions = [":indexer"], +) + +extra_action( + name = "indexer", + tools = ["//my/tools:indexer"], + cmd = "$(location //my/tools:indexer)" + + "--extra_action_file=$(EXTRA_ACTION_FILE)", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`extra_actions` + +List of [labels](/concepts/labels); required + + A list of `extra_action` targets + this `action_listener` should add to the build graph. + E.g. `[ "//my/tools:analyzer" ]`. + + `mnemonics` + +List of strings; required + + A list of action mnemonics this `action_listener` should listen + for, e.g. `[ "Javac" ]`. + + +Mnemonics are not a public interface. +There's no guarantee that the mnemonics and their actions don't change. + + +## extra\_action + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ExtraActionRule.java) + +``` +extra_action(name, data, aspect_hints, cmd, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, out_templates, package_metadata, requires_action_output, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility) +``` + +**WARNING:** Extra actions are deprecated. Use +[aspects](https://bazel.build/rules/aspects) +instead. + +An `extra_action` rule doesn't produce any meaningful output +when specified as a regular build target. Instead, it allows tool developers +to insert additional actions into the build graph that shadow existing actions. + +See [`action_listener`](/reference/be/extra-actions.html#action_listener) for details +on how to enable `extra_action` s. + +The `extra_action` s run as a command-line. The command-line tool gets +access to a file containing a protocol buffer as $(EXTRA\_ACTION\_FILE) +with detailed information on the original action it is shadowing. +It also has access to all the input files the original action has access to. +See `extra_actions_base.proto` +for details on the data stored inside the protocol buffer. Each proto file +contains an ExtraActionInfo message. + +Just like all other actions, extra actions are sandboxed, and should be designed to handle that. + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + + You may refer to this rule by `label` in the `extra_actions` argument + of [` action_listener`](/reference/be/extra-actions.html#action_listener) rules. + + `cmd` + +String; required + + The command to run. + + +Like [genrule cmd attribute](/reference/be/general.html#genrule.cmd) with the following +differences: + + +1. No heuristic label expansion. Only labels using $(location ...) are expanded. + + +2. An additional pass is applied to the string to replace all + occurrences of the outputs created from the `out_templates` + attribute. All occurrences of `$(output out_template)` + are replaced with the path to the file denoted by `label`. + + + + E.g. out\_template `$(ACTION_ID).analysis` + can be matched with `$(output $(ACTION_ID).analysis)`. + + + + In effect, this is the same substitution as `$(location)` + but with a different scope. + + + +`out_templates` + +List of strings; default is `[]` + + A list of templates for files generated by the `extra_action` command. + + +The template can use the following variables: + + +- $(ACTION\_ID), an id uniquely identifying this `extra_action`. + Used to generate a unique output file. + + +`requires_action_output` + +Boolean; default is `False` + + Indicates this `extra_action` requires the output of the + original action to be present as input to this `extra_action`. + + +When true (default false), the extra\_action can assume that the +original action outputs are available as part of its inputs. + + +`tools` + +List of [labels](/concepts/labels); default is `[]` + + A list of `tool` dependencies for this rule. + + +See the definition of [dependencies](/concepts/build-ref#deps) for more +information. + + +The build system ensures these prerequisites are built before running the +`extra_action` command; they are built using the +[`exec` configuration](/docs/user-manual#configurations), +since they must run as a tool during the build itself. The path of an individual +`tools` target `//x:y` can be obtained using +`$(location //x:y)`. + + +All tools and their data dependencies are consolidated into a single tree +within which the command can use relative paths. The working directory will +be the root of that unified tree. diff --git a/reference/be/functions.mdx b/reference/be/functions.mdx new file mode 100644 index 0000000..4f18f06 --- /dev/null +++ b/reference/be/functions.mdx @@ -0,0 +1,708 @@ +--- +title: 'Functions' +--- + + + +## Contents + +- [package](#package) +- [package\_group](#package_group) +- [exports\_files](#exports_files) +- [glob](#glob) +- [select](#select) +- [subpackages](#subpackages) + +## package + +``` +package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features) + +``` + +This function declares metadata that applies to every rule in the +package. It is used at most once within a package (BUILD file). + +For the counterpart that declares metadata applying to every rule in the whole +_repository_, use the `repo()` function in the +[`REPO.bazel` file](/external/overview#repo.bazel) at the root of your repo. +The `repo()` function takes exactly the same arguments as `package()`. + +The package() function should be called right after all the load() statements at the top of the +file, before any rule. + +### Arguments + +AttributeDescription`default_applicable_licenses` + +Alias for [`default_package_metadata`](#package.default_package_metadata). + + +`default_visibility` + +List of [labels](/concepts/labels); default is `[]` + +The default visibility of the top-level rule targets and symbolic +macros in this package — that is, the targets and symbolic macros +that are not themselves declared inside a symbolic macro. This attribute +is ignored if the target or macro specifies a `visibility` +value. + +For detailed information about the syntax of this attribute, see the +documentation of [visibility](/concepts/visibility). The package default visibility does not apply to +[exports\_files](#exports_files), which is public by default. + + +`default_deprecation` + +String; default is `""` + +Sets the default [`deprecation`](common-definitions.html#common.deprecation) message for all rules in this package. + +`default_package_metadata` + +List of [labels](/concepts/labels); default is `[]` + +Sets a default list of metadata targets which apply to all other targets in the package. +These are typically targets related to OSS package and license declarations. +See [rules\_license](https://github.com/bazelbuild/rules_license) for examples. + +`default_testonly` + +Boolean; default is `False` except as noted + +Sets the default [`testonly`](common-definitions.html#common.testonly) property for all rules in this package. + +In packages under `javatests` the default value is `True`. + +`features` + +List strings; default is `[]` + +Sets various flags that affect the semantics of this BUILD file. + +This feature is mainly used by the people working on the build system to +tag packages that need some kind of special handling. Do not use this unless +explicitly requested by someone working on the build system. + +### Examples + +The declaration below declares that the rules in this package are +visible only to members of package +group `//foo:target`. Individual visibility declarations +on a rule, if present, override this specification. + +``` +package(default_visibility = ["//foo:target"]) + +``` + +## package\_group + +``` +package_group(name, packages, includes) +``` + +This function defines a set of [packages](/concepts/build-ref#packages) +and associates a label with the set. The label can be referenced in +`visibility` attributes. + +Package groups are primarily used for visibility control. A publicly visible +target can be referenced from every package in the source tree. A privately +visible target can only be referenced within its own package (not subpackages). +In between these extremes, a target may allow access to its own package plus any +of the packages described by one or more package groups. For a more detailed +explanation of the visibility system, see the +[visibility](common-definitions.html#common.visibility) +attribute. + +A given package is considered to be in the group if it either matches the +`packages` attribute, or is already contained in one of the other +package groups mentioned in the `includes` attribute. + +Package groups are technically targets, but are not created by rules, and do +not themselves have any visibility protection. + +### Arguments + +AttributeDescription`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`packages` + +List of strings; default is `[]` + +A list of zero or more package specifications. + +Each package specification string can have one of the following +forms: + +1. The full name of a package, without its repository, starting with a + double slash. For example, `//foo/bar` specifies the package + having that name and which lives in the same repository as the package + group. + + +2. As above, but with a trailing `/...`. For example, ` + //foo/...` specifies the set of `//foo` and all its + subpackages. `//...` specifies all packages in the current + repository. + + +3. The strings `public` or `private`, which + respectively specify every package or no package. (This form requires + the flag `--incompatible_package_group_has_public_syntax` to + be set.) + + + +In addition, the first two kinds of package specifications may also +be prefixed with `-` to indicate that they are negated. + +The package group contains any package that matches at least one of +its positive specifications and none of its negative specifications +For instance, the value `[//foo/..., -//foo/tests/...]` +includes all subpackages of `//foo` that are not also +subpackages of `//foo/tests`. ( `//foo` itself is +included while //foo/tests itself is not.) + +Aside from public visibility, there is no way to directly specify +packages outside the current repository. + +If this attribute is missing, it is the same as setting it to an +empty list, which is also the same as setting it to a list containing +only `private`. + + + +_Note:_ Prior to Bazel 6.0, the specification `//...` +had a legacy behavior of being the same as `public`. This +behavior is fixed when +`--incompatible_fix_package_group_reporoot_syntax` is +enabled, which is the default after Bazel 6.0. + +_Note:_ Prior to Bazel 6.0, when this attribute is serialized as +part of `bazel query --output=proto` (or +`--output=xml`), the leading slashes are omitted. For +instance, `//pkg/foo/...` will output as +`\"pkg/foo/...\"`. This behavior is fixed when +`--incompatible_package_group_includes_double_slash` is +enabled, which is the default after Bazel 6.0. + +`includes` + +List of [labels](/concepts/labels); default is `[]` + +Other package groups that are included in this one. + +The labels in this attribute must refer to other package groups. +Packages in referenced package groups are taken to be part of this +package group. This is transitive — if package group +`a` includes package group `b`, and `b` +includes package group `c`, then every package in +`c` will also be a member of `a`. + +When used together with negated package specifications, note that the +set of packages for each group is first computed independently and the +results are then unioned together. This means that negated +specifications in one group have no effect on the specifications in +another group. + +### Examples + +The following `package_group` declaration specifies a +package group called "tropical" that contains tropical fruits. + +``` +package_group( + name = "tropical", + packages = [ + "//fruits/mango", + "//fruits/orange", + "//fruits/papaya/...", + ], +) + +``` + +The following declarations specify the package groups of a fictional +application: + +``` +package_group( + name = "fooapp", + includes = [ + ":controller", + ":model", + ":view", + ], +) + +package_group( + name = "model", + packages = ["//fooapp/database"], +) + +package_group( + name = "view", + packages = [ + "//fooapp/swingui", + "//fooapp/webui", + ], +) + +package_group( + name = "controller", + packages = ["//fooapp/algorithm"], +) + +``` + +## exports\_files + +``` +exports_files([label, ...], visibility, licenses) +``` + +`exports_files()` specifies a list of files belonging to +this package that are exported to other packages. + +The BUILD file for a package may only refer directly to source files belonging +to another package if they are explicitly exported with an +`exports_files()` statement. Read more about +[visibility of files](/concepts/visibility#source-file-target-visibility). + +As a legacy behaviour, also files mentioned as input to a rule are exported +with the default visibility until the flag +[`--incompatible_no_implicit_file_export`](https://github.com/bazelbuild/bazel/issues/10225) +is flipped. However, this behavior should not be relied upon and actively +migrated away from. + +### Arguments + +The argument is a list of names of files within the current package. A +visibility declaration can also be specified; in this case, the files will be +visible to the targets specified. If no visibility is specified, the files +will be visible to every package, even if a package default visibility was +specified in the `package` +function. The [licenses](common-definitions.html#common.licenses) +can also be specified. + +### Example + +The following example exports `golden.txt`, a +text file from the `test_data` package, so that other +packages may use it, for example, in the `data` attribute +of tests. + +``` +# from //test_data/BUILD + +exports_files(["golden.txt"]) + +``` + +## glob + +``` +glob(include, exclude=[], exclude_directories=1, allow_empty=True) +``` + +Glob is a helper function that finds all files that match certain path patterns, +and returns a new, mutable, sorted list of their paths. Glob only searches files +in its own package, and looks only for source files (not generated files nor +other targets). + +A source file's Label is included in the result if the file's package-relative +path matches any of the `include` patterns and none of the +`exclude` patterns. + +The `include` and `exclude` lists contain path patterns +that are relative to the current package. Every pattern may consist of one or +more path segments. As usual with Unix paths, these segments are separated by +`/`. The segments in the pattern are matched against the segments of +the path. Segments may contain the `*` wildcard: this matches +any substring in the path segment (even the empty substring), excluding the +directory separator `/`. This wildcard can be used multiple times +within one path segment. Additionally, the `**` wildcard can match +zero or more complete path segments, but it must be declared as a standalone +path segment. + +Examples: + +- `foo/bar.txt` matches exactly the `foo/bar.txt` file + in this package (unless `foo/` is a subpackage) +- `foo/*.txt` matches every file in the `foo/` directory + if the file ends with `.txt` (unless `foo/` is a + subpackage) +- `foo/a*.htm*` matches every file in the `foo/` + directory that starts with `a`, then has an arbitrary string (could + be empty), then has `.htm`, and ends with another arbitrary string + (unless `foo/` is a subpackage); such as `foo/axx.htm` + and `foo/a.html` or `foo/axxx.html` +- `foo/*` matches every file in the `foo/` directory, + (unless `foo/` is a subpackage); it does not match `foo` + directory itself even if `exclude_directories` is set to + 0 +- `foo/**` matches every file in every non-subpackage subdirectory + under package's first level subdirectory `foo/`; if + `exclude_directories` is set to 0, `foo` + directory itself also matches the pattern; in this case, `**` is + considered to match zero path segments +- `**/a.txt` matches `a.txt` files in this package's + directory plus non-subpackage subdirectories. +- `**/bar/**/*.txt` matches every `.txt` file in every + non-subpackage subdirectory of this package, if at least one directory on the + resulting path is called `bar`, such as + `xxx/bar/yyy/zzz/a.txt` or `bar/a.txt` (remember that + `**` also matches zero segments) or `bar/zzz/a.txt` +- `**` matches every file in every non-subpackage subdirectory of + this package +- `foo**/a.txt` is an invalid pattern, because `**` must + stand on its own as a segment +- `foo/` is an invalid pattern, because the second segment defined + after `/` is an empty string + +If the `exclude_directories` argument is enabled (set to 1), files of +type directory will be omitted from the results (default 1). + +If the `allow_empty` argument is set to `False`, the +`glob` function will error-out if the result would otherwise be the +empty list. + +There are several important limitations and caveats: + +1. Since `glob()` runs during BUILD file evaluation, + `glob()` matches files only in your source tree, never + generated files. If you are building a target that requires both + source and generated files, you must append an explicit list of generated + files to the glob. See the [example](#glob_example) + below with `:mylib` and `:gen_java_srcs`. + + +2. If a rule has the same name as a matched source file, the rule will + "shadow" the file. + + + + To understand this, remember that `glob()` returns a list of + paths, so using `glob()` in other rules' attribute (e.g. + `srcs = glob(["*.cc"])`) has the same effect as listing the + matched paths explicitly. If for example `glob()` yields + `["Foo.java", "bar/Baz.java"]` but there's also a rule in the + package called "Foo.java" (which is allowed, though Bazel warns about it), + then the consumer of the `glob()` will use the "Foo.java" rule + (its outputs) instead of the "Foo.java" file. See + [GitHub\ + issue #10395](https://github.com/bazelbuild/bazel/issues/10395#issuecomment-583714657) for more details. + + +3. Globs may match files in subdirectories. And subdirectory names + may be wildcarded. However... + +4. Labels are not allowed to cross the package boundary and glob does + not match files in subpackages. + + + + For example, the glob expression `**/*.cc` in package + `x` does not include `x/y/z.cc` if + `x/y` exists as a package (either as + `x/y/BUILD`, or somewhere else on the package-path). This + means that the result of the glob expression actually depends on the + existence of BUILD files — that is, the same glob expression would + include `x/y/z.cc` if there was no package called + `x/y` or it was marked as deleted using the + [--deleted\_packages](/docs/user-manual#flag--deleted_packages) + flag. + + +5. The restriction above applies to all glob expressions, + no matter which wildcards they use. + +6. A hidden file with filename starting with `.` is completely matched by + both the `**` and the `*` wildcards. If you want to match a hidden file + with a compound pattern, your pattern needs to begin with a `.`. For example, + `*` and `.*.txt` will match `.foo.txt`, but `*.txt` + will not. + + Hidden directories are also matched in the same manner. Hidden directories + may include files that are not required as inputs, and can increase the + number of unnecessarily globbed files and memory consumption. To exclude + hidden directories, add them to the "exclude" list argument. + +7. The "\*\*" wildcard has one corner case: the pattern + `"**"` doesn't match the package's directory path. That is to + say, `glob(["**"], exclude_directories = False)` matches all files + and directories transitively strictly under the current package's directory + (but of course not going into directories of subpackages - see the previous + note about that). + + +In general, you should **try to provide an appropriate extension (e.g. \*.html)** +**instead of using a bare '\*'** for a glob pattern. The more explicit name +is both self documenting and ensures that you don't accidentally match backup +files, or emacs/vi/... auto-save files. + +When writing build rules you can enumerate the elements of the glob. This +enables generating individual rules for every input, for example. See the +[expanded glob example](#expanded_glob_example) section below. + +### Glob Examples + +Create a Java library built from all java files in this directory, +and all files generated by the `:gen_java_srcs` rule. + +``` +java_library( + name = "mylib", + srcs = glob(["*.java"]) + [":gen_java_srcs"], + deps = "...", +) + +genrule( + name = "gen_java_srcs", + outs = [ + "Foo.java", + "Bar.java", + ], + ... +) + +``` + +Include all txt files in directory testdata except experimental.txt. +Note that files in subdirectories of testdata will not be included. If +you want those files to be included, use a recursive glob (\*\*). + +``` +sh_test( + name = "mytest", + srcs = ["mytest.sh"], + data = glob( + ["testdata/*.txt"], + exclude = ["testdata/experimental.txt"], + ), +) + +``` + +### Recursive Glob Examples + +Make the test depend on all txt files in the testdata directory and any +of its subdirectories (and their subdirectories, and so on). +Subdirectories containing a BUILD file are ignored. (See limitations +and caveats above.) + +``` +sh_test( + name = "mytest", + srcs = ["mytest.sh"], + data = glob(["testdata/**/*.txt"]), +) + +``` + +Create a library built from all java files in this directory and all +subdirectories except those whose path includes a directory named testing. +**This pattern should be avoided if possible, as it can reduce build** +**incrementality and therefore increase build times.** + +``` +java_library( + name = "mylib", + srcs = glob( + ["**/*.java"], + exclude = ["**/testing/**"], + ), +) + +``` + +### Expanded Glob Examples + +Create an individual genrule for \*\_test.cc in the current directory +that counts the number of lines in the file. + +``` +# Conveniently, the build language supports list comprehensions. +[genrule( + name = "count_lines_" + f[:-3], # strip ".cc" + srcs = [f], + outs = ["%s-linecount.txt" % f[:-3]], + cmd = "wc -l $< >$@", + ) for f in glob(["*_test.cc"])] + +``` + +If the BUILD file above is in package //foo and the package contains three +matching files, a\_test.cc, b\_test.cc and c\_test.cc then running +`bazel query '//foo:all'` will list all rules that were generated: + +``` +$ bazel query '//foo:all' | sort +//foo:count_lines_a_test +//foo:count_lines_b_test +//foo:count_lines_c_test + +``` + +## select + +``` +select( + {conditionA: valuesA, conditionB: valuesB, ...}, + no_match_error = "custom message" +) + +``` + +`select()` is the helper function that makes a rule attribute +[configurable](common-definitions.html#configurable-attributes). +It can replace the right-hand side of + +_almost_ +any attribute assignment so its value depends on command-line Bazel flags. +You can use this, for example, to define platform-specific dependencies or to +embed different resources depending on whether a rule is built in "developer" +vs. "release" mode. + +Basic use is as follows: + +``` +sh_binary( + name = "mytarget", + srcs = select({ + ":conditionA": ["mytarget_a.sh"], + ":conditionB": ["mytarget_b.sh"], + "//conditions:default": ["mytarget_default.sh"] + }) +) + +``` + +This makes the `srcs` attribute of +a `sh_binary` configurable by replacing its normal label +list assignment with a `select` call that maps +configuration conditions to matching values. Each condition is a label +reference to +a `config_setting` or +`constraint_value`, +which "matches" if the target's configuration matches an expected set of +values. The value of `mytarget#srcs` then becomes whichever +label list matches the current invocation. + +Notes: + +- Exactly one condition is selected on any invocation. + +- 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 and constraint + values as A plus some additional flags or constraint values. This also + means that specialization resolution is not designed to create an ordering as + demonstrated in Example 2 below. + +- If multiple conditions match and one is not a specialization of all the + others, Bazel fails with an error, unless all conditions resolve to the same value. + +- The special pseudo-label `//conditions:default` is + considered to match if no other condition matches. If this condition + is left out, some other rule must match to avoid an error. + +- `select` can be embedded _inside_ a larger + attribute assignment. So `srcs = ["common.sh"] + + select({ ":conditionA": ["myrule_a.sh"], ...})` and ` + srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": + ["b.sh"]})` are valid expressions. + +- `select` works with most, but not all, attributes. Incompatible + attributes are marked `nonconfigurable` in their documentation. + + + + ## subpackages + + + + ``` + subpackages(include, exclude=[], allow_empty=True) + ``` + + + `subpackages()` is a helper function, similar to `glob()` + that lists subpackages instead of files and directories. It uses the same + path patterns as `glob()` and can match any subpackage that is a + direct descendant of the currently loading BUILD file. See [glob](#glob) for a detailed explanation and examples of include and + exclude patterns. + + + + The resulting list of subpackages returned is in sorted order and contains + paths relative to the current loading package that match the given patterns in + `include` and not those in `exclude`. + + + + + ### Example + + + + The following example lists all the direct subpackages for the package `foo/BUILD` + + + ``` + # The following BUILD files exist: + # foo/BUILD + # foo/bar/baz/BUILD + # foo/bar/but/bad/BUILD + # foo/sub/BUILD + # foo/sub/deeper/BUILD + # + # In foo/BUILD a call to + subs1 = subpackages(include = ["**"]) + + # results in subs1 == ["sub", "bar/baz", "bar/but/bad"] + # + # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of + # 'foo' + + subs2 = subpackages(include = ["bar/*"]) + # results in subs2 = ["bar/baz"] + # + # Since 'bar' is not a subpackage itself, this looks for any subpackages under + # all first level subdirectories of 'bar'. + + subs3 = subpackages(include = ["bar/**"]) + # results in subs3 = ["bar/baz", "bar/but/bad"] + # + # Since bar is not a subpackage itself, this looks for any subpackages which are + # (1) under all subdirectories of 'bar' which can be at any level, (2) not a + # subpackage of another subpackages. + + subs4 = subpackages(include = ["sub"]) + subs5 = subpackages(include = ["sub/*"]) + subs6 = subpackages(include = ["sub/**"]) + # results in subs4 and subs6 being ["sub"] + # results in subs5 = []. + # + # In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a + # subpackage of 'foo'). + # In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since + # 'foo/sub' is already a subpackage itself, the subdirectories will not be + # traversed anymore. + # In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it + # is returned. But the subdirectories of 'foo/sub' will not be traversed + # anymore. + + ``` + + + + In general it is preferred that instead of calling this function directly + that users use the 'subpackages' module of + [skylib](https://github.com/bazelbuild/bazel-skylib). diff --git a/reference/be/general.mdx b/reference/be/general.mdx new file mode 100644 index 0000000..d96013c --- /dev/null +++ b/reference/be/general.mdx @@ -0,0 +1,1200 @@ +--- +title: 'General Rules' +--- + + + +## Rules + +- [alias](#alias) +- [config\_setting](#config_setting) +- [filegroup](#filegroup) +- [genquery](#genquery) +- [genrule](#genrule) +- [starlark\_doc\_extract](#starlark_doc_extract) +- [test\_suite](#test_suite) + +## alias + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/Alias.java) + +``` +alias(name, actual, aspect_hints, compatible_with, deprecation, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) +``` + +The `alias` rule creates another name a rule can be referred to as. + +Aliasing only works for "regular" targets. In particular, `package_group` +and `test_suite` cannot be aliased. + +Aliasing may be of help in large repositories where renaming a target would require making +changes to lots of files. You can also use alias rule to store a +[select](/reference/be/functions.html#select) function call if you want to reuse that logic for +multiple targets. + +The alias rule has its own visibility declaration. In all other respects, it behaves +like the rule it references (e.g. testonly _on the alias_ is ignored; the testonly-ness +of the referenced rule is used instead) with some minor exceptions: + + + +- Tests are not run if their alias is mentioned on the command line. To define an alias + that runs the referenced test, use a [`test_suite`](#test_suite) + rule with a single target in its [`tests`](#test_suite.tests) + attribute. + +- When defining environment groups, the aliases to `environment` rules are not + supported. They are not supported in the `--target_environment` command line + option, either. + + +#### Examples + +``` +filegroup( + name = "data", + srcs = ["data.txt"], +) + +alias( + name = "other", + actual = ":data", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`actual` + +[Label](/concepts/labels); required + + The target this alias refers to. It does not need to be a rule, it can also be an input + file. + + + +## config\_setting + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java) + +``` +config_setting(name, aspect_hints, constraint_values, define_values, deprecation, features, flag_values, licenses, package_metadata, tags, testonly, values, visibility) +``` + +Matches an expected configuration state (expressed as build flags or platform constraints) for +the purpose of triggering configurable attributes. See [select](/reference/be/functions.html#select) for +how to consume this rule and [Configurable attributes](/reference/be/common-definitions#configurable-attributes) for an overview of the general feature. + + + +#### Examples + +The following matches any build that sets `--compilation_mode=opt` or +`-c opt` (either explicitly at the command line or implicitly from .bazelrc files): + + +``` + config_setting( + name = "simple", + values = {"compilation_mode": "opt"} + ) + +``` + +The following matches any build that targets ARM and applies the custom define +`FOO=bar` (for instance, `bazel build --cpu=arm --define FOO=bar ...`): + + +``` + config_setting( + name = "two_conditions", + values = { + "cpu": "arm", + "define": "FOO=bar" + } + ) + +``` + +The following matches any build that sets +[user-defined flag](https://bazel.build/rules/config#user-defined-build-settings) `--//custom_flags:foo=1` (either explicitly at the command line or implicitly from +.bazelrc files): + + +``` + config_setting( + name = "my_custom_flag_is_set", + flag_values = { "//custom_flags:foo": "1" }, + ) + +``` + +The following matches any build that targets a platform with an x86\_64 architecture and glibc +version 2.25, assuming the existence of a `constraint_value` with label +`//example:glibc_2_25`. Note that a platform still matches if it defines additional +constraint values beyond these two. + + +``` + config_setting( + name = "64bit_glibc_2_25", + constraint_values = [ + "@platforms//cpu:x86_64", + "//example:glibc_2_25", + ] + ) + +``` + + In all these cases, it's possible for the configuration to change within the build, for example if + a target needs to be built for a different platform than its dep. This means that even when a + `config_setting` doesn't match the top-level command-line flags, it may still match + some build targets. + + + +#### Notes + +- See [select](/reference/be/functions.html#select) for what happens when multiple + `config_setting` s match the current configuration state. + +- For flags that support shorthand forms (e.g. `--compilation_mode` vs. + `-c`), `values` definitions must use the full form. These automatically + match invocations using either form. + +- If a flag takes multiple values (like `--copt=-Da --copt=-Db` or a list-typed + [Starlark flag](https://bazel.build/rules/config#user-defined-build-settings)), `values = { "flag": "a" }` matches if `"a"` is + present _anywhere_ in the actual list. + + + `values = { "myflag": "a,b" }` works the same way: this matches + `--myflag=a --myflag=b`, `--myflag=a --myflag=b --myflag=c`, + `--myflag=a,b`, and `--myflag=c,b,a`. Exact semantics vary between + flags. For example, `--copt` doesn't support multiple values _in the same_ + _instance_: `--copt=a,b` produces `["a,b"]` while `--copt=a + --copt=b` produces `["a", "b"]` (so `values = { "copt": "a,b" }` + matches the former but not the latter). But `--ios_multi_cpus` (for Apple rules) + _does_: `-ios_multi_cpus=a,b` and `ios_multi_cpus=a --ios_multi_cpus=b + ` both produce `["a", "b"]`. Check flag definitions and test your + conditions carefully to verify exact expectations. + + +- If you need to define conditions that aren't modeled by built-in build flags, use + [Starlark-defined flags](https://bazel.build/rules/config#user-defined-build-settings). You can also use `--define`, but this offers weaker + support and is not recommended. See + [here](/reference/be/common-definitions#configurable-attributes) for more discussion. + +- Avoid repeating identical `config_setting` definitions in different packages. + Instead, reference a common `config_setting` that defined in a canonical package. + +- [`values`](general.html#config_setting.values), + [`define_values`](general.html#config_setting.define_values), and + [`constraint_values`](general.html#config_setting.constraint_values) + can be used in any combination in the same `config_setting` but at least one must + be set for any given `config_setting`. + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`constraint_values` + +List of [labels](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + + The minimum set of `constraint_values` that the target platform must specify + in order to match this `config_setting`. (The execution platform is not + considered here.) Any additional constraint values that the platform has are ignored. See + [Configurable Build Attributes](https://bazel.build/docs/configurable-attributes#platforms) for details. + + + +If two `config_setting` s match in the same `select` and one has +all the same flags and `constraint_setting` s as the other plus additional ones, +the one with more settings is chosen. This is known as "specialization". For example, +a `config_setting` matching `x86` and `Linux` specializes +a `config_setting` matching `x86`. + + + +If two `config_setting` s match and both have `constraint_value` s +not present in the other, this is an error. + + + +`define_values` + +Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `{}` + + The same as [`values`](/reference/be/general.html#config_setting.values) but + specifically for the `--define` flag. + + + +`--define` is special because its syntax ( `--define KEY=VAL`) +means `KEY=VAL` is a _value_ from a Bazel flag perspective. + + +That means: + + + +``` + config_setting( + name = "a_and_b", + values = { + "define": "a=1", + "define": "b=2", + }) + +``` + +doesn't work because the same key ( `define`) appears twice in the +dictionary. This attribute solves that problem: + + + +``` + config_setting( + name = "a_and_b", + define_values = { + "a": "1", + "b": "2", + }) + +``` + +correctly matches `bazel build //foo --define a=1 --define b=2`. + + + +`--define` can still appear in +[`values`](/reference/be/general.html#config_setting.values) with normal flag syntax, +and can be mixed freely with this attribute as long as dictionary keys remain distinct. + + + +`flag_values` + +Dictionary: [label](/concepts/labels) -\> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `{}` + + The same as [`values`](/reference/be/general.html#config_setting.values) but + for [user-defined build flags](https://bazel.build/rules/config#user-defined-build-settings). + + + +This is a distinct attribute because user-defined flags are referenced as labels while +built-in flags are referenced as arbitrary strings. + + + +`values` + +Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `{}` + + The set of configuration values that match this rule (expressed as build flags) + + + +This rule inherits the configuration of the configured target that +references it in a `select` statement. It is considered to +"match" a Bazel invocation if, for every entry in the dictionary, its +configuration matches the entry's expected value. For example +`values = {"compilation_mode": "opt"}` matches the invocations +`bazel build --compilation_mode=opt ...` and +`bazel build -c opt ...` on target-configured rules. + + +For convenience's sake, configuration values are specified as build flags (without +the preceding `"--"`). But keep in mind that the two are not the same. This +is because targets can be built in multiple configurations within the same +build. For example, an exec configuration's "cpu" matches the value of +`--host_cpu`, not `--cpu`. So different instances of the +same `config_setting` may match the same invocation differently +depending on the configuration of the rule using them. + + +If a flag is not explicitly set at the command line, its default value is used. +If a key appears multiple times in the dictionary, only the last instance is used. +If a key references a flag that can be set multiple times on the command line (e.g. +`bazel build --copt=foo --copt=bar --copt=baz ...`), a match occurs if +_any_ of those settings match. + + +## filegroup + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/filegroup/FilegroupRule.java) + +``` +filegroup(name, srcs, data, aspect_hints, compatible_with, deprecation, features, licenses, output_group, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) +``` + +Use `filegroup` to gather the outputs of a set of targets under a single +label. + +`filegroup` is not a substitute for listing targets on the command line or +in an attribute of another rule, because targets have many properties other than their +outputs, which are not collected in the same way. However, it's still useful in quite +a few cases, for example, in the `srcs` attribute of a genrule, or +the `data` attribute of a \*\_binary rule. + +Using `filegroup` is encouraged instead of referencing directories directly. +Directly referencing directories is discouraged because the build system does not have +full knowledge of all files below the directory, so it may not rebuild when these files change. +When combined with [glob](/reference/be/functions.html#glob), `filegroup` can ensure that all +files are explicitly known to the build system. + +#### Examples + +To create a `filegroup` consisting of two source files, do + +``` +filegroup( + name = "mygroup", + srcs = [ + "a_file.txt", + "//a/library:target", + "//a/binary:target", + ], +) + +``` + +Or, use a `glob` to fully crawl a testdata directory: + +``` +filegroup( + name = "exported_testdata", + srcs = glob([ + "testdata/*.dat", + "testdata/logs/**/*.log", + ]), +) + +``` + +To make use of these definitions, reference the `filegroup` with a label from any rule: + +``` +cc_library( + name = "my_library", + srcs = ["foo.cc"], + data = [ + "//my_package:exported_testdata", + "//my_package:mygroup", + ], +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of targets that are members of the file group. + + +It is common to use the result of a [glob](/reference/be/functions.html#glob) expression for +the value of the `srcs` attribute. + + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this rule at runtime. + + +Targets named in the `data` attribute will be added to the +`runfiles` of this `filegroup` rule. When the +`filegroup` is referenced in the `data` attribute of +another rule its `runfiles` will be added to the `runfiles` +of the depending rule. See the [data dependencies](/concepts/dependencies#data-dependencies) +section and [general documentation of\ +`data`](/reference/be/common-definitions#common.data) for more information about how to depend on and use data files. + + +`output_group` + +String; default is `""` + + The output group from which to gather artifacts from sources. If this attribute is + specified, artifacts from the specified output group of the dependencies will be exported + instead of the default output group. + + +An "output group" is a category of output artifacts of a target, specified in that +rule's implementation. + + +## genquery + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java) + +``` +genquery(name, deps, data, aspect_hints, compatible_with, compressed_output, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, expression, features, licenses, opts, package_metadata, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility) +``` + +`genquery()` runs a query specified in the +[Bazel query language](/reference/query) and dumps the result +into a file. + + +In order to keep the build consistent, the query is allowed only to visit +the transitive closure of the targets specified in the `scope` +attribute. Queries violating this rule will fail during execution if +`strict` is unspecified or true (if `strict` is false, +the out of scope targets will simply be skipped with a warning). The +easiest way to make sure this does not happen is to mention the same labels +in the scope as in the query expression. + + +The only difference between the queries allowed here and on the command +line is that queries containing wildcard target specifications (e.g. +`//pkg:*` or `//pkg:all`) are not allowed here. +The reasons for this are two-fold: first, because `genquery` has +to specify a scope to prevent targets outside the transitive closure of the +query to influence its output; and, second, because `BUILD` files +do not support wildcard dependencies (e.g. `deps=["//a/..."]` +is not allowed). + + +The genquery's output is ordered lexicographically in order to enforce deterministic output, +with the exception of `--output=graph|minrank|maxrank` or when `somepath` +is used as the top-level function. + + +The name of the output file is the name of the rule. + + +#### Examples + +This example writes the list of the labels in the transitive closure of the +specified target to a file. + + +``` +genquery( + name = "kiwi-deps", + expression = "deps(//kiwi:kiwi_lib)", + scope = ["//kiwi:kiwi_lib"], +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`compressed_output` + +Boolean; default is `False` + + If `True`, query output is written in GZIP file format. This setting can be used + to avoid spikes in Bazel's memory use when the query output is expected to be large. Bazel + already internally compresses query outputs greater than 220 bytes regardless of + the value of this setting, so setting this to `True` may not reduce retained + heap. However, it allows Bazel to skip _decompression_ when writing the output file, + which can be memory-intensive. + + `expression` + +String; required + + The query to be executed. In contrast to the command line and other places in BUILD files, + labels here are resolved relative to the root directory of the workspace. For example, the + label `:b` in this attribute in the file `a/BUILD` will refer to the + target `//:b`. + + `opts` + +List of strings; default is `[]` + + The options that are passed to the query engine. These correspond to the command line + options that can be passed to `bazel query`. Some query options are not allowed + here: `--keep_going`, `--query_file`, `--universe_scope`, + `--order_results` and `--order_output`. Options not specified here + will have their default values just like on the command line of `bazel query`. + + `scope` + +List of [labels](/concepts/labels); required + + The scope of the query. The query is not allowed to touch targets outside the transitive + closure of these targets. + + `strict` + +Boolean; default is `True` + + If true, targets whose queries escape the transitive closure of their scopes will fail to + build. If false, Bazel will print a warning and skip whatever query path led it outside of + the scope, while completing the rest of the query. + + + +## genrule + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java) + +``` +genrule(name, srcs, outs, aspect_hints, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility) +``` + +A `genrule` generates one or more files using a user-defined Bash command. + +Genrules are generic build rules that you can use if there's no specific rule for the task. +For example, you could run a Bash one-liner. If however you need to compile C++ files, stick +to the existing `cc_*` rules, because all the heavy lifting has already been done +for you. + +Note that genrule requires a shell to interpret the command argument. +It is also easy to reference arbitrary programs available on the PATH, however this makes the +command non-hermetic and may not be reproducible. +If you only need to run a single tool, consider using +[run\_binary](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/run_binary_doc.md) +instead. + +Like every other action, the action created by genrules should not assume anything about their +working directory; all Bazel guarantees is that their declared inputs will be available at the +path that `$(location)` returns for their label. For example, if the action is run in a +sandbox or remotely, the implementation of the sandbox or the remote execution will determine the +working directory. If run directly (using the `standalone` strategy), the working +directory will be the execution root, i.e. the result of `bazel info execution_root`. + +Do not use a genrule for running tests. There are special dispensations for tests and test +results, including caching policies and environment variables. Tests generally need to be run +after the build is complete and on the target architecture, whereas genrules are executed during +the build and on the exec architecture (the two may be different). If you need a general purpose +testing rule, use [`sh_test`](/reference/be/shell.html#sh_test). + +#### Cross-compilation Considerations + +_See [the user manual](/docs/user-manual#configurations) for more info about_ +_cross-compilation._ + +While genrules run during a build, their outputs are often used after the build, for deployment or +testing. Consider the example of compiling C code for a microcontroller: the compiler accepts C +source files and generates code that runs on a microcontroller. The generated code obviously +cannot run on the CPU that was used for building it, but the C compiler (if compiled from source) +itself has to. + +The build system uses the exec configuration to describe the machine(s) on which the build runs +and the target configuration to describe the machine(s) on which the output of the build is +supposed to run. It provides options to configure each of these and it segregates the +corresponding files into separate directories to avoid conflicts. + +For genrules, the build system ensures that dependencies are built appropriately: +`srcs` are built (if necessary) for the _target_ configuration, +`tools` are built for the _exec_ configuration, and the output is considered to +be for the _target_ configuration. It also provides ["Make" variables](/reference/be/make-variables) that genrule commands can pass to the corresponding tools. + +It is intentional that genrule defines no `deps` attribute: other built-in rules use +language-dependent meta information passed between the rules to automatically determine how to +handle dependent rules, but this level of automation is not possible for genrules. Genrules work +purely at the file and runfiles level. + +#### Special Cases + +_Exec-exec compilation_: in some cases, the build system needs to run genrules such that the +output can also be executed during the build. If for example a genrule builds some custom compiler +which is subsequently used by another genrule, the first one has to produce its output for the +exec configuration, because that's where the compiler will run in the other genrule. In this case, +the build system does the right thing automatically: it builds the `srcs` and +`outs` of the first genrule for the exec configuration instead of the target +configuration. See [the user manual](/docs/user-manual#configurations) for more +info. + +_JDK & C++ Tooling_: to use a tool from the JDK or the C++ compiler suite, the build system +provides a set of variables to use. See ["Make" variable](/reference/be/make-variables) for +details. + +#### Genrule Environment + +The genrule command is executed by a Bash shell that is configured to fail when a command +or a pipeline fails, using `set -e -o pipefail`. + +The build tool executes the Bash command in a sanitized process environment that +defines only core variables such as `PATH`, `PWD`, +`TMPDIR`, and a few others. + +To ensure that builds are reproducible, most variables defined in the user's shell +environment are not passed though to the genrule's command. However, Bazel (but not +Blaze) passes through the value of the user's `PATH` environment variable. + +Any change to the value of `PATH` will cause Bazel to re-execute the command +on the next build. + + +A genrule command should not access the network except to connect processes that are +children of the command itself, though this is not currently enforced. + +The build system automatically deletes any existing output files, but creates any necessary parent +directories before it runs a genrule. It also removes any output files in case of a failure. + +#### General Advice + +- Do ensure that tools run by a genrule are deterministic and hermetic. They should not write + timestamps to their output, and they should use stable ordering for sets and maps, as well as + write only relative file paths to the output, no absolute paths. Not following this rule will + lead to unexpected build behavior (Bazel not rebuilding a genrule you thought it would) and + degrade cache performance. +- Do use `$(location)` extensively, for outputs, tools and sources. Due to the + segregation of output files for different configurations, genrules cannot rely on hard-coded + and/or absolute paths. +- Do write a common Starlark macro in case the same or very similar genrules are used in + multiple places. If the genrule is complex, consider implementing it in a script or as a + Starlark rule. This improves readability as well as testability. +- Do make sure that the exit code correctly indicates success or failure of the genrule. +- Do not write informational messages to stdout or stderr. While useful for debugging, this can + easily become noise; a successful genrule should be silent. On the other hand, a failing genrule + should emit good error messages. +- `$$` evaluates to a `$`, a literal dollar-sign, so in order to invoke a + shell command containing dollar-signs such as `ls $(dirname $x)`, one must escape it + thus: `ls $$(dirname $$x)`. +- Avoid creating symlinks and directories. Bazel doesn't copy over the directory/symlink + structure created by genrules and its dependency checking of directories is unsound. +- When referencing the genrule in other rules, you can use either the genrule's label or the + labels of individual output files. Sometimes the one approach is more readable, sometimes the + other: referencing outputs by name in a consuming rule's `srcs` will avoid + unintentionally picking up other outputs of the genrule, but can be tedious if the genrule + produces many outputs. + +#### Examples + +This example generates `foo.h`. There are no sources, because the command doesn't take +any input. The "binary" run by the command is a perl script in the same package as the genrule. + +``` +genrule( + name = "foo", + srcs = [], + outs = ["foo.h"], + cmd = "./$(location create_foo.pl) > \"$@\"", + tools = ["create_foo.pl"], +) + +``` + +The following example shows how to use a [`filegroup`](/reference/be/general.html#filegroup) and the outputs of another `genrule`. Note that using `$(SRCS)` instead +of explicit `$(location)` directives would also work; this example uses the latter for +sake of demonstration. + +``` +genrule( + name = "concat_all_files", + srcs = [ + "//some:files", # a filegroup with multiple files in it ==> $(locations) + "//other:gen", # a genrule with a single output ==> $(location) + ], + outs = ["concatenated.txt"], + cmd = "cat $(locations //some:files) $(location //other:gen) > $@", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +You may refer to this rule by name in the + `srcs` or `deps` section of other `BUILD` + rules. If the rule generates source files, you should use the + `srcs` attribute. + + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + A list of inputs for this rule, such as source files to process. + + +_This attributes is not suitable to list tools executed by the `cmd`; use_ +_the [`tools`](/reference/be/general.html#genrule.tools) attribute for them instead._ + +The build system ensures these prerequisites are built before running the genrule +command; they are built using the same configuration as the original build request. The +names of the files of these prerequisites are available to the command as a +space-separated list in `$(SRCS)`; alternatively the path of an individual +`srcs` target `//x:y` can be obtained using `$(location + //x:y)`, or using `$<` provided it's the only entry in +`srcs`. + + +`outs` + +List of [filenames](/concepts/build-ref#filename); [nonconfigurable](common-definitions.html#configurable-attributes); required + + A list of files generated by this rule. + + +Output files must not cross package boundaries. +Output filenames are interpreted as relative to the package. + + +If the `executable` flag is set, `outs` must contain exactly one +label. + + +The genrule command is expected to create each output file at a predetermined location. +The location is available in `cmd` using [genrule-specific "Make"\ +variables](/reference/be/make-variables#predefined_genrule_variables) ( `$@`, `$(OUTS)`, `$(@D)` or ` + $(RULEDIR)`) or using [`$(location)`](/reference/be/make-variables#predefined_label_variables) substitution. + + +`cmd` + +String; default is `""` + + The command to run. + Subject to [`$(location)\ + `](/reference/be/make-variables#predefined_label_variables) and ["Make" variable](/reference/be/make-variables) substitution. + + +1. First [`$(location)\ + `](/reference/be/make-variables#predefined_label_variables) substitution is applied, replacing all occurrences of `$(location + label)` and of `$(locations label)` (and similar + constructions using related variables `execpath`, `execpaths`, + `rootpath` and `rootpaths`). + +2. Next, ["Make" variables](/reference/be/make-variables) are expanded. Note that + predefined variables `$(JAVA)`, `$(JAVAC)` and + `$(JAVABASE)` expand under the _exec_ configuration, so Java invocations + that run as part of a build step can correctly load shared libraries and other + dependencies. + +3. Finally, the resulting command is executed using the Bash shell. If its exit code is + non-zero the command is considered to have failed. + + + This is the fallback of `cmd_bash`, `cmd_ps` and `cmd_bat`, + if none of them are applicable. + + +If the command line length exceeds the platform limit (64K on Linux/macOS, 8K on Windows), +then genrule will write the command to a script and execute that script to work around. This +applies to all cmd attributes ( `cmd`, `cmd_bash`, `cmd_ps`, +`cmd_bat`). + + +`cmd_bash` + +String; default is `""` + + The Bash command to run. + + +This attribute has higher priority than `cmd`. The command is expanded and +runs in the exact same way as the `cmd` attribute. + + +`cmd_bat` + +String; default is `""` + + The Batch command to run on Windows. + + +This attribute has higher priority than `cmd` and `cmd_bash`. +The command runs in the similar way as the `cmd` attribute, with the +following differences: + + +- This attribute only applies on Windows. + +- The command runs with `cmd.exe /c` with the following default arguments: + + - `/S` \- strip first and last quotes and execute everything else as is. + + - `/E:ON` \- enable extended command set. + + - `/V:ON` \- enable delayed variable expansion + + - `/D` \- ignore AutoRun registry entries. +- After [$(location)](/reference/be/make-variables#predefined_label_variables) and + ["Make" variable](/reference/be/make-variables) substitution, the paths will be + expanded to Windows style paths (with backslash). + + +`cmd_ps` + +String; default is `""` + + The Powershell command to run on Windows. + + +This attribute has higher priority than `cmd`, `cmd_bash` and +`cmd_bat`. The command runs in the similar way as the `cmd` +attribute, with the following differences: + + +- This attribute only applies on Windows. + +- The command runs with `powershell.exe /c`. + + +To make Powershell easier to use and less error-prone, we run the following +commands to set up the environment before executing Powershell command in genrule. + + +- `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` \- allow running + unsigned scripts. + +- `$errorActionPreference='Stop'` \- In case there are multiple commands + separated by `;`, the action exits immediately if a Powershell CmdLet fails, + but this does **NOT** work for external command. + +- `$PSDefaultParameterValues['*:Encoding'] = 'utf8'` \- change the default + encoding from utf-16 to utf-8. + + +`executable` + +Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` + + Declare output to be executable. + + +Setting this flag to True means the output is an executable file and can be run using the +`run` command. The genrule must produce exactly one output in this case. +If this attribute is set, `run` will try executing the file regardless of +its content. + + +Declaring data dependencies for the generated executable is not supported. + +`local` + +Boolean; default is `False` + +If set to True, this option forces this `genrule` to run using the "local" +strategy, which means no remote execution, no sandboxing, no persistent workers. + + +This is equivalent to providing 'local' as a tag ( `tags=["local"]`). + + +`message` + +String; default is `""` + + A progress message. + + +A progress message that will be printed as this build step is executed. By default, the +message is "Generating _output_" (or something equally bland) but you may provide a +more specific one. Use this attribute instead of `echo` or other print +statements in your `cmd` command, as this allows the build tool to control +whether such progress messages are printed or not. + + +`output_licenses` + +List of strings; default is `[]` + + See [`common attributes\ + `](/reference/be/common-definitions#binary.output_licenses)`output_to_bindir` + +Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` + +If set to True, this option causes output files to be written into the `bin` +directory instead of the `genfiles` directory. + + +`toolchains` + +List of [labels](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + +The set of targets whose [Make variables](/reference/be/make-variables) this genrule +is allowed to access, or the [`toolchain_type`](/docs/toolchains) +targets that this genrule will access. + + +Toolchains accessed via `toolchain_type` must also provide a +`TemplateVariableInfo` provider, which the target can use to access toolchain +details. + + +`tools` + +List of [labels](/concepts/labels); default is `[]` + + A list of _tool_ dependencies for this rule. See the definition of + [dependencies](/concepts/build-ref#deps) for more information. + +The build system ensures these prerequisites are built before running the genrule command; +they are built using the [_exec_\ +configuration](/contribute/guide#configurations), since these tools are executed as part of the build. The path of an +individual `tools` target `//x:y` can be obtained using +`$(location //x:y)`. + + +Any `*_binary` or tool to be executed by `cmd` must appear in this +list, not in `srcs`, to ensure they are built in the correct configuration. + + +## starlark\_doc\_extract + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/starlarkdocextract/StarlarkDocExtractRule.java) + +``` +starlark_doc_extract(name, deps, src, data, allow_unused_doc_comments, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility) +``` + +`starlark_doc_extract()` extracts documentation for rules, functions (including +macros), aspects, and providers defined or re-exported in a given `.bzl` or +`.scl` file. The output of this rule is a `ModuleInfo` binary proto as defined +in +[stardoc\_output.proto](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto) +in the Bazel source tree. + +#### Implicit output targets + +- `name.binaryproto` (the default output): A + `ModuleInfo` binary proto. +- `name.textproto` (only built if explicitly requested): the text + proto version of `name.binaryproto`. + +Warning: the output format of this rule is not guaranteed to be stable. It is intended mainly for +internal use by [Stardoc](https://github.com/bazelbuild/stardoc). + + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + A list of targets wrapping the Starlark files which are `load()`-ed by + `src`. These targets _should_ under normal usage be + [`bzl_library`](https://github.com/bazelbuild/bazel-skylib/blob/main/bzl_library.bzl) + targets, but the `starlark_doc_extract` rule does not enforce that, and accepts + any target which provides Starlark files in its `DefaultInfo`. + + + +Note that the wrapped Starlark files must be files in the source tree; Bazel cannot +`load()` generated files. + + + +`src` + +[Label](/concepts/labels); required + + A Starlark file from which to extract documentation. + + + +Note that this must be a file in the source tree; Bazel cannot `load()` +generated files. + + + +`allow_unused_doc_comments` + +Boolean; default is `False` + + If true, allow and silently ignore doc comments (comments starting with `#:`) + which are not attached to any global variable, or which are attached to a variable whose + value's documentation should be provided in a different way (for example, in a docstring for + a function, or via `rule(doc = ...)` for a rule). + + `render_main_repo_name` + +Boolean; default is `False` + + If true, render labels in the main repository in emitted documentation with a repo component + (in other words, `//foo:bar.bzl` will be emitted as + `@main_repo_name//foo:bar.bzl`). + + +The name to use for the main repository is obtained from `module(name = ...)` +in the main repository's `MODULE.bazel` file (if Bzlmod is enabled), or from +`workspace(name = ...)` in the main repository's `WORKSPACE` file. + + +This attribute should be set to `False` when generating documentation for +Starlark files which are intended to be used only within the same repository, and to +`True` when generating documentation for Starlark files which are intended to be +used from other repositories. + + + +`symbol_names` + +List of strings; default is `[]` + + An optional list of qualified names of exported functions, rules, providers, or aspects (or + structs in which they are nested) for which to extract documentation. Here, a _qualified_ +_name_ means the name under which an entity is made available to a user of the module, + including any structs in which the entity is nested for namespacing. + + + +`starlark_doc_extract` emits documentation for an entity if and only if + + +1. each component of the entity's qualified name is public (in other words, the first + character of each component of the qualified name is alphabetic, not `"_"`); + _and_ + 1. _either_ the `symbol_names` list is empty (which is the default + case), _or_ + 2. the entity's qualified name, or the qualified name of a struct in which the entity + is nested, is in the `symbol_names` list. + +## test\_suite + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java) + +``` +test_suite(name, aspect_hints, compatible_with, deprecation, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, tests, visibility) +``` + +A `test_suite` defines a set of tests that are considered "useful" to humans. This +allows projects to define sets of tests, such as "tests you must run before checkin", "our +project's stress tests" or "all small tests." The `bazel test` command respects this sort +of organization: For an invocation like `bazel test //some/test:suite`, Bazel first +enumerates all test targets transitively included by the `//some/test:suite` target (we +call this "test\_suite expansion"), then Bazel builds and tests those targets. + +#### Examples + +A test suite to run all of the small tests in the current package. + +``` +test_suite( + name = "small_tests", + tags = ["small"], +) + +``` + +A test suite that runs a specified set of tests: + +``` +test_suite( + name = "smoke_tests", + tests = [ + "system_unittest", + "public_api_unittest", + ], +) + +``` + +A test suite to run all tests in the current package which are not flaky. + +``` +test_suite( + name = "non_flaky_test", + tags = ["-flaky"], +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`tags` + +List of strings; [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + + List of text tags such as "small" or "database" or "-flaky". Tags may be any valid string. + + +Tags which begin with a "-" character are considered negative tags. The +preceding "-" character is not considered part of the tag, so a suite tag +of "-small" matches a test's "small" size. All other tags are considered +positive tags. + + +Optionally, to make positive tags more explicit, tags may also begin with the +"+" character, which will not be evaluated as part of the text of the tag. It +merely makes the positive and negative distinction easier to read. + + +Only test rules that match **all** of the positive tags and **none** of the negative +tags will be included in the test suite. Note that this does not mean that error checking +for dependencies on tests that are filtered out is skipped; the dependencies on skipped +tests still need to be legal (e.g. not blocked by visibility constraints). + + +The `manual` tag keyword is treated differently than the above by the +"test\_suite expansion" performed by the `bazel test` command on invocations +involving wildcard +[target patterns](https://bazel.build/docs/build#specifying-build-targets). +There, `test_suite` targets tagged "manual" are filtered out (and thus not +expanded). This behavior is consistent with how `bazel build` and +`bazel test` handle wildcard target patterns in general. Note that this is +explicitly different from how `bazel query 'tests(E)'` behaves, as suites are +always expanded by the `tests` query function, regardless of the +`manual` tag. + + +Note that a test's `size` is considered a tag for the purpose of filtering. + + +If you need a `test_suite` that contains tests with mutually exclusive tags +(e.g. all small and medium tests), you'll have to create three `test_suite` +rules: one for all small tests, one for all medium tests, and one that includes the +previous two. + + +`tests` + +List of [labels](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + + A list of test suites and test targets of any language. + + +Any `*_test` is accepted here, independent of the language. No +`*_binary` targets are accepted however, even if they happen to run a test. +Filtering by the specified `tags` is only done for tests listed directly in +this attribute. If this attribute contains `test_suite` s, the tests inside +those will not be filtered by this `test_suite` (they are considered to be +filtered already). + + +If the `tests` attribute is unspecified or empty, the rule will default to +including all test rules in the current BUILD file that are not tagged as +`manual`. These rules are still subject to `tag` filtering. diff --git a/reference/be/java.mdx b/reference/be/java.mdx new file mode 100644 index 0000000..7bbbd1a --- /dev/null +++ b/reference/be/java.mdx @@ -0,0 +1,1901 @@ +--- +title: 'Java Rules' +--- + + + +## Rules + +- [java\_binary](#java_binary) +- [java\_import](#java_import) +- [java\_library](#java_library) +- [java\_test](#java_test) +- [java\_package\_configuration](#java_package_configuration) +- [java\_plugin](#java_plugin) +- [java\_runtime](#java_runtime) +- [java\_single\_jar](#java_single_jar) +- [java\_toolchain](#java_toolchain) + +## java\_binary + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_binary.bzl) + +``` +java_binary(name, deps, srcs, data, resources, add_exports, add_opens, args, aspect_hints, bootclasspath, classpath_resources, compatible_with, create_executable, deploy_env, deploy_manifest_lines, deprecation, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, javacopts, jvm_flags, launcher, licenses, main_class, neverlink, output_licenses, package_metadata, plugins, resource_strip_prefix, restricted_to, runtime_deps, stamp, tags, target_compatible_with, testonly, toolchains, use_launcher, use_testrunner, visibility) +``` + +Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. +The wrapper shell script uses a classpath that includes, among other things, a jar file for each +library on which the binary depends. When running the wrapper shell script, any nonempty +`JAVABIN` environment variable will take precedence over the version specified via +Bazel's `--java_runtime_version` flag. + +The wrapper script accepts several unique flags. Refer to +`java_stub_template.txt` +for a list of configurable flags and environment variables accepted by the wrapper. + +#### Implicit output targets + +- `name.jar`: A Java archive, containing the class files and other + resources corresponding to the binary's direct dependencies. +- `name-src.jar`: An archive containing the sources ("source + jar"). +- `name_deploy.jar`: A Java archive suitable for deployment (only + built if explicitly requested). + + + Building the `<name>_deploy.jar` target for your rule + creates a self-contained jar file with a manifest that allows it to be run with the + `java -jar` command or with the wrapper script's `--singlejar` + option. Using the wrapper script is preferred to `java -jar` because it + also passes the [JVM flags](#java_binary-jvm_flags) and the options + to load native libraries. + + + + The deploy jar contains all the classes that would be found by a classloader that + searched the classpath from the binary's wrapper script from beginning to end. It also + contains the native libraries needed for dependencies. These are automatically loaded + into the JVM at runtime. + + + If your target specifies a [launcher](#java_binary.launcher) + attribute, then instead of being a normal JAR file, the \_deploy.jar will be a + native binary. This will contain the launcher plus any native (C++) dependencies of + your rule, all linked into a static binary. The actual jar file's bytes will be + appended to that native binary, creating a single binary blob containing both the + executable and the Java code. You can execute the resulting jar file directly + like you would execute any native binary. + +- `name_deploy-src.jar`: An archive containing the sources + collected from the transitive closure of the target. These will match the classes in the + `deploy.jar` except where jars have no matching source jar. + +It is good practice to use the name of the source file that is the main entry point of the +application (minus the extension). For example, if your entry point is called +`Main.java`, then your name could be `Main`. + +A `deps` attribute is not allowed in a `java_binary` rule without +[`srcs`](#java_binary-srcs); such a rule requires a +[`main_class`](#java_binary-main_class) provided by +[`runtime_deps`](#java_binary-runtime_deps). + +The following code snippet illustrates a common mistake: + +```lang-starlark + +java_binary( + name = "DontDoThis", + srcs = [ + ..., + "GeneratedJavaFile.java", # a generated .java file + ], + deps = [":generating_rule",], # rule that generates that file +) + +``` + +Do this instead: + +```lang-starlark + +java_binary( + name = "DoThisInstead", + srcs = [ + ..., + ":generating_rule", + ], +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries to be linked in to the target. +See general comments about `deps` at +[Typical attributes defined by\ +most build rules](common-definitions.html#typical-attributes). + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of source files that are processed to create the target. +This attribute is almost always required; see exceptions below. + +Source files of type `.java` are compiled. In case of generated +`.java` files it is generally advisable to put the generating rule's name +here instead of the name of the file itself. This not only improves readability but +makes the rule more resilient to future changes: if the generating rule generates +different files in the future, you only need to fix one place: the `outs` of +the generating rule. You should not list the generating rule in `deps` +because it is a no-op. + +Source files of type `.srcjar` are unpacked and compiled. (This is useful if +you need to generate a set of `.java` files with a genrule.) + +Rules: if the rule (typically `genrule` or `filegroup`) generates +any of the files listed above, they will be used the same way as described for source +files. + +This argument is almost always required, except if a +[`main_class`](#java_binary.main_class) attribute specifies a +class on the runtime classpath or you specify the `runtime_deps` argument. + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this library at runtime. +See general comments about `data` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + `resources` + +List of [labels](/concepts/labels); default is `[]` + + A list of data files to include in a Java jar. + +Resources may be source files or generated files. + +If resources are specified, they will be bundled in the jar along with the usual +`.class` files produced by compilation. The location of the resources inside +of the jar file is determined by the project structure. Bazel first looks for Maven's +[standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html), +(a "src" directory followed by a "resources" directory grandchild). If that is not +found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for +example, if a resource is at `<workspace root>/x/java/y/java/z`, the +path of the resource will be `y/java/z`. This heuristic cannot be overridden, +however, the `resource_strip_prefix` attribute can be used to specify a +specific alternative directory for resource files. + + +`add_exports` + +List of strings; default is `[]` + + Allow this library to access the given `module` or `package`. + +This corresponds to the javac and JVM --add-exports= flags. + + +`add_opens` + +List of strings; default is `[]` + + Allow this library to reflectively access the given `module` or +`package`. + +This corresponds to the javac and JVM --add-opens= flags. + + +`bootclasspath` + +[Label](/concepts/labels); default is `None` + + Restricted API, do not use! + `classpath_resources` + +List of [labels](/concepts/labels); default is `[]` + + _DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)_ + +A list of resources that must be located at the root of the java tree. This attribute's +only purpose is to support third-party libraries that require that their resources be +found on the classpath as exactly `"myconfig.xml"`. It is only allowed on +binaries and not libraries, due to the danger of namespace conflicts. + +`create_executable` + +Boolean; default is `True` + + Deprecated, use `java_single_jar` instead. + `deploy_env` + +List of [labels](/concepts/labels); default is `[]` + + A list of other `java_binary` targets which represent the deployment +environment for this binary. +Set this attribute when building a plugin which will be loaded by another +`java_binary`. + + Setting this attribute excludes all dependencies from +the runtime classpath (and the deploy jar) of this binary that are shared between this +binary and the targets specified in `deploy_env`. + `deploy_manifest_lines` + +List of strings; default is `[]` + + A list of lines to add to the `META-INF/manifest.mf` file generated for the +`*_deploy.jar` target. The contents of this attribute are _not_ subject +to ["Make variable"](make-variables.html) substitution. + `javacopts` + +List of strings; default is `[]` + + Extra compiler options for this binary. +Subject to ["Make variable"](make-variables.html) substitution and +[Bourne shell tokenization](common-definitions.html#sh-tokenization). + +These compiler options are passed to javac after the global compiler options. + +`jvm_flags` + +List of strings; default is `[]` + + A list of flags to embed in the wrapper script generated for running this binary. +Subject to [$(location)](/reference/be/make-variables#location) and +["Make variable"](make-variables.html) substitution, and +[Bourne shell tokenization](common-definitions.html#sh-tokenization). + +The wrapper script for a Java binary includes a CLASSPATH definition +(to find all the dependent jars) and invokes the right Java interpreter. +The command line generated by the wrapper script includes the name of +the main class followed by a `"$@"` so you can pass along other +arguments after the classname. However, arguments intended for parsing +by the JVM must be specified _before_ the classname on the command +line. The contents of `jvm_flags` are added to the wrapper +script before the classname is listed. + +Note that this attribute has _no effect_ on `*_deploy.jar` +outputs. + +`launcher` + +[Label](/concepts/labels); default is `None` + + Specify a binary that will be used to run your Java program instead of the +normal `bin/java` program included with the JDK. +The target must be a `cc_binary`. Any `cc_binary` that +implements the +[Java Invocation API](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html) can be specified as a value for this attribute. + +By default, Bazel will use the normal JDK launcher (bin/java or java.exe). + +The related [`\ +--java_launcher`](/docs/user-manual#flag--java_launcher) Bazel flag affects only those +`java_binary` and `java_test` targets that have +_not_ specified a `launcher` attribute. + +Note that your native (C++, SWIG, JNI) dependencies will be built differently +depending on whether you are using the JDK launcher or another launcher: + +- If you are using the normal JDK launcher (the default), native dependencies are + built as a shared library named `{name}_nativedeps.so`, where + `{name}` is the `name` attribute of this java\_binary rule. + Unused code is _not_ removed by the linker in this configuration. +- If you are using any other launcher, native (C++) dependencies are statically + linked into a binary named `{name}_nativedeps`, where `{name}` + is the `name` attribute of this java\_binary rule. In this case, + the linker will remove any code it thinks is unused from the resulting binary, + which means any C++ code accessed only via JNI may not be linked in unless + that `cc_library` target specifies `alwayslink = True`. + +When using any launcher other than the default JDK launcher, the format +of the `*_deploy.jar` output changes. See the main +[java\_binary](#java_binary) docs for details. + +`main_class` + +String; default is `""` + + Name of class with `main()` method to use as entry point. +If a rule uses this option, it does not need a `srcs=[...]` list. +Thus, with this attribute one can make an executable from a Java library that already +contains one or more `main()` methods. + +The value of this attribute is a class name, not a source file. The class must be +available at runtime: it may be compiled by this rule (from `srcs`) or +provided by direct or transitive dependencies (through `runtime_deps` or +`deps`). If the class is unavailable, the binary will fail at runtime; there +is no build-time check. + +`neverlink` + +Boolean; default is `False` + +`plugins` + +List of [labels](/concepts/labels); default is `[]` + + Java compiler plugins to run at compile-time. +Every `java_plugin` specified in this attribute will be run whenever this rule +is built. A library may also inherit plugins from dependencies that use +`exported_plugins`. Resources +generated by the plugin will be included in the resulting jar of this rule. + `resource_strip_prefix` + +String; default is `""` + + The path prefix to strip from Java resources. + +If specified, this path prefix is stripped from every file in the `resources` +attribute. It is an error for a resource file not to be under this directory. If not +specified (the default), the path of resource file is determined according to the same +logic as the Java package of source files. For example, a source file at +`stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. + +`runtime_deps` + +List of [labels](/concepts/labels); default is `[]` + + Libraries to make available to the final binary or test at runtime only. +Like ordinary `deps`, these will appear on the runtime classpath, but unlike +them, not on the compile-time classpath. Dependencies needed only at runtime should be +listed here. Dependency-analysis tools should ignore targets that appear in both +`runtime_deps` and `deps`. + `stamp` + +Integer; default is `-1` + + Whether to encode build information into the binary. Possible values: + +- `stamp = 1`: Always stamp the build information into the binary, even in + [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This** + **setting should be avoided**, since it potentially kills remote caching for the + binary and any downstream actions that depend on it. + +- `stamp = 0`: Always replace build information by constant values. This + gives good build result caching. + +- `stamp = -1`: Embedding of build information is controlled by the + [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. + + +Stamped binaries are _not_ rebuilt unless their dependencies change. + +`use_launcher` + +Boolean; default is `True` + + Whether the binary should use a custom launcher. + +If this attribute is set to false, the +[launcher](/reference/be/java.html#java_binary.launcher) attribute and the related +[`--java_launcher`](/docs/user-manual#flag--java_launcher) flag +will be ignored for this target. + + +`use_testrunner` + +Boolean; default is `False` + + Use the test runner (by default +`com.google.testing.junit.runner.BazelTestRunner`) class as the +main entry point for a Java program, and provide the test class +to the test runner as a value of `bazel.test_suite` +system property. + +You can use this to override the default +behavior, which is to use test runner for +`java_test` rules, +and not use it for `java_binary` rules. It is unlikely +you will want to do this. One use is for `AllTest` +rules that are invoked by another rule (to set up a database +before running the tests, for example). The `AllTest` +rule must be declared as a `java_binary`, but should +still use the test runner as its main entry point. + +The name of a test runner class can be overridden with `main_class` attribute. + + +## java\_import + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_import.bzl) + +``` +java_import(name, deps, data, add_exports, add_opens, aspect_hints, compatible_with, constraints, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exports, features, jars, licenses, neverlink, package_metadata, proguard_specs, restricted_to, runtime_deps, srcjar, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +This rule allows the use of precompiled `.jar` files as +libraries for `java_library` and +`java_binary` rules. + +#### Examples + +```lang-starlark + + java_import( + name = "maven_model", + jars = [ + "maven_model/maven-aether-provider-3.2.3.jar", + "maven_model/maven-model-3.2.3.jar", + "maven_model/maven-model-builder-3.2.3.jar", + ], + ) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries to be linked in to the target. +See [java\_library.deps](/reference/be/java.html#java_library.deps). + `data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this rule at runtime. + `add_exports` + +List of strings; default is `[]` + + Allow this library to access the given `module` or `package`. + +This corresponds to the javac and JVM --add-exports= flags. + + +`add_opens` + +List of strings; default is `[]` + + Allow this library to reflectively access the given `module` or +`package`. + +This corresponds to the javac and JVM --add-opens= flags. + + +`constraints` + +List of strings; default is `[]` + + Extra constraints imposed on this rule as a Java library. + `exports` + +List of [labels](/concepts/labels); default is `[]` + + Targets to make available to users of this rule. +See [java\_library.exports](/reference/be/java.html#java_library.exports). + `jars` + +List of [labels](/concepts/labels); required + + The list of JAR files provided to Java targets that depend on this target. + `neverlink` + +Boolean; default is `False` + + Only use this library for compilation and not at runtime. +Useful if the library will be provided by the runtime environment +during execution. Examples of libraries like this are IDE APIs +for IDE plug-ins or `tools.jar` for anything running on +a standard JDK. + `proguard_specs` + +List of [labels](/concepts/labels); default is `[]` + + Files to be used as Proguard specification. +These will describe the set of specifications to be used by Proguard. If specified, +they will be added to any `android_binary` target depending on this library. + +The files included here must only have idempotent rules, namely -dontnote, -dontwarn, +assumenosideeffects, and rules that start with -keep. Other options can only appear in +`android_binary`'s proguard\_specs, to ensure non-tautological merges. + `runtime_deps` + +List of [labels](/concepts/labels); default is `[]` + + Libraries to make available to the final binary or test at runtime only. +See [java\_library.runtime\_deps](/reference/be/java.html#java_library.runtime_deps). + `srcjar` + +[Label](/concepts/labels); default is `None` + + A JAR file that contains source code for the compiled JAR files. + + +## java\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_library.bzl) + +``` +java_library(name, deps, srcs, data, resources, add_exports, add_opens, aspect_hints, bootclasspath, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exported_plugins, exports, features, javabuilder_jvm_flags, javacopts, licenses, neverlink, package_metadata, plugins, proguard_specs, resource_strip_prefix, restricted_to, runtime_deps, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +This rule compiles and links sources into a `.jar` file. + +#### Implicit outputs + +- `libname.jar`: A Java archive containing the class files. +- `libname-src.jar`: An archive containing the sources ("source + jar"). + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of libraries to link into this library. +See general comments about `deps` at +[Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + +The jars built by `java_library` rules listed in `deps` will be on +the compile-time classpath of this rule. Furthermore the transitive closure of their +`deps`, `runtime_deps` and `exports` will be on the +runtime classpath. + +By contrast, targets in the `data` attribute are included in the runfiles but +on neither the compile-time nor runtime classpath. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of source files that are processed to create the target. +This attribute is almost always required; see exceptions below. + +Source files of type `.java` are compiled. In case of generated +`.java` files it is generally advisable to put the generating rule's name +here instead of the name of the file itself. This not only improves readability but +makes the rule more resilient to future changes: if the generating rule generates +different files in the future, you only need to fix one place: the `outs` of +the generating rule. You should not list the generating rule in `deps` +because it is a no-op. + +Source files of type `.srcjar` are unpacked and compiled. (This is useful if +you need to generate a set of `.java` files with a genrule.) + +Rules: if the rule (typically `genrule` or `filegroup`) generates +any of the files listed above, they will be used the same way as described for source +files. + +Source files of type `.properties` are treated as resources. + +All other files are ignored, as long as there is at least one file of a +file type described above. Otherwise an error is raised. + +This argument is almost always required, except if you specify the `runtime_deps` argument. + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this library at runtime. +See general comments about `data` at +[Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + +When building a `java_library`, Bazel doesn't put these files anywhere; if the +`data` files are generated files then Bazel generates them. When building a +test that depends on this `java_library` Bazel copies or links the +`data` files into the runfiles area. + +`resources` + +List of [labels](/concepts/labels); default is `[]` + + A list of data files to include in a Java jar. + +Resources may be source files or generated files. + +If resources are specified, they will be bundled in the jar along with the usual +`.class` files produced by compilation. The location of the resources inside +of the jar file is determined by the project structure. Bazel first looks for Maven's +[standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html), +(a "src" directory followed by a "resources" directory grandchild). If that is not +found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for +example, if a resource is at `<workspace root>/x/java/y/java/z`, the +path of the resource will be `y/java/z`. This heuristic cannot be overridden, +however, the `resource_strip_prefix` attribute can be used to specify a +specific alternative directory for resource files. + + +`add_exports` + +List of strings; default is `[]` + + Allow this library to access the given `module` or `package`. + +This corresponds to the javac and JVM --add-exports= flags. + + +`add_opens` + +List of strings; default is `[]` + + Allow this library to reflectively access the given `module` or +`package`. + +This corresponds to the javac and JVM --add-opens= flags. + + +`bootclasspath` + +[Label](/concepts/labels); default is `None` + + Restricted API, do not use! + `exported_plugins` + +List of [labels](/concepts/labels); default is `[]` + + The list of `java_plugin` s (e.g. annotation +processors) to export to libraries that directly depend on this library. + +The specified list of `java_plugin` s will be applied to any library which +directly depends on this library, just as if that library had explicitly declared these +labels in `plugins`. + +`exports` + +List of [labels](/concepts/labels); default is `[]` + + Exported libraries. + +Listing rules here will make them available to parent rules, as if the parents explicitly +depended on these rules. This is not true for regular (non-exported) `deps`. + +Summary: a rule _X_ can access the code in _Y_ if there exists a dependency +path between them that begins with a `deps` edge followed by zero or more +`exports` edges. Let's see some examples to illustrate this. + +Assume _A_ depends on _B_ and _B_ depends on _C_. In this case +C is a _transitive_ dependency of A, so changing C's sources and rebuilding A will +correctly rebuild everything. However A will not be able to use classes in C. To allow +that, either A has to declare C in its `deps`, or B can make it easier for A +(and anything that may depend on A) by declaring C in its (B's) `exports` +attribute. + +The closure of exported libraries is available to all direct parent rules. Take a slightly +different example: A depends on B, B depends on C and D, and also exports C but not D. +Now A has access to C but not to D. Now, if C and D exported some libraries, C' and D' +respectively, A could only access C' but not D'. + +Important: an exported rule is not a regular dependency. Sticking to the previous example, +if B exports C and wants to also use C, it has to also list it in its own +`deps`. + +`javabuilder_jvm_flags` + +List of strings; default is `[]` + + Restricted API, do not use! + `javacopts` + +List of strings; default is `[]` + + Extra compiler options for this library. +Subject to ["Make variable"](make-variables.html) substitution and +[Bourne shell tokenization](common-definitions.html#sh-tokenization). + +These compiler options are passed to javac after the global compiler options. + +`neverlink` + +Boolean; default is `False` + + Whether this library should only be used for compilation and not at runtime. +Useful if the library will be provided by the runtime environment during execution. Examples +of such libraries are the IDE APIs for IDE plug-ins or `tools.jar` for anything +running on a standard JDK. + +Note that `neverlink = True` does not prevent the compiler from inlining material +from this library into compilation targets that depend on it, as permitted by the Java +Language Specification (e.g., `static final` constants of `String` +or of primitive types). The preferred use case is therefore when the runtime library is +identical to the compilation library. + +If the runtime library differs from the compilation library then you must ensure that it +differs only in places that the JLS forbids compilers to inline (and that must hold for +all future versions of the JLS). + +`plugins` + +List of [labels](/concepts/labels); default is `[]` + + Java compiler plugins to run at compile-time. +Every `java_plugin` specified in this attribute will be run whenever this rule +is built. A library may also inherit plugins from dependencies that use +`exported_plugins`. Resources +generated by the plugin will be included in the resulting jar of this rule. + `proguard_specs` + +List of [labels](/concepts/labels); default is `[]` + + Files to be used as Proguard specification. +These will describe the set of specifications to be used by Proguard. If specified, +they will be added to any `android_binary` target depending on this library. + +The files included here must only have idempotent rules, namely -dontnote, -dontwarn, +assumenosideeffects, and rules that start with -keep. Other options can only appear in +`android_binary`'s proguard\_specs, to ensure non-tautological merges. + `resource_strip_prefix` + +String; default is `""` + + The path prefix to strip from Java resources. + +If specified, this path prefix is stripped from every file in the `resources` +attribute. It is an error for a resource file not to be under this directory. If not +specified (the default), the path of resource file is determined according to the same +logic as the Java package of source files. For example, a source file at +`stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. + +`runtime_deps` + +List of [labels](/concepts/labels); default is `[]` + + Libraries to make available to the final binary or test at runtime only. +Like ordinary `deps`, these will appear on the runtime classpath, but unlike +them, not on the compile-time classpath. Dependencies needed only at runtime should be +listed here. Dependency-analysis tools should ignore targets that appear in both +`runtime_deps` and `deps`. + + +## java\_test + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_test.bzl) + +``` +java_test(name, deps, srcs, data, resources, add_exports, add_opens, args, aspect_hints, bootclasspath, classpath_resources, compatible_with, create_executable, deploy_manifest_lines, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, javacopts, jvm_flags, launcher, licenses, local, main_class, neverlink, package_metadata, plugins, resource_strip_prefix, restricted_to, runtime_deps, shard_count, size, stamp, tags, target_compatible_with, test_class, testonly, timeout, toolchains, use_launcher, use_testrunner, visibility) +``` + +A `java_test()` rule compiles a Java test. A test is a binary wrapper around your +test code. The test runner's main method is invoked instead of the main class being compiled. + +#### Implicit output targets + +- `name.jar`: A Java archive. +- `name_deploy.jar`: A Java archive suitable + for deployment. (Only built if explicitly requested.) See the description of the + `name_deploy.jar` output from + [java\_binary](#java_binary) for more details. + +See the section on `java_binary()` arguments. This rule also +supports all [attributes common\ +to all test rules (\*\_test)](https://bazel.build/reference/be/common-definitions#common-attributes-tests). + +#### Examples + +```lang-starlark + +java_library( + name = "tests", + srcs = glob(["*.java"]), + deps = [ + "//java/com/foo/base:testResources", + "//java/com/foo/testing/util", + ], +) + +java_test( + name = "AllTests", + size = "small", + runtime_deps = [ + ":tests", + "//util/mysql", + ], +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries to be linked in to the target. +See general comments about `deps` at +[Typical attributes defined by\ +most build rules](common-definitions.html#typical-attributes). + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of source files that are processed to create the target. +This attribute is almost always required; see exceptions below. + +Source files of type `.java` are compiled. In case of generated +`.java` files it is generally advisable to put the generating rule's name +here instead of the name of the file itself. This not only improves readability but +makes the rule more resilient to future changes: if the generating rule generates +different files in the future, you only need to fix one place: the `outs` of +the generating rule. You should not list the generating rule in `deps` +because it is a no-op. + +Source files of type `.srcjar` are unpacked and compiled. (This is useful if +you need to generate a set of `.java` files with a genrule.) + +Rules: if the rule (typically `genrule` or `filegroup`) generates +any of the files listed above, they will be used the same way as described for source +files. + +This argument is almost always required, except if a +[`main_class`](#java_binary.main_class) attribute specifies a +class on the runtime classpath or you specify the `runtime_deps` argument. + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this library at runtime. +See general comments about `data` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + `resources` + +List of [labels](/concepts/labels); default is `[]` + + A list of data files to include in a Java jar. + +Resources may be source files or generated files. + +If resources are specified, they will be bundled in the jar along with the usual +`.class` files produced by compilation. The location of the resources inside +of the jar file is determined by the project structure. Bazel first looks for Maven's +[standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html), +(a "src" directory followed by a "resources" directory grandchild). If that is not +found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for +example, if a resource is at `<workspace root>/x/java/y/java/z`, the +path of the resource will be `y/java/z`. This heuristic cannot be overridden, +however, the `resource_strip_prefix` attribute can be used to specify a +specific alternative directory for resource files. + + +`add_exports` + +List of strings; default is `[]` + + Allow this library to access the given `module` or `package`. + +This corresponds to the javac and JVM --add-exports= flags. + + +`add_opens` + +List of strings; default is `[]` + + Allow this library to reflectively access the given `module` or +`package`. + +This corresponds to the javac and JVM --add-opens= flags. + + +`bootclasspath` + +[Label](/concepts/labels); default is `None` + + Restricted API, do not use! + `classpath_resources` + +List of [labels](/concepts/labels); default is `[]` + + _DO NOT USE THIS OPTION UNLESS THERE IS NO OTHER WAY)_ + +A list of resources that must be located at the root of the java tree. This attribute's +only purpose is to support third-party libraries that require that their resources be +found on the classpath as exactly `"myconfig.xml"`. It is only allowed on +binaries and not libraries, due to the danger of namespace conflicts. + +`create_executable` + +Boolean; default is `True` + + Deprecated, use `java_single_jar` instead. + `deploy_manifest_lines` + +List of strings; default is `[]` + + A list of lines to add to the `META-INF/manifest.mf` file generated for the +`*_deploy.jar` target. The contents of this attribute are _not_ subject +to ["Make variable"](make-variables.html) substitution. + `javacopts` + +List of strings; default is `[]` + + Extra compiler options for this binary. +Subject to ["Make variable"](make-variables.html) substitution and +[Bourne shell tokenization](common-definitions.html#sh-tokenization). + +These compiler options are passed to javac after the global compiler options. + +`jvm_flags` + +List of strings; default is `[]` + + A list of flags to embed in the wrapper script generated for running this binary. +Subject to [$(location)](/reference/be/make-variables#location) and +["Make variable"](make-variables.html) substitution, and +[Bourne shell tokenization](common-definitions.html#sh-tokenization). + +The wrapper script for a Java binary includes a CLASSPATH definition +(to find all the dependent jars) and invokes the right Java interpreter. +The command line generated by the wrapper script includes the name of +the main class followed by a `"$@"` so you can pass along other +arguments after the classname. However, arguments intended for parsing +by the JVM must be specified _before_ the classname on the command +line. The contents of `jvm_flags` are added to the wrapper +script before the classname is listed. + +Note that this attribute has _no effect_ on `*_deploy.jar` +outputs. + +`launcher` + +[Label](/concepts/labels); default is `None` + + Specify a binary that will be used to run your Java program instead of the +normal `bin/java` program included with the JDK. +The target must be a `cc_binary`. Any `cc_binary` that +implements the +[Java Invocation API](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html) can be specified as a value for this attribute. + +By default, Bazel will use the normal JDK launcher (bin/java or java.exe). + +The related [`\ +--java_launcher`](/docs/user-manual#flag--java_launcher) Bazel flag affects only those +`java_binary` and `java_test` targets that have +_not_ specified a `launcher` attribute. + +Note that your native (C++, SWIG, JNI) dependencies will be built differently +depending on whether you are using the JDK launcher or another launcher: + +- If you are using the normal JDK launcher (the default), native dependencies are + built as a shared library named `{name}_nativedeps.so`, where + `{name}` is the `name` attribute of this java\_binary rule. + Unused code is _not_ removed by the linker in this configuration. +- If you are using any other launcher, native (C++) dependencies are statically + linked into a binary named `{name}_nativedeps`, where `{name}` + is the `name` attribute of this java\_binary rule. In this case, + the linker will remove any code it thinks is unused from the resulting binary, + which means any C++ code accessed only via JNI may not be linked in unless + that `cc_library` target specifies `alwayslink = True`. + +When using any launcher other than the default JDK launcher, the format +of the `*_deploy.jar` output changes. See the main +[java\_binary](#java_binary) docs for details. + +`main_class` + +String; default is `""` + + Name of class with `main()` method to use as entry point. +If a rule uses this option, it does not need a `srcs=[...]` list. +Thus, with this attribute one can make an executable from a Java library that already +contains one or more `main()` methods. + +The value of this attribute is a class name, not a source file. The class must be +available at runtime: it may be compiled by this rule (from `srcs`) or +provided by direct or transitive dependencies (through `runtime_deps` or +`deps`). If the class is unavailable, the binary will fail at runtime; there +is no build-time check. + +`neverlink` + +Boolean; default is `False` + +`plugins` + +List of [labels](/concepts/labels); default is `[]` + + Java compiler plugins to run at compile-time. +Every `java_plugin` specified in this attribute will be run whenever this rule +is built. A library may also inherit plugins from dependencies that use +`exported_plugins`. Resources +generated by the plugin will be included in the resulting jar of this rule. + `resource_strip_prefix` + +String; default is `""` + + The path prefix to strip from Java resources. + +If specified, this path prefix is stripped from every file in the `resources` +attribute. It is an error for a resource file not to be under this directory. If not +specified (the default), the path of resource file is determined according to the same +logic as the Java package of source files. For example, a source file at +`stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. + +`runtime_deps` + +List of [labels](/concepts/labels); default is `[]` + + Libraries to make available to the final binary or test at runtime only. +Like ordinary `deps`, these will appear on the runtime classpath, but unlike +them, not on the compile-time classpath. Dependencies needed only at runtime should be +listed here. Dependency-analysis tools should ignore targets that appear in both +`runtime_deps` and `deps`. + `stamp` + +Integer; default is `0` + + Whether to encode build information into the binary. Possible values: + +- `stamp = 1`: Always stamp the build information into the binary, even in + [`--nostamp`](https://bazel.build/docs/user-manual#stamp) builds. **This** + **setting should be avoided**, since it potentially kills remote caching for the + binary and any downstream actions that depend on it. + +- `stamp = 0`: Always replace build information by constant values. This + gives good build result caching. + +- `stamp = -1`: Embedding of build information is controlled by the + [`--[no]stamp`](https://bazel.build/docs/user-manual#stamp) flag. + + +Stamped binaries are _not_ rebuilt unless their dependencies change. + +`test_class` + +String; default is `""` + + The Java class to be loaded by the test runner. + +By default, if this argument is not defined then the legacy mode is used and the +test arguments are used instead. Set the `--nolegacy_bazel_java_test` flag +to not fallback on the first argument. + +This attribute specifies the name of a Java class to be run by +this test. It is rare to need to set this. If this argument is omitted, +it will be inferred using the target's `name` and its +source-root-relative path. If the test is located outside a known +source root, Bazel will report an error if `test_class` +is unset. + +For JUnit3, the test class needs to either be a subclass of +`junit.framework.TestCase` or it needs to have a public +static `suite()` method that returns a +`junit.framework.Test` (or a subclass of `Test`). + +This attribute allows several `java_test` rules to +share the same `Test` +( `TestCase`, `TestSuite`, ...). Typically +additional information is passed to it +(e.g. via `jvm_flags=['-Dkey=value']`) so that its +behavior differs in each case, such as running a different +subset of the tests. This attribute also enables the use of +Java tests outside the `javatests` tree. + +`use_launcher` + +Boolean; default is `True` + + Whether the binary should use a custom launcher. + +If this attribute is set to false, the +[launcher](/reference/be/java.html#java_binary.launcher) attribute and the related +[`--java_launcher`](/docs/user-manual#flag--java_launcher) flag +will be ignored for this target. + + +`use_testrunner` + +Boolean; default is `True` + + Use the test runner (by default +`com.google.testing.junit.runner.BazelTestRunner`) class as the +main entry point for a Java program, and provide the test class +to the test runner as a value of `bazel.test_suite` +system property. + +You can use this to override the default +behavior, which is to use test runner for +`java_test` rules, +and not use it for `java_binary` rules. It is unlikely +you will want to do this. One use is for `AllTest` +rules that are invoked by another rule (to set up a database +before running the tests, for example). The `AllTest` +rule must be declared as a `java_binary`, but should +still use the test runner as its main entry point. + +The name of a test runner class can be overridden with `main_class` attribute. + + +## java\_package\_configuration + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_package_configuration.bzl) + +``` +java_package_configuration(name, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, javacopts, output_licenses, package_metadata, packages, restricted_to, system, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Configuration to apply to a set of packages. +Configurations can be added to +`java_toolchain.javacopts` s. + +#### Example: + +```lang-starlark + +java_package_configuration( + name = "my_configuration", + packages = [":my_packages"], + javacopts = ["-Werror"], +) + +package_group( + name = "my_packages", + packages = [ + "//com/my/project/...", + "-//com/my/project/testing/...", + ], +) + +java_toolchain( + ..., + package_configuration = [ + ":my_configuration", + ] +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this configuration at runtime. + `javacopts` + +List of strings; default is `[]` + + Java compiler flags. + `output_licenses` + +List of strings; default is `[]` + +`packages` + +List of [labels](/concepts/labels); default is `[]` + + The set of `package_group` s +the configuration should be applied to. + `system` + +[Label](/concepts/labels); default is `None` + + Corresponds to javac's --system flag. + + +## java\_plugin + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/bazel/rules/bazel_java_plugin.bzl) + +``` +java_plugin(name, deps, srcs, data, resources, add_exports, add_opens, aspect_hints, bootclasspath, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, generates_api, javabuilder_jvm_flags, javacopts, licenses, neverlink, output_licenses, package_metadata, plugins, processor_class, proguard_specs, resource_strip_prefix, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`java_plugin` defines plugins for the Java compiler run by Bazel. The +only supported kind of plugins are annotation processors. A `java_library` or +`java_binary` rule can run plugins by depending on them via the `plugins` +attribute. A `java_library` can also automatically export plugins to libraries that +directly depend on it using +`exported_plugins`. + +#### Implicit output targets + +- `libname.jar`: A Java archive. + +Arguments are a subset of (and with identical semantics to) those of +[java\_library()](/reference/be/java.html#java_library), +except for the addition of the `processor_class` and +`generates_api` arguments. + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of libraries to link into this library. +See general comments about `deps` at +[Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + +The jars built by `java_library` rules listed in `deps` will be on +the compile-time classpath of this rule. Furthermore the transitive closure of their +`deps`, `runtime_deps` and `exports` will be on the +runtime classpath. + +By contrast, targets in the `data` attribute are included in the runfiles but +on neither the compile-time nor runtime classpath. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of source files that are processed to create the target. +This attribute is almost always required; see exceptions below. + +Source files of type `.java` are compiled. In case of generated +`.java` files it is generally advisable to put the generating rule's name +here instead of the name of the file itself. This not only improves readability but +makes the rule more resilient to future changes: if the generating rule generates +different files in the future, you only need to fix one place: the `outs` of +the generating rule. You should not list the generating rule in `deps` +because it is a no-op. + +Source files of type `.srcjar` are unpacked and compiled. (This is useful if +you need to generate a set of `.java` files with a genrule.) + +Rules: if the rule (typically `genrule` or `filegroup`) generates +any of the files listed above, they will be used the same way as described for source +files. + +Source files of type `.properties` are treated as resources. + +All other files are ignored, as long as there is at least one file of a +file type described above. Otherwise an error is raised. + +This argument is almost always required, except if you specify the `runtime_deps` argument. + +`data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files needed by this library at runtime. +See general comments about `data` at +[Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical-attributes). + +When building a `java_library`, Bazel doesn't put these files anywhere; if the +`data` files are generated files then Bazel generates them. When building a +test that depends on this `java_library` Bazel copies or links the +`data` files into the runfiles area. + +`resources` + +List of [labels](/concepts/labels); default is `[]` + + A list of data files to include in a Java jar. + +Resources may be source files or generated files. + +If resources are specified, they will be bundled in the jar along with the usual +`.class` files produced by compilation. The location of the resources inside +of the jar file is determined by the project structure. Bazel first looks for Maven's +[standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html), +(a "src" directory followed by a "resources" directory grandchild). If that is not +found, Bazel then looks for the topmost directory named "java" or "javatests" (so, for +example, if a resource is at `<workspace root>/x/java/y/java/z`, the +path of the resource will be `y/java/z`. This heuristic cannot be overridden, +however, the `resource_strip_prefix` attribute can be used to specify a +specific alternative directory for resource files. + + +`add_exports` + +List of strings; default is `[]` + + Allow this library to access the given `module` or `package`. + +This corresponds to the javac and JVM --add-exports= flags. + + +`add_opens` + +List of strings; default is `[]` + + Allow this library to reflectively access the given `module` or +`package`. + +This corresponds to the javac and JVM --add-opens= flags. + + +`bootclasspath` + +[Label](/concepts/labels); default is `None` + + Restricted API, do not use! + `generates_api` + +Boolean; default is `False` + + This attribute marks annotation processors that generate API code. + +If a rule uses an API-generating annotation processor, other rules +depending on it can refer to the generated code only if their +compilation actions are scheduled after the generating rule. This +attribute instructs Bazel to introduce scheduling constraints when +--java\_header\_compilation is enabled. + +_WARNING: This attribute affects build_ +_performance, use it only if necessary._ + +`javabuilder_jvm_flags` + +List of strings; default is `[]` + + Restricted API, do not use! + `javacopts` + +List of strings; default is `[]` + + Extra compiler options for this library. +Subject to ["Make variable"](make-variables.html) substitution and +[Bourne shell tokenization](common-definitions.html#sh-tokenization). + +These compiler options are passed to javac after the global compiler options. + +`neverlink` + +Boolean; default is `False` + + Whether this library should only be used for compilation and not at runtime. +Useful if the library will be provided by the runtime environment during execution. Examples +of such libraries are the IDE APIs for IDE plug-ins or `tools.jar` for anything +running on a standard JDK. + +Note that `neverlink = True` does not prevent the compiler from inlining material +from this library into compilation targets that depend on it, as permitted by the Java +Language Specification (e.g., `static final` constants of `String` +or of primitive types). The preferred use case is therefore when the runtime library is +identical to the compilation library. + +If the runtime library differs from the compilation library then you must ensure that it +differs only in places that the JLS forbids compilers to inline (and that must hold for +all future versions of the JLS). + +`output_licenses` + +List of strings; default is `[]` + +`plugins` + +List of [labels](/concepts/labels); default is `[]` + + Java compiler plugins to run at compile-time. +Every `java_plugin` specified in this attribute will be run whenever this rule +is built. A library may also inherit plugins from dependencies that use +`exported_plugins`. Resources +generated by the plugin will be included in the resulting jar of this rule. + `processor_class` + +String; default is `""` + + The processor class is the fully qualified type of the class that the Java compiler should +use as entry point to the annotation processor. If not specified, this rule will not +contribute an annotation processor to the Java compiler's annotation processing, but its +runtime classpath will still be included on the compiler's annotation processor path. (This +is primarily intended for use by +[Error Prone plugins](https://errorprone.info/docs/plugins), which are loaded +from the annotation processor path using +[java.util.ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html).) + `proguard_specs` + +List of [labels](/concepts/labels); default is `[]` + + Files to be used as Proguard specification. +These will describe the set of specifications to be used by Proguard. If specified, +they will be added to any `android_binary` target depending on this library. + +The files included here must only have idempotent rules, namely -dontnote, -dontwarn, +assumenosideeffects, and rules that start with -keep. Other options can only appear in +`android_binary`'s proguard\_specs, to ensure non-tautological merges. + `resource_strip_prefix` + +String; default is `""` + + The path prefix to strip from Java resources. + +If specified, this path prefix is stripped from every file in the `resources` +attribute. It is an error for a resource file not to be under this directory. If not +specified (the default), the path of resource file is determined according to the same +logic as the Java package of source files. For example, a source file at +`stuff/java/foo/bar/a.txt` will be located at `foo/bar/a.txt`. + +## java\_runtime + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_runtime.bzl) + +``` +java_runtime(name, srcs, aspect_hints, compatible_with, default_cds, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hermetic_srcs, hermetic_static_libs, java, java_home, lib_ct_sym, lib_modules, output_licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, version, visibility) +``` + +Specifies the configuration for a Java runtime. + +#### Example: + +```lang-starlark + +java_runtime( + name = "jdk-9-ea+153", + srcs = glob(["jdk9-ea+153/**"]), + java_home = "jdk9-ea+153", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + + All files in the runtime. + `default_cds` + +[Label](/concepts/labels); default is `None` + + Default CDS archive for hermetic `java_runtime`. When hermetic +is enabled for a `java_binary` target the `java_runtime` +default CDS is packaged in the hermetic deploy JAR. + `hermetic_srcs` + +List of [labels](/concepts/labels); default is `[]` + + Files in the runtime needed for hermetic deployments. + `hermetic_static_libs` + +List of [labels](/concepts/labels); default is `[]` + + The libraries that are statically linked with the launcher for hermetic deployments + `java` + +[Label](/concepts/labels); default is `None` + + The path to the java executable. + `java_home` + +String; default is `""` + + The path to the root of the runtime. +Subject to ["Make" variable](/reference/be/make-variables) substitution. +If this path is absolute, the rule denotes a non-hermetic Java runtime with a well-known +path. In that case, the `srcs` and `java` attributes must be empty. + `lib_ct_sym` + +[Label](/concepts/labels); default is `None` + + The lib/ct.sym file needed for compilation with `--release`. If not specified and +there is exactly one file in `srcs` whose path ends with +`/lib/ct.sym`, that file is used. + `lib_modules` + +[Label](/concepts/labels); default is `None` + + The lib/modules file needed for hermetic deployments. + `output_licenses` + +List of strings; default is `[]` + +`version` + +Integer; default is `0` + + The feature version of the Java runtime. I.e., the integer returned by +`Runtime.version().feature()`. + + +## java\_single\_jar + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/java_single_jar.bzl) + +``` +java_single_jar(name, deps, aspect_hints, compatible_with, compress, deploy_env, deploy_manifest_lines, deprecation, exclude_build_data, exec_compatible_with, exec_group_compatible_with, exec_properties, features, multi_release, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + + Collects Java dependencies and jar files into a single jar + +\`java\_single\_jar\` collects Java dependencies and jar files into a single jar. +This is similar to java\_binary with everything related to executables disabled, +and provides an alternative to the java\_binary "deploy jar hack". + +\## Example + +\`\`\`skylark +load("//tools/build\_defs/java\_single\_jar:java\_single\_jar.bzl", "java\_single\_jar") + +java\_single\_jar( + name = "my\_single\_jar", + deps = \[ + "//java/com/google/foo", + "//java/com/google/bar", + \], +) +\`\`\` + +Outputs: + {name}.jar: A single jar containing all of the inputs. + + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The Java targets (including java\_import and java\_library) to collect +transitive dependencies from. Runtime dependencies are collected via +deps, exports, and runtime\_deps. Resources are also collected. +Native cc\_library or java\_wrap\_cc dependencies are not. + `compress` + +String; default is `"preserve"` + + Whether to always deflate ("yes"), always store ("no"), or pass +through unmodified ("preserve"). The default is "preserve", and is the +most efficient option -- no extra work is done to inflate or deflate. + `deploy_env` + +List of [labels](/concepts/labels); default is `[]` + + A list of \`java\_binary\` or \`java\_single\_jar\` targets which represent +the deployment environment for this binary. + +Set this attribute when building a plugin which will be loaded by another +\`java\_binary\`. + +\`deploy\_env\` dependencies are excluded from the jar built by this rule. + `deploy_manifest_lines` + +List of strings; default is `[]` + + A list of lines to add to the `META-INF/manifest.mf` file. + `exclude_build_data` + +Boolean; default is `True` + + Whether to omit the build-data.properties file generated +by default. + `multi_release` + +Boolean; default is `True` + + Whether to enable Multi-Release output jars. + + +## java\_toolchain + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_java/blob/master/java/common/rules/java_toolchain.bzl) + +``` +java_toolchain(name, android_lint_data, android_lint_jvm_opts, android_lint_opts, android_lint_package_configuration, android_lint_runner, aspect_hints, bootclasspath, compatible_javacopts, compatible_with, deprecation, deps_checker, exec_compatible_with, exec_group_compatible_with, exec_properties, features, forcibly_disable_header_compilation, genclass, header_compiler, header_compiler_builtin_processors, header_compiler_direct, ijar, jacocorunner, java_runtime, javabuilder, javabuilder_data, javabuilder_jvm_opts, javac_supports_multiplex_workers, javac_supports_worker_cancellation, javac_supports_worker_multiplex_sandboxing, javac_supports_workers, javacopts, jspecify_implicit_deps, jspecify_javacopts, jspecify_packages, jspecify_processor, jspecify_processor_class, jspecify_stubs, jvm_opts, licenses, misc, oneversion, oneversion_allowlist, oneversion_allowlist_for_tests, oneversion_whitelist, package_configuration, package_metadata, proguard_allowlister, reduced_classpath_incompatible_processors, restricted_to, singlejar, source_version, tags, target_compatible_with, target_version, testonly, timezone_data, toolchains, tools, turbine_data, turbine_jvm_opts, visibility, xlint) +``` + +Specifies the configuration for the Java compiler. Which toolchain to be used can be changed through +the --java\_toolchain argument. Normally you should not write those kind of rules unless you want to +tune your Java compiler. + +#### Examples + +A simple example would be: + +```lang-starlark + +java_toolchain( + name = "toolchain", + source_version = "7", + target_version = "7", + bootclasspath = ["//tools/jdk:bootclasspath"], + xlint = [ "classfile", "divzero", "empty", "options", "path" ], + javacopts = [ "-g" ], + javabuilder = ":JavaBuilder_deploy.jar", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`android_lint_data` + +List of [labels](/concepts/labels); default is `[]` + + Labels of tools available for label-expansion in android\_lint\_jvm\_opts. + `android_lint_jvm_opts` + +List of strings; default is `[]` + + The list of arguments for the JVM when invoking Android Lint. + `android_lint_opts` + +List of strings; default is `[]` + + The list of Android Lint arguments. + `android_lint_package_configuration` + +List of [labels](/concepts/labels); default is `[]` + + Android Lint Configuration that should be applied to the specified package groups. + `android_lint_runner` + +[Label](/concepts/labels); default is `None` + + Label of the Android Lint runner, if any. + `bootclasspath` + +List of [labels](/concepts/labels); default is `[]` + + The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. + `compatible_javacopts` + +null; default is `{}` + + Internal API, do not use! + `deps_checker` + +[Label](/concepts/labels); default is `None` + + Label of the ImportDepsChecker deploy jar. + `forcibly_disable_header_compilation` + +Boolean; default is `False` + + Overrides --java\_header\_compilation to disable header compilation on platforms that do not +support it, e.g. JDK 7 Bazel. + `genclass` + +[Label](/concepts/labels); default is `None` + + Label of the GenClass deploy jar. + `header_compiler` + +[Label](/concepts/labels); default is `None` + + Label of the header compiler. Required if --java\_header\_compilation is enabled. + `header_compiler_builtin_processors` + +List of strings; default is `[]` + + Internal API, do not use! + `header_compiler_direct` + +[Label](/concepts/labels); default is `None` + + Optional label of the header compiler to use for direct classpath actions that do not +include any API-generating annotation processors. + +This tool does not support annotation processing. + + +`ijar` + +[Label](/concepts/labels); default is `None` + + Label of the ijar executable. + `jacocorunner` + +[Label](/concepts/labels); default is `None` + + Label of the JacocoCoverageRunner deploy jar. + `java_runtime` + +[Label](/concepts/labels); default is `None` + + The java\_runtime to use with this toolchain. It defaults to java\_runtime +in execution configuration. + `javabuilder` + +[Label](/concepts/labels); default is `None` + + Label of the JavaBuilder deploy jar. + `javabuilder_data` + +List of [labels](/concepts/labels); default is `[]` + + Labels of data available for label-expansion in javabuilder\_jvm\_opts. + `javabuilder_jvm_opts` + +List of strings; default is `[]` + + The list of arguments for the JVM when invoking JavaBuilder. + `javac_supports_multiplex_workers` + +Boolean; default is `True` + + True if JavaBuilder supports running as a multiplex persistent worker, false if it doesn't. + `javac_supports_worker_cancellation` + +Boolean; default is `True` + + True if JavaBuilder supports cancellation of persistent workers, false if it doesn't. + `javac_supports_worker_multiplex_sandboxing` + +Boolean; default is `False` + + True if JavaBuilder supports running as a multiplex persistent worker with sandboxing, false if it doesn't. + `javac_supports_workers` + +Boolean; default is `True` + + True if JavaBuilder supports running as a persistent worker, false if it doesn't. + `javacopts` + +List of strings; default is `[]` + + The list of extra arguments for the Java compiler. Please refer to the Java compiler +documentation for the extensive list of possible Java compiler flags. + `jspecify_implicit_deps` + +[Label](/concepts/labels); default is `None` + + Experimental, do not use! + `jspecify_javacopts` + +List of strings; default is `[]` + + Experimental, do not use! + `jspecify_packages` + +List of [labels](/concepts/labels); default is `[]` + + Experimental, do not use! + `jspecify_processor` + +[Label](/concepts/labels); default is `None` + + Experimental, do not use! + `jspecify_processor_class` + +String; default is `""` + + Experimental, do not use! + `jspecify_stubs` + +List of [labels](/concepts/labels); default is `[]` + + Experimental, do not use! + `jvm_opts` + +List of strings; default is `[]` + + The list of arguments for the JVM when invoking the Java compiler. Please refer to the Java +virtual machine documentation for the extensive list of possible flags for this option. + `misc` + +List of strings; default is `[]` + + Deprecated: use javacopts instead + `oneversion` + +[Label](/concepts/labels); default is `None` + + Label of the one-version enforcement binary. + `oneversion_allowlist` + +[Label](/concepts/labels); default is `None` + + Label of the one-version allowlist. + `oneversion_allowlist_for_tests` + +[Label](/concepts/labels); default is `None` + + Label of the one-version allowlist for tests. + `oneversion_whitelist` + +[Label](/concepts/labels); default is `None` + + Deprecated: use oneversion\_allowlist instead + `package_configuration` + +List of [labels](/concepts/labels); default is `[]` + + Configuration that should be applied to the specified package groups. + `proguard_allowlister` + +[Label](/concepts/labels); default is `"@bazel_tools//tools/jdk:proguard_whitelister"` + + Label of the Proguard allowlister. + `reduced_classpath_incompatible_processors` + +List of strings; default is `[]` + + Internal API, do not use! + `singlejar` + +[Label](/concepts/labels); default is `None` + + Label of the SingleJar deploy jar. + `source_version` + +String; default is `""` + + The Java source version (e.g., '6' or '7'). It specifies which set of code structures +are allowed in the Java source code. + `target_version` + +String; default is `""` + + The Java target version (e.g., '6' or '7'). It specifies for which Java runtime the class +should be build. + `timezone_data` + +[Label](/concepts/labels); default is `None` + + Label of a resource jar containing timezone data. If set, the timezone data is added as an +implicitly runtime dependency of all java\_binary rules. + `tools` + +List of [labels](/concepts/labels); default is `[]` + + Labels of tools available for label-expansion in jvm\_opts. + `turbine_data` + +List of [labels](/concepts/labels); default is `[]` + + Labels of data available for label-expansion in turbine\_jvm\_opts. + `turbine_jvm_opts` + +List of strings; default is `[]` + + The list of arguments for the JVM when invoking turbine. + `xlint` + +List of strings; default is `[]` + + The list of warning to add or removes from default list. Precedes it with a dash to +removes it. Please see the Javac documentation on the -Xlint options for more information. diff --git a/reference/be/make-variables.mdx b/reference/be/make-variables.mdx new file mode 100644 index 0000000..fbf91e9 --- /dev/null +++ b/reference/be/make-variables.mdx @@ -0,0 +1,393 @@ +--- +title: 'Make Variables' +--- + + + +- [Use](#use) +- [Predefined variables](#predefined_variables) +- [Predefined genrule variables](#predefined_genrule_variables) +- [Predefined source/output path variables](#predefined_label_variables) +- [Custom variables](#custom_variables) + +"Make" variables are a special class of expandable string variables available +to attributes marked as _"Subject to 'Make variable' substitution"_. + +These can be used, for example, to inject specific toolchain paths into +user-constructed build actions. + +Bazel provides both _predefined_ variables, which are available to all +targets, and _custom_ variables, which are defined in dependency targets +and only available to targets that depend on them. + +The reason for the term "Make" is historical: the syntax and semantics of +these variables were originally intended to match [GNU\ +Make](https://www.gnu.org/software/make/manual/html_node/Using-Variables.html). + +## Use + +Attributes marked as _"Subject to 'Make variable' substitution"_ can +reference the "Make" variable `FOO` as follows: + +`my_attr = "prefix $(FOO) suffix"` + +In other words, any substring matching `$(FOO)` gets expanded +to `FOO`'s value. If that value is `"bar"`, the final +string becomes: + +`my_attr = "prefix bar suffix"` + +If `FOO` doesn't correspond to a variable known to the consuming +target, Bazel fails with an error. + +"Make" variables whose names are non-letter symbols, such as +`@`, can also be referenced using only a dollar sign, without +the parentheses. For example: + +`my_attr = "prefix $@ suffix"` + +To write `$` as a string literal (i.e. to prevent variable +expansion), write `$$`. + +## Predefined variables + +Predefined "Make" variables can be referenced by any attribute marked as +_"Subject to 'Make variable' substitution"_ on any target. + +To see the list of these variables and their values for a given set of build +options, run + +`bazel info --show_make_env [build options]` + +and look at the top output lines with capital letters. + +[See an example of predefined variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-variables). + +**Toolchain option variables** + +- `COMPILATION_MODE`: + `fastbuild`, `dbg`, or `opt`. ( [more\ + details](https://bazel.build/docs/user-manual#flag--compilation_mode)) + + +**Path variables** + +- `BINDIR`: The base of the generated binary tree for the target + architecture. + + + + Note that a different tree may be used for programs that run during the + build on the host architecture, to support cross-compiling. + + + + If you want to run a tool from within a `genrule`, the + recommended way to get its path is `$(execpath toolname)`, + where _toolname_ must be listed in the `genrule`'s + `tools` attribute. + + +- `GENDIR`: + The base of the generated code tree for the target architecture. + + +**Machine architecture variables** + +- `TARGET_CPU`: + The target architecture's CPU, e.g. `k8`. + +## Predefined genrule variables + +The following are specially available to `genrule`'s +`cmd` attribute and are +generally important for making that attribute work. + +[See an example of predefined genrule variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-genrule-variables). + +- `OUTS`: The `genrule`'s `outs` list. If you have + only one output file, you can also use `$@`. +- `SRCS`: The `genrule`'s `srcs` list (or more + precisely: the path names of the files corresponding to labels in the + `srcs` list). + If you have only one source file, you can also use `$<`. + +- `<`: `SRCS`, if it is a single file. Else triggers + a build error. + +- `@`: `OUTS`, if it is a single file. Else triggers a + build error. + +- `RULEDIR`: The output directory of the target, that is, the + directory corresponding to the name of the package containing the target + under the `genfiles` or `bin` tree. For + `//my/pkg:my_genrule` this always ends in `my/pkg`, + even if `//my/pkg:my_genrule`'s outputs are in subdirectories. + + +- `@D`: The output directory. If + [outs](/reference/be/general.html#genrule.outs) has one entry, + this expands to the directory containing that file. If it has multiple + entries, this expands to the package's root directory in the + `genfiles` tree, _even if all output files are in the same_ + _subdirectory_! + + + **Note:** Use `RULEDIR` over `@D` because + `RULEDIR` has simpler semantics and behaves the same way + regardless of the number of output files. + + + + If the genrule needs to generate temporary intermediate files (perhaps as + a result of using some other tool like a compiler), it should attempt to + write them to `@D` (although `/tmp` will also + be writable) and remove them before finishing. + + + + Especially avoid writing to directories containing inputs. They may be on + read-only filesystems. Even if not, doing so would trash the source tree. + + + +**Note:** If the filenames corresponding to the input labels or the output +filenames contain spaces, `'`, or other special characters (or your +genrule is part of a Starlark macro which downstream users may invoke on such +files), then `$(SRCS)` and `$(OUTS)` are not suitable +for interpolation into a command line, as they do not have the semantics that +`"${@}"` would in Bash. + +One workaround is to convert to a Bash array, with + + +``` +mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion' +$(SRC) +genrule_srcs_expansion +) +``` + +and then use `"$$\{SRCS[@]}"` in subsequent command lines in place +of `$(SRCS)`. A more robust option is to write a Starlark rule +instead. + +## Predefined source/output path variables + +The predefined variables `execpath`, `execpaths`, +`rootpath`, `rootpaths`, `location`, and +`locations` take label parameters (e.g. `$(execpath +//foo:bar)`) and substitute the file paths denoted by that label. + +For source files, this is the path relative to your workspace root. +For files that are outputs of rules, this is the file's _output path_ +(see the explanation of _output files_ below). + +[See an example of predefined path variables](https://github.com/bazelbuild/examples/tree/main/make-variables#predefined-path-variables). + +- `execpath`: Denotes the path beneath the + + [execroot](/docs/output_directories) + where Bazel runs build actions. + + + + In the above example, Bazel runs all build actions in the directory linked + by the `bazel-myproject` symlink in your workspace root. The + source file `empty.source` is linked at the path + `bazel-myproject/testapp/empty.source`. So its exec path (which + is the subpath below the root) is `testapp/empty.source`. This + is the path build actions can use to find the file. + + + + Output files are staged similarly, but are also prefixed with the subpath + `bazel-out/cpu-compilation_mode/bin` (or for the outputs of + tools: `bazel-out/cpu-opt-exec-hash/bin`). In the above example, + `//testapp:app` is a tool because it appears in + `show_app_output`'s `tools` attribute. + So its output file `app` is written to + `bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app`. + The exec path is thus ` + bazel-out/cpu-opt-exec-hash/bin/testapp/app`. This extra prefix + makes it possible to build the same target for, say, two different CPUs in + the same build without the results clobbering each other. + + + + The label passed to this variable must represent exactly one file. For + labels representing source files, this is automatically true. For labels + representing rules, the rule must generate exactly one output. If this is + false or the label is malformed, the build fails with an error. + + +- `rootpath`: Denotes the path that a built binary can use to + find a dependency at runtime relative to the subdirectory of its runfiles + directory corresponding to the main repository. + **Note:** This only works if [`--enable_runfiles`](/reference/command-line-reference#flag--enable_runfiles) is enabled, which is not the case on + Windows by default. Use `rlocationpath` instead for + cross-platform support. + + + + This is similar to `execpath` but strips the configuration + prefixes described above. In the example from above this means both + `empty.source` and `app` use pure workspace-relative + paths: `testapp/empty.source` and `testapp/app`. + + + + The `rootpath` of a file in an external repository + `repo` will start with `../repo/`, followed by the + repository-relative path. + + + + This has the same "one output only" requirements as `execpath`. + + +- `rlocationpath`: The path a built binary can pass to the ` + Rlocation` function of a runfiles library to find a dependency at + runtime, either in the runfiles directory (if available) or using the + runfiles manifest. + + + + This is similar to `rootpath` in that it does not contain + configuration prefixes, but differs in that it always starts with the + name of the repository. In the example from above this means that ` + empty.source` and `app` result in the following + paths: `myproject/testapp/empty.source` and ` + myproject/testapp/app`. + + + + The `rlocationpath` of a file in an external repository + `repo` will start with `repo/`, followed by the + repository-relative path. + + + + Passing this path to a binary and resolving it to a file system path using + the runfiles libraries is the preferred approach to find dependencies at + runtime. Compared to `rootpath`, it has the advantage that it + works on all platforms and even if the runfiles directory is not + available. + + + + This has the same "one output only" requirements as `execpath`. + + +- `location`: A synonym for either `execpath` or + `rootpath`, depending on the attribute being expanded. This is + legacy pre-Starlark behavior and not recommended unless you really know what + it does for a particular rule. See [#2475](https://github.com/bazelbuild/bazel/issues/2475#issuecomment-339318016) + for details. + + +`execpaths`, `rootpaths`, `rlocationpaths`, +and `locations` are the plural variations of `execpath`, +`rootpath`, `rlocationpath`, and `location`, +respectively. They support labels producing multiple outputs, in which case +each output is listed separated by a space. Zero-output rules and malformed +labels produce build errors. + +All referenced labels must appear in the consuming target's `srcs`, +output files, or `deps`. Otherwise the build fails. C++ targets can +also reference labels in `data`. + +Labels don't have to be in canonical form: `foo`, `:foo` +and `//somepkg:foo` are all fine. + +## Custom variables + +Custom "Make" variables can be referenced by any attribute marked as +_"Subject to 'Make variable' substitution"_, but only on targets that +depend on other targets that _define_ these variables. + +As best practice all variables should be custom unless there's a really good +reason to bake them into core Bazel. This saves Bazel from having to load +potentially expensive dependencies to supply variables consuming tarets may +not care about. + +**C++ toolchain variables** + +The following are defined in C++ toolchain rules and available to any rule +that sets `toolchains = +["@bazel_tools//tools/cpp:toolchain_type"]` +Some rules, like `java_binary`, implicitly +include the C++ toolchain in their rule definition. They inherit these variables +automatically. + +The built-in C++ rules are much more sophisticated than "run the compiler on +it". In order to support compilation modes as diverse as \*SAN, ThinLTO, +with/without modules, and carefully optimized binaries at the same time as +fast running tests on multiple platforms, the built-in rules go to great +lengths to ensure the correct inputs, outputs, and command-line flags are set +on each of potentially multiple internally generated actions. + +These variables are a fallback mechanism to be used by language experts in +rare cases. If you are tempted to use them, please [contact the Bazel devs](https://bazel.build/help) first. + +- `ABI`: The C++ ABI version. +- `AR`: The "ar" command from crosstool. +- `C_COMPILER`: + The C/C++ compiler identifier, e.g. `llvm`. + +- `CC`: The C and C++ compiler command. + + + We strongly recommended always using `CC_FLAGS` in + combination with `CC`. Fail to do so at your own risk. + + +- `CC_FLAGS`: A minimal set of flags for the C/C++ + compiler to be usable by genrules. In particular, this contains flags to + select the correct architecture if `CC` supports multiple + architectures. + +- `DUMPBIN`: Microsoft COFF Binary File Dumper (dumpbin.exe) from + from Microsoft Visual Studio. +- `NM`: The "nm" command from crosstool. +- `OBJCOPY`: The objcopy command from the same suite as the C/C++ + compiler. +- `STRIP`: The strip command from the same suite as the C/C++ + compiler. + +**Java toolchain variables** + +The following are defined in Java toolchain rules and available to any rule +that sets `toolchains = +["@rules_java//toolchains:current_java_runtime"]` (or +`"@rules_java//toolchains:current_host_java_runtime"` +for the host toolchain equivalent). + +Most of the tools in the JDK should not be used directly. The built-in Java +rules use much more sophisticated approaches to Java compilation and packaging +than upstream tools can express, such as interface Jars, header interface +Jars, and highly optimized Jar packaging and merging implementations. + +These variables are a fallback mechanism to be used by language experts in +rare cases. If you are tempted to use them, please [contact the Bazel devs](https://bazel.build/help) first. + +- `JAVA`: The "java" command (a Java virtual + machine). Avoid this, and use a `java_binary` rule + instead where possible. May be a relative path. If you must change + directories before invoking `java`, you need to capture the + working directory before changing it. + +- `JAVABASE`: The base directory containing the + Java utilities. May be a relative path. It will have a "bin" + subdirectory. + + +**Starlark-defined variables** + +Rule and [toolchain](/docs/toolchains) writers can define +completely custom variables by returning a +[TemplateVariableInfo](/rules/lib/TemplateVariableInfo) +provider. Any rules depending on these through the +`toolchains` attribute can then read their values: + +[See an example of Starlark-defined variables](https://github.com/bazelbuild/examples/tree/main/make-variables#custom-starlark-defined-variables). diff --git a/reference/be/objective-c.mdx b/reference/be/objective-c.mdx new file mode 100644 index 0000000..c0e2037 --- /dev/null +++ b/reference/be/objective-c.mdx @@ -0,0 +1,384 @@ +--- +title: 'Objective-C Rules' +--- + + + +## Rules + +- [objc\_import](#objc_import) +- [objc\_library](#objc_library) + +## objc\_import + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_import.bzl) + +``` +objc_import(name, deps, hdrs, alwayslink, archives, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, includes, package_metadata, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) +``` + +This rule encapsulates an already-compiled static library in the form of an +`.a` file. It also allows exporting headers and resources using the same +attributes supported by `objc_library`. + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of targets that this target depend on. + `hdrs` + +List of [labels](/concepts/labels); default is `[]` + + The list of C, C++, Objective-C, and Objective-C++ header files published +by this library to be included by sources in dependent rules. + +These headers describe the public interface for the library and will be +made available for inclusion by sources in this rule or in dependent +rules. Headers not meant to be included by a client of this library +should be listed in the srcs attribute instead. + +These will be compiled separately from the source if modules are enabled. + + +`alwayslink` + +Boolean; default is `False` + + If 1, any bundle or binary that depends (directly or indirectly) on this +library will link in all the object files for the files listed in +`srcs` and `non_arc_srcs`, even if some contain no +symbols referenced by the binary. +This is useful if your code isn't explicitly called by code in +the binary, e.g., if your code registers to receive some callback +provided by some service. + `archives` + +List of [labels](/concepts/labels); required + + The list of `.a` files provided to Objective-C targets that +depend on this target. + `includes` + +List of strings; default is `[]` + + List of `#include/#import` search paths to add to this target +and all depending targets. + +This is to support third party and open-sourced libraries that do not +specify the entire workspace path in their +`#import/#include` statements. + +The paths are interpreted relative to the package directory, and the +genfiles and bin roots (e.g. `blaze-genfiles/pkg/includedir` +and `blaze-out/pkg/includedir`) are included in addition to the +actual client root. + +Unlike [COPTS](/reference/be/objective-c.html#objc_library.copts), these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-iquote" flags to [COPTS](/reference/be/objective-c.html#objc_library.copts) instead. + + +`sdk_dylibs` + +List of strings; default is `[]` + + Names of SDK .dylib libraries to link with. For instance, "libz" or +"libarchive". + +"libc++" is included automatically if the binary has any C++ or +Objective-C++ sources in its dependency tree. When linking a binary, +all libraries named in that binary's transitive dependency graph are +used. + `sdk_frameworks` + +List of strings; default is `[]` + + Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). + +When linking a top level Apple binary, all SDK frameworks listed in that binary's +transitive dependency graph are linked. + + +`sdk_includes` + +List of strings; default is `[]` + + List of `#include/#import` search paths to add to this target +and all depending targets, where each path is relative to +`$(SDKROOT)/usr/include`. + `textual_hdrs` + +List of [labels](/concepts/labels); default is `[]` + + The list of C, C++, Objective-C, and Objective-C++ files that are +included as headers by source files in this rule or by users of this +library. Unlike hdrs, these will not be compiled separately from the +sources. + `weak_sdk_frameworks` + +List of strings; default is `[]` + + Names of SDK frameworks to weakly link with. For instance, +"MediaAccessibility". + +In difference to regularly linked SDK frameworks, symbols +from weakly linked frameworks do not cause an error if they +are not present at runtime. + + +## objc\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_library.bzl) + +``` +objc_library(name, deps, srcs, data, hdrs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, enable_modules, exec_compatible_with, exec_group_compatible_with, exec_properties, features, implementation_deps, includes, linkopts, module_map, module_name, non_arc_srcs, package_metadata, pch, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, stamp, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) +``` + +This rule produces a static library from the given Objective-C source files. + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of targets that this target depend on. + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of C, C++, Objective-C, and Objective-C++ source and header +files, and/or (\`.s\`, \`.S\`, or \`.asm\`) assembly source files, that are processed to create +the library target. +These are your checked-in files, plus any generated files. +Source files are compiled into .o files with Clang. Header files +may be included/imported by any source or header in the srcs attribute +of this target, but not by headers in hdrs or any targets that depend +on this rule. +Additionally, precompiled .o files may be given as srcs. Be careful to +ensure consistency in the architecture of provided .o files and that of the +build to avoid missing symbol linker errors. + `hdrs` + +List of [labels](/concepts/labels); default is `[]` + + The list of C, C++, Objective-C, and Objective-C++ header files published +by this library to be included by sources in dependent rules. + +These headers describe the public interface for the library and will be +made available for inclusion by sources in this rule or in dependent +rules. Headers not meant to be included by a client of this library +should be listed in the srcs attribute instead. + +These will be compiled separately from the source if modules are enabled. + + +`alwayslink` + +Boolean; default is `False` + + If 1, any bundle or binary that depends (directly or indirectly) on this +library will link in all the object files for the files listed in +`srcs` and `non_arc_srcs`, even if some contain no +symbols referenced by the binary. +This is useful if your code isn't explicitly called by code in +the binary, e.g., if your code registers to receive some callback +provided by some service. + `conlyopts` + +List of strings; default is `[]` + + Extra flags to pass to the compiler for C files. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +These flags will only apply to this target, and not those upon which +it depends, or those which depend on it. + +Note that for the generated Xcode project, directory paths specified using "-I" flags in +copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and +added to the header search paths for the associated Xcode target. + + +`copts` + +List of strings; default is `[]` + + Extra flags to pass to the compiler. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +These flags will only apply to this target, and not those upon which +it depends, or those which depend on it. + +Note that for the generated Xcode project, directory paths specified using "-I" flags in +copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and +added to the header search paths for the associated Xcode target. + + +`cxxopts` + +List of strings; default is `[]` + + Extra flags to pass to the compiler for Objective-C++ and C++ files. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). +These flags will only apply to this target, and not those upon which +it depends, or those which depend on it. + +Note that for the generated Xcode project, directory paths specified using "-I" flags in +copts are parsed out, prepended with "$(WORKSPACE\_ROOT)/" if they are relative paths, and +added to the header search paths for the associated Xcode target. + + +`defines` + +List of strings; default is `[]` + + Extra `-D` flags to pass to the compiler. They should be in +the form `KEY=VALUE` or simply `KEY` and are +passed not only to the compiler for this target (as `copts` +are) but also to all `objc_` dependers of this target. +Subject to ["Make variable"](/reference/be/make-variables) substitution and +[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). + `enable_modules` + +Boolean; default is `False` + + Enables clang module support (via -fmodules). +Setting this to 1 will allow you to @import system headers and other targets: +@import UIKit; +@import path\_to\_package\_target; + `implementation_deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other libraries that the library target depends on. Unlike with +`deps`, the headers and include paths of these libraries (and all their +transitive deps) are only used for compilation of this library, and not libraries that +depend on it. Libraries specified with `implementation_deps` are still linked +in binary targets that depend on this library. + `includes` + +List of strings; default is `[]` + + List of `#include/#import` search paths to add to this target +and all depending targets. + +This is to support third party and open-sourced libraries that do not +specify the entire workspace path in their +`#import/#include` statements. + +The paths are interpreted relative to the package directory, and the +genfiles and bin roots (e.g. `blaze-genfiles/pkg/includedir` +and `blaze-out/pkg/includedir`) are included in addition to the +actual client root. + +Unlike [COPTS](/reference/be/objective-c.html#objc_library.copts), these flags are added for this rule +and every rule that depends on it. (Note: not the rules it depends upon!) Be +very careful, since this may have far-reaching effects. When in doubt, add +"-iquote" flags to [COPTS](/reference/be/objective-c.html#objc_library.copts) instead. + + +`linkopts` + +List of strings; default is `[]` + + Extra flags to pass to the linker. + `module_map` + +[Label](/concepts/labels); default is `None` + + custom Clang module map for this target. Use of a custom module map is discouraged. Most +users should use module maps generated by Bazel. +If specified, Bazel will not generate a module map for this target, but will pass the +provided module map to the compiler. + `module_name` + +String; default is `""` + + Sets the module name for this target. By default the module name is the target path with +all special symbols replaced by \_, e.g. //foo/baz:bar can be imported as foo\_baz\_bar. + `non_arc_srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of Objective-C files that are processed to create the +library target that DO NOT use ARC. +The files in this attribute are treated very similar to those in the +srcs attribute, but are compiled without ARC enabled. + `pch` + +[Label](/concepts/labels); default is `None` + + Header file to prepend to every source file being compiled (both arc +and non-arc). +Use of pch files is actively discouraged in BUILD files, and this should be +considered deprecated. Since pch files are not actually precompiled this is not +a build-speed enhancement, and instead is just a global dependency. From a build +efficiency point of view you are actually better including what you need directly +in your sources where you need it. + `sdk_dylibs` + +List of strings; default is `[]` + + Names of SDK .dylib libraries to link with. For instance, "libz" or +"libarchive". + +"libc++" is included automatically if the binary has any C++ or +Objective-C++ sources in its dependency tree. When linking a binary, +all libraries named in that binary's transitive dependency graph are +used. + `sdk_frameworks` + +List of strings; default is `[]` + + Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). + +When linking a top level Apple binary, all SDK frameworks listed in that binary's +transitive dependency graph are linked. + + +`sdk_includes` + +List of strings; default is `[]` + + List of `#include/#import` search paths to add to this target +and all depending targets, where each path is relative to +`$(SDKROOT)/usr/include`. + `stamp` + +Boolean; default is `False` + +`textual_hdrs` + +List of [labels](/concepts/labels); default is `[]` + + The list of C, C++, Objective-C, and Objective-C++ files that are +included as headers by source files in this rule or by users of this +library. Unlike hdrs, these will not be compiled separately from the +sources. + `weak_sdk_frameworks` + +List of strings; default is `[]` + + Names of SDK frameworks to weakly link with. For instance, +"MediaAccessibility". + +In difference to regularly linked SDK frameworks, symbols +from weakly linked frameworks do not cause an error if they +are not present at runtime. diff --git a/reference/be/overview.mdx b/reference/be/overview.mdx new file mode 100644 index 0000000..b57c03a --- /dev/null +++ b/reference/be/overview.mdx @@ -0,0 +1,134 @@ +--- +title: 'Bazel BUILD Encyclopedia of Functions' +--- + + + +## Concepts and terminology + +- [Common definitions](/reference/be/common-definitions) - [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization) + - [Label expansion](/reference/be/common-definitions#label-expansion) + - [Typical attributes for most rules](/reference/be/common-definitions#typical-attributes) + - [Common attributes for all rules](/reference/be/common-definitions#common-attributes) + - [Common attributes for tests](/reference/be/common-definitions#common-attributes-tests) + - [Common attributes for binaries](/reference/be/common-definitions#common-attributes-binaries) + - [Configurable attributes](/reference/be/common-definitions#configurable-attributes) + - [Implicit output targets](/reference/be/common-definitions#implicit-outputs) +- ["Make" variables](/reference/be/make-variables) - [Use](/reference/be/make-variables#use) + +## Functions + +- [package](/reference/be/functions.html#package) +- [package\_group](/reference/be/functions.html#package_group) +- [exports\_files](/reference/be/functions.html#exports_files) +- [glob](/reference/be/functions.html#glob) +- [select](/reference/be/functions.html#select) +- [workspace](/rules/lib/globals/workspace#workspace) + +## Rules + +Native rules ship with the Bazel binary and do not require a `load` statement. +Native rules are available globally in BUILD files. In .bzl files, you can find them in +the `native` module. + +For non-native Starlark rules that ship separately from Bazel, see the list of +[recommended rules](/rules/rules#recommended-rules). + +### Language-specific native rules + +LanguageFlagsBinary rulesLibrary rulesTest rulesOther rulesC / C++[cc\_binary](c-cpp.html#cc_binary) + +[cc\_import](c-cpp.html#cc_import) + +[cc\_library](c-cpp.html#cc_library) + +[cc\_shared\_library](c-cpp.html#cc_shared_library) + +[cc\_static\_library](c-cpp.html#cc_static_library) + +[cc\_test](c-cpp.html#cc_test) + +[cc\_toolchain](c-cpp.html#cc_toolchain) + +[fdo\_prefetch\_hints](c-cpp.html#fdo_prefetch_hints) + +[fdo\_profile](c-cpp.html#fdo_profile) + +[memprof\_profile](c-cpp.html#memprof_profile) + +[propeller\_optimize](c-cpp.html#propeller_optimize) + +Java[java\_binary](java.html#java_binary) + +[java\_import](java.html#java_import) + +[java\_library](java.html#java_library) + +[java\_test](java.html#java_test) + +[java\_package\_configuration](java.html#java_package_configuration) + +[java\_plugin](java.html#java_plugin) + +[java\_runtime](java.html#java_runtime) + +[java\_single\_jar](java.html#java_single_jar) + +[java\_toolchain](java.html#java_toolchain) + +Objective-C[objc\_import](objective-c.html#objc_import) + +[objc\_library](objective-c.html#objc_library) + +Protocol Buffer[cc\_proto\_library](protocol-buffer.html#cc_proto_library) + +[java\_lite\_proto\_library](protocol-buffer.html#java_lite_proto_library) + +[java\_proto\_library](protocol-buffer.html#java_proto_library) + +[proto\_library](protocol-buffer.html#proto_library) + +[py\_proto\_library](protocol-buffer.html#py_proto_library) + +[proto\_lang\_toolchain](protocol-buffer.html#proto_lang_toolchain) + +[proto\_toolchain](protocol-buffer.html#proto_toolchain) + +Python[py\_binary](python.html#py_binary) + +[py\_library](python.html#py_library) + +[py\_test](python.html#py_test) + +[py\_runtime](python.html#py_runtime) + +Shell[sh\_binary](shell.html#sh_binary) + +[sh\_library](shell.html#sh_library) + +[sh\_test](shell.html#sh_test) + +### Language-agnostic native rules + +FamilyRulesExtra Actions + +- [action\_listener](extra-actions.html#action_listener) +- [extra\_action](extra-actions.html#extra_action) + +General + +- [alias](general.html#alias) +- [config\_setting](general.html#config_setting) +- [filegroup](general.html#filegroup) +- [genquery](general.html#genquery) +- [genrule](general.html#genrule) +- [starlark\_doc\_extract](general.html#starlark_doc_extract) +- [test\_suite](general.html#test_suite) + +Platforms and Toolchains + +- [constraint\_setting](platforms-and-toolchains.html#constraint_setting) +- [constraint\_value](platforms-and-toolchains.html#constraint_value) +- [platform](platforms-and-toolchains.html#platform) +- [toolchain](platforms-and-toolchains.html#toolchain) +- [toolchain\_type](platforms-and-toolchains.html#toolchain_type) diff --git a/reference/be/platforms-and-toolchains.mdx b/reference/be/platforms-and-toolchains.mdx new file mode 100644 index 0000000..1844b00 --- /dev/null +++ b/reference/be/platforms-and-toolchains.mdx @@ -0,0 +1,544 @@ +--- +title: 'Platforms and Toolchains Rules' +--- + + + +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 [here](/extending/platforms). + +## Rules + +- [constraint\_setting](#constraint_setting) +- [constraint\_value](#constraint_value) +- [platform](#platform) +- [toolchain](#toolchain) +- [toolchain\_type](#toolchain_type) + +## constraint\_setting + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintSettingRule.java) + +``` +constraint_setting(name, aspect_hints, default_constraint_value, deprecation, features, licenses, tags, testonly, visibility) +``` + +This rule is used to introduce a new constraint type for which a platform may specify a value. +For instance, you might define a `constraint_setting` named "glibc\_version" to represent +the capability for platforms to have different versions of the glibc library installed. + +For more details, see the +[Platforms](https://bazel.build/docs/platforms) page. + +Each `constraint_setting` has an extensible set of associated +`constraint_value` 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 `@platforms//cpu:cpu` can be extended with a custom value in order to +define a platform targeting an obscure cpu architecture. + + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`default_constraint_value` + +[Name](/concepts/labels#target-names); [nonconfigurable](common-definitions.html#configurable-attributes); default is `None` + + The label of the default value for this setting, to be used if no value is given. If this + attribute is present, the `constraint_value` it points to must be defined in the + same package as this `constraint_setting`. + + + +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 `config_setting`) that requires a particular value +for that setting. + + + +## constraint\_value + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintValueRule.java) + +``` +constraint_value(name, aspect_hints, constraint_setting, deprecation, features, licenses, tags, testonly, visibility) +``` + +This rule introduces a new value for a given constraint type. + +For more details, see the +[Platforms](https://bazel.build/docs/platforms) page. + +#### Example + +The following creates a new possible value for the predefined `constraint_value` +representing cpu architecture. + +``` +constraint_value( + name = "mips", + constraint_setting = "@platforms//cpu:cpu", +) + +``` + +Platforms can then declare that they have the `mips` architecture as an alternative to +`x86_64`, `arm`, and so on. + + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`constraint_setting` + +[Label](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); required + + The `constraint_setting` for which this `constraint_value` is a + possible choice. + + + +## platform + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformRule.java) + +``` +platform(name, aspect_hints, constraint_values, deprecation, exec_properties, features, flags, licenses, missing_toolchain_error, parents, remote_execution_properties, required_settings, tags, testonly, visibility) +``` + +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 [Platforms](/extending/platforms) page. + +#### Example + +This defines a platform that describes any environment running Linux on ARM. + +``` +platform( + name = "linux_arm", + constraint_values = [ + "@platforms//os:linux", + "@platforms//cpu:arm", + ], +) + +``` + +### Platform Flags + +Platforms may use the `flags` attribute to specify a list of flags that will be added +to the configuration whenever the platform is used as the target platform (i.e., as the value of +the `--platforms` flag). + +Flags set from the platform effectively have the highest precedence and overwrite any previous +value for that flag, from the command line, rc file, or transition. + +#### Example + +``` +platform( + name = "foo", + flags = [ + "--dynamic_mode=fully", + "--//bool_flag", + "--no//package:other_bool_flag", + ], +) + +``` + +This defines a platform named `foo`. When this is the target platform (either because +the user specified `--platforms//:foo`, because a transition set the +`//command_line_option:platforms` flag to `["//:foo"]`, or because +`//:foo` was used as an execution platform), then the given flags will be set in the +configuration. + +#### Platforms and Repeatable Flags + +Some flags will accumulate values when they are repeated, such as `--features`, +`--copt`, any Starlark flag created as `config.string(repeatable = True)`. +These flags are not compatible with setting the flags from the platform: instead, all previous +values will be removed and overwritten with the values from the platform. + +As an example, given the following platform, the invocation `build --platforms=//:repeat_demo + --features feature_a --features feature_b` will end up with the value of the +`--feature` flag being `["feature_c", "feature_d"]`, removing the features +set on the command line. + +``` +platform( + name = "repeat_demo", + flags = [ + "--features=feature_c", + "--features=feature_d", + ], +) + +``` + +For this reason, it is discouraged to use repeatable flags in the `flags` attribute. + +### Platform Inheritance + +Platforms may use the `parents` attribute to specify another platform that they will +inherit constraint values from. Although the `parents` attribute takes a list, no +more than a single value is currently supported, and specifying multiple parents is an error. + +When checking for the value of a constraint setting in a platform, first the values directly set +(via the `constraint_values` 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. + +Platforms inherit the `exec_properties` attribute from the parent platform. +The dictionary entries in `exec_properties` of the parent and child platforms +will be combined. +If the same key appears in both the parent's and the child's `exec_properties`, +the child's value will be used. If the child platform specifies an empty string as a value, the +corresponding property will be unset. + +Platforms can also inherit the (deprecated) `remote_execution_properties` attribute +from the parent platform. Note: new code should use `exec_properties` 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 `remote_execution_platform` is as follows when there +is a parent platform: + + + +1. If `remote_execution_property` is not set on the child platform, the parent's + `remote_execution_properties` will be used. + +2. If `remote_execution_property` is set on the child platform, and contains the + literal string {PARENT\_REMOTE\_EXECUTION\_PROPERTIES}, that macro will be + replaced with the contents of the parent's `remote_execution_property` attribute. + +3. If `remote_execution_property` is set on the child platform, and does not contain + the macro, the child's `remote_execution_property` will be used unchanged. + + +_Since `remote_execution_properties` is deprecated and will be phased out, mixing_ +_`remote_execution_properties` and `exec_properties` in the same_ +_inheritance chain is not allowed._ +Prefer to use `exec_properties` over the deprecated +`remote_execution_properties`. + +#### Example: Constraint Values + +``` +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"], +) + +``` + +In this example, the child platforms have the following properties: + + + +- `child_a` has the constraint values `@platforms//os:linux` (inherited + from the parent) and `@platforms//cpu:x86_64` (set directly on the platform). + +- `child_b` inherits all constraint values from the parent, and doesn't set any of + its own. + + +#### Example: Execution properties + +``` +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" + } +) + +``` + +In this example, the child platforms have the following properties: + + + +- `child_a` inherits the "exec\_properties" of the parent and does not set its own. + +- `child_b` inherits the parent's `exec_properties` and overrides the + value of `k1`. Its `exec_properties` will be: + `{ "k1": "child", "k2": "v2" }`. + +- `child_c` inherits the parent's `exec_properties` and unsets + `k1`. Its `exec_properties` will be: + `{ "k2": "v2" }`. + +- `child_d` inherits the parent's `exec_properties` and adds a new + property. Its `exec_properties` will be: + `{ "k1": "v1", "k2": "v2", "k3": "v3" }`. + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`constraint_values` + +List of [labels](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + + 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. + + + +Each `constraint_value` in this list must be for a different +`constraint_setting`. For example, you cannot define a platform that requires the +cpu architecture to be both `@platforms//cpu:x86_64` and +`@platforms//cpu:arm`. + + + +`exec_properties` + +Dictionary: String -> String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `{}` + + 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 [remote execution protocol](https://github.com/bazelbuild/remote-apis). + + This includes any data from the parent platform's `exec_properties` 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 + `remote_execution_properties`. + + `flags` + +List of strings; [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + + A list of flags that will be enabled when this platform is used as the target platform in + a configuration. Only flags that are part of the configuration can be set, such as those + that can be used in transitions, or the `--define` flag. + + `missing_toolchain_error` + +String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `"For more information on platforms or toolchains see https://bazel.build/concepts/platforms-intro."` + + A custom error message that is displayed when a mandatory toolchain requirement cannot be satisfied for this target platform. Intended to point to relevant documentation users can read to understand why their toolchains are misconfigured. + + Not inherited from parent platforms. + + `parents` + +List of [labels](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + + The label of a `platform` 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 [Platform Inheritance](#platform_inheritance) for details. + + `remote_execution_properties` + +String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `""` + + 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 + [Platform Inheritance](#platform_inheritance) for details. + + `required_settings` + +List of [labels](/concepts/labels); default is `[]` + + A list of `config_setting` s that must be satisfied by the target configuration + in order for this platform to be used as an execution platform during toolchain resolution. + + Required settings are not inherited from parent platforms. + + + +## toolchain + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ToolchainRule.java) + +``` +toolchain(name, aspect_hints, deprecation, exec_compatible_with, features, licenses, package_metadata, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, use_target_platform_constraints, visibility) +``` + +This rule declares a specific toolchain's type and constraints so that it can be selected +during toolchain resolution. See the +[Toolchains](https://bazel.build/docs/toolchains) page for more +details. + + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`exec_compatible_with` + +List of [labels](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + + A list of `constraint_value` s that must be satisfied by an execution platform in + order for this toolchain to be selected for a target building on that platform. + + `target_compatible_with` + +List of [labels](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); default is `[]` + + A list of `constraint_value` s that must be satisfied by the target platform in + order for this toolchain to be selected for a target building for that platform. + + `target_settings` + +List of [labels](/concepts/labels); default is `[]` + + A list of `config_setting` s that must be satisfied by the target configuration + in order for this toolchain to be selected during toolchain resolution. + + `toolchain` + +[Name](/concepts/labels#target-names); required + + The target representing the actual tool or tool suite that is made available when this + toolchain is selected. + + `toolchain_type` + +[Label](/concepts/labels); [nonconfigurable](common-definitions.html#configurable-attributes); required + + The label of a `toolchain_type` target that represents the role that this + toolchain serves. + + `use_target_platform_constraints` + +Boolean; [nonconfigurable](common-definitions.html#configurable-attributes); default is `False` + + If `True`, this toolchain behaves as if its `exec_compatible_with` and + `target_compatible_with` constraints are set to those of the current target + platform. `exec_compatible_with` and `target_compatible_with` must not + be set in that case. + + + +## toolchain\_type + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/ToolchainType.java) + +``` +toolchain_type(name, aspect_hints, compatible_with, deprecation, features, no_match_error, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility) +``` + +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. + +See the [Toolchains](/docs/toolchains) page for more details. + +#### Example + +This defines a toolchain type for a custom rule. + +``` +toolchain_type( + name = "bar_toolchain_type", +) + +``` + +This can be used in a bzl file. + +``` +bar_binary = rule( + implementation = _bar_binary_impl, + attrs = { + "srcs": attr.label_list(allow_files = True), + ... + # No `_compiler` attribute anymore. + }, + toolchains = ["//bar_tools:toolchain_type"] +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`no_match_error` + +String; [nonconfigurable](common-definitions.html#configurable-attributes); default is `""` + + A custom error message to display when no matching toolchain is found for this type. diff --git a/reference/be/protocol-buffer.mdx b/reference/be/protocol-buffer.mdx new file mode 100644 index 0000000..61bb4f1 --- /dev/null +++ b/reference/be/protocol-buffer.mdx @@ -0,0 +1,484 @@ +--- +title: 'Protocol Buffer Rules' +--- + + + +## Rules + +- [cc\_proto\_library](#cc_proto_library) +- [java\_lite\_proto\_library](#java_lite_proto_library) +- [java\_proto\_library](#java_proto_library) +- [proto\_library](#proto_library) +- [py\_proto\_library](#py_proto_library) +- [proto\_lang\_toolchain](#proto_lang_toolchain) +- [proto\_toolchain](#proto_toolchain) + +## cc\_proto\_library + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_cc_proto_library.bzl) + +``` +cc_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`cc_proto_library` generates C++ code from `.proto` files. + +`deps` must point to [`proto_library\ +`](protocol-buffer.html#proto_library) rules. + +Example: + +```lang-starlark + +cc_library( + name = "lib", + deps = [":foo_cc_proto"], +) + +cc_proto_library( + name = "foo_cc_proto", + deps = [":foo_proto"], +) + +proto_library( + name = "foo_proto", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of [`proto_library`](protocol-buffer.html#proto_library) +rules to generate C++ code for. + + +## java\_lite\_proto\_library + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/java_lite_proto_library.bzl) + +``` +java_lite_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`java_lite_proto_library` generates Java code from `.proto` files. + +`deps` must point to [`proto_library\ +`](protocol-buffer.html#proto_library) rules. + +Example: + +```lang-starlark + +java_library( + name = "lib", + runtime_deps = [":foo"], +) + +java_lite_proto_library( + name = "foo", + deps = [":bar"], +) + +proto_library( + name = "bar", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of [`proto_library`](protocol-buffer.html#proto_library) +rules to generate Java code for. + + +## java\_proto\_library + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/bazel_java_proto_library_rule.bzl) + +``` +java_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +`java_proto_library` generates Java code from `.proto` files. + +`deps` must point to [`proto_library\ +`](protocol-buffer.html#proto_library) rules. + +Example: + +```lang-starlark + +java_library( + name = "lib", + runtime_deps = [":foo_java_proto"], +) + +java_proto_library( + name = "foo_java_proto", + deps = [":foo_proto"], +) + +proto_library( + name = "foo_proto", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of [`proto_library`](protocol-buffer.html#proto_library) +rules to generate Java code for. + + +## proto\_library + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_library_rule.bzl) + +``` +proto_library(name, deps, srcs, data, allow_exports, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, exports, features, import_prefix, licenses, option_deps, package_metadata, restricted_to, strip_import_prefix, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +Use `proto_library` to define libraries of protocol buffers which +may be used from multiple languages. A `proto_library` may be listed +in the `deps` clause of supported rules, such as +`java_proto_library`. + +When compiled on the command-line, a `proto_library` creates a file +named `foo-descriptor-set.proto.bin`, which is the descriptor set for +the messages the rule srcs. The file is a serialized +`FileDescriptorSet`, which is described in +[https://developers.google.com/protocol-buffers/docs/techniques#self-description](https://developers.google.com/protocol-buffers/docs/techniques#self-description). + +It only contains information about the `.proto` files directly +mentioned by a `proto_library` rule; the collection of transitive +descriptor sets is available through the +`[ProtoInfo].transitive_descriptor_sets` Starlark provider. +See documentation in `proto_info.bzl`. + +Recommended code organization: + +- One `proto_library` rule per `.proto` file. + +- A file named `foo.proto` will be in a rule named `foo_proto`, + which is located in the same package. + +- A `[language]_proto_library` that wraps a `proto_library` + named `foo_proto` should be called `foo_[language]_proto`, + and be located in the same package. + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other `proto_library` rules that the target depends upon. +A `proto_library` may only depend on other `proto_library` +targets. It may not depend on language-specific libraries. + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of `.proto` and `.protodevel` files that are +processed to create the target. This is usually a non empty list. One usecase +where `srcs` can be empty is an _alias-library_. This is a +proto\_library rule having one or more other proto\_library in `deps`. +This pattern can be used to e.g. export a public api under a persistent name. + `allow_exports` + +[Label](/concepts/labels); default is `None` + + An optional allowlist that prevents proto library to be reexported or used in +lang\_proto\_library that is not in one of the listed packages. + `exports` + +List of [labels](/concepts/labels); default is `[]` + + List of proto\_library targets that can be referenced via "import public" in the +proto source. +It's an error if you use "import public" but do not list the corresponding library +in the exports attribute. +Note that you have list the library both in deps and exports since not all +lang\_proto\_library implementations have been changed yet. + `import_prefix` + +String; default is `""` + + The prefix to add to the paths of the .proto files in this rule. + +When set, the .proto source files in the `srcs` attribute of this rule are +accessible at is the value of this attribute prepended to their repository-relative path. + +The prefix in the `strip_import_prefix` attribute is removed before this +prefix is added. + + +`option_deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of other `proto_library` rules that the target depends upon for options only. +A `proto_library` may only depend on other `proto_library` +targets. It may not depend on language-specific libraries. + `strip_import_prefix` + +String; default is `"/"` + + The prefix to strip from the paths of the .proto files in this rule. + +When set, .proto source files in the `srcs` attribute of this rule are +accessible at their path with this prefix cut off. + +If it's a relative path (not starting with a slash), it's taken as a package-relative +one. If it's an absolute one, it's understood as a repository-relative path. + +The prefix in the `import_prefix` attribute is added after this prefix is +stripped. + + +## py\_proto\_library + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/py_proto_library.bzl) + +``` +py_proto_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + + Use \`py\_proto\_library\` to generate Python libraries from \`.proto\` files. + + The convention is to name the \`py\_proto\_library\` rule \`foo\_py\_pb2\`, + when it is wrapping \`proto\_library\` rule \`foo\_proto\`. + + \`deps\` must point to a \`proto\_library\` rule. + + Example: + +\`\`\`starlark +py\_library( + name = "lib", + deps = \[":foo\_py\_pb2"\], +) + +py\_proto\_library( + name = "foo\_py\_pb2", + deps = \[":foo\_proto"\], +) + +proto\_library( + name = "foo\_proto", + srcs = \["foo.proto"\], +) +\`\`\` + + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of \`proto\_library\` rules to generate Python libraries for. + +Usually this is just the one target: the proto library of interest. +It can be any target providing \`ProtoInfo\`. + + +## proto\_lang\_toolchain + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_lang_toolchain_rule.bzl) + +``` +proto_lang_toolchain(name, allowlist_different_package, aspect_hints, blacklisted_protos, command_line, compatible_with, denylisted_protos, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, mnemonic, output_files, package_metadata, plugin, plugin_format_flag, progress_message, protoc_minimal_do_not_use, restricted_to, runtime, tags, target_compatible_with, testonly, toolchain_type, toolchains, visibility) +``` + +If using Bazel, please load the rule from [https://github.com/bazelbuild/rules\_proto](https://github.com/bazelbuild/rules_proto). + +Specifies how a LANG\_proto\_library rule (e.g., `java_proto_library`) should invoke the +proto-compiler. +Some LANG\_proto\_library rules allow specifying which toolchain to use using command-line flags; +consult their documentation. + +Normally you should not write those kind of rules unless you want to +tune your Java compiler. + +There's no compiler. The proto-compiler is taken from the proto\_library rule we attach to. It is +passed as a command-line flag to Blaze. +Several features require a proto-compiler to be invoked on the proto\_library rule itself. +It's beneficial to enforce the compiler that LANG\_proto\_library uses is the same as the one +`proto_library` does. + +#### Examples + +A simple example would be: + +```lang-starlark + +proto_lang_toolchain( + name = "javalite_toolchain", + command_line = "--javalite_out=shared,immutable:$(OUT)", + plugin = ":javalite_plugin", + runtime = ":protobuf_lite", +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`allowlist_different_package` + +[Label](/concepts/labels); default is `None` + +`blacklisted_protos` + +List of [labels](/concepts/labels); default is `[]` + + Deprecated. Alias for `denylisted_protos`. Will be removed in a future release. + `command_line` + +String; required + + This value will be passed to proto-compiler to generate the code. Only include the parts +specific to this code-generator/plugin (e.g., do not include -I parameters) + +- `$(OUT)` is LANG\_proto\_library-specific. The rules are expected to define + how they interpret this variable. For Java, for example, $(OUT) will be replaced with + the src-jar filename to create. + +`denylisted_protos` + +List of [labels](/concepts/labels); default is `[]` + + No code will be generated for files in the `srcs` attribute of +`denylisted_protos`. +This is used for .proto files that are already linked into proto runtimes, such as +`any.proto`. + `mnemonic` + +String; default is `"GenProto"` + + This value will be set as the mnemonic on protoc action. + `output_files` + +String; default is `"legacy"` + + Controls how `$(OUT)` in `command_line` is formatted, either by +a path to a single file or output directory in case of multiple files. +Possible values are: "single", "multiple". + `plugin` + +[Label](/concepts/labels); default is `None` + + If provided, will be made available to the action that calls the proto-compiler, and will be +passed to the proto-compiler: +`--plugin=protoc-gen-PLUGIN=<executable>.``plugin_format_flag` + +String; default is `""` + + If provided, this value will be passed to proto-compiler to use the plugin. +The value must contain a single %s which is replaced with plugin executable. +`--plugin=protoc-gen-PLUGIN=<executable>.``progress_message` + +String; default is `"Generating proto_library %{label}"` + + This value will be set as the progress message on protoc action. + `protoc_minimal_do_not_use` + +[Label](/concepts/labels); default is `None` + +`runtime` + +[Label](/concepts/labels); default is `None` + + A language-specific library that the generated code is compiled against. +The exact behavior is LANG\_proto\_library-specific. +Java, for example, should compile against the runtime. + `toolchain_type` + +[Label](/concepts/labels); default is `None` + +## proto\_toolchain + +[View rule sourceopen\_in\_new](https://github.com/protocolbuffers/protobuf/tree/v29.0-rc2/bazel/private/proto_toolchain_rule.bzl) + +``` +proto_toolchain(name, aspect_hints, command_line, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, mnemonic, output_files, package_metadata, progress_message, proto_compiler, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`command_line` + +String; default is `"--descriptor_set_out=%s"` + +`mnemonic` + +String; default is `"GenProtoDescriptorSet"` + +`output_files` + +String; default is `"single"` + +`progress_message` + +String; default is `"Generating Descriptor Set proto_library %{label}"` + +`proto_compiler` + +[Label](/concepts/labels); default is `None` diff --git a/reference/be/python.mdx b/reference/be/python.mdx new file mode 100644 index 0000000..32acec6 --- /dev/null +++ b/reference/be/python.mdx @@ -0,0 +1,984 @@ +--- +title: 'Python Rules' +--- + + + +## Rules + +- [py\_binary](#py_binary) +- [py\_library](#py_library) +- [py\_test](#py_test) +- [py\_runtime](#py_runtime) + +## py\_binary + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_binary_rule.bzl) + +``` +py_binary(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, distribs, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, imports, interpreter_args, legacy_create_init, licenses, main, main_module, output_licenses, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, pyi_deps, pyi_srcs, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + List of additional libraries to be linked in to the target. +See comments about +the \[\`deps\` attribute typically defined by +rules\](https://bazel.build/reference/be/common-definitions#typical-attributes). +These are typically \`py\_library\` rules. + +Targets that only provide data files used at runtime belong in the \`data\` +attribute. + +:::{note} +The order of this list can matter because it affects the order that information +from dependencies is merged in, which can be relevant depending on the ordering +mode of depsets that are merged. + +\\* {obj}\`PyInfo.site\_packages\_symlinks\` uses topological ordering. + +See {obj}\`PyInfo\` for more information about the ordering of its depsets and +how its fields are merged. +::: + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The +\`.py\` files belong in \`srcs\` and library targets belong in \`deps\`. Other binary +files that may be needed at run time belong in \`data\`. + `data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files need by this library at runtime. See comments about +the \[\`data\` attribute typically defined by rules\](https://bazel.build/reference/be/common-definitions#typical-attributes). + +There is no \`py\_embed\_data\` like there is \`cc\_embed\_data\` and \`go\_embed\_data\`. +This is because Python has a concept of runtime resources. + `distribs` + +List of strings; default is `[]` + +`imports` + +List of strings; default is `[]` + + List of import directories to be added to the PYTHONPATH. + +Subject to "Make variable" substitution. These import directories will be added +for this rule and all rules that depend on it (note: not the rules this rule +depends on. Each directory will be added to \`PYTHONPATH\` by \`py\_binary\` rules +that depend on this rule. The strings are repo-runfiles-root relative, + +Absolute paths (paths that start with \`/\`) and paths that references a path +above the execution root are not allowed and will result in an error. + `interpreter_args` + +List of strings; default is `[]` + + Arguments that are only applicable to the interpreter. + +The args an interpreter supports are specific to the interpreter. For +CPython, see https://docs.python.org/3/using/cmdline.html. + +:::{note} +Only supported for {obj}\`--bootstrap\_impl=script\`. Ignored otherwise. +::: + +:::{seealso} +The {any}\`RULES\_PYTHON\_ADDITIONAL\_INTERPRETER\_ARGS\` environment variable +::: + +:::{versionadded} 1.3.0 +::: + `legacy_create_init` + +Integer; default is `-1` + + Whether to implicitly create empty \`\_\_init\_\_.py\` files in the runfiles tree. +These are created in every directory containing Python source code or shared +libraries, and every parent directory of those directories, excluding the repo +root directory. The default, \`-1\` (auto), means true unless +\`--incompatible\_default\_to\_explicit\_init\_py\` is used. If false, the user is +responsible for creating (possibly empty) \`\_\_init\_\_.py\` files and adding them to +the \`srcs\` of Python targets as required. + `main` + +[Label](/concepts/labels); default is `None` + + Optional; the name of the source file that is the main entry point of the +application. This file must also be listed in \`srcs\`. If left unspecified, +\`name\`, with \`.py\` appended, is used instead. If \`name\` does not match any +filename in \`srcs\`, \`main\` must be specified. + +This is mutually exclusive with {obj}\`main\_module\`. + `main_module` + +String; default is `""` + + Module name to execute as the main program. + +When set, \`srcs\` is not required, and it is assumed the module is +provided by a dependency. + +See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more +information about running modules as the main program. + +This is mutually exclusive with {obj}\`main\`. + +:::{versionadded} 1.3.0 +::: + `precompile` + +String; default is `"inherit"` + + Whether py source files \*\*for this target\*\* should be precompiled. + +Values: + +\\* \`inherit\`: Allow the downstream binary decide if precompiled files are used. +\\* \`enabled\`: Compile Python source files at build time. +\\* \`disabled\`: Don't compile Python source files at build time. + +:::{seealso} + +\\* The {flag}\`--precompile\` flag, which can override this attribute in some cases + and will affect all targets when building. +\\* The {obj}\`pyc\_collection\` attribute for transitively enabling precompiling on + a per-target basis. +\\* The \[Precompiling\](precompiling) docs for a guide about using precompiling. +::: + `precompile_invalidation_mode` + +String; default is `"auto"` + + How precompiled files should be verified to be up-to-date with their associated +source files. Possible values are: +\\* \`auto\`: The effective value will be automatically determined by other build + settings. +\\* \`checked\_hash\`: Use the pyc file if the hash of the source file matches the hash + recorded in the pyc file. This is most useful when working with code that + you may modify. +\\* \`unchecked\_hash\`: Always use the pyc file; don't check the pyc's hash against + the source file. This is most useful when the code won't be modified. + +For more information on pyc invalidation modes, see +https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode + `precompile_optimize_level` + +Integer; default is `0` + + The optimization level for precompiled files. + +For more information about optimization levels, see the \`compile()\` function's +\`optimize\` arg docs at https://docs.python.org/3/library/functions.html#compile + +NOTE: The value \`-1\` means "current interpreter", which will be the interpreter +used \_at build time when pycs are generated\_, not the interpreter used at +runtime when the code actually runs. + `precompile_source_retention` + +String; default is `"inherit"` + + Determines, when a source file is compiled, if the source file is kept +in the resulting output or not. Valid values are: + +\\* \`inherit\`: Inherit the value from the {flag}\`--precompile\_source\_retention\` flag. +\\* \`keep\_source\`: Include the original Python source. +\\* \`omit\_source\`: Don't include the original py source. + `pyc_collection` + +String; default is `"inherit"` + + Determines whether pyc files from dependencies should be manually included. + +Valid values are: +\\* \`inherit\`: Inherit the value from {flag}\`--precompile\`. +\\* \`include\_pyc\`: Add implicitly generated pyc files from dependencies. i.e. + pyc files for targets that specify {attr}\`precompile="inherit"\`. +\\* \`disabled\`: Don't add implicitly generated pyc files. Note that + pyc files may still come from dependencies that enable precompiling at the + target level. + `pyi_deps` + +List of [labels](/concepts/labels); default is `[]` + + Dependencies providing type definitions the library needs. + +These are dependencies that satisfy imports guarded by \`typing.TYPE\_CHECKING\`. +These are build-time only dependencies and not included as part of a runnable +program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + `pyi_srcs` + +List of [labels](/concepts/labels); default is `[]` + + Type definition files for the library. + +These are typically \`.pyi\` files, but other file types for type-checker specific +formats are allowed. These files are build-time only dependencies and not included +as part of a runnable program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + `python_version` + +String; default is `""` + + The Python version this target should use. + +The value should be in \`X.Y\` or \`X.Y.Z\` (or compatible) format. If empty or +unspecified, the incoming configuration's {obj}\`--python\_version\` flag is +inherited. For backwards compatibility, the values \`PY2\` and \`PY3\` are +accepted, but treated as an empty/unspecified value. + +:::{note} +In order for the requested version to be used, there must be a +toolchain configured to match the Python version. If there isn't, then it +may be silently ignored, or an error may occur, depending on the toolchain +configuration. +::: + +:::{versionchanged} 1.1.0 + +This attribute was changed from only accepting \`PY2\` and \`PY3\` values to +accepting arbitrary Python versions. +::: + `srcs_version` + +String; default is `""` + + Defunct, unused, does nothing. + `stamp` + +Integer; default is `-1` + + Whether to encode build information into the binary. Possible values: + +\\* \`stamp = 1\`: Always stamp the build information into the binary, even in + \`--nostamp\` builds. \*\*This setting should be avoided\*\*, since it potentially kills + remote caching for the binary and any downstream actions that depend on it. +\\* \`stamp = 0\`: Always replace build information by constant values. This gives + good build result caching. +\\* \`stamp = -1\`: Embedding of build information is controlled by the + \`--\[no\]stamp\` flag. + +Stamped binaries are not rebuilt unless their dependencies change. + +WARNING: Stamping can harm build performance by reducing cache hits and should +be avoided if possible. + + +## py\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_library_rule.bzl) + +``` +py_library(name, deps, srcs, data, aspect_hints, compatible_with, deprecation, distribs, exec_compatible_with, exec_group_compatible_with, exec_properties, experimental_venvs_site_packages, features, imports, licenses, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyi_deps, pyi_srcs, restricted_to, srcs_version, tags, target_compatible_with, testonly, toolchains, visibility) +``` + + A library of Python code that can be depended upon. + +Default outputs: +\\* The input Python sources +\\* The precompiled artifacts from the sources. + +NOTE: Precompilation affects which of the default outputs are included in the +resulting runfiles. See the precompile-related attributes and flags for +more information. + +:::{versionchanged} 0.37.0 +Source files are no longer added to the runfiles directly. +::: + + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + List of additional libraries to be linked in to the target. +See comments about +the \[\`deps\` attribute typically defined by +rules\](https://bazel.build/reference/be/common-definitions#typical-attributes). +These are typically \`py\_library\` rules. + +Targets that only provide data files used at runtime belong in the \`data\` +attribute. + +:::{note} +The order of this list can matter because it affects the order that information +from dependencies is merged in, which can be relevant depending on the ordering +mode of depsets that are merged. + +\\* {obj}\`PyInfo.site\_packages\_symlinks\` uses topological ordering. + +See {obj}\`PyInfo\` for more information about the ordering of its depsets and +how its fields are merged. +::: + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The +\`.py\` files belong in \`srcs\` and library targets belong in \`deps\`. Other binary +files that may be needed at run time belong in \`data\`. + `data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files need by this library at runtime. See comments about +the \[\`data\` attribute typically defined by rules\](https://bazel.build/reference/be/common-definitions#typical-attributes). + +There is no \`py\_embed\_data\` like there is \`cc\_embed\_data\` and \`go\_embed\_data\`. +This is because Python has a concept of runtime resources. + `distribs` + +List of strings; default is `[]` + +`experimental_venvs_site_packages` + +[Label](/concepts/labels); default is `None` + + \*\*INTERNAL ATTRIBUTE. SHOULD ONLY BE SET BY rules\_python-INTERNAL CODE.\*\* + +:::{include} /\_includes/experimental\_api.md +::: + +A flag that decides whether the library should treat its sources as a +site-packages layout. + +When the flag is \`yes\`, then the \`srcs\` files are treated as a site-packages +layout that is relative to the \`imports\` attribute. The \`imports\` attribute +can have only a single element. It is a repo-relative runfiles path. + +For example, in the \`my/pkg/BUILD.bazel\` file, given +\`srcs=\["site-packages/foo/bar.py"\]\`, specifying +\`imports=\["my/pkg/site-packages"\]\` means \`foo/bar.py\` is the file path +under the binary's venv site-packages directory that should be made available (i.e. +\`import foo.bar\` will work). + +\`\_\_init\_\_.py\` files are treated specially to provide basic support for \[implicit +namespace packages\]( +https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages). +However, the \*content\* of the files cannot be taken into account, merely their +presence or absense. Stated another way: \[pkgutil-style namespace packages\]( +https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages) +won't be understood as namespace packages; they'll be seen as regular packages. This will +likely lead to conflicts with other targets that contribute to the namespace. + +:::{tip} +This attributes populates {obj}\`PyInfo.site\_packages\_symlinks\`, which is +a topologically ordered depset. This means dependencies closer and earlier +to a consumer have precedence. See {obj}\`PyInfo.site\_packages\_symlinks\` for +more information. +::: + +:::{versionadded} 1.4.0 +::: + `imports` + +List of strings; default is `[]` + + List of import directories to be added to the PYTHONPATH. + +Subject to "Make variable" substitution. These import directories will be added +for this rule and all rules that depend on it (note: not the rules this rule +depends on. Each directory will be added to \`PYTHONPATH\` by \`py\_binary\` rules +that depend on this rule. The strings are repo-runfiles-root relative, + +Absolute paths (paths that start with \`/\`) and paths that references a path +above the execution root are not allowed and will result in an error. + `precompile` + +String; default is `"inherit"` + + Whether py source files \*\*for this target\*\* should be precompiled. + +Values: + +\\* \`inherit\`: Allow the downstream binary decide if precompiled files are used. +\\* \`enabled\`: Compile Python source files at build time. +\\* \`disabled\`: Don't compile Python source files at build time. + +:::{seealso} + +\\* The {flag}\`--precompile\` flag, which can override this attribute in some cases + and will affect all targets when building. +\\* The {obj}\`pyc\_collection\` attribute for transitively enabling precompiling on + a per-target basis. +\\* The \[Precompiling\](precompiling) docs for a guide about using precompiling. +::: + `precompile_invalidation_mode` + +String; default is `"auto"` + + How precompiled files should be verified to be up-to-date with their associated +source files. Possible values are: +\\* \`auto\`: The effective value will be automatically determined by other build + settings. +\\* \`checked\_hash\`: Use the pyc file if the hash of the source file matches the hash + recorded in the pyc file. This is most useful when working with code that + you may modify. +\\* \`unchecked\_hash\`: Always use the pyc file; don't check the pyc's hash against + the source file. This is most useful when the code won't be modified. + +For more information on pyc invalidation modes, see +https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode + `precompile_optimize_level` + +Integer; default is `0` + + The optimization level for precompiled files. + +For more information about optimization levels, see the \`compile()\` function's +\`optimize\` arg docs at https://docs.python.org/3/library/functions.html#compile + +NOTE: The value \`-1\` means "current interpreter", which will be the interpreter +used \_at build time when pycs are generated\_, not the interpreter used at +runtime when the code actually runs. + `precompile_source_retention` + +String; default is `"inherit"` + + Determines, when a source file is compiled, if the source file is kept +in the resulting output or not. Valid values are: + +\\* \`inherit\`: Inherit the value from the {flag}\`--precompile\_source\_retention\` flag. +\\* \`keep\_source\`: Include the original Python source. +\\* \`omit\_source\`: Don't include the original py source. + `pyi_deps` + +List of [labels](/concepts/labels); default is `[]` + + Dependencies providing type definitions the library needs. + +These are dependencies that satisfy imports guarded by \`typing.TYPE\_CHECKING\`. +These are build-time only dependencies and not included as part of a runnable +program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + `pyi_srcs` + +List of [labels](/concepts/labels); default is `[]` + + Type definition files for the library. + +These are typically \`.pyi\` files, but other file types for type-checker specific +formats are allowed. These files are build-time only dependencies and not included +as part of a runnable program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + `srcs_version` + +String; default is `""` + + Defunct, unused, does nothing. + + +## py\_test + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_test_rule.bzl) + +``` +py_test(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, imports, interpreter_args, legacy_create_init, licenses, local, main, main_module, package_metadata, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, pyi_deps, pyi_srcs, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility) +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + List of additional libraries to be linked in to the target. +See comments about +the \[\`deps\` attribute typically defined by +rules\](https://bazel.build/reference/be/common-definitions#typical-attributes). +These are typically \`py\_library\` rules. + +Targets that only provide data files used at runtime belong in the \`data\` +attribute. + +:::{note} +The order of this list can matter because it affects the order that information +from dependencies is merged in, which can be relevant depending on the ordering +mode of depsets that are merged. + +\\* {obj}\`PyInfo.site\_packages\_symlinks\` uses topological ordering. + +See {obj}\`PyInfo\` for more information about the ordering of its depsets and +how its fields are merged. +::: + `srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of Python source files that are processed to create the target. This +includes all your checked-in code and may include generated source files. The +\`.py\` files belong in \`srcs\` and library targets belong in \`deps\`. Other binary +files that may be needed at run time belong in \`data\`. + `data` + +List of [labels](/concepts/labels); default is `[]` + + The list of files need by this library at runtime. See comments about +the \[\`data\` attribute typically defined by rules\](https://bazel.build/reference/be/common-definitions#typical-attributes). + +There is no \`py\_embed\_data\` like there is \`cc\_embed\_data\` and \`go\_embed\_data\`. +This is because Python has a concept of runtime resources. + `distribs` + +List of strings; default is `[]` + +`imports` + +List of strings; default is `[]` + + List of import directories to be added to the PYTHONPATH. + +Subject to "Make variable" substitution. These import directories will be added +for this rule and all rules that depend on it (note: not the rules this rule +depends on. Each directory will be added to \`PYTHONPATH\` by \`py\_binary\` rules +that depend on this rule. The strings are repo-runfiles-root relative, + +Absolute paths (paths that start with \`/\`) and paths that references a path +above the execution root are not allowed and will result in an error. + `interpreter_args` + +List of strings; default is `[]` + + Arguments that are only applicable to the interpreter. + +The args an interpreter supports are specific to the interpreter. For +CPython, see https://docs.python.org/3/using/cmdline.html. + +:::{note} +Only supported for {obj}\`--bootstrap\_impl=script\`. Ignored otherwise. +::: + +:::{seealso} +The {any}\`RULES\_PYTHON\_ADDITIONAL\_INTERPRETER\_ARGS\` environment variable +::: + +:::{versionadded} 1.3.0 +::: + `legacy_create_init` + +Integer; default is `-1` + + Whether to implicitly create empty \`\_\_init\_\_.py\` files in the runfiles tree. +These are created in every directory containing Python source code or shared +libraries, and every parent directory of those directories, excluding the repo +root directory. The default, \`-1\` (auto), means true unless +\`--incompatible\_default\_to\_explicit\_init\_py\` is used. If false, the user is +responsible for creating (possibly empty) \`\_\_init\_\_.py\` files and adding them to +the \`srcs\` of Python targets as required. + `main` + +[Label](/concepts/labels); default is `None` + + Optional; the name of the source file that is the main entry point of the +application. This file must also be listed in \`srcs\`. If left unspecified, +\`name\`, with \`.py\` appended, is used instead. If \`name\` does not match any +filename in \`srcs\`, \`main\` must be specified. + +This is mutually exclusive with {obj}\`main\_module\`. + `main_module` + +String; default is `""` + + Module name to execute as the main program. + +When set, \`srcs\` is not required, and it is assumed the module is +provided by a dependency. + +See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more +information about running modules as the main program. + +This is mutually exclusive with {obj}\`main\`. + +:::{versionadded} 1.3.0 +::: + `precompile` + +String; default is `"inherit"` + + Whether py source files \*\*for this target\*\* should be precompiled. + +Values: + +\\* \`inherit\`: Allow the downstream binary decide if precompiled files are used. +\\* \`enabled\`: Compile Python source files at build time. +\\* \`disabled\`: Don't compile Python source files at build time. + +:::{seealso} + +\\* The {flag}\`--precompile\` flag, which can override this attribute in some cases + and will affect all targets when building. +\\* The {obj}\`pyc\_collection\` attribute for transitively enabling precompiling on + a per-target basis. +\\* The \[Precompiling\](precompiling) docs for a guide about using precompiling. +::: + `precompile_invalidation_mode` + +String; default is `"auto"` + + How precompiled files should be verified to be up-to-date with their associated +source files. Possible values are: +\\* \`auto\`: The effective value will be automatically determined by other build + settings. +\\* \`checked\_hash\`: Use the pyc file if the hash of the source file matches the hash + recorded in the pyc file. This is most useful when working with code that + you may modify. +\\* \`unchecked\_hash\`: Always use the pyc file; don't check the pyc's hash against + the source file. This is most useful when the code won't be modified. + +For more information on pyc invalidation modes, see +https://docs.python.org/3/library/py\_compile.html#py\_compile.PycInvalidationMode + `precompile_optimize_level` + +Integer; default is `0` + + The optimization level for precompiled files. + +For more information about optimization levels, see the \`compile()\` function's +\`optimize\` arg docs at https://docs.python.org/3/library/functions.html#compile + +NOTE: The value \`-1\` means "current interpreter", which will be the interpreter +used \_at build time when pycs are generated\_, not the interpreter used at +runtime when the code actually runs. + `precompile_source_retention` + +String; default is `"inherit"` + + Determines, when a source file is compiled, if the source file is kept +in the resulting output or not. Valid values are: + +\\* \`inherit\`: Inherit the value from the {flag}\`--precompile\_source\_retention\` flag. +\\* \`keep\_source\`: Include the original Python source. +\\* \`omit\_source\`: Don't include the original py source. + `pyc_collection` + +String; default is `"inherit"` + + Determines whether pyc files from dependencies should be manually included. + +Valid values are: +\\* \`inherit\`: Inherit the value from {flag}\`--precompile\`. +\\* \`include\_pyc\`: Add implicitly generated pyc files from dependencies. i.e. + pyc files for targets that specify {attr}\`precompile="inherit"\`. +\\* \`disabled\`: Don't add implicitly generated pyc files. Note that + pyc files may still come from dependencies that enable precompiling at the + target level. + `pyi_deps` + +List of [labels](/concepts/labels); default is `[]` + + Dependencies providing type definitions the library needs. + +These are dependencies that satisfy imports guarded by \`typing.TYPE\_CHECKING\`. +These are build-time only dependencies and not included as part of a runnable +program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + `pyi_srcs` + +List of [labels](/concepts/labels); default is `[]` + + Type definition files for the library. + +These are typically \`.pyi\` files, but other file types for type-checker specific +formats are allowed. These files are build-time only dependencies and not included +as part of a runnable program (packaging rules may include them, however). + +:::{versionadded} 1.1.0 +::: + `python_version` + +String; default is `""` + + The Python version this target should use. + +The value should be in \`X.Y\` or \`X.Y.Z\` (or compatible) format. If empty or +unspecified, the incoming configuration's {obj}\`--python\_version\` flag is +inherited. For backwards compatibility, the values \`PY2\` and \`PY3\` are +accepted, but treated as an empty/unspecified value. + +:::{note} +In order for the requested version to be used, there must be a +toolchain configured to match the Python version. If there isn't, then it +may be silently ignored, or an error may occur, depending on the toolchain +configuration. +::: + +:::{versionchanged} 1.1.0 + +This attribute was changed from only accepting \`PY2\` and \`PY3\` values to +accepting arbitrary Python versions. +::: + `srcs_version` + +String; default is `""` + + Defunct, unused, does nothing. + `stamp` + +Integer; default is `0` + + Whether to encode build information into the binary. Possible values: + +\\* \`stamp = 1\`: Always stamp the build information into the binary, even in + \`--nostamp\` builds. \*\*This setting should be avoided\*\*, since it potentially kills + remote caching for the binary and any downstream actions that depend on it. +\\* \`stamp = 0\`: Always replace build information by constant values. This gives + good build result caching. +\\* \`stamp = -1\`: Embedding of build information is controlled by the + \`--\[no\]stamp\` flag. + +Stamped binaries are not rebuilt unless their dependencies change. + +WARNING: Stamping can harm build performance by reducing cache hits and should +be avoided if possible. + + +## py\_runtime + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_runtime_rule.bzl) + +``` +py_runtime(name, abi_flags, aspect_hints, bootstrap_template, compatible_with, coverage_tool, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, files, implementation_name, interpreter, interpreter_path, interpreter_version_info, package_metadata, pyc_tag, python_version, restricted_to, site_init_template, stage2_bootstrap_template, stub_shebang, tags, target_compatible_with, testonly, toolchains, visibility, zip_main_template) +``` + + Represents a Python runtime used to execute Python code. + +A \`py\_runtime\` target can represent either a \*platform runtime\* or an \*in-build +runtime\*. A platform runtime accesses a system-installed interpreter at a known +path, whereas an in-build runtime points to an executable target that acts as +the interpreter. In both cases, an "interpreter" means any executable binary or +wrapper script that is capable of running a Python script passed on the command +line, following the same conventions as the standard CPython interpreter. + +A platform runtime is by its nature non-hermetic. It imposes a requirement on +the target platform to have an interpreter located at a specific path. An +in-build runtime may or may not be hermetic, depending on whether it points to +a checked-in interpreter or a wrapper script that accesses the system +interpreter. + +Example + +\`\`\` +load("@rules\_python//python:py\_runtime.bzl", "py\_runtime") + +py\_runtime( + name = "python-2.7.12", + files = glob(\["python-2.7.12/\*\*"\]), + interpreter = "python-2.7.12/bin/python", +) + +py\_runtime( + name = "python-3.6.0", + interpreter\_path = "/opt/pyenv/versions/3.6.0/bin/python", +) +\`\`\` + + + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`abi_flags` + +String; default is `""` + + The runtime's ABI flags, i.e. \`sys.abiflags\`. + +If not set, then it will be set based on flags. + `bootstrap_template` + +[Label](/concepts/labels); default is `"@rules_python//python/private:bootstrap_template"` + + The bootstrap script template file to use. Should have %python\_binary%, +%workspace\_name%, %main%, and %imports%. + +This template, after expansion, becomes the executable file used to start the +process, so it is responsible for initial bootstrapping actions such as finding +the Python interpreter, runfiles, and constructing an environment to run the +intended Python application. + +While this attribute is currently optional, it will become required when the +Python rules are moved out of Bazel itself. + +The exact variable names expanded is an unstable API and is subject to change. +The API will become more stable when the Python rules are moved out of Bazel +itself. + +See @bazel\_tools//tools/python:python\_bootstrap\_template.txt for more variables. + `coverage_tool` + +[Label](/concepts/labels); default is `None` + + This is a target to use for collecting code coverage information from +{rule}\`py\_binary\` and {rule}\`py\_test\` targets. + +If set, the target must either produce a single file or be an executable target. +The path to the single file, or the executable if the target is executable, +determines the entry point for the python coverage tool. The target and its +runfiles will be added to the runfiles when coverage is enabled. + +The entry point for the tool must be loadable by a Python interpreter (e.g. a +\`.py\` or \`.pyc\` file). It must accept the command line arguments +of \[\`coverage.py\`\](https://coverage.readthedocs.io), at least including +the \`run\` and \`lcov\` subcommands. + `files` + +List of [labels](/concepts/labels); default is `[]` + + For an in-build runtime, this is the set of files comprising this runtime. +These files will be added to the runfiles of Python binaries that use this +runtime. For a platform runtime this attribute must not be set. + `implementation_name` + +String; default is `"cpython"` + + The Python implementation name (\`sys.implementation.name\`) + `interpreter` + +[Label](/concepts/labels); default is `None` + + For an in-build runtime, this is the target to invoke as the interpreter. It +can be either of: + +\\* A single file, which will be the interpreter binary. It's assumed such + interpreters are either self-contained single-file executables or any + supporting files are specified in \`files\`. +\\* An executable target. The target's executable will be the interpreter binary. + Any other default outputs (\`target.files\`) and plain files runfiles + (\`runfiles.files\`) will be automatically included as if specified in the + \`files\` attribute. + + NOTE: the runfiles of the target may not yet be properly respected/propagated + to consumers of the toolchain/interpreter, see + bazel-contrib/rules\_python/issues/1612 + +For a platform runtime (i.e. \`interpreter\_path\` being set) this attribute must +not be set. + `interpreter_path` + +String; default is `""` + + For a platform runtime, this is the absolute path of a Python interpreter on +the target platform. For an in-build runtime this attribute must not be set. + `interpreter_version_info` + +Dictionary: String -> String; default is `{}` + + Version information about the interpreter this runtime provides. + +If not specified, uses {obj}\`--python\_version\` + +The supported keys match the names for \`sys.version\_info\`. While the input +values are strings, most are converted to ints. The supported keys are: + \\* major: int, the major version number + \\* minor: int, the minor version number + \\* micro: optional int, the micro version number + \\* releaselevel: optional str, the release level + \\* serial: optional int, the serial number of the release + +:::{versionchanged} 0.36.0 +{obj}\`--python\_version\` determines the default value. +::: + `pyc_tag` + +String; default is `""` + + Optional string; the tag portion of a pyc filename, e.g. the \`cpython-39\` infix +of \`foo.cpython-39.pyc\`. See PEP 3147. If not specified, it will be computed +from \`implementation\_name\` and \`interpreter\_version\_info\`. If no pyc\_tag is +available, then only source-less pyc generation will function correctly. + `python_version` + +String; default is `"PY3"` + + Whether this runtime is for Python major version 2 or 3. Valid values are \`"PY2"\` +and \`"PY3"\`. + +The default value is controlled by the \`--incompatible\_py3\_is\_default\` flag. +However, in the future this attribute will be mandatory and have no default +value. + `site_init_template` + +[Label](/concepts/labels); default is `"@rules_python//python/private:site_init_template"` + + The template to use for the binary-specific site-init hook run by the +interpreter at startup. + +:::{versionadded} 0.41.0 +::: + `stage2_bootstrap_template` + +[Label](/concepts/labels); default is `"@rules_python//python/private:stage2_bootstrap_template"` + + The template to use when two stage bootstrapping is enabled + +:::{seealso} +{obj}\`PyRuntimeInfo.stage2\_bootstrap\_template\` and {obj}\`--bootstrap\_impl\` +::: + `stub_shebang` + +String; default is `"#!/usr/bin/env python3"` + + "Shebang" expression prepended to the bootstrapping Python stub script +used when executing {rule}\`py\_binary\` targets. + +See https://github.com/bazelbuild/bazel/issues/8685 for +motivation. + +Does not apply to Windows. + `zip_main_template` + +[Label](/concepts/labels); default is `"@rules_python//python/private:zip_main_template"` + + The template to use for a zip's top-level \`\_\_main\_\_.py\` file. + +This becomes the entry point executed when \`python foo.zip\` is run. + +:::{seealso} +The {obj}\`PyRuntimeInfo.zip\_main\_template\` field. +::: diff --git a/reference/be/shell.mdx b/reference/be/shell.mdx new file mode 100644 index 0000000..5a9baf4 --- /dev/null +++ b/reference/be/shell.mdx @@ -0,0 +1,218 @@ +--- +title: 'Shell Rules' +--- + + + +## Rules + +- [sh\_binary](#sh_binary) +- [sh\_library](#sh_library) +- [sh\_test](#sh_test) + +## sh\_binary + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_binary.bzl) + +``` +sh_binary(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, output_licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, use_bash_launcher, visibility) +``` + +The `sh_binary` rule is used to declare executable shell scripts. +( `sh_binary` is a misnomer: its outputs aren't necessarily binaries.) This rule ensures +that all dependencies are built, and appear in the `runfiles` area at execution time. +We recommend that you name your `sh_binary()` rules after the name of the script minus +the extension (e.g. `.sh`); the rule name and the file name must be distinct. +`sh_binary` respects shebangs, so any available interpreter may be used (eg. +`#!/bin/zsh`) + +#### Example + +For a simple shell script with no dependencies and some data files: + +``` +sh_binary( + name = "foo", + srcs = ["foo.sh"], + data = glob(["datafiles/*.txt"]), +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of "library" targets to be aggregated into this target. +See general comments about `deps` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical.deps). + +This attribute should be used to list other `sh_library` rules that provide +interpreted program source code depended on by the code in `srcs`. The files +provided by these rules will be present among the `runfiles` of this target. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + + The file containing the shell script. + +This attribute must be a singleton list, whose element is the shell script. +This script must be executable, and may be a source file or a generated file. +All other files required at runtime (whether scripts or data) belong in the +`data` attribute. + +`env_inherit` + +List of strings; default is `[]` + +`use_bash_launcher` + +Boolean; default is `False` + + Use a bash launcher initializing the runfiles library + + +## sh\_library + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_library.bzl) + +``` +sh_library(name, deps, srcs, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) +``` + +The main use for this rule is to aggregate together a logical +"library" consisting of related scripts—programs in an +interpreted language that does not require compilation or linking, +such as the Bourne shell—and any data those programs need at +run-time. Such "libraries" can then be used from +the `data` attribute of one or +more `sh_binary` rules. + +You can use the [`filegroup`](/reference/be/general.html#filegroup) rule to aggregate data +files. + +In interpreted programming languages, there's not always a clear +distinction between "code" and "data": after all, the program is +just "data" from the interpreter's point of view. For this reason +this rule has three attributes which are all essentially equivalent: +`srcs`, `deps` and `data`. +The current implementation does not distinguish between the elements of these lists. +All three attributes accept rules, source files and generated files. +It is however good practice to use the attributes for their usual purpose (as with other rules). + +#### Examples + +``` +sh_library( + name = "foo", + data = [ + ":foo_service_script", # an sh_binary with srcs + ":deploy_foo", # another sh_binary with srcs + ], +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of "library" targets to be aggregated into this target. +See general comments about `deps` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical.deps). + +This attribute should be used to list other `sh_library` rules that provide +interpreted program source code depended on by the code in `srcs`. The files +provided by these rules will be present among the `runfiles` of this target. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + + The list of input files. + +This attribute should be used to list shell script source files that belong to +this library. Scripts can load other scripts using the shell's `source` +or `.` command. + +## sh\_test + +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_shell/tree/v0.2.0/shell/private/sh_test.bzl) + +``` +sh_test(name, deps, srcs, data, args, aspect_hints, compatible_with, deprecation, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, local, package_metadata, restricted_to, shard_count, size, tags, target_compatible_with, testonly, timeout, toolchains, use_bash_launcher, visibility) +``` + +A `sh_test()` rule creates a test written as a Bourne shell script. + +See the [attributes common to all test rules (\*\_test)](/reference/be/common-definitions#common-attributes-tests). + +#### Examples + +``` +sh_test( + name = "foo_integration_test", + size = "small", + srcs = ["foo_integration_test.sh"], + deps = [":foo_sh_lib"], + data = glob(["testdata/*.txt"]), +) + +``` + +### Arguments + +Attributes`name` + +[Name](/concepts/labels#target-names); required + +A unique name for this target. + +`deps` + +List of [labels](/concepts/labels); default is `[]` + + The list of "library" targets to be aggregated into this target. +See general comments about `deps` +at [Typical attributes defined by\ +most build rules](/reference/be/common-definitions#typical.deps). + +This attribute should be used to list other `sh_library` rules that provide +interpreted program source code depended on by the code in `srcs`. The files +provided by these rules will be present among the `runfiles` of this target. + +`srcs` + +List of [labels](/concepts/labels); default is `[]` + + The file containing the shell script. + +This attribute must be a singleton list, whose element is the shell script. +This script must be executable, and may be a source file or a generated file. +All other files required at runtime (whether scripts or data) belong in the +`data` attribute. + +`use_bash_launcher` + +Boolean; default is `False` + + Use a bash launcher initializing the runfiles library diff --git a/reference/command-line-reference.mdx b/reference/command-line-reference.mdx new file mode 100644 index 0000000..73ed4cc --- /dev/null +++ b/reference/command-line-reference.mdx @@ -0,0 +1,13974 @@ +--- +title: 'Command-Line Reference' +--- + + + +``` +bazel [<startup options>] <command> [<args>] + +``` + +or + +``` +bazel [<startup options>] <command> [<args>] -- [<target patterns>] + +``` + +See the [User's Guide](/docs/build#specifying-build-targets) for the +target patterns syntax. + +## Option Syntax + +Options can be passed to Bazel in different ways. Options that require a value +can be passed with either an equals sign or a space: + +``` +--<option>=<value> +--<option> <value> + +``` + +Some options have a single character short form; in that case, the short form +has to be passed with a single dash and a space. + +``` +-<short_form> <value> + +``` + +Boolean options can be enabled as follows: + +``` +--<option> +--<option>=[true|yes|1] + +``` + +and disabled as follows: + +``` +--no<option> +--<option>=[false|no|0] + +``` + +Tristate options are usually set to automatic by default, and can be +force-enabled as follows: + +``` +--<option>=[true|yes|1] + +``` + +or force-disabled as follows: + +``` +--no<option> +--<option>=[false|no|0] + +``` + +## Commands + +[`aquery`](#aquery)Analyzes the given targets and queries the action graph.[`build`](#build)Builds the specified targets.[`canonicalize-flags`](#canonicalize-flags)Canonicalizes a list of bazel options.[`clean`](#clean)Removes output files and optionally stops the server.[`coverage`](#coverage)Generates code coverage report for specified test targets.[`cquery`](#cquery)Loads, analyzes, and queries the specified targets w/ configurations.[`dump`](#dump)Dumps the internal state of the bazel server process.[`fetch`](#fetch)Fetches external repositories that are prerequisites to the targets.[`help`](#help)Prints help for commands, or the index.[`info`](#info)Displays runtime info about the bazel server.[`license`](#license)Prints the license of this software.[`mobile-install`](#mobile-install)Installs targets to mobile devices.[`mod`](#mod)Queries the Bzlmod external dependency graph[`print_action`](#print_action)Prints the command line args for compiling a file.[`query`](#query)Executes a dependency graph query.[`run`](#run)Runs the specified target.[`shutdown`](#shutdown)Stops the bazel server.[`test`](#test)Builds and runs the specified test targets.[`vendor`](#vendor)Fetches external repositories into a folder specified by the flag --vendor\_dir.[`version`](#version)Prints version information for bazel. + +## Startup Options + +Options that appear before the command and are parsed by the client: +`--[no]autodetect_server_javabase` default: "true" + +When --noautodetect\_server\_javabase is passed, Bazel does not fall back to the local JDK for running the bazel server and instead exits. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]batch` default: "false" + +If set, Bazel will be run as just a client process without a server, instead of in the standard client/server mode. This is deprecated and will be removed, please prefer shutting down the server explicitly if you wish to avoid lingering servers. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`deprecated`](#metadata_tag_DEPRECATED) + +`--[no]batch_cpu_scheduling` default: "false" + +Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched\_setscheduler'. If false, then Bazel does not perform a system call. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--bazelrc=<path>` multiple uses are accumulated + +The location of the user .bazelrc file containing default values of Bazel options. /dev/null indicates that all further `--bazelrc` s will be ignored, which is useful to disable the search for a user rc file, e.g. in release builds. +This option can also be specified multiple times. +E.g. with `--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc`, + +1. x.rc and y.rc are read. +2. z.rc is ignored due to the prior /dev/null. + If unspecified, Bazel uses the first .bazelrc file it finds in the following two locations: the workspace directory, then the user's home directory. + Note: command line options will always supersede any option in bazelrc. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--[no]block_for_lock` default: "true" + +When --noblock\_for\_lock is passed, Bazel does not wait for a running command to complete, but instead exits immediately. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]client_debug` default: "false" + +If true, log debug information from the client to stderr. Changing this option will not cause the server to restart. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--connect_timeout_secs=<an integer>` default: "30" + +The amount of time the client waits for each attempt to connect to the server + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--digest_function=<hash function>` default: see description + +The hash function to use when computing file digests. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--experimental_cgroup_parent=<path>` default: see description + +The cgroup where to start the bazel server as an absolute path. The server process will be started in the specified cgroup for each supported controller. For example, if the value of this flag is /build/bazel and the cpu and memory controllers are mounted respectively on /sys/fs/cgroup/cpu and /sys/fs/cgroup/memory, the server will be started in the cgroups /sys/fs/cgroup/cpu/build/bazel and /sys/fs/cgroup/memory/build/bazel.It is not an error if the specified cgroup is not writable for one or more of the controllers. This options does not have any effect on platforms that do not support cgroups. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_run_in_user_cgroup` default: "false" + +If true, the Bazel server will be run with systemd-run, and the user will own the cgroup. This flag only takes effect on Linux. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`execution`](#effect_tag_EXECUTION) + +`--failure_detail_out=<path>` default: see description + +If set, specifies a location to write a failure\_detail protobuf message if the server experiences a failure and cannot report it via gRPC, as normal. Otherwise, the location will be ${OUTPUT\_BASE}/failure\_detail.rawproto. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]home_rc` default: "true" + +Whether or not to look for the home bazelrc file at $HOME/.bazelrc + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--[no]idle_server_tasks` default: "true" + +Run System.gc() when the server is idle + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]ignore_all_rc_files` default: "false" + +Disables all rc files, regardless of the values of other rc-modifying flags, even if these flags come later in the list of startup options. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--io_nice_level={-1,0,1,2,3,4,5,6,7}` default: "-1" + +Only on Linux; set a level from 0-7 for best-effort IO scheduling using the sys\_ioprio\_set system call. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. If set to a negative value, then Bazel does not perform a system call. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--local_startup_timeout_secs=<an integer>` default: "120" + +The maximum amount of time the client waits to connect to the server + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--macos_qos_class=<a string>` default: "default" + +Sets the QoS service class of the bazel server when running on macOS. This flag has no effect on all other platforms but is supported to ensure rc files can be shared among them without changes. Possible values are: user-interactive, user-initiated, default, utility, and background. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--max_idle_secs=<integer>` default: "10800" + +The number of seconds the build server will wait idling before shutting down. Zero means that the server will never shutdown. This is only read on server-startup, changing this option will not cause the server to restart. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--output_base=<path>` default: see description + +If set, specifies the output location to which all build output will be written. Otherwise, the location will be ${OUTPUT\_ROOT}/ _blaze_ ${USER}/${MD5\_OF\_WORKSPACE\_ROOT}. Note: If you specify a different option from one to the next Bazel invocation for this value, you'll likely start up a new, additional Bazel server. Bazel starts exactly one server per specified output base. Typically there is one output base per workspace - however, with this option you may have multiple output bases per workspace and thereby run multiple builds for the same client on the same machine concurrently. See 'bazel help shutdown' on how to shutdown a Bazel server. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--output_user_root=<path>` default: see description + +The user-specific directory beneath which all build outputs are written; by default, this is a function of $USER, but by specifying a constant, build outputs can be shared between collaborating users. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]preemptible` default: "false" + +If true, the command can be preempted if another command is started. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]quiet` default: "false" + +If true, no informational messages are emitted on the console, only errors. Changing this option will not cause the server to restart. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--server_jvm_out=<path>` default: see description + +The location to write the server's JVM's output. If unset then defaults to a location in output\_base. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]shutdown_on_low_sys_mem` default: "false" + +If max\_idle\_secs is set and the build server has been idle for a while, shut down the server when the system is low on free RAM. Linux and MacOS only. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]system_rc` default: "true" + +Whether or not to look for the system-wide bazelrc. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--[no]unlimit_coredumps` default: "false" + +Raises the soft coredump limit to the hard limit to make coredumps of the server (including the JVM) and the client possible under common conditions. Stick this flag in your bazelrc once and forget about it so that you get coredumps when you actually encounter a condition that triggers them. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--[no]windows_enable_symlinks` default: "false" + +If true, real symbolic links will be created on Windows instead of file copying. Requires Windows developer mode to be enabled and Windows 10 version 1703 or greater. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--[no]workspace_rc` default: "true" + +Whether or not to look for the workspace bazelrc file at $workspace/.bazelrc + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Miscellaneous options, not otherwise categorized.: +`--host_jvm_args=<jvm_arg>` multiple uses are accumulated + +Flags to pass to the JVM executing Blaze. + +`--host_jvm_debug` + +Convenience option to add some additional JVM startup flags, which cause the JVM to wait during startup until you connect from a JDWP-compliant debugger (like Eclipse) to port 5005. + +Expands to: + +`--host_jvm_args=-agentlib:jdwp=transport=dt_socket,server=y,address=5005` + +`--server_javabase=<jvm path>` default: "" + +Path to the JVM used to execute Bazel itself. + +## Options Common to all Commands + +Options that appear before the command and are parsed by the client: +`--distdir=<a path>` multiple uses are accumulated + +Additional places to search for archives before accessing the network to download them. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--[no]experimental_repository_cache_hardlinks` default: "false" + +If set, the repository cache will hardlink the file in case of a cache hit, rather than copying. This is intended to save disk space. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--experimental_repository_downloader_retries=<an integer>` default: "5" + +The maximum number of attempts to retry a download error. If set to 0, retries are disabled. + +Tags: +[`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_scale_timeouts=<a double>` default: "1.0" + +Scale all timeouts in Starlark repository rules by this factor. In this way, external repositories can be made working on machines that are slower than the rule author expected, without changing the source code + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--http_connector_attempts=<an integer>` default: "8" + +The maximum number of attempts for http downloads. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--http_connector_retry_max_timeout=<An immutable length of time.>` default: "0s" + +The maximum timeout for http download retries. With a value of 0, no timeout maximum is defined. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--http_max_parallel_downloads=<an integer>` default: "8" + +The maximum number parallel http downloads. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--http_timeout_scaling=<a double>` default: "1.0" + +Scale all timeouts related to http downloads by the given factor + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--repo_contents_cache=<a path>` default: see description + +Specifies the location of the repo contents cache, which contains fetched repo directories shareable across workspaces. An empty string as argument requests the repo contents cache to be disabled, otherwise the default of '<--repository\_cache>/contents' is used. Note that this means setting '--repository\_cache=' would by default disable the repo contents cache as well, unless '--repo\_contents\_cache=<some\_path>' is also set. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--repo_contents_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" + +Specifies the amount of time the server must remain idle before garbage collection happens +to the repo contents cache. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--repo_contents_cache_gc_max_age=<An immutable length of time.>` default: "14d" + +Specifies the amount of time an entry in the repo contents cache can stay unused before it's garbage collected. If set to zero, only duplicate entries will be garbage collected. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--repository_cache=<a path>` default: see description + +Specifies the cache location of the downloaded values obtained during the fetching of external repositories. An empty string as argument requests the cache to be disabled, otherwise the default of '<--output\_user\_root>/cache/repos/v1' is used + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--[no]repository_disable_download` default: "false" + +If set, downloading using ctx.download{,\_and\_extract} is not allowed during repository fetching. Note that network access is not completely disabled; ctx.execute could still run an arbitrary executable that accesses the Internet. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +Options that control build execution: +`--experimental_ui_max_stdouterr_bytes=<an integer in (-1)-1073741819 range>` default: "1048576" + +The maximum size of the stdout / stderr files that will be printed to the console. -1 implies no limit. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--gc_churning_threshold=<an integer in 0-100 range>` default: "100" + +At any point after an invocation has been running for at least one minute, if Blaze has spent at least this percentage of the invocation's wall time doing full GCs, Blaze will give up and fail with an OOM. A value of 100 effectively means to never give up for this reason. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--gc_churning_threshold_if_multiple_top_level_targets=<an integer>` default: "-1" + +If set to a value in \[0, 100\] and this is a command that takes top-level targets (e.g. build but not query) and there are multiple such top-level targets, overrides --gc\_churning\_threshold. Useful to configure more aggressive OOMing behavior (i.e. a lower value than --gc\_churning\_threshold) when they are multiple top-level targets so that the invoker of Bazel can split and retry while still having less aggressive behavior when there is a single top-level target. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--gc_thrashing_threshold=<an integer in 0-100 range>` default: "100" + +The percent of tenured space occupied (0-100) above which GcThrashingDetector considers memory pressure events against its limits (--gc\_thrashing\_limits). If set to 100, GcThrashingDetector is disabled. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +Options that configure the toolchain used for action execution: +`--[no]incompatible_enable_proto_toolchain_resolution` default: "false" + +If true, proto lang rules define toolchains from protobuf repository. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--bep_maximum_open_remote_upload_files=<an integer>` default: "-1" + +Maximum number of open files allowed during BEP artifact upload. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_all` + +Downloads all remote outputs to the local machine. This flag is an alias for --remote\_download\_outputs=all. + +Expands to: + +`--remote_download_outputs=all` + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_minimal` + +Does not download any remote build outputs to the local machine. This flag is an alias for --remote\_download\_outputs=minimal. + +Expands to: + +`--remote_download_outputs=minimal` + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_outputs=<all, minimal or toplevel>` default: "toplevel" + +If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_symlink_template=<a string>` default: "" + +Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size\_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_toplevel` + +Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote\_download\_outputs=toplevel. + +Expands to: + +`--remote_download_outputs=toplevel` + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--repo_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies additional environment variables to be available only for repository rules. Note that repository rules see the full environment anyway, but in this way variables can be set via command-line flags and <code>.bazelrc</code> entries. The special syntax <code>=NAME</code> can be used to explicitly unset a variable. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]allow_experimental_loads` default: "false" + +If enabled, issue only a warning instead of an error for loads of experimental .bzls. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]check_bzl_visibility` default: "true" + +If disabled, .bzl load visibility errors are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]incompatible_enforce_starlark_utf8` default: "warning" + +If enabled (or set to 'error'), fail if Starlark files are not UTF-8 encoded. If set to 'warning', emit a warning instead. If set to 'off', Bazel assumes that Starlark files are UTF-8 encoded but does not verify this assumption. Note that Starlark files which are not UTF-8 encoded can cause Bazel to behave inconsistently. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]experimental_bzl_visibility` default: "true" + +If enabled, adds a `visibility()` function that .bzl files may call during top-level evaluation to set their visibility for the purpose of load() statements. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_cc_shared_library` default: "false" + +If set to true, rule attributes and Starlark API methods needed for the rule cc\_shared\_library will be available + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_disable_external_package` default: "false" + +If set to true, the auto-generated //external package will not be available anymore. Bazel will still be unable to parse the file 'external/BUILD', but globs reaching into external/ from the unnamed package will work. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_dormant_deps` default: "false" + +If set to true, attr.label(materializer=), attr(for\_dependency\_resolution=), attr.dormant\_label(), attr.dormant\_label\_list() and rule(for\_dependency\_resolution=) are allowed. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_enable_android_migration_apis` default: "false" + +If set to true, enables the APIs required to support the Android Starlark migration. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]experimental_enable_first_class_macros` default: "true" + +If set to true, enables the `macro()` construct for defining symbolic macros. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]experimental_enable_scl_dialect` default: "true" + +If set to true, .scl files may be used in load() statements. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]experimental_enable_starlark_set` default: "true" + +If true, enable the set data type and set() constructor in Starlark. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_google_legacy_api` default: "false" + +If set to true, exposes a number of experimental pieces of Starlark build API pertaining to Google legacy code. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_isolated_extension_usages` default: "false" + +If true, enables the <code>isolate</code> parameter in the <a href="https://bazel.build/rules/lib/globals/module#use\_extension"><code>use\_extension</code></a> function. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]experimental_platforms_api` default: "false" + +If set to true, enables a number of platform-related Starlark APIs useful for debugging. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_repo_remote_exec` default: "false" + +If set to true, repository\_rule gains some remote execution capabilities. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_repository_ctx_execute_wasm` default: "false" + +If true enables the repository\_ctx `load_wasm` and `execute_wasm` methods. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_sibling_repository_layout` default: "false" + +If set to true, non-main repositories are planted as symlinks to the main repository in the execution root. That is, all repositories are direct children of the $output\_base/execution\_root directory. This has the side effect of freeing up $output\_base/execution\_root/ **main**/external for the real top-level 'external' directory. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_single_package_toolchain_binding` default: "false" + +If enabled, the register\_toolchain function may not include target patterns which may refer to more than one package. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]experimental_starlark_types` default: "false" + +Enables type annotations and type checking. Locations where the annotations are allowed is further controlled by `--experimental_starlark_types_allowed_paths`. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_starlark_types_allowed_paths=<comma-separated list of options>` default: "" + +List of canonical Label prefixes under which Starlark type annotations are allowed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_allow_tags_propagation` default: "true" + +If set to true, tags will be propagated from a target to the actions' execution requirements; otherwise tags are not propagated. See https://github.com/bazelbuild/bazel/issues/8830 for details. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_always_check_depset_elements` default: "true" + +Check the validity of elements added to depsets, in all constructors. Elements must be immutable, but historically the depset(direct=...) constructor forgot to check. Use tuples instead of lists in depset elements. See https://github.com/bazelbuild/bazel/issues/10313 for details. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_autoload_externally=<comma-separated set of options>` default: "+@rules\_cc" + +A comma-separated list of rules (or other symbols) that were previously part of Bazel and which are now to be retrieved from their respective external repositories. This flag is intended to be used to facilitate migration of rules out of Bazel. See also https://github.com/bazelbuild/bazel/issues/23043. +A symbol that is autoloaded within a file behaves as if its built-into-Bazel definition were replaced by its canonical new definition in an external repository. For a BUILD file, this essentially means implicitly adding a load() statement. For a .bzl file, it's either a load() statement or a change to a field of the `native` object, depending on whether the autoloaded symbol is a rule. +Bazel maintains a hardcoded list of all symbols that may be autoloaded; only those symbols may appear in this flag. For each symbol, Bazel knows the new definition location in an external repository, as well as a set of special-cased repositories that must not autoload it to avoid creating cycles. +A list item of "+foo" in this flag causes symbol foo to be autoloaded, except in foo's exempt repositories, within which the Bazel-defined version of foo is still available. +A list item of "foo" triggers autoloading as above, but the Bazel-defined version of foo is not made available to the excluded repositories. This ensures that foo's external repository does not depend on the old Bazel implementation of foo +A list item of "-foo" does not trigger any autoloading, but makes the Bazel-defined version of foo inaccessible throughout the workspace. This is used to validate that the workspace is ready for foo's definition to be deleted from Bazel. +If a symbol is not named in this flag then it continues to work as normal -- no autoloading is done, nor is the Bazel-defined version suppressed. For configuration see https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/packages/AutoloadSymbols.java As a shortcut also whole repository may be used, for example +@rules\_python will autoload all Python rules. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_autoloads_in_main_repo` default: "true" + +Controls if the autoloads (set by --incompatible\_autoload\_externally) are enabled in themain repository. When enabled the rules (or other symbols) that were previously part of Bazel need to have load statements. Use buildifier to add them. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_objc_library_transition` default: "true" + +Disable objc\_library's custom transition and inherit from the top level target instead (No-op in Bazel) + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_starlark_host_transitions` default: "false" + +If set to true, rule attributes cannot set 'cfg = "host"'. Rules should set 'cfg = "exec"' instead. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_target_default_provider_fields` default: "false" + +If set to true, disable the ability to utilize the default provider via field syntax. Use provider-key syntax instead. For example, instead of using `ctx.attr.dep.files` to access `files`, utilize \`ctx.attr.dep\[DefaultInfo\].files See https://github.com/bazelbuild/bazel/issues/9014 for details. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_disable_transitions_on=<comma-separated set of options>` default: "" + +A comma-separated list of flags that cannot be used in transitions inputs or outputs. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_disallow_ctx_resolve_tools` default: "true" + +If set to true, calling the deprecated ctx.resolve\_tools API always fails. Uses of this API should be replaced by an executable or tools argument to ctx.actions.run or ctx.actions.run\_shell. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disallow_empty_glob` default: "true" + +If set to true, the default value of the `allow_empty` argument of glob() is False. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enable_deprecated_label_apis` default: "true" + +If enabled, certain deprecated APIs (native.repository\_name, Label.workspace\_name, Label.relative) can be used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]incompatible_fail_on_unknown_attributes` default: "true" + +If enabled, targets that have unknown attributes set to None fail. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_fix_package_group_reporoot_syntax` default: "true" + +In package\_group's `packages` attribute, changes the meaning of the value "//..." to refer to all packages in the current repository instead of all packages in any repository. You can use the special value "public" in place of "//..." to obtain the old behavior. This flag requires that --incompatible\_package\_group\_has\_public\_syntax also be enabled. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_locations_prefers_executable` default: "true" + +Whether a target that provides an executable expands to the executable rather than the files in <code>DefaultInfo.files</code> under $(locations ...) expansion if the number of files is not 1. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_no_attr_license` default: "true" + +If set to true, disables the function `attr.license`. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_no_implicit_file_export` default: "false" + +If set, (used) source files are package private unless exported explicitly. See https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_no_implicit_watch_label` default: "true" + +If true, then methods on <code>repository\_ctx</code> that are passed a Label will no longer automatically watch the file under that label for changes even if <code>watch = "no"</code>, and <code>repository\_ctx.path</code> no longer causes the returned path to be watched. Use <code>repository\_ctx.watch</code> instead. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_no_rule_outputs_param` default: "false" + +If set to true, disables the `outputs` parameter of the `rule()` Starlark function. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_package_group_has_public_syntax` default: "true" + +In package\_group's `packages` attribute, allows writing "public" or "private" to refer to all packages or no packages respectively. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_resolve_select_keys_eagerly` default: "false" + +If enabled, string keys in dicts passed to select() in .bzl files are immediately resolved to Labels relative to the file instead of being interpreted relative to the BUILD file they are ultimately loaded from. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_run_shell_command_string` default: "true" + +If set to true, the command parameter of actions.run\_shell will only accept string + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_simplify_unconditional_selects_in_rule_attrs` default: "true" + +If true, simplify configurable rule attributes which contain only unconditional selects; for example, if \["a"\] + select("//conditions:default", \["b"\]) is assigned to a rule attribute, it is stored as \["a", "b"\]. This option does not affect attributes of symbolic macros or attribute default values. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_stop_exporting_build_file_path` default: "false" + +If set to true, deprecated ctx.build\_file\_path will not be available. ctx.label.package + '/BUILD' can be used instead. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_stop_exporting_language_modules` default: "false" + +If enabled, certain language-specific modules (such as `cc_common`) are unavailable in user .bzl files and may only be called from their respective rules repositories. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_unambiguous_label_stringification` default: "true" + +When true, Bazel will stringify the label @//foo:bar to @//foo:bar, instead of //foo:bar. This only affects the behavior of str(), the % operator, and so on; the behavior of repr() is unchanged. See https://github.com/bazelbuild/bazel/issues/15916 for more information. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_use_cc_configure_from_rules_cc` default: "false" + +When true, Bazel will no longer allow using cc\_configure from @bazel\_tools. Please see https://github.com/bazelbuild/bazel/issues/10134 for details and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--max_computation_steps=<a long integer>` default: "0" + +The maximum number of Starlark computation steps that may be executed by a BUILD file (zero means no limit). + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--nested_set_depth_limit=<an integer>` default: "3500" + +The maximum depth of the graph internal to a depset (also known as NestedSet), above which the depset() constructor will fail. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--repositories_without_autoloads=<comma-separated set of options>` default: "" + +A list of additional repositories (beyond the hardcoded ones Bazel knows about) where autoloads are not to be added. This should typically contain repositories that are transitively depended on by a repository that may be loaded automatically (and which can therefore potentially create a cycle). + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options relating to Bzlmod output and semantics: +`--allow_yanked_versions=<a string>` multiple uses are accumulated + +Specified the module versions in the form of `<module1>@<version1>,<module2>@<version2>` that will be allowed in the resolved dependency graph even if they are declared yanked in the registry where they come from (if they are not coming from a NonRegistryOverride). Otherwise, yanked versions will cause the resolution to fail. You can also define allowed yanked version with the `BZLMOD_ALLOW_YANKED_VERSIONS` environment variable. You can disable this check by using the keyword 'all' (not recommended). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--check_bazel_compatibility=<error, warning or off>` default: "error" + +Check bazel version compatibility of Bazel modules. Valid values are `error` to escalate it to a resolution failure, `off` to disable the check, or `warning` to print a warning when mismatch detected. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--check_direct_dependencies=<off, warning or error>` default: "warning" + +Check if the direct `bazel_dep` dependencies declared in the root module are the same versions you get in the resolved dependency graph. Valid values are `off` to disable the check, `warning` to print a warning when mismatch detected or `error` to escalate it to a resolution failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]ignore_dev_dependency` default: "false" + +If true, Bazel ignores `bazel_dep` and `use_extension` declared as `dev_dependency` in the MODULE.bazel of the root module. Note that, those dev dependencies are always ignored in the MODULE.bazel if it's not the root module regardless of the value of this flag. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--lockfile_mode=<off, update, refresh or error>` default: "update" + +Specifies how and whether or not to use the lockfile. Valid values are `update` to use the lockfile and update it if there are changes, `refresh` to additionally refresh mutable information (yanked versions and previously missing modules) from remote registries from time to time, `error` to use the lockfile but throw an error if it's not up-to-date, or `off` to neither read from or write to the lockfile. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--module_mirrors=<comma-separated list of options>` default: see description + +A comma-separated list of URLs under which the source URLs of Bazel modules can be found, +in addition to and taking precedence over any registry-provided mirror URLs. Set this to +an empty value to disable the use of any mirrors not specified by the registries. The +default set of mirrors may change over time, but all downloads from mirrors are verified +by hashes stored in the registry (and thus pinned by the lockfile). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--override_module=<an equals-separated mapping of module name to path>` multiple uses are accumulated + +Override a module with a local path in the form of <module name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. + +`--registry=<a string>` multiple uses are accumulated + +Specifies the registries to use to locate Bazel module dependencies. The order is important: modules will be looked up in earlier registries first, and only fall back to later registries when they're missing from the earlier ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--vendor_dir=<a path>` default: see description + +Specifies the directory that should hold the external repositories in vendor mode, whether for the purpose of fetching them into it or using them while building. The path can be specified as either an absolute path or a path relative to the workspace directory. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options that trigger optimizations of the build time: +`--gc_thrashing_limits=<comma separated pairs of <period>:<count>>` default: "1s:2,20s:3,1m:5" + +Limits which, if reached, cause GcThrashingDetector to crash Bazel with an OOM. Each limit is specified as <period>:<count> where period is a duration and count is a positive integer. If more than --gc\_thrashing\_threshold percent of tenured space (old gen heap) remains occupied after <count> consecutive full GCs within <period>, an OOM is triggered. Multiple limits can be specified separated by commas. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]heuristically_drop_nodes` default: "false" + +If true, Blaze will remove FileState and DirectoryListingState nodes after related File and DirectoryListing node is done to save memory. We expect that it is less likely that these nodes will be needed again. If so, the program will re-evaluate them. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]incompatible_do_not_split_linking_cmdline` default: "true" + +When true, Bazel no longer modifies command line flags used for linking, and also doesn't selectively decide which flags go to the param file and which don't. See https://github.com/bazelbuild/bazel/issues/7670 for details. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]keep_state_after_build` default: "true" + +If false, Blaze will discard the inmemory state from this build when the build finishes. Subsequent builds will not have any incrementality with respect to this one. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--skyframe_high_water_mark_full_gc_drops_per_invocation=<an integer, >= 0>` default: "10" + +Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe\_high\_water\_mark\_threshold, when a full GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that full GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a full GC event occurs and that retained heap percentage threshold is exceeded. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--skyframe_high_water_mark_minor_gc_drops_per_invocation=<an integer, >= 0>` default: "10" + +Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage exceeds the threshold set by --skyframe\_high\_water\_mark\_threshold, when a minor GC event occurs, it will drop unnecessary temporary Skyframe state, up to this many times per invocation. Defaults to 10. Zero means that minor GC events will never trigger drops. If the limit is reached, Skyframe state will no longer be dropped when a minor GC event occurs and that retained heap percentage threshold is exceeded. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--skyframe_high_water_mark_threshold=<an integer>` default: "85" + +Flag for advanced configuration of Bazel's internal Skyframe engine. If Bazel detects its retained heap percentage usage is at least this threshold, it will drop unnecessary temporary Skyframe state. Tweaking this may let you mitigate wall time impact of GC thrashing, when the GC thrashing is (i) caused by the memory usage of this temporary state and (ii) more costly than reconstituting the state when it is needed. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]track_incremental_state` default: "true" + +If false, Blaze will not persist data that allows for invalidation and re-evaluation on incremental builds in order to save memory on this build. Subsequent builds will not have any incrementality with respect to this one. Usually you will want to specify --batch when setting this to false. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +Options that affect the verbosity, format or location of logging: +`--[no]announce_rc` default: "false" + +Whether to announce rc options. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]attempt_to_print_relative_paths` default: "false" + +When printing the location part of messages, attempt to use a path relative to the workspace directory or one of the directories specified by --package\_path. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--bes_backend=<a string>` default: "" + +Specifies the build event service (BES) backend endpoint in the form \[SCHEME://\]HOST\[:PORT\]. The default is to disable BES uploads. Supported schemes are grpc and grpcs (grpc with TLS enabled). If no scheme is provided, Bazel assumes grpcs. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]bes_check_preceding_lifecycle_events` default: "false" + +Sets the field check\_preceding\_lifecycle\_events\_present on PublishBuildToolEventStreamRequest which tells BES to check whether it previously received InvocationAttemptStarted and BuildEnqueued events matching the current tool event. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--bes_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header in NAME=VALUE form that will be included in BES requests. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--bes_instance_name=<a string>` default: see description + +Specifies the instance name under which the BES will persist uploaded BEP. Defaults to null. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--bes_keywords=<comma-separated list of options>` multiple uses are accumulated + +Specifies a list of notification keywords to be added the default set of keywords published to BES ("command\_name=<command\_name> ", "protocol\_name=BEP"). Defaults to none. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]bes_lifecycle_events` default: "true" + +Specifies whether to publish BES lifecycle events. (defaults to 'true'). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--bes_oom_finish_upload_timeout=<An immutable length of time.>` default: "10m" + +Specifies how long bazel should wait for the BES/BEP upload to complete while OOMing. This flag ensures termination when the JVM is severely GC thrashing and cannot make progress on any user thread. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--bes_outerr_buffer_size=<an integer>` default: "10240" + +Specifies the maximal size of stdout or stderr to be buffered in BEP, before it is reported as a progress event. Individual writes are still reported in a single event, even if larger than the specified value up to --bes\_outerr\_chunk\_size. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--bes_outerr_chunk_size=<an integer>` default: "1048576" + +Specifies the maximal size of stdout or stderr to be sent to BEP in a single message. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--bes_proxy=<a string>` default: see description + +Connect to the Build Event Service through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). + +`--bes_results_url=<a string>` default: "" + +Specifies the base URL where a user can view the information streamed to the BES backend. Bazel will output the URL appended by the invocation id to the terminal. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--bes_system_keywords=<comma-separated list of options>` multiple uses are accumulated + +Specifies a list of notification keywords to be included directly, without the "user\_keyword=" prefix included for keywords supplied via --bes\_keywords. Intended for Build service operators that set --bes\_lifecycle\_events=false and include keywords when calling PublishLifecycleEvent. Build service operators using this flag should prevent users from overriding the flag value. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--bes_timeout=<An immutable length of time.>` default: "0s" + +Specifies how long bazel should wait for the BES/BEP upload to complete after the build and tests have finished. A valid timeout is a natural number followed by a unit: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). The default value is '0' which means that there is no timeout. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--bes_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" + +Specifies whether the Build Event Service upload should block the build completion or should end the invocation immediately and finish the upload in the background. + +- `wait_for_upload_complete`: blocks at the end of the current invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. +- `nowait_for_upload_complete`: blocks at the beginning of the next invocation until all events (including lifecycle events if applicable) are uploaded and acknowledged by the backend. +- `fully_async`: blocks at the beginning of the next invocation until all events are uploaded but does not wait for acknowledgements. Events may be lost in case of (transient) failures and backends may report streams as incomplete in this mode. There is no guarantee that `FinishInvocationAttempt` or `FinishBuild` lifecycle events are sent. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--build_event_binary_file=<a string>` default: "" + +If non-empty, write a varint delimited binary representation of representation of the build event protocol to that file. This option implies --bes\_upload\_mode=wait\_for\_upload\_complete. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_event_binary_file_path_conversion` default: "true" + +Convert paths in the binary file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--build_event_binary_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" + +Specifies whether the Build Event Service upload for --build\_event\_binary\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--build_event_json_file=<a string>` default: "" + +If non-empty, write a JSON serialisation of the build event protocol to that file. This option implies --bes\_upload\_mode=wait\_for\_upload\_complete. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_event_json_file_path_conversion` default: "true" + +Convert paths in the json file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--build_event_json_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" + +Specifies whether the Build Event Service upload for --build\_event\_json\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--build_event_max_named_set_of_file_entries=<an integer>` default: "5000" + +The maximum number of entries for a single named\_set\_of\_files event; values smaller than 2 are ignored and no event splitting is performed. This is intended for limiting the maximum event size in the build event protocol, although it does not directly control event size. The total event size is a function of the structure of the set as well as the file and uri lengths, which may in turn depend on the hash function. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_event_publish_all_actions` default: "false" + +Whether all actions should be published. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--build_event_text_file=<a string>` default: "" + +If non-empty, write a textual representation of the build event protocol to that file + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_event_text_file_path_conversion` default: "true" + +Convert paths in the text file representation of the build event protocol to more globally valid URIs whenever possible; if disabled, the file:// uri scheme will always be used + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--build_event_text_file_upload_mode=<wait_for_upload_complete, nowait_for_upload_complete or fully_async>` default: "wait\_for\_upload\_complete" + +Specifies whether the Build Event Service upload for --build\_event\_text\_file should block the build completion or should end the invocation immediately and finish the upload in the background. Either 'wait\_for\_upload\_complete' (default), 'nowait\_for\_upload\_complete', or 'fully\_async'. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--build_event_upload_max_retries=<an integer>` default: "4" + +The maximum number of times Bazel should retry uploading a build event. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--[no]experimental_bep_target_summary` default: "false" + +Whether to publish TargetSummary events. + +`--[no]experimental_build_event_expand_filesets` default: "false" + +If true, expand Filesets in the BEP when presenting output files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--experimental_build_event_output_group_mode=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated + +Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED\_SET\_OF\_FILES\_ONLY', 'INLINE\_ONLY', or 'BOTH'. The default value is 'NAMED\_SET\_OF\_FILES\_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental\_build\_event\_output\_group\_mode=baseline.lcov=both + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--experimental_build_event_upload_retry_minimum_delay=<An immutable length of time.>` default: "1s" + +Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--experimental_build_event_upload_strategy=<a string>` default: see description + +Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_collect_load_average_in_profiler` default: "true" + +If enabled, the profiler collects the system's overall load average. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_collect_pressure_stall_indicators` default: "false" + +If enabled, the profiler collects the Linux PSI data. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_collect_resource_estimation` default: "false" + +If enabled, the profiler collects CPU and memory usage estimation for local actions. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_collect_skyframe_counts_in_profiler` default: "false" + +If enabled, the profiler collects SkyFunction counts in the Skyframe graph over time for key function types, like configured targets and action executions. May have a performance hit as this visits the ENTIRE Skyframe graph at every profiling time unit. Do not use this flag with performance-critical measurements. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_collect_system_network_usage` default: "true" + +If enabled, the profiler collects the system's network usage. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_collect_worker_data_in_profiler` default: "true" + +If enabled, the profiler collects worker's aggregated resource data. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--experimental_command_profile=<cpu, wall, alloc or lock>` default: see description + +Records a Java Flight Recorder profile for the duration of the command. One of the supported profiling event types (cpu, wall, alloc or lock) must be given as an argument. The profile is written to a file named after the event type under the output base directory. The syntax and semantics of this flag might change in the future to support additional profile types or output formats; use at your own risk. + +`--experimental_profile_additional_tasks=<phase, action, discover_inputs, action_check, action_lock, action_update, action_complete, action_rewinding, bzlmod, info, create_package, remote_execution, local_execution, scanner, local_parse, upload_time, remote_process_time, remote_queue, remote_setup, fetch, local_process_time, vfs_stat, vfs_dir, vfs_readlink, vfs_md5, vfs_xattr, vfs_delete, vfs_open, vfs_read, vfs_write, vfs_glob, vfs_vmfs_stat, vfs_vmfs_dir, vfs_vmfs_read, wait, thread_name, thread_sort_index, skyframe_eval, skyfunction, critical_path, critical_path_component, handle_gc_notification, local_action_counts, starlark_parser, starlark_user_fn, starlark_builtin_fn, starlark_user_compiled_fn, starlark_repository_fn, action_fs_staging, remote_cache_check, remote_download, remote_network, filesystem_traversal, worker_execution, worker_setup, worker_borrow, worker_working, worker_copying_outputs, credential_helper, conflict_check, dynamic_lock, repository_fetch, repository_vendor, repo_cache_gc_wait, spawn_log, rpc, skycache, wasm_load, wasm_exec or unknown>` multiple uses are accumulated + +Specifies additional profile tasks to be included in the profile. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_profile_include_primary_output` default: "false" + +Includes the extra "out" attribute in action events that contains the exec path to the action's primary output. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_profile_include_target_configuration` default: "false" + +Includes target configuration hash in action events' JSON profile data. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_profile_include_target_label` default: "false" + +Includes target label in action events' JSON profile data. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_record_metrics_for_all_mnemonics` default: "false" + +Controls the output of BEP ActionSummary and BuildGraphMetrics, limiting the number of mnemonics in ActionData and number of entries reported in BuildGraphMetrics.AspectCount/RuleClassCount. By default the number of types is limited to the top 20, by number of executed actions for ActionData, and instances for RuleClass and Asepcts. Setting this option will write statistics for all mnemonics, rule classes and aspects. + +`--[no]experimental_record_skyframe_metrics` default: "false" + +Controls the output of BEP BuildGraphMetrics, including expensiveto compute skyframe metrics about Skykeys, RuleClasses and Aspects.With this flag set to false BuildGraphMetrics.rule\_count and aspectfields will not be populated in the BEP. + +`--[no]experimental_run_bep_event_include_residue` default: "false" + +Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_stream_log_file_uploads` default: "false" + +Stream log file uploads directly to the remote storage rather than writing them to disk. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--experimental_workspace_rules_log_file=<a path>` default: see description + +Log certain Workspace Rules events into this file as delimited WorkspaceEvent protos. + +`--[no]generate_json_trace_profile` default: "auto" + +If enabled, Bazel profiles the build and writes a JSON-format profile into a file in the output base. View profile by loading into chrome://tracing. By default Bazel writes the profile for all build-like commands and query. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]heap_dump_on_oom` default: "false" + +Whether to manually output a heap dump if an OOM is thrown (including manual OOMs due to reaching --gc\_thrashing\_limits). The dump will be written to <output\_base>/<invocation\_id>.heapdump.hprof. This option effectively replaces -XX:+HeapDumpOnOutOfMemoryError, which has no effect for manual OOMs. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--jvm_heap_histogram_internal_object_pattern=<a valid Java regular expression>` default: "jdk\\.internal\\.vm\\.Filler.+" + +Regex for overriding the matching logic for JDK21+ JVM heap memory collection. We are relying on volatile internal G1 GC implemenation details to get a clean memory metric, this option allows us to adapt to changes in that internal implementation without having to wait for a binary release. Passed to JDK Matcher.find() + +`--[no]legacy_important_outputs` default: "false" + +Use this to suppress generation of the legacy important\_outputs field in the TargetComplete event. important\_outputs are required for Bazel to ResultStore/BTX integration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--logging=<0 <= an integer <= 6>` default: "3" + +The logging level. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--memory_profile=<a path>` default: see description + +If set, write memory usage data to the specified file at phase ends and stable heap to master log at end of build. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--memory_profile_stable_heap_parameters=<integers, separated by a comma expected in pairs>` default: "1,0" + +Tune memory profile's computation of stable heap at end of build. Should be and even number of integers separated by commas. In each pair the first integer is the number of GCs to perform. The second integer in each pair is the number of seconds to wait between GCs. Ex: 2,4,4,0 would 2 GCs with a 4sec pause, followed by 4 GCs with zero second pause + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--profile=<a path>` default: see description + +If set, profile Bazel and write data to the specified file. See https://bazel.build/advanced/performance/json-trace-profile for more information. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--profiles_to_retain=<an integer>` default: "5" + +Number of profiles to retain in the output base. If there are more than this number of profiles in the output base, the oldest are deleted until the total is under the limit. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]record_full_profiler_data` default: "false" + +By default, Bazel profiler will record only aggregated data for fast but numerous events (such as statting the file). If this option is enabled, profiler will record each event - resulting in more precise profiling data but LARGE performance hit. Option only has effect if --profile used as well. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]redirect_local_instrumentation_output_writes` default: "false" + +If true and supported, instrumentation output is redirected to be written locally on a different machine than where bazel is running on. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--remote_print_execution_messages=<failure, success or all>` default: "failure" + +Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]slim_profile` default: "true" + +Slims down the size of the JSON profile by merging events if the profile gets too large. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--starlark_cpu_profile=<a string>` default: "" + +Writes into the specified file a pprof profile of CPU usage by all Starlark threads. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--tool_tag=<a string>` default: "" + +A tool name to attribute this Bazel invocation to. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--ui_event_filters=<Convert list of comma separated event kind to list of filters>` multiple uses are accumulated + +Specifies which events to show in the UI. It is possible to add or remove events to the default ones using leading +/-, or override the default set completely with direct assignment. The set of supported event kinds include INFO, DEBUG, ERROR and more. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]write_command_log` default: "false" + +Whether or not to write the command.log file + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +Remote caching and execution options: +`--downloader_config=<a path>` default: see description + +Specify a file to configure the remote downloader with. This file consists of lines, each of which starts with a directive ( `allow`, `block` or `rewrite`) followed by either a host name (for `allow` and `block`) or two patterns, one to match against, and one to use as a substitute URL, with back-references starting from `$1`. It is possible for multiple `rewrite` directives for the same URL to be given, and in this case multiple URLs will be returned. + +`--experimental_circuit_breaker_strategy=<failure>` default: see description + +Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_remote_cache_compression_threshold=<an integer>` default: "100" + +The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote\_cache\_compression is set. + +`--[no]experimental_remote_cache_lease_extension` default: "false" + +If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. + +`--experimental_remote_cache_ttl=<An immutable length of time.>` default: "3h" + +The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_remote_capture_corrupted_outputs=<a path>` default: see description + +A path to a directory where the corrupted outputs will be captured to. + +`--[no]experimental_remote_discard_merkle_trees` default: "true" + +If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. + +`--experimental_remote_downloader=<a string>` default: see description + +A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote\_asset.proto + +`--[no]experimental_remote_downloader_local_fallback` default: "false" + +Whether to fall back to the local downloader if remote downloader fails. + +`--[no]experimental_remote_downloader_propagate_credentials` default: "false" + +Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. + +`--[no]experimental_remote_execution_keepalive` default: "false" + +Whether to use keepalive for remote execution calls. + +`--experimental_remote_failure_rate_threshold=<an integer in 0-100 range>` default: "10" + +Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_remote_failure_window_interval=<An immutable length of time.>` default: "60s" + +The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_remote_mark_tool_inputs` default: "false" + +If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. + +`--[no]experimental_remote_merkle_tree_cache` default: "false" + +If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental\_remote\_merkle\_tree\_cache\_size. + +`--experimental_remote_merkle_tree_cache_size=<a long integer>` default: "1000" + +The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. + +`--experimental_remote_output_service=<a string>` default: see description + +HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. + +`--experimental_remote_output_service_output_path_prefix=<a string>` default: "" + +The path under which the contents of output directories managed by the --experimental\_remote\_output\_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. + +`--[no]experimental_remote_require_cached` default: "false" + +If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. + +`--experimental_remote_scrubbing_config=<Converts to a Scrubber>` default: see description + +Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote\_scrubbing.proto). + +This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. + +Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. + +Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. + +In order to successfully use this feature, you likely want to set a custom --host\_platform together with --experimental\_platform\_in\_output\_dir (to normalize output prefixes) and --incompatible\_strict\_action\_env (to normalize environment variables). + +`--[no]guard_against_concurrent_changes` default: "lite" + +Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]remote_accept_cached` default: "true" + +Whether to accept remotely cached action results. + +`--remote_build_event_upload=<all or minimal>` default: "minimal" + +If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. +If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. +Default to 'minimal'. + +`--remote_bytestream_uri_prefix=<a string>` default: see description + +The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote\_executor and --remote\_instance\_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "${hostname}/${instance\_name}". + +`--remote_cache=<a string>` default: see description + +A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching + +`--[no]remote_cache_async` default: "true" + +If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. + +`--[no]remote_cache_compression` default: "false" + +If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental\_remote\_cache\_compression\_threshold. + +`--remote_cache_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header that will be included in cache requests: --remote\_cache\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +`--remote_default_exec_properties=<a 'name=value' assignment>` multiple uses are accumulated + +Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec\_properties. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_default_platform_properties=<a string>` default: "" + +Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote\_execution\_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. + +`--remote_download_regex=<a valid Java regular expression>` multiple uses are accumulated + +Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote\_download\_outputs. Multiple patterns may be specified by repeating this flag. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_downloader_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header that will be included in remote downloader requests: --remote\_downloader\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +`--remote_exec_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header that will be included in execution requests: --remote\_exec\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +`--remote_execution_priority=<an integer>` default: "0" + +The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. + +`--remote_executor=<a string>` default: see description + +HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. + +`--remote_grpc_log=<a path>` default: see description + +If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). + +`--remote_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header that will be included in requests: --remote\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +`--remote_instance_name=<a string>` default: "" + +Value to pass as instance\_name in the remote execution API. + +`--[no]remote_local_fallback` default: "false" + +Whether to fall back to standalone local execution strategy if remote execution fails. + +`--remote_local_fallback_strategy=<a string>` default: "local" + +Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. + +`--remote_max_connections=<an integer>` default: "100" + +Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. +For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote\_max\_connections concurrent requests. +For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--remote_proxy=<a string>` default: see description + +Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). + +`--remote_result_cache_priority=<an integer>` default: "0" + +The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. + +`--remote_retries=<an integer>` default: "5" + +The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. + +`--remote_retry_max_delay=<An immutable length of time.>` default: "5s" + +The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +`--remote_timeout=<An immutable length of time.>` default: "60s" + +The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +`--[no]remote_upload_local_results` default: "true" + +Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. + +`--[no]remote_verify_downloads` default: "true" + +If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. + +Miscellaneous options, not otherwise categorized.: +`--build_metadata=<a 'name=value' assignment>` multiple uses are accumulated + +Custom key-value string pairs to supply in a build event. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--color=<yes, no or auto>` default: "auto" + +Use terminal controls to colorize output. + +`--config=<a string>` multiple uses are accumulated + +Selects additional config sections from the rc files; for every <command>, it also pulls in the options from <command>:<config> if such a section exists; if this section doesn't exist in any .rc file, Blaze fails with an error. The config sections and flag combinations they are equivalent to are located in the tools/\*.blazerc config files. + +`--credential_helper=<Path to a credential helper. It may be absolute, relative to the PATH environment variable, or %workspace%-relative. The path be optionally prefixed by a scope followed by an '='. The scope is a domain name, optionally with a single leading '*' wildcard component. A helper applies to URIs matching its scope, with more specific scopes preferred. If a helper has no scope, it applies to every URI.>` multiple uses are accumulated + +Configures a credential helper conforming to the <a href="https://github.com/EngFlow/credential-helper-spec">Credential Helper Specification</a> to use for retrieving authorization credentials for repository fetching, remote caching and execution, and the build event service. + +Credentials supplied by a helper take precedence over credentials supplied by `--google_default_credentials`, `--google_credentials`, a `.netrc` file, or the auth parameter to `repository_ctx.download()` and `repository_ctx.download_and_extract()`. + +May be specified multiple times to set up multiple helpers. + +See https://blog.engflow.com/2023/10/09/configuring-bazels-credential-helper/ for instructions. + +`--credential_helper_cache_duration=<An immutable length of time.>` default: "30m" + +How long to cache credentials for if the credential helper doesn't return an expiration time. Changing the value of this flag clears the cache. + +`--credential_helper_timeout=<An immutable length of time.>` default: "10s" + +Configures the timeout for a credential helper. + +Credential helpers failing to respond within this timeout will fail the invocation. + +`--curses=<yes, no or auto>` default: "auto" + +Use terminal cursor controls to minimize scrolling output. + +`--disk_cache=<a path>` default: see description + +A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. + +`--[no]enable_platform_specific_config` default: "true" + +If true, Bazel picks up host-OS-specific config lines from bazelrc files. For example, if the host OS is Linux and you run bazel build, Bazel picks up lines starting with build:linux. Supported OS identifiers are linux, macos, windows, freebsd, and openbsd. Enabling this flag is equivalent to using --config=linux on Linux, --config=windows on Windows, etc. + +`--experimental_action_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" + +How long the server must remain idle before a garbage collection of the action cache is attempted. Ineffectual unless --experimental\_action\_cache\_gc\_max\_age is nonzero. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--experimental_action_cache_gc_max_age=<An immutable length of time.>` default: "0" + +If set to a nonzero value, the action cache will be periodically garbage collected to remove entries older than this age. Garbage collection occurs in the background once the server has become idle, as determined by the --experimental\_action\_cache\_gc\_idle\_delay and --experimental\_action\_cache\_gc\_threshold flags. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--experimental_action_cache_gc_threshold=<an integer in 0-100 range>` default: "10" + +The percentage of stale action cache entries required for garbage collection to be triggered. Ineffectual unless --experimental\_action\_cache\_gc\_max\_age is nonzero. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--experimental_disk_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" + +How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental\_disk\_cache\_gc\_max\_size and/or --experimental\_disk\_cache\_gc\_max\_age. + +`--experimental_disk_cache_gc_max_age=<An immutable length of time.>` default: "0" + +If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. + +`--experimental_disk_cache_gc_max_size=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" + +If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. + +`--[no]experimental_enable_thread_dump` default: "false" + +Whether to enable thread dumps. If true, Bazel will dump the state of all threads (including virtual threads) to a file every --experimental\_thread\_dump\_interval, or after action execution being inactive for --experimental\_thread\_dump\_action\_execution\_inactivity\_duration. The dumps will be written to the <output\_base>/server/thread\_dumps/ directory. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--experimental_install_base_gc_max_age=<An immutable length of time.>` default: "30d" + +How long an install base must go unused before it's eligible for garbage collection. If nonzero, the server will attempt to garbage collect other install bases when idle. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]experimental_rule_extension_api` default: "true" + +Enable experimental rule extension API and subrule APIs + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_thread_dump_action_execution_inactivity_duration=<An immutable length of time.>` default: "0" + +Dump the threads when action execution being inactive for this duration. If zero, no thread dumps are written for action execution being inactive. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--experimental_thread_dump_interval=<An immutable length of time.>` default: "0" + +How often to dump the threads periodically. If zero, no thread dumps are written periodically. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]experimental_windows_watchfs` default: "false" + +If true, experimental Windows support for --watchfs is enabled. Otherwise --watchfsis a non-op on Windows. Make sure to also enable --watchfs. + +`--google_auth_scopes=<comma-separated list of options>` default: "https://www.googleapis.com/auth/cloud-platform" + +A comma-separated list of Google Cloud authentication scopes. + +`--google_credentials=<a string>` default: see description + +Specifies the file to get authentication credentials from. See https://cloud.google.com/docs/authentication for details. + +`--[no]google_default_credentials` default: "false" + +Whether to use 'Google Application Default Credentials' for authentication. See https://cloud.google.com/docs/authentication for details. Disabled by default. + +`--grpc_keepalive_time=<An immutable length of time.>` default: see description + +Configures keep-alive pings for outgoing gRPC connections. If this is set, then Bazel sends pings after this much time of no read operations on the connection, but only if there is at least one pending gRPC call. Times are treated as second granularity; it is an error to set a value less than one second. By default, keep-alive pings are disabled. You should coordinate with the service owner before enabling this setting. For example to set a value of 30 seconds to this flag, it should be done as this --grpc\_keepalive\_time=30s + +`--grpc_keepalive_timeout=<An immutable length of time.>` default: "20s" + +Configures a keep-alive timeout for outgoing gRPC connections. If keep-alive pings are enabled with --grpc\_keepalive\_time, then Bazel times out a connection if it does not receive a ping reply after this much time. Times are treated as second granularity; it is an error to set a value less than one second. If keep-alive pings are disabled, then this setting is ignored. + +`--[no]incompatible_disable_non_executable_java_binary` default: "false" + +If true, java\_binary is always executable. create\_executable attribute is removed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_repo_env_ignores_action_env` default: "true" + +If true, <code>--action\_env=NAME=VALUE</code> will no longer affect repository rule and module extension environments. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--inject_repository=<an equals-separated mapping of repository name to path>` multiple uses are accumulated + +Adds a new repository with a local path in the form of <repository name>=<path>. This only takes effect with --enable\_bzlmod and is equivalent to adding a corresponding `local_repository` to the root module's MODULE.bazel file via `use_repo_rule`. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%', it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous injections. + +`--invocation_id=<a UUID>` default: "" + +Unique identifier, in UUID format, for the command being run. If explicitly specified uniqueness must be ensured by the caller. The UUID is printed to stderr, the BEP and remote execution protocol. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--override_repository=<an equals-separated mapping of repository name to path>` multiple uses are accumulated + +Override a repository with a local path in the form of <repository name>=<path>. If the given path is an absolute path, it will be used as it is. If the given path is a relative path, it is relative to the current working directory. If the given path starts with '%workspace%, it is relative to the workspace root, which is the output of `bazel info workspace`. If the given path is empty, then remove any previous overrides. + +`--[no]progress_in_terminal_title` default: "false" + +Show the command progress in the terminal title. Useful to see what bazel is doing when having multiple terminal tabs. + +`--[no]show_progress` default: "true" + +Display progress messages during a build. + +`--show_progress_rate_limit=<a double>` default: "0.2" + +Minimum number of seconds between progress messages in the output. + +`--[no]show_timestamps` default: "false" + +Include timestamps in messages + +`--tls_certificate=<a string>` default: see description + +Specify a path to a TLS certificate that is trusted to sign server certificates. + +`--tls_client_certificate=<a string>` default: see description + +Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication. + +`--tls_client_key=<a string>` default: see description + +Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication. + +`--ui_actions_shown=<an integer>` default: "8" + +Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]watchfs` default: "false" + +On Linux/macOS: If true, bazel tries to use the operating system's file watch service for local changes instead of scanning every file for a change. On Windows: this flag currently is a non-op but can be enabled in conjunction with --experimental\_windows\_watchfs. On any OS: The behavior is undefined if your workspace is on a network file system, and files are edited on a remote machine. + +## Aquery Options + +Inherits all options from [build](#build). + +Options relating to query output and semantics: +`--aspect_deps=<off, conservative or precise>` default: "conservative" + +How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]consistent_labels` default: "false" + +If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]experimental_explicit_aspects` default: "false" + +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]graph:factored` default: "true" + +If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--graph:node_limit=<an integer>` default: "512" + +The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]implicit_deps` default: "true" + +If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]include_artifacts` default: "true" + +Includes names of the action inputs and outputs in the output (potentially large). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]include_aspects` default: "true" + +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]include_commandline` default: "true" + +Includes the content of the action command lines in the output (potentially large). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]include_file_write_contents` default: "false" + +Include the file contents for the FileWrite, SourceSymlinkManifest, and RepoMappingManifest actions (potentially large). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]include_param_files` default: "false" + +Include the content of the param files used in the command (potentially large). Note: Enabling this flag will automatically enable the --include\_commandline flag. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]include_pruned_inputs` default: "true" + +Includes action inputs that were pruned during action execution. Only affects actions that discover inputs and have been executed in a previous invocation. Only takes effect if --include\_artifacts is also set. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]incompatible_package_group_includes_double_slash` default: "true" + +If enabled, when outputting package\_group's `packages` attribute, the leading `//` will not be omitted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]infer_universe_scope` default: "false" + +If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g. `allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]line_terminator_null` default: "false" + +Whether each format is terminated with \\0 instead of newline. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]nodep_deps` default: "true" + +If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--output=<a string>` default: "text" + +The format in which the aquery results should be printed. Allowed values for aquery are: text, textproto, proto, streamed\_proto, jsonproto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--output_file=<a string>` default: "" + +When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query > file</code>. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:default_values` default: "true" + +If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:definition_stack` default: "false" + +Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:flatten_selects` default: "true" + +If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]proto:include_attribute_source_aspects` default: "false" + +Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:include_starlark_rule_env` default: "true" + +Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:include_synthetic_attribute_hash` default: "false" + +Whether or not to calculate and populate the $internal\_attr\_hash attribute. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:instantiation_stack` default: "false" + +Populate the instantiation call stack of each rule. Note that this requires the stack to be present + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:locations` default: "true" + +Whether to output location information in proto output at all. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" + +Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:rule_classes` default: "false" + +Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:rule_inputs_and_outputs` default: "true" + +Whether or not to populate the rule\_input and rule\_output fields. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--query_file=<a string>` default: "" + +If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--[no]relative_locations` default: "false" + +If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]skyframe_state` default: "false" + +Without performing extra analysis, dump the current Action Graph from Skyframe. Note: Specifying a target with --skyframe\_state is currently not supported. This flag is only available with --output=proto or --output=textproto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]tool_deps` default: "true" + +Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--universe_scope=<comma-separated list of options>` default: "" + +A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options that control build execution: +`--[no]experimental_persistent_aar_extractor` default: "false" + +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_remotable_source_manifests` default: "false" + +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_split_coverage_postprocessing` default: "false" + +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_strict_fileset_output` default: "false" + +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_modify_execution_info_additive` default: "true" + +When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated + +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'. _=+x,._ =-y,. _=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions._ +_'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions._ +_'(?!Genrule)._ =-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` + +Enable persistent Android dex and desugar actions by using workers. + +Expands to: + +`--internal_persistent_android_dex_desugar` + +`--strategy=Desugar=worker` + +`--strategy=DexBuilder=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` + +Enable persistent Android resource processor by using workers. + +Expands to: + +`--internal_persistent_busybox_tools` + +`--strategy=AaptPackage=worker` + +`--strategy=AndroidResourceParser=worker` + +`--strategy=AndroidResourceValidator=worker` + +`--strategy=AndroidResourceCompiler=worker` + +`--strategy=RClassGenerator=worker` + +`--strategy=AndroidResourceLink=worker` + +`--strategy=AndroidAapt2=worker` + +`--strategy=AndroidAssetMerger=worker` + +`--strategy=AndroidResourceMerger=worker` + +`--strategy=AndroidCompiledResourceMerger=worker` + +`--strategy=ManifestMerger=worker` + +`--strategy=AndroidManifestMerger=worker` + +`--strategy=Aapt2Optimize=worker` + +`--strategy=AARGenerator=worker` + +`--strategy=ProcessDatabinding=worker` + +`--strategy=GenerateDataBindingBaseClasses=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` + +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: + +`--persistent_android_dex_desugar` + +`--internal_persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` + +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: + +`--persistent_android_resource_processor` + +`--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +`--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +`--modify_execution_info=AARGenerator=+supports-multiplex-workers` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` + +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: + +`--internal_persistent_multiplex_busybox_tools` + +`--persistent_multiplex_android_resource_processor` + +`--persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" + +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: +`--android_compiler=<a string>` default: see description + +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" + +Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_platforms=<a build target label>` default: "" + +Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--cc_output_directory_tag=<a string>` default: "" + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compiler=<a string>` default: see description + +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" + +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" + +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" + +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--custom_malloc=<a build target label>` default: see description + +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_include_xcode_execution_requirements` default: "false" + +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version\_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_prefer_mutual_xcode` default: "true" + +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--extra_execution_platforms=<comma-separated list of options>` default: "" + +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated + +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--grte_top=<a label>` default: see description + +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_compiler=<a string>` default: see description + +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--host_grte_top=<a label>` default: see description + +If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" + +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]incompatible_bazel_test_exec_run_under` default: "true" + +If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run\_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_builtin_objc_strip_action` default: "true" + +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" + +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" + +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_remove_legacy_whole_archive` default: "true" + +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strip_executable_safely` default: "false" + +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]interface_shared_objects` default: "true" + +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--minimum_os_version=<a string>` default: see description + +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_mappings=<a main workspace-relative path>` default: "" + +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--platforms=<a build target label>` default: "" + +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_path=<a string>` default: see description + +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" + +Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version=<a string>` default: see description + +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" + +The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options that control the output of the command: +`--[no]apple_generate_dsym` default: "false" + +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]build_runfile_links` default: "true" + +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_runfile_manifests` default: "true" + +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_test_dwp` default: "false" + +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" + +Sets the suffixes of header files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" + +Sets the suffixes of source files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" + +Run extra actions for alternative Java api versions in a proto\_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_save_feature_state` default: "false" + +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fission=<a set of compilation modes>` default: "no" + +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_always_include_files_in_data` default: "true" + +If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" + +If enabled, the <binary>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" + +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" + +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]objc_generate_linkmap` default: "false" + +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]save_temps` default: "false" + +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible\_repo\_env\_ignores\_action\_env</code> is true, all <code>name=value</code> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--allowed_cpu_values=<comma-separated set of options>` default: "" + +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]android_databinding_use_androidx` default: "true" + +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]android_databinding_use_v3_4_args` default: "true" + +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--android_dynamic_mode=<off, default or fully>` default: "off" + +Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" + +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +`--[no]android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]build_python_zip` default: "auto" + +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]collect_code_coverage` default: "false" + +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compilation_mode=<fastbuild, dbg or opt>` \[ `-c`\] default: "fastbuild" + +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--copt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cpu=<a string>` default: "" + +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_absolute_path=<a string>` default: see description + +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_instrument=<a string>` default: see description + +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_profile=<a build target label>` default: see description + +The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cxxopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--define=<a 'name=value' assignment>` multiple uses are accumulated + +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--dynamic_mode=<off, default or fully>` default: "default" + +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_propeller_optimize_absolute_paths` default: "true" + +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_remaining_fdo_absolute_paths` default: "true" + +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_runfiles` default: "auto" + +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_action_listener=<a build target label>` multiple uses are accumulated + +Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_compress_java_resources` default: "false" + +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_databinding_v2` default: "true" + +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" + +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" + +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" + +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]experimental_omitfp` default: "false" + +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_output_paths=<off or strip>` default: "off" + +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated + +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_platform_in_output_dir` default: "false" + +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_py_binaries_include_label` default: "false" + +py\_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_llvm_covmap` default: "false" + +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" + +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fdo_instrument=<a string>` default: see description + +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_optimize=<a string>` default: see description + +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` \- you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_prefetch_hints=<a build target label>` default: see description + +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_profile=<a build target label>` default: see description + +The fdo\_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host\_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]force_pic` default: "false" + +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" + +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_copt=<a string>` multiple uses are accumulated + +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cpu=<a string>` default: "" + +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cxxopt=<a string>` multiple uses are accumulated + +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_auto_exec_groups` default: "false" + +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_merge_genfiles_directory` default: "true" + +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_target_cpu_from_platform` default: "true" + +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]instrument_test_targets` default: "false" + +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" + +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]legacy_whole_archive` default: "true" + +Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +`--linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltobackendopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO backend step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltoindexopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO indexing step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--memprof_profile=<a build target label>` default: see description + +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]objc_debug_with_GLIBCXX` default: "false" + +If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]objc_enable_binary_stripping` default: "false" + +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--objccopt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_suffix=<a string>` default: see description + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--propeller_optimize=<a build target label>` default: see description + +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description + +Absolute path name of cc\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description + +Absolute path name of ld\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--run_under=<a prefix in front of command>` default: see description + +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]share_native_deps` default: "true" + +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]stamp` default: "false" + +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--strip=<always, sometimes or never>` default: "sometimes" + +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--stripopt=<a string>` multiple uses are accumulated + +Additional options to pass to strip when generating a '<name>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xbinary_fdo=<a build target label>` default: see description + +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]check_visibility` default: "true" + +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]desugar_for_android` default: "true" + +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]desugar_java8_libs` default: "false" + +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]enforce_constraints` default: "true" + +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" + +When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" + +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]incompatible_check_testonly_for_output_files` default: "false" + +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_android_rules` default: "false" + +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" + +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]one_version_enforcement_on_java_tests` default: "true" + +When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_native_rules_allowlist=<a build target label>` default: see description + +An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]strict_filesets` default: "false" + +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" + +Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" + +Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]strict_system_includes` default: "false" + +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--target_environment=<a build target label>` multiple uses are accumulated + +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Options that affect the signing outputs of a build: +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" + +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]device_debug_entitlements` default: "true" + +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--ios_signing_cert_name=<a string>` default: see description + +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" + +If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_objc_alwayslink_by_default` default: "false" + +If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_python_disallow_native_rules` default: "false" + +When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that govern the behavior of the test environment or test runner: +`--[no]allow_analysis_failures` default: "false" + +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--analysis_testing_deps_limit=<an integer>` default: "2000" + +Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" + +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated + +Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by \[-\| _\]<float> (eg. memory=HOST\_RAM_.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +`--[no]experimental_android_use_parallel_dex2oat` default: "false" + +Use dex2oat in parallel to possibly speed up android\_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]ios_memleaks` default: "false" + +Enable checking for memory leaks in ios\_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--ios_simulator_device=<a string>` default: see description + +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated + +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/. _,-//foo/bar/._@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" + +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +`--[no]zip_undeclared_test_outputs` default: "false" + +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +Options that trigger optimizations of the build time: +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" + +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_dotd_files` default: "true" + +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_jdeps_files` default: "true" + +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" + +When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" + +Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]process_headers_in_dependencies` default: "false" + +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]trim_test_configuration` default: "true" + +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +Options that affect the verbosity, format or location of logging: +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" + +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]verbose_visibility_errors` default: "false" + +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated + +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_default_to_explicit_init_py` default: "false" + +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Miscellaneous options, not otherwise categorized.: +`--[no]cache_test_results` \[ `-t`\] default: "auto" + +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +`--[no]experimental_cancel_concurrent_tests` default: "never" + +If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_fetch_all_coverage_outputs` default: "false" + +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_generate_llvm_lcov` default: "false" + +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" + +Enables reduced classpaths for Java compilations. + +`--[no]experimental_run_android_lint_on_java_rules` default: "false" + +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[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. + +`--host_java_launcher=<a build target label>` default: see description + +The Java launcher used by tools that are executed during a build. + +`--host_javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac when building tools that are executed during a build. + +`--host_jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. + +`--[no]incompatible_check_sharding_support` default: "true" + +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_exclusive_test_sandboxed` default: "true" + +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strict_action_env` default: "false" + +If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated + +Additional options to pass to the J2ObjC tool. + +`--java_debug` + +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. + +Expands to: + +`--test_arg=--wrapper_script_flag=--debug` + +`--test_output=streamed` + +`--test_strategy=exclusive` + +`--test_timeout=9999` + +`--nocache_test_results` + +`--[no]java_deps` default: "true" + +Generate dependency information (for now, compile-time classpath) per Java target. + +`--[no]java_header_compilation` default: "true" + +Compile ijars directly from source. + +`--java_language_version=<a string>` default: "" + +The Java language version + +`--java_launcher=<a build target label>` default: see description + +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +`--java_runtime_version=<a string>` default: "local\_jdk" + +The Java runtime version + +`--javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac. + +`--jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. + +`--legacy_main_dex_list_generator=<a build target label>` default: see description + +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +`--optimizing_dexer=<a build target label>` default: see description + +Specifies a binary to use to do dexing without sharding. + +`--plugin=<a build target label>` multiple uses are accumulated + +Plugins to use in the build. Currently works with java\_plugin. + +`--proguard_top=<a build target label>` default: see description + +Specifies which version of ProGuard to use for code removal when building a Java binary. + +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" + +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]proto_profile` default: "true" + +Whether to pass profile\_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_profile_path=<a build target label>` default: see description + +The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--protocopt=<a string>` multiple uses are accumulated + +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]runs_per_test_detects_flakes` default: "false" + +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +`--shell_executable=<a path>` default: see description + +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--test_arg=<a string>` multiple uses are accumulated + +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +`--test_filter=<a string>` default: see description + +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +`--test_result_expiration=<an integer>` default: "-1" + +This option is deprecated and has no effect. + +`--[no]test_runner_fail_fast` default: "false" + +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" + +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. + +`--tool_java_language_version=<a string>` default: "" + +The Java language version used to execute the tools that are needed during a build + +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" + +The Java runtime version used to execute tools during the build + +`--[no]use_ijars` default: "true" + +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## Build Options + +Options that control build execution: +`--[no]allow_one_action_on_resource_unavailable` default: "true" + +If set, allow at least one action to run even if the resource is not enough or unavailable. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]check_up_to_date` default: "false" + +Don't perform the build, just check if it is up-to-date. If all targets are up-to-date, the build completes successfully. If any step needs to be executed an error is reported and the build fails. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--dynamic_local_execution_delay=<an integer>` default: "1000" + +How many milliseconds should local execution be delayed, if remote execution was faster during a build at least once? + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--dynamic_local_strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated + +The local strategies, in order, to use for the given mnemonic - the first applicable strategy is used. For example, `worker,sandboxed` runs actions that support persistent workers using the worker strategy, and all others using the sandboxed strategy. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `worker,sandboxed`, or `worker,sandboxed,standalone` if `experimental_local_lockfree_output` is set. Takes \[mnemonic=\]local\_strategy\[,local\_strategy,...\] + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--dynamic_remote_strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated + +The remote strategies, in order, to use for the given mnemonic - the first applicable strategy is used. If no mnemonic is given, the list of strategies is used as the fallback for all mnemonics. The default fallback list is `remote`, so this flag usually does not need to be set explicitly. Takes \[mnemonic=\]remote\_strategy\[,remote\_strategy,...\] + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]experimental_async_execution` default: "false" + +If set to true, Bazel is allowed to run action in a virtual thread. The number of actions in flight is still capped with --jobs. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--experimental_async_execution_max_concurrent_actions=<an integer>` default: "5000" + +The number of maximum concurrent actions to run with async execution. If the value is less than --jobs, it is clamped to --jobs. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_docker_image=<a string>` default: "" + +Specify a Docker image name (e.g. "ubuntu:latest") that should be used to execute a sandboxed action when using the docker strategy and the action itself doesn't already have a container-image attribute in its remote\_execution\_properties in the platform description. The value of this flag is passed verbatim to 'docker run', so it supports the same syntax and mechanisms as Docker itself. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_docker_use_customized_images` default: "true" + +If enabled, injects the uid and gid of the current user into the Docker image before using it. This is required if your build / tests depend on the user having a name and home directory inside the container. This is on by default, but you can disable it in case the automatic image customization feature doesn't work in your case or you know that you don't need it. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_dynamic_exclude_tools` default: "true" + +When set, targets that are build "for tool" are not subject to dynamic execution. Such targets are extremely unlikely to be built incrementally and thus not worth spending local cycles on. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--experimental_dynamic_local_load_factor=<a double>` default: "0" + +Controls how much load from dynamic execution to put on the local machine. This flag adjusts how many actions in dynamic execution we will schedule concurrently. It is based on the number of CPUs Blaze thinks is available, which can be controlled with the --local\_resources=cpu= flag. +If this flag is 0, all actions are scheduled locally immediately. If > 0, the amount of actions scheduled locally is limited by the number of CPUs available. If < 1, the load factor is used to reduce the number of locally scheduled actions when the number of actions waiting to schedule is high. This lessens the load on the local machine in the clean build case, where the local machine does not contribute much. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--experimental_dynamic_slow_remote_time=<An immutable length of time.>` default: "0" + +If >0, the time a dynamically run action must run remote-only before we prioritize its local execution to avoid remote timeouts. This may hide some problems on the remote execution system. Do not turn this on without monitoring of remote execution issues. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]experimental_enable_docker_sandbox` default: "false" + +Enable Docker-based sandboxing. This option has no effect if Docker is not installed. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_inmemory_sandbox_stashes` default: "false" + +If set to true, the contents of stashed sandboxes for reuse\_sandbox\_directories will be tracked in memory. This reduces the amount of I/O needed during reuse. Depending on the build this flag may improve wall time. Depending on the build as well this flag may use a significant amount of additional memory. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_sandbox_async_tree_delete_idle_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "4" + +If 0, sandboxes are deleted as soon as actions finish, blocking action completion. If greater than 0, sandboxes are deleted asynchronously in the background without blocking action completion. Asynchronous deletion uses a single thread while a command is running, but ramps up to as many threads as the value of this flag once the server becomes idle. Set to `auto` to use as many threads as the number of CPUs. A server shutdown blocks on any pending asynchronous deletions. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_sandbox_enforce_resources_regexp=<a valid Java regular expression>` default: "" + +If true, actions whose mnemonic matches the input regex will have their resources request enforced as limits, overriding the value of --experimental\_sandbox\_limits, if the resource type supports it. For example a test that declares cpu:3 and resources:memory:10, will run with at most 3 cpus and 10 megabytes of memory. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_sandbox_limits=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated + +If > 0, each Linux sandbox will be limited to the given amount for the specified resource. Requires --incompatible\_use\_new\_cgroup\_implementation and overrides --experimental\_sandbox\_memory\_limit\_mb. Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_sandbox_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" + +If > 0, each Linux sandbox will be limited to the given amount of memory (in MB). Requires cgroups v1 or v2 and permissions for the users to the cgroups dir. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_shrink_worker_pool` default: "false" + +If enabled, could shrink worker pool if worker memory pressure is high. This flag works only when flag experimental\_total\_worker\_memory\_limit\_mb is enabled. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--experimental_total_worker_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" + +If this limit is greater than zero idle workers might be killed if the total memory usage of all workers exceed the limit. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]experimental_use_hermetic_linux_sandbox` default: "false" + +If set to true, do not mount root, only mount whats provided with sandbox\_add\_mount\_pair. Input files will be hardlinked to the sandbox instead of symlinked to from the sandbox. If action input files are located on a filesystem different from the sandbox, then the input files will be copied instead. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_use_windows_sandbox` default: "false" + +Use Windows sandbox to run actions. If "yes", the binary provided by --experimental\_windows\_sandbox\_path must be valid and correspond to a supported version of sandboxfs. If "auto", the binary may be missing or not compatible. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_windows_sandbox_path=<a string>` default: "BazelSandbox.exe" + +Path to the Windows sandbox binary to use when --experimental\_use\_windows\_sandbox is true. If a bare name, use the first binary of that name found in the PATH. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_worker_allowlist=<comma-separated set of options>` default: see description + +If non-empty, only allow using persistent workers with the given worker key mnemonic. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]experimental_worker_cancellation` default: "false" + +If enabled, Bazel may send cancellation requests to workers that support them. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_worker_memory_limit_mb=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "0" + +If this limit is greater than zero, workers might be killed if the memory usage of the worker exceeds the limit. If not used together with dynamic execution and `--experimental_dynamic_ignore_local_signals=9`, this may crash your build. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--experimental_worker_metrics_poll_interval=<An immutable length of time.>` default: "5s" + +The interval between collecting worker metrics and possibly attempting evictions. Cannot effectively be less than 1s for performance reasons. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]experimental_worker_multiplex_sandboxing` default: "false" + +If enabled, multiplex workers with a 'supports-multiplex-sandboxing' execution requirement will run in a sandboxed environment, using a separate sandbox directory per work request. Multiplex workers with the execution requirement are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_worker_sandbox_hardening` default: "false" + +If enabled, workers are run in a hardened sandbox, if the implementation allows it. If hardening is enabled then tmp directories are distinct for different workers. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_worker_sandbox_inmemory_tracking=<a string>` multiple uses are accumulated + +A worker key mnemonic for which the contents of the sandbox directory are tracked in memory. This may improve build performance at the cost of additional memory usage. Only affects sandboxed workers. May be specified multiple times for different mnemonics. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_worker_strict_flagfiles` default: "false" + +If enabled, actions arguments for workers that do not follow the worker specification will cause an error. Worker arguments must have exactly one @flagfile argument as the last of its list of arguments. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--genrule_strategy=<comma-separated list of options>` default: "" + +Specify how to execute genrules. This flag will be phased out. Instead, use --spawn\_strategy=<value> to control all actions or --strategy=Genrule=<value> to control genrules only. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]incompatible_use_new_cgroup_implementation` default: "true" + +If true, use the new implementation for cgroups. The old implementation only supports the memory controller and ignores the value of --experimental\_sandbox\_limits. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]internal_spawn_scheduler` default: "true" + +Placeholder option so that we can tell in Blaze whether the spawn scheduler was enabled. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--jobs=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` \[ `-j`\] default: "auto" + +The number of concurrent jobs to run. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". Values must be between 1 and 5000. Values above 2500 may cause memory issues. "auto" calculates a reasonable default based on host resources. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]keep_going` \[ `-k`\] default: "false" + +Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" + +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--[no]reuse_sandbox_directories` default: "true" + +If set to true, directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--sandbox_base=<a string>` default: "" + +Lets the sandbox create its sandbox directories underneath this path. Specify a path on tmpfs (like /run/shm) to possibly improve performance a lot when your build / tests have many input files. Note: You need enough RAM and free space on the tmpfs to hold output and intermediate files generated by running actions. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]sandbox_enable_loopback_device` default: "true" + +If true, a loopback device will be set up in the linux-sandbox network namespace for local actions. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]sandbox_explicit_pseudoterminal` default: "false" + +Explicitly enable the creation of pseudoterminals for sandboxed actions. Some linux distributions require setting the group id of the process to 'tty' inside the sandbox in order for pseudoterminals to function. If this is causing issues, this flag can be disabled to enable other groups to be used. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--sandbox_tmpfs_path=<an absolute path>` multiple uses are accumulated + +For sandboxed actions, mount an empty, writable directory at this absolute path (if supported by the sandboxing implementation, ignored otherwise). + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]skip_incompatible_explicit_targets` default: "false" + +Skip incompatible targets that are explicitly listed on the command line. By default, building such targets results in an error but they are silently skipped when this option is enabled. See: https://bazel.build/extending/platforms#skipping-incompatible-targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--spawn_strategy=<comma-separated list of options>` default: "" + +Specify how spawn actions are executed by default. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". See https://blog.bazel.build/2019/06/19/list-strategy.html for details. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--strategy=<a '[name=]value1[,..,valueN]' assignment>` multiple uses are accumulated + +Specify how to distribute compilation of other spawn actions. Accepts a comma-separated list of strategies from highest to lowest priority. For each action Bazel picks the strategy with the highest priority that can execute the action. The default value is "remote,worker,sandboxed,local". This flag overrides the values set by --spawn\_strategy (and --genrule\_strategy if used with mnemonic Genrule). See https://blog.bazel.build/2019/06/19/list-strategy.html for details. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--strategy_regexp=<a '<RegexFilter>=value[,value]' assignment>` multiple uses are accumulated + +Override which spawn strategy should be used to execute spawn actions that have descriptions matching a certain regex\_filter. See --per\_file\_copt for details onregex\_filter matching. The last regex\_filter that matches the description is used. This option overrides other flags for specifying strategy. Example: --strategy\_regexp=//foo. _.cc,-//foo/bar=local means to run actions using local strategy if their descriptions match //foo._.cc but not //foo/bar. Example: --strategy\_regexp='Compiling.\*/bar=local --strategy\_regexp=Compiling=sandboxed will run 'Compiling //foo/bar/baz' with the 'local' strategy, but reversing the order would run it with 'sandboxed'. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--worker_extra_flag=<a 'name=value' assignment>` multiple uses are accumulated + +Extra command-flags that will be passed to worker processes in addition to --persistent\_worker, keyed by mnemonic (e.g. --worker\_extra\_flag=Javac=--debug. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--worker_max_instances=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated + +How many instances of each kind of persistent worker may be launched if you use the 'worker' strategy. May be specified as \[name=value\] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--worker_max_multiplex_instances=<[name=]value, where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated + +How many WorkRequests a multiplex worker process may receive in parallel if you use the 'worker' strategy with --worker\_multiplex. May be specified as \[name=value\] to give a different value per mnemonic. The limit is based on worker keys, which are differentiated based on mnemonic, but also on startup flags and environment, so there can in some cases be more workers per mnemonic than this flag specifies. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". 'auto' calculates a reasonable default based on machine capacity. "=value" sets a default for unspecified mnemonics. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]worker_multiplex` default: "true" + +If enabled, workers will use multiplexing if they support it. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]worker_quit_after_build` default: "false" + +If enabled, all workers quit after a build is done. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]worker_sandboxing` default: "false" + +If enabled, singleplex workers will run in a sandboxed environment. Singleplex workers are always sandboxed when running under the dynamic execution strategy, irrespective of this flag. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]worker_verbose` default: "false" + +If enabled, prints verbose messages when workers are started, shutdown, ... + +Options that control the output of the command: +`--[no]build` default: "true" + +Execute the build; this is the usual behaviour. Specifying --nobuild causes the build to stop before executing the build actions, returning zero iff the package loading and analysis phases completed successfully; this mode is useful for testing those phases. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_use_validation_aspect` default: "false" + +Whether to run validation actions using aspect (for parallelism with tests). + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--output_groups=<comma-separated list of options>` multiple uses are accumulated + +A list of comma-separated output group names, each of which optionally prefixed by a + or a -. A group prefixed by + is added to the default set of output groups, while a group prefixed by - is removed from the default set. If at least one group is not prefixed, the default set of output groups is omitted. For example, --output\_groups=+foo,+bar builds the union of the default set, foo, and bar, while --output\_groups=foo,bar overrides the default set such that only foo and bar are built. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]run_validations` default: "true" + +Whether to run validation actions as part of the build. See https://bazel.build/extending/rules#validation\_actions + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--serialized_frontier_profile=<a string>` default: "" + +Dump a profile of serialized frontier bytes. Specifies the output path. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--aspects=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of aspects to be applied to top-level targets. In the list, if aspect some\_aspect specifies required aspect providers via required\_aspect\_providers, some\_aspect will run after every aspect that was mentioned before it in the aspects list whose advertised providers satisfy some\_aspect required aspect providers. Moreover, some\_aspect will run after all its required aspects specified by requires attribute. some\_aspect will then have access to the values of those aspects' providers. <bzl-file-label>%<aspect\_name>, for example '//tools:my\_def.bzl%my\_aspect', where 'my\_aspect' is a top-level value from a file tools/my\_def.bzl + +`--bep_maximum_open_remote_upload_files=<an integer>` default: "-1" + +Maximum number of open files allowed during BEP artifact upload. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_convenience_symlinks` default: "normal" + +This flag controls how the convenience symlinks (the symlinks that appear in the workspace after the build) will be managed. Possible values: +normal (default): Each kind of convenience symlink will be created or deleted, as determined by the build. +clean: All symlinks will be unconditionally deleted. +ignore: Symlinks will not be created or cleaned up. +log\_only: Generate log messages as if 'normal' were passed, but don't actually perform any filesystem operations (useful for tools). +Note that only symlinks whose names are generated by the current value of --symlink\_prefix can be affected; if the prefix changes, any pre-existing symlinks will be left alone. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_convenience_symlinks_bep_event` default: "true" + +This flag controls whether or not we will post the build eventConvenienceSymlinksIdentified to the BuildEventProtocol. If the value is true, the BuildEventProtocol will have an entry for convenienceSymlinksIdentified, listing all of the convenience symlinks created in your workspace. If false, then the convenienceSymlinksIdentified entry in the BuildEventProtocol will be empty. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_all` + +Downloads all remote outputs to the local machine. This flag is an alias for --remote\_download\_outputs=all. + +Expands to: + +`--remote_download_outputs=all` + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_minimal` + +Does not download any remote build outputs to the local machine. This flag is an alias for --remote\_download\_outputs=minimal. + +Expands to: + +`--remote_download_outputs=minimal` + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_outputs=<all, minimal or toplevel>` default: "toplevel" + +If set to 'minimal' doesn't download any remote build outputs to the local machine, except the ones required by local actions. If set to 'toplevel' behaves like 'minimal' except that it also downloads outputs of top level targets to the local machine. Both options can significantly reduce build times if network bandwidth is a bottleneck. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_symlink_template=<a string>` default: "" + +Instead of downloading remote build outputs to the local machine, create symbolic links. The target of the symbolic links can be specified in the form of a template string. This template string may contain {hash} and {size\_bytes} that expand to the hash of the object and the size in bytes, respectively. These symbolic links may, for example, point to a FUSE file system that loads objects from the CAS on demand. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_download_toplevel` + +Only downloads remote outputs of top level targets to the local machine. This flag is an alias for --remote\_download\_outputs=toplevel. + +Expands to: + +`--remote_download_outputs=toplevel` + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--symlink_prefix=<a string>` default: see description + +The prefix that is prepended to any of the convenience symlinks that are created after a build. If omitted, the default value is the name of the build tool followed by a hyphen. If '/' is passed, then no symlinks are created and no warning is emitted. Warning: the special functionality for '/' will be deprecated soon; use --experimental\_convenience\_symlinks=ignore instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]experimental_docker_privileged` default: "false" + +If enabled, Bazel will pass the --privileged flag to 'docker run' when running actions. This might be required by your build, but it might also result in reduced hermeticity. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_sandboxfs_map_symlink_targets` default: "false" + +No-op + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--sandbox_add_mount_pair=<a single path or a 'source:target' pair>` multiple uses are accumulated + +Add additional path pair to mount in sandbox. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--sandbox_block_path=<a string>` multiple uses are accumulated + +For sandboxed actions, disallow access to this path. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]sandbox_default_allow_network` default: "true" + +Allow network access by default for actions; this may not work with all sandboxing implementations. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]sandbox_fake_hostname` default: "false" + +Change the current hostname to 'localhost' for sandboxed actions. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]sandbox_fake_username` default: "false" + +Change the current username to 'nobody' for sandboxed actions. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--sandbox_writable_path=<a string>` multiple uses are accumulated + +For sandboxed actions, make an existing directory writable in the sandbox (if supported by the sandboxing implementation, ignored otherwise). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_config_setting_private_default_visibility` default: "false" + +If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enforce_config_setting_visibility` default: "true" + +If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that govern the behavior of the test environment or test runner: +`--[no]check_tests_up_to_date` default: "false" + +Don't run tests, just check if they are up-to-date. If all tests results are up-to-date, the testing completes successfully. If any test needs to be built or executed, an error is reported and the testing fails. This option implies --check\_up\_to\_date behavior. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--flaky_test_attempts=<a positive integer, the string "default", or test_regex@attempts. This flag may be passed more than once>` multiple uses are accumulated + +Each test will be retried up to the specified number of times in case of any test failure. Tests that required more than one attempt to pass are marked as 'FLAKY' in the test summary. Normally the value specified is just an integer or the string 'default'. If an integer, then all tests will be run up to N times. If 'default', then only a single test attempt will be made for regular tests and three for tests marked explicitly as flaky by their rule (flaky=1 attribute). Alternate syntax: regex\_filter@flaky\_test\_attempts. Where flaky\_test\_attempts is as above and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --runs\_per\_test). Example: --flaky\_test\_attempts=//foo/. _,-//foo/bar/._@3 deflakes all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, behavior is as if 'default' above. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--local_test_jobs=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" + +The max number of local test jobs to run concurrently. Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". 0 means local resources will limit the number of local test jobs to run concurrently instead. Setting this greater than the value for --jobs is ineffectual. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]test_keep_going` default: "true" + +When disabled, any non-passing test will cause the entire build to stop. By default all tests are run, even if some do not pass. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--test_strategy=<a string>` default: "" + +Specifies which strategy to use when running tests. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--test_tmpdir=<a path>` default: see description + +Specifies the base temporary directory for 'bazel test' to use. + +Options that trigger optimizations of the build time: +`--cache_computed_file_digests=<a long integer>` default: "50000" + +If greater than 0, configures Bazel to cache file digests in memory based on their metadata instead of recomputing the digests from disk every time they are needed. Setting this to 0 ensures correctness because not all file changes can be noted from file metadata. When not 0, the number indicates the size of the cache as the number of file digests to be cached. + +`--experimental_active_directories=<comma-separated list of options>` default: "" + +Active directories for Skyfocus and remote analysis caching. Specify as comma-separated workspace root-relative paths. This is a stateful flag. Defining one persists it for subsequent invocations, until it is redefined with a new set. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]experimental_cpu_load_scheduling` default: "false" + +Enables the experimental local execution scheduling based on CPU load, not estimation of actions one by one. Experimental scheduling have showed the large benefit on a large local builds on a powerful machines with the large number of cores. Reccommended to use with --local\_resources=cpu=HOST\_CPUS + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_dynamic_ignore_local_signals=<a comma-separated list of signal numbers>` default: see description + +Takes a list of OS signal numbers. If a local branch of dynamic execution gets killed with any of these signals, the remote branch will be allowed to finish instead. For persistent workers, this only affects signals that kill the worker process. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_enable_skyfocus` default: "false" + +If true, enable the use of --experimental\_active\_directories to reduce Bazel's memory footprint for incremental builds. This feature is known as Skyfocus. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--local_cpu_resources=<an integer, or "HOST_CPUS", optionally followed by [-|*]<float>.>` default: "HOST\_CPUS" + +Explicitly set the total number of local CPU cores available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST\_CPUS", optionally followed by \[-\| _\]<float> (eg. HOST\_CPUS_.5 to use half the available CPU cores). By default, ("HOST\_CPUS"), Bazel will query system configuration to estimate the number of CPU cores available. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--local_extra_resources=<a named float, 'name=value'>` multiple uses are accumulated + +Set the number of extra resources available to Bazel. Takes in a string-float pair. Can be used multiple times to specify multiple types of extra resources. Bazel will limit concurrently running actions based on the available extra resources and the extra resources required. Tests can declare the amount of extra resources they need by using a tag of the "resources:<resoucename>:<amount>" format. Available CPU, RAM and resources cannot be set with this flag. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--local_ram_resources=<an integer number of MBs, or "HOST_RAM", optionally followed by [-|*]<float>.>` default: "HOST\_RAM\*.67" + +Explicitly set the total amount of local host RAM (in MB) available to Bazel to spend on build actions executed locally. Takes an integer, or "HOST\_RAM", optionally followed by \[-\| _\]<float> (eg. HOST\_RAM_.5 to use half the available RAM). By default, ("HOST\_RAM\*.67"), Bazel will query system configuration to estimate the amount of RAM available and will use 67% of it. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--local_resources=<a named double, 'name=value', where value is an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` multiple uses are accumulated + +Set the number of resources available to Bazel. Takes in an assignment to a float or HOST\_RAM/HOST\_CPUS, optionally followed by \[-\| _\]<float> (eg. memory=HOST\_RAM_.5 to use half the available RAM). Can be used multiple times to specify multiple types of resources. Bazel will limit concurrently running actions based on the available resources and the resources required. Tests can declare the amount of resources they need by using a tag of the "resources:<resource name>:<amount>" format. Overrides resources specified by --local\_{cpu\|ram\|extra}\_resources. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +Options that affect the verbosity, format or location of logging: +`--build_event_upload_max_retries=<an integer>` default: "4" + +The maximum number of times Bazel should retry uploading a build event. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--[no]debug_spawn_scheduler` default: "false"`--[no]experimental_bep_target_summary` default: "false" + +Whether to publish TargetSummary events. + +`--[no]experimental_build_event_expand_filesets` default: "false" + +If true, expand Filesets in the BEP when presenting output files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--experimental_build_event_output_group_mode=<an output group name followed by an OutputGroupFileMode, e.g. default=both>` multiple uses are accumulated + +Specify how an output group's files will be represented in TargetComplete/AspectComplete BEP events. Values are an assignment of an output group name to one of 'NAMED\_SET\_OF\_FILES\_ONLY', 'INLINE\_ONLY', or 'BOTH'. The default value is 'NAMED\_SET\_OF\_FILES\_ONLY'. If an output group is repeated, the final value to appear is used. The default value sets the mode for coverage artifacts to BOTH: --experimental\_build\_event\_output\_group\_mode=baseline.lcov=both + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--experimental_build_event_upload_retry_minimum_delay=<An immutable length of time.>` default: "1s" + +Initial, minimum delay for exponential backoff retries when BEP upload fails. (exponent: 1.6) + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--experimental_build_event_upload_strategy=<a string>` default: see description + +Selects how to upload artifacts referenced in the build event protocol. In Bazel the valid options include 'local' and 'remote'. The default value is 'local'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_docker_verbose` default: "false" + +If enabled, Bazel will print more verbose messages about the Docker sandbox strategy. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_frontier_violation_check=<strict, warn or disabled_for_testing>` default: "strict" + +Strategies to handle potential incorrectness from changes beyond the frontier (i.e. outside the active directories) + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]experimental_frontier_violation_verbose` default: "false" + +If true, Bazel will print instructions for fixing Skycache violations + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]experimental_materialize_param_files_directly` default: "false" + +If materializing param files, do so with direct writes to disk. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_run_bep_event_include_residue` default: "false" + +Whether to include the command-line residue in run build events which could contain the residue. By default, the residue is not included in run command build events that could contain the residue. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--experimental_skyfocus_dump_keys=<none, count or verbose>` default: "none" + +For debugging Skyfocus. Dump the focused SkyKeys (roots, leafs, focused deps, focused rdeps). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]experimental_skyfocus_dump_post_gc_stats` default: "false" + +For debugging Skyfocus. If enabled, trigger manual GC before/after focusing to report heap sizes reductions. This will increase the Skyfocus latency. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]experimental_stream_log_file_uploads` default: "false" + +Stream log file uploads directly to the remote storage rather than writing them to disk. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--explain=<a path>` default: see description + +Causes the build system to explain each executed step of the build. The explanation is written to the specified log file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]ignore_unsupported_sandboxing` default: "false" + +Do not print a warning when sandboxed execution is not supported on this system. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]legacy_important_outputs` default: "false" + +Use this to suppress generation of the legacy important\_outputs field in the TargetComplete event. important\_outputs are required for Bazel to ResultStore/BTX integration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]materialize_param_files` default: "false" + +Writes intermediate parameter files to output tree even when using remote action execution or caching. Useful when debugging actions. This is implied by --subcommands and --verbose\_failures. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--max_config_changes_to_show=<an integer>` default: "3" + +When discarding the analysis cache due to a change in the build options, displays up to the given number of changed option names. If the number given is -1, all changed options will be displayed. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--max_test_output_bytes=<an integer>` default: "-1" + +Specifies maximum per-test-log size that can be emitted when --test\_output is 'errors' or 'all'. Useful for avoiding overwhelming the output with excessively noisy test output. The test header is included in the log size. Negative values imply no limit. Output is all or nothing. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) + +`--output_filter=<a valid Java regular expression>` default: see description + +Only shows warnings and action outputs for rules with a name matching the provided regular expression. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--progress_report_interval=<an integer in 0-3600 range>` default: "0" + +The number of seconds to wait between reports on still running jobs. The default value 0 means the first report will be printed after 10 seconds, then 30 seconds and after that progress is reported once every minute. When --curses is enabled, progress is reported every second. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_analysis_json_log=<a string>` default: see description + +If set, a JSON file is written to this location that contains a detailed log of the behavior of remote analysis caching. It's interpreted as a path relative to the current working directory. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--remote_print_execution_messages=<failure, success or all>` default: "failure" + +Choose when to print remote execution messages. Valid values are `failure`, to print only on failures, `success` to print only on successes and `all` to print always. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]sandbox_debug` default: "false" + +Enables debugging features for the sandboxing feature. This includes two things: first, the sandbox root contents are left untouched after a build; and second, prints extra debugging information on execution. This can help developers of Bazel or Starlark rules with debugging failures due to missing input files, etc. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--show_result=<an integer>` default: "1" + +Show the results of the build. For each target, state whether or not it was brought up-to-date, and if so, a list of output files that were built. The printed files are convenient strings for copy+pasting to the shell, to execute them. +This option requires an integer argument, which is the threshold number of targets above which result information is not printed. Thus zero causes suppression of the message and MAX\_INT causes printing of the result to occur always. The default is one. +If nothing was built for a target its results may be omitted to keep the output under the threshold. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]subcommands` \[ `-s`\] default: "false" + +Display the subcommands executed during a build. Related flags: --execution\_log\_json\_file, --execution\_log\_binary\_file (for logging subcommands to a file in a tool-friendly format). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--test_output=<summary, errors, all or streamed>` default: "summary" + +Specifies desired output mode. Valid values are 'summary' to output only test status summary, 'errors' to also print test logs for failed tests, 'all' to print logs for all tests and 'streamed' to output logs for all tests in real time (this will force tests to be executed locally one at a time regardless of --test\_strategy value). + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`execution`](#effect_tag_EXECUTION) + +`--test_summary=<short, terse, detailed, none or testcase>` default: "short" + +Specifies the desired format of the test summary. Valid values are 'short' to print information only about tests executed, 'terse', to print information only about unsuccessful tests that were run, 'detailed' to print detailed information about failed test cases, 'testcase' to print summary in test case resolution, do not print detailed information about failed test cases and 'none' to omit the summary. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]verbose_failures` default: "false" + +If a command fails, print out the full command line. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--aspects_parameters=<a 'name=value' assignment>` multiple uses are accumulated + +Specifies the values of the command-line aspects parameters. Each parameter value is specified via <param\_name>=<param\_value>, for example 'my\_param=my\_val' where 'my\_param' is a parameter of some aspect in --aspects list or required by an aspect in the list. This option can be used multiple times. However, it is not allowed to assign values to the same parameter more than once. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--target_pattern_file=<a string>` default: "" + +If set, build will read patterns from the file named here, rather than on the command line. It is an error to specify a file here as well as command-line patterns. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Remote caching and execution options: +`--experimental_circuit_breaker_strategy=<failure>` default: see description + +Specifies the strategy for the circuit breaker to use. Available strategies are "failure". On invalid value for the option the behavior same as the option is not set. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_remote_cache_compression_threshold=<an integer>` default: "100" + +The minimum blob size required to compress/decompress with zstd. Ineffectual unless --remote\_cache\_compression is set. + +`--experimental_remote_cache_eviction_retries=<an integer>` default: "5" + +The maximum number of attempts to retry if the build encountered a transient remote cache error that would otherwise fail the build. Applies for example when artifacts are evicted from the remote cache, or in certain cache failure conditions. A new invocation id will be generated for each attempt. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_remote_cache_lease_extension` default: "false" + +If set to true, Bazel will extend the lease for outputs of remote actions during the build by sending `FindMissingBlobs` calls periodically to remote cache. The frequency is based on the value of `--experimental_remote_cache_ttl`. + +`--experimental_remote_cache_ttl=<An immutable length of time.>` default: "3h" + +The guaranteed minimal TTL of blobs in the remote cache after their digests are recently referenced e.g. by an ActionResult or FindMissingBlobs. Bazel does several optimizations based on the blobs' TTL e.g. doesn't repeatedly call GetActionResult in an incremental build. The value should be set slightly less than the real TTL since there is a gap between when the server returns the digests and when Bazel receives them. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_remote_capture_corrupted_outputs=<a path>` default: see description + +A path to a directory where the corrupted outputs will be captured to. + +`--[no]experimental_remote_discard_merkle_trees` default: "true" + +If set to true, discard in-memory copies of the input root's Merkle tree and associated input mappings during calls to GetActionResult() and Execute(). This reduces memory usage significantly, but does require Bazel to recompute them upon remote cache misses and retries. + +`--experimental_remote_downloader=<a string>` default: see description + +A Remote Asset API endpoint URI, to be used as a remote download proxy. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. See: https://github.com/bazelbuild/remote-apis/blob/master/build/bazel/remote/asset/v1/remote\_asset.proto + +`--[no]experimental_remote_downloader_local_fallback` default: "false" + +Whether to fall back to the local downloader if remote downloader fails. + +`--[no]experimental_remote_downloader_propagate_credentials` default: "false" + +Whether to propagate credentials from netrc and credential helper to the remote downloader server. The server implementation needs to support the new `http_header_url:<url-index>:<header-key>` qualifier where the `<url-index>` is a 0-based position of the URL inside the FetchBlobRequest's `uris` field. The URL-specific headers should take precedence over the global headers. + +`--[no]experimental_remote_execution_keepalive` default: "false" + +Whether to use keepalive for remote execution calls. + +`--experimental_remote_failure_rate_threshold=<an integer in 0-100 range>` default: "10" + +Sets the allowed number of failure rate in percentage for a specific time window after which it stops calling to the remote cache/executor. By default the value is 10. Setting this to 0 means no limitation. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--experimental_remote_failure_window_interval=<An immutable length of time.>` default: "60s" + +The interval in which the failure rate of the remote requests are computed. On zero or negative value the failure duration is computed the whole duration of the execution.Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]experimental_remote_mark_tool_inputs` default: "false" + +If set to true, Bazel will mark inputs as tool inputs for the remote executor. This can be used to implement remote persistent workers. + +`--[no]experimental_remote_merkle_tree_cache` default: "false" + +If set to true, Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The memory foot print of the cache is controlled by --experimental\_remote\_merkle\_tree\_cache\_size. + +`--experimental_remote_merkle_tree_cache_size=<a long integer>` default: "1000" + +The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though the cache is automatically pruned according to Java's handling of soft references, out-of-memory errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies depending on project's size. Default to 1000. + +`--experimental_remote_output_service=<a string>` default: see description + +HOST or HOST:PORT of a remote output service endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. + +`--experimental_remote_output_service_output_path_prefix=<a string>` default: "" + +The path under which the contents of output directories managed by the --experimental\_remote\_output\_service are placed. The actual output directory used by a build will be a descendant of this path and determined by the output service. + +`--[no]experimental_remote_require_cached` default: "false" + +If set to true, enforce that all actions that can run remotely are cached, or else fail the build. This is useful to troubleshoot non-determinism issues as it allows checking whether actions that should be cached are actually cached without spuriously injecting new results into the cache. + +`--experimental_remote_scrubbing_config=<Converts to a Scrubber>` default: see description + +Enables remote cache key scrubbing with the supplied configuration file, which must be a protocol buffer in text format (see src/main/protobuf/remote\_scrubbing.proto). + +This feature is intended to facilitate sharing a remote/disk cache between actions executing on different platforms but targeting the same platform. It should be used with extreme care, as improper settings may cause accidental sharing of cache entries and result in incorrect builds. + +Scrubbing does not affect how an action is executed, only how its remote/disk cache key is computed for the purpose of retrieving or storing an action result. Scrubbed actions are incompatible with remote execution, and will always be executed locally instead. + +Modifying the scrubbing configuration does not invalidate outputs present in the local filesystem or internal caches; a clean build is required to reexecute affected actions. + +In order to successfully use this feature, you likely want to set a custom --host\_platform together with --experimental\_platform\_in\_output\_dir (to normalize output prefixes) and --incompatible\_strict\_action\_env (to normalize environment variables). + +`--[no]guard_against_concurrent_changes` default: "lite" + +Set this to 'full' to enable checking the ctime of all input files of an action before uploading it to a remote cache. There may be cases where the Linux kernel delays writing of files, which could cause false positives. The default is 'lite', which only checks source files in the main repository. Setting this to 'off' disables all checks. This is not recommended, as the cache may be polluted when a source file is changed while an action that takes it as an input is executing. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]remote_accept_cached` default: "true" + +Whether to accept remotely cached action results. + +`--remote_build_event_upload=<all or minimal>` default: "minimal" + +If set to 'all', all local outputs referenced by BEP are uploaded to remote cache. +If set to 'minimal', local outputs referenced by BEP are not uploaded to the remote cache, except for files that are important to the consumers of BEP (e.g. test logs and timing profile). bytestream:// scheme is always used for the uri of files even if they are missing from remote cache. +Default to 'minimal'. + +`--remote_bytestream_uri_prefix=<a string>` default: see description + +The hostname and instance name to be used in bytestream:// URIs that are written into build event streams. This option can be set when builds are performed using a proxy, which causes the values of --remote\_executor and --remote\_instance\_name to no longer correspond to the canonical name of the remote execution service. When not set, it will default to "${hostname}/${instance\_name}". + +`--remote_cache=<a string>` default: see description + +A URI of a caching endpoint. The supported schemas are http, https, grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc://, http:// or unix: schema to disable TLS. See https://bazel.build/remote/caching + +`--[no]remote_cache_async` default: "true" + +If true, uploading of action results to a disk or remote cache will happen in the background instead of blocking the completion of an action. Some actions are incompatible with background uploads, and may still block even when this flag is set. + +`--[no]remote_cache_compression` default: "false" + +If enabled, compress/decompress cache blobs with zstd when their size is at least --experimental\_remote\_cache\_compression\_threshold. + +`--remote_cache_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header that will be included in cache requests: --remote\_cache\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +`--remote_default_exec_properties=<a 'name=value' assignment>` multiple uses are accumulated + +Set the default exec properties to be used as the remote execution platform if an execution platform does not already set exec\_properties. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_default_platform_properties=<a string>` default: "" + +Set the default platform properties to be set for the remote execution API, if the execution platform does not already set remote\_execution\_properties. This value will also be used if the host platform is selected as the execution platform for remote execution. + +`--remote_download_regex=<a valid Java regular expression>` multiple uses are accumulated + +Force remote build outputs whose path matches this pattern to be downloaded, irrespective of --remote\_download\_outputs. Multiple patterns may be specified by repeating this flag. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--remote_downloader_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header that will be included in remote downloader requests: --remote\_downloader\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +`--remote_exec_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header that will be included in execution requests: --remote\_exec\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +`--remote_execution_priority=<an integer>` default: "0" + +The relative priority of actions to be executed remotely. The semantics of the particular priority values are server-dependent. + +`--remote_executor=<a string>` default: see description + +HOST or HOST:PORT of a remote execution endpoint. The supported schemas are grpc, grpcs (grpc with TLS enabled) and unix (local UNIX sockets). If no schema is provided Bazel will default to grpcs. Specify grpc:// or unix: schema to disable TLS. + +`--remote_grpc_log=<a path>` default: see description + +If specified, a path to a file to log gRPC call related details. This log consists of a sequence of serialized com.google.devtools.build.lib.remote.logging.RemoteExecutionLog.LogEntry protobufs with each message prefixed by a varint denoting the size of the following serialized protobuf message, as performed by the method LogEntry.writeDelimitedTo(OutputStream). + +`--remote_header=<a 'name=value' assignment>` multiple uses are accumulated + +Specify a header that will be included in requests: --remote\_header=Name=Value. Multiple headers can be passed by specifying the flag multiple times. Multiple values for the same name will be converted to a comma-separated list. + +`--remote_instance_name=<a string>` default: "" + +Value to pass as instance\_name in the remote execution API. + +`--[no]remote_local_fallback` default: "false" + +Whether to fall back to standalone local execution strategy if remote execution fails. + +`--remote_local_fallback_strategy=<a string>` default: "local" + +Deprecated. See https://github.com/bazelbuild/bazel/issues/7480 for details. + +`--remote_max_connections=<an integer>` default: "100" + +Limit the max number of concurrent connections to remote cache/executor. By default the value is 100. Setting this to 0 means no limitation. +For HTTP remote cache, one TCP connection could handle one request at one time, so Bazel could make up to --remote\_max\_connections concurrent requests. +For gRPC remote cache/executor, one gRPC channel could usually handle 100+ concurrent requests, so Bazel could make around `--remote_max_connections * 100` concurrent requests. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--remote_proxy=<a string>` default: see description + +Connect to the remote cache through a proxy. Currently this flag can only be used to configure a Unix domain socket (unix:/path/to/socket). + +`--remote_result_cache_priority=<an integer>` default: "0" + +The relative priority of remote actions to be stored in remote cache. The semantics of the particular priority values are server-dependent. + +`--remote_retries=<an integer>` default: "5" + +The maximum number of attempts to retry a transient error. If set to 0, retries are disabled. + +`--remote_retry_max_delay=<An immutable length of time.>` default: "5s" + +The maximum backoff delay between remote retry attempts. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +`--remote_timeout=<An immutable length of time.>` default: "60s" + +The maximum amount of time to wait for remote execution and cache calls. For the REST cache, this is both the connect and the read timeout. Following units can be used: Days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). If the unit is omitted, the value is interpreted as seconds. + +`--[no]remote_upload_local_results` default: "true" + +Whether to upload locally executed action results to the remote cache if the remote cache supports it and the user is authorized to do so. + +`--[no]remote_verify_downloads` default: "true" + +If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. + +Miscellaneous options, not otherwise categorized.: +`--[no]allow_analysis_cache_discard` default: "true" + +If discarding the analysis cache due to a change in the build system, setting this option to false will cause bazel to exit, rather than continuing with the build. This option has no effect when 'discard\_analysis\_cache' is also set. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--auto_output_filter=<none, all, packages or subpackages>` default: "none" + +If --output\_filter is not specified, then the value for this option is used create a filter automatically. Allowed values are 'none' (filter nothing / show everything), 'all' (filter everything / show nothing), 'packages' (include output from rules in packages mentioned on the Blaze command line), and 'subpackages' (like 'packages', but also include subpackages). For the 'packages' and 'subpackages' values //java/foo and //javatests/foo are treated as one package)'. + +`--[no]build_manual_tests` default: "false" + +Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from processing. This option forces them to be built (but not executed). + +`--build_tag_filters=<comma-separated list of options>` default: "" + +Specifies a comma-separated list of tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those targets will be built that contain at least one included tag and do not contain any excluded tags. This option does not affect the set of tests executed with the 'test' command; those are be governed by the test filtering options, for example '--test\_tag\_filters' + +`--[no]build_tests_only` default: "false" + +If specified, only \*\_test and test\_suite rules will be built and other targets specified on the command line will be ignored. By default everything that was requested will be built. + +`--combined_report=<none or lcov>` default: "lcov" + +Specifies desired cumulative coverage report type. At this point only LCOV is supported. + +`--[no]compile_one_dependency` default: "false" + +Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single target that depends on the source file to detect errors as early as possible in the edit/build/test cycle. This argument affects the way all non-flag arguments are interpreted; instead of being targets to build they are source filenames. For each source filename an arbitrary target that depends on it will be built. + +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated + +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. + +`--[no]discard_analysis_cache` default: "false" + +Discard the analysis cache immediately after the analysis phase completes. Reduces memory usage by ~10%, but makes further incremental builds slower. + +`--disk_cache=<a path>` default: see description + +A path to a directory where Bazel can read and write actions and action outputs. If the directory does not exist, it will be created. + +`--embed_label=<a one-line string>` default: "" + +Embed source control revision or release label in binary + +`--execution_log_binary_file=<a path>` default: see description + +Log the executed spawns into this file as length-delimited SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution\_log\_compact\_file, which is significantly smaller and cheaper to produce. Related flags: --execution\_log\_compact\_file (compact format; mutually exclusive), --execution\_log\_json\_file (text JSON format; mutually exclusive), --execution\_log\_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). + +`--execution_log_compact_file=<a path>` default: see description + +Log the executed spawns into this file as length-delimited ExecLogEntry protos, according to src/main/protobuf/spawn.proto. The entire file is zstd compressed. Related flags: --execution\_log\_binary\_file (binary protobuf format; mutually exclusive), --execution\_log\_json\_file (text JSON format; mutually exclusive), --subcommands (for displaying subcommands in terminal output). + +`--execution_log_json_file=<a path>` default: see description + +Log the executed spawns into this file as newline-delimited JSON representations of SpawnExec protos, according to src/main/protobuf/spawn.proto. Prefer --execution\_log\_compact\_file, which is significantly smaller and cheaper to produce. Related flags: --execution\_log\_compact\_file (compact format; mutually exclusive), --execution\_log\_binary\_file (binary protobuf format; mutually exclusive), --execution\_log\_sort (whether to sort the execution log), --subcommands (for displaying subcommands in terminal output). + +`--[no]execution_log_sort` default: "true" + +Whether to sort the execution log, making it easier to compare logs across invocations. Set to false to avoid potentially significant CPU and memory usage at the end of the invocation, at the cost of producing the log in nondeterministic execution order. Only applies to the binary and JSON formats; the compact format is never sorted. + +`--[no]expand_test_suites` default: "true" + +Expand test\_suite targets into their constituent tests before analysis. When this flag is turned on (the default), negative target patterns will apply to the tests belonging to the test suite, otherwise they will not. Turning off this flag is useful when top-level aspects are applied at command line: then they can analyze test\_suite targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_disk_cache_gc_idle_delay=<An immutable length of time.>` default: "5m" + +How long the server must remain idle before a garbage collection of the disk cache occurs. To specify the garbage collection policy, set --experimental\_disk\_cache\_gc\_max\_size and/or --experimental\_disk\_cache\_gc\_max\_age. + +`--experimental_disk_cache_gc_max_age=<An immutable length of time.>` default: "0" + +If set to a positive value, the disk cache will be periodically garbage collected to remove entries older than this age. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_size, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. + +`--experimental_disk_cache_gc_max_size=<a size in bytes, optionally followed by a K, M, G or T multiplier>` default: "0" + +If set to a positive value, the disk cache will be periodically garbage collected to stay under this size. If set in conjunction with --experimental\_disk\_cache\_gc\_max\_age, both criteria are applied. Garbage collection occurrs in the background once the server has become idle, as determined by the --experimental\_disk\_cache\_gc\_idle\_delay flag. + +`--experimental_extra_action_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "" + +Deprecated in favor of aspects. Filters set of targets to schedule extra\_actions for. + +`--[no]experimental_extra_action_top_level_only` default: "false" + +Deprecated in favor of aspects. Only schedules extra\_actions for top level targets. + +`--experimental_spawn_scheduler` + +Enable dynamic execution by running actions locally and remotely in parallel. Bazel spawns each action locally and remotely and picks the one that completes first. If an action supports workers, the local action will be run in the persistent worker mode. To enable dynamic execution for an individual action mnemonic, use the `--internal_spawn_scheduler` and `--strategy=<mnemonic>=dynamic` flags instead. + +Expands to: + +`--internal_spawn_scheduler` + +`--spawn_strategy=dynamic` + +`--[no]fetch` default: "true" + +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +`--local_termination_grace_seconds=<an integer>` default: "15" + +Time to wait between terminating a local process due to timeout and forcefully shutting it down. + +`--package_path=<colon-separated list of options>` default: "%workspace%" + +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +`--[no]show_loading_progress` default: "true" + +If enabled, causes Bazel to print "Loading package:" messages. + +`--test_lang_filters=<comma-separated list of options>` default: "" + +Specifies a comma-separated list of test languages. Each language can be optionally preceded with '-' to specify excluded languages. Only those test targets will be found that are written in the specified languages. The name used for each language should be the same as the language prefix in the \*\_test rule, e.g. one of 'cc', 'java', 'py', etc. This option affects --build\_tests\_only behavior and the test command. + +`--test_size_filters=<comma-separated list of values: small, medium, large, or enormous>` default: "" + +Specifies a comma-separated list of test sizes. Each size can be optionally preceded with '-' to specify excluded sizes. Only those test targets will be found that contain at least one included size and do not contain any excluded sizes. This option affects --build\_tests\_only behavior and the test command. + +`--test_tag_filters=<comma-separated list of options>` default: "" + +Specifies a comma-separated list of test tags. Each tag can be optionally preceded with '-' to specify excluded tags. Only those test targets will be found that contain at least one included tag and do not contain any excluded tags. This option affects --build\_tests\_only behavior and the test command. + +`--test_timeout_filters=<comma-separated list of values: short, moderate, long, or eternal>` default: "" + +Specifies a comma-separated list of test timeouts. Each timeout can be optionally preceded with '-' to specify excluded timeouts. Only those test targets will be found that contain at least one included timeout and do not contain any excluded timeouts. This option affects --build\_tests\_only behavior and the test command. + +`--workspace_status_command=<path>` default: "" + +A command invoked at the beginning of the build to provide status information about the workspace in the form of key/value pairs. See the User's Manual for the full specification. Also see tools/buildstamp/get\_workspace\_status for an example. + +Options that control build execution: +`--[no]experimental_persistent_aar_extractor` default: "false" + +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_remotable_source_manifests` default: "false" + +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_split_coverage_postprocessing` default: "false" + +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_strict_fileset_output` default: "false" + +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_modify_execution_info_additive` default: "true" + +When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated + +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'. _=+x,._ =-y,. _=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions._ +_'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions._ +_'(?!Genrule)._ =-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` + +Enable persistent Android dex and desugar actions by using workers. + +Expands to: + +`--internal_persistent_android_dex_desugar` + +`--strategy=Desugar=worker` + +`--strategy=DexBuilder=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` + +Enable persistent Android resource processor by using workers. + +Expands to: + +`--internal_persistent_busybox_tools` + +`--strategy=AaptPackage=worker` + +`--strategy=AndroidResourceParser=worker` + +`--strategy=AndroidResourceValidator=worker` + +`--strategy=AndroidResourceCompiler=worker` + +`--strategy=RClassGenerator=worker` + +`--strategy=AndroidResourceLink=worker` + +`--strategy=AndroidAapt2=worker` + +`--strategy=AndroidAssetMerger=worker` + +`--strategy=AndroidResourceMerger=worker` + +`--strategy=AndroidCompiledResourceMerger=worker` + +`--strategy=ManifestMerger=worker` + +`--strategy=AndroidManifestMerger=worker` + +`--strategy=Aapt2Optimize=worker` + +`--strategy=AARGenerator=worker` + +`--strategy=ProcessDatabinding=worker` + +`--strategy=GenerateDataBindingBaseClasses=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` + +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: + +`--persistent_android_dex_desugar` + +`--internal_persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` + +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: + +`--persistent_android_resource_processor` + +`--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +`--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +`--modify_execution_info=AARGenerator=+supports-multiplex-workers` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` + +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: + +`--internal_persistent_multiplex_busybox_tools` + +`--persistent_multiplex_android_resource_processor` + +`--persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" + +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: +`--android_compiler=<a string>` default: see description + +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" + +Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_platforms=<a build target label>` default: "" + +Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--cc_output_directory_tag=<a string>` default: "" + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compiler=<a string>` default: see description + +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" + +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" + +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" + +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--custom_malloc=<a build target label>` default: see description + +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_include_xcode_execution_requirements` default: "false" + +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version\_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_prefer_mutual_xcode` default: "true" + +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--extra_execution_platforms=<comma-separated list of options>` default: "" + +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated + +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--grte_top=<a label>` default: see description + +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_compiler=<a string>` default: see description + +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--host_grte_top=<a label>` default: see description + +If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" + +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]incompatible_bazel_test_exec_run_under` default: "true" + +If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run\_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_builtin_objc_strip_action` default: "true" + +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" + +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" + +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_remove_legacy_whole_archive` default: "true" + +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strip_executable_safely` default: "false" + +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]interface_shared_objects` default: "true" + +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--minimum_os_version=<a string>` default: see description + +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_mappings=<a main workspace-relative path>` default: "" + +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--platforms=<a build target label>` default: "" + +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_path=<a string>` default: see description + +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" + +Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version=<a string>` default: see description + +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" + +The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options that control the output of the command: +`--[no]apple_generate_dsym` default: "false" + +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]build_runfile_links` default: "true" + +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_runfile_manifests` default: "true" + +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_test_dwp` default: "false" + +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" + +Sets the suffixes of header files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" + +Sets the suffixes of source files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" + +Run extra actions for alternative Java api versions in a proto\_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_save_feature_state` default: "false" + +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fission=<a set of compilation modes>` default: "no" + +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_always_include_files_in_data` default: "true" + +If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" + +If enabled, the <binary>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" + +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" + +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]objc_generate_linkmap` default: "false" + +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]save_temps` default: "false" + +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible\_repo\_env\_ignores\_action\_env</code> is true, all <code>name=value</code> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--allowed_cpu_values=<comma-separated set of options>` default: "" + +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]android_databinding_use_androidx` default: "true" + +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]android_databinding_use_v3_4_args` default: "true" + +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--android_dynamic_mode=<off, default or fully>` default: "off" + +Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" + +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +`--[no]android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]build_python_zip` default: "auto" + +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]collect_code_coverage` default: "false" + +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compilation_mode=<fastbuild, dbg or opt>` \[ `-c`\] default: "fastbuild" + +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--copt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cpu=<a string>` default: "" + +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_absolute_path=<a string>` default: see description + +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_instrument=<a string>` default: see description + +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_profile=<a build target label>` default: see description + +The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cxxopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--define=<a 'name=value' assignment>` multiple uses are accumulated + +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--dynamic_mode=<off, default or fully>` default: "default" + +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_propeller_optimize_absolute_paths` default: "true" + +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_remaining_fdo_absolute_paths` default: "true" + +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_runfiles` default: "auto" + +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_action_listener=<a build target label>` multiple uses are accumulated + +Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_compress_java_resources` default: "false" + +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_databinding_v2` default: "true" + +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" + +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" + +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" + +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]experimental_omitfp` default: "false" + +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_output_paths=<off or strip>` default: "off" + +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated + +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_platform_in_output_dir` default: "false" + +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_py_binaries_include_label` default: "false" + +py\_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_llvm_covmap` default: "false" + +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" + +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fdo_instrument=<a string>` default: see description + +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_optimize=<a string>` default: see description + +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` \- you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_prefetch_hints=<a build target label>` default: see description + +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_profile=<a build target label>` default: see description + +The fdo\_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host\_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]force_pic` default: "false" + +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" + +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_copt=<a string>` multiple uses are accumulated + +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cpu=<a string>` default: "" + +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cxxopt=<a string>` multiple uses are accumulated + +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_auto_exec_groups` default: "false" + +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_merge_genfiles_directory` default: "true" + +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_target_cpu_from_platform` default: "true" + +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]instrument_test_targets` default: "false" + +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" + +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]legacy_whole_archive` default: "true" + +Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +`--linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltobackendopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO backend step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltoindexopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO indexing step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--memprof_profile=<a build target label>` default: see description + +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]objc_debug_with_GLIBCXX` default: "false" + +If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]objc_enable_binary_stripping` default: "false" + +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--objccopt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_suffix=<a string>` default: see description + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--propeller_optimize=<a build target label>` default: see description + +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description + +Absolute path name of cc\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description + +Absolute path name of ld\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--run_under=<a prefix in front of command>` default: see description + +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]share_native_deps` default: "true" + +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]stamp` default: "false" + +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--strip=<always, sometimes or never>` default: "sometimes" + +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--stripopt=<a string>` multiple uses are accumulated + +Additional options to pass to strip when generating a '<name>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xbinary_fdo=<a build target label>` default: see description + +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]check_visibility` default: "true" + +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]desugar_for_android` default: "true" + +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]desugar_java8_libs` default: "false" + +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]enforce_constraints` default: "true" + +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" + +When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" + +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]incompatible_check_testonly_for_output_files` default: "false" + +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_android_rules` default: "false" + +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" + +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]one_version_enforcement_on_java_tests` default: "true" + +When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_native_rules_allowlist=<a build target label>` default: see description + +An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]strict_filesets` default: "false" + +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" + +Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" + +Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]strict_system_includes` default: "false" + +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--target_environment=<a build target label>` multiple uses are accumulated + +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Options that affect the signing outputs of a build: +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" + +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]device_debug_entitlements` default: "true" + +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--ios_signing_cert_name=<a string>` default: see description + +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" + +If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_objc_alwayslink_by_default` default: "false" + +If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_python_disallow_native_rules` default: "false" + +When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that govern the behavior of the test environment or test runner: +`--[no]allow_analysis_failures` default: "false" + +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--analysis_testing_deps_limit=<an integer>` default: "2000" + +Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" + +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated + +Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by \[-\| _\]<float> (eg. memory=HOST\_RAM_.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +`--[no]experimental_android_use_parallel_dex2oat` default: "false" + +Use dex2oat in parallel to possibly speed up android\_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]ios_memleaks` default: "false" + +Enable checking for memory leaks in ios\_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--ios_simulator_device=<a string>` default: see description + +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated + +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/. _,-//foo/bar/._@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" + +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +`--[no]zip_undeclared_test_outputs` default: "false" + +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +Options that trigger optimizations of the build time: +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" + +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_dotd_files` default: "true" + +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_jdeps_files` default: "true" + +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" + +When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" + +Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]process_headers_in_dependencies` default: "false" + +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]trim_test_configuration` default: "true" + +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +Options that affect the verbosity, format or location of logging: +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" + +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]verbose_visibility_errors` default: "false" + +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated + +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_default_to_explicit_init_py` default: "false" + +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Miscellaneous options, not otherwise categorized.: +`--[no]cache_test_results` \[ `-t`\] default: "auto" + +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +`--[no]experimental_cancel_concurrent_tests` default: "never" + +If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_fetch_all_coverage_outputs` default: "false" + +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_generate_llvm_lcov` default: "false" + +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" + +Enables reduced classpaths for Java compilations. + +`--[no]experimental_run_android_lint_on_java_rules` default: "false" + +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[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. + +`--host_java_launcher=<a build target label>` default: see description + +The Java launcher used by tools that are executed during a build. + +`--host_javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac when building tools that are executed during a build. + +`--host_jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. + +`--[no]incompatible_check_sharding_support` default: "true" + +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_exclusive_test_sandboxed` default: "true" + +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strict_action_env` default: "false" + +If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated + +Additional options to pass to the J2ObjC tool. + +`--java_debug` + +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. + +Expands to: + +`--test_arg=--wrapper_script_flag=--debug` + +`--test_output=streamed` + +`--test_strategy=exclusive` + +`--test_timeout=9999` + +`--nocache_test_results` + +`--[no]java_deps` default: "true" + +Generate dependency information (for now, compile-time classpath) per Java target. + +`--[no]java_header_compilation` default: "true" + +Compile ijars directly from source. + +`--java_language_version=<a string>` default: "" + +The Java language version + +`--java_launcher=<a build target label>` default: see description + +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +`--java_runtime_version=<a string>` default: "local\_jdk" + +The Java runtime version + +`--javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac. + +`--jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. + +`--legacy_main_dex_list_generator=<a build target label>` default: see description + +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +`--optimizing_dexer=<a build target label>` default: see description + +Specifies a binary to use to do dexing without sharding. + +`--plugin=<a build target label>` multiple uses are accumulated + +Plugins to use in the build. Currently works with java\_plugin. + +`--proguard_top=<a build target label>` default: see description + +Specifies which version of ProGuard to use for code removal when building a Java binary. + +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" + +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]proto_profile` default: "true" + +Whether to pass profile\_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_profile_path=<a build target label>` default: see description + +The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--protocopt=<a string>` multiple uses are accumulated + +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]runs_per_test_detects_flakes` default: "false" + +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +`--shell_executable=<a path>` default: see description + +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--test_arg=<a string>` multiple uses are accumulated + +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +`--test_filter=<a string>` default: see description + +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +`--test_result_expiration=<an integer>` default: "-1" + +This option is deprecated and has no effect. + +`--[no]test_runner_fail_fast` default: "false" + +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" + +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. + +`--tool_java_language_version=<a string>` default: "" + +The Java language version used to execute the tools that are needed during a build + +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" + +The Java runtime version used to execute tools during the build + +`--[no]use_ijars` default: "true" + +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## Canonicalize-flags Options + +Inherits all options from [build](#build). + +Options that control the output of the command: +`--[no]canonicalize_policy` default: "false" + +Output the canonical policy, after expansion and filtering. To keep the output clean, the canonicalized command arguments will NOT be shown when this option is set to true. Note that the command specified by --for\_command affects the filtered policy, and if none is specified, the default command is 'build'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]experimental_include_default_values` default: "true" + +Whether Starlark options set to their default values are included in the output. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_config_setting_private_default_visibility` default: "false" + +If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enforce_config_setting_visibility` default: "true" + +If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--for_command=<a string>` default: "build" + +The command for which the options should be canonicalized. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--invocation_policy=<a string>` default: "" + +Applies an invocation policy to the options to be canonicalized. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +Miscellaneous options, not otherwise categorized.: +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated + +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. + +`--[no]fetch` default: "true" + +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +`--package_path=<colon-separated list of options>` default: "%workspace%" + +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +`--[no]show_loading_progress` default: "true" + +If enabled, causes Bazel to print "Loading package:" messages. + +## Clean Options + +Inherits all options from [build](#build). + +Options that control the output of the command: +`--[no]async` default: "false" + +If true, output cleaning is asynchronous. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--[no]expunge` default: "false" + +If true, clean removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +`--expunge_async` + +If specified, clean asynchronously removes the entire working tree for this bazel instance, which includes all bazel-created temporary and build output files, and stops the bazel server if it is running. When this command completes, it will be safe to execute new commands in the same client, even though the deletion may continue in the background. + +Expands to: + +`--expunge` + +`--async` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS) + +## Config Options + +## Coverage Options + +Inherits all options from [test](#test). + +## Cquery Options + +Inherits all options from [test](#test). + +Options relating to query output and semantics: +`--aspect_deps=<off, conservative or precise>` default: "conservative" + +How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]consistent_labels` default: "false" + +If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]experimental_explicit_aspects` default: "false" + +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]graph:factored` default: "true" + +If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--graph:node_limit=<an integer>` default: "512" + +The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]implicit_deps` default: "true" + +If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]include_aspects` default: "true" + +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]incompatible_package_group_includes_double_slash` default: "true" + +If enabled, when outputting package\_group's `packages` attribute, the leading `//` will not be omitted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]infer_universe_scope` default: "false" + +If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g. `allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]line_terminator_null` default: "false" + +Whether each format is terminated with \\0 instead of newline. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]nodep_deps` default: "true" + +If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--output=<a string>` default: "label" + +The format in which the cquery results should be printed. Allowed values for cquery are: label, label\_kind, textproto, transitions, proto, streamed\_proto, jsonproto. If you select 'transitions', you also have to specify the --transitions=(lite\|full) option. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--output_file=<a string>` default: "" + +When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query > file</code>. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:default_values` default: "true" + +If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:definition_stack` default: "false" + +Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:flatten_selects` default: "true" + +If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]proto:include_attribute_source_aspects` default: "false" + +Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:include_configurations` default: "true" + +if enabled, proto output will include information about configurations. When disabled,cquery proto output format resembles query output format. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]proto:include_starlark_rule_env` default: "true" + +Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:include_synthetic_attribute_hash` default: "false" + +Whether or not to calculate and populate the $internal\_attr\_hash attribute. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:instantiation_stack` default: "false" + +Populate the instantiation call stack of each rule. Note that this requires the stack to be present + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:locations` default: "true" + +Whether to output location information in proto output at all. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" + +Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:rule_classes` default: "false" + +Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:rule_inputs_and_outputs` default: "true" + +Whether or not to populate the rule\_input and rule\_output fields. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--query_file=<a string>` default: "" + +If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--[no]relative_locations` default: "false" + +If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--show_config_fragments=<off, direct or transitive>` default: "off" + +Shows the configuration fragments required by a rule and its transitive dependencies. This can be useful for evaluating how much a configured target graph can be trimmed. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--starlark:expr=<a string>` default: "" + +A Starlark expression to format each configured target in cquery's --output=starlark mode. The configured target is bound to 'target'. If neither --starlark:expr nor --starlark:file is specified, this option will default to 'str(target.label)'. It is an error to specify both --starlark:expr and --starlark:file. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--starlark:file=<a string>` default: "" + +The name of a file that defines a Starlark function called 'format', of one argument, that is applied to each configured target to format it as a string. It is an error to specify both --starlark:expr and --starlark:file. See help for --output=starlark for additional detail. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]tool_deps` default: "true" + +Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--transitions=<full, lite or none>` default: "none" + +The format in which cquery will print transition information. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--universe_scope=<comma-separated list of options>` default: "" + +A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options that control build execution: +`--[no]experimental_persistent_aar_extractor` default: "false" + +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_remotable_source_manifests` default: "false" + +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_split_coverage_postprocessing` default: "false" + +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_strict_fileset_output` default: "false" + +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_modify_execution_info_additive` default: "true" + +When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated + +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'. _=+x,._ =-y,. _=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions._ +_'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions._ +_'(?!Genrule)._ =-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` + +Enable persistent Android dex and desugar actions by using workers. + +Expands to: + +`--internal_persistent_android_dex_desugar` + +`--strategy=Desugar=worker` + +`--strategy=DexBuilder=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` + +Enable persistent Android resource processor by using workers. + +Expands to: + +`--internal_persistent_busybox_tools` + +`--strategy=AaptPackage=worker` + +`--strategy=AndroidResourceParser=worker` + +`--strategy=AndroidResourceValidator=worker` + +`--strategy=AndroidResourceCompiler=worker` + +`--strategy=RClassGenerator=worker` + +`--strategy=AndroidResourceLink=worker` + +`--strategy=AndroidAapt2=worker` + +`--strategy=AndroidAssetMerger=worker` + +`--strategy=AndroidResourceMerger=worker` + +`--strategy=AndroidCompiledResourceMerger=worker` + +`--strategy=ManifestMerger=worker` + +`--strategy=AndroidManifestMerger=worker` + +`--strategy=Aapt2Optimize=worker` + +`--strategy=AARGenerator=worker` + +`--strategy=ProcessDatabinding=worker` + +`--strategy=GenerateDataBindingBaseClasses=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` + +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: + +`--persistent_android_dex_desugar` + +`--internal_persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` + +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: + +`--persistent_android_resource_processor` + +`--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +`--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +`--modify_execution_info=AARGenerator=+supports-multiplex-workers` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` + +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: + +`--internal_persistent_multiplex_busybox_tools` + +`--persistent_multiplex_android_resource_processor` + +`--persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" + +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: +`--android_compiler=<a string>` default: see description + +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" + +Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_platforms=<a build target label>` default: "" + +Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--cc_output_directory_tag=<a string>` default: "" + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compiler=<a string>` default: see description + +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" + +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" + +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" + +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--custom_malloc=<a build target label>` default: see description + +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_include_xcode_execution_requirements` default: "false" + +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version\_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_prefer_mutual_xcode` default: "true" + +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--extra_execution_platforms=<comma-separated list of options>` default: "" + +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated + +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--grte_top=<a label>` default: see description + +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_compiler=<a string>` default: see description + +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--host_grte_top=<a label>` default: see description + +If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" + +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]incompatible_bazel_test_exec_run_under` default: "true" + +If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run\_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_builtin_objc_strip_action` default: "true" + +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" + +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" + +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_remove_legacy_whole_archive` default: "true" + +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strip_executable_safely` default: "false" + +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]interface_shared_objects` default: "true" + +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--minimum_os_version=<a string>` default: see description + +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_mappings=<a main workspace-relative path>` default: "" + +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--platforms=<a build target label>` default: "" + +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_path=<a string>` default: see description + +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" + +Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version=<a string>` default: see description + +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" + +The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options that control the output of the command: +`--[no]apple_generate_dsym` default: "false" + +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]build_runfile_links` default: "true" + +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_runfile_manifests` default: "true" + +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_test_dwp` default: "false" + +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" + +Sets the suffixes of header files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" + +Sets the suffixes of source files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" + +Run extra actions for alternative Java api versions in a proto\_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_save_feature_state` default: "false" + +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fission=<a set of compilation modes>` default: "no" + +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_always_include_files_in_data` default: "true" + +If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" + +If enabled, the <binary>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" + +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" + +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]objc_generate_linkmap` default: "false" + +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]save_temps` default: "false" + +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible\_repo\_env\_ignores\_action\_env</code> is true, all <code>name=value</code> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--allowed_cpu_values=<comma-separated set of options>` default: "" + +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]android_databinding_use_androidx` default: "true" + +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]android_databinding_use_v3_4_args` default: "true" + +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--android_dynamic_mode=<off, default or fully>` default: "off" + +Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" + +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +`--[no]android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]build_python_zip` default: "auto" + +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]collect_code_coverage` default: "false" + +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compilation_mode=<fastbuild, dbg or opt>` \[ `-c`\] default: "fastbuild" + +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--copt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cpu=<a string>` default: "" + +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_absolute_path=<a string>` default: see description + +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_instrument=<a string>` default: see description + +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_profile=<a build target label>` default: see description + +The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cxxopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--define=<a 'name=value' assignment>` multiple uses are accumulated + +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--dynamic_mode=<off, default or fully>` default: "default" + +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_propeller_optimize_absolute_paths` default: "true" + +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_remaining_fdo_absolute_paths` default: "true" + +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_runfiles` default: "auto" + +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_action_listener=<a build target label>` multiple uses are accumulated + +Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_compress_java_resources` default: "false" + +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_databinding_v2` default: "true" + +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" + +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" + +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" + +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]experimental_omitfp` default: "false" + +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_output_paths=<off or strip>` default: "off" + +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated + +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_platform_in_output_dir` default: "false" + +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_py_binaries_include_label` default: "false" + +py\_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_llvm_covmap` default: "false" + +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" + +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fdo_instrument=<a string>` default: see description + +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_optimize=<a string>` default: see description + +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` \- you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_prefetch_hints=<a build target label>` default: see description + +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_profile=<a build target label>` default: see description + +The fdo\_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host\_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]force_pic` default: "false" + +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" + +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_copt=<a string>` multiple uses are accumulated + +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cpu=<a string>` default: "" + +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cxxopt=<a string>` multiple uses are accumulated + +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_auto_exec_groups` default: "false" + +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_merge_genfiles_directory` default: "true" + +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_target_cpu_from_platform` default: "true" + +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]instrument_test_targets` default: "false" + +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" + +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]legacy_whole_archive` default: "true" + +Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +`--linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltobackendopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO backend step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltoindexopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO indexing step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--memprof_profile=<a build target label>` default: see description + +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]objc_debug_with_GLIBCXX` default: "false" + +If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]objc_enable_binary_stripping` default: "false" + +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--objccopt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_suffix=<a string>` default: see description + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--propeller_optimize=<a build target label>` default: see description + +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description + +Absolute path name of cc\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description + +Absolute path name of ld\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--run_under=<a prefix in front of command>` default: see description + +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]share_native_deps` default: "true" + +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]stamp` default: "false" + +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--strip=<always, sometimes or never>` default: "sometimes" + +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--stripopt=<a string>` multiple uses are accumulated + +Additional options to pass to strip when generating a '<name>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xbinary_fdo=<a build target label>` default: see description + +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]check_visibility` default: "true" + +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]desugar_for_android` default: "true" + +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]desugar_java8_libs` default: "false" + +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]enforce_constraints` default: "true" + +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" + +When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" + +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]incompatible_check_testonly_for_output_files` default: "false" + +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_android_rules` default: "false" + +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" + +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]one_version_enforcement_on_java_tests` default: "true" + +When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_native_rules_allowlist=<a build target label>` default: see description + +An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]strict_filesets` default: "false" + +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" + +Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" + +Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]strict_system_includes` default: "false" + +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--target_environment=<a build target label>` multiple uses are accumulated + +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Options that affect the signing outputs of a build: +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" + +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]device_debug_entitlements` default: "true" + +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--ios_signing_cert_name=<a string>` default: see description + +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" + +If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_objc_alwayslink_by_default` default: "false" + +If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_python_disallow_native_rules` default: "false" + +When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that govern the behavior of the test environment or test runner: +`--[no]allow_analysis_failures` default: "false" + +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--analysis_testing_deps_limit=<an integer>` default: "2000" + +Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" + +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated + +Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by \[-\| _\]<float> (eg. memory=HOST\_RAM_.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +`--[no]experimental_android_use_parallel_dex2oat` default: "false" + +Use dex2oat in parallel to possibly speed up android\_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]ios_memleaks` default: "false" + +Enable checking for memory leaks in ios\_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--ios_simulator_device=<a string>` default: see description + +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated + +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/. _,-//foo/bar/._@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" + +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +`--[no]zip_undeclared_test_outputs` default: "false" + +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +Options that trigger optimizations of the build time: +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" + +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_dotd_files` default: "true" + +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_jdeps_files` default: "true" + +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" + +When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" + +Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]process_headers_in_dependencies` default: "false" + +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]trim_test_configuration` default: "true" + +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +Options that affect the verbosity, format or location of logging: +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" + +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]verbose_visibility_errors` default: "false" + +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated + +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_default_to_explicit_init_py` default: "false" + +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Miscellaneous options, not otherwise categorized.: +`--[no]cache_test_results` \[ `-t`\] default: "auto" + +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +`--[no]experimental_cancel_concurrent_tests` default: "never" + +If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_fetch_all_coverage_outputs` default: "false" + +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_generate_llvm_lcov` default: "false" + +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" + +Enables reduced classpaths for Java compilations. + +`--[no]experimental_run_android_lint_on_java_rules` default: "false" + +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[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. + +`--host_java_launcher=<a build target label>` default: see description + +The Java launcher used by tools that are executed during a build. + +`--host_javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac when building tools that are executed during a build. + +`--host_jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. + +`--[no]incompatible_check_sharding_support` default: "true" + +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_exclusive_test_sandboxed` default: "true" + +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strict_action_env` default: "false" + +If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated + +Additional options to pass to the J2ObjC tool. + +`--java_debug` + +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. + +Expands to: + +`--test_arg=--wrapper_script_flag=--debug` + +`--test_output=streamed` + +`--test_strategy=exclusive` + +`--test_timeout=9999` + +`--nocache_test_results` + +`--[no]java_deps` default: "true" + +Generate dependency information (for now, compile-time classpath) per Java target. + +`--[no]java_header_compilation` default: "true" + +Compile ijars directly from source. + +`--java_language_version=<a string>` default: "" + +The Java language version + +`--java_launcher=<a build target label>` default: see description + +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +`--java_runtime_version=<a string>` default: "local\_jdk" + +The Java runtime version + +`--javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac. + +`--jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. + +`--legacy_main_dex_list_generator=<a build target label>` default: see description + +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +`--optimizing_dexer=<a build target label>` default: see description + +Specifies a binary to use to do dexing without sharding. + +`--plugin=<a build target label>` multiple uses are accumulated + +Plugins to use in the build. Currently works with java\_plugin. + +`--proguard_top=<a build target label>` default: see description + +Specifies which version of ProGuard to use for code removal when building a Java binary. + +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" + +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]proto_profile` default: "true" + +Whether to pass profile\_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_profile_path=<a build target label>` default: see description + +The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--protocopt=<a string>` multiple uses are accumulated + +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]runs_per_test_detects_flakes` default: "false" + +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +`--shell_executable=<a path>` default: see description + +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--test_arg=<a string>` multiple uses are accumulated + +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +`--test_filter=<a string>` default: see description + +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +`--test_result_expiration=<an integer>` default: "-1" + +This option is deprecated and has no effect. + +`--[no]test_runner_fail_fast` default: "false" + +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" + +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. + +`--tool_java_language_version=<a string>` default: "" + +The Java language version used to execute the tools that are needed during a build + +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" + +The Java runtime version used to execute tools during the build + +`--[no]use_ijars` default: "true" + +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## Dump Options + +Options that control the output of the command: +`--[no]action_cache` default: "false" + +Dump action cache content. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--memory=<memory mode>` default: see description + +Dump the memory use of the given Skyframe node. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]packages` default: "false" + +Dump package cache content. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]rule_classes` default: "false" + +Dump rule classes. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--[no]rules` default: "false" + +Dump rules, including counts and memory usage (if memory is tracked). + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--skyframe=<off, summary, count, value, deps, rdeps, function_graph, active_directories or active_directories_frontier_deps>` default: "off" + +Dump the Skyframe graph. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--skykey_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: ".\*" + +Regex filter of SkyKey names to output. Only used with --skyframe=deps, rdeps, function\_graph. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +`--skylark_memory=<a string>` default: see description + +Dumps a pprof-compatible memory profile to the specified path. To learn more please see https://github.com/google/pprof. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +## Fetch Options + +Inherits all options from [test](#test). + +Options that control build execution: +`--[no]all` default: "false" + +Fetches all external repositories necessary for building any target or repository. This is the default if no other flags and arguments are provided. Only works when --enable\_bzlmod is on. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--[no]keep_going` \[ `-k`\] default: "false" + +Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" + +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_config_setting_private_default_visibility` default: "false" + +If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enforce_config_setting_visibility` default: "true" + +If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options relating to Bzlmod output and semantics: +`--[no]configure` default: "false" + +Only fetches repositories marked as 'configure' for system-configuration purpose. Only works when --enable\_bzlmod is on. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--[no]force` default: "false" + +Ignore existing repository if any and force fetch the repository again. Only works when --enable\_bzlmod is on. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--repo=<a string>` multiple uses are accumulated + +Only fetches the specified repository, which can be either {@apparent\_repo\_name} or {@@canonical\_repo\_name}. Only works when --enable\_bzlmod is on. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Miscellaneous options, not otherwise categorized.: +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated + +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. + +`--[no]fetch` default: "true" + +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +`--package_path=<colon-separated list of options>` default: "%workspace%" + +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +`--[no]show_loading_progress` default: "true" + +If enabled, causes Bazel to print "Loading package:" messages. + +Options that control build execution: +`--[no]experimental_persistent_aar_extractor` default: "false" + +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_remotable_source_manifests` default: "false" + +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_split_coverage_postprocessing` default: "false" + +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_strict_fileset_output` default: "false" + +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_modify_execution_info_additive` default: "true" + +When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated + +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'. _=+x,._ =-y,. _=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions._ +_'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions._ +_'(?!Genrule)._ =-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` + +Enable persistent Android dex and desugar actions by using workers. + +Expands to: + +`--internal_persistent_android_dex_desugar` + +`--strategy=Desugar=worker` + +`--strategy=DexBuilder=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` + +Enable persistent Android resource processor by using workers. + +Expands to: + +`--internal_persistent_busybox_tools` + +`--strategy=AaptPackage=worker` + +`--strategy=AndroidResourceParser=worker` + +`--strategy=AndroidResourceValidator=worker` + +`--strategy=AndroidResourceCompiler=worker` + +`--strategy=RClassGenerator=worker` + +`--strategy=AndroidResourceLink=worker` + +`--strategy=AndroidAapt2=worker` + +`--strategy=AndroidAssetMerger=worker` + +`--strategy=AndroidResourceMerger=worker` + +`--strategy=AndroidCompiledResourceMerger=worker` + +`--strategy=ManifestMerger=worker` + +`--strategy=AndroidManifestMerger=worker` + +`--strategy=Aapt2Optimize=worker` + +`--strategy=AARGenerator=worker` + +`--strategy=ProcessDatabinding=worker` + +`--strategy=GenerateDataBindingBaseClasses=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` + +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: + +`--persistent_android_dex_desugar` + +`--internal_persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` + +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: + +`--persistent_android_resource_processor` + +`--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +`--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +`--modify_execution_info=AARGenerator=+supports-multiplex-workers` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` + +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: + +`--internal_persistent_multiplex_busybox_tools` + +`--persistent_multiplex_android_resource_processor` + +`--persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" + +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: +`--android_compiler=<a string>` default: see description + +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" + +Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_platforms=<a build target label>` default: "" + +Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--cc_output_directory_tag=<a string>` default: "" + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compiler=<a string>` default: see description + +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" + +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" + +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" + +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--custom_malloc=<a build target label>` default: see description + +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_include_xcode_execution_requirements` default: "false" + +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version\_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_prefer_mutual_xcode` default: "true" + +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--extra_execution_platforms=<comma-separated list of options>` default: "" + +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated + +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--grte_top=<a label>` default: see description + +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_compiler=<a string>` default: see description + +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--host_grte_top=<a label>` default: see description + +If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" + +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]incompatible_bazel_test_exec_run_under` default: "true" + +If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run\_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_builtin_objc_strip_action` default: "true" + +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" + +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" + +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_remove_legacy_whole_archive` default: "true" + +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strip_executable_safely` default: "false" + +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]interface_shared_objects` default: "true" + +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--minimum_os_version=<a string>` default: see description + +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_mappings=<a main workspace-relative path>` default: "" + +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--platforms=<a build target label>` default: "" + +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_path=<a string>` default: see description + +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" + +Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version=<a string>` default: see description + +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" + +The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options that control the output of the command: +`--[no]apple_generate_dsym` default: "false" + +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]build_runfile_links` default: "true" + +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_runfile_manifests` default: "true" + +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_test_dwp` default: "false" + +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" + +Sets the suffixes of header files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" + +Sets the suffixes of source files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" + +Run extra actions for alternative Java api versions in a proto\_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_save_feature_state` default: "false" + +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fission=<a set of compilation modes>` default: "no" + +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_always_include_files_in_data` default: "true" + +If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" + +If enabled, the <binary>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" + +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" + +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]objc_generate_linkmap` default: "false" + +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]save_temps` default: "false" + +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible\_repo\_env\_ignores\_action\_env</code> is true, all <code>name=value</code> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--allowed_cpu_values=<comma-separated set of options>` default: "" + +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]android_databinding_use_androidx` default: "true" + +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]android_databinding_use_v3_4_args` default: "true" + +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--android_dynamic_mode=<off, default or fully>` default: "off" + +Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" + +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +`--[no]android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]build_python_zip` default: "auto" + +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]collect_code_coverage` default: "false" + +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compilation_mode=<fastbuild, dbg or opt>` \[ `-c`\] default: "fastbuild" + +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--copt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cpu=<a string>` default: "" + +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_absolute_path=<a string>` default: see description + +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_instrument=<a string>` default: see description + +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_profile=<a build target label>` default: see description + +The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cxxopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--define=<a 'name=value' assignment>` multiple uses are accumulated + +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--dynamic_mode=<off, default or fully>` default: "default" + +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_propeller_optimize_absolute_paths` default: "true" + +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_remaining_fdo_absolute_paths` default: "true" + +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_runfiles` default: "auto" + +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_action_listener=<a build target label>` multiple uses are accumulated + +Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_compress_java_resources` default: "false" + +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_databinding_v2` default: "true" + +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" + +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" + +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" + +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]experimental_omitfp` default: "false" + +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_output_paths=<off or strip>` default: "off" + +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated + +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_platform_in_output_dir` default: "false" + +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_py_binaries_include_label` default: "false" + +py\_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_llvm_covmap` default: "false" + +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" + +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fdo_instrument=<a string>` default: see description + +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_optimize=<a string>` default: see description + +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` \- you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_prefetch_hints=<a build target label>` default: see description + +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_profile=<a build target label>` default: see description + +The fdo\_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host\_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]force_pic` default: "false" + +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" + +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_copt=<a string>` multiple uses are accumulated + +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cpu=<a string>` default: "" + +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cxxopt=<a string>` multiple uses are accumulated + +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_auto_exec_groups` default: "false" + +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_merge_genfiles_directory` default: "true" + +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_target_cpu_from_platform` default: "true" + +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]instrument_test_targets` default: "false" + +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" + +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]legacy_whole_archive` default: "true" + +Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +`--linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltobackendopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO backend step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltoindexopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO indexing step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--memprof_profile=<a build target label>` default: see description + +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]objc_debug_with_GLIBCXX` default: "false" + +If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]objc_enable_binary_stripping` default: "false" + +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--objccopt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_suffix=<a string>` default: see description + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--propeller_optimize=<a build target label>` default: see description + +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description + +Absolute path name of cc\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description + +Absolute path name of ld\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--run_under=<a prefix in front of command>` default: see description + +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]share_native_deps` default: "true" + +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]stamp` default: "false" + +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--strip=<always, sometimes or never>` default: "sometimes" + +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--stripopt=<a string>` multiple uses are accumulated + +Additional options to pass to strip when generating a '<name>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xbinary_fdo=<a build target label>` default: see description + +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]check_visibility` default: "true" + +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]desugar_for_android` default: "true" + +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]desugar_java8_libs` default: "false" + +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]enforce_constraints` default: "true" + +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" + +When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" + +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]incompatible_check_testonly_for_output_files` default: "false" + +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_android_rules` default: "false" + +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" + +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]one_version_enforcement_on_java_tests` default: "true" + +When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_native_rules_allowlist=<a build target label>` default: see description + +An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]strict_filesets` default: "false" + +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" + +Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" + +Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]strict_system_includes` default: "false" + +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--target_environment=<a build target label>` multiple uses are accumulated + +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Options that affect the signing outputs of a build: +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" + +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]device_debug_entitlements` default: "true" + +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--ios_signing_cert_name=<a string>` default: see description + +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" + +If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_objc_alwayslink_by_default` default: "false" + +If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_python_disallow_native_rules` default: "false" + +When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that govern the behavior of the test environment or test runner: +`--[no]allow_analysis_failures` default: "false" + +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--analysis_testing_deps_limit=<an integer>` default: "2000" + +Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" + +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated + +Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by \[-\| _\]<float> (eg. memory=HOST\_RAM_.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +`--[no]experimental_android_use_parallel_dex2oat` default: "false" + +Use dex2oat in parallel to possibly speed up android\_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]ios_memleaks` default: "false" + +Enable checking for memory leaks in ios\_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--ios_simulator_device=<a string>` default: see description + +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated + +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/. _,-//foo/bar/._@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" + +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +`--[no]zip_undeclared_test_outputs` default: "false" + +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +Options that trigger optimizations of the build time: +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" + +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_dotd_files` default: "true" + +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_jdeps_files` default: "true" + +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" + +When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" + +Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]process_headers_in_dependencies` default: "false" + +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]trim_test_configuration` default: "true" + +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +Options that affect the verbosity, format or location of logging: +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" + +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]verbose_visibility_errors` default: "false" + +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated + +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_default_to_explicit_init_py` default: "false" + +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Miscellaneous options, not otherwise categorized.: +`--[no]cache_test_results` \[ `-t`\] default: "auto" + +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +`--[no]experimental_cancel_concurrent_tests` default: "never" + +If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_fetch_all_coverage_outputs` default: "false" + +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_generate_llvm_lcov` default: "false" + +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" + +Enables reduced classpaths for Java compilations. + +`--[no]experimental_run_android_lint_on_java_rules` default: "false" + +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[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. + +`--host_java_launcher=<a build target label>` default: see description + +The Java launcher used by tools that are executed during a build. + +`--host_javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac when building tools that are executed during a build. + +`--host_jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. + +`--[no]incompatible_check_sharding_support` default: "true" + +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_exclusive_test_sandboxed` default: "true" + +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strict_action_env` default: "false" + +If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated + +Additional options to pass to the J2ObjC tool. + +`--java_debug` + +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. + +Expands to: + +`--test_arg=--wrapper_script_flag=--debug` + +`--test_output=streamed` + +`--test_strategy=exclusive` + +`--test_timeout=9999` + +`--nocache_test_results` + +`--[no]java_deps` default: "true" + +Generate dependency information (for now, compile-time classpath) per Java target. + +`--[no]java_header_compilation` default: "true" + +Compile ijars directly from source. + +`--java_language_version=<a string>` default: "" + +The Java language version + +`--java_launcher=<a build target label>` default: see description + +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +`--java_runtime_version=<a string>` default: "local\_jdk" + +The Java runtime version + +`--javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac. + +`--jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. + +`--legacy_main_dex_list_generator=<a build target label>` default: see description + +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +`--optimizing_dexer=<a build target label>` default: see description + +Specifies a binary to use to do dexing without sharding. + +`--plugin=<a build target label>` multiple uses are accumulated + +Plugins to use in the build. Currently works with java\_plugin. + +`--proguard_top=<a build target label>` default: see description + +Specifies which version of ProGuard to use for code removal when building a Java binary. + +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" + +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]proto_profile` default: "true" + +Whether to pass profile\_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_profile_path=<a build target label>` default: see description + +The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--protocopt=<a string>` multiple uses are accumulated + +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]runs_per_test_detects_flakes` default: "false" + +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +`--shell_executable=<a path>` default: see description + +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--test_arg=<a string>` multiple uses are accumulated + +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +`--test_filter=<a string>` default: see description + +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +`--test_result_expiration=<an integer>` default: "-1" + +This option is deprecated and has no effect. + +`--[no]test_runner_fail_fast` default: "false" + +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" + +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. + +`--tool_java_language_version=<a string>` default: "" + +The Java language version used to execute the tools that are needed during a build + +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" + +The Java runtime version used to execute tools during the build + +`--[no]use_ijars` default: "true" + +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## Help Options + +Options that affect the verbosity, format or location of logging: +`--help_verbosity=<long, medium or short>` default: "medium" + +Select the verbosity of the help command. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--long` \[ `-l`\] + +Show full description of each option, instead of just its name. + +Expands to: + +`--help_verbosity=long` + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--short` + +Show only the names of the options, not their types or meanings. + +Expands to: + +`--help_verbosity=short` + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +## Info Options + +Inherits all options from [build](#build). + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--info_output_type=<stdout or response_proto>` default: "stdout" + +If stdout, results are directly printed to the console. If response\_proto, the info command results are packed in response extensions. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +Options that affect the verbosity, format or location of logging: +`--[no]show_make_env` default: "false" + +Include the "Make" environment in the output. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +## License Options + +## Mobile-install Options + +Inherits all options from [build](#build). + +Options that control build execution: +`--mode=<classic, classic_internal_test_do_not_use or skylark>` default: "skylark" + +Deprecated no-effect flag. Only skylark mode is still supported. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that configure the toolchain used for action execution: +`--adb=<a string>` default: "" + +adb binary to use for the 'mobile-install' command. If unspecified, the one in the Android SDK specified by the --android\_sdk\_channel command line option (or the default SDK if --android\_sdk\_channel is not specified) is used. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Options that control the output of the command: +`--[no]incremental` default: "false" + +Whether to do an incremental install. If true, try to avoid unnecessary additional work by reading the state of the device the code is to be installed on and using that information to avoid unnecessary work. If false (the default), always do a full install. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]split_apks` default: "false" + +Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--adb_arg=<a string>` multiple uses are accumulated + +Extra arguments to pass to adb. Usually used to designate a device to install to. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--debug_app` + +Whether to wait for the debugger before starting the app. + +Expands to: + +`--start=DEBUG` + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--device=<a string>` default: "" + +The adb device serial number. If not specified, the first device will be used. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--start=<no, cold, warm or debug>` default: "NO" + +How the app should be started after installing it. Set to WARM to preserve and restore application state on incremental installs. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--start_app` + +Whether to start the app after installing it. + +Expands to: + +`--start=COLD` + +Tags: +[`execution`](#effect_tag_EXECUTION) + +Options that affect the verbosity, format or location of logging: +`--incremental_install_verbosity=<a string>` default: "" + +The verbosity for incremental install. Set to 1 for debug logging. + +Tags: +[`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) + +## Mod Options + +Options that control build execution: +`--[no]experimental_remotable_source_manifests` default: "false" + +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_strict_fileset_output` default: "false" + +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_modify_execution_info_additive` default: "true" + +When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" + +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated + +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'. _=+x,._ =-y,. _=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions._ +_'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions._ +_'(?!Genrule)._ =-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]use_target_platform_for_tests` default: "false" + +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: +`--[no]incompatible_bazel_test_exec_run_under` default: "true" + +If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run\_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that control the output of the command: +`--[no]build_runfile_links` default: "true" + +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_runfile_manifests` default: "true" + +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_always_include_files_in_data` default: "true" + +If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" + +If enabled, the <binary>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" + +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" + +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible\_repo\_env\_ignores\_action\_env</code> is true, all <code>name=value</code> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--allowed_cpu_values=<comma-separated set of options>` default: "" + +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]collect_code_coverage` default: "false" + +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compilation_mode=<fastbuild, dbg or opt>` \[ `-c`\] default: "fastbuild" + +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--cpu=<a string>` default: "" + +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--define=<a 'name=value' assignment>` multiple uses are accumulated + +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_runfiles` default: "auto" + +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_action_listener=<a build target label>` multiple uses are accumulated + +Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" + +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_output_paths=<off or strip>` default: "off" + +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated + +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_platform_in_output_dir` default: "false" + +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" + +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host\_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" + +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_cpu=<a string>` default: "" + +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_auto_exec_groups` default: "false" + +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_merge_genfiles_directory` default: "true" + +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_target_cpu_from_platform` default: "true" + +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]instrument_test_targets` default: "false" + +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" + +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_suffix=<a string>` default: see description + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--run_under=<a prefix in front of command>` default: see description + +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]stamp` default: "false" + +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]check_visibility` default: "true" + +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]enforce_constraints` default: "true" + +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_check_testonly_for_output_files` default: "false" + +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]strict_filesets` default: "false" + +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--target_environment=<a build target label>` multiple uses are accumulated + +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_config_setting_private_default_visibility` default: "false" + +If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enforce_config_setting_visibility` default: "true" + +If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that govern the behavior of the test environment or test runner: +`--[no]allow_analysis_failures` default: "false" + +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--analysis_testing_deps_limit=<an integer>` default: "2000" + +Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options relating to the output and semantics of the \`mod\` subcommand: +`--base_module=<"<root>" for the root module; <module>@<version> for a specific version of a module; <module> for all versions of a module; @<name> for a repo with the given apparent name; or @@<name> for a repo with the given canonical name>` default: "<root>" + +Specify a module relative to which the specified target repos will be interpreted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--charset=<utf8 or ascii>` default: "utf8" + +Chooses the character set to use for the tree. Only affects text output. Valid values are "utf8" or "ascii". Default is "utf8" + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]cycles` default: "true" + +Points out dependency cycles inside the displayed tree. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--depth=<an integer>` default: "-1" + +Maximum display depth of the dependency tree. A depth of 1 displays the direct dependencies, for example. For tree, path and all\_paths it defaults to Integer.MAX\_VALUE, while for deps and explain it defaults to 1 (only displays direct deps of the root besides the target leaves and their parents). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--extension_filter=<a comma-separated list of <extension>s>` default: see description + +Only display the usages of these module extensions and the repos generated by them if their respective flags are set. If set, the result graph will only include paths that contain modules using the specified extensions. An empty list disables the filter, effectively specifying all possible extensions. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--extension_info=<hidden, usages, repos or all>` default: "hidden" + +Specify how much detail about extension usages to include in the query result. "Usages" will only show the extensions names, "repos" will also include repos imported with use\_repo, and "all" will also show the other repositories generated by extensions. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--extension_usages=<a comma-separated list of <module>s>` default: "" + +Specify modules whose extension usages will be displayed in the show\_extension query. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--from=<a comma-separated list of <module>s>` default: "<root>" + +The module(s) starting from which the dependency graph query will be displayed. Check each query’s description for the exact semantics. Defaults to <root>. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]include_builtin` default: "false" + +Include built-in modules in the dependency graph. Disabled by default because it is quite noisy. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]include_unused` default: "false" + +The queries will also take into account and display the unused modules, which are not present in the module resolution graph after selection (due to the Minimal-Version Selection or override rules). This can have different effects for each of the query types i.e. include new paths in the all\_paths command, or extra dependants in the explain command. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--output=<text, json or graph>` default: "text" + +The format in which the query results should be printed. Allowed values for query are: text, json, graph + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]verbose` default: "false" + +The queries will also display the reason why modules were resolved to their current version (if changed). Defaults to true only for the explain query. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +Options that affect the verbosity, format or location of logging: +`--[no]verbose_visibility_errors` default: "false" + +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated + +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Miscellaneous options, not otherwise categorized.: +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated + +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. + +`--[no]fetch` default: "true" + +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +`--package_path=<colon-separated list of options>` default: "%workspace%" + +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +`--[no]show_loading_progress` default: "true" + +If enabled, causes Bazel to print "Loading package:" messages. + +## Print\_action Options + +Inherits all options from [build](#build). + +Miscellaneous options, not otherwise categorized.: +`--print_action_mnemonics=<a string>` multiple uses are accumulated + +Lists which mnemonics to filter print\_action data by, no filtering takes place when left empty. + +## Query Options + +Options that control build execution: +`--[no]experimental_remotable_source_manifests` default: "false" + +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_strict_fileset_output` default: "false" + +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_modify_execution_info_additive` default: "true" + +When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]keep_going` \[ `-k`\] default: "false" + +Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" + +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated + +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'. _=+x,._ =-y,. _=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions._ +_'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions._ +_'(?!Genrule)._ =-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]use_target_platform_for_tests` default: "false" + +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: +`--[no]incompatible_bazel_test_exec_run_under` default: "true" + +If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run\_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that control the output of the command: +`--[no]build_runfile_links` default: "true" + +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_runfile_manifests` default: "true" + +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_always_include_files_in_data` default: "true" + +If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" + +If enabled, the <binary>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" + +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" + +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible\_repo\_env\_ignores\_action\_env</code> is true, all <code>name=value</code> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--allowed_cpu_values=<comma-separated set of options>` default: "" + +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]collect_code_coverage` default: "false" + +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compilation_mode=<fastbuild, dbg or opt>` \[ `-c`\] default: "fastbuild" + +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--cpu=<a string>` default: "" + +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--define=<a 'name=value' assignment>` multiple uses are accumulated + +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_runfiles` default: "auto" + +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_action_listener=<a build target label>` multiple uses are accumulated + +Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" + +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_output_paths=<off or strip>` default: "off" + +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated + +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_platform_in_output_dir` default: "false" + +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" + +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host\_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" + +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_cpu=<a string>` default: "" + +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_auto_exec_groups` default: "false" + +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_merge_genfiles_directory` default: "true" + +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_target_cpu_from_platform` default: "true" + +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]instrument_test_targets` default: "false" + +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" + +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_suffix=<a string>` default: see description + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--run_under=<a prefix in front of command>` default: see description + +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]stamp` default: "false" + +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]check_visibility` default: "true" + +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]enforce_constraints` default: "true" + +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_check_testonly_for_output_files` default: "false" + +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]strict_filesets` default: "false" + +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--target_environment=<a build target label>` multiple uses are accumulated + +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_config_setting_private_default_visibility` default: "false" + +If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enforce_config_setting_visibility` default: "true" + +If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that govern the behavior of the test environment or test runner: +`--[no]allow_analysis_failures` default: "false" + +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--analysis_testing_deps_limit=<an integer>` default: "2000" + +Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options relating to query output and semantics: +`--aspect_deps=<off, conservative or precise>` default: "conservative" + +How to resolve aspect dependencies when the output format is one of {xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' (the default) means all declared aspect dependencies are added regardless of whether they are given the rule class of direct dependencies, 'precise' means that only those aspects are added that are possibly active given the rule class of the direct dependencies. Note that precise mode requires loading other packages to evaluate a single target thus making it slower than the other modes. Also note that even precise mode is not completely precise: the decision whether to compute an aspect is decided in the analysis phase, which is not run during 'bazel query'. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]consistent_labels` default: "false" + +If enabled, every query command emits labels as if by the Starlark <code>str</code> function applied to a <code>Label</code> instance. This is useful for tools that need to match the output of different query commands and/or labels emitted by rules. If not enabled, output formatters are free to emit apparent repository names (relative to the main repository) instead to make the output more readable. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]experimental_explicit_aspects` default: "false" + +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]experimental_graphless_query` default: "auto" + +If true, uses a Query implementation that does not make a copy of the graph. The new implementation only supports --order\_output=no, as well as only a subset of output formatters. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--graph:conditional_edges_limit=<an integer>` default: "4" + +The maximum number of condition labels to show. -1 means no truncation and 0 means no annotation. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]graph:factored` default: "true" + +If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes will be merged together and their labels concatenated. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--graph:node_limit=<an integer>` default: "512" + +The maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 means no truncation. This option is only applicable to --output=graph. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]implicit_deps` default: "true" + +If enabled, implicit dependencies will be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel. For cquery, this option controls filtering resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]include_aspects` default: "true" + +aquery, cquery: whether to include aspect-generated actions in the output. query: no-op (aspects are always followed). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]incompatible_lexicographical_output` default: "true" + +If this option is set, sorts --order\_output=auto output in lexicographical order. + +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. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]infer_universe_scope` default: "false" + +If set and --universe\_scope is unset, then a value of --universe\_scope will be inferred as the list of unique target patterns in the query expression. Note that the --universe\_scope value inferred for a query expression that uses universe-scoped functions (e.g. `allrdeps`) may not be what you want, so you should use this option only if you know what you are doing. See https://bazel.build/reference/query#sky-query for details and examples. If --universe\_scope is set, then this option's value is ignored. Note: this option applies only to `query` (i.e. not `cquery`). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]line_terminator_null` default: "false" + +Whether each format is terminated with \\0 instead of newline. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]nodep_deps` default: "true" + +If enabled, deps from "nodep" attributes will be included in the dependency graph over which the query operates. A common example of a "nodep" attribute is "visibility". Run and parse the output of `info build-language` to learn about all the "nodep" attributes in the build language. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--noorder_results` + +Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. + +Expands to: + +`--order_output=no` + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--null` + +Whether each format is terminated with \\0 instead of newline. + +Expands to: + +`--line_terminator_null=true` + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--order_output=<no, deps, auto or full>` default: "auto" + +Output the results unordered (no), dependency-ordered (deps), or fully ordered (full). The default is 'auto', meaning that results are output either dependency-ordered or fully ordered, depending on the output formatter (dependency-ordered for proto, minrank, maxrank, and graph, fully ordered for all others). When output is fully ordered, nodes are printed in a fully deterministic (total) order. First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a post-order depth-first search in which outgoing edges to unvisited nodes are traversed in alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order in which they were visited. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--order_results` + +Output the results in dependency-ordered (default) or unordered fashion. The unordered output is faster but only supported when --output is not minrank, maxrank, or graph. + +Expands to: + +`--order_output=auto` + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--output=<a string>` default: "label" + +The format in which the query results should be printed. Allowed values for query are: build, graph, streamed\_jsonproto, label, label\_kind, location, maxrank, minrank, package, proto, streamed\_proto, xml. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--output_file=<a string>` default: "" + +When specified, query results will be written directly to this file, and nothing will be printed to Bazel's standard output stream (stdout). In benchmarks, this is generally faster than <code>bazel query > file</code>. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:default_values` default: "true" + +If true, attributes whose value is not explicitly specified in the BUILD file are included; otherwise they are omitted. This option is applicable to --output=proto + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:definition_stack` default: "false" + +Populate the definition\_stack proto field, which records for each rule instance the Starlark call stack at the moment the rule's class was defined. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:flatten_selects` default: "true" + +If enabled, configurable attributes created by select() are flattened. For list types the flattened representation is a list containing each value of the select map exactly once. Scalar types are flattened to null. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--[no]proto:include_attribute_source_aspects` default: "false" + +Populate the source\_aspect\_name proto field of each Attribute with the source aspect that the attribute came from (empty string if it did not). + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:include_starlark_rule_env` default: "true" + +Use the starlark environment in the value of the generated $internal\_attr\_hash attribute. This ensures that the starlark rule definition (and its transitive imports) are part of this identifier. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:include_synthetic_attribute_hash` default: "false" + +Whether or not to calculate and populate the $internal\_attr\_hash attribute. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:instantiation_stack` default: "false" + +Populate the instantiation call stack of each rule. Note that this requires the stack to be present + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:locations` default: "true" + +Whether to output location information in proto output at all. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--proto:output_rule_attrs=<comma-separated list of options>` default: "all" + +Comma separated list of attributes to include in output. Defaults to all attributes. Set to empty string to not output any attribute. This option is applicable to --output=proto. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:rule_classes` default: "false" + +Populate the rule\_class\_key field of each rule; and for the first rule with a given rule\_class\_key, also populate its rule\_class\_info proto field. The rule\_class\_key field uniquely identifies a rule class, and the rule\_class\_info field is a Stardoc-format rule class API definition. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]proto:rule_inputs_and_outputs` default: "true" + +Whether or not to populate the rule\_input and rule\_output fields. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--query_file=<a string>` default: "" + +If set, query will read the query from the file named here, rather than on the command line. It is an error to specify a file here as well as a command-line query. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--[no]relative_locations` default: "false" + +If true, the location of BUILD files in xml and proto outputs will be relative. By default, the location output is an absolute path and will not be consistent across machines. You can set this option to true to have a consistent result across machines. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]strict_test_suite` default: "false" + +If true, the tests() expression gives an error if it encounters a test\_suite containing non-test targets. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]tool_deps` default: "true" + +Query: If disabled, dependencies on 'exec configuration' will not be included in the dependency graph over which the query operates. An 'exec configuration' dependency edge, such as the one from any 'proto\_library' rule to the Protocol Compiler, usually points to a tool executed during the build rather than a part of the same 'target' program. +Cquery: If disabled, filters out all configured targets which cross an execution transition from the top-level target that discovered this configured target. That means if the top-level target is in the target configuration, only configured targets also in the target configuration will be returned. If the top-level target is in the exec configuration, only exec configured targets will be returned. This option will NOT exclude resolved toolchains. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS) + +`--universe_scope=<comma-separated list of options>` default: "" + +A comma-separated set of target patterns (additive and subtractive). The query may be performed in the universe defined by the transitive closure of the specified targets. This option is used for the query and cquery commands. +For cquery, the input to this option is the targets all answers are built under and so this option may affect configurations and transitions. If this option is not specified, the top-level targets are assumed to be the targets parsed from the query expression. Note: For cquery, not specifying this option may cause the build to break if targets parsed from the query expression are not buildable with top-level options. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]xml:default_values` default: "false" + +If true, rule attributes whose value is not explicitly specified in the BUILD file are printed; otherwise they are omitted. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]xml:line_numbers` default: "true" + +If true, XML output contains line numbers. Disabling this option may make diffs easier to read. This option is only applicable to --output=xml. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +Options that affect the verbosity, format or location of logging: +`--[no]verbose_visibility_errors` default: "false" + +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated + +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Miscellaneous options, not otherwise categorized.: +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated + +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. + +`--[no]fetch` default: "true" + +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +`--package_path=<colon-separated list of options>` default: "%workspace%" + +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +`--[no]show_loading_progress` default: "true" + +If enabled, causes Bazel to print "Loading package:" messages. + +## Run Options + +Inherits all options from [build](#build). + +Options that appear before the command and are parsed by the client: +`--[no]portable_paths` default: "false" + +If true, includes paths to replace in ExecRequest to make the resulting paths portable. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]run` default: "true" + +If false, skip running the command line constructed for the built target. Note that this flag is ignored for all --script\_path builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--run_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to the target to run. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. Note that the executed target will generally see the full environment of the host except for those variables that have been explicitly unset. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--script_path=<a path>` default: see description + +If set, write a shell script to the given file which invokes the target. If this option is set, the target is not run from bazel. Use 'bazel run --script\_path=foo //foo && ./foo' to invoke target '//foo' This differs from 'bazel run //foo' in that the bazel lock is released and the executable is connected to the terminal's stdin. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +## Shutdown Options + +Options that control the output of the command: +`--iff_heap_size_greater_than=<an integer>` default: "0" + +Iff non-zero, then shutdown will only shut down the server if the total memory (in MB) consumed by the JVM exceeds this value. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +## Test Options + +Inherits all options from [build](#build). + +Options that affect the verbosity, format or location of logging: +`--[no]print_relative_test_log_paths` default: "false" + +If true, when printing the path to a test log, use relative path that makes use of the 'testlogs' convenience symlink. N.B. - A subsequent 'build'/'test'/etc invocation with a different configuration can cause the target of this symlink to change, making the path printed previously no longer useful. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]test_verbose_timeout_warnings` default: "false" + +If true, print additional warnings when the actual test execution time does not match the timeout defined by the test (whether implied or explicit). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]verbose_test_summary` default: "true" + +If true, print additional information (timing, number of failed runs, etc) in the test summary. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +## Vendor Options + +Inherits all options from [test](#test). + +Options that control build execution: +`--[no]keep_going` \[ `-k`\] default: "false" + +Continue as much as possible after an error. While the target that failed and those that depend on it cannot be analyzed, other prerequisites of these targets can be. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--loading_phase_threads=<an integer, or a keyword ("auto", "HOST_CPUS", "HOST_RAM"), optionally followed by an operation ([-|*]<float>) eg. "auto", "HOST_CPUS*.5">` default: "auto" + +Number of parallel threads to use for the loading/analysis phase.Takes an integer, or a keyword ("auto", "HOST\_CPUS", "HOST\_RAM"), optionally followed by an operation (\[-\| _\]<float>) eg. "auto", "HOST\_CPUS_.5". "auto" sets a reasonable default based on host resources. Must be at least 1. + +Tags: +[`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_config_setting_private_default_visibility` default: "false" + +If incompatible\_enforce\_config\_setting\_visibility=false, this is a noop. Else, if this flag is false, any config\_setting without an explicit visibility attribute is //visibility:public. If this flag is true, config\_setting follows the same visibility logic as all other rules. See https://github.com/bazelbuild/bazel/issues/12933. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enforce_config_setting_visibility` default: "true" + +If true, enforce config\_setting visibility restrictions. If false, every config\_setting is visible to every target. See https://github.com/bazelbuild/bazel/issues/12932. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options relating to Bzlmod output and semantics: +`--repo=<a string>` multiple uses are accumulated + +Only vendors the specified repository, which can be either `@apparent_repo_name` or `@@canonical_repo_name`. This option can be set multiple times + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Miscellaneous options, not otherwise categorized.: +`--deleted_packages=<comma-separated list of package names>` multiple uses are accumulated + +A comma-separated list of names of packages which the build system will consider non-existent, even if they are visible somewhere on the package path. +Use this option when deleting a subpackage 'x/y' of an existing package 'x'. For example, after deleting x/y/BUILD in your client, the build system may complain if it encounters a label '//x:y/z' if that is still provided by another package\_path entry. Specifying --deleted\_packages x/y avoids this problem. + +`--[no]fetch` default: "true" + +Allows the command to fetch external dependencies. If set to false, the command will utilize any cached version of the dependency, and if none exists, the command will result in failure. + +`--package_path=<colon-separated list of options>` default: "%workspace%" + +A colon-separated list of where to look for packages. Elements beginning with '%workspace%' are relative to the enclosing workspace. If omitted or empty, the default is the output of 'bazel info default-package-path'. + +`--[no]show_loading_progress` default: "true" + +If enabled, causes Bazel to print "Loading package:" messages. + +Options that control build execution: +`--[no]experimental_persistent_aar_extractor` default: "false" + +Enable persistent aar extractor by using workers. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_remotable_source_manifests` default: "false" + +Whether to make source manifest actions remotable + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_split_coverage_postprocessing` default: "false" + +If true, then Bazel will run coverage postprocessing for test in a new spawn. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_strict_fileset_output` default: "false" + +If this option is enabled, filesets will treat all output artifacts as regular files. They will not traverse directories or be sensitive to symlinks. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]incompatible_modify_execution_info_additive` default: "true" + +When enabled, passing multiple --modify\_execution\_info flags is additive. When disabled, only the last flag is taken into account. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--modify_execution_info=<regex=[+-]key,regex=[+-]key,...>` multiple uses are accumulated + +Add or remove keys from an action's execution info based on action mnemonic. Applies only to actions which support execution info. Many common actions support execution info, e.g. Genrule, CppCompile, Javac, StarlarkAction, TestRunner. When specifying multiple values, order matters because many regexes may apply to the same mnemonic. + +Syntax: "regex=\[+-\]key,regex=\[+-\]key,...". + +Examples: +'. _=+x,._ =-y,. _=+z' adds 'x' and 'z' to, and removes 'y' from, the execution info for all actions._ +_'Genrule=+requires-x' adds 'requires-x' to the execution info for all Genrule actions._ +_'(?!Genrule)._ =-requires-x' removes 'requires-x' from the execution info for all non-Genrule actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--persistent_android_dex_desugar` + +Enable persistent Android dex and desugar actions by using workers. + +Expands to: + +`--internal_persistent_android_dex_desugar` + +`--strategy=Desugar=worker` + +`--strategy=DexBuilder=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_android_resource_processor` + +Enable persistent Android resource processor by using workers. + +Expands to: + +`--internal_persistent_busybox_tools` + +`--strategy=AaptPackage=worker` + +`--strategy=AndroidResourceParser=worker` + +`--strategy=AndroidResourceValidator=worker` + +`--strategy=AndroidResourceCompiler=worker` + +`--strategy=RClassGenerator=worker` + +`--strategy=AndroidResourceLink=worker` + +`--strategy=AndroidAapt2=worker` + +`--strategy=AndroidAssetMerger=worker` + +`--strategy=AndroidResourceMerger=worker` + +`--strategy=AndroidCompiledResourceMerger=worker` + +`--strategy=ManifestMerger=worker` + +`--strategy=AndroidManifestMerger=worker` + +`--strategy=Aapt2Optimize=worker` + +`--strategy=AARGenerator=worker` + +`--strategy=ProcessDatabinding=worker` + +`--strategy=GenerateDataBindingBaseClasses=worker` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_dex_desugar` + +Enable persistent multiplexed Android dex and desugar actions by using workers. + +Expands to: + +`--persistent_android_dex_desugar` + +`--internal_persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_resource_processor` + +Enable persistent multiplexed Android resource processor by using workers. + +Expands to: + +`--persistent_android_resource_processor` + +`--modify_execution_info=AaptPackage=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceParser=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceValidator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceCompiler=+supports-multiplex-workers` + +`--modify_execution_info=RClassGenerator=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceLink=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAapt2=+supports-multiplex-workers` + +`--modify_execution_info=AndroidAssetMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidCompiledResourceMerger=+supports-multiplex-workers` + +`--modify_execution_info=ManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=AndroidManifestMerger=+supports-multiplex-workers` + +`--modify_execution_info=Aapt2Optimize=+supports-multiplex-workers` + +`--modify_execution_info=AARGenerator=+supports-multiplex-workers` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--persistent_multiplex_android_tools` + +Enable persistent and multiplexed Android tools (dexing, desugaring, resource processing). + +Expands to: + +`--internal_persistent_multiplex_busybox_tools` + +`--persistent_multiplex_android_resource_processor` + +`--persistent_multiplex_android_dex_desugar` + +Tags: +[`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`execution`](#effect_tag_EXECUTION) + +`--[no]use_target_platform_for_tests` default: "false" + +If true, use the target platform for running tests rather than the test exec group. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +Options that configure the toolchain used for action execution: +`--android_compiler=<a string>` default: see description + +The Android target compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_manifest_merger=<legacy, android or force_android>` default: "android" + +Selects the manifest merger to use for android\_binary rules. Flag to help the transition to the Android manifest merger from the legacy merger. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--android_platforms=<a build target label>` default: "" + +Sets the platforms that android\_binary targets use. If multiple platforms are specified, then the binary is a fat APKs, which contains native binaries for each specified target platform. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--cc_output_directory_tag=<a string>` default: "" + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compiler=<a string>` default: see description + +The C++ compiler to use for compiling the target. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--coverage_output_generator=<a build target label>` default: "@bazel\_tools//tools/test:lcov\_merger" + +Location of the binary that is used to postprocess raw coverage reports. This must be a binary target. Defaults to '//tools/test:lcov\_merger'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_report_generator=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_report\_generator" + +Location of the binary that is used to generate coverage reports. This must be a binary target. Defaults to '//tools/test:coverage\_report\_generator'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--coverage_support=<a build target label>` default: "@bazel\_tools//tools/test:coverage\_support" + +Location of support files that are required on the inputs of every test action that collects code coverage. Defaults to '//tools/test:coverage\_support'. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--custom_malloc=<a build target label>` default: see description + +Specifies a custom malloc implementation. This setting overrides malloc attributes in build rules. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]experimental_include_xcode_execution_requirements` default: "false" + +If set, add a "requires-xcode:{version}" execution requirement to every Xcode action. If the Xcode version has a hyphenated label, also add a "requires-xcode-label:{version\_label}" execution requirement. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_prefer_mutual_xcode` default: "true" + +If true, use the most recent Xcode that is available both locally and remotely. If false, or if there are no mutual available versions, use the local Xcode version selected via xcode-select. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--extra_execution_platforms=<comma-separated list of options>` default: "" + +The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by register\_execution\_platforms(). This option may only be set once; later instances will override earlier flag settings. + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--extra_toolchains=<comma-separated list of options>` multiple uses are accumulated + +The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by register\_toolchains(). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--grte_top=<a label>` default: see description + +A label to a checked-in libc library. The default value is selected by the crosstool toolchain, and you almost never need to override it. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_compiler=<a string>` default: see description + +No-op flag. Will be removed in a future release. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION) + +`--host_grte_top=<a label>` default: see description + +If specified, this setting overrides the libc top-level directory (--grte\_top) for the exec configuration. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_platform=<a build target label>` default: "@bazel\_tools//tools:host\_platform" + +The label of a platform rule that describes the host system. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]incompatible_bazel_test_exec_run_under` default: "true" + +If enabled, "bazel test --run\_under=//:runner" builds "//:runner" in the exec configuration. If disabled, it builds "//:runner" in the target configuration. Bazel executes tests on exec machines, so the former is more correct. This doesn't affect "bazel run", which always builds "\`--run\_under=//foo" in the target configuration. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_builtin_objc_strip_action` default: "true" + +Whether to emit a strip action as part of objc linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_dont_enable_host_nonhost_crosstool_features` default: "true" + +If true, Bazel will not enable 'host' and 'nonhost' features in the c++ toolchain (see https://github.com/bazelbuild/bazel/issues/7407 for more information). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_enable_apple_toolchain_resolution` default: "false" + +Use toolchain resolution to select the Apple SDK for apple rules (Starlark and native) + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_remove_legacy_whole_archive` default: "true" + +If true, Bazel will not link library dependencies as whole archive by default (see https://github.com/bazelbuild/bazel/issues/7362 for migration instructions). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strip_executable_safely` default: "false" + +If true, strip action for executables will use flag -x, which does not break dynamic symbol resolution. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]interface_shared_objects` default: "true" + +Use interface shared objects if supported by the toolchain. All ELF toolchains currently support this setting. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--minimum_os_version=<a string>` default: see description + +The minimum OS version which your compilation targets. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_mappings=<a main workspace-relative path>` default: "" + +The location of a mapping file that describes which platform to use if none is set or which flags to set when a platform already exists. Must be relative to the main workspace root. Defaults to 'platform\_mappings' (a file directly under the workspace root). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--platforms=<a build target label>` default: "" + +The labels of the platform rules describing the target platforms for the current command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_path=<a string>` default: see description + +The absolute path of the Python interpreter invoked to run Python targets on the target platform. Deprecated; disabled by --incompatible\_use\_python\_toolchains. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" + +Makes apple\_crosstool\_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version=<a string>` default: see description + +If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xcode_version_config=<a build target label>` default: "@bazel\_tools//tools/cpp:host\_xcodes" + +The label of the xcode\_config rule to be used for selecting the Xcode version in the build configuration. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +Options that control the output of the command: +`--[no]apple_generate_dsym` default: "false" + +Whether to generate debug symbol(.dSYM) file(s). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]build_runfile_links` default: "true" + +If true, build runfiles symlink forests for all targets. If false, write them only when required by a local action, test or run command. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_runfile_manifests` default: "true" + +If true, write runfiles manifests for all targets. If false, omit them. Local tests will fail to run when false. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]build_test_dwp` default: "false" + +If enabled, when building C++ tests statically and with fission the .dwp file for the test binary will be automatically built as well. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cc_proto_library_header_suffixes=<comma-separated set of options>` default: ".pb.h" + +Sets the suffixes of header files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--cc_proto_library_source_suffixes=<comma-separated set of options>` default: ".pb.cc" + +Sets the suffixes of source files that a cc\_proto\_library creates. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]experimental_proto_descriptor_sets_include_source_info` default: "false" + +Run extra actions for alternative Java api versions in a proto\_library. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_save_feature_state` default: "false" + +Save the state of enabled and requested feautres as an output of compilation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fission=<a set of compilation modes>` default: "no" + +Specifies which compilation modes use fission for C++ compilations and links. May be any combination of {'fastbuild', 'dbg', 'opt'} or the special values 'yes' to enable all modes and 'no' to disable all modes. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_always_include_files_in_data` default: "true" + +If true, native rules add <code>DefaultInfo.files</code> of data dependencies to their runfiles, which matches the recommended behavior for Starlark rules (https://bazel.build/extending/rules#runfiles\_features\_to\_avoid). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_compact_repo_mapping_manifest` default: "false" + +If enabled, the <binary>.repo\_mapping file emits a module extension's repo mapping only once instead of once for each repo generated by the extension that contributes runfiles. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--incompatible_disable_select_on=<comma-separated set of options>` default: "" + +List of flags for which the use in select() is disabled. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_filegroup_runfiles_for_data` default: "true" + +If true, runfiles of targets listed in the srcs attribute are available to targets that consume the filegroup as a data dependency. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]objc_generate_linkmap` default: "false" + +Specifies whether to generate a linkmap file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]save_temps` default: "false" + +If set, temporary outputs from gcc will be saved. These include .s files (assembler code), .i files (preprocessed C) and .ii files (preprocessed C++). + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with target configuration. Variables can be either specified by <code>name</code>, in which case +the value will be taken from the invocation environment, by the <code>name=value</code> pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. +<br> +Note that unless <code>--incompatible\_repo\_env\_ignores\_action\_env</code> is true, all <code>name=value</code> pairs will be available to repository rules. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--allowed_cpu_values=<comma-separated set of options>` default: "" + +Allowed values for the --cpu flag. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]android_databinding_use_androidx` default: "true" + +Generate AndroidX-compatible data-binding files. This is only used with databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]android_databinding_use_v3_4_args` default: "true" + +Use android databinding v2 with 3.4.0 argument. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--android_dynamic_mode=<off, default or fully>` default: "off" + +Determines whether C++ deps of Android rules will be linked dynamically when a cc\_binary does not explicitly create a shared library. 'default' means bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--android_manifest_merger_order=<alphabetical, alphabetical_by_configuration or dependency>` default: "alphabetical" + +Sets the order of manifests passed to the manifest merger for Android binaries. ALPHABETICAL means manifests are sorted by path relative to the execroot. ALPHABETICAL\_BY\_CONFIGURATION means manifests are sorted by paths relative to the configuration directory within the output directory. DEPENDENCY means manifests are ordered with each library's manifest coming before the manifests of its dependencies. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`execution`](#effect_tag_EXECUTION) + +`--[no]android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]build_python_zip` default: "auto" + +Build python executable zip; on on Windows, off on other platforms + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--catalyst_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple Catalyst binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]collect_code_coverage` default: "false" + +If specified, Bazel will instrument code (using offline instrumentation where possible) and will collect coverage information during tests. Only targets that match --instrumentation\_filter will be affected. Usually this option should not be specified directly - 'bazel coverage' command should be used instead. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--compilation_mode=<fastbuild, dbg or opt>` \[ `-c`\] default: "fastbuild" + +Specify the mode the binary will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--copt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cpu=<a string>` default: "" + +Deprecated: this flag is not used internally by Blaze although there are legacy platform mappings to allow for backwards compatibility. Do not use this flag, instead use --platforms with an appropriate platform definition. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_absolute_path=<a string>` default: see description + +Use CSFDO profile information to optimize compilation. Specify the absolute path name of the zip file containing the profile file, a raw or an indexed LLVM profile file. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_instrument=<a string>` default: see description + +Generate binaries with context sensitive FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cs_fdo_profile=<a build target label>` default: see description + +The cs\_fdo\_profile representing the context sensitive profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--cxxopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when compiling C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--define=<a 'name=value' assignment>` multiple uses are accumulated + +Each --define option specifies an assignment for a build variable. In case of multiple values for a variable, the last one wins. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--dynamic_mode=<off, default or fully>` default: "default" + +Determines whether C++ binaries will be linked dynamically. 'default' means Bazel will choose whether to link dynamically. 'fully' means all libraries will be linked dynamically. 'off' means that all libraries will be linked in mostly static mode. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_propeller_optimize_absolute_paths` default: "true" + +If set, any use of absolute paths for propeller optimize will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_remaining_fdo_absolute_paths` default: "true" + +If set, any use of absolute paths for FDO will raise an error. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]enable_runfiles` default: "auto" + +Enable runfiles symlink tree; By default, it's off on Windows, on on other platforms. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--exec_aspects=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of aspects to be applied to exec-configured targets, regardless of whether or not they are top-level targets. This is an experimental feature and is subject to change. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_action_listener=<a build target label>` multiple uses are accumulated + +Deprecated in favor of aspects. Use action\_listener to attach an extra\_action to existing build actions. + +Tags: +[`execution`](#effect_tag_EXECUTION), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_compress_java_resources` default: "false" + +Compress Java resources in APKs + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_databinding_v2` default: "true" + +Use android databinding v2. This flag is a no-op. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_resource_shrinking` default: "false" + +Enables resource shrinking for android\_binary APKs that use ProGuard. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_android_rewrite_dexes_with_rex` default: "false" + +use rex tool to rewrite dex files + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_collect_code_coverage_for_generated_files` default: "false" + +If specified, Bazel will also generate collect coverage information for generated files. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_objc_fastbuild_options=<comma-separated list of options>` default: "-O0,-DDEBUG=1" + +Uses these strings as objc fastbuild compiler options. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]experimental_omitfp` default: "false" + +If true, use libunwind for stack unwinding, and compile with -fomit-frame-pointer and -fasynchronous-unwind-tables. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_output_paths=<off or strip>` default: "off" + +Which model to use for where in the output tree rules write their outputs, particularly for multi-platform / multi-configuration builds. This is highly experimental. See https://github.com/bazelbuild/bazel/issues/6526 for details. Starlark actions canopt into path mapping by adding the key 'supports-path-mapping' to the 'execution\_requirements' dict. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`bazel_internal_configuration`](#effect_tag_BAZEL_INTERNAL_CONFIGURATION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +`--experimental_override_platform_cpu_name=<a 'label=value' assignment>` multiple uses are accumulated + +Each entry should be of the form label=value where label refers to a platform and values is the desired shortname to override the platform's CPU name in $(TARGET\_CPU) make variable and output path. Only used when --experimental\_platform\_in\_output\_dir, --incompatible\_target\_cpu\_from\_platform or --incompatible\_bep\_cpu\_from\_platform is true. Has highest naming priority. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_platform_in_output_dir` default: "false" + +If true, a shortname for the target platform is used in the output directory name instead of the CPU. If auto, this is only applied for the exec configuration. The exact scheme is experimental and subject to change: First, in the rare case the --platforms option does not have exactly one value, a hash of the platforms option is used. Next, if any shortname for the current platform was registered by --experimental\_override\_name\_platform\_in\_output\_dir, then that shortname is used. Then, if --experimental\_use\_platforms\_in\_output\_dir\_legacy\_heuristic is set, use a shortname based off the current platform Label. Finally, a hash of the platform option is used as a last resort. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_py_binaries_include_label` default: "false" + +py\_binary targets include their label even when stamping is disabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_llvm_covmap` default: "false" + +If specified, Bazel will generate llvm-cov coverage map information rather than gcov when collect\_code\_coverage is enabled. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_use_platforms_in_output_dir_legacy_heuristic` default: "true" + +Please only use this flag as part of a suggested migration or testing strategy. Note that the heuristic has known deficiencies and it is suggested to migrate to relying on just --experimental\_override\_name\_platform\_in\_output\_dir. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--fdo_instrument=<a string>` default: see description + +Generate binaries with FDO instrumentation. With Clang/LLVM compiler, it also accepts the directory name under which the raw profile file(s) will be dumped at runtime. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_optimize=<a string>` default: see description + +Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree, an afdo file containing an auto profile, or an LLVM profile file. This flag also accepts files specified as labels (e.g. `//foo/bar:file.afdo` \- you may need to add an `exports_files` directive to the corresponding package) and labels pointing to `fdo_profile` targets. This flag will be superseded by the `fdo_profile` rule. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_prefetch_hints=<a build target label>` default: see description + +Use cache prefetch hints. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--fdo_profile=<a build target label>` default: see description + +The fdo\_profile representing the profile to be used for optimization. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the target configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. See also --host\_features + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]force_pic` default: "false" + +If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_action_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies the set of environment variables available to actions with execution configurations. Variables can be either specified by name, in which case the value will be taken from the invocation environment, by the name=value pair which sets the value independent of the invocation environment, or by <code>=name</code>, which unsets the variable of that name. This option can be used multiple times; for options given for the same variable, the latest wins, options for different variables accumulate. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_compilation_mode=<fastbuild, dbg or opt>` default: "opt" + +Specify the mode the tools used during the build will be built in. Values: 'fastbuild', 'dbg', 'opt'. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--host_conlyopt=<a string>` multiple uses are accumulated + +Additional option to pass to the C compiler when compiling C (but not C++) source files in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_copt=<a string>` multiple uses are accumulated + +Additional options to pass to the C compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cpu=<a string>` default: "" + +The host CPU. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_cxxopt=<a string>` multiple uses are accumulated + +Additional options to pass to C++ compiler for tools built in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_features=<a string>` multiple uses are accumulated + +The given features will be enabled or disabled by default for targets built in the exec configuration. Specifying -<feature> will disable the feature. Negative features always override positive ones. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to linker when linking tools in the exec configurations. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--host_macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for host targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--host_per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to the C/C++ compiler when compiling certain files in the exec configurations. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --host\_per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]incompatible_auto_exec_groups` default: "false" + +When enabled, an exec groups is automatically created for each toolchain used by a rule. For this to work rule needs to specify `toolchain` parameter on its actions. For more information, see https://github.com/bazelbuild/bazel/issues/17134. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_merge_genfiles_directory` default: "true" + +If true, the genfiles directory is folded into the bin directory. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_target_cpu_from_platform` default: "true" + +If specified, the value of the cpu constraint (@platforms//cpu:cpu) of the target platform is used to set the $(TARGET\_CPU) make variable. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]instrument_test_targets` default: "false" + +When coverage is enabled, specifies whether to consider instrumenting test rules. When set, test rules included by --instrumentation\_filter are instrumented. Otherwise, test rules are always excluded from coverage instrumentation. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--instrumentation_filter=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-/javatests\[/:\],-/test/java\[/:\]" + +When coverage is enabled, only rules with names included by the specified regex-based filter will be instrumented. Rules prefixed with '-' are excluded instead. Note that only non-test rules are instrumented unless --instrument\_test\_targets is enabled. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ios_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible iOS version for target simulators and devices. If unspecified, uses 'ios\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--ios_multi_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures to build an ios\_application with. The result is a universal binary containing all specified architectures. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]legacy_whole_archive` default: "true" + +Deprecated, superseded by --incompatible\_remove\_legacy\_whole\_archive (see https://github.com/bazelbuild/bazel/issues/7362 for details). When on, use --whole-archive for cc\_binary rules that have linkshared=True and either linkstatic=True or '-static' in linkopts. This is for backwards compatibility only. A better alternative is to use alwayslink=1 where required. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`deprecated`](#metadata_tag_DEPRECATED) + +`--linkopt=<a string>` multiple uses are accumulated + +Additional option to pass to gcc when linking. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltobackendopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO backend step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--ltoindexopt=<a string>` multiple uses are accumulated + +Additional option to pass to the LTO indexing step (under --features=thin\_lto). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--macos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple macOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--macos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible macOS version for targets. If unspecified, uses 'macos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--memprof_profile=<a build target label>` default: see description + +Use memprof profile. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]objc_debug_with_GLIBCXX` default: "false" + +If set, and compilation mode is set to 'dbg', define GLIBCXX\_DEBUG, GLIBCXX\_DEBUG\_PEDANTIC and GLIBCPP\_CONCEPT\_CHECKS. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]objc_enable_binary_stripping` default: "false" + +Whether to perform symbol and dead-code strippings on linked binaries. Binary strippings will be performed if both this flag and --compilation\_mode=opt are specified. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--objccopt=<a string>` multiple uses are accumulated + +Additional options to pass to gcc when compiling Objective-C/C++ source files. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--per_file_copt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to gcc when compiling certain files. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_copt=//foo/.\*.cc,-//foo/bar.cc@-O0 adds the -O0 command line option to the gcc command line of all cc files in //foo/ except bar.cc. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--per_file_ltobackendopt=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths followed by an @ and a comma separated list of options>` multiple uses are accumulated + +Additional options to selectively pass to LTO backend (under --features=thin\_lto) when compiling certain backend objects. This option can be passed multiple times. Syntax: regex\_filter@option\_1,option\_2,...,option\_n. Where regex\_filter stands for a list of include and exclude regular expression patterns. option\_1 to option\_n stand for arbitrary command line options. If an option contains a comma it has to be quoted with a backslash. Options can contain @. Only the first @ is used to split the string. Example: --per\_file\_ltobackendopt=//foo/.\*.o,-//foo/bar.o@-O0 adds the -O0 command line option to the LTO backend command line of all o files in //foo/ except bar.o. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--platform_suffix=<a string>` default: see description + +Specifies a suffix to be added to the configuration directory. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--propeller_optimize=<a build target label>` default: see description + +Use Propeller profile information to optimize the build target.A propeller profile must consist of at least one of two files, a cc profile and a ld profile. This flag accepts a build label which must refer to the propeller profile input files. For example, the BUILD file that defines the label, in a/b/BUILD:propeller\_optimize( name = "propeller\_profile", cc\_profile = "propeller\_cc\_profile.txt", ld\_profile = "propeller\_ld\_profile.txt",)An exports\_files directive may have to be added to the corresponding package to make these files visible to Bazel. The option must be used as: --propeller\_optimize=//a/b:propeller\_profile + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_cc_profile=<a string>` default: see description + +Absolute path name of cc\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--propeller_optimize_absolute_ld_profile=<a string>` default: see description + +Absolute path name of ld\_profile file for Propeller Optimized builds. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--run_under=<a prefix in front of command>` default: see description + +Prefix to insert before the executables for the 'test' and 'run' commands. If the value is 'foo -bar', and the execution command line is 'test\_binary -baz', then the final command line is 'foo -bar test\_binary -baz'.This can also be a label to an executable target. Some examples are: 'valgrind', 'strace', 'strace -c', 'valgrind --quiet --num-callers=20', '//package:target', '//package:target --options'. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--[no]share_native_deps` default: "true" + +If true, native libraries that contain identical functionality will be shared among different targets + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]stamp` default: "false" + +Stamp binaries with the date, username, hostname, workspace information, etc. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--strip=<always, sometimes or never>` default: "sometimes" + +Specifies whether to strip binaries and shared libraries (using "-Wl,--strip-debug"). The default value of 'sometimes' means strip iff --compilation\_mode=fastbuild. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--stripopt=<a string>` multiple uses are accumulated + +Additional options to pass to strip when generating a '<name>.stripped' binary. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--tvos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple tvOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--tvos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible tvOS version for target simulators and devices. If unspecified, uses 'tvos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--visionos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple visionOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_cpus=<comma-separated list of options>` multiple uses are accumulated + +Comma-separated list of architectures for which to build Apple watchOS binaries. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_minimum_os=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +Minimum compatible watchOS version for target simulators and devices. If unspecified, uses 'watchos\_sdk\_version'. + +Tags: +[`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--xbinary_fdo=<a build target label>` default: see description + +Use XbinaryFDO profile information to optimize compilation. Specify the name of default cross binary profile. When the option is used together with --fdo\_instrument/--fdo\_optimize/--fdo\_profile, those options will always prevail as if xbinary\_fdo is never specified. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +Options that affect how strictly Bazel enforces valid build inputs (rule definitions, flag combinations, etc.): +`--[no]check_visibility` default: "true" + +If disabled, visibility errors in target dependencies are demoted to warnings. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]desugar_for_android` default: "true" + +Whether to desugar Java 8 bytecode before dexing. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]desugar_java8_libs` default: "false" + +Whether to include supported Java 8 libraries in apps for legacy devices. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]enforce_constraints` default: "true" + +Checks the environments each target is compatible with and reports errors if any target has dependencies that don't support the same environments + +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. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_one_version_enforcement=<off, warning or error>` default: "OFF" + +When enabled, enforce that a java\_binary rule can't contain more than one version of the same class file on the classpath. This enforcement can break the build, or can just result in warnings. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--experimental_strict_java_deps=<off, warn, error, strict or default>` default: "default" + +If true, checks that a Java target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--[no]incompatible_check_testonly_for_output_files` default: "false" + +If enabled, check testonly for prerequisite targets that are output files by looking up the testonly of the generating rule. This matches visibility checking. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_android_rules` default: "false" + +If enabled, direct usage of the native Android rules is disabled. Please use the Starlark Android rules from https://github.com/bazelbuild/rules\_android + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_disable_native_apple_binary_rule` default: "false" + +No-op. Kept here for backwards compatibility. + +Tags: +[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]one_version_enforcement_on_java_tests` default: "true" + +When enabled, and with experimental\_one\_version\_enforcement set to a non-NONE value, enforce one version on java\_test targets. This flag can be disabled to improve incremental test performance at the expense of missing potential one version violations. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--python_native_rules_allowlist=<a build target label>` default: see description + +An allowlist (package\_group target) to use when enforcing --incompatible\_python\_disallow\_native\_rules. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]strict_filesets` default: "false" + +If this option is enabled, filesets crossing package boundaries are reported as errors. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--strict_proto_deps=<off, warn, error, strict or default>` default: "error" + +Unless OFF, checks that a proto\_library target explicitly declares all directly used targets as dependencies. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--strict_public_imports=<off, warn, error, strict or default>` default: "off" + +Unless OFF, checks that a proto\_library target explicitly declares all targets used in 'import public' as exported. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]strict_system_includes` default: "false" + +If true, headers found through system include paths (-isystem) are also required to be declared. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT) + +`--target_environment=<a build target label>` multiple uses are accumulated + +Declares this build's target environment. Must be a label reference to an "environment" rule. If specified, all top-level targets must be compatible with this environment. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +Options that affect the signing outputs of a build: +`--apk_signing_method=<v1, v2, v1_v2 or v4>` default: "v1\_v2" + +Implementation to use to sign APKs + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]device_debug_entitlements` default: "true" + +If set, and compilation mode is not 'opt', objc apps will include debug entitlements when signing. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS) + +`--ios_signing_cert_name=<a string>` default: see description + +Certificate name to use for iOS signing. If not set will fall back to provisioning profile. May be the certificate's keychain identity preference or (substring) of the certificate's common name, as per codesign's man page (SIGNING IDENTITIES). + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +This option affects semantics of the Starlark language or the build API accessible to BUILD files, .bzl files, or WORKSPACE files.: +`--[no]incompatible_disallow_sdk_frameworks_attributes` default: "false" + +If true, disallow sdk\_frameworks and weak\_sdk\_frameworks attributes in objc\_library andobjc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_objc_alwayslink_by_default` default: "false" + +If true, make the default value true for alwayslink attributes in objc\_library and objc\_import. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_python_disallow_native_rules` default: "false" + +When true, an error occurs when using the builtin py\_\* rules; instead the rule\_python rules should be used. See https://github.com/bazelbuild/bazel/issues/17773 for more information and migration instructions. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Options that govern the behavior of the test environment or test runner: +`--[no]allow_analysis_failures` default: "false" + +If true, an analysis failure of a rule target results in the target's propagation of an instance of AnalysisFailureInfo containing the error description, instead of resulting in a build failure. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--analysis_testing_deps_limit=<an integer>` default: "2000" + +Sets the maximum number of transitive dependencies through a rule attribute with a for\_analysis\_testing configuration transition. Exceeding this limit will result in a rule error. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]break_build_on_parallel_dex2oat_failure` default: "false" + +If true dex2oat action failures will cause the build to break instead of executing dex2oat during test runtime. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--default_test_resources=<a resource name followed by equal and 1 float or 4 float, e.g memory=10,30,60,100>` multiple uses are accumulated + +Override the default resources amount for tests. The expected format is <resource>=<value>. If a single positive number is specified as <value> it will override the default resources for all test sizes. If 4 comma-separated numbers are specified, they will override the resource amount for respectively the small, medium, large, enormous test sizes. Values can also be HOST\_RAM/HOST\_CPU, optionally followed by \[-\| _\]<float> (eg. memory=HOST\_RAM_.1,HOST\_RAM\*.2,HOST\_RAM\*.3,HOST\_RAM\*.4). The default test resources specified by this flag are overridden by explicit resources specified in tags. + +`--[no]experimental_android_use_parallel_dex2oat` default: "false" + +Use dex2oat in parallel to possibly speed up android\_test. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`host_machine_resource_optimizations`](#effect_tag_HOST_MACHINE_RESOURCE_OPTIMIZATIONS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]ios_memleaks` default: "false" + +Enable checking for memory leaks in ios\_test targets. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES) + +`--ios_simulator_device=<a string>` default: see description + +The device to simulate when running an iOS application in the simulator, e.g. 'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' on the machine the simulator will be run on. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--ios_simulator_version=<a dotted version (for example '2.3' or '3.3alpha2.4')>` default: see description + +The version of iOS to run on the simulator when running or testing. This is ignored for ios\_test rules if a target device is specified in the rule. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--runs_per_test=<a positive integer or test_regex@runs. This flag may be passed more than once>` multiple uses are accumulated + +Specifies number of times to run each test. If any of those attempts fail for any reason, the whole test is considered failed. Normally the value specified is just an integer. Example: --runs\_per\_test=3 will run all tests 3 times. Alternate syntax: regex\_filter@runs\_per\_test. Where runs\_per\_test stands for an integer value and regex\_filter stands for a list of include and exclude regular expression patterns (Also see --instrumentation\_filter). Example: --runs\_per\_test=//foo/. _,-//foo/bar/._@3 runs all tests in //foo/ except those under foo/bar three times. This option can be passed multiple times. The most recently passed argument that matches takes precedence. If nothing matches, the test is only run once. + +`--test_env=<a 'name[=value]' assignment with an optional value part or the special syntax '=name' to unset a variable>` multiple uses are accumulated + +Specifies additional environment variables to be injected into the test runner environment. Variables can be either specified by <code>name</code>, in which case its value will be read from the Bazel client environment, or by the <code>name=value</code> pair. Previously set variables can be unset via <code>=name</code>. This option can be used multiple times to specify several variables. Used only by the 'bazel test' command. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +`--test_timeout=<a single integer or comma-separated list of 4 integers>` default: "-1" + +Override the default test timeout values for test timeouts (in secs). If a single positive integer value is specified it will override all categories. If 4 comma-separated integers are specified, they will override the timeouts for short, moderate, long and eternal (in that order). In either form, a value of -1 tells blaze to use its default timeouts for that category. + +`--[no]zip_undeclared_test_outputs` default: "false" + +If true, undeclared test outputs will be archived in a zip file. + +Tags: +[`test_runner`](#effect_tag_TEST_RUNNER) + +Options that trigger optimizations of the build time: +`--[no]experimental_filter_library_jar_with_program_jar` default: "false" + +Filter the ProGuard ProgramJar to remove any classes also present in the LibraryJar. + +Tags: +[`action_command_lines`](#effect_tag_ACTION_COMMAND_LINES), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_dotd_files` default: "true" + +If enabled, C++ .d files will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_inmemory_jdeps_files` default: "true" + +If enabled, the dependency (.jdeps) files generated from Java compilations will be passed through in memory directly from the remote build nodes instead of being written to disk. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_retain_test_configuration_across_testonly` default: "false" + +When enabled, --trim\_test\_configuration will not trim the test configuration for rules marked testonly=1. This is meant to reduce action conflict issues when non-test rules depend on cc\_test rules. No effect if --trim\_test\_configuration is false. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_unsupported_and_brittle_include_scanning` default: "false" + +Whether to narrow inputs to C/C++ compilation by parsing #include lines from input files. This can improve performance and incrementality by decreasing the size of compilation input trees. However, it can also break builds because the include scanner does not fully implement C preprocessor semantics. In particular, it does not understand dynamic #include directives and ignores preprocessor conditional logic. Use at your own risk. Any issues relating to this flag that are filed will be closed. + +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. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]process_headers_in_dependencies` default: "false" + +When building a target //a:a, process headers in all targets that //a:a depends on (if header processing is enabled for the toolchain). + +Tags: +[`execution`](#effect_tag_EXECUTION) + +`--[no]trim_test_configuration` default: "true" + +When enabled, test-related options will be cleared below the top level of the build. When this flag is active, tests cannot be built as dependencies of non-test rules, but changes to test-related options will not cause non-test rules to be re-analyzed. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +Options that affect the verbosity, format or location of logging: +`--toolchain_resolution_debug=<a comma-separated list of regex expressions with prefix '-' specifying excluded paths>` default: "-.\*" + +Print debug information during toolchain resolution. The flag takes a regex, which is checked against toolchain types and specific targets to see which to debug. Multiple regexes may be separated by commas, and then each regex is checked separately. Note: The output of this flag is very complex and will likely only be useful to experts in toolchain resolution. + +Tags: +[`terminal_output`](#effect_tag_TERMINAL_OUTPUT) + +`--[no]verbose_visibility_errors` default: "false" + +If enabled, visibility errors include additional diagnostic information. + +Tags: +[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +Options specifying or altering a generic input to a Bazel command that does not fall into other categories.: +`--flag_alias=<a 'name=value' flag alias>` multiple uses are accumulated + +Sets a shorthand name for a Starlark flag. It takes a single key-value pair in the form "<key>=<value>" as an argument. + +Tags: +[`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`non_configurable`](#metadata_tag_NON_CONFIGURABLE) + +`--[no]incompatible_default_to_explicit_init_py` default: "false" + +This flag changes the default behavior so that **init**.py files are no longer automatically created in the runfiles of Python targets. Precisely, when a py\_binary or py\_test target has legacy\_create\_init set to "auto" (the default), it is treated as false if and only if this flag is set. See https://github.com/bazelbuild/bazel/issues/10076. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +Miscellaneous options, not otherwise categorized.: +`--[no]cache_test_results` \[ `-t`\] default: "auto" + +If set to 'auto', Bazel reruns a test if and only if: (1) Bazel detects changes in the test or its dependencies, (2) the test is marked as external, (3) multiple test runs were requested with --runs\_per\_test, or(4) the test previously failed. If set to 'yes', Bazel caches all test results except for tests marked as external. If set to 'no', Bazel does not cache any test results. + +`--[no]experimental_cancel_concurrent_tests` default: "never" + +If 'on\_failed' or 'on\_passed, then Blaze will cancel concurrently running tests on the first run with that result. This is only useful in combination with --runs\_per\_test\_detects\_flakes. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_fetch_all_coverage_outputs` default: "false" + +If true, then Bazel fetches the entire coverage data directory for each test during a coverage run. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[no]experimental_generate_llvm_lcov` default: "false" + +If true, coverage for clang will generate an LCOV report. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--experimental_java_classpath=<off, javabuilder, bazel or bazel_no_fallback>` default: "bazel" + +Enables reduced classpaths for Java compilations. + +`--[no]experimental_run_android_lint_on_java_rules` default: "false" + +Whether to validate java\_\* sources. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL) + +`--[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. + +`--host_java_launcher=<a build target label>` default: see description + +The Java launcher used by tools that are executed during a build. + +`--host_javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac when building tools that are executed during a build. + +`--host_jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM when building tools that are executed during the build. These options will get added to the VM startup options of each java\_binary target. + +`--[no]incompatible_check_sharding_support` default: "true" + +If true, Bazel will fail a sharded test if the test runner does not indicate that it supports sharding by touching the file at the path in TEST\_SHARD\_STATUS\_FILE. If false, a test runner that does not support sharding will lead to all tests running in each shard. + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_exclusive_test_sandboxed` default: "true" + +If true, exclusive tests will run with sandboxed strategy. Add 'local' tag to force an exclusive test run locally + +Tags: +[`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--[no]incompatible_strict_action_env` default: "false" + +If true, Bazel uses an environment with a static value for PATH and does not inherit LD\_LIBRARY\_PATH. Use --action\_env=ENV\_VARIABLE if you want to inherit specific environment variables from the client, but note that doing so can prevent cross-user caching if a shared cache is used. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) + +`--j2objc_translation_flags=<comma-separated list of options>` multiple uses are accumulated + +Additional options to pass to the J2ObjC tool. + +`--java_debug` + +Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test\_output=streamed. + +Expands to: + +`--test_arg=--wrapper_script_flag=--debug` + +`--test_output=streamed` + +`--test_strategy=exclusive` + +`--test_timeout=9999` + +`--nocache_test_results` + +`--[no]java_deps` default: "true" + +Generate dependency information (for now, compile-time classpath) per Java target. + +`--[no]java_header_compilation` default: "true" + +Compile ijars directly from source. + +`--java_language_version=<a string>` default: "" + +The Java language version + +`--java_launcher=<a build target label>` default: see description + +The Java launcher to use when building Java binaries. If this flag is set to the empty string, the JDK launcher is used. The "launcher" attribute overrides this flag. + +`--java_runtime_version=<a string>` default: "local\_jdk" + +The Java runtime version + +`--javacopt=<a string>` multiple uses are accumulated + +Additional options to pass to javac. + +`--jvmopt=<a string>` multiple uses are accumulated + +Additional options to pass to the Java VM. These options will get added to the VM startup options of each java\_binary target. + +`--legacy_main_dex_list_generator=<a build target label>` default: see description + +Specifies a binary to use to generate the list of classes that must be in the main dex when compiling legacy multidex. + +`--optimizing_dexer=<a build target label>` default: see description + +Specifies a binary to use to do dexing without sharding. + +`--plugin=<a build target label>` multiple uses are accumulated + +Plugins to use in the build. Currently works with java\_plugin. + +`--proguard_top=<a build target label>` default: see description + +Specifies which version of ProGuard to use for code removal when building a Java binary. + +`--proto_compiler=<a build target label>` default: "@bazel\_tools//tools/proto:protoc" + +The label of the proto-compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--[no]proto_profile` default: "true" + +Whether to pass profile\_path to the proto compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_profile_path=<a build target label>` default: see description + +The profile to pass to the proto compiler as profile\_path. If unset, but --proto\_profile is true (the default), infers the path from --fdo\_optimize. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_cc=<a build target label>` default: "@bazel\_tools//tools/proto:cc\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile C++ protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_j2objc=<a build target label>` default: "@bazel\_tools//tools/j2objc:j2objc\_proto\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile j2objc protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_java=<a build target label>` default: "@bazel\_tools//tools/proto:java\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile Java protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--proto_toolchain_for_javalite=<a build target label>` default: "@bazel\_tools//tools/proto:javalite\_toolchain" + +Label of proto\_lang\_toolchain() which describes how to compile JavaLite protos + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--protocopt=<a string>` multiple uses are accumulated + +Additional options to pass to the protobuf compiler. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) + +`--[no]runs_per_test_detects_flakes` default: "false" + +If true, any shard in which at least one run/attempt passes and at least one run/attempt fails gets a FLAKY status. + +`--shell_executable=<a path>` default: see description + +Absolute path to the shell executable for Bazel to use. If this is unset, but the BAZEL\_SH environment variable is set on the first Bazel invocation (that starts up a Bazel server), Bazel uses that. If neither is set, Bazel uses a hard-coded default path depending on the operating system it runs on (Windows: c:/msys64/usr/bin/bash.exe, FreeBSD: /usr/local/bin/bash, all others: /bin/bash). Note that using a shell that is not compatible with bash may lead to build failures or runtime failures of the generated binaries. + +Tags: +[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--test_arg=<a string>` multiple uses are accumulated + +Specifies additional options and arguments that should be passed to the test executable. Can be used multiple times to specify several arguments. If multiple tests are executed, each of them will receive identical arguments. Used only by the 'bazel test' command. + +`--test_filter=<a string>` default: see description + +Specifies a filter to forward to the test framework. Used to limit the tests run. Note that this does not affect which targets are built. + +`--test_result_expiration=<an integer>` default: "-1" + +This option is deprecated and has no effect. + +`--[no]test_runner_fail_fast` default: "false" + +Forwards fail fast option to the test runner. The test runner should stop execution upon first failure. + +`--test_sharding_strategy=<explicit, disabled or forced=k where k is the number of shards to enforce>` default: "explicit" + +Specify strategy for test sharding: 'explicit' to only use sharding if the 'shard\_count' BUILD attribute is present. 'disabled' to never use test sharding. 'forced=k' to enforce 'k' shards for testing regardless of the 'shard\_count' BUILD attribute. + +`--tool_java_language_version=<a string>` default: "" + +The Java language version used to execute the tools that are needed during a build + +`--tool_java_runtime_version=<a string>` default: "remotejdk\_11" + +The Java runtime version used to execute tools during the build + +`--[no]use_ijars` default: "true" + +If enabled, this option causes Java compilation to use interface jars. This will result in faster incremental compilation, but error messages can be different. + +## Version Options + +Options that let the user configure the intended output, affecting its value, as opposed to its existence: +`--[no]gnu_format` default: "false" + +If set, write the version to stdout using the conventions described in the GNU standards. + +Tags: +[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`execution`](#effect_tag_EXECUTION) + +### Option Effect Tags + +`unknown`This option has unknown, or undocumented, effect.`no_op`This option has literally no effect.`loses_incremental_state`Changing the value of this option can cause significant loss of incremental state, which slows builds. State could be lost due to a server restart or to invalidation of a large part of the dependency graph.`changes_inputs`This option actively changes the inputs that bazel considers for the build, such as filesystem restrictions, repository versions, or other options.`affects_outputs`This option affects bazel's outputs. This tag is intentionally broad, can include transitive affects, and does not specify the type of output it affects.`build_file_semantics`This option affects the semantics of BUILD or .bzl files.`bazel_internal_configuration`This option affects settings of bazel-internal machinery. This tag does not, on its own, mean that build artifacts are affected.`loading_and_analysis`This option affects the loading and analysis of dependencies, and the building of the dependency graph.`execution`This option affects the execution phase, such as sandboxing or remote execution related options.`host_machine_resource_optimizations`This option triggers an optimization that may be machine specific and is not guaranteed to work on all machines. The optimization could include a tradeoff with other aspects of performance, such as memory or cpu cost.`eagerness_to_exit`This option changes how eagerly bazel will exit from a failure, where a choice between continuing despite the failure and ending the invocation exists.`bazel_monitoring`This option is used to monitor bazel's behavior and performance.`terminal_output`This option affects bazel's terminal output.`action_command_lines`This option changes the command line arguments of one or more build actions.`test_runner`This option changes the testrunner environment of the build. + +### Option Metadata Tags + +`experimental`This option triggers an experimental feature with no guarantees of functionality.`incompatible_change`This option triggers a breaking change. Use this option to test your migration readiness or get early access to the new feature`deprecated`This option is deprecated. It might be that the feature it affects is deprecated, or that another method of supplying the information is preferred.`non_configurable`This option cannot be changed in a transition or be used in a select() statement. diff --git a/rules/bzl-style.mdx b/rules/bzl-style.mdx deleted file mode 100644 index 941028a..0000000 --- a/rules/bzl-style.mdx +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: '.bzl style guide' ---- - - - -This page covers basic style guidelines for Starlark and also includes -information on macros and rules. - -[Starlark](/rules/language) is a -language that defines how software is built, and as such it is both a -programming and a configuration language. - -You will use Starlark to write `BUILD` files, macros, and build rules. Macros and -rules are essentially meta-languages - they define how `BUILD` files are written. -`BUILD` files are intended to be simple and repetitive. - -All software is read more often than it is written. This is especially true for -Starlark, as engineers read `BUILD` files to understand dependencies of their -targets and details of their builds. This reading will often happen in passing, -in a hurry, or in parallel to accomplishing some other task. Consequently, -simplicity and readability are very important so that users can parse and -comprehend `BUILD` files quickly. - -When a user opens a `BUILD` file, they quickly want to know the list of targets in -the file; or review the list of sources of that C++ library; or remove a -dependency from that Java binary. Each time you add a layer of abstraction, you -make it harder for a user to do these tasks. - -`BUILD` files are also analyzed and updated by many different tools. Tools may not -be able to edit your `BUILD` file if it uses abstractions. Keeping your `BUILD` -files simple will allow you to get better tooling. As a code base grows, it -becomes more and more frequent to do changes across many `BUILD` files in order to -update a library or do a cleanup. - -Important: Do not create a variable or macro just to avoid some amount of -repetition in `BUILD` files. Your `BUILD` file should be easily readable both by -developers and tools. The -[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) principle doesn't -really apply here. - -## General advice - -* Use [Buildifier](https://github.com/bazelbuild/buildtools/tree/master/buildifier#linter) - as a formatter and linter. -* Follow [testing guidelines](/rules/testing). - -## Style - -### Python style - -When in doubt, follow the -[PEP 8 style guide](https://www.python.org/dev/peps/pep-0008/) where possible. -In particular, use four rather than two spaces for indentation to follow the -Python convention. - -Since -[Starlark is not Python](/rules/language#differences-with-python), -some aspects of Python style do not apply. For example, PEP 8 advises that -comparisons to singletons be done with `is`, which is not an operator in -Starlark. - - -### Docstring - -Document files and functions using [docstrings](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#function-docstring). -Use a docstring at the top of each `.bzl` file, and a docstring for each public -function. - -### Document rules and aspects - -Rules and aspects, along with their attributes, as well as providers and their -fields, should be documented using the `doc` argument. - -### Naming convention - -* Variables and function names use lowercase with words separated by - underscores (`[a-z][a-z0-9_]*`), such as `cc_library`. -* Top-level private values start with one underscore. Bazel enforces that - private values cannot be used from other files. Local variables should not - use the underscore prefix. - -### Line length - -As in `BUILD` files, there is no strict line length limit as labels can be long. -When possible, try to use at most 79 characters per line (following Python's -style guide, [PEP 8](https://www.python.org/dev/peps/pep-0008/)). This guideline -should not be enforced strictly: editors should display more than 80 columns, -automated changes will frequently introduce longer lines, and humans shouldn't -spend time splitting lines that are already readable. - -### Keyword arguments - -In keyword arguments, spaces around the equal sign are preferred: - -```python -def fct(name, srcs): - filtered_srcs = my_filter(source = srcs) - native.cc_library( - name = name, - srcs = filtered_srcs, - testonly = True, - ) -``` - -### Boolean values - -Prefer values `True` and `False` (rather than of `1` and `0`) for boolean values -(such as when using a boolean attribute in a rule). - -### Use print only for debugging - -Do not use the `print()` function in production code; it is only intended for -debugging, and will spam all direct and indirect users of your `.bzl` file. The -only exception is that you may submit code that uses `print()` if it is disabled -by default and can only be enabled by editing the source -- for example, if all -uses of `print()` are guarded by `if DEBUG:` where `DEBUG` is hardcoded to -`False`. Be mindful of whether these statements are useful enough to justify -their impact on readability. - -## Macros - -A macro is a function which instantiates one or more rules during the loading -phase. In general, use rules whenever possible instead of macros. The build -graph seen by the user is not the same as the one used by Bazel during the -build - macros are expanded *before Bazel does any build graph analysis.* - -Because of this, when something goes wrong, the user will need to understand -your macro's implementation to troubleshoot build problems. Additionally, `bazel -query` results can be hard to interpret because targets shown in the results -come from macro expansion. Finally, aspects are not aware of macros, so tooling -depending on aspects (IDEs and others) might fail. - -A safe use for macros is for defining additional targets intended to be -referenced directly at the Bazel CLI or in BUILD files: In that case, only the -*end users* of those targets need to know about them, and any build problems -introduced by macros are never far from their usage. - -For macros that define generated targets (implementation details of the macro -which are not supposed to be referred to at the CLI or depended on by targets -not instantiated by that macro), follow these best practices: - -* A macro should take a `name` argument and define a target with that name. - That target becomes that macro's *main target*. -* Generated targets, that is all other targets defined by a macro, should: - * Have their names prefixed by `<name>` or `_<name>`. For example, using - `name = '%s_bar' % (name)`. - * Have restricted visibility (`//visibility:private`), and - * Have a `manual` tag to avoid expansion in wildcard targets (`:all`, - `...`, `:*`, etc). -* The `name` should only be used to derive names of targets defined by the - macro, and not for anything else. For example, don't use the name to derive - a dependency or input file that is not generated by the macro itself. -* All the targets created in the macro should be coupled in some way to the - main target. -* Conventionally, `name` should be the first argument when defining a macro. -* Keep the parameter names in the macro consistent. If a parameter is passed - as an attribute value to the main target, keep its name the same. If a macro - parameter serves the same purpose as a common rule attribute, such as - `deps`, name as you would the attribute (see below). -* When calling a macro, use only keyword arguments. This is consistent with - rules, and greatly improves readability. - -Engineers often write macros when the Starlark API of relevant rules is -insufficient for their specific use case, regardless of whether the rule is -defined within Bazel in native code, or in Starlark. If you're facing this -problem, ask the rule author if they can extend the API to accomplish your -goals. - -As a rule of thumb, the more macros resemble the rules, the better. - -See also [macros](/extending/macros#conventions). - -## Rules - -* Rules, aspects, and their attributes should use lower_case names ("snake - case"). -* Rule names are nouns that describe the main kind of artifact produced by the - rule, from the point of view of its dependencies (or for leaf rules, the - user). This is not necessarily a file suffix. For instance, a rule that - produces C++ artifacts meant to be used as Python extensions might be called - `py_extension`. For most languages, typical rules include: - * `*_library` - a compilation unit or "module". - * `*_binary` - a target producing an executable or a deployment unit. - * `*_test` - a test target. This can include multiple tests. Expect all - tests in a `*_test` target to be variations on the same theme, for - example, testing a single library. - * `*_import`: a target encapsulating a pre-compiled artifact, such as a - `.jar`, or a `.dll` that is used during compilation. -* Use consistent names and types for attributes. Some generally applicable - attributes include: - * `srcs`: `label_list`, allowing files: source files, typically - human-authored. - * `deps`: `label_list`, typically *not* allowing files: compilation - dependencies. - * `data`: `label_list`, allowing files: data files, such as test data etc. - * `runtime_deps`: `label_list`: runtime dependencies that are not needed - for compilation. -* For any attributes with non-obvious behavior (for example, string templates - with special substitutions, or tools that are invoked with specific - requirements), provide documentation using the `doc` keyword argument to the - attribute's declaration (`attr.label_list()` or similar). -* Rule implementation functions should almost always be private functions - (named with a leading underscore). A common style is to give the - implementation function for `myrule` the name `_myrule_impl`. -* Pass information between your rules using a well-defined - [provider](/extending/rules#providers) interface. Declare and document provider - fields. -* Design your rule with extensibility in mind. Consider that other rules might - want to interact with your rule, access your providers, and reuse the - actions you create. -* Follow [performance guidelines](/rules/performance) in your rules. diff --git a/rules/challenges.mdx b/rules/challenges.mdx deleted file mode 100644 index 10ff737..0000000 --- a/rules/challenges.mdx +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: 'Challenges of Writing Rules' ---- - - - -This page gives a high-level overview of the specific issues and challenges -of writing efficient Bazel rules. - -## Summary Requirements - -* Assumption: Aim for Correctness, Throughput, Ease of Use & Latency -* Assumption: Large Scale Repositories -* Assumption: BUILD-like Description Language -* Historic: Hard Separation between Loading, Analysis, and Execution is - Outdated, but still affects the API -* Intrinsic: Remote Execution and Caching are Hard -* Intrinsic: Using Change Information for Correct and Fast Incremental Builds - requires Unusual Coding Patterns -* Intrinsic: Avoiding Quadratic Time and Memory Consumption is Hard - -## Assumptions - -Here are some assumptions made about the build system, such as need for -correctness, ease of use, throughput, and large scale repositories. The -following sections address these assumptions and offer guidelines to ensure -rules are written in an effective manner. - -### Aim for correctness, throughput, ease of use & latency - -We assume that the build system needs to be first and foremost correct with -respect to incremental builds. For a given source tree, the output of the -same build should always be the same, regardless of what the output tree looks -like. In the first approximation, this means Bazel needs to know every single -input that goes into a given build step, such that it can rerun that step if any -of the inputs change. There are limits to how correct Bazel can get, as it leaks -some information such as date / time of the build, and ignores certain types of -changes such as changes to file attributes. [Sandboxing](/docs/sandboxing) -helps ensure correctness by preventing reads to undeclared input files. Besides -the intrinsic limits of the system, there are a few known correctness issues, -most of which are related to Fileset or the C++ rules, which are both hard -problems. We have long-term efforts to fix these. - -The second goal of the build system is to have high throughput; we are -permanently pushing the boundaries of what can be done within the current -machine allocation for a remote execution service. If the remote execution -service gets overloaded, nobody can get work done. - -Ease of use comes next. Of multiple correct approaches with the same (or -similar) footprint of the remote execution service, we choose the one that is -easier to use. - -Latency denotes the time it takes from starting a build to getting the intended -result, whether that is a test log from a passing or failing test, or an error -message that a `BUILD` file has a typo. - -Note that these goals often overlap; latency is as much a function of throughput -of the remote execution service as is correctness relevant for ease of use. - -### Large scale repositories - -The build system needs to operate at the scale of large repositories where large -scale means that it does not fit on a single hard drive, so it is impossible to -do a full checkout on virtually all developer machines. A medium-sized build -will need to read and parse tens of thousands of `BUILD` files, and evaluate -hundreds of thousands of globs. While it is theoretically possible to read all -`BUILD` files on a single machine, we have not yet been able to do so within a -reasonable amount of time and memory. As such, it is critical that `BUILD` files -can be loaded and parsed independently. - -### BUILD-like description language - -In this context, we assume a configuration language that is -roughly similar to `BUILD` files in declaration of library and binary rules -and their interdependencies. `BUILD` files can be read and parsed independently, -and we avoid even looking at source files whenever we can (except for -existence). - -## Historic - -There are differences between Bazel versions that cause challenges and some -of these are outlined in the following sections. - -### Hard separation between loading, analysis, and execution is outdated but still affects the API - -Technically, it is sufficient for a rule to know the input and output files of -an action just before the action is sent to remote execution. However, the -original Bazel code base had a strict separation of loading packages, then -analyzing rules using a configuration (command-line flags, essentially), and -only then running any actions. This distinction is still part of the rules API -today, even though the core of Bazel no longer requires it (more details below). - -That means that the rules API requires a declarative description of the rule -interface (what attributes it has, types of attributes). There are some -exceptions where the API allows custom code to run during the loading phase to -compute implicit names of output files and implicit values of attributes. For -example, a java_library rule named 'foo' implicitly generates an output named -'libfoo.jar', which can be referenced from other rules in the build graph. - -Furthermore, the analysis of a rule cannot read any source files or inspect the -output of an action; instead, it needs to generate a partial directed bipartite -graph of build steps and output file names that is only determined from the rule -itself and its dependencies. - -## Intrinsic - -There are some intrinsic properties that make writing rules challenging and -some of the most common ones are described in the following sections. - -### Remote execution and caching are hard - -Remote execution and caching improve build times in large repositories by -roughly two orders of magnitude compared to running the build on a single -machine. However, the scale at which it needs to perform is staggering: Google's -remote execution service is designed to handle a huge number of requests per -second, and the protocol carefully avoids unnecessary roundtrips as well as -unnecessary work on the service side. - -At this time, the protocol requires that the build system knows all inputs to a -given action ahead of time; the build system then computes a unique action -fingerprint, and asks the scheduler for a cache hit. If a cache hit is found, -the scheduler replies with the digests of the output files; the files itself are -addressed by digest later on. However, this imposes restrictions on the Bazel -rules, which need to declare all input files ahead of time. - -### Using change information for correct and fast incremental builds requires unusual coding patterns - -Above, we argued that in order to be correct, Bazel needs to know all the input -files that go into a build step in order to detect whether that build step is -still up-to-date. The same is true for package loading and rule analysis, and we -have designed [Skyframe](/reference/skyframe) to handle this -in general. Skyframe is a graph library and evaluation framework that takes a -goal node (such as 'build //foo with these options'), and breaks it down into -its constituent parts, which are then evaluated and combined to yield this -result. As part of this process, Skyframe reads packages, analyzes rules, and -executes actions. - -At each node, Skyframe tracks exactly which nodes any given node used to compute -its own output, all the way from the goal node down to the input files (which -are also Skyframe nodes). Having this graph explicitly represented in memory -allows the build system to identify exactly which nodes are affected by a given -change to an input file (including creation or deletion of an input file), doing -the minimal amount of work to restore the output tree to its intended state. - -As part of this, each node performs a dependency discovery process. Each -node can declare dependencies, and then use the contents of those dependencies -to declare even further dependencies. In principle, this maps well to a -thread-per-node model. However, medium-sized builds contain hundreds of -thousands of Skyframe nodes, which isn't easily possible with current Java -technology (and for historical reasons, we're currently tied to using Java, so -no lightweight threads and no continuations). - -Instead, Bazel uses a fixed-size thread pool. However, that means that if a node -declares a dependency that isn't available yet, we may have to abort that -evaluation and restart it (possibly in another thread), when the dependency is -available. This, in turn, means that nodes should not do this excessively; a -node that declares N dependencies serially can potentially be restarted N times, -costing O(N^2) time. Instead, we aim for up-front bulk declaration of -dependencies, which sometimes requires reorganizing the code, or even splitting -a node into multiple nodes to limit the number of restarts. - -Note that this technology isn't currently available in the rules API; instead, -the rules API is still defined using the legacy concepts of loading, analysis, -and execution phases. However, a fundamental restriction is that all accesses to -other nodes have to go through the framework so that it can track the -corresponding dependencies. Regardless of the language in which the build system -is implemented or in which the rules are written (they don't have to be the -same), rule authors must not use standard libraries or patterns that bypass -Skyframe. For Java, that means avoiding java.io.File as well as any form of -reflection, and any library that does either. Libraries that support dependency -injection of these low-level interfaces still need to be setup correctly for -Skyframe. - -This strongly suggests to avoid exposing rule authors to a full language runtime -in the first place. The danger of accidental use of such APIs is just too big - -several Bazel bugs in the past were caused by rules using unsafe APIs, even -though the rules were written by the Bazel team or other domain experts. - -### Avoiding quadratic time and memory consumption is hard - -To make matters worse, apart from the requirements imposed by Skyframe, the -historical constraints of using Java, and the outdatedness of the rules API, -accidentally introducing quadratic time or memory consumption is a fundamental -problem in any build system based on library and binary rules. There are two -very common patterns that introduce quadratic memory consumption (and therefore -quadratic time consumption). - -1. Chains of Library Rules - -Consider the case of a chain of library rules A depends on B, depends on C, and -so on. Then, we want to compute some property over the transitive closure of -these rules, such as the Java runtime classpath, or the C++ linker command for -each library. Naively, we might take a standard list implementation; however, -this already introduces quadratic memory consumption: the first library -contains one entry on the classpath, the second two, the third three, and so -on, for a total of 1+2+3+...+N = O(N^2) entries. - -2. Binary Rules Depending on the Same Library Rules - -Consider the case where a set of binaries that depend on the same library -rules — such as if you have a number of test rules that test the same -library code. Let's say out of N rules, half the rules are binary rules, and -the other half library rules. Now consider that each binary makes a copy of -some property computed over the transitive closure of library rules, such as -the Java runtime classpath, or the C++ linker command line. For example, it -could expand the command line string representation of the C++ link action. N/2 -copies of N/2 elements is O(N^2) memory. - -#### Custom collections classes to avoid quadratic complexity - -Bazel is heavily affected by both of these scenarios, so we introduced a set of -custom collection classes that effectively compress the information in memory by -avoiding the copy at each step. Almost all of these data structures have set -semantics, so we called it -[depset](/rules/lib/depset) -(also known as `NestedSet` in the internal implementation). The majority of -changes to reduce Bazel's memory consumption over the past several years were -changes to use depsets instead of whatever was previously used. - -Unfortunately, usage of depsets does not automatically solve all the issues; -in particular, even just iterating over a depset in each rule re-introduces -quadratic time consumption. Internally, NestedSets also has some helper methods -to facilitate interoperability with normal collections classes; unfortunately, -accidentally passing a NestedSet to one of these methods leads to copying -behavior, and reintroduces quadratic memory consumption. diff --git a/rules/deploying.mdx b/rules/deploying.mdx deleted file mode 100644 index 3fe2c86..0000000 --- a/rules/deploying.mdx +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: 'Deploying Rules' ---- - - - -This page is for rule writers who are planning to make their rules available -to others. - -We recommend you start a new ruleset from the template repository: -https://github.com/bazel-contrib/rules-template -That template follows the recommendations below, and includes API documentation generation -and sets up a CI/CD pipeline to make it trivial to distribute your ruleset. - -## Hosting and naming rules - -New rules should go into their own GitHub repository under your organization. -Start a thread on [GitHub](https://github.com/bazelbuild/bazel/discussions) -if you feel like your rules belong in the [bazelbuild](https://github.com/bazelbuild) -organization. - -Repository names for Bazel rules are standardized on the following format: -`$ORGANIZATION/rules_$NAME`. -See [examples on GitHub](https://github.com/search?q=rules+bazel&type=Repositories). -For consistency, you should follow this same format when publishing your Bazel rules. - -Make sure to use a descriptive GitHub repository description and `README.md` -title, example: - -* Repository name: `bazelbuild/rules_go` -* Repository description: *Go rules for Bazel* -* Repository tags: `golang`, `bazel` -* `README.md` header: *Go rules for [Bazel](https://bazel.build)* -(note the link to https://bazel.build which will guide users who are unfamiliar -with Bazel to the right place) - -Rules can be grouped either by language (such as Scala), runtime platform -(such as Android), or framework (such as Spring). - -## Repository content - -Every rule repository should have a certain layout so that users can quickly -understand new rules. - -For example, when writing new rules for the (make-believe) -`mockascript` language, the rule repository would have the following structure: - -``` -/ - LICENSE - README - MODULE.bazel - mockascript/ - constraints/ - BUILD - runfiles/ - BUILD - runfiles.mocs - BUILD - defs.bzl - tests/ - BUILD - some_test.sh - another_test.py - examples/ - BUILD - bin.mocs - lib.mocs - test.mocs -``` - -### MODULE.bazel - -In the project's `MODULE.bazel`, you should define the name that users will use -to reference your rules. If your rules belong to the -[bazelbuild](https://github.com/bazelbuild) organization, you must use -`rules_<lang>` (such as `rules_mockascript`). Otherwise, you should name your -repository `<org>_rules_<lang>` (such as `build_stack_rules_proto`). Please -start a thread on [GitHub](https://github.com/bazelbuild/bazel/discussions) -if you feel like your rules should follow the convention for rules in the -[bazelbuild](https://github.com/bazelbuild) organization. - -In the following sections, assume the repository belongs to the -[bazelbuild](https://github.com/bazelbuild) organization. - -``` -module(name = "rules_mockascript") -``` - -### README - -At the top level, there should be a `README` that contains a brief description -of your ruleset, and the API users should expect. - -### Rules - -Often times there will be multiple rules provided by your repository. Create a -directory named by the language and provide an entry point - `defs.bzl` file -exporting all rules (also include a `BUILD` file so the directory is a package). -For `rules_mockascript` that means there will be a directory named -`mockascript`, and a `BUILD` file and a `defs.bzl` file inside: - -``` -/ - mockascript/ - BUILD - defs.bzl -``` - -### Constraints - -If your rule defines -[toolchain](/extending/toolchains) rules, -it's possible that you'll need to define custom `constraint_setting`s and/or -`constraint_value`s. Put these into a `//<LANG>/constraints` package. Your -directory structure will look like this: - -``` -/ - mockascript/ - constraints/ - BUILD - BUILD - defs.bzl -``` - -Please read -[github.com/bazelbuild/platforms](https://github.com/bazelbuild/platforms) -for best practices, and to see what constraints are already present, and -consider contributing your constraints there if they are language independent. -Be mindful of introducing custom constraints, all users of your rules will -use them to perform platform specific logic in their `BUILD` files (for example, -using [selects](/reference/be/functions#select)). -With custom constraints, you define a language that the whole Bazel ecosystem -will speak. - -### Runfiles library - -If your rule provides a standard library for accessing runfiles, it should be -in the form of a library target located at `//<LANG>/runfiles` (an abbreviation -of `//<LANG>/runfiles:runfiles`). User targets that need to access their data -dependencies will typically add this target to their `deps` attribute. - -### Repository rules - -#### Dependencies - -Your rules might have external dependencies, which you'll need to specify in -your MODULE.bazel file. - -#### Registering toolchains - -Your rules might also register toolchains, which you can also specify in the -MODULE.bazel file. - -Note that in order to resolve toolchains in the analysis phase Bazel needs to -analyze all `toolchain` targets that are registered. Bazel will not need to -analyze all targets referenced by `toolchain.toolchain` attribute. If in order -to register toolchains you need to perform complex computation in the -repository, consider splitting the repository with `toolchain` targets from the -repository with `<LANG>_toolchain` targets. Former will be always fetched, and -the latter will only be fetched when user actually needs to build `<LANG>` code. - - -#### Release snippet - -In your release announcement provide a snippet that your users can copy-paste -into their `MODULE.bazel` file. This snippet in general will look as follows: - -``` -bazel_dep(name = "rules_<LANG>", version = "<VERSION>") -``` - - -### Tests - -There should be tests that verify that the rules are working as expected. This -can either be in the standard location for the language the rules are for or a -`tests/` directory at the top level. - -### Examples (optional) - -It is useful to users to have an `examples/` directory that shows users a couple -of basic ways that the rules can be used. - -## CI/CD - -Many rulesets use GitHub Actions. See the configuration used in the [rules-template](https://github.com/bazel-contrib/rules-template/tree/main/.github/workflows) repo, which are simplified using a "reusable workflow" hosted in the bazel-contrib -org. `ci.yaml` runs tests on each PR and `main` comit, and `release.yaml` runs anytime you push a tag to the repository. -See comments in the rules-template repo for more information. - -If your repository is under the [bazelbuild organization](https://github.com/bazelbuild), -you can [ask to add](https://github.com/bazelbuild/continuous-integration/issues/new?template=adding-your-project-to-bazel-ci.md&title=Request+to+add+new+project+%5BPROJECT_NAME%5D&labels=new-project) -it to [ci.bazel.build](http://ci.bazel.build). - -## Documentation - -See the [Stardoc documentation](https://github.com/bazelbuild/stardoc) for -instructions on how to comment your rules so that documentation can be generated -automatically. - -The [rules-template docs/ folder](https://github.com/bazel-contrib/rules-template/tree/main/docs) -shows a simple way to ensure the Markdown content in the `docs/` folder is always up-to-date -as Starlark files are updated. - -## FAQs - -### Why can't we add our rule to the main Bazel GitHub repository? - -We want to decouple rules from Bazel releases as much as possible. It's clearer -who owns individual rules, reducing the load on Bazel developers. For our users, -decoupling makes it easier to modify, upgrade, downgrade, and replace rules. -Contributing to rules can be lighter weight than contributing to Bazel - -depending on the rules -, including full submit access to the corresponding -GitHub repository. Getting submit access to Bazel itself is a much more involved -process. - -The downside is a more complicated one-time installation process for our users: -they have to add a dependency on your ruleset in their `MODULE.bazel` file. - -We used to have all of the rules in the Bazel repository (under -`//tools/build_rules` or `//tools/build_defs`). We still have a couple rules -there, but we are working on moving the remaining rules out. diff --git a/rules/errors/read-only-variable.mdx b/rules/errors/read-only-variable.mdx deleted file mode 100644 index 2bfde65..0000000 --- a/rules/errors/read-only-variable.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Error: Variable x is read only' ---- - - - -A global variable cannot be reassigned. It will always point to the same object. -However, its content might change, if the value is mutable (for example, the -content of a list). Local variables don't have this restriction. - -```python -a = [1, 2] - -a[1] = 3 - -b = 3 - -b = 4 # forbidden -``` - -`ERROR: /path/ext.bzl:7:1: Variable b is read only` - -You will get a similar error if you try to redefine a function (function -overloading is not supported), for example: - -```python -def foo(x): return x + 1 - -def foo(x, y): return x + y # forbidden -``` diff --git a/rules/faq.mdx b/rules/faq.mdx deleted file mode 100644 index 5321f0b..0000000 --- a/rules/faq.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: 'Frequently Asked Questions' ---- - - - -These are some common issues and questions with writing extensions. - -## Why is my file not produced / my action never executed? - -Bazel only executes the actions needed to produce the *requested* output files. - -* If the file you want has a label, you can request it directly: - `bazel build //pkg:myfile.txt` - -* If the file is in an output group of the target, you may need to specify that - output group on the command line: - `bazel build //pkg:mytarget --output_groups=foo` - -* If you want the file to be built automatically whenever your target is - mentioned on the command line, add it to your rule's default outputs by - returning a [`DefaultInfo`](lib/globals#DefaultInfo) provider. - -See the [Rules page](/extending/rules#requesting-output-files) for more information. - -## Why is my implementation function not executed? - -Bazel analyzes only the targets that are requested for the build. You should -either name the target on the command line, or something that depends on the -target. - -## A file is missing when my action or binary is executed - -Make sure that 1) the file has been registered as an input to the action or -binary, and 2) the script or tool being executed is accessing the file using the -correct path. - -For actions, you declare inputs by passing them to the `ctx.actions.*` function -that creates the action. The proper path for the file can be obtained using -[`File.path`](lib/File#path). - -For binaries (the executable outputs run by a `bazel run` or `bazel test` -command), you declare inputs by including them in the -[runfiles](/extending/rules#runfiles). Instead of using the `path` field, use -[`File.short_path`](lib/File#short_path), which is file's path relative to -the runfiles directory in which the binary executes. - -## How can I control which files are built by `bazel build //pkg:mytarget`? - -Use the [`DefaultInfo`](lib/globals#DefaultInfo) provider to -[set the default outputs](/extending/rules#requesting-output-files). - -## How can I run a program or do file I/O as part of my build? - -A tool can be declared as a target, just like any other part of your build, and -run during the execution phase to help build other targets. To create an action -that runs a tool, use [`ctx.actions.run`](lib/actions#run) and pass in the -tool as the `executable` parameter. - -During the loading and analysis phases, a tool *cannot* run, nor can you perform -file I/O. This means that tools and file contents (except the contents of BUILD -and .bzl files) cannot affect how the target and action graphs get created. - -## What if I need to access the same structured data both before and during the execution phase? - -You can format the structured data as a .bzl file. You can `load()` the file to -access it during the loading and analysis phases. You can pass it as an input or -runfile to actions and executables that need it during the execution phase. - -## How should I document Starlark code? - -For rules and rule attributes, you can pass a docstring literal (possibly -triple-quoted) to the `doc` parameter of `rule` or `attr.*()`. For helper -functions and macros, use a triple-quoted docstring literal following the format -given [here](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#function-docstring). -Rule implementation functions generally do not need their own docstring. - -Using string literals in the expected places makes it easier for automated -tooling to extract documentation. Feel free to use standard non-string comments -wherever it may help the reader of your code. diff --git a/rules/index.mdx b/rules/index.mdx deleted file mode 100644 index 2a6c3eb..0000000 --- a/rules/index.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: 'Rules' ---- - - - -The Bazel ecosystem has a growing and evolving set of rules to support popular -languages and packages. Much of Bazel's strength comes from the ability to -[define new rules](/extending/concepts) that can be used by others. - -This page describes the recommended, native, and non-native Bazel rules. - -## Recommended rules - -Here is a selection of recommended rules: - -* [Android](/docs/bazel-and-android) -* [C / C++](/docs/bazel-and-cpp) -* [Docker/OCI](https://github.com/bazel-contrib/rules_oci) -* [Go](https://github.com/bazelbuild/rules_go) -* [Haskell](https://github.com/tweag/rules_haskell) -* [Java](/docs/bazel-and-java) -* [JavaScript / NodeJS](https://github.com/bazelbuild/rules_nodejs) -* [Maven dependency management](https://github.com/bazelbuild/rules_jvm_external) -* [Objective-C](/docs/bazel-and-apple) -* [Package building](https://github.com/bazelbuild/rules_pkg) -* [Protocol Buffers](https://github.com/bazelbuild/rules_proto#protobuf-rules-for-bazel) -* [Python](https://github.com/bazelbuild/rules_python) -* [Rust](https://github.com/bazelbuild/rules_rust) -* [Scala](https://github.com/bazelbuild/rules_scala) -* [Shell](/reference/be/shell) -* [Webtesting](https://github.com/bazelbuild/rules_webtesting) (Webdriver) - -The repository [Skylib](https://github.com/bazelbuild/bazel-skylib) contains -additional functions that can be useful when writing new rules and new -macros. - -The rules above were reviewed and follow our -[requirements for recommended rules](/community/recommended-rules). -Contact the respective rule set's maintainers regarding issues and feature -requests. - -To find more Bazel rules, use a search engine, take a look on -[awesomebazel.com](https://awesomebazel.com/), or search on -[GitHub](https://github.com/search?o=desc&q=bazel+rules&s=stars&type=Repositories). - -## Native rules that do not apply to a specific programming language - -Native rules are shipped with the Bazel binary, they are always available in -BUILD files without a `load` statement. - -* Extra actions - - [`extra_action`](/reference/be/extra-actions#extra_action) - - [`action_listener`](/reference/be/extra-actions#action_listener) -* General - - [`filegroup`](/reference/be/general#filegroup) - - [`genquery`](/reference/be/general#genquery) - - [`test_suite`](/reference/be/general#test_suite) - - [`alias`](/reference/be/general#alias) - - [`config_setting`](/reference/be/general#config_setting) - - [`genrule`](/reference/be/general#genrule) -* Platform - - [`constraint_setting`](/reference/be/platforms-and-toolchains#constraint_setting) - - [`constraint_value`](/reference/be/platforms-and-toolchains#constraint_value) - - [`platform`](/reference/be/platforms-and-toolchains#platform) - - [`toolchain`](/reference/be/platforms-and-toolchains#toolchain) - - [`toolchain_type`](/reference/be/platforms-and-toolchains#toolchain_type) -* Workspace - - [`bind`](/reference/be/workspace#bind) - - [`local_repository`](/reference/be/workspace#local_repository) - - [`new_local_repository`](/reference/be/workspace#new_local_repository) - - [`xcode_config`](/reference/be/objective-c#xcode_config) - - [`xcode_version`](/reference/be/objective-c#xcode_version) - -## Embedded non-native rules - -Bazel also embeds additional rules written in [Starlark](/rules/language). Those can be loaded from -the `@bazel_tools` built-in external repository. - -* Repository rules - - [`git_repository`](/rules/lib/repo/git#git_repository) - - [`http_archive`](/rules/lib/repo/http#http_archive) - - [`http_file`](/rules/lib/repo/http#http_archive) - - [`http_jar`](/rules/lib/repo/http#http_jar) - - [Utility functions on patching](/rules/lib/repo/utils) diff --git a/rules/legacy-macro-tutorial.mdx b/rules/legacy-macro-tutorial.mdx deleted file mode 100644 index 28b0fca..0000000 --- a/rules/legacy-macro-tutorial.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: 'Creating a Legacy Macro' ---- - - - -IMPORTANT: This tutorial is for [*legacy macros*](/extending/legacy-macros). If -you only need to support Bazel 8 or newer, we recommend using [symbolic -macros](/extending/macros) instead; take a look at [Creating a Symbolic -Macro](macro-tutorial). - -Imagine that you need to run a tool as part of your build. For example, you -may want to generate or preprocess a source file, or compress a binary. In this -tutorial, you are going to create a legacy macro that resizes an image. - -Macros are suitable for simple tasks. If you want to do anything more -complicated, for example add support for a new programming language, consider -creating a [rule](/extending/rules). Rules give you more control and flexibility. - -The easiest way to create a macro that resizes an image is to use a `genrule`: - -```starlark -genrule( - name = "logo_miniature", - srcs = ["logo.png"], - outs = ["small_logo.png"], - cmd = "convert $< -resize 100x100 $@", -) - -cc_binary( - name = "my_app", - srcs = ["my_app.cc"], - data = [":logo_miniature"], -) -``` - -If you need to resize more images, you may want to reuse the code. To do that, -define a function in a separate `.bzl` file, and call the file `miniature.bzl`: - -```starlark -def miniature(name, src, size = "100x100", **kwargs): - """Create a miniature of the src image. - - The generated file is prefixed with 'small_'. - """ - native.genrule( - name = name, - srcs = [src], - # Note that the line below will fail if `src` is not a filename string - outs = ["small_" + src], - cmd = "convert $< -resize " + size + " $@", - **kwargs - ) -``` - -A few remarks: - - * By convention, legacy macros have a `name` argument, just like rules. - - * To document the behavior of a legacy macro, use - [docstring](https://www.python.org/dev/peps/pep-0257/) like in Python. - - * To call a `genrule`, or any other native rule, prefix with `native.`. - - * Use `**kwargs` to forward the extra arguments to the underlying `genrule` - (it works just like in - [Python](https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments)). - This is useful, so that a user can use standard attributes like - `visibility`, or `tags`. - -Now, use the macro from the `BUILD` file: - -```starlark -load("//path/to:miniature.bzl", "miniature") - -miniature( - name = "logo_miniature", - src = "image.png", -) - -cc_binary( - name = "my_app", - srcs = ["my_app.cc"], - data = [":logo_miniature"], -) -``` - -And finally, a **warning note**: the macro assumes that `src` is a filename -string (otherwise, `outs = ["small_" + src]` will fail). So `src = "image.png"` -works; but what happens if the `BUILD` file instead used `src = -"//other/package:image.png"`, or even `src = select(...)`? - -You should make sure to declare such assumptions in your macro's documentation. -Unfortunately, legacy macros, especially large ones, tend to be fragile because -it can be hard to notice and document all such assumptions in your code – and, -of course, some users of the macro won't read the documentation. We recommend, -if possible, instead using [symbolic macros](/extending/macros), which have -built\-in checks on attribute types. diff --git a/rules/lib/_toc.yaml b/rules/lib/_toc.yaml new file mode 100644 index 0000000..81f8c15 --- /dev/null +++ b/rules/lib/_toc.yaml @@ -0,0 +1,297 @@ +toc: +- title: Build API + section: + - title: Overview + path: /rules/lib/overview + - title: "Global functions" + section: + - title: Overview + path: /rules/lib/globals + - title: .bzl files + path: /rules/lib/globals/bzl + - title: All Bazel files + path: /rules/lib/globals/all + - title: BUILD files + path: /rules/lib/globals/build + - title: MODULE.bazel files + path: /rules/lib/globals/module + - title: REPO.bazel files + path: /rules/lib/globals/repo + - title: VENDOR.bazel files + path: /rules/lib/globals/vendor + - title: "Configuration Fragments" + section: + - title: Overview + path: /rules/lib/fragments + - title: apple + path: /rules/lib/fragments/apple + - title: bazel_android + path: /rules/lib/fragments/bazel_android + - title: bazel_py + path: /rules/lib/fragments/bazel_py + - title: coverage + path: /rules/lib/fragments/coverage + - title: cpp + path: /rules/lib/fragments/cpp + - title: j2objc + path: /rules/lib/fragments/j2objc + - title: java + path: /rules/lib/fragments/java + - title: objc + path: /rules/lib/fragments/objc + - title: platform + path: /rules/lib/fragments/platform + - title: proto + path: /rules/lib/fragments/proto + - title: py + path: /rules/lib/fragments/py + - title: "Providers" + section: + - title: Overview + path: /rules/lib/providers + - title: AnalysisTestResultInfo + path: /rules/lib/providers/AnalysisTestResultInfo + - title: CcInfo + path: /rules/lib/providers/CcInfo + - title: CcToolchainConfigInfo + path: /rules/lib/providers/CcToolchainConfigInfo + - title: CcToolchainInfo + path: /rules/lib/providers/CcToolchainInfo + - title: ConstraintCollection + path: /rules/lib/providers/ConstraintCollection + - title: ConstraintSettingInfo + path: /rules/lib/providers/ConstraintSettingInfo + - title: ConstraintValueInfo + path: /rules/lib/providers/ConstraintValueInfo + - title: DebugPackageInfo + path: /rules/lib/providers/DebugPackageInfo + - title: DefaultInfo + path: /rules/lib/providers/DefaultInfo + - title: ExecutionInfo + path: /rules/lib/providers/ExecutionInfo + - title: FeatureFlagInfo + path: /rules/lib/providers/FeatureFlagInfo + - title: file_provider + path: /rules/lib/providers/file_provider + - title: FilesToRunProvider + path: /rules/lib/providers/FilesToRunProvider + - title: IncompatiblePlatformProvider + path: /rules/lib/providers/IncompatiblePlatformProvider + - title: InstrumentedFilesInfo + path: /rules/lib/providers/InstrumentedFilesInfo + - title: java_compilation_info + path: /rules/lib/providers/java_compilation_info + - title: java_output_jars + path: /rules/lib/providers/java_output_jars + - title: JavaRuntimeInfo + path: /rules/lib/providers/JavaRuntimeInfo + - title: JavaToolchainInfo + path: /rules/lib/providers/JavaToolchainInfo + - title: MaterializedDepsInfo + path: /rules/lib/providers/MaterializedDepsInfo + - title: ObjcProvider + path: /rules/lib/providers/ObjcProvider + - title: OutputGroupInfo + path: /rules/lib/providers/OutputGroupInfo + - title: PackageSpecificationInfo + path: /rules/lib/providers/PackageSpecificationInfo + - title: PlatformInfo + path: /rules/lib/providers/PlatformInfo + - title: RunEnvironmentInfo + path: /rules/lib/providers/RunEnvironmentInfo + - title: TemplateVariableInfo + path: /rules/lib/providers/TemplateVariableInfo + - title: ToolchainInfo + path: /rules/lib/providers/ToolchainInfo + - title: ToolchainTypeInfo + path: /rules/lib/providers/ToolchainTypeInfo + - title: "Built-in Types" + section: + - title: Overview + path: /rules/lib/builtins + - title: Action + path: /rules/lib/builtins/Action + - title: actions + path: /rules/lib/builtins/actions + - title: apple_platform + path: /rules/lib/builtins/apple_platform + - title: Args + path: /rules/lib/builtins/Args + - title: Aspect + path: /rules/lib/builtins/Aspect + - title: Attribute + path: /rules/lib/builtins/Attribute + - title: bazel_module + path: /rules/lib/builtins/bazel_module + - title: bazel_module_tags + path: /rules/lib/builtins/bazel_module_tags + - title: BuildSetting + path: /rules/lib/builtins/BuildSetting + - title: CcCompilationOutputs + path: /rules/lib/builtins/CcCompilationOutputs + - title: CcLinkingOutputs + path: /rules/lib/builtins/CcLinkingOutputs + - title: CompilationContext + path: /rules/lib/builtins/CompilationContext + - title: configuration + path: /rules/lib/builtins/configuration + - title: ctx + path: /rules/lib/builtins/ctx + - title: depset + path: /rules/lib/builtins/depset + - title: DirectoryExpander + path: /rules/lib/builtins/DirectoryExpander + - title: DottedVersion + path: /rules/lib/builtins/DottedVersion + - title: exec_result + path: /rules/lib/builtins/exec_result + - title: ExecGroupCollection + path: /rules/lib/builtins/ExecGroupCollection + - title: ExecGroupContext + path: /rules/lib/builtins/ExecGroupContext + - title: ExecTransitionFactory + path: /rules/lib/builtins/ExecTransitionFactory + - title: ExpandedDirectory + path: /rules/lib/builtins/ExpandedDirectory + - title: extension_metadata + path: /rules/lib/builtins/extension_metadata + - title: FeatureConfiguration + path: /rules/lib/builtins/FeatureConfiguration + - title: File + path: /rules/lib/builtins/File + - title: fragments + path: /rules/lib/builtins/fragments + - title: java_annotation_processing + path: /rules/lib/builtins/java_annotation_processing + - title: Label + path: /rules/lib/builtins/Label + - title: LateBoundDefault + path: /rules/lib/builtins/LateBoundDefault + - title: LibraryToLink + path: /rules/lib/builtins/LibraryToLink + - title: License + path: /rules/lib/builtins/License + - title: LinkerInput + path: /rules/lib/builtins/LinkerInput + - title: LinkingContext + path: /rules/lib/builtins/LinkingContext + - title: macro + path: /rules/lib/builtins/macro + - title: mapped_root + path: /rules/lib/builtins/mapped_root + - title: module_ctx + path: /rules/lib/builtins/module_ctx + - title: path + path: /rules/lib/builtins/path + - title: propagation_ctx + path: /rules/lib/builtins/propagation_ctx + - title: Provider + path: /rules/lib/builtins/Provider + - title: repo_metadata + path: /rules/lib/builtins/repo_metadata + - title: repository_ctx + path: /rules/lib/builtins/repository_ctx + - title: repository_os + path: /rules/lib/builtins/repository_os + - title: repository_rule + path: /rules/lib/builtins/repository_rule + - title: root + path: /rules/lib/builtins/root + - title: rule + path: /rules/lib/builtins/rule + - title: rule_attributes + path: /rules/lib/builtins/rule_attributes + - title: runfiles + path: /rules/lib/builtins/runfiles + - title: struct + path: /rules/lib/builtins/struct + - title: Subrule + path: /rules/lib/builtins/Subrule + - title: subrule_ctx + path: /rules/lib/builtins/subrule_ctx + - title: SymlinkEntry + path: /rules/lib/builtins/SymlinkEntry + - title: tag_class + path: /rules/lib/builtins/tag_class + - title: Target + path: /rules/lib/builtins/Target + - title: template_ctx + path: /rules/lib/builtins/template_ctx + - title: TemplateDict + path: /rules/lib/builtins/TemplateDict + - title: toolchain_type + path: /rules/lib/builtins/toolchain_type + - title: ToolchainContext + path: /rules/lib/builtins/ToolchainContext + - title: transition + path: /rules/lib/builtins/transition + - title: wasm_exec_result + path: /rules/lib/builtins/wasm_exec_result + - title: wasm_module + path: /rules/lib/builtins/wasm_module + - title: "Top-level Modules" + section: + - title: Overview + path: /rules/lib/toplevel + - title: apple_common + path: /rules/lib/toplevel/apple_common + - title: attr + path: /rules/lib/toplevel/attr + - title: cc_common + path: /rules/lib/toplevel/cc_common + - title: config + path: /rules/lib/toplevel/config + - title: config_common + path: /rules/lib/toplevel/config_common + - title: coverage_common + path: /rules/lib/toplevel/coverage_common + - title: java_common + path: /rules/lib/toplevel/java_common + - title: native + path: /rules/lib/toplevel/native + - title: platform_common + path: /rules/lib/toplevel/platform_common + - title: proto + path: /rules/lib/toplevel/proto + - title: testing + path: /rules/lib/toplevel/testing + - title: "Core Starlark data types" + section: + - title: Overview + path: /rules/lib/core + - title: bool + path: /rules/lib/core/bool + - title: builtin_function_or_method + path: /rules/lib/core/builtin_function_or_method + - title: dict + path: /rules/lib/core/dict + - title: float + path: /rules/lib/core/float + - title: function + path: /rules/lib/core/function + - title: int + path: /rules/lib/core/int + - title: json + path: /rules/lib/core/json + - title: list + path: /rules/lib/core/list + - title: range + path: /rules/lib/core/range + - title: set + path: /rules/lib/core/set + - title: string + path: /rules/lib/core/string + - title: tuple + path: /rules/lib/core/tuple + - title: "Repository rules" + section: + - title: Overview + path: /rules/lib/repo/index + - title: git + path: /rules/lib/repo/git + - title: http + path: /rules/lib/repo/http + - title: local + path: /rules/lib/repo/local + - title: utils + path: /rules/lib/repo/utils diff --git a/rules/lib/builtins.mdx b/rules/lib/builtins.mdx index 8fbd257..6b8fff9 100644 --- a/rules/lib/builtins.mdx +++ b/rules/lib/builtins.mdx @@ -1,67 +1,67 @@ --- -title: 'builtins' +title: 'Built-in Types' --- This section lists types of Starlark objects. With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. -* [Action](./rules/lib/builtins/Action) -* [actions](./rules/lib/builtins/actions) -* [apple\_platform](./rules/lib/builtins/apple_platform) -* [Args](./rules/lib/builtins/Args) -* [Aspect](./rules/lib/builtins/Aspect) -* [Attribute](./rules/lib/builtins/Attribute) -* [bazel\_module](./rules/lib/builtins/bazel_module) -* [bazel\_module\_tags](./rules/lib/builtins/bazel_module_tags) -* [BuildSetting](./rules/lib/builtins/BuildSetting) -* [CcCompilationOutputs](./rules/lib/builtins/CcCompilationOutputs) -* [CcLinkingOutputs](./rules/lib/builtins/CcLinkingOutputs) -* [CompilationContext](./rules/lib/builtins/CompilationContext) -* [configuration](./rules/lib/builtins/configuration) -* [ctx](./rules/lib/builtins/ctx) -* [depset](./rules/lib/builtins/depset) -* [DirectoryExpander](./rules/lib/builtins/DirectoryExpander) -* [DottedVersion](./rules/lib/builtins/DottedVersion) -* [exec\_result](./rules/lib/builtins/exec_result) -* [ExecGroupCollection](./rules/lib/builtins/ExecGroupCollection) -* [ExecGroupContext](./rules/lib/builtins/ExecGroupContext) -* [ExecTransitionFactory](./rules/lib/builtins/ExecTransitionFactory) -* [ExpandedDirectory](./rules/lib/builtins/ExpandedDirectory) -* [extension\_metadata](./rules/lib/builtins/extension_metadata) -* [FeatureConfiguration](./rules/lib/builtins/FeatureConfiguration) -* [File](./rules/lib/builtins/File) -* [fragments](./rules/lib/builtins/fragments) -* [java\_annotation\_processing](./rules/lib/builtins/java_annotation_processing) -* [Label](./rules/lib/builtins/Label) -* [LateBoundDefault](./rules/lib/builtins/LateBoundDefault) -* [LibraryToLink](./rules/lib/builtins/LibraryToLink) -* [License](./rules/lib/builtins/License) -* [LinkerInput](./rules/lib/builtins/LinkerInput) -* [LinkingContext](./rules/lib/builtins/LinkingContext) -* [macro](./rules/lib/builtins/macro) -* [mapped\_root](./rules/lib/builtins/mapped_root) -* [module\_ctx](./rules/lib/builtins/module_ctx) -* [path](./rules/lib/builtins/path) -* [propagation\_ctx](./rules/lib/builtins/propagation_ctx) -* [Provider](./rules/lib/builtins/Provider) -* [repo\_metadata](./rules/lib/builtins/repo_metadata) -* [repository\_ctx](./rules/lib/builtins/repository_ctx) -* [repository\_os](./rules/lib/builtins/repository_os) -* [repository\_rule](./rules/lib/builtins/repository_rule) -* [root](./rules/lib/builtins/root) -* [rule](./rules/lib/builtins/rule) -* [rule\_attributes](./rules/lib/builtins/rule_attributes) -* [runfiles](./rules/lib/builtins/runfiles) -* [struct](./rules/lib/builtins/struct) -* [Subrule](./rules/lib/builtins/Subrule) -* [subrule\_ctx](./rules/lib/builtins/subrule_ctx) -* [SymlinkEntry](./rules/lib/builtins/SymlinkEntry) -* [tag\_class](./rules/lib/builtins/tag_class) -* [Target](./rules/lib/builtins/Target) -* [template\_ctx](./rules/lib/builtins/template_ctx) -* [TemplateDict](./rules/lib/builtins/TemplateDict) -* [toolchain\_type](./rules/lib/builtins/toolchain_type) -* [ToolchainContext](./rules/lib/builtins/ToolchainContext) -* [transition](./rules/lib/builtins/transition) -* [wasm\_exec\_result](./rules/lib/builtins/wasm_exec_result) -* [wasm\_module](./rules/lib/builtins/wasm_module) \ No newline at end of file +- [Action](/rules/lib/builtins/Action) +- [actions](/rules/lib/builtins/actions) +- [apple\_platform](/rules/lib/builtins/apple_platform) +- [Args](/rules/lib/builtins/Args) +- [Aspect](/rules/lib/builtins/Aspect) +- [Attribute](/rules/lib/builtins/Attribute) +- [bazel\_module](/rules/lib/builtins/bazel_module) +- [bazel\_module\_tags](/rules/lib/builtins/bazel_module_tags) +- [BuildSetting](/rules/lib/builtins/BuildSetting) +- [CcCompilationOutputs](/rules/lib/builtins/CcCompilationOutputs) +- [CcLinkingOutputs](/rules/lib/builtins/CcLinkingOutputs) +- [CompilationContext](/rules/lib/builtins/CompilationContext) +- [configuration](/rules/lib/builtins/configuration) +- [ctx](/rules/lib/builtins/ctx) +- [depset](/rules/lib/builtins/depset) +- [DirectoryExpander](/rules/lib/builtins/DirectoryExpander) +- [DottedVersion](/rules/lib/builtins/DottedVersion) +- [exec\_result](/rules/lib/builtins/exec_result) +- [ExecGroupCollection](/rules/lib/builtins/ExecGroupCollection) +- [ExecGroupContext](/rules/lib/builtins/ExecGroupContext) +- [ExecTransitionFactory](/rules/lib/builtins/ExecTransitionFactory) +- [ExpandedDirectory](/rules/lib/builtins/ExpandedDirectory) +- [extension\_metadata](/rules/lib/builtins/extension_metadata) +- [FeatureConfiguration](/rules/lib/builtins/FeatureConfiguration) +- [File](/rules/lib/builtins/File) +- [fragments](/rules/lib/builtins/fragments) +- [java\_annotation\_processing](/rules/lib/builtins/java_annotation_processing) +- [Label](/rules/lib/builtins/Label) +- [LateBoundDefault](/rules/lib/builtins/LateBoundDefault) +- [LibraryToLink](/rules/lib/builtins/LibraryToLink) +- [License](/rules/lib/builtins/License) +- [LinkerInput](/rules/lib/builtins/LinkerInput) +- [LinkingContext](/rules/lib/builtins/LinkingContext) +- [macro](/rules/lib/builtins/macro) +- [mapped\_root](/rules/lib/builtins/mapped_root) +- [module\_ctx](/rules/lib/builtins/module_ctx) +- [path](/rules/lib/builtins/path) +- [propagation\_ctx](/rules/lib/builtins/propagation_ctx) +- [Provider](/rules/lib/builtins/Provider) +- [repo\_metadata](/rules/lib/builtins/repo_metadata) +- [repository\_ctx](/rules/lib/builtins/repository_ctx) +- [repository\_os](/rules/lib/builtins/repository_os) +- [repository\_rule](/rules/lib/builtins/repository_rule) +- [root](/rules/lib/builtins/root) +- [rule](/rules/lib/builtins/rule) +- [rule\_attributes](/rules/lib/builtins/rule_attributes) +- [runfiles](/rules/lib/builtins/runfiles) +- [struct](/rules/lib/builtins/struct) +- [Subrule](/rules/lib/builtins/Subrule) +- [subrule\_ctx](/rules/lib/builtins/subrule_ctx) +- [SymlinkEntry](/rules/lib/builtins/SymlinkEntry) +- [tag\_class](/rules/lib/builtins/tag_class) +- [Target](/rules/lib/builtins/Target) +- [template\_ctx](/rules/lib/builtins/template_ctx) +- [TemplateDict](/rules/lib/builtins/TemplateDict) +- [toolchain\_type](/rules/lib/builtins/toolchain_type) +- [ToolchainContext](/rules/lib/builtins/ToolchainContext) +- [transition](/rules/lib/builtins/transition) +- [wasm\_exec\_result](/rules/lib/builtins/wasm_exec_result) +- [wasm\_module](/rules/lib/builtins/wasm_module) diff --git a/rules/lib/builtins/Action.mdx b/rules/lib/builtins/Action.mdx index e2d7de8..4236324 100644 --- a/rules/lib/builtins/Action.mdx +++ b/rules/lib/builtins/Action.mdx @@ -3,22 +3,23 @@ title: 'Action' --- + An action created during rule analysis. -This object is visible for the purpose of testing, and may be obtained from an `Actions` provider. It is normally not necessary to access `Action` objects or their fields within a rule's implementation function. You may instead want to see the [Rules page](https://bazel.build/extending/rules#actions) for a general discussion of how to use actions when defining custom rules, or the [API reference](../builtins/actions.mdx) for creating actions. +This object is visible for the purpose of testing, and may be obtained from an `Actions` provider. It is normally not necessary to access `Action` objects or their fields within a rule's implementation function. You may instead want to see the [Rules page](https://bazel.build/extending/rules#actions) for a general discussion of how to use actions when defining custom rules, or the [API reference](../builtins/actions.html) for creating actions. Some fields of this object are only applicable for certain kinds of actions. Fields that are inapplicable are set to `None`. ## Members -* [args](#args) -* [argv](#argv) -* [content](#content) -* [env](#env) -* [inputs](#inputs) -* [mnemonic](#mnemonic) -* [outputs](#outputs) -* [substitutions](#substitutions) +- [args](#args) +- [argv](#argv) +- [content](#content) +- [env](#env) +- [inputs](#inputs) +- [mnemonic](#mnemonic) +- [outputs](#outputs) +- [substitutions](#substitutions) ## args @@ -26,19 +27,23 @@ Some fields of this object are only applicable for certain kinds of actions. Fie sequence Action.args ``` -A list of frozen [Args](../builtins/Args.mdx) objects containing information about the action arguments. These objects contain accurate argument information, including arguments involving expanded action output directories. However, [Args](../builtins/Args.mdx) objects are not readable in the analysis phase. For a less accurate account of arguments which is available in the analysis phase, see [argv](#argv). + A list of frozen [Args](../builtins/Args.html) objects containing information about the action arguments. These objects contain accurate argument information, including arguments involving expanded action output directories. However, [Args](../builtins/Args.html) objects are not readable in the analysis phase. For a less accurate account of arguments which is available in the analysis phase, see [argv](#argv). Note that some types of actions do not yet support exposure of this field. For such action types, this is `None`. May return `None`. + + ## argv ``` sequence Action.argv ``` -For actions created by [ctx.actions.run()](../builtins/actions.html#run) or [ctx.actions.run\_shell()](../builtins/actions.html#run_shell) an immutable list of the arguments for the command line to be executed. Note that for shell actions the first two arguments will be the shell path and `"-c"`. -May return `None`. + For actions created by [ctx.actions.run()](../builtins/actions.html#run) or [ctx.actions.run\_shell()](../builtins/actions.html#run_shell) an immutable list of the arguments for the command line to be executed. Note that for shell actions the first two arguments will be the shell path and `"-c"`. + May return `None`. + + ## content @@ -46,8 +51,10 @@ May return `None`. string Action.content ``` -For actions created by [ctx.actions.write()](../builtins/actions.html#write) or [ctx.actions.expand\_template()](../builtins/actions.html#expand_template), the contents of the file to be written, if those contents can be computed during the analysis phase. The value is `None` if the contents cannot be determined until the execution phase, such as when a directory in an [Args](../builtins/Args.mdx) object needs to be expanded. -May return `None`. + For actions created by [ctx.actions.write()](../builtins/actions.html#write) or [ctx.actions.expand\_template()](../builtins/actions.html#expand_template), the contents of the file to be written, if those contents can be computed during the analysis phase. The value is `None` if the contents cannot be determined until the execution phase, such as when a directory in an [Args](../builtins/Args.html) object needs to be expanded. + May return `None`. + + ## env @@ -55,7 +62,9 @@ May return `None`. dict Action.env ``` -The 'fixed' environment variables for this action. This includes only environment settings which are explicitly set by the action definition, and thus omits settings which are only pre-set in the execution environment. + The 'fixed' environment variables for this action. This includes only environment settings which are explicitly set by the action definition, and thus omits settings which are only pre-set in the execution environment. + + ## inputs @@ -63,7 +72,9 @@ The 'fixed' environment variables for this action. This includes only environmen depset Action.inputs ``` -A set of the input files of this action. + A set of the input files of this action. + + ## mnemonic @@ -71,7 +82,9 @@ A set of the input files of this action. string Action.mnemonic ``` -The mnemonic for this action. + The mnemonic for this action. + + ## outputs @@ -79,7 +92,9 @@ The mnemonic for this action. depset Action.outputs ``` -A set of the output files of this action. + A set of the output files of this action. + + ## substitutions @@ -87,5 +102,5 @@ A set of the output files of this action. dict Action.substitutions ``` -For actions created by [ctx.actions.expand\_template()](../builtins/actions.html#expand_template), an immutable dict holding the substitution mapping. -May return `None`. \ No newline at end of file + For actions created by [ctx.actions.expand\_template()](../builtins/actions.html#expand_template), an immutable dict holding the substitution mapping. + May return `None`. diff --git a/rules/lib/builtins/Args.mdx b/rules/lib/builtins/Args.mdx index a1f8241..7710c4c 100644 --- a/rules/lib/builtins/Args.mdx +++ b/rules/lib/builtins/Args.mdx @@ -3,9 +3,10 @@ title: 'Args' --- + An object that encapsulates, in a memory-efficient way, the data needed to build part or all of a command line. -It often happens that an action requires a large command line containing values accumulated from transitive dependencies. For example, a linker command line might list every object file needed by all of the libraries being linked. It is best practice to store such transitive data in [`depset`](../builtins/depset.mdx)s, so that they can be shared by multiple targets. However, if the rule author had to convert these depsets into lists of strings in order to construct an action command line, it would defeat this memory-sharing optimization. +It often happens that an action requires a large command line containing values accumulated from transitive dependencies. For example, a linker command line might list every object file needed by all of the libraries being linked. It is best practice to store such transitive data in [`depset`](../builtins/depset.html) s, so that they can be shared by multiple targets. However, if the rule author had to convert these depsets into lists of strings in order to construct an action command line, it would defeat this memory-sharing optimization. For this reason, the action-constructing functions accept `Args` objects in addition to strings. Each `Args` object represents a concatenation of strings and depsets, with optional transformations for manipulating the data. `Args` objects do not process the depsets they encapsulate until the execution phase, when it comes time to calculate the command line. This helps defer any expensive copying until after the analysis phase is complete. See the [Optimizing Performance](https://bazel.build/rules/performance) page for more information. @@ -13,9 +14,12 @@ For this reason, the action-constructing functions accept `Args` objects in addi The `map_each` feature allows you to customize how items are transformed into strings. If you do not provide a `map_each` function, the standard conversion is as follows: -* Values that are already strings are left as-is.* [`File`](../builtins/File.mdx) objects are turned into their `File.path` values.* [`Label`](../builtins/Label.mdx) objects are turned into a string representation that resolves back to the same object when resolved in the context of the main repository. If possible, the string representation uses the apparent name of a repository in favor of the repository's canonical name, which makes this representation suited for use in BUILD files. While the exact form of the representation is not guaranteed, typical examples are `//foo:bar`, `@repo//foo:bar` and `@@canonical_name+//foo:bar.bzl`.* All other types are turned into strings in an *unspecified* manner. For this reason, you should avoid passing values that are not of string or `File` type to `add()`, and if you pass them to `add_all()` or `add_joined()` then you should provide a `map_each` function. +- Values that are already strings are left as-is. +- [`File`](../builtins/File.html) objects are turned into their `File.path` values. +- [`Label`](../builtins/Label.html) objects are turned into a string representation that resolves back to the same object when resolved in the context of the main repository. If possible, the string representation uses the apparent name of a repository in favor of the repository's canonical name, which makes this representation suited for use in BUILD files. While the exact form of the representation is not guaranteed, typical examples are `//foo:bar`, `@repo//foo:bar` and `@@canonical_name+//foo:bar.bzl`. +- All other types are turned into strings in an _unspecified_ manner. For this reason, you should avoid passing values that are not of string or `File` type to `add()`, and if you pass them to `add_all()` or `add_joined()` then you should provide a `map_each` function. -When using string formatting (`format`, `format_each`, and `format_joined` params of the `add*()` methods), the format template is interpreted in the same way as `%`-substitution on strings, except that the template must have exactly one substitution placeholder and it must be `%s`. Literal percents may be escaped as `%%`. Formatting is applied after the value is converted to a string as per the above. +When using string formatting ( `format`, `format_each`, and `format_joined` params of the `add*()` methods), the format template is interpreted in the same way as `%`-substitution on strings, except that the template must have exactly one substitution placeholder and it must be `%s`. Literal percents may be escaped as `%%`. Formatting is applied after the value is converted to a string as per the above. Each of the `add*()` methods have an alternate form that accepts an extra positional parameter, an "arg name" string to insert before the rest of the arguments. For `add_all` and `add_joined` the extra string will not be added if the sequence turns out to be empty. For instance, the same usage can add either `--foo val1 val2 val3 --bar` or just `--bar` to the command line, depending on whether the given sequence contains `val1..val3` or is empty. @@ -25,6 +29,7 @@ Example: Suppose we wanted to generate the command line: ``` --foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz + ``` We could use the following `Args` object: @@ -41,15 +46,16 @@ ctx.actions.run( arguments = [args], ... ) + ``` ## Members -* [add](#add) -* [add\_all](#add_all) -* [add\_joined](#add_joined) -* [set\_param\_file\_format](#set_param_file_format) -* [use\_param\_file](#use_param_file) +- [add](#add) +- [add\_all](#add_all) +- [add\_joined](#add_joined) +- [set\_param\_file\_format](#set_param_file_format) +- [use\_param\_file](#use_param_file) ## add @@ -57,15 +63,24 @@ ctx.actions.run( Args Args.add(arg_name_or_value, value=unbound, *, format=None) ``` -Appends an argument to this command line. + Appends an argument to this command line. + ### Parameters -| Parameter | Description | -| --- | --- | -| `arg_name_or_value` | required If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the value without any processing. If only one positional parameter is passed, it is interpreted as `value` (see below). | -| `value` | default is `unbound` The object to append. It will be converted to a string using the standard conversion mentioned above. Since there is no `map_each` parameter for this function, `value` should be either a string or a `File`. A list, tuple, depset, or directory `File` must be passed to [`add_all()` or [`add_joined()`](#add_joined) instead of this method.](#add_all) | -| `format` | [string](../core/string.mdx); or `None`; default is `None` A format string pattern, to be applied to the stringified version of `value`. | +ParameterDescription`arg_name_or_value` + required + + If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the value without any processing. If only one positional parameter is passed, it is interpreted as `value` (see below). + `value` + default is `unbound` + + The object to append. It will be converted to a string using the standard conversion mentioned above. Since there is no `map_each` parameter for this function, `value` should be either a string or a `File`. A list, tuple, depset, or directory `File` must be passed to [`add_all()` or](#add_all) [`add_joined()`](#add_joined) instead of this method. + `format`[string](../core/string.html); or `None`; + default is `None` + + A format string pattern, to be applied to the stringified version of `value`. + ## add\_all @@ -73,29 +88,82 @@ Appends an argument to this command line. Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False) ``` -Appends multiple arguments to this command line. The items are processed lazily during the execution phase. + Appends multiple arguments to this command line. The items are processed lazily during the execution phase. Most of the processing occurs over a list of arguments to be appended, as per the following steps: -1. Each directory `File` item is replaced by all `File`s recursively contained in that directory. -2. If `map_each` is given, it is applied to each item, and the resulting lists of strings are concatenated to form the initial argument list. Otherwise, the initial argument list is the result of applying the standard conversion to each item.- Each argument in the list is formatted with `format_each`, if present.- If `uniquify` is true, duplicate arguments are removed. The first occurrence is the one that remains.- If a `before_each` string is given, it is inserted as a new argument before each existing argument in the list. This effectively doubles the number of arguments to be appended by this point.- Except in the case that the list is empty and `omit_if_empty` is true (the default), the arg name and `terminate_with` are inserted as the first and last arguments, respectively, if they are given. +1. Each directory `File` item is replaced by all `File` s recursively contained in that directory. +2. If `map_each` is given, it is applied to each item, and the resulting lists of strings are concatenated to form the initial argument list. Otherwise, the initial argument list is the result of applying the standard conversion to each item. +3. Each argument in the list is formatted with `format_each`, if present. +4. If `uniquify` is true, duplicate arguments are removed. The first occurrence is the one that remains. +5. If a `before_each` string is given, it is inserted as a new argument before each existing argument in the list. This effectively doubles the number of arguments to be appended by this point. +6. Except in the case that the list is empty and `omit_if_empty` is true (the default), the arg name and `terminate_with` are inserted as the first and last arguments, respectively, if they are given. Note that empty strings are valid arguments that are subject to all these processing steps. + ### Parameters -| Parameter | Description | -| --- | --- | -| `arg_name_or_values` | required If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the `values` as a separate argument without any processing. This arg name will not be added if `omit_if_empty` is true (the default) and no other items are appended (as happens if `values` is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as `values` (see below). | -| `values` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `unbound` The list, tuple, or depset whose items will be appended. | -| `map_each` | callable; or `None`; default is `None` A function that converts each item to zero or more strings, which may be further processed before appending. If this param is not provided, the standard conversion is used. The function is passed either one or two positional arguments: the item to convert, followed by an optional [`DirectoryExpander`](../builtins/DirectoryExpander.mdx). The second argument will be passed only if the supplied function is user-defined (not built-in) and declares more than one parameter. The return value's type depends on how many arguments are to be produced for the item: * In the common case when each item turns into one string, the function should return that string.* If the item is to be filtered out entirely, the function should return `None`.* If the item turns into multiple strings, the function returns a list of those strings. Returning a single string or `None` has the same effect as returning a list of length 1 or length 0 respectively. However, it is more efficient and readable to avoid creating a list where it is not needed. Ordinarily, items that are directories are automatically expanded to their contents when `expand_directories=True` is set. However, this will not expand directories contained inside other values -- for instance, when the items are structs that have directories as fields. In this situation, the `DirectoryExpander` argument can be applied to manually obtain the files of a given directory. To avoid unintended retention of large analysis-phase data structures into the execution phase, the `map_each` function must be declared by a top-level `def` statement; it may not be a nested function closure by default. *Warning:* [`print()`](../globals/all.html#print) statements that are executed during the call to `map_each` will not produce any visible output. | -| `format_each` | [string](../core/string.mdx); or `None`; default is `None` An optional format string pattern, applied to each string returned by the `map_each` function. The format string must have exactly one '%s' placeholder. | -| `before_each` | [string](../core/string.mdx); or `None`; default is `None` An optional argument to append before each argument derived from `values` is appended. | -| `omit_if_empty` | [bool](../core/bool.mdx); default is `True` If true, if there are no arguments derived from `values` to be appended, then all further processing is suppressed and the command line will be unchanged. If false, the arg name and `terminate_with`, if provided, will still be appended regardless of whether or not there are other arguments. | -| `uniquify` | [bool](../core/bool.mdx); default is `False` If true, duplicate arguments that are derived from `values` will be omitted. Only the first occurrence of each argument will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if `map_each` emits the same string for multiple items. | -| `expand_directories` | [bool](../core/bool.mdx); default is `True` If true, any directories in `values` will be expanded to a flat list of files. This happens before `map_each` is applied. | -| `terminate_with` | [string](../core/string.mdx); or `None`; default is `None` An optional argument to append after all other arguments. This argument will not be added if `omit_if_empty` is true (the default) and no other items are appended (as happens if `values` is empty or all of its items are filtered). | -| `allow_closure` | [bool](../core/bool.mdx); default is `False` If true, allows the use of closures in function parameters like `map_each`. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. | +ParameterDescription`arg_name_or_values` + required + + If two positional parameters are passed this is interpreted as the arg name. The arg name is added before the `values` as a separate argument without any processing. This arg name will not be added if `omit_if_empty` is true (the default) and no other items are appended (as happens if `values` is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as `values` (see below). + `values`[sequence](../core/list.html); or [depset](../builtins/depset.html); + default is `unbound` + + The list, tuple, or depset whose items will be appended. + `map_each` + callable; or `None`; + default is `None` + + A function that converts each item to zero or more strings, which may be further processed before appending. If this param is not provided, the standard conversion is used. + +The function is passed either one or two positional arguments: the item to convert, followed by an optional [`DirectoryExpander`](../builtins/DirectoryExpander.html). The second argument will be passed only if the supplied function is user-defined (not built-in) and declares more than one parameter. + +The return value's type depends on how many arguments are to be produced for the item: + +- In the common case when each item turns into one string, the function should return that string. +- If the item is to be filtered out entirely, the function should return `None`. +- If the item turns into multiple strings, the function returns a list of those strings. + +Returning a single string or `None` has the same effect as returning a list of length 1 or length 0 respectively. However, it is more efficient and readable to avoid creating a list where it is not needed. + +Ordinarily, items that are directories are automatically expanded to their contents when `expand_directories=True` is set. However, this will not expand directories contained inside other values -- for instance, when the items are structs that have directories as fields. In this situation, the `DirectoryExpander` argument can be applied to manually obtain the files of a given directory. + +To avoid unintended retention of large analysis-phase data structures into the execution phase, the `map_each` function must be declared by a top-level `def` statement; it may not be a nested function closure by default. + +_Warning:_ [`print()`](../globals/all.html#print) statements that are executed during the call to `map_each` will not produce any visible output. + + +`format_each`[string](../core/string.html); or `None`; + default is `None` + + An optional format string pattern, applied to each string returned by the `map_each` function. The format string must have exactly one '%s' placeholder. + `before_each`[string](../core/string.html); or `None`; + default is `None` + + An optional argument to append before each argument derived from `values` is appended. + `omit_if_empty`[bool](../core/bool.html); + default is `True` + + If true, if there are no arguments derived from `values` to be appended, then all further processing is suppressed and the command line will be unchanged. If false, the arg name and `terminate_with`, if provided, will still be appended regardless of whether or not there are other arguments. + `uniquify`[bool](../core/bool.html); + default is `False` + + If true, duplicate arguments that are derived from `values` will be omitted. Only the first occurrence of each argument will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if `map_each` emits the same string for multiple items. + `expand_directories`[bool](../core/bool.html); + default is `True` + + If true, any directories in `values` will be expanded to a flat list of files. This happens before `map_each` is applied. + `terminate_with`[string](../core/string.html); or `None`; + default is `None` + + An optional argument to append after all other arguments. This argument will not be added if `omit_if_empty` is true (the default) and no other items are appended (as happens if `values` is empty or all of its items are filtered). + `allow_closure`[bool](../core/bool.html); + default is `False` + + If true, allows the use of closures in function parameters like `map_each`. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. + ## add\_joined @@ -103,26 +171,57 @@ Note that empty strings are valid arguments that are subject to all these proces Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False) ``` -Appends an argument to this command line by concatenating together multiple values using a separator. The items are processed lazily during the execution phase. + Appends an argument to this command line by concatenating together multiple values using a separator. The items are processed lazily during the execution phase. Processing is similar to [`add_all()`](#add_all), but the list of arguments derived from `values` is combined into a single argument as if by `join_with.join(...)`, and then formatted using the given `format_joined` string template. Unlike `add_all()`, there is no `before_each` or `terminate_with` parameter since these are not generally useful when the items are combined into a single argument. If after filtering there are no strings to join into an argument, and if `omit_if_empty` is true (the default), no processing is done. Otherwise if there are no strings to join but `omit_if_empty` is false, the joined string will be an empty string. + ### Parameters -| Parameter | Description | -| --- | --- | -| `arg_name_or_values` | required If two positional parameters are passed this is interpreted as the arg name. The arg name is added before `values` without any processing. This arg will not be added if `omit_if_empty` is true (the default) and there are no strings derived from `values` to join together (which can happen if `values` is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as `values` (see below). | -| `values` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `unbound` The list, tuple, or depset whose items will be joined. | -| `join_with` | [string](../core/string.mdx); required A delimiter string used to join together the strings obtained from applying `map_each` and `format_each`, in the same manner as [`string.join()`](../core/string.html#join). | -| `map_each` | callable; or `None`; default is `None` Same as for [`add_all`](#add_all.map_each). | -| `format_each` | [string](../core/string.mdx); or `None`; default is `None` Same as for [`add_all`](#add_all.format_each). | -| `format_joined` | [string](../core/string.mdx); or `None`; default is `None` An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. | -| `omit_if_empty` | [bool](../core/bool.mdx); default is `True` If true, if there are no strings to join together (either because `values` is empty or all its items are filtered), then all further processing is suppressed and the command line will be unchanged. If false, then even if there are no strings to join together, two arguments will be appended: the arg name followed by an empty string (which is the logical join of zero strings). | -| `uniquify` | [bool](../core/bool.mdx); default is `False` Same as for [`add_all`](#add_all.uniquify). | -| `expand_directories` | [bool](../core/bool.mdx); default is `True` Same as for [`add_all`](#add_all.expand_directories). | -| `allow_closure` | [bool](../core/bool.mdx); default is `False` Same as for [`add_all`](#add_all.allow_closure). | +ParameterDescription`arg_name_or_values` + required + + If two positional parameters are passed this is interpreted as the arg name. The arg name is added before `values` without any processing. This arg will not be added if `omit_if_empty` is true (the default) and there are no strings derived from `values` to join together (which can happen if `values` is empty or all of its items are filtered). If only one positional parameter is passed, it is interpreted as `values` (see below). + `values`[sequence](../core/list.html); or [depset](../builtins/depset.html); + default is `unbound` + + The list, tuple, or depset whose items will be joined. + `join_with`[string](../core/string.html); + required + + A delimiter string used to join together the strings obtained from applying `map_each` and `format_each`, in the same manner as [`string.join()`](../core/string.html#join). + `map_each` + callable; or `None`; + default is `None` + + Same as for [`add_all`](#add_all.map_each). + `format_each`[string](../core/string.html); or `None`; + default is `None` + + Same as for [`add_all`](#add_all.format_each). + `format_joined`[string](../core/string.html); or `None`; + default is `None` + + An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. + `omit_if_empty`[bool](../core/bool.html); + default is `True` + + If true, if there are no strings to join together (either because `values` is empty or all its items are filtered), then all further processing is suppressed and the command line will be unchanged. If false, then even if there are no strings to join together, two arguments will be appended: the arg name followed by an empty string (which is the logical join of zero strings). + `uniquify`[bool](../core/bool.html); + default is `False` + + Same as for [`add_all`](#add_all.uniquify). + `expand_directories`[bool](../core/bool.html); + default is `True` + + Same as for [`add_all`](#add_all.expand_directories). + `allow_closure`[bool](../core/bool.html); + default is `False` + + Same as for [`add_all`](#add_all.allow_closure). + ## set\_param\_file\_format @@ -130,13 +229,22 @@ If after filtering there are no strings to join into an argument, and if `omit_i Args Args.set_param_file_format(format) ``` -Sets the format of the param file, if one is used + Sets the format of the param file, if one is used + ### Parameters -| Parameter | Description | -| --- | --- | -| `format` | [string](../core/string.mdx); required Must be one of: * "multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it. * "shell": Same as "multiline", but the items are shell-quoted * "flag\_per\_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library. The format defaults to "shell" if not called. | +ParameterDescription`format`[string](../core/string.html); + required + + Must be one of: + +- "multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it. +- "shell": Same as "multiline", but the items are shell-quoted +- "flag\_per\_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library. + +The format defaults to "shell" if not called. + ## use\_param\_file @@ -144,13 +252,22 @@ Sets the format of the param file, if one is used Args Args.use_param_file(param_file_arg, *, use_always=False) ``` -Spills the args to a params file, replacing them with a pointer to the param file. Use when your args may be too large for the system's command length limits. + Spills the args to a params file, replacing them with a pointer to the param file. Use when your args may be too large for the system's command length limits. Bazel may choose to elide writing the params file to the output tree during execution for efficiency. If you are debugging actions and want to inspect the param file, pass `--materialize_param_files` to your build. + ### Parameters -| Parameter | Description | -| --- | --- | -| `param_file_arg` | [string](../core/string.mdx); required A format string with a single "%s". If the args are spilled to a params file then they are replaced with an argument consisting of this string formatted with the path of the params file. For example, if the args are spilled to a params file "params.txt", then specifying "--file=%s" would cause the action command line to contain "--file=params.txt". | -| `use_always` | [bool](../core/bool.mdx); default is `False` Whether to always spill the args to a params file. If false, bazel will decide whether the arguments need to be spilled based on your system and arg length. | \ No newline at end of file +ParameterDescription`param_file_arg`[string](../core/string.html); + required + + A format string with a single "%s". If the args are spilled to a params file then they are replaced with an argument consisting of this string formatted with the path of the params file. + +For example, if the args are spilled to a params file "params.txt", then specifying "--file=%s" would cause the action command line to contain "--file=params.txt". + + +`use_always`[bool](../core/bool.html); + default is `False` + + Whether to always spill the args to a params file. If false, bazel will decide whether the arguments need to be spilled based on your system and arg length. diff --git a/rules/lib/builtins/Aspect.mdx b/rules/lib/builtins/Aspect.mdx index b9383df..535d0c1 100644 --- a/rules/lib/builtins/Aspect.mdx +++ b/rules/lib/builtins/Aspect.mdx @@ -3,5 +3,6 @@ title: 'Aspect' --- + For more information about Aspects, please consult the -[documentation of the aspect function](../globals/bzl.html#aspect) or the [introduction to Aspects](https://bazel.build/extending/aspects). \ No newline at end of file +[documentation of the aspect function](../globals/bzl.html#aspect) or the [introduction to Aspects](https://bazel.build/extending/aspects). diff --git a/rules/lib/builtins/Attribute.mdx b/rules/lib/builtins/Attribute.mdx index 8dc8b2d..2d1bde7 100644 --- a/rules/lib/builtins/Attribute.mdx +++ b/rules/lib/builtins/Attribute.mdx @@ -3,4 +3,5 @@ title: 'Attribute' --- -Representation of a definition of an attribute. Use the [attr](../toplevel/attr.mdx) module to create an Attribute. They are only for use with a [rule](../globals/bzl.html#rule) or an [aspect](../globals/bzl.html#aspect). \ No newline at end of file + +Representation of a definition of an attribute. Use the [attr](../toplevel/attr.html) module to create an Attribute. They are only for use with a [rule](../globals/bzl.html#rule) or an [aspect](../globals/bzl.html#aspect). diff --git a/rules/lib/builtins/BuildSetting.mdx b/rules/lib/builtins/BuildSetting.mdx index 896632c..4c41ea6 100644 --- a/rules/lib/builtins/BuildSetting.mdx +++ b/rules/lib/builtins/BuildSetting.mdx @@ -3,4 +3,5 @@ title: 'BuildSetting' --- -The descriptor for a single piece of configuration information. If configuration is a key-value map of settings like \{'cpu': 'ppc', 'copt': '-DFoo'\}, this describes a single entry in that map. \ No newline at end of file + +The descriptor for a single piece of configuration information. If configuration is a key-value map of settings like {'cpu': 'ppc', 'copt': '-DFoo'}, this describes a single entry in that map. diff --git a/rules/lib/builtins/CcCompilationOutputs.mdx b/rules/lib/builtins/CcCompilationOutputs.mdx index ca1c2e4..00a9a0d 100644 --- a/rules/lib/builtins/CcCompilationOutputs.mdx +++ b/rules/lib/builtins/CcCompilationOutputs.mdx @@ -3,12 +3,13 @@ title: 'CcCompilationOutputs' --- + Helper class containing CC compilation outputs. ## Members -* [objects](#objects) -* [pic\_objects](#pic_objects) +- [objects](#objects) +- [pic\_objects](#pic_objects) ## objects @@ -16,7 +17,9 @@ Helper class containing CC compilation outputs. sequence CcCompilationOutputs.objects ``` -Non-PIC object files. + Non-PIC object files. + + ## pic\_objects @@ -24,4 +27,4 @@ Non-PIC object files. sequence CcCompilationOutputs.pic_objects ``` -PIC object files. \ No newline at end of file + PIC object files. diff --git a/rules/lib/builtins/CcLinkingOutputs.mdx b/rules/lib/builtins/CcLinkingOutputs.mdx index b8bb713..0013240 100644 --- a/rules/lib/builtins/CcLinkingOutputs.mdx +++ b/rules/lib/builtins/CcLinkingOutputs.mdx @@ -3,12 +3,13 @@ title: 'CcLinkingOutputs' --- + Helper class containing CC compilation outputs. ## Members -* [executable](#executable) -* [library\_to\_link](#library_to_link) +- [executable](#executable) +- [library\_to\_link](#library_to_link) ## executable @@ -16,8 +17,10 @@ Helper class containing CC compilation outputs. File CcLinkingOutputs.executable ``` -Represents the linked executable. -May return `None`. + Represents the linked executable. + May return `None`. + + ## library\_to\_link @@ -25,5 +28,5 @@ May return `None`. LibraryToLink CcLinkingOutputs.library_to_link ``` -`LibraryToLink` for including these outputs in further linking. -May return `None`. \ No newline at end of file + `LibraryToLink` for including these outputs in further linking. + May return `None`. diff --git a/rules/lib/builtins/CompilationContext.mdx b/rules/lib/builtins/CompilationContext.mdx index ea67aab..3c34a71 100644 --- a/rules/lib/builtins/CompilationContext.mdx +++ b/rules/lib/builtins/CompilationContext.mdx @@ -3,23 +3,24 @@ title: 'CompilationContext' --- + Immutable store of information needed for C++ compilation that is aggregated across dependencies. ## Members -* [defines](#defines) -* [direct\_headers](#direct_headers) -* [direct\_private\_headers](#direct_private_headers) -* [direct\_public\_headers](#direct_public_headers) -* [direct\_textual\_headers](#direct_textual_headers) -* [external\_includes](#external_includes) -* [framework\_includes](#framework_includes) -* [headers](#headers) -* [includes](#includes) -* [local\_defines](#local_defines) -* [quote\_includes](#quote_includes) -* [system\_includes](#system_includes) -* [validation\_artifacts](#validation_artifacts) +- [defines](#defines) +- [direct\_headers](#direct_headers) +- [direct\_private\_headers](#direct_private_headers) +- [direct\_public\_headers](#direct_public_headers) +- [direct\_textual\_headers](#direct_textual_headers) +- [external\_includes](#external_includes) +- [framework\_includes](#framework_includes) +- [headers](#headers) +- [includes](#includes) +- [local\_defines](#local_defines) +- [quote\_includes](#quote_includes) +- [system\_includes](#system_includes) +- [validation\_artifacts](#validation_artifacts) ## defines @@ -27,7 +28,9 @@ Immutable store of information needed for C++ compilation that is aggregated acr depset CompilationContext.defines ``` -Returns the set of defines needed to compile this target. Each define is a string. These values are propagated to the target's transitive dependents, that is, any rules that depend on this target. + Returns the set of defines needed to compile this target. Each define is a string. These values are propagated to the target's transitive dependents, that is, any rules that depend on this target. + + ## direct\_headers @@ -35,7 +38,9 @@ Returns the set of defines needed to compile this target. Each define is a strin list CompilationContext.direct_headers ``` -Returns the list of modular headers that are declared by this target. This includes both public headers (such as those listed in "hdrs") and private headers (such as those listed in "srcs"). + Returns the list of modular headers that are declared by this target. This includes both public headers (such as those listed in "hdrs") and private headers (such as those listed in "srcs"). + + ## direct\_private\_headers @@ -43,7 +48,9 @@ Returns the list of modular headers that are declared by this target. This inclu list CompilationContext.direct_private_headers ``` -Returns the list of modular private headers (those listed in "srcs") that are declared by this target. + Returns the list of modular private headers (those listed in "srcs") that are declared by this target. + + ## direct\_public\_headers @@ -51,7 +58,9 @@ Returns the list of modular private headers (those listed in "srcs") that are de list CompilationContext.direct_public_headers ``` -Returns the list of modular public headers (those listed in "hdrs") that are declared by this target. + Returns the list of modular public headers (those listed in "hdrs") that are declared by this target. + + ## direct\_textual\_headers @@ -59,7 +68,9 @@ Returns the list of modular public headers (those listed in "hdrs") that are dec list CompilationContext.direct_textual_headers ``` -Returns the list of textual headers that are declared by this target. + Returns the list of textual headers that are declared by this target. + + ## external\_includes @@ -67,7 +78,9 @@ Returns the list of textual headers that are declared by this target. depset CompilationContext.external_includes ``` -Returns the set of search paths (as strings) for external header files referenced by angle bracket. Usually passed with -isystem. + Returns the set of search paths (as strings) for external header files referenced by angle bracket. Usually passed with -isystem. + + ## framework\_includes @@ -75,7 +88,9 @@ Returns the set of search paths (as strings) for external header files reference depset CompilationContext.framework_includes ``` -Returns the set of search paths (as strings) for framework header files. Usually passed with -F. + Returns the set of search paths (as strings) for framework header files. Usually passed with -F. + + ## headers @@ -83,7 +98,9 @@ Returns the set of search paths (as strings) for framework header files. Usually depset CompilationContext.headers ``` -Returns the set of headers needed to compile this target. + Returns the set of headers needed to compile this target. + + ## includes @@ -91,7 +108,9 @@ Returns the set of headers needed to compile this target. depset CompilationContext.includes ``` -Returns the set of search paths (as strings) for header files referenced both by angle bracket and quotes. Usually passed with -I. + Returns the set of search paths (as strings) for header files referenced both by angle bracket and quotes. Usually passed with -I. + + ## local\_defines @@ -99,7 +118,9 @@ Returns the set of search paths (as strings) for header files referenced both by depset CompilationContext.local_defines ``` -Returns the set of defines needed to compile this target. Each define is a string. These values are not propagated to the target's transitive dependents. + Returns the set of defines needed to compile this target. Each define is a string. These values are not propagated to the target's transitive dependents. + + ## quote\_includes @@ -107,7 +128,9 @@ Returns the set of defines needed to compile this target. Each define is a strin depset CompilationContext.quote_includes ``` -Returns the set of search paths (as strings) for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. + Returns the set of search paths (as strings) for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. + + ## system\_includes @@ -115,7 +138,9 @@ Returns the set of search paths (as strings) for header files referenced by quot depset CompilationContext.system_includes ``` -Returns the set of search paths (as strings) for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. + Returns the set of search paths (as strings) for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. + + ## validation\_artifacts @@ -123,4 +148,4 @@ Returns the set of search paths (as strings) for header files referenced by angl depset CompilationContext.validation_artifacts ``` -Returns the set of validation artifacts. \ No newline at end of file + Returns the set of validation artifacts. diff --git a/rules/lib/builtins/DirectoryExpander.mdx b/rules/lib/builtins/DirectoryExpander.mdx index e1de798..c41258a 100644 --- a/rules/lib/builtins/DirectoryExpander.mdx +++ b/rules/lib/builtins/DirectoryExpander.mdx @@ -3,11 +3,12 @@ title: 'DirectoryExpander' --- + Expands directories created by [`ctx.actions.declare_directory`](../builtins/actions.html#declare_directory) during the execution phase. This is useful to expand directories in [`map_each`](../builtins/Args.html#add_all.map_each). ## Members -* [expand](#expand) +- [expand](#expand) ## expand @@ -15,10 +16,12 @@ Expands directories created by [`ctx.actions.declare_directory`](../builtins/act list DirectoryExpander.expand(file) ``` -If the given `File` is a directory, this returns a list of `File`s recursively underneath the directory. Otherwise, this returns a list containing just the given `File` itself. + If the given `File` is a directory, this returns a list of `File` s recursively underneath the directory. Otherwise, this returns a list containing just the given `File` itself. + ### Parameters -| Parameter | Description | -| --- | --- | -| `file` | [File](../builtins/File.mdx); required The directory or file to expand. | \ No newline at end of file +ParameterDescription`file`[File](../builtins/File.html); + required + + The directory or file to expand. diff --git a/rules/lib/builtins/DottedVersion.mdx b/rules/lib/builtins/DottedVersion.mdx index 9dcbb0f..1883781 100644 --- a/rules/lib/builtins/DottedVersion.mdx +++ b/rules/lib/builtins/DottedVersion.mdx @@ -3,11 +3,12 @@ title: 'DottedVersion' --- + A value representing a version with multiple components, separated by periods, such as 1.2.3.4. ## Members -* [compare\_to](#compare_to) +- [compare\_to](#compare_to) ## compare\_to @@ -15,10 +16,12 @@ A value representing a version with multiple components, separated by periods, s int DottedVersion.compare_to(other) ``` -Compares based on most significant (first) not-matching version component. So, for example, 1.2.3 < 1.2.4 + Compares based on most significant (first) not-matching version component. So, for example, 1.2.3 < 1.2.4 + ### Parameters -| Parameter | Description | -| --- | --- | -| `other` | [DottedVersion](../builtins/DottedVersion.mdx); required The other dotted version. | \ No newline at end of file +ParameterDescription`other`[DottedVersion](../builtins/DottedVersion.html); + required + + The other dotted version. diff --git a/rules/lib/builtins/ExecGroupCollection.mdx b/rules/lib/builtins/ExecGroupCollection.mdx index 7b85845..6ef169f 100644 --- a/rules/lib/builtins/ExecGroupCollection.mdx +++ b/rules/lib/builtins/ExecGroupCollection.mdx @@ -3,4 +3,5 @@ title: 'ExecGroupCollection' --- -Stores exec groups available to a given rule. \ No newline at end of file + +Stores exec groups available to a given rule. diff --git a/rules/lib/builtins/ExecGroupContext.mdx b/rules/lib/builtins/ExecGroupContext.mdx index c615c1f..949d9c9 100644 --- a/rules/lib/builtins/ExecGroupContext.mdx +++ b/rules/lib/builtins/ExecGroupContext.mdx @@ -3,11 +3,12 @@ title: 'ExecGroupContext' --- + Stores information about an exec group. ## Members -* [toolchains](#toolchains) +- [toolchains](#toolchains) ## toolchains @@ -15,4 +16,4 @@ Stores information about an exec group. ToolchainContext ExecGroupContext.toolchains ``` -Toolchains required for this exec group \ No newline at end of file + Toolchains required for this exec group diff --git a/rules/lib/builtins/ExecTransitionFactory.mdx b/rules/lib/builtins/ExecTransitionFactory.mdx index eaaa96b..a296560 100644 --- a/rules/lib/builtins/ExecTransitionFactory.mdx +++ b/rules/lib/builtins/ExecTransitionFactory.mdx @@ -3,4 +3,5 @@ title: 'ExecTransitionFactory' --- -an execution transition. \ No newline at end of file + +an execution transition. diff --git a/rules/lib/builtins/ExpandedDirectory.mdx b/rules/lib/builtins/ExpandedDirectory.mdx index e5facf0..65e06bc 100644 --- a/rules/lib/builtins/ExpandedDirectory.mdx +++ b/rules/lib/builtins/ExpandedDirectory.mdx @@ -3,12 +3,13 @@ title: 'ExpandedDirectory' --- + Represents an expanded directory that makes the files within the it directly accessible. ## Members -* [children](#children) -* [directory](#directory) +- [children](#children) +- [directory](#directory) ## children @@ -16,7 +17,9 @@ Represents an expanded directory that makes the files within the it directly acc list ExpandedDirectory.children ``` -Contains the files within the directory. + Contains the files within the directory. + + ## directory @@ -24,4 +27,4 @@ Contains the files within the directory. File ExpandedDirectory.directory ``` -The input directory that was expanded. \ No newline at end of file + The input directory that was expanded. diff --git a/rules/lib/builtins/FeatureConfiguration.mdx b/rules/lib/builtins/FeatureConfiguration.mdx index e1a30eb..502cbda 100644 --- a/rules/lib/builtins/FeatureConfiguration.mdx +++ b/rules/lib/builtins/FeatureConfiguration.mdx @@ -3,4 +3,5 @@ title: 'FeatureConfiguration' --- -Class used to construct command lines from CROSSTOOL features. \ No newline at end of file + +Class used to construct command lines from CROSSTOOL features. diff --git a/rules/lib/builtins/File.mdx b/rules/lib/builtins/File.mdx index a2d7b08..8c51b1d 100644 --- a/rules/lib/builtins/File.mdx +++ b/rules/lib/builtins/File.mdx @@ -3,23 +3,24 @@ title: 'File' --- + This object is created during the analysis phase to represent a file or directory that will be read or written during the execution phase. It is not an open file handle, and cannot be used to directly read or write file contents. Rather, you use it to construct the action graph in a rule implementation function by passing it to action-creating functions. See the [Rules page](https://bazel.build/extending/rules#files) for more information. -When a `File` is passed to an [`Args`](../builtins/Args.mdx) object without using a `map_each` function, it is converted to a string by taking the value of its `path` field. +When a `File` is passed to an [`Args`](../builtins/Args.html) object without using a `map_each` function, it is converted to a string by taking the value of its `path` field. ## Members -* [basename](#basename) -* [dirname](#dirname) -* [extension](#extension) -* [is\_directory](#is_directory) -* [is\_source](#is_source) -* [is\_symlink](#is_symlink) -* [owner](#owner) -* [path](#path) -* [root](#root) -* [short\_path](#short_path) -* [tree\_relative\_path](#tree_relative_path) +- [basename](#basename) +- [dirname](#dirname) +- [extension](#extension) +- [is\_directory](#is_directory) +- [is\_source](#is_source) +- [is\_symlink](#is_symlink) +- [owner](#owner) +- [path](#path) +- [root](#root) +- [short\_path](#short_path) +- [tree\_relative\_path](#tree_relative_path) ## basename @@ -27,7 +28,9 @@ When a `File` is passed to an [`Args`](../builtins/Args.mdx) object without usin string File.basename ``` -The base name of this file. This is the name of the file inside the directory. + The base name of this file. This is the name of the file inside the directory. + + ## dirname @@ -35,7 +38,9 @@ The base name of this file. This is the name of the file inside the directory. string File.dirname ``` -The name of the directory containing this file. It's taken from [path](#path) and is always relative to the execution directory. + The name of the directory containing this file. It's taken from [path](#path) and is always relative to the execution directory. + + ## extension @@ -43,7 +48,9 @@ The name of the directory containing this file. It's taken from [path](#path) an string File.extension ``` -The file extension of this file, following (not including) the rightmost period. Empty string if the file's basename includes no periods. + The file extension of this file, following (not including) the rightmost period. Empty string if the file's basename includes no periods. + + ## is\_directory @@ -51,7 +58,9 @@ The file extension of this file, following (not including) the rightmost period. bool File.is_directory ``` -Returns true if this is a directory. This reflects the type the file was declared as (i.e. ctx.actions.declare\_directory), not its type on the filesystem, which might differ. + Returns true if this is a directory. This reflects the type the file was declared as (i.e. ctx.actions.declare\_directory), not its type on the filesystem, which might differ. + + ## is\_source @@ -59,7 +68,9 @@ Returns true if this is a directory. This reflects the type the file was declare bool File.is_source ``` -Returns true if this is a source file, i.e. it is not generated. + Returns true if this is a source file, i.e. it is not generated. + + ## is\_symlink @@ -67,7 +78,9 @@ Returns true if this is a source file, i.e. it is not generated. bool File.is_symlink ``` -Returns true if this was declared as a symlink. This reflects the type the file was declared as (i.e. ctx.actions.declare\_symlink), not its type on the filesystem, which might differ. + Returns true if this was declared as a symlink. This reflects the type the file was declared as (i.e. ctx.actions.declare\_symlink), not its type on the filesystem, which might differ. + + ## owner @@ -75,8 +88,10 @@ Returns true if this was declared as a symlink. This reflects the type the file Label File.owner ``` -A label of a target that produces this File. -May return `None`. + A label of a target that produces this File. + May return `None`. + + ## path @@ -84,7 +99,9 @@ May return `None`. string File.path ``` -The execution path of this file, relative to the workspace's execution directory. It consists of two parts, an optional first part called the *root* (see also the [root](../builtins/root.mdx) module), and the second part which is the `short_path`. The root may be empty, which it usually is for non-generated files. For generated files it usually contains a configuration-specific path fragment that encodes things like the target CPU architecture that was used while building said file. Use the `short_path` for the path under which the file is mapped if it's in the runfiles of a binary. + The execution path of this file, relative to the workspace's execution directory. It consists of two parts, an optional first part called the _root_ (see also the [root](../builtins/root.html) module), and the second part which is the `short_path`. The root may be empty, which it usually is for non-generated files. For generated files it usually contains a configuration-specific path fragment that encodes things like the target CPU architecture that was used while building said file. Use the `short_path` for the path under which the file is mapped if it's in the runfiles of a binary. + + ## root @@ -92,7 +109,9 @@ The execution path of this file, relative to the workspace's execution directory root File.root ``` -The root beneath which this file resides. + The root beneath which this file resides. + + ## short\_path @@ -100,7 +119,9 @@ The root beneath which this file resides. string File.short_path ``` -The path of this file relative to its root. This excludes the aforementioned *root*, i.e. configuration-specific fragments of the path. This is also the path under which the file is mapped if it's in the runfiles of a binary. + The path of this file relative to its root. This excludes the aforementioned _root_, i.e. configuration-specific fragments of the path. This is also the path under which the file is mapped if it's in the runfiles of a binary. + + ## tree\_relative\_path @@ -108,4 +129,4 @@ The path of this file relative to its root. This excludes the aforementioned *ro string File.tree_relative_path ``` -The path of this file relative to the root of the ancestor's tree, if the ancestor's [is\_directory](#is_directory) field is true. `tree_relative_path` is only available for expanded files of a directory in an action command, i.e. [Args.add\_all()](../builtins/Args.html#add_all). For other types of files, it is an error to access this field. \ No newline at end of file + The path of this file relative to the root of the ancestor's tree, if the ancestor's [is\_directory](#is_directory) field is true. `tree_relative_path` is only available for expanded files of a directory in an action command, i.e. [Args.add\_all()](../builtins/Args.html#add_all). For other types of files, it is an error to access this field. diff --git a/rules/lib/builtins/Label.mdx b/rules/lib/builtins/Label.mdx index cc8cfff..ef1c97d 100644 --- a/rules/lib/builtins/Label.mdx +++ b/rules/lib/builtins/Label.mdx @@ -3,22 +3,23 @@ title: 'Label' --- + A BUILD target identifier. For every `Label` instance `l`, the string representation `str(l)` has the property that `Label(str(l)) == l`, regardless of where the `Label()` call occurs. -When passed as positional arguments to `print()` or `fail()`, `Label` use a string representation optimized for human readability instead. This representation uses an [apparent repository name](./external/overview#apparent-repo-name) from the perspective of the main repository if possible. +When passed as positional arguments to `print()` or `fail()`, `Label` use a string representation optimized for human readability instead. This representation uses an [apparent repository name](/external/overview#apparent-repo-name) from the perspective of the main repository if possible. ## Members -* [Label](#Label) -* [name](#name) -* [package](#package) -* [relative](#relative) -* [repo\_name](#repo_name) -* [same\_package\_label](#same_package_label) -* [workspace\_name](#workspace_name) -* [workspace\_root](#workspace_root) +- [Label](#Label) +- [name](#name) +- [package](#package) +- [relative](#relative) +- [repo\_name](#repo_name) +- [same\_package\_label](#same_package_label) +- [workspace\_name](#workspace_name) +- [workspace\_root](#workspace_root) ## Label @@ -26,15 +27,18 @@ When passed as positional arguments to `print()` or `fail()`, `Label` use a stri Label Label(input) ``` -Converts a label string into a `Label` object, in the context of the package where the calling `.bzl` source file lives. If the given value is already a `Label`, it is returned unchanged. + Converts a label string into a `Label` object, in the context of the package where the calling `.bzl` source file lives. If the given value is already a `Label`, it is returned unchanged. For macros, a related function, `native.package_relative_label()`, converts the input into a `Label` in the context of the package currently being constructed. Use that function to mimic the string-to-label conversion that is automatically done by label-valued rule attributes. + ### Parameters -| Parameter | Description | -| --- | --- | -| `input` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); required The input label string or Label object. If a Label object is passed, it's returned as is. | +ParameterDescription`input`[string](../core/string.html); or [Label](../builtins/Label.html); + required + + The input label string or Label object. If a Label object is passed, it's returned as is. + ## name @@ -42,7 +46,7 @@ For macros, a related function, `native.package_relative_label()`, converts the string Label.name ``` -The name of the target referred to by this label. For instance: + The name of the target referred to by this label. For instance: ``` Label("@@foo//pkg/foo:abc").name == "abc" @@ -54,7 +58,7 @@ Label("@@foo//pkg/foo:abc").name == "abc" string Label.package ``` -The name of the package containing the target referred to by this label, without the repository name. For instance: + The name of the package containing the target referred to by this label, without the repository name. For instance: ``` Label("@@repo//pkg/foo:abc").package == "pkg/foo" @@ -66,11 +70,13 @@ Label("@@repo//pkg/foo:abc").package == "pkg/foo" Label Label.relative(relName) ``` -**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` + **Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` + **Deprecated.** This method behaves surprisingly when used with an argument containing an apparent repo name. Prefer [`Label.same_package_label()`](#same_package_label), [`native.package_relative_label()`](../toplevel/native.html#package_relative_label), or [`Label()`](#Label) instead. -Resolves a label that is either absolute (starts with `//`) or relative to the current package. If this label is in a remote repository, the argument will be resolved relative to that repository. If the argument contains a repository name, the current label is ignored and the argument is returned as-is, except that the repository name is rewritten if it is in the current repository mapping. Reserved labels will also be returned as-is. -For example: +Resolves a label that is either absolute (starts with `//`) or relative to the current package. If this label is in a remote repository, the argument will be resolved relative to that repository. If the argument contains a repository name, the current label is ignored and the argument is returned as-is, except that the repository name is rewritten if it is in the current repository mapping. Reserved labels will also be returned as-is. + +For example: ``` Label("//foo/bar:baz").relative(":quux") == Label("//foo/bar:quux") @@ -78,19 +84,23 @@ Label("//foo/bar:baz").relative("//wiz:quux") == Label("//wiz:quux") Label("@repo//foo/bar:baz").relative("//wiz:quux") == Label("@repo//wiz:quux") Label("@repo//foo/bar:baz").relative("//visibility:public") == Label("//visibility:public") Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@other//wiz:quux") + ``` -If the repository mapping passed in is `\{'@other' : '@remapped'\}`, then the following remapping will take place: +If the repository mapping passed in is `{'@other' : '@remapped'}`, then the following remapping will take place: ``` Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@remapped//wiz:quux") + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `relName` | [string](../core/string.mdx); required | +ParameterDescription`relName`[string](../core/string.html); + required + + The label that will be resolved relative to this one. + ## repo\_name @@ -98,7 +108,7 @@ Label("@repo//foo/bar:baz").relative("@other//wiz:quux") == Label("@remapped//wi string Label.repo_name ``` -The canonical name of the repository containing the target referred to by this label, without any leading at-signs (`@`). For instance, + The canonical name of the repository containing the target referred to by this label, without any leading at-signs ( `@`). For instance, ``` Label("@@foo//bar:baz").repo_name == "foo" @@ -110,13 +120,16 @@ Label("@@foo//bar:baz").repo_name == "foo" Label Label.same_package_label(target_name) ``` -Creates a label in the same package as this label with the given target name. + Creates a label in the same package as this label with the given target name. + ### Parameters -| Parameter | Description | -| --- | --- | -| `target_name` | [string](../core/string.mdx); required | +ParameterDescription`target_name`[string](../core/string.html); + required + + The target name of the new label. + ## workspace\_name @@ -124,10 +137,11 @@ Creates a label in the same package as this label with the given target name. string Label.workspace_name ``` -**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` + **Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` + **Deprecated.** The field name "workspace name" is a misnomer here; use the identically-behaving [`Label.repo_name`](#repo_name) instead. -The canonical name of the repository containing the target referred to by this label, without any leading at-signs (`@`). For instance, +The canonical name of the repository containing the target referred to by this label, without any leading at-signs ( `@`). For instance, ``` Label("@@foo//bar:baz").workspace_name == "foo" @@ -139,8 +153,8 @@ Label("@@foo//bar:baz").workspace_name == "foo" string Label.workspace_root ``` -Returns the execution root for the repository containing the target referred to by this label, relative to the execroot. For instance: + Returns the execution root for the repository containing the target referred to by this label, relative to the execroot. For instance: ``` Label("@repo//pkg/foo:abc").workspace_root == "external/repo" -``` \ No newline at end of file +``` diff --git a/rules/lib/builtins/LateBoundDefault.mdx b/rules/lib/builtins/LateBoundDefault.mdx index 9dbc0bf..a9b278b 100644 --- a/rules/lib/builtins/LateBoundDefault.mdx +++ b/rules/lib/builtins/LateBoundDefault.mdx @@ -3,6 +3,7 @@ title: 'LateBoundDefault' --- + Represents a late-bound default attribute value of type 'Label'. The value of a LateBoundDefault is only resolvable in the context of a rule implementation function, and depends on the current build configuration. For example, a LateBoundDefault might represent the Label of the java toolchain in the current build configuration. -See [configuration\_field](../globals/bzl.html#configuration_field) for example usage. \ No newline at end of file +See [configuration\_field](../globals/bzl.html#configuration_field) for example usage. diff --git a/rules/lib/builtins/LibraryToLink.mdx b/rules/lib/builtins/LibraryToLink.mdx index d424b9c..abeee80 100644 --- a/rules/lib/builtins/LibraryToLink.mdx +++ b/rules/lib/builtins/LibraryToLink.mdx @@ -3,21 +3,22 @@ title: 'LibraryToLink' --- + A library the user can link against. ## Members -* [alwayslink](#alwayslink) -* [dynamic\_library](#dynamic_library) -* [interface\_library](#interface_library) -* [lto\_bitcode\_files](#lto_bitcode_files) -* [objects](#objects) -* [pic\_lto\_bitcode\_files](#pic_lto_bitcode_files) -* [pic\_objects](#pic_objects) -* [pic\_static\_library](#pic_static_library) -* [resolved\_symlink\_dynamic\_library](#resolved_symlink_dynamic_library) -* [resolved\_symlink\_interface\_library](#resolved_symlink_interface_library) -* [static\_library](#static_library) +- [alwayslink](#alwayslink) +- [dynamic\_library](#dynamic_library) +- [interface\_library](#interface_library) +- [lto\_bitcode\_files](#lto_bitcode_files) +- [objects](#objects) +- [pic\_lto\_bitcode\_files](#pic_lto_bitcode_files) +- [pic\_objects](#pic_objects) +- [pic\_static\_library](#pic_static_library) +- [resolved\_symlink\_dynamic\_library](#resolved_symlink_dynamic_library) +- [resolved\_symlink\_interface\_library](#resolved_symlink_interface_library) +- [static\_library](#static_library) ## alwayslink @@ -25,7 +26,9 @@ A library the user can link against. bool LibraryToLink.alwayslink ``` -Whether to link the static library/objects in the --whole\_archive block. + Whether to link the static library/objects in the --whole\_archive block. + + ## dynamic\_library @@ -33,8 +36,10 @@ Whether to link the static library/objects in the --whole\_archive block. File LibraryToLink.dynamic_library ``` -`Artifact` of dynamic library to be linked. Always used for runtime and used for linking if `interface_library` is not passed. -May return `None`. + `Artifact` of dynamic library to be linked. Always used for runtime and used for linking if `interface_library` is not passed. + May return `None`. + + ## interface\_library @@ -42,8 +47,10 @@ May return `None`. File LibraryToLink.interface_library ``` -`Artifact` of interface library to be linked. -May return `None`. + `Artifact` of interface library to be linked. + May return `None`. + + ## lto\_bitcode\_files @@ -51,8 +58,10 @@ May return `None`. sequence LibraryToLink.lto_bitcode_files ``` -`List` of LTO bitcode files in the library. -May return `None`. + `List` of LTO bitcode files in the library. + May return `None`. + + ## objects @@ -60,8 +69,10 @@ May return `None`. sequence LibraryToLink.objects ``` -`List` of object files in the library. -May return `None`. + `List` of object files in the library. + May return `None`. + + ## pic\_lto\_bitcode\_files @@ -69,8 +80,10 @@ May return `None`. sequence LibraryToLink.pic_lto_bitcode_files ``` -`List` of pic LTO bitcode files in the library. -May return `None`. + `List` of pic LTO bitcode files in the library. + May return `None`. + + ## pic\_objects @@ -78,8 +91,10 @@ May return `None`. sequence LibraryToLink.pic_objects ``` -`List` of pic object files in the library. -May return `None`. + `List` of pic object files in the library. + May return `None`. + + ## pic\_static\_library @@ -87,8 +102,10 @@ May return `None`. File LibraryToLink.pic_static_library ``` -`Artifact` of pic static library to be linked. -May return `None`. + `Artifact` of pic static library to be linked. + May return `None`. + + ## resolved\_symlink\_dynamic\_library @@ -96,8 +113,10 @@ May return `None`. File LibraryToLink.resolved_symlink_dynamic_library ``` -The resolved `Artifact` of the dynamic library to be linked if `dynamic_library` is a symlink, otherwise this is None. -May return `None`. + The resolved `Artifact` of the dynamic library to be linked if `dynamic_library` is a symlink, otherwise this is None. + May return `None`. + + ## resolved\_symlink\_interface\_library @@ -105,8 +124,10 @@ May return `None`. File LibraryToLink.resolved_symlink_interface_library ``` -The resolved `Artifact` of the interface library to be linked if `interface_library` is a symlink, otherwise this is None. -May return `None`. + The resolved `Artifact` of the interface library to be linked if `interface_library` is a symlink, otherwise this is None. + May return `None`. + + ## static\_library @@ -114,5 +135,5 @@ May return `None`. File LibraryToLink.static_library ``` -`Artifact` of static library to be linked. -May return `None`. \ No newline at end of file + `Artifact` of static library to be linked. + May return `None`. diff --git a/rules/lib/builtins/License.mdx b/rules/lib/builtins/License.mdx index e977075..2413249 100644 --- a/rules/lib/builtins/License.mdx +++ b/rules/lib/builtins/License.mdx @@ -3,4 +3,5 @@ title: 'License' --- -This API is deprecated and will be removed. Please do not depend on it. This object represents the value of a license attribute. \ No newline at end of file + +This API is deprecated and will be removed. Please do not depend on it. This object represents the value of a license attribute. diff --git a/rules/lib/builtins/LinkerInput.mdx b/rules/lib/builtins/LinkerInput.mdx index 2fa8b95..c6fe3a5 100644 --- a/rules/lib/builtins/LinkerInput.mdx +++ b/rules/lib/builtins/LinkerInput.mdx @@ -3,14 +3,15 @@ title: 'LinkerInput' --- + Either libraries, flags or other files that may be passed to the linker as inputs. ## Members -* [additional\_inputs](#additional_inputs) -* [libraries](#libraries) -* [owner](#owner) -* [user\_link\_flags](#user_link_flags) +- [additional\_inputs](#additional_inputs) +- [libraries](#libraries) +- [owner](#owner) +- [user\_link\_flags](#user_link_flags) ## additional\_inputs @@ -18,7 +19,9 @@ Either libraries, flags or other files that may be passed to the linker as input sequence LinkerInput.additional_inputs ``` -Returns the depset of additional inputs, e.g.: linker scripts. + Returns the depset of additional inputs, e.g.: linker scripts. + + ## libraries @@ -26,7 +29,9 @@ Returns the depset of additional inputs, e.g.: linker scripts. sequence LinkerInput.libraries ``` -Returns the depset of `LibraryToLink`. May return a list but this is deprecated. See #8118. + Returns the depset of `LibraryToLink`. May return a list but this is deprecated. See #8118. + + ## owner @@ -34,7 +39,9 @@ Returns the depset of `LibraryToLink`. May return a list but this is deprecated. Label LinkerInput.owner ``` -Returns the owner of this LinkerInput. + Returns the owner of this LinkerInput. + + ## user\_link\_flags @@ -42,4 +49,4 @@ Returns the owner of this LinkerInput. sequence LinkerInput.user_link_flags ``` -Returns the list of user link flags passed as strings. \ No newline at end of file + Returns the list of user link flags passed as strings. diff --git a/rules/lib/builtins/LinkingContext.mdx b/rules/lib/builtins/LinkingContext.mdx index d5072e8..24c9a9e 100644 --- a/rules/lib/builtins/LinkingContext.mdx +++ b/rules/lib/builtins/LinkingContext.mdx @@ -3,11 +3,12 @@ title: 'LinkingContext' --- + Immutable store of information needed for C++ linking that is aggregated across dependencies. ## Members -* [linker\_inputs](#linker_inputs) +- [linker\_inputs](#linker_inputs) ## linker\_inputs @@ -15,4 +16,4 @@ Immutable store of information needed for C++ linking that is aggregated across depset LinkingContext.linker_inputs ``` -Returns the depset of linker inputs. \ No newline at end of file + Returns the depset of linker inputs. diff --git a/rules/lib/builtins/Provider.mdx b/rules/lib/builtins/Provider.mdx index b2f281b..cf207e8 100644 --- a/rules/lib/builtins/Provider.mdx +++ b/rules/lib/builtins/Provider.mdx @@ -3,10 +3,12 @@ title: 'Provider' --- -A constructor for simple value objects, known as provider instances. + +A constructor for simple value objects, known as provider instances. + This value has a dual purpose: -* It is a function that can be called to construct 'struct'-like values: +- It is a function that can be called to construct 'struct'-like values: ``` DataInfo = provider() @@ -14,8 +16,8 @@ This value has a dual purpose: print(d.x + d.y) # prints 5 ``` - Note: Some providers, defined internally, do not allow instance creation -* It is a *key* to access a provider instance on a [Target](../builtins/Target.mdx) + Note: Some providers, defined internally, do not allow instance creation +- It is a _key_ to access a provider instance on a [Target](../builtins/Target.html) ``` DataInfo = provider() @@ -23,4 +25,5 @@ This value has a dual purpose: ... ctx.attr.dep[DataInfo] ``` -Create a new `Provider` using the [provider](../globals/bzl.html#provider) function. \ No newline at end of file + +Create a new `Provider` using the [provider](../globals/bzl.html#provider) function. diff --git a/rules/lib/builtins/Subrule.mdx b/rules/lib/builtins/Subrule.mdx index b608c95..850479d 100644 --- a/rules/lib/builtins/Subrule.mdx +++ b/rules/lib/builtins/Subrule.mdx @@ -3,4 +3,5 @@ title: 'Subrule' --- -Experimental: a building block for writing rules with shared code. For more information, please see the subrule proposal: https://docs.google.com/document/d/1RbNC88QieKvBEwir7iV5zZU08AaMlOzxhVkPnmKDedQ \ No newline at end of file + +Experimental: a building block for writing rules with shared code. For more information, please see the subrule proposal: https://docs.google.com/document/d/1RbNC88QieKvBEwir7iV5zZU08AaMlOzxhVkPnmKDedQ diff --git a/rules/lib/builtins/SymlinkEntry.mdx b/rules/lib/builtins/SymlinkEntry.mdx index 94a6fe2..7b1bddd 100644 --- a/rules/lib/builtins/SymlinkEntry.mdx +++ b/rules/lib/builtins/SymlinkEntry.mdx @@ -3,12 +3,13 @@ title: 'SymlinkEntry' --- + A single runfiles symlink represented by a link name and target. ## Members -* [path](#path) -* [target\_file](#target_file) +- [path](#path) +- [target\_file](#target_file) ## path @@ -16,7 +17,9 @@ A single runfiles symlink represented by a link name and target. string SymlinkEntry.path ``` -The path of the symlink in the runfiles tree + The path of the symlink in the runfiles tree + + ## target\_file @@ -24,4 +27,4 @@ The path of the symlink in the runfiles tree File SymlinkEntry.target_file ``` -Target file of the symlink \ No newline at end of file + Target file of the symlink diff --git a/rules/lib/builtins/Target.mdx b/rules/lib/builtins/Target.mdx index d750a1f..53d89d2 100644 --- a/rules/lib/builtins/Target.mdx +++ b/rules/lib/builtins/Target.mdx @@ -3,12 +3,16 @@ title: 'Target' --- -The BUILD target for a dependency. Appears in the fields of `ctx.attr` corresponding to [dependency attributes](https://bazel.build/extending/rules#dependency_attributes) (`label` or `label_list`). Has the following fields: -* ### label +The BUILD target for a dependency. Appears in the fields of `ctx.attr` corresponding to [dependency attributes](https://bazel.build/extending/rules#dependency_attributes) ( `label` or `label_list`). Has the following fields: + +- ### label + + `Label Target.label` + - `Label Target.label` The identifier of the target. -* ### Providers +- ### Providers + - The [providers](https://bazel.build/extending/rules#providers) of a rule target can be accessed by type using index notation (`target[DefaultInfo]`). The presence of providers can be checked using the `in` operator (`SomeInfo in target`). \ No newline at end of file + The [providers](https://bazel.build/extending/rules#providers) of a rule target can be accessed by type using index notation ( `target[DefaultInfo]`). The presence of providers can be checked using the `in` operator ( `SomeInfo in target`). diff --git a/rules/lib/builtins/TemplateDict.mdx b/rules/lib/builtins/TemplateDict.mdx index 3f10a99..ee8265b 100644 --- a/rules/lib/builtins/TemplateDict.mdx +++ b/rules/lib/builtins/TemplateDict.mdx @@ -3,12 +3,13 @@ title: 'TemplateDict' --- + An Args-like structure for use in ctx.actions.expand\_template(), which allows for deferring evaluation of values till the execution phase. ## Members -* [add](#add) -* [add\_joined](#add_joined) +- [add](#add) +- [add\_joined](#add_joined) ## add @@ -16,14 +17,20 @@ An Args-like structure for use in ctx.actions.expand\_template(), which allows f TemplateDict TemplateDict.add(key, value) ``` -Add a String value + Add a String value + ### Parameters -| Parameter | Description | -| --- | --- | -| `key` | [string](../core/string.mdx); required A String key | -| `value` | [string](../core/string.mdx); required A String value | +ParameterDescription`key`[string](../core/string.html); + required + + A String key + `value`[string](../core/string.html); + required + + A String value + ## add\_joined @@ -31,16 +38,37 @@ Add a String value TemplateDict TemplateDict.add_joined(key, values, *, join_with, map_each, uniquify=False, format_joined=None, allow_closure=False) ``` -Add depset of values + Add depset of values + ### Parameters -| Parameter | Description | -| --- | --- | -| `key` | [string](../core/string.mdx); required A String key | -| `values` | [depset](../builtins/depset.mdx); required The depset whose items will be joined. | -| `join_with` | [string](../core/string.mdx); required A delimiter string used to join together the strings obtained from applying `map_each`, in the same manner as [`string.join()`](../core/string.html#join). | -| `map_each` | callable; required A Starlark function accepting a single argument and returning either a string, `None`, or a list of strings. This function is applied to each item of the depset specified in the `values` parameter | -| `uniquify` | [bool](../core/bool.mdx); default is `False` If true, duplicate strings derived from `values` will be omitted. Only the first occurrence of each string will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if `map_each` emits the same string for multiple items. | -| `format_joined` | [string](../core/string.mdx); or `None`; default is `None` An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. | -| `allow_closure` | [bool](../core/bool.mdx); default is `False` If true, allows the use of closures in function parameters like `map_each`. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. | \ No newline at end of file +ParameterDescription`key`[string](../core/string.html); + required + + A String key + `values`[depset](../builtins/depset.html); + required + + The depset whose items will be joined. + `join_with`[string](../core/string.html); + required + + A delimiter string used to join together the strings obtained from applying `map_each`, in the same manner as [`string.join()`](../core/string.html#join). + `map_each` + callable; + required + + A Starlark function accepting a single argument and returning either a string, `None`, or a list of strings. This function is applied to each item of the depset specified in the `values` parameter + `uniquify`[bool](../core/bool.html); + default is `False` + + If true, duplicate strings derived from `values` will be omitted. Only the first occurrence of each string will remain. Usually this feature is not needed because depsets already omit duplicates, but it can be useful if `map_each` emits the same string for multiple items. + `format_joined`[string](../core/string.html); or `None`; + default is `None` + + An optional format string pattern applied to the joined string. The format string must have exactly one '%s' placeholder. + `allow_closure`[bool](../core/bool.html); + default is `False` + + If true, allows the use of closures in function parameters like `map_each`. Usually this isn't necessary and it risks retaining large analysis-phase data structures into the execution phase. diff --git a/rules/lib/builtins/ToolchainContext.mdx b/rules/lib/builtins/ToolchainContext.mdx index 33ff674..75862f1 100644 --- a/rules/lib/builtins/ToolchainContext.mdx +++ b/rules/lib/builtins/ToolchainContext.mdx @@ -3,4 +3,5 @@ title: 'ToolchainContext' --- -Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in `ctx.toolchains["//pkg:my_toolchain_type"]`. If the toolchain was optional and no toolchain was resolved, this will return `None`. Accessing toolchains of an aspect or rule via `ctx.toolchains` returns the indexed toolchain as a `ToolchainInfo` provider. While when using aspects, `ToolchainContext` is also used to hold the toolchains of the base target. It can be accessed by `ctx.rule.toolchains["//pkg:my_toolchain_type"]` and it returns the list of providers resulted from applying the aspects on these toolchain targets. \ No newline at end of file + +Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in `ctx.toolchains["//pkg:my_toolchain_type"]`. If the toolchain was optional and no toolchain was resolved, this will return `None`. Accessing toolchains of an aspect or rule via `ctx.toolchains` returns the indexed toolchain as a `ToolchainInfo` provider. While when using aspects, `ToolchainContext` is also used to hold the toolchains of the base target. It can be accessed by `ctx.rule.toolchains["//pkg:my_toolchain_type"]` and it returns the list of providers resulted from applying the aspects on these toolchain targets. diff --git a/rules/lib/builtins/actions.mdx b/rules/lib/builtins/actions.mdx index 67e4387..60a13f6 100644 --- a/rules/lib/builtins/actions.mdx +++ b/rules/lib/builtins/actions.mdx @@ -3,22 +3,23 @@ title: 'actions' --- + Module providing functions to create actions. Access this module using [`ctx.actions`](../builtins/ctx.html#actions). ## Members -* [args](#args) -* [declare\_directory](#declare_directory) -* [declare\_file](#declare_file) -* [declare\_symlink](#declare_symlink) -* [do\_nothing](#do_nothing) -* [expand\_template](#expand_template) -* [map\_directory](#map_directory) -* [run](#run) -* [run\_shell](#run_shell) -* [symlink](#symlink) -* [template\_dict](#template_dict) -* [write](#write) +- [args](#args) +- [declare\_directory](#declare_directory) +- [declare\_file](#declare_file) +- [declare\_symlink](#declare_symlink) +- [do\_nothing](#do_nothing) +- [expand\_template](#expand_template) +- [map\_directory](#map_directory) +- [run](#run) +- [run\_shell](#run_shell) +- [symlink](#symlink) +- [template\_dict](#template_dict) +- [write](#write) ## args @@ -26,7 +27,9 @@ Module providing functions to create actions. Access this module using [`ctx.act Args actions.args() ``` -Returns an Args object that can be used to build memory-efficient command lines. + Returns an Args object that can be used to build memory-efficient command lines. + + ## declare\_directory @@ -34,14 +37,20 @@ Returns an Args object that can be used to build memory-efficient command lines. File actions.declare_directory(filename, *, sibling=None) ``` -Declares that the rule or aspect creates a directory with the given name, in the current package. You must create an action that generates the directory. The contents of the directory are not directly accessible from Starlark, but can be expanded in an action command with [`Args.add_all()`](../builtins/Args.html#add_all). Only regular files and directories can be in the expanded contents of a declare\_directory. + Declares that the rule or aspect creates a directory with the given name, in the current package. You must create an action that generates the directory. The contents of the directory are not directly accessible from Starlark, but can be expanded in an action command with [`Args.add_all()`](../builtins/Args.html#add_all). Only regular files and directories can be in the expanded contents of a declare\_directory. + ### Parameters -| Parameter | Description | -| --- | --- | -| `filename` | [string](../core/string.mdx); required If no 'sibling' provided, path of the new directory, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). | -| `sibling` | [File](../builtins/File.mdx); or `None`; default is `None` A file that lives in the same directory as the newly declared directory. The file must be in the current package. | +ParameterDescription`filename`[string](../core/string.html); + required + + If no 'sibling' provided, path of the new directory, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). + `sibling`[File](../builtins/File.html); or `None`; + default is `None` + + A file that lives in the same directory as the newly declared directory. The file must be in the current package. + ## declare\_file @@ -49,18 +58,24 @@ Declares that the rule or aspect creates a directory with the given name, in the File actions.declare_file(filename, *, sibling=None) ``` -Declares that the rule or aspect creates a file with the given filename. If `sibling` is not specified, the file name is relative to the package directory, otherwise the file is in the same directory as `sibling`. Files cannot be created outside of the current package. + Declares that the rule or aspect creates a file with the given filename. If `sibling` is not specified, the file name is relative to the package directory, otherwise the file is in the same directory as `sibling`. Files cannot be created outside of the current package. Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned `File` object to the action's construction function. Note that [predeclared output files](https://bazel.build/extending/rules#files) do not need to be (and cannot be) declared using this function. You can obtain their `File` objects from [`ctx.outputs`](../builtins/ctx.html#outputs) instead. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/computed_dependencies/hash.bzl). + ### Parameters -| Parameter | Description | -| --- | --- | -| `filename` | [string](../core/string.mdx); required If no 'sibling' provided, path of the new file, relative to the current package. Otherwise a base name for a file ('sibling' determines a directory). | -| `sibling` | [File](../builtins/File.mdx); or `None`; default is `None` A file that lives in the same directory as the newly created file. The file must be in the current package. | +ParameterDescription`filename`[string](../core/string.html); + required + + If no 'sibling' provided, path of the new file, relative to the current package. Otherwise a base name for a file ('sibling' determines a directory). + `sibling`[File](../builtins/File.html); or `None`; + default is `None` + + A file that lives in the same directory as the newly created file. The file must be in the current package. + ## declare\_symlink @@ -68,14 +83,20 @@ Note that [predeclared output files](https://bazel.build/extending/rules#files) File actions.declare_symlink(filename, *, sibling=None) ``` -Declares that the rule or aspect creates a symlink with the given name in the current package. You must create an action that generates this symlink. Bazel will never dereference this symlink and will transfer it verbatim to sandboxes or remote executors. Symlinks inside tree artifacts are not currently supported. + Declares that the rule or aspect creates a symlink with the given name in the current package. You must create an action that generates this symlink. Bazel will never dereference this symlink and will transfer it verbatim to sandboxes or remote executors. Symlinks inside tree artifacts are not currently supported. + ### Parameters -| Parameter | Description | -| --- | --- | -| `filename` | [string](../core/string.mdx); required If no 'sibling' provided, path of the new symlink, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). | -| `sibling` | [File](../builtins/File.mdx); or `None`; default is `None` A file that lives in the same directory as the newly declared symlink. | +ParameterDescription`filename`[string](../core/string.html); + required + + If no 'sibling' provided, path of the new symlink, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). + `sibling`[File](../builtins/File.html); or `None`; + default is `None` + + A file that lives in the same directory as the newly declared symlink. + ## do\_nothing @@ -83,57 +104,154 @@ Declares that the rule or aspect creates a symlink with the given name in the cu None actions.do_nothing(*, mnemonic, inputs=[]) ``` -Creates an empty action that neither executes a command nor produces any output, but that is useful for inserting 'extra actions'. + Creates an empty action that neither executes a command nor produces any output, but that is useful for inserting 'extra actions'. + ### Parameters -| Parameter | Description | -| --- | --- | -| `mnemonic` | [string](../core/string.mdx); required A one-word description of the action, for example, CppCompile or GoLink. | -| `inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `[]` List of the input files of the action. | +ParameterDescription`mnemonic`[string](../core/string.html); + required + + A one-word description of the action, for example, CppCompile or GoLink. + `inputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; or [depset](../builtins/depset.html); + default is `[]` + + List of the input files of the action. + ## expand\_template ``` -None actions.expand_template(*, template, output, substitutions=\{\}, is_executable=False, computed_substitutions=unbound) +None actions.expand_template(*, template, output, substitutions={}, is_executable=False, computed_substitutions=unbound) ``` -Creates a template expansion action. When the action is executed, it will generate a file based on a template. Parts of the template will be replaced using the `substitutions` dictionary, in the order the substitutions are specified. Whenever a key of the dictionary appears in the template (or a result of a previous substitution), it is replaced with the associated value. There is no special syntax for the keys. You may, for example, use curly braces to avoid conflicts (for example, `\{KEY\}`). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). + Creates a template expansion action. When the action is executed, it will generate a file based on a template. Parts of the template will be replaced using the `substitutions` dictionary, in the order the substitutions are specified. Whenever a key of the dictionary appears in the template (or a result of a previous substitution), it is replaced with the associated value. There is no special syntax for the keys. You may, for example, use curly braces to avoid conflicts (for example, `{KEY}`). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). + ### Parameters -| Parameter | Description | -| --- | --- | -| `template` | [File](../builtins/File.mdx); required The template file, which is a UTF-8 encoded text file. | -| `output` | [File](../builtins/File.mdx); required The output file, which is a UTF-8 encoded text file. | -| `substitutions` | [dict](../core/dict.mdx); default is `\{\}` Substitutions to make when expanding the template. | -| `is_executable` | [bool](../core/bool.mdx); default is `False` Whether the output file should be executable. | -| `computed_substitutions` | [TemplateDict](../builtins/TemplateDict.mdx); default is `unbound` Substitutions to make when expanding the template. | +ParameterDescription`template`[File](../builtins/File.html); + required + + The template file, which is a UTF-8 encoded text file. + `output`[File](../builtins/File.html); + required + + The output file, which is a UTF-8 encoded text file. + `substitutions`[dict](../core/dict.html); + default is `{}` + + Substitutions to make when expanding the template. + `is_executable`[bool](../core/bool.html); + default is `False` + + Whether the output file should be executable. + `computed_substitutions`[TemplateDict](../builtins/TemplateDict.html); + default is `unbound` + + Substitutions to make when expanding the template. + ## map\_directory ``` -None actions.map_directory(*, input_directories, additional_inputs=\{\}, output_directories, tools, additional_params=\{\}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation) +None actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation) ``` -Creates multiple actions based on the files within one or more input directories, to output one or more output directories. + Creates multiple actions based on the files within one or more input directories, to output one or more output directories. + ### Parameters -| Parameter | Description | -| --- | --- | -| `input_directories` | [dict](../core/dict.mdx) of [File](../builtins/File.mdx)s; required A dictionary mapping of strings to input directories, as declared by `ctx.actions.declare_directory()` (only directories are allowed as values here). The values specify the directories that we want expanded to access their files in the implementation function. The keys (strings) act as identifiers to easily reference a specific directory in the implementation function. | -| `additional_inputs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary of mapping of strings to additional inputs (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify any additional inputs that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific input from within the implementation function. | -| `output_directories` | [dict](../core/dict.mdx) of [File](../builtins/File.mdx)s; required A dictionary mapping of strings to output directories, as declared by `ctx.actions.declare_directory()`. The values specify the output directories that we want to generate by the actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific output directory from within the implementation function. | -| `tools` | [dict](../core/dict.mdx); required A dictionary mapping of strings to tools (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify the tools that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific tool from within the implementation function. | -| `additional_params` | [dict](../core/dict.mdx); default is `\{\}` A dictionary mapping of strings to additional parameters (only string, boolean and integer values are allowed here). The values specify any additional parameters that we want to make accessible to the implementation function that could be used to influence its behavior. The keys (strings) act as identifiers to easily reference a specific parameter from within the implementation function. | -| `execution_requirements` | [dict](../core/dict.mdx); or `None`; default is `None` Information for scheduling the created actions. See [tags](./reference/be/common-definitions#common.tags) for useful keys. | -| `exec_group` | [string](../core/string.mdx); or `None`; default is `None` Run the created actions on the given exec group's execution platform. If none, uses the target's default execution platform. | -| `toolchain` | [Label](../builtins/Label.mdx); or [string](../core/string.mdx); or `None`; default is `None` Toolchain type of the executable or tools used by the created actions. 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 created actions execute on the correct execution platform. Note that the rule which creates these actions 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. | -| `use_default_shell_env` | [bool](../core/bool.mdx); default is `False` Whether the created actions should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](./reference/command-line-reference#flag--action_env). If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | -| `env` | [dict](../core/dict.mdx); or `None`; default is `None` Sets the dictionary of environment variables. If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | -| `mnemonic` | [string](../core/string.mdx); or `None`; default is `None` A one-word description of the created actions, for example, CppCompile or GoLink. | -| `implementation` | [function](../core/function.mdx); required A Starlark function that gets called after input directories have been built to generate actions that output files to the specified output directories. This function is passed the following arguments: * `template_ctx` (positional): A [`template_ctx`](../builtins/template_ctx.mdx) object that can be used to create actions. * `input_directories` (keyword-only): A dictionary mapping from the string keys of the `input_directories` argument of `actions.map_directory()` to their values' corresponding [`ExpandedDirectory`](../builtins/File.mdx) objects. * `output_directories` (keyword-only): The value of the `output_directories` argument of `actions.map_directory()`; a dictionary mapping from strings to output directories. * `additional_inputs` (keyword-only): The value of the `additional_inputs` argument of `actions.map_directory()`; a dictionary mapping from strings to input files. * `tools` (keyword-only): The value of the `tools` argument of `actions.map_directory()`; a dictionary mapping from strings to tools. * `additional_params` (keyword-only): The value of the `additional_params` argument of `actions.map_directory()`; a dictionary mapping from strings to strings, booleans, or integers. This function must be top-level, i.e. lambdas and nested functions are not allowed. | +ParameterDescription`input_directories`[dict](../core/dict.html) of [File](../builtins/File.html) s; + required + + A dictionary mapping of strings to input directories, as declared by `ctx.actions.declare_directory()` (only directories are allowed as values here). The values specify the directories that we want expanded to access their files in the implementation function. The keys (strings) act as identifiers to easily reference a specific directory in the implementation function. + `additional_inputs`[dict](../core/dict.html); + default is `{}` + + A dictionary of mapping of strings to additional inputs (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify any additional inputs that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific input from within the implementation function. + `output_directories`[dict](../core/dict.html) of [File](../builtins/File.html) s; + required + + A dictionary mapping of strings to output directories, as declared by `ctx.actions.declare_directory()`. The values specify the output directories that we want to generate by the actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific output directory from within the implementation function. + `tools`[dict](../core/dict.html); + required + + A dictionary mapping of strings to tools (only files, FilesToRunProvider(s) and Depset(s) are allowed here). The values specify the tools that we want to make accessible to actions created by the implementation function. The keys (strings) act as identifiers to easily reference a specific tool from within the implementation function. + `additional_params`[dict](../core/dict.html); + default is `{}` + + A dictionary mapping of strings to additional parameters (only string, boolean and integer values are allowed here). The values specify any additional parameters that we want to make accessible to the implementation function that could be used to influence its behavior. The keys (strings) act as identifiers to easily reference a specific parameter from within the implementation function. + `execution_requirements`[dict](../core/dict.html); or `None`; + default is `None` + + Information for scheduling the created actions. See [tags](/reference/be/common-definitions#common.tags) for useful keys. + `exec_group`[string](../core/string.html); or `None`; + default is `None` + + Run the created actions on the given exec group's execution platform. If none, uses the target's default execution platform. + `toolchain`[Label](../builtins/Label.html); or [string](../core/string.html); or `None`; + default is `None` + +Toolchain type of the executable or tools used by the created actions. + +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 created actions execute on the correct execution platform. + +Note that the rule which creates these actions 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. + +`use_default_shell_env`[bool](../core/bool.html); + default is `False` + + Whether the created actions should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](/reference/command-line-reference#flag--action_env). + +If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. + + +`env`[dict](../core/dict.html); or `None`; + default is `None` + + Sets the dictionary of environment variables. + +If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. + + +`mnemonic`[string](../core/string.html); or `None`; + default is `None` + + A one-word description of the created actions, for example, CppCompile or GoLink. + `implementation`[function](../core/function.html); + required + + A Starlark function that gets called after input directories have been built to generate actions +that output files to the specified output directories. This function is passed the following +arguments: + +- `template_ctx` (positional): A [`template_ctx`](../builtins/template_ctx.html) object that can be used to + create actions. +- `input_directories` (keyword-only): A dictionary mapping from the string keys of + the `input_directories` argument of `actions.map_directory()` to their + values' corresponding [`ExpandedDirectory`](../builtins/File.html) + objects. +- `output_directories` (keyword-only): The value of the + `output_directories` argument of `actions.map_directory()`; a + dictionary mapping from strings to output directories. +- `additional_inputs` (keyword-only): The value of the + `additional_inputs` argument of `actions.map_directory()`; a + dictionary mapping from strings to input files. +- `tools` (keyword-only): The value of the `tools` argument of + `actions.map_directory()`; a dictionary mapping from strings to tools. +- `additional_params` (keyword-only): The value of the + `additional_params` argument of `actions.map_directory()`; a + dictionary mapping from strings to strings, booleans, or integers. + +This function must be top-level, i.e. lambdas and nested functions are not allowed. + + ## run @@ -141,28 +259,117 @@ Creates multiple actions based on the files within one or more input directories 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) ``` -Creates an action that runs an executable. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/actions_run/execute.bzl). + Creates an action that runs an executable. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/actions_run/execute.bzl). + ### Parameters -| Parameter | Description | -| --- | --- | -| `outputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; required List of the output files of the action. | -| `inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `[]` List or depset of the input files of the action. | -| `unused_inputs_list` | [File](../builtins/File.mdx); or `None`; default is `None` File containing list of inputs unused by the action. The content of this file (generally one of the outputs of the action) corresponds to the list of input files that were not used during the whole action execution. Any change in those files must not affect in any way the outputs of the action. | -| `executable` | [File](../builtins/File.mdx); or [string](../core/string.mdx); or [FilesToRunProvider](../providers/FilesToRunProvider.mdx); required The executable file to be called by the action. | -| `tools` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `unbound` List or [`depset`](../builtins/depset.mdx) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. When a list is provided, it can be a heterogenous collection of: * `File`s * `FilesToRunProvider` instances * `depset`s of `File`s `File`s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider`s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. | -| `arguments` | [sequence](../core/list.mdx); default is `[]` Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. | -| `mnemonic` | [string](../core/string.mdx); or `None`; default is `None` A one-word description of the action, for example, CppCompile or GoLink. | -| `progress_message` | [string](../core/string.mdx); or `None`; default is `None` Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain `%\{label\}`, `%\{input\}`, or `%\{output\}` patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | -| `use_default_shell_env` | [bool](../core/bool.mdx); default is `False` Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](./reference/command-line-reference#flag--action_env). If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | -| `env` | [dict](../core/dict.mdx); or `None`; default is `None` Sets the dictionary of environment variables. If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | -| `execution_requirements` | [dict](../core/dict.mdx); or `None`; default is `None` Information for scheduling the action. See [tags](./reference/be/common-definitions#common.tags) for useful keys. | -| `input_manifests` | [sequence](../core/list.mdx); or `None`; default is `None` Legacy argument. Ignored. | -| `exec_group` | [string](../core/string.mdx); or `None`; default is `None` Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. | -| `shadowed_action` | [Action](../builtins/Action.mdx); 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.mdx); or [string](../core/string.mdx); 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. | +ParameterDescription`outputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; + required + + List of the output files of the action. + `inputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; or [depset](../builtins/depset.html); + default is `[]` + + List or depset of the input files of the action. + `unused_inputs_list`[File](../builtins/File.html); or `None`; + default is `None` + + File containing list of inputs unused by the action. + +The content of this file (generally one of the outputs of the action) corresponds to the list of input files that were not used during the whole action execution. Any change in those files must not affect in any way the outputs of the action. + + +`executable`[File](../builtins/File.html); or [string](../core/string.html); or [FilesToRunProvider](../providers/FilesToRunProvider.html); + required + + The executable file to be called by the action. + `tools`[sequence](../core/list.html); or [depset](../builtins/depset.html); + default is `unbound` + + List or [`depset`](../builtins/depset.html) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. + +When a list is provided, it can be a heterogenous collection of: + +- `File` s +- `FilesToRunProvider` instances +- `depset` s of `File` s + +`File` s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider` s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. + +`arguments`[sequence](../core/list.html); + default is `[]` + + Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. + `mnemonic`[string](../core/string.html); or `None`; + default is `None` + + A one-word description of the action, for example, CppCompile or GoLink. + `progress_message`[string](../core/string.html); or `None`; + default is `None` + + Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain `%{label}`, `%{input}`, or `%{output}` patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. + `use_default_shell_env`[bool](../core/bool.html); + default is `False` + + Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](/reference/command-line-reference#flag--action_env). + +If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. + + +`env`[dict](../core/dict.html); or `None`; + default is `None` + + Sets the dictionary of environment variables. + +If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. + + +`execution_requirements`[dict](../core/dict.html); or `None`; + default is `None` + + Information for scheduling the action. See [tags](/reference/be/common-definitions#common.tags) for useful keys. + `input_manifests`[sequence](../core/list.html); or `None`; + default is `None` + + Legacy argument. Ignored. + `exec_group`[string](../core/string.html); or `None`; + default is `None` + + Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. + `shadowed_action`[Action](../builtins/Action.html); + 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.html); or [string](../core/string.html); 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. ## run\_shell @@ -170,27 +377,111 @@ Creates an action that runs an executable. [See example of use](https://github.c 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) ``` -Creates an action that runs a shell command. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/shell_command/rules.bzl). + Creates an action that runs a shell command. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/shell_command/rules.bzl). + ### Parameters -| Parameter | Description | -| --- | --- | -| `outputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; required List of the output files of the action. | -| `inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `[]` List or depset of the input files of the action. | -| `tools` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `unbound` List or [`depset`](../builtins/depset.mdx) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. When a list is provided, it can be a heterogenous collection of: * `File`s * `FilesToRunProvider` instances * `depset`s of `File`s `File`s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider`s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. | -| `arguments` | [sequence](../core/list.mdx); default is `[]` Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as `$1`, `$2`, etc. Note that since Args objects are flattened before indexing, if there is an Args object of unknown size then all subsequent strings will be at unpredictable indices. It may be useful to use `$@` (to retrieve all arguments) in conjunction with Args objects of indeterminate size. In the case where `command` is a list of strings, this parameter may not be used. | -| `mnemonic` | [string](../core/string.mdx); or `None`; default is `None` A one-word description of the action, for example, CppCompile or GoLink. | -| `command` | [string](../core/string.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required Shell command to execute. This may either be a string (preferred) or a sequence of strings **(deprecated)**. If `command` is a string, then it is executed as if by `sh -c <command> "" <arguments>` -- that is, the elements in `arguments` are made available to the command as `$1`, `$2` (or `%1`, `%2` if using Windows batch), etc. If `arguments` contains any [`actions.args()`](#args) objects, their contents are appended one by one to the command line, so `$`*i* can refer to individual strings within an Args object. Note that if an Args object of unknown size is passed as part of `arguments`, then the strings will be at unknown indices; in this case the `$@` shell substitution (retrieve all arguments) may be useful. **(Deprecated)** If `command` is a sequence of strings, the first item is the executable to run and the remaining items are its arguments. If this form is used, the `arguments` parameter must not be supplied. *Note that this form is deprecated and will soon be removed. It is disabled with `--incompatible\_run\_shell\_command\_string`. Use this flag to verify your code is compatible.* Bazel uses the same shell to execute the command as it does for genrules. | -| `progress_message` | [string](../core/string.mdx); or `None`; default is `None` Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain `%\{label\}`, `%\{input\}`, or `%\{output\}` patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | -| `use_default_shell_env` | [bool](../core/bool.mdx); default is `False` Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](./reference/command-line-reference#flag--action_env). If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | -| `env` | [dict](../core/dict.mdx); or `None`; default is `None` Sets the dictionary of environment variables. If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | -| `execution_requirements` | [dict](../core/dict.mdx); or `None`; default is `None` Information for scheduling the action. See [tags](./reference/be/common-definitions#common.tags) for useful keys. | -| `input_manifests` | [sequence](../core/list.mdx); or `None`; default is `None` Legacy argument. Ignored. | -| `exec_group` | [string](../core/string.mdx); or `None`; default is `None` Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. | -| `shadowed_action` | [Action](../builtins/Action.mdx); 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.mdx); or [string](../core/string.mdx); 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. | +ParameterDescription`outputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; + required + + List of the output files of the action. + `inputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; or [depset](../builtins/depset.html); + default is `[]` + + List or depset of the input files of the action. + `tools`[sequence](../core/list.html) of [File](../builtins/File.html) s; or [depset](../builtins/depset.html); + default is `unbound` + + List or [`depset`](../builtins/depset.html) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. + +When a list is provided, it can be a heterogenous collection of: + +- `File` s +- `FilesToRunProvider` instances +- `depset` s of `File` s + +`File` s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider` s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. + +`arguments`[sequence](../core/list.html); + default is `[]` + + Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. + +Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as `$1`, `$2`, etc. Note that since Args objects are flattened before indexing, if there is an Args object of unknown size then all subsequent strings will be at unpredictable indices. It may be useful to use `$@` (to retrieve all arguments) in conjunction with Args objects of indeterminate size. + +In the case where `command` is a list of strings, this parameter may not be used. + + +`mnemonic`[string](../core/string.html); or `None`; + default is `None` + + A one-word description of the action, for example, CppCompile or GoLink. + `command`[string](../core/string.html); or [sequence](../core/list.html) of [string](../core/string.html) s; + required + + Shell command to execute. This may either be a string (preferred) or a sequence of strings **(deprecated)**. + +If `command` is a string, then it is executed as if by `sh -c <command> "" <arguments>` \-\- that is, the elements in `arguments` are made available to the command as `$1`, `$2` (or `%1`, `%2` if using Windows batch), etc. If `arguments` contains any [`actions.args()`](#args) objects, their contents are appended one by one to the command line, so `$` _i_ can refer to individual strings within an Args object. Note that if an Args object of unknown size is passed as part of `arguments`, then the strings will be at unknown indices; in this case the `$@` shell substitution (retrieve all arguments) may be useful. + +**(Deprecated)** If `command` is a sequence of strings, the first item is the executable to run and the remaining items are its arguments. If this form is used, the `arguments` parameter must not be supplied. _Note that this form is deprecated and will soon be removed. It is disabled with \`--incompatible\_run\_shell\_command\_string\`. Use this flag to verify your code is compatible._ + +Bazel uses the same shell to execute the command as it does for genrules. + + +`progress_message`[string](../core/string.html); or `None`; + default is `None` + + Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain `%{label}`, `%{input}`, or `%{output}` patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. + `use_default_shell_env`[bool](../core/bool.html); + default is `False` + + Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](/reference/command-line-reference#flag--action_env). + +If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. + + +`env`[dict](../core/dict.html); or `None`; + default is `None` + + Sets the dictionary of environment variables. + +If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. + + +`execution_requirements`[dict](../core/dict.html); or `None`; + default is `None` + + Information for scheduling the action. See [tags](/reference/be/common-definitions#common.tags) for useful keys. + `input_manifests`[sequence](../core/list.html); or `None`; + default is `None` + + Legacy argument. Ignored. + `exec_group`[string](../core/string.html); or `None`; + default is `None` + + Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. + `shadowed_action`[Action](../builtins/Action.html); + 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.html); or [string](../core/string.html); 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. ## symlink @@ -198,7 +489,7 @@ Creates an action that runs a shell command. [See example of use](https://github None actions.symlink(*, output, target_file=None, target_path=None, is_executable=False, progress_message=None) ``` -Creates an action that writes a symlink in the file system. + Creates an action that writes a symlink in the file system. This function must be called with exactly one of `target_file` or `target_path` specified. @@ -208,13 +499,30 @@ Otherwise, when you use `target_path`, declare `output` with [`declare_symlink() ### Parameters -| Parameter | Description | -| --- | --- | -| `output` | [File](../builtins/File.mdx); required The output of this action. | -| `target_file` | [File](../builtins/File.mdx); or `None`; default is `None` The File that the output symlink will point to. | -| `target_path` | [string](../core/string.mdx); or `None`; default is `None` The exact path that the output symlink will point to. No normalization or other processing is applied. | -| `is_executable` | [bool](../core/bool.mdx); default is `False` May only be used with `target_file`, not `target_path`. If true, when the action is executed, the `target_file`'s path is checked to confirm that it is executable, and an error is reported if it is not. Setting `is_executable` to False does not mean the target is not executable, just that no verification is done. This feature does not make sense for `target_path` because dangling symlinks might not exist at build time. | -| `progress_message` | [string](../core/string.mdx); or `None`; default is `None` Progress message to show to the user during the build. | +ParameterDescription`output`[File](../builtins/File.html); + required + + The output of this action. + `target_file`[File](../builtins/File.html); or `None`; + default is `None` + + The File that the output symlink will point to. + `target_path`[string](../core/string.html); or `None`; + default is `None` + + The exact path that the output symlink will point to. No normalization or other processing is applied. + `is_executable`[bool](../core/bool.html); + default is `False` + + May only be used with `target_file`, not `target_path`. If true, when the action is executed, the `target_file`'s path is checked to confirm that it is executable, and an error is reported if it is not. Setting `is_executable` to False does not mean the target is not executable, just that no verification is done. + +This feature does not make sense for `target_path` because dangling symlinks might not exist at build time. + +`progress_message`[string](../core/string.html); or `None`; + default is `None` + + Progress message to show to the user during the build. + ## template\_dict @@ -222,7 +530,9 @@ Otherwise, when you use `target_path`, declare `output` with [`declare_symlink() TemplateDict actions.template_dict() ``` -Returns a TemplateDict object for memory-efficient template expansion. + Returns a TemplateDict object for memory-efficient template expansion. + + ## write @@ -230,13 +540,24 @@ Returns a TemplateDict object for memory-efficient template expansion. None actions.write(output, content, is_executable=False, *, mnemonic=None) ``` -Creates a file write action. When the action is executed, it will write the given content to a file. This is used to generate files using information available in the analysis phase. If the file is large and with a lot of static content, consider using [`expand_template`](#expand_template). + Creates a file write action. When the action is executed, it will write the given content to a file. This is used to generate files using information available in the analysis phase. If the file is large and with a lot of static content, consider using [`expand_template`](#expand_template). + ### Parameters -| Parameter | Description | -| --- | --- | -| `output` | [File](../builtins/File.mdx); required The output file. | -| `content` | [string](../core/string.mdx); or [Args](../builtins/Args.mdx); required the contents of the file. May be a either a string or an [`actions.args()`](#args) object. | -| `is_executable` | [bool](../core/bool.mdx); default is `False` Whether the output file should be executable. | -| `mnemonic` | [string](../core/string.mdx); or `None`; default is `None` A one-word description of the action, for example, CppCompile or GoLink. | \ No newline at end of file +ParameterDescription`output`[File](../builtins/File.html); + required + + The output file. + `content`[string](../core/string.html); or [Args](../builtins/Args.html); + required + + the contents of the file. May be a either a string or an [`actions.args()`](#args) object. + `is_executable`[bool](../core/bool.html); + default is `False` + + Whether the output file should be executable. + `mnemonic`[string](../core/string.html); or `None`; + default is `None` + + A one-word description of the action, for example, CppCompile or GoLink. diff --git a/rules/lib/builtins/apple_platform.mdx b/rules/lib/builtins/apple_platform.mdx index 0a7ae8d..5250c30 100644 --- a/rules/lib/builtins/apple_platform.mdx +++ b/rules/lib/builtins/apple_platform.mdx @@ -1,35 +1,37 @@ --- -title: 'apple_platform' +title: 'apple\_platform' --- + Corresponds to Xcode's notion of a platform as would be found in `Xcode.app/Contents/Developer/Platforms`. Each platform represents an Apple platform type (such as iOS or tvOS) combined with one or more related CPU architectures. For example, the iOS simulator platform supports `x86_64` and `i386` architectures. -Specific instances of this type can be retrieved from the fields of the [apple\_common.platform](../toplevel/apple_common.html#platform) struct: +Specific instances of this type can be retrieved from the fields of the [apple\_common.platform](../toplevel/apple_common.html#platform) struct: -* `apple_common.platform.ios_device` -* `apple_common.platform.ios_simulator` -* `apple_common.platform.macos` -* `apple_common.platform.tvos_device` -* `apple_common.platform.tvos_simulator` -* `apple_common.platform.watchos_device` -* `apple_common.platform.watchos_simulator` +- `apple_common.platform.ios_device` +- `apple_common.platform.ios_simulator` +- `apple_common.platform.macos` +- `apple_common.platform.tvos_device` +- `apple_common.platform.tvos_simulator` +- `apple_common.platform.watchos_device` +- `apple_common.platform.watchos_simulator` -More commonly, however, the [apple](../fragments/apple.mdx) configuration fragment has fields/methods that allow rules to determine the platform for which a target is being built. +More commonly, however, the [apple](../fragments/apple.html) configuration fragment has fields/methods that allow rules to determine the platform for which a target is being built. -Example: +Example: ``` p = apple_common.platform.ios_device print(p.name_in_plist) # 'iPhoneOS' + ``` ## Members -* [is\_device](#is_device) -* [name](#name) -* [name\_in\_plist](#name_in_plist) -* [platform\_type](#platform_type) +- [is\_device](#is_device) +- [name](#name) +- [name\_in\_plist](#name_in_plist) +- [platform\_type](#platform_type) ## is\_device @@ -37,7 +39,9 @@ print(p.name_in_plist) # 'iPhoneOS' bool apple_platform.is_device ``` -Returns `True` if this platform is a device platform or `False` if it is a simulator platform. + Returns `True` if this platform is a device platform or `False` if it is a simulator platform. + + ## name @@ -45,7 +49,9 @@ Returns `True` if this platform is a device platform or `False` if it is a simul string apple_platform.name ``` -Returns the name aka starlarkKey of this platform. + Returns the name aka starlarkKey of this platform. + + ## name\_in\_plist @@ -53,13 +59,16 @@ Returns the name aka starlarkKey of this platform. string apple_platform.name_in_plist ``` -The name of the platform as it appears in the `CFBundleSupportedPlatforms` entry of an Info.plist file and in Xcode's platforms directory, without the extension (for example, `iPhoneOS` or `iPhoneSimulator`). + The name of the platform as it appears in the `CFBundleSupportedPlatforms` entry of an Info.plist file and in Xcode's platforms directory, without the extension (for example, `iPhoneOS` or `iPhoneSimulator`). + This name, when converted to lowercase (e.g., `iphoneos`, `iphonesimulator`), can be passed to Xcode's command-line tools like `ibtool` and `actool` when they expect a platform name. + + ## platform\_type ``` string apple_platform.platform_type ``` -Returns the platform type of this platform. \ No newline at end of file + Returns the platform type of this platform. diff --git a/rules/lib/builtins/bazel_module.mdx b/rules/lib/builtins/bazel_module.mdx index f71a893..bfcc129 100644 --- a/rules/lib/builtins/bazel_module.mdx +++ b/rules/lib/builtins/bazel_module.mdx @@ -1,16 +1,17 @@ --- -title: 'bazel_module' +title: 'bazel\_module' --- + Represents a Bazel module in the external dependency graph. ## Members -* [is\_root](#is_root) -* [name](#name) -* [tags](#tags) -* [version](#version) +- [is\_root](#is_root) +- [name](#name) +- [tags](#tags) +- [version](#version) ## is\_root @@ -18,7 +19,9 @@ Represents a Bazel module in the external dependency graph. bool bazel_module.is_root ``` -Whether this module is the root module. + Whether this module is the root module. + + ## name @@ -26,7 +29,9 @@ Whether this module is the root module. string bazel_module.name ``` -The name of the module. + The name of the module. + + ## tags @@ -34,7 +39,9 @@ The name of the module. bazel_module_tags bazel_module.tags ``` -The tags in the module related to the module extension currently being processed. + The tags in the module related to the module extension currently being processed. + + ## version @@ -42,4 +49,4 @@ The tags in the module related to the module extension currently being processed string bazel_module.version ``` -The version of the module. \ No newline at end of file + The version of the module. diff --git a/rules/lib/builtins/bazel_module_tags.mdx b/rules/lib/builtins/bazel_module_tags.mdx index aa093a8..7c9bcda 100644 --- a/rules/lib/builtins/bazel_module_tags.mdx +++ b/rules/lib/builtins/bazel_module_tags.mdx @@ -1,7 +1,9 @@ --- -title: 'bazel_module_tags' +title: 'bazel\_module\_tags' --- + Contains the tags in a module for the module extension currently being processed. This object has a field for each tag class of the extension, and the value of the field is a list containing an object for each tag instance. This "tag instance" object in turn has a field for each attribute of the tag class. -When passed as positional arguments to `print()` or `fail()`, tag instance objects turn into a meaningful string representation of the form "'install' tag at /home/user/workspace/MODULE.bazel:3:4". This can be used to construct error messages that point to the location of the tag in the module file, e.g. `fail("Conflict between", tag1, "and", tag2)`. \ No newline at end of file + +When passed as positional arguments to `print()` or `fail()`, tag instance objects turn into a meaningful string representation of the form "'install' tag at /home/user/workspace/MODULE.bazel:3:4". This can be used to construct error messages that point to the location of the tag in the module file, e.g. `fail("Conflict between", tag1, "and", tag2)`. diff --git a/rules/lib/builtins/configuration.mdx b/rules/lib/builtins/configuration.mdx index 5ad6b28..8a58ff7 100644 --- a/rules/lib/builtins/configuration.mdx +++ b/rules/lib/builtins/configuration.mdx @@ -3,15 +3,16 @@ title: 'configuration' --- + This object holds information about the environment in which the build is running. See the [Rules page](https://bazel.build/extending/rules#configurations) for more on the general concept of configurations. ## Members -* [coverage\_enabled](#coverage_enabled) -* [default\_shell\_env](#default_shell_env) -* [host\_path\_separator](#host_path_separator) -* [short\_id](#short_id) -* [test\_env](#test_env) +- [coverage\_enabled](#coverage_enabled) +- [default\_shell\_env](#default_shell_env) +- [host\_path\_separator](#host_path_separator) +- [short\_id](#short_id) +- [test\_env](#test_env) ## coverage\_enabled @@ -19,7 +20,9 @@ This object holds information about the environment in which the build is runnin bool configuration.coverage_enabled ``` -A boolean that tells whether code coverage is enabled for this run. Note that this does not compute whether a specific rule should be instrumented for code coverage data collection. For that, see the [`ctx.coverage_instrumented`](../builtins/ctx.html#coverage_instrumented) function. + A boolean that tells whether code coverage is enabled for this run. Note that this does not compute whether a specific rule should be instrumented for code coverage data collection. For that, see the [`ctx.coverage_instrumented`](../builtins/ctx.html#coverage_instrumented) function. + + ## default\_shell\_env @@ -27,7 +30,9 @@ A boolean that tells whether code coverage is enabled for this run. Note that th dict configuration.default_shell_env ``` -A dictionary representing the static local shell environment. It maps variables to their values (strings). + A dictionary representing the static local shell environment. It maps variables to their values (strings). + + ## host\_path\_separator @@ -35,7 +40,9 @@ A dictionary representing the static local shell environment. It maps variables string configuration.host_path_separator ``` -Returns the separator for PATH environment variable, which is ':' on Unix. + Returns the separator for PATH environment variable, which is ':' on Unix. + + ## short\_id @@ -43,16 +50,28 @@ Returns the separator for PATH environment variable, which is ':' on Unix. string configuration.short_id ``` -A short identifier for this configuration understood by the `config` and query subcommands. + A short identifier for this configuration understood by the `config` and query subcommands. Use this to distinguish different configurations for the same target in a way that is friendly to humans and tool usage, for example in an aspect used by an IDE. Keep in mind the following caveats: -* The value may differ across Bazel versions, including patch releases.* The value encodes the value of **every** flag, including those that aren't otherwise relevant for the current target and may thus invalidate caches more frequently. +- The value may differ across Bazel versions, including patch releases. +- The value encodes the value of **every** flag, including those that aren't otherwise relevant for the current target and may thus invalidate caches more frequently. + + + + + ## test\_env + + + + + + ``` + dict configuration.test_env + ``` + + - ## test\_env - ``` - dict configuration.test_env - ``` - A dictionary containing user-specified test environment variables and their values, as set by the --test\_env options. DO NOT USE! This is not the complete environment! \ No newline at end of file + A dictionary containing user-specified test environment variables and their values, as set by the --test\_env options. DO NOT USE! This is not the complete environment! diff --git a/rules/lib/builtins/ctx.mdx b/rules/lib/builtins/ctx.mdx index bb7d85d..a990dde 100644 --- a/rules/lib/builtins/ctx.mdx +++ b/rules/lib/builtins/ctx.mdx @@ -3,6 +3,7 @@ title: 'ctx' --- + A context object that is passed to the implementation function for a rule or aspect. It provides access to the information and methods needed to analyze the current target. In particular, it lets the implementation function access the current target's label, attributes, configuration, and the providers of its dependencies. It has methods for declaring output files and the actions that produce them. @@ -11,39 +12,39 @@ Context objects essentially live for the duration of the call to the implementat ## Members -* [actions](#actions) -* [aspect\_ids](#aspect_ids) -* [attr](#attr) -* [bin\_dir](#bin_dir) -* [build\_file\_path](#build_file_path) -* [build\_setting\_value](#build_setting_value) -* [configuration](#configuration) -* [coverage\_instrumented](#coverage_instrumented) -* [created\_actions](#created_actions) -* [disabled\_features](#disabled_features) -* [exec\_groups](#exec_groups) -* [executable](#executable) -* [expand\_location](#expand_location) -* [expand\_make\_variables](#expand_make_variables) -* [features](#features) -* [file](#file) -* [files](#files) -* [fragments](#fragments) -* [genfiles\_dir](#genfiles_dir) -* [info\_file](#info_file) -* [label](#label) -* [outputs](#outputs) -* [resolve\_command](#resolve_command) -* [resolve\_tools](#resolve_tools) -* [rule](#rule) -* [runfiles](#runfiles) -* [split\_attr](#split_attr) -* [super](#super) -* [target\_platform\_has\_constraint](#target_platform_has_constraint) -* [toolchains](#toolchains) -* [var](#var) -* [version\_file](#version_file) -* [workspace\_name](#workspace_name) +- [actions](#actions) +- [aspect\_ids](#aspect_ids) +- [attr](#attr) +- [bin\_dir](#bin_dir) +- [build\_file\_path](#build_file_path) +- [build\_setting\_value](#build_setting_value) +- [configuration](#configuration) +- [coverage\_instrumented](#coverage_instrumented) +- [created\_actions](#created_actions) +- [disabled\_features](#disabled_features) +- [exec\_groups](#exec_groups) +- [executable](#executable) +- [expand\_location](#expand_location) +- [expand\_make\_variables](#expand_make_variables) +- [features](#features) +- [file](#file) +- [files](#files) +- [fragments](#fragments) +- [genfiles\_dir](#genfiles_dir) +- [info\_file](#info_file) +- [label](#label) +- [outputs](#outputs) +- [resolve\_command](#resolve_command) +- [resolve\_tools](#resolve_tools) +- [rule](#rule) +- [runfiles](#runfiles) +- [split\_attr](#split_attr) +- [super](#super) +- [target\_platform\_has\_constraint](#target_platform_has_constraint) +- [toolchains](#toolchains) +- [var](#var) +- [version\_file](#version_file) +- [workspace\_name](#workspace_name) ## actions @@ -51,7 +52,9 @@ Context objects essentially live for the duration of the call to the implementat actions ctx.actions ``` -Contains methods for declaring output files and the actions that produce them. + Contains methods for declaring output files and the actions that produce them. + + ## aspect\_ids @@ -59,7 +62,9 @@ Contains methods for declaring output files and the actions that produce them. list ctx.aspect_ids ``` -A list of ids for all aspects applied to the target. Only available in aspect implementation functions. + A list of ids for all aspects applied to the target. Only available in aspect implementation functions. + + ## attr @@ -67,7 +72,9 @@ A list of ids for all aspects applied to the target. Only available in aspect im struct ctx.attr ``` -A struct to access the values of the [attributes](https://bazel.build/extending/rules#attributes). The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the [`attrs` dict](../globals/bzl.html#rule.attrs) provided to the [`rule` function](../globals/bzl.html#rule). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl). + A struct to access the values of the [attributes](https://bazel.build/extending/rules#attributes). The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the [`attrs` dict](../globals/bzl.html#rule.attrs) provided to the [`rule` function](../globals/bzl.html#rule). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl). + + ## bin\_dir @@ -75,7 +82,9 @@ A struct to access the values of the [attributes](https://bazel.build/extending/ root ctx.bin_dir ``` -The root corresponding to bin directory. + The root corresponding to bin directory. + + ## build\_file\_path @@ -83,7 +92,9 @@ The root corresponding to bin directory. string ctx.build_file_path ``` -Deprecated: Use `ctx.label.package + '/BUILD'`. The path to the BUILD file for this rule, relative to the source root. + Deprecated: Use `ctx.label.package + '/BUILD'`. The path to the BUILD file for this rule, relative to the source root. + + ## build\_setting\_value @@ -91,7 +102,9 @@ Deprecated: Use `ctx.label.package + '/BUILD'`. The path to the BUILD file for t unknown ctx.build_setting_value ``` -Value of the build setting represented by the current target. If this isn't the context for an instance of a rule that sets the [`build_setting`](https://bazel.build/extending/config#rule-parameter) attribute, reading this is an error. + Value of the build setting represented by the current target. If this isn't the context for an instance of a rule that sets the [`build_setting`](https://bazel.build/extending/config#rule-parameter) attribute, reading this is an error. + + ## configuration @@ -99,7 +112,9 @@ Value of the build setting represented by the current target. If this isn't the configuration ctx.configuration ``` -The default configuration. See the [configuration](../builtins/configuration.mdx) type for more details. + The default configuration. See the [configuration](../builtins/configuration.html) type for more details. + + ## coverage\_instrumented @@ -107,13 +122,16 @@ The default configuration. See the [configuration](../builtins/configuration.mdx bool ctx.coverage_instrumented(target=None) ``` -Returns whether code coverage instrumentation should be generated when performing compilation actions for this rule or, if `target` is provided, the rule specified by that Target. (If a non-rule or a Starlark rule Target is provided, this returns False.) Checks if the sources of the current rule (if no Target is provided) or the sources of Target should be instrumented based on the --instrumentation\_filter and --instrument\_test\_targets config settings. This differs from `coverage_enabled` in the [configuration](../builtins/configuration.mdx), which notes whether coverage data collection is enabled for the entire run, but not whether a specific target should be instrumented. + Returns whether code coverage instrumentation should be generated when performing compilation actions for this rule or, if `target` is provided, the rule specified by that Target. (If a non-rule or a Starlark rule Target is provided, this returns False.) Checks if the sources of the current rule (if no Target is provided) or the sources of Target should be instrumented based on the --instrumentation\_filter and --instrument\_test\_targets config settings. This differs from `coverage_enabled` in the [configuration](../builtins/configuration.html), which notes whether coverage data collection is enabled for the entire run, but not whether a specific target should be instrumented. + ### Parameters -| Parameter | Description | -| --- | --- | -| `target` | [Target](../builtins/Target.mdx); or `None`; default is `None` A Target specifying a rule. If not provided, defaults to the current rule. | +ParameterDescription`target`[Target](../builtins/Target.html); or `None`; + default is `None` + + A Target specifying a rule. If not provided, defaults to the current rule. + ## created\_actions @@ -121,17 +139,21 @@ Returns whether code coverage instrumentation should be generated when performin StarlarkValue ctx.created_actions() ``` -For rules with [\_skylark\_testable](../globals/bzl.html#rule._skylark_testable) set to `True`, this returns an `Actions` provider representing all actions created so far for the current rule. For all other rules, returns `None`. Note that the provider is not updated when subsequent actions are created, so you will have to call this function again if you wish to inspect them. - + For rules with [\_skylark\_testable](../globals/bzl.html#rule._skylark_testable) set to `True`, this returns an `Actions` provider representing all actions created so far for the current rule. For all other rules, returns `None`. Note that the provider is not updated when subsequent actions are created, so you will have to call this function again if you wish to inspect them. + This is intended to help write tests for rule-implementation helper functions, which may take in a `ctx` object and create actions on it. + + ## disabled\_features ``` list ctx.disabled_features ``` -The set of features that are explicitly disabled by the user for this rule. + The set of features that are explicitly disabled by the user for this rule. + + ## exec\_groups @@ -139,7 +161,9 @@ The set of features that are explicitly disabled by the user for this rule. ExecGroupCollection ctx.exec_groups ``` -A collection of the execution groups available for this rule, indexed by their name. Access with `ctx.exec_groups[name_of_group]`. + A collection of the execution groups available for this rule, indexed by their name. Access with `ctx.exec_groups[name_of_group]`. + + ## executable @@ -147,7 +171,9 @@ A collection of the execution groups available for this rule, indexed by their n struct ctx.executable ``` -A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.mdx) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). + A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). + + ## expand\_location @@ -155,20 +181,27 @@ A `struct` containing executable files defined in [label type attributes](../top string ctx.expand_location(input, targets=[]) ``` -Expands all `$(location ...)` templates in the given string by replacing `$(location //x)` with the path of the output file of target //x. Expansion only works for labels that point to direct dependencies of this rule or that are explicitly listed in the optional argument `targets`. - -`$(location ...)` will cause an error if the referenced target has multiple outputs. In this case, please use `$(locations ...)` since it produces a space-separated list of output paths. It can be safely used for a single output file, too. - + Expands all `$(location ...)` templates in the given string by replacing `$(location //x)` with the path of the output file of target //x. Expansion only works for labels that point to direct dependencies of this rule or that are explicitly listed in the optional argument `targets`. + +`$(location ...)` will cause an error if the referenced target has multiple outputs. In this case, please use `$(locations ...)` since it produces a space-separated list of output paths. It can be safely used for a single output file, too. + This function is useful to let the user specify a command in a BUILD file (like for `genrule`). In other cases, it is often better to manipulate labels directly. + ### Parameters -| Parameter | Description | -| --- | --- | -| `input` | [string](../core/string.mdx); required String to be expanded. | -| `targets` | [sequence](../core/list.mdx) of [Target](../builtins/Target.mdx)s; default is `[]` List of targets for additional lookup information. These are expanded as follows: A target with a single file in `DefaultInfo.files` expands to that file. Other targets expand to their `DefaultInfo.executable` file if set and if `--incompatible_locations_prefers_executable` is enabled, otherwise they expand to `DefaultInfo.files`. | +ParameterDescription`input`[string](../core/string.html); + required + + String to be expanded. + `targets`[sequence](../core/list.html) of [Target](../builtins/Target.html) s; + default is `[]` + + List of targets for additional lookup information. These are expanded as follows: A target with a single file in `DefaultInfo.files` expands to that file. Other targets expand to their `DefaultInfo.executable` file if set and if `--incompatible_locations_prefers_executable` is enabled, otherwise they expand to `DefaultInfo.files`. + + May return `None`. + -May return `None`. ## expand\_make\_variables @@ -176,23 +209,34 @@ May return `None`. string ctx.expand_make_variables(attribute_name, command, additional_substitutions) ``` -**Deprecated.** Use [ctx.var](../builtins/ctx.html#var) to access the variables instead. + **Deprecated.** Use [ctx.var](../builtins/ctx.html#var) to access the variables instead. + Returns a string after expanding all references to "Make variables". The variables must have the following format: `$(VAR_NAME)`. Also, `$$VAR_NAME` expands to `$VAR_NAME`. Examples: ``` -ctx.expand_make_variables("cmd", "$(MY_VAR)", \{"MY_VAR": "Hi"\}) # == "Hi" -ctx.expand_make_variables("cmd", "$$PWD", \{\}) # == "$PWD" +ctx.expand_make_variables("cmd", "$(MY_VAR)", {"MY_VAR": "Hi"}) # == "Hi" +ctx.expand_make_variables("cmd", "$$PWD", {}) # == "$PWD" + ``` Additional variables may come from other places, such as configurations. Note that this function is experimental. + ### Parameters -| Parameter | Description | -| --- | --- | -| `attribute_name` | [string](../core/string.mdx); required | -| `command` | [string](../core/string.mdx); required The expression to expand. It can contain references to "Make variables". | -| `additional_substitutions` | [dict](../core/dict.mdx); required Additional substitutions to make beyond the default make variables. | +ParameterDescription`attribute_name`[string](../core/string.html); + required + + The attribute name. Used for error reporting. + `command`[string](../core/string.html); + required + + The expression to expand. It can contain references to "Make variables". + `additional_substitutions`[dict](../core/dict.html); + required + + Additional substitutions to make beyond the default make variables. + ## features @@ -200,7 +244,9 @@ Additional variables may come from other places, such as configurations. Note th list ctx.features ``` -The set of features that are explicitly enabled by the user for this rule. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/features/rule.bzl). + The set of features that are explicitly enabled by the user for this rule. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/features/rule.bzl). + + ## file @@ -208,27 +254,31 @@ The set of features that are explicitly enabled by the user for this rule. [See struct ctx.file ``` -A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.mdx) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: + A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: ``` -list(ctx.attr.\<ATTR\>.files)[0] +list(ctx.attr.<ATTR>.files)[0] ``` In other words, use `file` to access the (singular) [default output](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). + + ## files ``` struct ctx.files ``` -A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.mdx)s. It is a shortcut for: + A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.html) s. It is a shortcut for: ``` -[f for t in ctx.attr.\<ATTR\> for f in t.files] +[f for t in ctx.attr.<ATTR> for f in t.files] ``` -In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). + In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). + + ## fragments @@ -236,7 +286,9 @@ In other words, use `files` to access the [default outputs](https://bazel.build fragments ctx.fragments ``` -Allows access to configuration fragments in target configuration. + Allows access to configuration fragments in target configuration. + + ## genfiles\_dir @@ -244,7 +296,9 @@ Allows access to configuration fragments in target configuration. root ctx.genfiles_dir ``` -The root corresponding to genfiles directory. + The root corresponding to genfiles directory. + + ## info\_file @@ -252,7 +306,9 @@ The root corresponding to genfiles directory. File ctx.info_file ``` -The file that is used to hold the non-volatile workspace status for the current build request. See documentation for --workspace\_status\_command for more information. + The file that is used to hold the non-volatile workspace status for the current build request. See documentation for --workspace\_status\_command for more information. + + ## label @@ -260,7 +316,9 @@ The file that is used to hold the non-volatile workspace status for the current Label ctx.label ``` -The label of the target currently being analyzed. + The label of the target currently being analyzed. + + ## outputs @@ -268,34 +326,59 @@ The label of the target currently being analyzed. structure ctx.outputs ``` -A pseudo-struct containing all the predeclared output files, represented by [`File`](../builtins/File.mdx) objects. See the [Rules page](https://bazel.build/extending/rules#files) for more information and examples. + A pseudo-struct containing all the predeclared output files, represented by [`File`](../builtins/File.html) objects. See the [Rules page](https://bazel.build/extending/rules#files) for more information and examples. This field does not exist on aspect contexts, since aspects do not have predeclared outputs. The fields of this object are defined as follows. It is an error if two outputs produce the same field name or have the same label. -* If the rule declares an [`outputs`](../globals/bzl.html#rule.outputs) dict, then for every entry in the dict, there is a field whose name is the key and whose value is the corresponding `File`.* For every attribute of type [`attr.output`](../toplevel/attr.html#output) that the rule declares, there is a field whose name is the attribute's name. If the target specified a label for that attribute, then the field value is the corresponding `File`; otherwise the field value is `None`.* For every attribute of type [`attr.output_list`](../toplevel/attr.html#output_list) that the rule declares, there is a field whose name is the attribute's name. The field value is a list of `File` objects corresponding to the labels given for that attribute in the target, or an empty list if the attribute was not specified in the target.* **(Deprecated)** If the rule is marked [`executable`](../globals/bzl.html#rule.executable) or [`test`](../globals/bzl.html#rule.test), there is a field named `"executable"`, which is the default executable. It is recommended that instead of using this, you pass another file (either predeclared or not) to the `executable` arg of [`DefaultInfo`](../providers/DefaultInfo.mdx). +- If the rule declares an [`outputs`](../globals/bzl.html#rule.outputs) dict, then for every entry in the dict, there is a field whose name is the key and whose value is the corresponding `File`. +- For every attribute of type [`attr.output`](../toplevel/attr.html#output) that the rule declares, there is a field whose name is the attribute's name. If the target specified a label for that attribute, then the field value is the corresponding `File`; otherwise the field value is `None`. +- For every attribute of type [`attr.output_list`](../toplevel/attr.html#output_list) that the rule declares, there is a field whose name is the attribute's name. The field value is a list of `File` objects corresponding to the labels given for that attribute in the target, or an empty list if the attribute was not specified in the target. +- **(Deprecated)** If the rule is marked [`executable`](../globals/bzl.html#rule.executable) or [`test`](../globals/bzl.html#rule.test), there is a field named `"executable"`, which is the default executable. It is recommended that instead of using this, you pass another file (either predeclared or not) to the `executable` arg of [`DefaultInfo`](../providers/DefaultInfo.html). ## resolve\_command ``` -tuple ctx.resolve_command(*, command='', attribute=None, expand_locations=False, make_variables=None, tools=[], label_dict=\{\}, execution_requirements=\{\}) +tuple ctx.resolve_command(*, command='', attribute=None, expand_locations=False, make_variables=None, tools=[], label_dict={}, execution_requirements={}) ``` -*(Experimental)* Returns a tuple `(inputs, command, empty list)` of the list of resolved inputs and the argv list for the resolved command both of them suitable for passing as the same-named arguments of the `ctx.action` method. + _(Experimental)_ Returns a tuple `(inputs, command, empty list)` of the list of resolved inputs and the argv list for the resolved command both of them suitable for passing as the same-named arguments of the `ctx.action` method. + **Note for Windows users**: this method requires Bash (MSYS2). Consider using `resolve_tools()` instead (if that fits your needs). The empty list is returned as the third member of the tuple for backwards compatibility. + ### Parameters -| Parameter | Description | -| --- | --- | -| `command` | [string](../core/string.mdx); default is `''` Command to resolve. | -| `attribute` | [string](../core/string.mdx); or `None`; default is `None` Name of the associated attribute for which to issue an error, or None. | -| `expand_locations` | [bool](../core/bool.mdx); default is `False` Shall we expand $(location) variables? See [ctx.expand\_location()](#expand_location) for more details. | -| `make_variables` | [dict](../core/dict.mdx); or `None`; default is `None` Make variables to expand, or None. | -| `tools` | [sequence](../core/list.mdx) of [Target](../builtins/Target.mdx)s; default is `[]` List of tools (list of targets). | -| `label_dict` | [dict](../core/dict.mdx); default is `\{\}` Dictionary of resolved labels and the corresponding list of Files (a dict of Label : list of Files). | -| `execution_requirements` | [dict](../core/dict.mdx); default is `\{\}` Information for scheduling the action to resolve this command. See [tags](./reference/be/common-definitions#common.tags) for useful keys. | +ParameterDescription`command`[string](../core/string.html); + default is `''` + + Command to resolve. + `attribute`[string](../core/string.html); or `None`; + default is `None` + + Name of the associated attribute for which to issue an error, or None. + `expand_locations`[bool](../core/bool.html); + default is `False` + + Shall we expand $(location) variables? See [ctx.expand\_location()](#expand_location) for more details. + `make_variables`[dict](../core/dict.html); or `None`; + default is `None` + + Make variables to expand, or None. + `tools`[sequence](../core/list.html) of [Target](../builtins/Target.html) s; + default is `[]` + + List of tools (list of targets). + `label_dict`[dict](../core/dict.html); + default is `{}` + + Dictionary of resolved labels and the corresponding list of Files (a dict of Label : list of Files). + `execution_requirements`[dict](../core/dict.html); + default is `{}` + + Information for scheduling the action to resolve this command. See [tags](/reference/be/common-definitions#common.tags) for useful keys. + ## resolve\_tools @@ -303,15 +386,18 @@ tuple ctx.resolve_command(*, command='', attribute=None, expand_locations=False, tuple ctx.resolve_tools(*, tools=[]) ``` -Returns a tuple `(inputs, empty list)` of the depset of resolved inputs required to run the tools, suitable for passing as the same-named argument of the `ctx.actions.run` and `ctx.actions.run_shell` methods. - + Returns a tuple `(inputs, empty list)` of the depset of resolved inputs required to run the tools, suitable for passing as the same-named argument of the `ctx.actions.run` and `ctx.actions.run_shell` methods. + In contrast to `ctx.resolve_command`, this method does not require that Bash be installed on the machine, so it's suitable for rules built on Windows. The empty list is returned as part of the tuple for backward compatibility. + ### Parameters -| Parameter | Description | -| --- | --- | -| `tools` | [sequence](../core/list.mdx) of [Target](../builtins/Target.mdx)s; default is `[]` List of tools (list of targets). | +ParameterDescription`tools`[sequence](../core/list.html) of [Target](../builtins/Target.html) s; + default is `[]` + + List of tools (list of targets). + ## rule @@ -319,26 +405,54 @@ In contrast to `ctx.resolve_command`, this method does not require that Bash be rule_attributes ctx.rule ``` -Rule attributes descriptor for the rule that the aspect is applied to. Only available in aspect implementation functions. + Rule attributes descriptor for the rule that the aspect is applied to. Only available in aspect implementation functions. + + ## runfiles ``` -runfiles ctx.runfiles(files=[], transitive_files=None, collect_data=False, collect_default=False, symlinks=\{\}, root_symlinks=\{\}) +runfiles ctx.runfiles(files=[], transitive_files=None, collect_data=False, collect_default=False, symlinks={}, root_symlinks={}) ``` -Creates a runfiles object. + Creates a runfiles object. + ### Parameters -| Parameter | Description | -| --- | --- | -| `files` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` The list of files to be added to the runfiles. | -| `transitive_files` | [depset](../builtins/depset.mdx) of [File](../builtins/File.mdx)s; or `None`; default is `None` The (transitive) set of files to be added to the runfiles. The depset should use the `default` order (which, as the name implies, is the default). | -| `collect_data` | [bool](../core/bool.mdx); default is `False` **Use of this parameter is not recommended. See [runfiles guide](https://bazel.build/extending/rules#runfiles)**. Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes. | -| `collect_default` | [bool](../core/bool.mdx); default is `False` **Use of this parameter is not recommended. See [runfiles guide](https://bazel.build/extending/rules#runfiles)**. Whether to collect the default runfiles from the dependencies in srcs, data and deps attributes. | -| `symlinks` | [dict](../core/dict.mdx); or [depset](../builtins/depset.mdx) of [SymlinkEntry](../builtins/SymlinkEntry.mdx)s; default is `\{\}` Either a SymlinkEntry depset or the map of symlinks to be added to the runfiles. Symlinks are always added under the main workspace's runfiles directory (e.g. `<runfiles_root>/_main/\<symlink_path\>`, **not** the directory corresponding to the current target's repository. See [Runfiles symlinks](https://bazel.build/extending/rules#runfiles_symlinks) in the rules guide. | -| `root_symlinks` | [dict](../core/dict.mdx); or [depset](../builtins/depset.mdx) of [SymlinkEntry](../builtins/SymlinkEntry.mdx)s; default is `\{\}` Either a SymlinkEntry depset or a map of symlinks to be added to the runfiles. See [Runfiles symlinks](https://bazel.build/extending/rules#runfiles_symlinks) in the rules guide. | +ParameterDescription`files`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + + The list of files to be added to the runfiles. + `transitive_files`[depset](../builtins/depset.html) of [File](../builtins/File.html) s; or `None`; + default is `None` + + The (transitive) set of files to be added to the runfiles. The depset should use the `default` order (which, as the name implies, is the default). + `collect_data`[bool](../core/bool.html); + default is `False` + +**Use of this parameter is not recommended. See [runfiles guide](https://bazel.build/extending/rules#runfiles)**. + +Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes. + + +`collect_default`[bool](../core/bool.html); + default is `False` + +**Use of this parameter is not recommended. See [runfiles guide](https://bazel.build/extending/rules#runfiles)**. + +Whether to collect the default runfiles from the dependencies in srcs, data and deps attributes. + + +`symlinks`[dict](../core/dict.html); or [depset](../builtins/depset.html) of [SymlinkEntry](../builtins/SymlinkEntry.html) s; + default is `{}` + + Either a SymlinkEntry depset or the map of symlinks to be added to the runfiles. Symlinks are always added under the main workspace's runfiles directory (e.g. `<runfiles_root>/_main/<symlink_path>`, **not** the directory corresponding to the current target's repository. See [Runfiles symlinks](https://bazel.build/extending/rules#runfiles_symlinks) in the rules guide. + `root_symlinks`[dict](../core/dict.html); or [depset](../builtins/depset.html) of [SymlinkEntry](../builtins/SymlinkEntry.html) s; + default is `{}` + + Either a SymlinkEntry depset or a map of symlinks to be added to the runfiles. See [Runfiles symlinks](https://bazel.build/extending/rules#runfiles_symlinks) in the rules guide. + ## split\_attr @@ -346,7 +460,9 @@ Creates a runfiles object. struct ctx.split_attr ``` -A struct to access the values of attributes with split configurations. If the attribute is a label list, the value of split\_attr is a dict of the keys of the split (as strings) to lists of the ConfiguredTargets in that branch of the split. If the attribute is a label, then the value of split\_attr is a dict of the keys of the split (as strings) to single ConfiguredTargets. Attributes with split configurations still appear in the attr struct, but their values will be single lists with all the branches of the split merged together. + A struct to access the values of attributes with split configurations. If the attribute is a label list, the value of split\_attr is a dict of the keys of the split (as strings) to lists of the ConfiguredTargets in that branch of the split. If the attribute is a label, then the value of split\_attr is a dict of the keys of the split (as strings) to single ConfiguredTargets. Attributes with split configurations still appear in the attr struct, but their values will be single lists with all the branches of the split merged together. + + ## super @@ -354,7 +470,9 @@ A struct to access the values of attributes with split configurations. If the at unknown ctx.super() ``` -Experimental: Calls parent's implementation function and returns its providers + Experimental: Calls parent's implementation function and returns its providers + + ## target\_platform\_has\_constraint @@ -362,13 +480,16 @@ Experimental: Calls parent's implementation function and returns its providers bool ctx.target_platform_has_constraint(constraintValue) ``` -Returns true if the given constraint value is part of the current target platform. + Returns true if the given constraint value is part of the current target platform. + ### Parameters -| Parameter | Description | -| --- | --- | -| `constraintValue` | [ConstraintValueInfo](../providers/ConstraintValueInfo.mdx); required The constraint value to check the target platform against. | +ParameterDescription`constraintValue`[ConstraintValueInfo](../providers/ConstraintValueInfo.html); + required + + The constraint value to check the target platform against. + ## toolchains @@ -376,7 +497,9 @@ Returns true if the given constraint value is part of the current target platfor ToolchainContext ctx.toolchains ``` -Toolchains for the default exec group of this rule. + Toolchains for the default exec group of this rule. + + ## var @@ -384,7 +507,9 @@ Toolchains for the default exec group of this rule. dict ctx.var ``` -Dictionary (String to String) of configuration variables. + Dictionary (String to String) of configuration variables. + + ## version\_file @@ -392,7 +517,9 @@ Dictionary (String to String) of configuration variables. File ctx.version_file ``` -The file that is used to hold the volatile workspace status for the current build request. See documentation for --workspace\_status\_command for more information. + The file that is used to hold the volatile workspace status for the current build request. See documentation for --workspace\_status\_command for more information. + + ## workspace\_name @@ -400,4 +527,4 @@ The file that is used to hold the volatile workspace status for the current buil string ctx.workspace_name ``` -The name of the workspace, which is effectively the execution root name and runfiles prefix for the main repo. If `--enable_bzlmod` is on, this is the fixed string `_main`. Otherwise, this is the workspace name as defined in the WORKSPACE file. \ No newline at end of file + The name of the workspace, which is effectively the execution root name and runfiles prefix for the main repo. If `--enable_bzlmod` is on, this is the fixed string `_main`. Otherwise, this is the workspace name as defined in the WORKSPACE file. diff --git a/rules/lib/builtins/depset.mdx b/rules/lib/builtins/depset.mdx index 5e84d17..59d6240 100644 --- a/rules/lib/builtins/depset.mdx +++ b/rules/lib/builtins/depset.mdx @@ -3,9 +3,10 @@ title: 'depset' --- + A specialized data structure that supports efficient merge operations and has a defined traversal order. Commonly used for accumulating data from transitive dependencies in rules and aspects. For -more information see [here](./extending/depsets). +more information see [here](/extending/depsets). The elements of a depset must be hashable and all of the same type (as defined by the built-in [`type(x)`](../globals/all#type) function), but depsets are not simply hash @@ -25,16 +26,20 @@ depsets via the `transitive` argument. The `order` parameter determines the kind of traversal that is done to convert the depset to an iterable. There are four possible values: -* `"default"` (formerly `"stable"`): Order is unspecified (but - deterministic). -* `"postorder"` (formerly `"compile"`): A left-to-right post-ordering. - Precisely, this recursively traverses all children leftmost-first, then the direct elements - leftmost-first. -* `"preorder"` (formerly `"naive_link"`): A left-to-right pre-ordering. - Precisely, this traverses the direct elements leftmost-first, then recursively traverses the - children leftmost-first. -* `"topological"` (formerly `"link"`): A topological ordering from the root - down to the leaves. There is no left-to-right guarantee. +- `"default"` (formerly `"stable"`): Order is unspecified (but + deterministic). + +- `"postorder"` (formerly `"compile"`): A left-to-right post-ordering. + Precisely, this recursively traverses all children leftmost-first, then the direct elements + leftmost-first. + +- `"preorder"` (formerly `"naive_link"`): A left-to-right pre-ordering. + Precisely, this traverses the direct elements leftmost-first, then recursively traverses the + children leftmost-first. + +- `"topological"` (formerly `"link"`): A topological ordering from the root + down to the leaves. There is no left-to-right guarantee. + Two depsets may only be merged if either both depsets have the same order, or one of them has `"default"` order. In the latter case the resulting depset's order will be the same as @@ -46,7 +51,7 @@ semantics. ## Members -* [to\_list](#to_list) +- [to\_list](#to_list) ## to\_list @@ -54,4 +59,4 @@ semantics. list depset.to_list() ``` -Returns a list of the elements, without duplicates, in the depset's traversal order. Note that order is unspecified (but deterministic) for elements that were added more than once to the depset. Order is also unspecified for `"default"`-ordered depsets, and for elements of child depsets whose order differs from that of the parent depset. The list is a copy; modifying it has no effect on the depset and vice versa. \ No newline at end of file + Returns a list of the elements, without duplicates, in the depset's traversal order. Note that order is unspecified (but deterministic) for elements that were added more than once to the depset. Order is also unspecified for `"default"`-ordered depsets, and for elements of child depsets whose order differs from that of the parent depset. The list is a copy; modifying it has no effect on the depset and vice versa. diff --git a/rules/lib/builtins/exec_result.mdx b/rules/lib/builtins/exec_result.mdx index 47fbfdd..a4d37fa 100644 --- a/rules/lib/builtins/exec_result.mdx +++ b/rules/lib/builtins/exec_result.mdx @@ -1,15 +1,16 @@ --- -title: 'exec_result' +title: 'exec\_result' --- + A structure storing result of repository\_ctx.execute() method. It contains the standard output stream content, the standard error stream content and the execution return code. ## Members -* [return\_code](#return_code) -* [stderr](#stderr) -* [stdout](#stdout) +- [return\_code](#return_code) +- [stderr](#stderr) +- [stdout](#stdout) ## return\_code @@ -17,7 +18,9 @@ A structure storing result of repository\_ctx.execute() method. It contains the int exec_result.return_code ``` -The return code returned after the execution of the program. 256 if the process was terminated by a time out; values larger than 128 indicate termination by a signal. + The return code returned after the execution of the program. 256 if the process was terminated by a time out; values larger than 128 indicate termination by a signal. + + ## stderr @@ -25,7 +28,9 @@ The return code returned after the execution of the program. 256 if the process string exec_result.stderr ``` -The content of the standard error output returned by the execution. + The content of the standard error output returned by the execution. + + ## stdout @@ -33,4 +38,4 @@ The content of the standard error output returned by the execution. string exec_result.stdout ``` -The content of the standard output returned by the execution. \ No newline at end of file + The content of the standard output returned by the execution. diff --git a/rules/lib/builtins/extension_metadata.mdx b/rules/lib/builtins/extension_metadata.mdx index 180e16d..cb6b3b4 100644 --- a/rules/lib/builtins/extension_metadata.mdx +++ b/rules/lib/builtins/extension_metadata.mdx @@ -1,6 +1,7 @@ --- -title: 'extension_metadata' +title: 'extension\_metadata' --- -Return values of this type from a module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. \ No newline at end of file + +Return values of this type from a module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. diff --git a/rules/lib/builtins/fragments.mdx b/rules/lib/builtins/fragments.mdx index 70b847a..0c6d48d 100644 --- a/rules/lib/builtins/fragments.mdx +++ b/rules/lib/builtins/fragments.mdx @@ -3,8 +3,9 @@ title: 'fragments' --- + A collection of configuration fragments available in the current rule implementation context. Access a specific fragment by its field name. For example, `ctx.fragments.java` Only configuration fragments which are declared in the rule definition may be accessed in this collection. -See the [configuration fragment reference](../fragments.mdx) for a list of available fragments and the [rules documentation](https://bazel.build/extending/rules#configuration_fragments) for how to use them. \ No newline at end of file +See the [configuration fragment reference](../fragments.html) for a list of available fragments and the [rules documentation](https://bazel.build/extending/rules#configuration_fragments) for how to use them. diff --git a/rules/lib/builtins/java_annotation_processing.mdx b/rules/lib/builtins/java_annotation_processing.mdx index 82bbaad..f2be555 100644 --- a/rules/lib/builtins/java_annotation_processing.mdx +++ b/rules/lib/builtins/java_annotation_processing.mdx @@ -1,19 +1,20 @@ --- -title: 'java_annotation_processing' +title: 'java\_annotation\_processing' --- + Information about jars that are a result of annotation processing for a Java rule. ## Members -* [class\_jar](#class_jar) -* [enabled](#enabled) -* [processor\_classnames](#processor_classnames) -* [processor\_classpath](#processor_classpath) -* [source\_jar](#source_jar) -* [transitive\_class\_jars](#transitive_class_jars) -* [transitive\_source\_jars](#transitive_source_jars) +- [class\_jar](#class_jar) +- [enabled](#enabled) +- [processor\_classnames](#processor_classnames) +- [processor\_classpath](#processor_classpath) +- [source\_jar](#source_jar) +- [transitive\_class\_jars](#transitive_class_jars) +- [transitive\_source\_jars](#transitive_source_jars) ## class\_jar @@ -21,8 +22,10 @@ Information about jars that are a result of annotation processing for a Java rul File java_annotation_processing.class_jar ``` -Deprecated: Please use `JavaInfo.java_outputs.generated_class_jar` instead. -May return `None`. + Deprecated: Please use `JavaInfo.java_outputs.generated_class_jar` instead. + May return `None`. + + ## enabled @@ -30,7 +33,9 @@ May return `None`. bool java_annotation_processing.enabled ``` -Deprecated. Returns true if annotation processing was applied on this target. + Deprecated. Returns true if annotation processing was applied on this target. + + ## processor\_classnames @@ -38,7 +43,9 @@ Deprecated. Returns true if annotation processing was applied on this target. list java_annotation_processing.processor_classnames ``` -Deprecated: Please use `JavaInfo.plugins` instead. Returns class names of annotation processors applied to this rule. + Deprecated: Please use `JavaInfo.plugins` instead. Returns class names of annotation processors applied to this rule. + + ## processor\_classpath @@ -46,7 +53,9 @@ Deprecated: Please use `JavaInfo.plugins` instead. Returns class names of annota depset java_annotation_processing.processor_classpath ``` -Deprecated: Please use `JavaInfo.plugins` instead. Returns a classpath of annotation processors applied to this rule. + Deprecated: Please use `JavaInfo.plugins` instead. Returns a classpath of annotation processors applied to this rule. + + ## source\_jar @@ -54,8 +63,10 @@ Deprecated: Please use `JavaInfo.plugins` instead. Returns a classpath of annota File java_annotation_processing.source_jar ``` -Deprecated: Please use `JavaInfo.java_outputs.generated_source_jar` instead. -May return `None`. + Deprecated: Please use `JavaInfo.java_outputs.generated_source_jar` instead. + May return `None`. + + ## transitive\_class\_jars @@ -63,7 +74,9 @@ May return `None`. depset java_annotation_processing.transitive_class_jars ``` -Deprecated. Returns a transitive set of class file jars resulting from annotation processing of this rule and its dependencies. + Deprecated. Returns a transitive set of class file jars resulting from annotation processing of this rule and its dependencies. + + ## transitive\_source\_jars @@ -71,4 +84,4 @@ Deprecated. Returns a transitive set of class file jars resulting from annotatio depset java_annotation_processing.transitive_source_jars ``` -Deprecated. Returns a transitive set of source archives resulting from annotation processing of this rule and its dependencies. \ No newline at end of file + Deprecated. Returns a transitive set of source archives resulting from annotation processing of this rule and its dependencies. diff --git a/rules/lib/builtins/macro.mdx b/rules/lib/builtins/macro.mdx index 8228c3b..9ac9af7 100644 --- a/rules/lib/builtins/macro.mdx +++ b/rules/lib/builtins/macro.mdx @@ -3,9 +3,10 @@ title: 'macro' --- + A callable Starlark value representing a symbolic macro; in other words, the return value of [`macro()`](../globals/bzl.html#macro). Invoking this value during package construction time will instantiate the macro, and cause the macro's implementation function to be evaluated (in a separate context, different from the context in which the macro value was invoked), in most cases causing targets to be added to the package's target set. For more information, see -[Macros](https://bazel.build/extending/macros). \ No newline at end of file +[Macros](https://bazel.build/extending/macros). diff --git a/rules/lib/builtins/mapped_root.mdx b/rules/lib/builtins/mapped_root.mdx index 70ce184..c448abf 100644 --- a/rules/lib/builtins/mapped_root.mdx +++ b/rules/lib/builtins/mapped_root.mdx @@ -1,13 +1,14 @@ --- -title: 'mapped_root' +title: 'mapped\_root' --- + A root for files that have been subject to path mapping ## Members -* [path](#path) +- [path](#path) ## path @@ -15,4 +16,4 @@ A root for files that have been subject to path mapping string mapped_root.path ``` -Returns the relative path from the exec root to the actual root. \ No newline at end of file + Returns the relative path from the exec root to the actual root. diff --git a/rules/lib/builtins/module_ctx.mdx b/rules/lib/builtins/module_ctx.mdx index b6b0e33..714e9de 100644 --- a/rules/lib/builtins/module_ctx.mdx +++ b/rules/lib/builtins/module_ctx.mdx @@ -1,95 +1,197 @@ --- -title: 'module_ctx' +title: 'module\_ctx' --- + The context of the module extension containing helper functions and information about pertinent tags across the dependency graph. You get a module\_ctx object as an argument to the `implementation` function when you create a module extension. ## Members -* [download](#download) -* [download\_and\_extract](#download_and_extract) -* [execute](#execute) -* [extension\_metadata](#extension_metadata) -* [extract](#extract) -* [file](#file) -* [getenv](#getenv) -* [is\_dev\_dependency](#is_dev_dependency) -* [modules](#modules) -* [os](#os) -* [path](#path) -* [read](#read) -* [report\_progress](#report_progress) -* [root\_module\_has\_non\_dev\_dependency](#root_module_has_non_dev_dependency) -* [watch](#watch) -* [which](#which) +- [download](#download) +- [download\_and\_extract](#download_and_extract) +- [execute](#execute) +- [extension\_metadata](#extension_metadata) +- [extract](#extract) +- [file](#file) +- [getenv](#getenv) +- [is\_dev\_dependency](#is_dev_dependency) +- [modules](#modules) +- [os](#os) +- [path](#path) +- [read](#read) +- [report\_progress](#report_progress) +- [root\_module\_has\_non\_dev\_dependency](#root_module_has_non_dev_dependency) +- [watch](#watch) +- [which](#which) ## download ``` -unknown module_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth=\{\}, headers=\{\}, *, integrity='', block=True) +unknown module_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True) ``` -Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](./rules/lib/repo/cache#get_default_canonical_id) - + Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) ### Parameters -| Parameter | Description | -| --- | --- | -| `url` | [string](../core/string.mdx); or Iterable of [string](../core/string.mdx)s; required List of mirror URLs referencing the same file. | -| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` path to the output file, relative to the repository directory. | -| `sha256` | [string](../core/string.mdx); default is `''` The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | -| `executable` | [bool](../core/bool.mdx); default is `False` Set the executable flag on the created file, false by default. | -| `allow_fail` | [bool](../core/bool.mdx); default is `False` If set, indicate the error in the return value instead of raising an error for failed downloads. | -| `canonical_id` | [string](../core/string.mdx); default is `''` If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (`sha256` or `integrity`). | -| `auth` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying authentication information for some of the URLs. | -| `headers` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying http headers for all URLs. | -| `integrity` | [string](../core/string.mdx); default is `''` Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | -| `block` | [bool](../core/bool.mdx); default is `True` If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. | +ParameterDescription`url`[string](../core/string.html); or Iterable of [string](../core/string.html) s; + required + + List of mirror URLs referencing the same file. + `output`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + default is `''` + + path to the output file, relative to the repository directory. + `sha256`[string](../core/string.html); + default is `''` + + The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + `executable`[bool](../core/bool.html); + default is `False` + + Set the executable flag on the created file, false by default. + `allow_fail`[bool](../core/bool.html); + default is `False` + + If set, indicate the error in the return value instead of raising an error for failed downloads. + + `canonical_id`[string](../core/string.html); + default is `''` + + If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum ( `sha256` or `integrity`). + + `auth`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying authentication information for some of the URLs. + `headers`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying http headers for all URLs. + `integrity`[string](../core/string.html); + default is `''` + + Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + `block`[bool](../core/bool.html); + default is `True` + + If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. + + ## download\_and\_extract ``` -struct module_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth=\{\}, headers=\{\}, *, integrity='', rename_files=\{\}) +struct module_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={}) ``` -Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](./rules/lib/repo/cache#get_default_canonical_id) - + Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) ### Parameters -| Parameter | Description | -| --- | --- | -| `url` | [string](../core/string.mdx); or Iterable of [string](../core/string.mdx)s; required List of mirror URLs referencing the same file. | -| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` Path to the directory where the archive will be unpacked, relative to the repository directory. | -| `sha256` | [string](../core/string.mdx); default is `''` The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | -| `type` | [string](../core/string.mdx); default is `''` The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. | -| `strip_prefix` | [string](../core/string.mdx); default is `''` A directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the `build_file`, this field can be used to strip it from extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. | -| `allow_fail` | [bool](../core/bool.mdx); default is `False` If set, indicate the error in the return value instead of raising an error for failed downloads. | -| `canonical_id` | [string](../core/string.mdx); default is `''` If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (`sha256` or `integrity`). | -| `auth` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying authentication information for some of the URLs. | -| `headers` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying http headers for all URLs. | -| `integrity` | [string](../core/string.mdx); default is `''` Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | -| `rename_files` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. | +ParameterDescription`url`[string](../core/string.html); or Iterable of [string](../core/string.html) s; + required + + List of mirror URLs referencing the same file. + `output`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + default is `''` + + Path to the directory where the archive will be unpacked, relative to the repository directory. + + `sha256`[string](../core/string.html); + default is `''` + + The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + `type`[string](../core/string.html); + default is `''` + + The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. + + `strip_prefix`[string](../core/string.html); + default is `''` + + A directory prefix to strip from the extracted files. Many archives contain a +top-level directory that contains all files in the archive. Instead of needing to +specify this prefix over and over in the `build_file`, this field can +be used to strip it from extracted files. + +For compatibility, this parameter may also be used under the deprecated name +`stripPrefix`. + + + +`allow_fail`[bool](../core/bool.html); + default is `False` + + If set, indicate the error in the return value instead of raising an error for failed downloads. + + `canonical_id`[string](../core/string.html); + default is `''` + + If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum +( `sha256` or `integrity`). + + `auth`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying authentication information for some of the URLs. + `headers`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying http headers for all URLs. + `integrity`[string](../core/string.html); + default is `''` + + Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + `rename_files`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. + + ## execute ``` -exec_result module_ctx.execute(arguments, timeout=600, environment=\{\}, quiet=True, working_directory="") +exec_result module_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="") ``` -Executes the command given by the list of arguments. The execution time of the command is limited by `timeout` (in seconds, default 600 seconds). This method returns an `exec_result` structure containing the output of the command. The `environment` map can be used to override some environment variables to be passed to the process. + Executes the command given by the list of arguments. The execution time of the command is limited by `timeout` (in seconds, default 600 seconds). This method returns an `exec_result` structure containing the output of the command. The `environment` map can be used to override some environment variables to be passed to the process. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `arguments` | [sequence](../core/list.mdx); required List of arguments, the first element should be the path to the program to execute. | -| `timeout` | [int](../core/int.mdx); default is `600` Maximum duration of the command in seconds (default is 600 seconds). | -| `environment` | [dict](../core/dict.mdx); default is `\{\}` Force some environment variables to be set to be passed to the process. The value can be `None` to remove the environment variable. | -| `quiet` | [bool](../core/bool.mdx); default is `True` If stdout and stderr should be printed to the terminal. | -| `working_directory` | [string](../core/string.mdx); default is `""` Working directory for command execution. Can be relative to the repository root or absolute. The default is the repository root. | +ParameterDescription`arguments`[sequence](../core/list.html); + required + + List of arguments, the first element should be the path to the program to execute. + + `timeout`[int](../core/int.html); + default is `600` + + Maximum duration of the command in seconds (default is 600 seconds). + `environment`[dict](../core/dict.html); + default is `{}` + + Force some environment variables to be set to be passed to the process. The value can be `None` to remove the environment variable. + + `quiet`[bool](../core/bool.html); + default is `True` + + If stdout and stderr should be printed to the terminal. + `working_directory`[string](../core/string.html); + default is `""` + + Working directory for command execution. +Can be relative to the repository root or absolute. +The default is the repository root. + + ## extension\_metadata @@ -97,33 +199,80 @@ Executes the command given by the list of arguments. The execution time of the c extension_metadata module_ctx.extension_metadata(*, root_module_direct_deps=None, root_module_direct_dev_deps=None, reproducible=False) ``` -Constructs an opaque object that can be returned from the module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. + Constructs an opaque object that can be returned from the module extension's implementation function to provide metadata about the repositories generated by the extension to Bazel. + ### Parameters -| Parameter | Description | -| --- | --- | -| `root_module_direct_deps` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or [string](../core/string.mdx); or `None`; default is `None` The names of the repositories that the extension considers to be direct dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via [`use_repo`](../globals/module.html#use_repo), Bazel will print a warning when the extension is evaluated, instructing the user to run `bazel mod tidy` to fix the `use_repo` calls automatically. If one of `root_module_direct_deps` and will print a warning and a fixup command when the extension is evaluated. If one of `root_module_direct_deps` and `root_module_direct_dev_deps` is specified, the other has to be as well. The lists specified by these two parameters must be disjoint. Exactly one of `root_module_direct_deps` and `root_module_direct_dev_deps` can be set to the special value `"all"`, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. | -| `root_module_direct_dev_deps` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or [string](../core/string.mdx); or `None`; default is `None` The names of the repositories that the extension considers to be direct dev dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via [`use_repo`](../globals/module.html#use_repo) on an extension proxy created with `use_extension(..., dev_dependency = True)`, Bazel will print a warning when the extension is evaluated, instructing the user to run `bazel mod tidy` to fix the `use_repo` calls automatically. If one of `root_module_direct_deps` and `root_module_direct_dev_deps` is specified, the other has to be as well. The lists specified by these two parameters must be disjoint. Exactly one of `root_module_direct_deps` and `root_module_direct_dev_deps` can be set to the special value `"all"`, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. | -| `reproducible` | [bool](../core/bool.mdx); default is `False` States that this module extension ensures complete reproducibility, thereby it should not be stored in the lockfile. | +ParameterDescription`root_module_direct_deps`[sequence](../core/list.html) of [string](../core/string.html) s; or [string](../core/string.html); or `None`; + default is `None` + + The names of the repositories that the extension considers to be direct dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via [`use_repo`](../globals/module.html#use_repo), Bazel will print a warning when the extension is evaluated, instructing the user to run `bazel mod tidy` to fix the `use_repo` calls automatically. + +If one of `root_module_direct_deps` and will print a warning and a fixup command when the extension is evaluated. + +If one of `root_module_direct_deps` and `root_module_direct_dev_deps` is specified, the other has to be as well. The lists specified by these two parameters must be disjoint. + +Exactly one of `root_module_direct_deps` and `root_module_direct_dev_deps` can be set to the special value `"all"`, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. + + +`root_module_direct_dev_deps`[sequence](../core/list.html) of [string](../core/string.html) s; or [string](../core/string.html); or `None`; + default is `None` + + The names of the repositories that the extension considers to be direct dev dependencies of the root module. If the root module imports additional repositories or does not import all of these repositories via [`use_repo`](../globals/module.html#use_repo) on an extension proxy created with `use_extension(..., dev_dependency = True)`, Bazel will print a warning when the extension is evaluated, instructing the user to run `bazel mod tidy` to fix the `use_repo` calls automatically. + +If one of `root_module_direct_deps` and `root_module_direct_dev_deps` is specified, the other has to be as well. The lists specified by these two parameters must be disjoint. + +Exactly one of `root_module_direct_deps` and `root_module_direct_dev_deps` can be set to the special value `"all"`, which is treated as if a list with the names of all repositories generated by the extension was specified as the value. + + +`reproducible`[bool](../core/bool.html); + default is `False` + + States that this module extension ensures complete reproducibility, thereby it should not be stored in the lockfile. + ## extract ``` -None module_ctx.extract(archive, output='', strip_prefix='', *, rename_files=\{\}, watch_archive='auto') +None module_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto') ``` -Extract an archive to the repository directory. + Extract an archive to the repository directory. + ### Parameters -| Parameter | Description | -| --- | --- | -| `archive` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required path to the archive that will be unpacked, relative to the repository directory. | -| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` path to the directory where the archive will be unpacked, relative to the repository directory. | -| `strip_prefix` | [string](../core/string.mdx); default is `''` a directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the `build_file`, this field can be used to strip it from extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. | -| `rename_files` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. | -| `watch_archive` | [string](../core/string.mdx); default is `'auto'` whether to [watch](#watch) the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | +ParameterDescription`archive`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + path to the archive that will be unpacked, relative to the repository directory. + `output`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + default is `''` + + path to the directory where the archive will be unpacked, relative to the repository directory. + `strip_prefix`[string](../core/string.html); + default is `''` + + a directory prefix to strip from the extracted files. Many archives contain a +top-level directory that contains all files in the archive. Instead of needing to +specify this prefix over and over in the `build_file`, this field can be +used to strip it from extracted files. + +For compatibility, this parameter may also be used under the deprecated name +`stripPrefix`. + + + +`rename_files`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. + `watch_archive`[string](../core/string.html); + default is `'auto'` + + whether to [watch](#watch) the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. + ## file @@ -131,16 +280,29 @@ Extract an archive to the repository directory. None module_ctx.file(path, content='', executable=True, legacy_utf8=False) ``` -Generates a file in the repository directory with the provided content. + Generates a file in the repository directory with the provided content. + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to create, relative to the repository directory. | -| `content` | [string](../core/string.mdx); default is `''` The content of the file to create, empty by default. | -| `executable` | [bool](../core/bool.mdx); default is `True` Set the executable flag on the created file, true by default. | -| `legacy_utf8` | [bool](../core/bool.mdx); default is `False` No-op. This parameter is deprecated and will be removed in a future version of Bazel. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path of the file to create, relative to the repository directory. + `content`[string](../core/string.html); + default is `''` + + The content of the file to create, empty by default. + `executable`[bool](../core/bool.html); + default is `True` + + Set the executable flag on the created file, true by default. + `legacy_utf8`[bool](../core/bool.html); + default is `False` + + No-op. This parameter is deprecated and will be removed in a future version of Bazel. + + ## getenv @@ -148,18 +310,26 @@ Generates a file in the repository directory with the provided content. string module_ctx.getenv(name, default=None) ``` -Returns the value of an environment variable `name` as a string if exists, or `default` if it doesn't. + Returns the value of an environment variable `name` as a string if exists, or `default` if it doesn't. When building incrementally, any change to the value of the variable named by `name` will cause this repository to be re-fetched. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required Name of desired environment variable. | -| `default` | [string](../core/string.mdx); or `None`; default is `None` Default value to return if `name` is not found. | +ParameterDescription`name`[string](../core/string.html); + required + + Name of desired environment variable. + `default`[string](../core/string.html); or `None`; + default is `None` + + Default value to return if `name` is not found. + + May return `None`. + -May return `None`. ## is\_dev\_dependency @@ -167,13 +337,17 @@ May return `None`. bool module_ctx.is_dev_dependency(tag) ``` -Returns whether the given tag was specified on the result of a [use\_extension](../globals/module.html#use_extension) call with `devDependency = True`. + Returns whether the given tag was specified on the result of a [use\_extension](../globals/module.html#use_extension) call with `devDependency = True`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `tag` | bazel\_module\_tag; required A tag obtained from [bazel\_module.tags](../builtins/bazel_module.html#tags). | +ParameterDescription`tag` + bazel\_module\_tag; + required + + A tag obtained from [bazel\_module.tags](../builtins/bazel_module.html#tags). + ## modules @@ -181,7 +355,9 @@ Returns whether the given tag was specified on the result of a [use\_extension]( list module_ctx.modules ``` -A list of all the Bazel modules in the external dependency graph that use this module extension, each of which is a [bazel\_module](../builtins/bazel_module.mdx) object that exposes all the tags it specified for this extension. The iteration order of this dictionary is guaranteed to be the same as breadth-first search starting from the root module. + A list of all the Bazel modules in the external dependency graph that use this module extension, each of which is a [bazel\_module](../builtins/bazel_module.html) object that exposes all the tags it specified for this extension. The iteration order of this dictionary is guaranteed to be the same as breadth-first search starting from the root module. + + ## os @@ -189,7 +365,9 @@ A list of all the Bazel modules in the external dependency graph that use this m repository_os module_ctx.os ``` -A struct to access information from the system. + A struct to access information from the system. + + ## path @@ -197,13 +375,17 @@ A struct to access information from the system. path module_ctx.path(path) ``` -Returns a path from a string, label, or path. If this context is a `repository_ctx`, a relative path will resolve relative to the repository directory. If it is a `module_ctx`, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. + Returns a path from a string, label, or path. If this context is a `repository_ctx`, a relative path will resolve relative to the repository directory. If it is a `module_ctx`, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required `string`, `Label` or `path` from which to create a path from. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + +`string`, `Label` or `path` from which to create a path from. + ## read @@ -211,14 +393,21 @@ Returns a path from a string, label, or path. If this context is a `repository_c string module_ctx.read(path, *, watch='auto') ``` -Reads the content of a file on the filesystem. + Reads the content of a file on the filesystem. + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to read from. | -| `watch` | [string](../core/string.mdx); default is `'auto'` Whether to [watch](#watch) the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path of the file to read from. + `watch`[string](../core/string.html); + default is `'auto'` + + Whether to [watch](#watch) the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. + + ## report\_progress @@ -226,13 +415,16 @@ Reads the content of a file on the filesystem. None module_ctx.report_progress(status='') ``` -Updates the progress status for the fetching of this repository or module extension. + Updates the progress status for the fetching of this repository or module extension. + ### Parameters -| Parameter | Description | -| --- | --- | -| `status` | [string](../core/string.mdx); default is `''` `string` describing the current status of the fetch progress. | +ParameterDescription`status`[string](../core/string.html); + default is `''` + +`string` describing the current status of the fetch progress. + ## root\_module\_has\_non\_dev\_dependency @@ -240,7 +432,9 @@ Updates the progress status for the fetching of this repository or module extens bool module_ctx.root_module_has_non_dev_dependency ``` -Whether the root module uses this extension as a non-dev dependency. + Whether the root module uses this extension as a non-dev dependency. + + ## watch @@ -248,17 +442,21 @@ Whether the root module uses this extension as a non-dev dependency. None module_ctx.watch(path) ``` -Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time. + Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time. -"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does *not* include changes to any files under the directory if the path is a directory. For that, use [`path.readdir()`](path.html#readdir) instead. +"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does _not_ include changes to any files under the directory if the path is a directory. For that, use [`path.readdir()`](path.html#readdir) instead. Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to watch. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path of the file to watch. + ## which @@ -266,12 +464,15 @@ Note that attempting to watch paths inside the repo currently being fetched, or path module_ctx.which(program) ``` -Returns the `path` of the corresponding program or `None` if there is no such program in the path. + Returns the `path` of the corresponding program or `None` if there is no such program in the path. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `program` | [string](../core/string.mdx); required Program to find in the path. | +ParameterDescription`program`[string](../core/string.html); + required + + Program to find in the path. -May return `None`. \ No newline at end of file + May return `None`. diff --git a/rules/lib/builtins/path.mdx b/rules/lib/builtins/path.mdx index 95ab28a..1d1d36b 100644 --- a/rules/lib/builtins/path.mdx +++ b/rules/lib/builtins/path.mdx @@ -3,17 +3,18 @@ title: 'path' --- + A structure representing a file to be used inside a repository. ## Members -* [basename](#basename) -* [dirname](#dirname) -* [exists](#exists) -* [get\_child](#get_child) -* [is\_dir](#is_dir) -* [readdir](#readdir) -* [realpath](#realpath) +- [basename](#basename) +- [dirname](#dirname) +- [exists](#exists) +- [get\_child](#get_child) +- [is\_dir](#is_dir) +- [readdir](#readdir) +- [realpath](#realpath) ## basename @@ -21,7 +22,9 @@ A structure representing a file to be used inside a repository. string path.basename ``` -A string giving the basename of the file. + A string giving the basename of the file. + + ## dirname @@ -29,8 +32,10 @@ A string giving the basename of the file. path path.dirname ``` -The parent directory of this file, or None if this file does not have a parent. -May return `None`. + The parent directory of this file, or None if this file does not have a parent. + May return `None`. + + ## exists @@ -38,9 +43,11 @@ May return `None`. bool path.exists ``` -Returns true if the file or directory denoted by this path exists. + Returns true if the file or directory denoted by this path exists. + +Note that accessing this field does _not_ cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to the path's existence, use the `watch()` method on the context object. + -Note that accessing this field does *not* cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to the path's existence, use the `watch()` method on the context object. ## get\_child @@ -48,13 +55,17 @@ Note that accessing this field does *not* cause the path to be watched. If you'd path path.get_child(*relative_paths) ``` -Returns the path obtained by joining this path with the given relative paths. + Returns the path obtained by joining this path with the given relative paths. + ### Parameters -| Parameter | Description | -| --- | --- | -| `relative_paths` | required Zero or more relative path strings to append to this path with path separators added as needed. | +ParameterDescription`relative_paths` + required + + Zero or more relative path strings to append to this path with path separators added as needed. + + ## is\_dir @@ -62,9 +73,11 @@ Returns the path obtained by joining this path with the given relative paths. bool path.is_dir ``` -Returns true if this path points to a directory. + Returns true if this path points to a directory. + +Note that accessing this field does _not_ cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to whether the path is a directory or a file, use the `watch()` method on the context object. + -Note that accessing this field does *not* cause the path to be watched. If you'd like the repo rule or module extension to be sensitive to whether the path is a directory or a file, use the `watch()` method on the context object. ## readdir @@ -72,13 +85,20 @@ Note that accessing this field does *not* cause the path to be watched. If you'd list path.readdir(*, watch='auto') ``` -Returns the list of entries in the directory denoted by this path. Each entry is a `path` object itself. + Returns the list of entries in the directory denoted by this path. Each entry is a `path` object itself. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `watch` | [string](../core/string.mdx); default is `'auto'` whether Bazel should watch the list of entries in this directory and refetch the repository or re-evaluate the module extension next time when any changes are detected. Changes to detect include entry creation, deletion, and renaming. Note that this doesn't watch the *contents* of any entries in the directory. Can be the string 'yes', 'no', or 'auto'. If set to 'auto', Bazel will only watch this directory when it is legal to do so (see [`repository_ctx.watch()`](repository_ctx.html#watch) docs for more information). | +ParameterDescription`watch`[string](../core/string.html); + default is `'auto'` + + whether Bazel should watch the list of entries in this directory and refetch the repository or re-evaluate the module extension next time when any changes are detected. Changes to detect include entry creation, deletion, and renaming. Note that this doesn't watch the _contents_ of any entries in the directory. + +Can be the string 'yes', 'no', or 'auto'. If set to 'auto', Bazel will only watch this directory when it is legal to do so (see [`repository_ctx.watch()`](repository_ctx.html#watch) docs for more information). + + ## realpath @@ -86,4 +106,4 @@ Returns the list of entries in the directory denoted by this path. Each entry is path path.realpath ``` -Returns the canonical path for this path by repeatedly replacing all symbolic links with their referents. \ No newline at end of file + Returns the canonical path for this path by repeatedly replacing all symbolic links with their referents. diff --git a/rules/lib/builtins/propagation_ctx.mdx b/rules/lib/builtins/propagation_ctx.mdx index 30f2138..8e4b23c 100644 --- a/rules/lib/builtins/propagation_ctx.mdx +++ b/rules/lib/builtins/propagation_ctx.mdx @@ -1,14 +1,15 @@ --- -title: 'propagation_ctx' +title: 'propagation\_ctx' --- + A context object that is passed to the `propagation_predicate`, `attr_aspects` and `toolchains_aspects` functions of aspects. It provides access to the information needed to determine whether the aspect should be propagated to the target and what attributes or toolchain types it should be propagated to next. ## Members -* [attr](#attr) -* [rule](#rule) +- [attr](#attr) +- [rule](#rule) ## attr @@ -16,7 +17,9 @@ A context object that is passed to the `propagation_predicate`, `attr_aspects` a struct propagation_ctx.attr ``` -A struct to access only the public parameters of the aspect. The keys and values of the struct are the parameters names and values. + A struct to access only the public parameters of the aspect. The keys and values of the struct are the parameters names and values. + + ## rule @@ -24,4 +27,4 @@ A struct to access only the public parameters of the aspect. The keys and values StarlarkAspectPropagationRuleApi propagation_ctx.rule ``` -Allows access to the details of the rule. \ No newline at end of file + Allows access to the details of the rule. diff --git a/rules/lib/builtins/repo_metadata.mdx b/rules/lib/builtins/repo_metadata.mdx index fbcf9dc..ba364b5 100644 --- a/rules/lib/builtins/repo_metadata.mdx +++ b/rules/lib/builtins/repo_metadata.mdx @@ -1,6 +1,7 @@ --- -title: 'repo_metadata' +title: 'repo\_metadata' --- -See [`repository_ctx.repo_metadata`](repository_ctx#repo_metadata). \ No newline at end of file + +See [`repository_ctx.repo_metadata`](repository_ctx#repo_metadata). diff --git a/rules/lib/builtins/repository_ctx.mdx b/rules/lib/builtins/repository_ctx.mdx index 8540496..8f89f3e 100644 --- a/rules/lib/builtins/repository_ctx.mdx +++ b/rules/lib/builtins/repository_ctx.mdx @@ -1,35 +1,36 @@ --- -title: 'repository_ctx' +title: 'repository\_ctx' --- + The context of the repository rule containing helper functions and information about attributes. You get a repository\_ctx object as an argument to the `implementation` function when you create a repository rule. ## Members -* [attr](#attr) -* [delete](#delete) -* [download](#download) -* [download\_and\_extract](#download_and_extract) -* [execute](#execute) -* [extract](#extract) -* [file](#file) -* [getenv](#getenv) -* [name](#name) -* [original\_name](#original_name) -* [os](#os) -* [patch](#patch) -* [path](#path) -* [read](#read) -* [rename](#rename) -* [repo\_metadata](#repo_metadata) -* [report\_progress](#report_progress) -* [symlink](#symlink) -* [template](#template) -* [watch](#watch) -* [watch\_tree](#watch_tree) -* [which](#which) -* [workspace\_root](#workspace_root) +- [attr](#attr) +- [delete](#delete) +- [download](#download) +- [download\_and\_extract](#download_and_extract) +- [execute](#execute) +- [extract](#extract) +- [file](#file) +- [getenv](#getenv) +- [name](#name) +- [original\_name](#original_name) +- [os](#os) +- [patch](#patch) +- [path](#path) +- [read](#read) +- [rename](#rename) +- [repo\_metadata](#repo_metadata) +- [report\_progress](#report_progress) +- [symlink](#symlink) +- [template](#template) +- [watch](#watch) +- [watch\_tree](#watch_tree) +- [which](#which) +- [workspace\_root](#workspace_root) ## attr @@ -37,7 +38,9 @@ The context of the repository rule containing helper functions and information a structure repository_ctx.attr ``` -A struct to access the values of the attributes. The values are provided by the user (if not, a default value is used). + A struct to access the values of the attributes. The values are provided by the user (if not, a default value is used). + + ## delete @@ -45,98 +48,228 @@ A struct to access the values of the attributes. The values are provided by the bool repository_ctx.delete(path) ``` -Deletes a file or a directory. Returns a bool, indicating whether the file or directory was actually deleted by this call. + Deletes a file or a directory. Returns a bool, indicating whether the file or directory was actually deleted by this call. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [path](../builtins/path.mdx); required Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string. | +ParameterDescription`path`[string](../core/string.html); or [path](../builtins/path.html); + required + + Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string. + + ## download ``` -unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth=\{\}, headers=\{\}, *, integrity='', block=True) +unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True) ``` -Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](./rules/lib/repo/cache#get_default_canonical_id) - + Downloads a file to the output path for the provided url and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) ### Parameters -| Parameter | Description | -| --- | --- | -| `url` | [string](../core/string.mdx); or Iterable of [string](../core/string.mdx)s; required List of mirror URLs referencing the same file. | -| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` path to the output file, relative to the repository directory. | -| `sha256` | [string](../core/string.mdx); default is `''` The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | -| `executable` | [bool](../core/bool.mdx); default is `False` Set the executable flag on the created file, false by default. | -| `allow_fail` | [bool](../core/bool.mdx); default is `False` If set, indicate the error in the return value instead of raising an error for failed downloads. | -| `canonical_id` | [string](../core/string.mdx); default is `''` If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (`sha256` or `integrity`). | -| `auth` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying authentication information for some of the URLs. | -| `headers` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying http headers for all URLs. | -| `integrity` | [string](../core/string.mdx); default is `''` Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | -| `block` | [bool](../core/bool.mdx); default is `True` If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. | +ParameterDescription`url`[string](../core/string.html); or Iterable of [string](../core/string.html) s; + required + + List of mirror URLs referencing the same file. + `output`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + default is `''` + + path to the output file, relative to the repository directory. + `sha256`[string](../core/string.html); + default is `''` + + The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + `executable`[bool](../core/bool.html); + default is `False` + + Set the executable flag on the created file, false by default. + `allow_fail`[bool](../core/bool.html); + default is `False` + + If set, indicate the error in the return value instead of raising an error for failed downloads. + + `canonical_id`[string](../core/string.html); + default is `''` + + If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum ( `sha256` or `integrity`). + + `auth`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying authentication information for some of the URLs. + `headers`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying http headers for all URLs. + `integrity`[string](../core/string.html); + default is `''` + + Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + `block`[bool](../core/bool.html); + default is `True` + + If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. + + ## download\_and\_extract ``` -struct repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth=\{\}, headers=\{\}, *, integrity='', rename_files=\{\}) +struct repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={}) ``` -Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](./rules/lib/repo/cache#get_default_canonical_id) - + Downloads a file to the output path for the provided url, extracts it, and returns a struct containing `success`, a flag which is `true` if the download completed successfully, and if successful, a hash of the file with the fields `sha256` and `integrity`. When `sha256` or `integrity` is user specified, setting an explicit `canonical_id` is highly recommended. e.g. [`get_default_canonical_id`](/rules/lib/repo/cache#get_default_canonical_id) ### Parameters -| Parameter | Description | -| --- | --- | -| `url` | [string](../core/string.mdx); or Iterable of [string](../core/string.mdx)s; required List of mirror URLs referencing the same file. | -| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` Path to the directory where the archive will be unpacked, relative to the repository directory. | -| `sha256` | [string](../core/string.mdx); default is `''` The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | -| `type` | [string](../core/string.mdx); default is `''` The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. | -| `strip_prefix` | [string](../core/string.mdx); default is `''` A directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the `build_file`, this field can be used to strip it from extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. | -| `allow_fail` | [bool](../core/bool.mdx); default is `False` If set, indicate the error in the return value instead of raising an error for failed downloads. | -| `canonical_id` | [string](../core/string.mdx); default is `''` If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum (`sha256` or `integrity`). | -| `auth` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying authentication information for some of the URLs. | -| `headers` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying http headers for all URLs. | -| `integrity` | [string](../core/string.mdx); default is `''` Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. | -| `rename_files` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. | +ParameterDescription`url`[string](../core/string.html); or Iterable of [string](../core/string.html) s; + required + + List of mirror URLs referencing the same file. + `output`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + default is `''` + + Path to the directory where the archive will be unpacked, relative to the repository directory. + + `sha256`[string](../core/string.html); + default is `''` + + The expected SHA-256 hash of the file downloaded. This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + + `type`[string](../core/string.html); + default is `''` + + The archive type of the downloaded file. By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify either "zip", "jar", "war", "aar", "nupkg", "whl", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. + + `strip_prefix`[string](../core/string.html); + default is `''` + + A directory prefix to strip from the extracted files. Many archives contain a +top-level directory that contains all files in the archive. Instead of needing to +specify this prefix over and over in the `build_file`, this field can +be used to strip it from extracted files. + +For compatibility, this parameter may also be used under the deprecated name +`stripPrefix`. + + + +`allow_fail`[bool](../core/bool.html); + default is `False` + + If set, indicate the error in the return value instead of raising an error for failed downloads. + + `canonical_id`[string](../core/string.html); + default is `''` + + If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum +( `sha256` or `integrity`). + + `auth`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying authentication information for some of the URLs. + `headers`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying http headers for all URLs. + `integrity`[string](../core/string.html); + default is `''` + + Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. + `rename_files`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. + + ## execute ``` -exec_result repository_ctx.execute(arguments, timeout=600, environment=\{\}, quiet=True, working_directory="") +exec_result repository_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="") ``` -Executes the command given by the list of arguments. The execution time of the command is limited by `timeout` (in seconds, default 600 seconds). This method returns an `exec_result` structure containing the output of the command. The `environment` map can be used to override some environment variables to be passed to the process. + Executes the command given by the list of arguments. The execution time of the command is limited by `timeout` (in seconds, default 600 seconds). This method returns an `exec_result` structure containing the output of the command. The `environment` map can be used to override some environment variables to be passed to the process. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `arguments` | [sequence](../core/list.mdx); required List of arguments, the first element should be the path to the program to execute. | -| `timeout` | [int](../core/int.mdx); default is `600` Maximum duration of the command in seconds (default is 600 seconds). | -| `environment` | [dict](../core/dict.mdx); default is `\{\}` Force some environment variables to be set to be passed to the process. The value can be `None` to remove the environment variable. | -| `quiet` | [bool](../core/bool.mdx); default is `True` If stdout and stderr should be printed to the terminal. | -| `working_directory` | [string](../core/string.mdx); default is `""` Working directory for command execution. Can be relative to the repository root or absolute. The default is the repository root. | +ParameterDescription`arguments`[sequence](../core/list.html); + required + + List of arguments, the first element should be the path to the program to execute. + + `timeout`[int](../core/int.html); + default is `600` + + Maximum duration of the command in seconds (default is 600 seconds). + `environment`[dict](../core/dict.html); + default is `{}` + + Force some environment variables to be set to be passed to the process. The value can be `None` to remove the environment variable. + + `quiet`[bool](../core/bool.html); + default is `True` + + If stdout and stderr should be printed to the terminal. + `working_directory`[string](../core/string.html); + default is `""` + + Working directory for command execution. +Can be relative to the repository root or absolute. +The default is the repository root. + + ## extract ``` -None repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files=\{\}, watch_archive='auto') +None repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto') ``` -Extract an archive to the repository directory. + Extract an archive to the repository directory. + ### Parameters -| Parameter | Description | -| --- | --- | -| `archive` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required path to the archive that will be unpacked, relative to the repository directory. | -| `output` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); default is `''` path to the directory where the archive will be unpacked, relative to the repository directory. | -| `strip_prefix` | [string](../core/string.mdx); default is `''` a directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the `build_file`, this field can be used to strip it from extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. | -| `rename_files` | [dict](../core/dict.mdx); default is `\{\}` An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. | -| `watch_archive` | [string](../core/string.mdx); default is `'auto'` whether to [watch](#watch) the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | +ParameterDescription`archive`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + path to the archive that will be unpacked, relative to the repository directory. + `output`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + default is `''` + + path to the directory where the archive will be unpacked, relative to the repository directory. + `strip_prefix`[string](../core/string.html); + default is `''` + + a directory prefix to strip from the extracted files. Many archives contain a +top-level directory that contains all files in the archive. Instead of needing to +specify this prefix over and over in the `build_file`, this field can be +used to strip it from extracted files. + +For compatibility, this parameter may also be used under the deprecated name +`stripPrefix`. + + + +`rename_files`[dict](../core/dict.html); + default is `{}` + + An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. + `watch_archive`[string](../core/string.html); + default is `'auto'` + + whether to [watch](#watch) the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. + ## file @@ -144,16 +277,29 @@ Extract an archive to the repository directory. None repository_ctx.file(path, content='', executable=True, legacy_utf8=False) ``` -Generates a file in the repository directory with the provided content. + Generates a file in the repository directory with the provided content. + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to create, relative to the repository directory. | -| `content` | [string](../core/string.mdx); default is `''` The content of the file to create, empty by default. | -| `executable` | [bool](../core/bool.mdx); default is `True` Set the executable flag on the created file, true by default. | -| `legacy_utf8` | [bool](../core/bool.mdx); default is `False` No-op. This parameter is deprecated and will be removed in a future version of Bazel. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path of the file to create, relative to the repository directory. + `content`[string](../core/string.html); + default is `''` + + The content of the file to create, empty by default. + `executable`[bool](../core/bool.html); + default is `True` + + Set the executable flag on the created file, true by default. + `legacy_utf8`[bool](../core/bool.html); + default is `False` + + No-op. This parameter is deprecated and will be removed in a future version of Bazel. + + ## getenv @@ -161,18 +307,26 @@ Generates a file in the repository directory with the provided content. string repository_ctx.getenv(name, default=None) ``` -Returns the value of an environment variable `name` as a string if exists, or `default` if it doesn't. + Returns the value of an environment variable `name` as a string if exists, or `default` if it doesn't. When building incrementally, any change to the value of the variable named by `name` will cause this repository to be re-fetched. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required Name of desired environment variable. | -| `default` | [string](../core/string.mdx); or `None`; default is `None` Default value to return if `name` is not found. | +ParameterDescription`name`[string](../core/string.html); + required + + Name of desired environment variable. + `default`[string](../core/string.html); or `None`; + default is `None` + + Default value to return if `name` is not found. + + May return `None`. + -May return `None`. ## name @@ -180,7 +334,9 @@ May return `None`. string repository_ctx.name ``` -The canonical name of the external repository created by this rule. This name is guaranteed to be unique among all external repositories, but its exact format is not specified. Use [`original_name`](#original_name) instead to get the name that was originally specified as the `name` when this repository rule was instantiated. + The canonical name of the external repository created by this rule. This name is guaranteed to be unique among all external repositories, but its exact format is not specified. Use [`original_name`](#original_name) instead to get the name that was originally specified as the `name` when this repository rule was instantiated. + + ## original\_name @@ -188,7 +344,9 @@ The canonical name of the external repository created by this rule. This name is string repository_ctx.original_name ``` -The name that was originally specified as the `name` attribute when this repository rule was instantiated. This name is not necessarily unique among external repositories. Use [`name`](#name) instead to get the canonical name of the external repository. + The name that was originally specified as the `name` attribute when this repository rule was instantiated. This name is not necessarily unique among external repositories. Use [`name`](#name) instead to get the canonical name of the external repository. + + ## os @@ -196,7 +354,9 @@ The name that was originally specified as the `name` attribute when this reposit repository_os repository_ctx.os ``` -A struct to access information from the system. + A struct to access information from the system. + + ## patch @@ -204,15 +364,27 @@ A struct to access information from the system. None repository_ctx.patch(patch_file, strip=0, *, watch_patch='auto') ``` -Apply a patch file to the root directory of external repository. The patch file should be a standard [unified diff format](https://en.wikipedia.org/wiki/Diff#Unified_format) file. The Bazel-native patch implementation doesn't support fuzz match and binary patch like the patch command line tool. + Apply a patch file to the root directory of external repository. The patch file should be a standard [unified diff format](https://en.wikipedia.org/wiki/Diff#Unified_format) file. The Bazel-native patch implementation doesn't support fuzz match and binary patch like the patch command line tool. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `patch_file` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The patch file to apply, it can be label, relative path or absolute path. If it's a relative path, it will resolve to the repository directory. | -| `strip` | [int](../core/int.mdx); default is `0` Strip the specified number of leading components from file names. | -| `watch_patch` | [string](../core/string.mdx); default is `'auto'` Whether to [watch](#watch) the patch file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | +ParameterDescription`patch_file`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + The patch file to apply, it can be label, relative path or absolute path. If it's a relative path, it will resolve to the repository directory. + + `strip`[int](../core/int.html); + default is `0` + + Strip the specified number of leading components from file names. + `watch_patch`[string](../core/string.html); + default is `'auto'` + + Whether to [watch](#watch) the patch file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. + + ## path @@ -220,13 +392,17 @@ Apply a patch file to the root directory of external repository. The patch file path repository_ctx.path(path) ``` -Returns a path from a string, label, or path. If this context is a `repository_ctx`, a relative path will resolve relative to the repository directory. If it is a `module_ctx`, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. + Returns a path from a string, label, or path. If this context is a `repository_ctx`, a relative path will resolve relative to the repository directory. If it is a `module_ctx`, a relative path will resolve relative to a temporary working directory for this module extension. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories and module extensions are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required `string`, `Label` or `path` from which to create a path from. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + +`string`, `Label` or `path` from which to create a path from. + ## read @@ -234,14 +410,21 @@ Returns a path from a string, label, or path. If this context is a `repository_c string repository_ctx.read(path, *, watch='auto') ``` -Reads the content of a file on the filesystem. + Reads the content of a file on the filesystem. + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to read from. | -| `watch` | [string](../core/string.mdx); default is `'auto'` Whether to [watch](#watch) the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path of the file to read from. + `watch`[string](../core/string.html); + default is `'auto'` + + Whether to [watch](#watch) the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. + + ## rename @@ -249,30 +432,54 @@ Reads the content of a file on the filesystem. None repository_ctx.rename(src, dst) ``` -Renames the file or directory from `src` to `dst`. Parent directories are created as needed. Fails if the destination path + Renames the file or directory from `src` to `dst`. Parent directories are created as needed. Fails if the destination path already exists. Both paths must be located within the repository. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `src` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The path of the existing file or directory to rename, relative to the repository directory. | -| `dst` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The new name to which the file or directory will be renamed to, relative to the repository directory. | +ParameterDescription`src`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + The path of the existing file or directory to rename, relative +to the repository directory. + + `dst`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + The new name to which the file or directory will be renamed to, +relative to the repository directory. + + ## repo\_metadata ``` -repo_metadata repository_ctx.repo_metadata(*, reproducible=False, attrs_for_reproducibility=\{\}) +repo_metadata repository_ctx.repo_metadata(*, reproducible=False, attrs_for_reproducibility={}) ``` -Constructs an opaque object that can be returned from the repo rule's implementation function to provide metadata about its reproducibility. + Constructs an opaque object that can be returned from the repo rule's implementation function to provide metadata about its reproducibility. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `reproducible` | [bool](../core/bool.mdx); default is `False` States that this repo can be reproducibly refetched; that is, if it were fetched another time with exactly the same input attributes, repo rule definition, watched files and environment variables, etc., then exactly the same output would be produced. This property needs to hold even if other untracked conditions change, such as information from the internet, the path of the workspace root, output from running arbitrary executables, etc. If set to True, this allows the fetched repo contents to be cached across workspaces. Note that setting this to True does not guarantee caching in the repo contents cache; for example, local repo rules are never cached. | -| `attrs_for_reproducibility` | [dict](../core/dict.mdx); default is `\{\}` If `reproducible` is False, this can be specified to tell Bazel which attributes of the original repo rule to change to make it reproducible. | +ParameterDescription`reproducible`[bool](../core/bool.html); + default is `False` + + States that this repo can be reproducibly refetched; that is, if it were fetched another time with exactly the same input attributes, repo rule definition, watched files and environment variables, etc., then exactly the same output would be produced. This property needs to hold even if other untracked conditions change, such as information from the internet, the path of the workspace root, output from running arbitrary executables, etc. If set to True, this allows the fetched repo contents to be cached across workspaces. + +Note that setting this to True does not guarantee caching in the repo contents cache; for example, local repo rules are never cached. + + + +`attrs_for_reproducibility`[dict](../core/dict.html); + default is `{}` + + If `reproducible` is False, this can be specified to tell Bazel which attributes of the original repo rule to change to make it reproducible. + + ## report\_progress @@ -280,13 +487,16 @@ Constructs an opaque object that can be returned from the repo rule's implementa None repository_ctx.report_progress(status='') ``` -Updates the progress status for the fetching of this repository or module extension. + Updates the progress status for the fetching of this repository or module extension. + ### Parameters -| Parameter | Description | -| --- | --- | -| `status` | [string](../core/string.mdx); default is `''` `string` describing the current status of the fetch progress. | +ParameterDescription`status`[string](../core/string.html); + default is `''` + +`string` describing the current status of the fetch progress. + ## symlink @@ -294,32 +504,55 @@ Updates the progress status for the fetching of this repository or module extens None repository_ctx.symlink(target, link_name) ``` -Creates a symlink on the filesystem. + Creates a symlink on the filesystem. + ### Parameters -| Parameter | Description | -| --- | --- | -| `target` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The path that the symlink should point to. | -| `link_name` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required The path of the symlink to create. | +ParameterDescription`target`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + The path that the symlink should point to. + `link_name`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + The path of the symlink to create. + ## template ``` -None repository_ctx.template(path, template, substitutions=\{\}, executable=True, *, watch_template='auto') +None repository_ctx.template(path, template, substitutions={}, executable=True, *, watch_template='auto') ``` -Generates a new file using a `template`. Every occurrence in `template` of a key of `substitutions` will be replaced by the corresponding value. The result is written in `path`. An optional `executable` argument (default to true) can be set to turn on or off the executable bit. + Generates a new file using a `template`. Every occurrence in `template` of a key of `substitutions` will be replaced by the corresponding value. The result is written in `path`. An optional `executable` argument (default to true) can be set to turn on or off the executable bit. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to create, relative to the repository directory. | -| `template` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path to the template file. | -| `substitutions` | [dict](../core/dict.mdx); default is `\{\}` Substitutions to make when expanding the template. | -| `executable` | [bool](../core/bool.mdx); default is `True` Set the executable flag on the created file, true by default. | -| `watch_template` | [string](../core/string.mdx); default is `'auto'` Whether to [watch](#watch) the template file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path of the file to create, relative to the repository directory. + `template`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path to the template file. + `substitutions`[dict](../core/dict.html); + default is `{}` + + Substitutions to make when expanding the template. + `executable`[bool](../core/bool.html); + default is `True` + + Set the executable flag on the created file, true by default. + `watch_template`[string](../core/string.html); + default is `'auto'` + + Whether to [watch](#watch) the template file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the [`watch()`](#watch) method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see `watch()` docs for more information. + + ## watch @@ -327,17 +560,21 @@ Generates a new file using a `template`. Every occurrence in `template` of a key None repository_ctx.watch(path) ``` -Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time. + Tells Bazel to watch for changes to the given path, whether or not it exists, or whether it's a file or a directory. Any changes to the file or directory will invalidate this repository or module extension, and cause it to be refetched or re-evaluated next time. -"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does *not* include changes to any files under the directory if the path is a directory. For that, use [`path.readdir()`](path.html#readdir) instead. +"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does _not_ include changes to any files under the directory if the path is a directory. For that, use [`path.readdir()`](path.html#readdir) instead. Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the file to watch. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path of the file to watch. + ## watch\_tree @@ -345,15 +582,19 @@ Note that attempting to watch paths inside the repo currently being fetched, or None repository_ctx.watch_tree(path) ``` -Tells Bazel to watch for changes to any files or directories transitively under the given path. Any changes to the contents of files, the existence of files or directories, file names or directory names, will cause this repo to be refetched. + Tells Bazel to watch for changes to any files or directories transitively under the given path. Any changes to the contents of files, the existence of files or directories, file names or directory names, will cause this repo to be refetched. Note that attempting to watch paths inside the repo currently being fetched will result in an error. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); or [path](../builtins/path.mdx); required Path of the directory tree to watch. | +ParameterDescription`path`[string](../core/string.html); or [Label](../builtins/Label.html); or [path](../builtins/path.html); + required + + Path of the directory tree to watch. + ## which @@ -361,15 +602,20 @@ Note that attempting to watch paths inside the repo currently being fetched will path repository_ctx.which(program) ``` -Returns the `path` of the corresponding program or `None` if there is no such program in the path. + Returns the `path` of the corresponding program or `None` if there is no such program in the path. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `program` | [string](../core/string.mdx); required Program to find in the path. | +ParameterDescription`program`[string](../core/string.html); + required + + Program to find in the path. + + May return `None`. + -May return `None`. ## workspace\_root @@ -377,4 +623,4 @@ May return `None`. path repository_ctx.workspace_root ``` -The path to the root workspace of the bazel invocation. \ No newline at end of file + The path to the root workspace of the bazel invocation. diff --git a/rules/lib/builtins/repository_os.mdx b/rules/lib/builtins/repository_os.mdx index baac91e..9514f13 100644 --- a/rules/lib/builtins/repository_os.mdx +++ b/rules/lib/builtins/repository_os.mdx @@ -1,15 +1,16 @@ --- -title: 'repository_os' +title: 'repository\_os' --- + Various data about the current platform Bazel is running on. ## Members -* [arch](#arch) -* [environ](#environ) -* [name](#name) +- [arch](#arch) +- [environ](#environ) +- [name](#name) ## arch @@ -17,7 +18,9 @@ Various data about the current platform Bazel is running on. string repository_os.arch ``` -A string identifying the architecture Bazel is running on (the value of the `"os.arch"` Java property converted to lower case). + A string identifying the architecture Bazel is running on (the value of the `"os.arch"` Java property converted to lower case). + + ## environ @@ -25,14 +28,16 @@ A string identifying the architecture Bazel is running on (the value of the `"os dict repository_os.environ ``` -The dictionary of environment variables. + The dictionary of environment variables. **NOTE**: Retrieving an environment variable from this dictionary does not establish a dependency from a repository rule or module extension to the environment variable. To establish a dependency when looking up an environment variable, use either `repository_ctx.getenv` or `module_ctx.getenv` instead. + + ## name ``` string repository_os.name ``` -A string identifying the operating system Bazel is running on (the value of the `"os.name"` Java property converted to lower case). \ No newline at end of file + A string identifying the operating system Bazel is running on (the value of the `"os.name"` Java property converted to lower case). diff --git a/rules/lib/builtins/repository_rule.mdx b/rules/lib/builtins/repository_rule.mdx index 269be17..935811a 100644 --- a/rules/lib/builtins/repository_rule.mdx +++ b/rules/lib/builtins/repository_rule.mdx @@ -1,6 +1,7 @@ --- -title: 'repository_rule' +title: 'repository\_rule' --- -A callable value that may be invoked within the implementation function of a module extension to instantiate and return a repository rule. Created by [`repository_rule()`](../globals/bzl.html#repository_rule). \ No newline at end of file + +A callable value that may be invoked within the implementation function of a module extension to instantiate and return a repository rule. Created by [`repository_rule()`](../globals/bzl.html#repository_rule). diff --git a/rules/lib/builtins/root.mdx b/rules/lib/builtins/root.mdx index 43fe0d5..fe266c6 100644 --- a/rules/lib/builtins/root.mdx +++ b/rules/lib/builtins/root.mdx @@ -3,11 +3,12 @@ title: 'root' --- + A root for files. The roots are the directories containing files, and they are mapped together into a single directory tree to form the execution environment. ## Members -* [path](#path) +- [path](#path) ## path @@ -15,4 +16,4 @@ A root for files. The roots are the directories containing files, and they are m string root.path ``` -Returns the relative path from the exec root to the actual root. \ No newline at end of file + Returns the relative path from the exec root to the actual root. diff --git a/rules/lib/builtins/rule.mdx b/rules/lib/builtins/rule.mdx index cd2e123..e2550b7 100644 --- a/rules/lib/builtins/rule.mdx +++ b/rules/lib/builtins/rule.mdx @@ -3,8 +3,9 @@ title: 'rule' --- + A callable value representing the type of a native or Starlark rule (created by [`rule()`](../globals/bzl.html#rule)). Calling the value during evaluation of a package's BUILD file creates an instance of the rule and adds it to the package's target set. For more information, visit this page about -[Rules](https://bazel.build/extending/rules). \ No newline at end of file +[Rules](https://bazel.build/extending/rules). diff --git a/rules/lib/builtins/rule_attributes.mdx b/rules/lib/builtins/rule_attributes.mdx index 91d9d68..0b2cbd1 100644 --- a/rules/lib/builtins/rule_attributes.mdx +++ b/rules/lib/builtins/rule_attributes.mdx @@ -1,20 +1,21 @@ --- -title: 'rule_attributes' +title: 'rule\_attributes' --- + Information about attributes of a rule an aspect is applied to. ## Members -* [attr](#attr) -* [exec\_groups](#exec_groups) -* [executable](#executable) -* [file](#file) -* [files](#files) -* [kind](#kind) -* [toolchains](#toolchains) -* [var](#var) +- [attr](#attr) +- [exec\_groups](#exec_groups) +- [executable](#executable) +- [file](#file) +- [files](#files) +- [kind](#kind) +- [toolchains](#toolchains) +- [var](#var) ## attr @@ -22,7 +23,9 @@ Information about attributes of a rule an aspect is applied to. struct rule_attributes.attr ``` -A struct to access the values of the [attributes](https://bazel.build/extending/rules#attributes). The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the [`attrs` dict](../globals/bzl.html#rule.attrs) provided to the [`rule` function](../globals/bzl.html#rule). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl). + A struct to access the values of the [attributes](https://bazel.build/extending/rules#attributes). The values are provided by the user (if not, a default value is used). The attributes of the struct and the types of their values correspond to the keys and values of the [`attrs` dict](../globals/bzl.html#rule.attrs) provided to the [`rule` function](../globals/bzl.html#rule). [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl). + + ## exec\_groups @@ -30,7 +33,9 @@ A struct to access the values of the [attributes](https://bazel.build/extending/ ExecGroupCollection rule_attributes.exec_groups ``` -A collection of the execution groups available for the rule the aspect is applied to, indexed by their names. + A collection of the execution groups available for the rule the aspect is applied to, indexed by their names. + + ## executable @@ -38,7 +43,9 @@ A collection of the execution groups available for the rule the aspect is applie struct rule_attributes.executable ``` -A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.mdx) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). + A `struct` containing executable files defined in [label type attributes](../toplevel/attr.html#label) marked as [`executable=True`](../toplevel/attr.html#label.executable). The struct fields correspond to the attribute names. Each value in the struct is either a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `executable=True`, no corresponding struct field is generated. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl). + + ## file @@ -46,27 +53,31 @@ A `struct` containing executable files defined in [label type attributes](../top struct rule_attributes.file ``` -A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.mdx) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: + A `struct` containing files defined in [label type attributes](../toplevel/attr.html#label) marked as [`allow_single_file`](../toplevel/attr.html#label.allow_single_file). The struct fields correspond to the attribute names. The struct value is always a [`File`](../builtins/File.html) or `None`. If an optional attribute is not specified in the rule then the corresponding struct value is `None`. If a label type is not marked as `allow_single_file`, no corresponding struct field is generated. It is a shortcut for: ``` -list(ctx.attr.\<ATTR\>.files)[0] +list(ctx.attr.<ATTR>.files)[0] ``` In other words, use `file` to access the (singular) [default output](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl). + + ## files ``` struct rule_attributes.files ``` -A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.mdx)s. It is a shortcut for: + A `struct` containing files defined in [label](../toplevel/attr.html#label) or [label list](../toplevel/attr.html#label_list) type attributes. The struct fields correspond to the attribute names. The struct values are `list` of [`File`](../builtins/File.html) s. It is a shortcut for: ``` -[f for t in ctx.attr.\<ATTR\> for f in t.files] +[f for t in ctx.attr.<ATTR> for f in t.files] ``` -In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). + In other words, use `files` to access the [default outputs](https://bazel.build/extending/rules#requesting_output_files) of a dependency. [See example of use](https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl). + + ## kind @@ -74,7 +85,9 @@ In other words, use `files` to access the [default outputs](https://bazel.build string rule_attributes.kind ``` -The kind of a rule, such as 'cc\_library' + The kind of a rule, such as 'cc\_library' + + ## toolchains @@ -82,7 +95,9 @@ The kind of a rule, such as 'cc\_library' ToolchainContext rule_attributes.toolchains ``` -Toolchains for the default exec group of the rule the aspect is applied to. + Toolchains for the default exec group of the rule the aspect is applied to. + + ## var @@ -90,4 +105,4 @@ Toolchains for the default exec group of the rule the aspect is applied to. dict rule_attributes.var ``` -Dictionary (String to String) of configuration variables. \ No newline at end of file + Dictionary (String to String) of configuration variables. diff --git a/rules/lib/builtins/runfiles.mdx b/rules/lib/builtins/runfiles.mdx index a14b8a8..0dc5844 100644 --- a/rules/lib/builtins/runfiles.mdx +++ b/rules/lib/builtins/runfiles.mdx @@ -3,18 +3,19 @@ title: 'runfiles' --- -A container of information regarding a set of files required at runtime by an executable. This object should be passed via [`DefaultInfo`](../providers/DefaultInfo.mdx) in order to tell the build system about the runfiles needed by the outputs produced by the rule. + +A container of information regarding a set of files required at runtime by an executable. This object should be passed via [`DefaultInfo`](../providers/DefaultInfo.html) in order to tell the build system about the runfiles needed by the outputs produced by the rule. See [runfiles guide](https://bazel.build/extending/rules#runfiles) for details. ## Members -* [empty\_filenames](#empty_filenames) -* [files](#files) -* [merge](#merge) -* [merge\_all](#merge_all) -* [root\_symlinks](#root_symlinks) -* [symlinks](#symlinks) +- [empty\_filenames](#empty_filenames) +- [files](#files) +- [merge](#merge) +- [merge\_all](#merge_all) +- [root\_symlinks](#root_symlinks) +- [symlinks](#symlinks) ## empty\_filenames @@ -22,7 +23,9 @@ See [runfiles guide](https://bazel.build/extending/rules#runfiles) for details. depset runfiles.empty_filenames ``` -Returns names of empty files to create. + Returns names of empty files to create. + + ## files @@ -30,7 +33,9 @@ Returns names of empty files to create. depset runfiles.files ``` -Returns the set of runfiles as files. + Returns the set of runfiles as files. + + ## merge @@ -38,15 +43,17 @@ Returns the set of runfiles as files. runfiles runfiles.merge(other) ``` -Returns a new runfiles object that includes all the contents of this one and the argument. + Returns a new runfiles object that includes all the contents of this one and the argument. -*Note:* When you have many runfiles objects to merge, use [`merge_all()`](#merge_all) rather than calling `merge` in a loop. This avoids constructing deep depset structures which can cause build failures. +_Note:_ When you have many runfiles objects to merge, use [`merge_all()`](#merge_all) rather than calling `merge` in a loop. This avoids constructing deep depset structures which can cause build failures. ### Parameters -| Parameter | Description | -| --- | --- | -| `other` | [runfiles](../builtins/runfiles.mdx); required The runfiles object to merge into this. | +ParameterDescription`other`[runfiles](../builtins/runfiles.html); + required + + The runfiles object to merge into this. + ## merge\_all @@ -54,13 +61,17 @@ Returns a new runfiles object that includes all the contents of this one and the runfiles runfiles.merge_all(other) ``` -Returns a new runfiles object that includes all the contents of this one and of the runfiles objects in the argument. + Returns a new runfiles object that includes all the contents of this one and of the runfiles objects in the argument. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `other` | [sequence](../core/list.mdx) of [runfiles](../builtins/runfiles.mdx)s; required The sequence of runfiles objects to merge into this. | +ParameterDescription`other`[sequence](../core/list.html) of [runfiles](../builtins/runfiles.html) s; + required + + The sequence of runfiles objects to merge into this. + ## root\_symlinks @@ -68,7 +79,9 @@ Returns a new runfiles object that includes all the contents of this one and of depset runfiles.root_symlinks ``` -Returns the set of root symlinks. + Returns the set of root symlinks. + + ## symlinks @@ -76,4 +89,4 @@ Returns the set of root symlinks. depset runfiles.symlinks ``` -Returns the set of symlinks. \ No newline at end of file + Returns the set of symlinks. diff --git a/rules/lib/builtins/struct.mdx b/rules/lib/builtins/struct.mdx index eb8d04b..deaa939 100644 --- a/rules/lib/builtins/struct.mdx +++ b/rules/lib/builtins/struct.mdx @@ -3,13 +3,14 @@ title: 'struct' --- + A generic object with fields. Structs fields cannot be reassigned once the struct is created. Two structs are equal if they have the same fields and if corresponding field values are equal. ## Members -* [struct](#struct) +- [struct](#struct) ## struct @@ -17,7 +18,7 @@ Structs fields cannot be reassigned once the struct is created. Two structs are struct struct(**kwargs) ``` -Creates an immutable struct using the keyword arguments as attributes. It is used to group multiple values together. Example: + Creates an immutable struct using the keyword arguments as attributes. It is used to group multiple values together. Example: ``` s = struct(x = 2, y = 3) @@ -26,6 +27,7 @@ return s.x + getattr(s, "y") # returns 5 ### Parameters -| Parameter | Description | -| --- | --- | -| `kwargs` | default is `\{\}` | \ No newline at end of file +ParameterDescription`kwargs` + default is `{}` + + Dictionary of arguments. diff --git a/rules/lib/builtins/subrule_ctx.mdx b/rules/lib/builtins/subrule_ctx.mdx index cb82a90..3783076 100644 --- a/rules/lib/builtins/subrule_ctx.mdx +++ b/rules/lib/builtins/subrule_ctx.mdx @@ -1,16 +1,17 @@ --- -title: 'subrule_ctx' +title: 'subrule\_ctx' --- + A context object passed to the implementation function of a subrule. ## Members -* [actions](#actions) -* [fragments](#fragments) -* [label](#label) -* [toolchains](#toolchains) +- [actions](#actions) +- [fragments](#fragments) +- [label](#label) +- [toolchains](#toolchains) ## actions @@ -18,7 +19,9 @@ A context object passed to the implementation function of a subrule. actions subrule_ctx.actions ``` -Contains methods for declaring output files and the actions that produce them + Contains methods for declaring output files and the actions that produce them + + ## fragments @@ -26,7 +29,9 @@ Contains methods for declaring output files and the actions that produce them fragments subrule_ctx.fragments ``` -Allows access to configuration fragments in target configuration. + Allows access to configuration fragments in target configuration. + + ## label @@ -34,7 +39,9 @@ Allows access to configuration fragments in target configuration. Label subrule_ctx.label ``` -The label of the target currently being analyzed + The label of the target currently being analyzed + + ## toolchains @@ -42,4 +49,4 @@ The label of the target currently being analyzed ToolchainContext subrule_ctx.toolchains ``` -Contains methods for declaring output files and the actions that produce them \ No newline at end of file + Contains methods for declaring output files and the actions that produce them diff --git a/rules/lib/builtins/tag_class.mdx b/rules/lib/builtins/tag_class.mdx index 2014823..b8830d6 100644 --- a/rules/lib/builtins/tag_class.mdx +++ b/rules/lib/builtins/tag_class.mdx @@ -1,6 +1,7 @@ --- -title: 'tag_class' +title: 'tag\_class' --- -Defines a schema of attributes for a tag, created by [`tag_class()`](../globals/bzl.html#tag_class). \ No newline at end of file + +Defines a schema of attributes for a tag, created by [`tag_class()`](../globals/bzl.html#tag_class). diff --git a/rules/lib/builtins/template_ctx.mdx b/rules/lib/builtins/template_ctx.mdx index cc8078f..93c749b 100644 --- a/rules/lib/builtins/template_ctx.mdx +++ b/rules/lib/builtins/template_ctx.mdx @@ -1,15 +1,16 @@ --- -title: 'template_ctx' +title: 'template\_ctx' --- + A context object that is passed to the action template expansion function. ## Members -* [args](#args) -* [declare\_file](#declare_file) -* [run](#run) +- [args](#args) +- [declare\_file](#declare_file) +- [run](#run) ## args @@ -17,7 +18,9 @@ A context object that is passed to the action template expansion function. Args template_ctx.args() ``` -Returns an Args object that can be used to build memory-efficient command lines. + Returns an Args object that can be used to build memory-efficient command lines. + + ## declare\_file @@ -25,16 +28,22 @@ Returns an Args object that can be used to build memory-efficient command lines. File template_ctx.declare_file(filename, *, directory) ``` -Declares that implementation creates a file with the given filename within the specified directory. + Declares that implementation creates a file with the given filename within the specified directory. Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned `File` object to the action's construction function. + ### Parameters -| Parameter | Description | -| --- | --- | -| `filename` | [string](../core/string.mdx); required The relative path of the file within the directory. | -| `directory` | [File](../builtins/File.mdx); required The directory in which the file should be created. | +ParameterDescription`filename`[string](../core/string.html); + required + + The relative path of the file within the directory. + `directory`[File](../builtins/File.html); + required + + The directory in which the file should be created. + ## run @@ -42,15 +51,41 @@ Remember that in addition to declaring a file, you must separately create an act None template_ctx.run(*, outputs, inputs=[], executable, tools=None, arguments=[], progress_message=None) ``` -Creates an action that runs an executable. + Creates an action that runs an executable. + ### Parameters -| Parameter | Description | -| --- | --- | -| `outputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; required List of the output files of the action. | -| `inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or [depset](../builtins/depset.mdx); default is `[]` List or depset of the input files of the action. | -| `executable` | [File](../builtins/File.mdx); or [string](../core/string.mdx); or [FilesToRunProvider](../providers/FilesToRunProvider.mdx); required The executable file to be called by the action. | -| `tools` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); or `None`; default is `None` List or [`depset`](../builtins/depset.mdx) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. When a list is provided, it can be a heterogenous collection of: * `File`s * `FilesToRunProvider` instances * `depset`s of `File`s `File`s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider`s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. | -| `arguments` | [sequence](../core/list.mdx); default is `[]` Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. | -| `progress_message` | [string](../core/string.mdx); or `None`; default is `None` Progress message to show to the user during the build. | \ No newline at end of file +ParameterDescription`outputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; + required + + List of the output files of the action. + `inputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; or [depset](../builtins/depset.html); + default is `[]` + + List or depset of the input files of the action. + `executable`[File](../builtins/File.html); or [string](../core/string.html); or [FilesToRunProvider](../providers/FilesToRunProvider.html); + required + + The executable file to be called by the action. + `tools`[sequence](../core/list.html); or [depset](../builtins/depset.html); or `None`; + default is `None` + + List or [`depset`](../builtins/depset.html) of any tools needed by the action. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. + +When a list is provided, it can be a heterogenous collection of: + +- `File` s +- `FilesToRunProvider` instances +- `depset` s of `File` s + +`File` s from [`ctx.executable`](../builtins/ctx#executable) and `FilesToRunProvider` s which are directly in the list will have their runfiles automatically added. All tools are implicitly added as inputs. + +`arguments`[sequence](../core/list.html); + default is `[]` + + Command line arguments of the action. Must be a list of strings or [`actions.args()`](#args) objects. + `progress_message`[string](../core/string.html); or `None`; + default is `None` + + Progress message to show to the user during the build. diff --git a/rules/lib/builtins/toolchain_type.mdx b/rules/lib/builtins/toolchain_type.mdx index d5c67a9..abcf4b1 100644 --- a/rules/lib/builtins/toolchain_type.mdx +++ b/rules/lib/builtins/toolchain_type.mdx @@ -1,14 +1,15 @@ --- -title: 'toolchain_type' +title: 'toolchain\_type' --- + A data type describing a dependency on a specific toolchain type. ## Members -* [mandatory](#mandatory) -* [toolchain\_type](#toolchain_type) +- [mandatory](#mandatory) +- [toolchain\_type](#toolchain_type) ## mandatory @@ -16,7 +17,9 @@ A data type describing a dependency on a specific toolchain type. bool toolchain_type.mandatory ``` -Whether the toolchain type is mandatory or optional. + Whether the toolchain type is mandatory or optional. + + ## toolchain\_type @@ -24,4 +27,4 @@ Whether the toolchain type is mandatory or optional. Label toolchain_type.toolchain_type ``` -The toolchain type that is required. \ No newline at end of file + The toolchain type that is required. diff --git a/rules/lib/builtins/transition.mdx b/rules/lib/builtins/transition.mdx index 520b936..e104906 100644 --- a/rules/lib/builtins/transition.mdx +++ b/rules/lib/builtins/transition.mdx @@ -3,11 +3,12 @@ title: 'transition' --- + Represents a configuration transition across a dependency edge. For example, if `//package:foo` depends on `//package:bar` with a configuration transition, then the configuration of `//package:bar` (and its dependencies) will be `//package:foo`'s configuration plus the changes specified by the transition function. ## Members -* [transition](#transition) +- [transition](#transition) ## transition @@ -15,7 +16,7 @@ Represents a configuration transition across a dependency edge. For example, if transition transition(*, implementation, inputs, outputs) ``` -A transition that reads a set of input build settings and writes a set of output build settings. + A transition that reads a set of input build settings and writes a set of output build settings. Example: @@ -24,7 +25,7 @@ def _transition_impl(settings, attr): # This transition just reads the current CPU value as a demonstration. # A real transition could incorporate this into its followup logic. current_cpu = settings["//command_line_option:cpu"] - return \{"//command_line_option:compilation_mode": "dbg"\} + return {"//command_line_option:compilation_mode": "dbg"} build_in_debug_mode = transition( implementation = _transition_impl, @@ -37,8 +38,22 @@ For more details see [here](https://bazel.build/rules/config#user-defined-transi ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | callable; required The function implementing this transition. This function always has two parameters: `settings` and `attr`. The `settings` param is a dictionary whose set of keys is defined by the inputs parameter. So, for each build setting `--//foo=bar`, if `inputs` contains `//foo`, `settings` will have an entry `settings['//foo']='bar'`. The `attr` param is a reference to `ctx.attr`. This gives the implementation function access to the rule's attributes to make attribute-parameterized transitions possible. This function must return a `dict` from build setting identifier to build setting value; this represents the configuration transition: for each entry in the returned `dict`, the transition updates that setting to the new value. All other settings are unchanged. This function can also return a `list` of `dict`s or a `dict` of `dict`s in the case of a split transition. | -| `inputs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required List of build settings that can be read by this transition. This becomes the key set of the settings parameter of the implementation function parameter. | -| `outputs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required List of build settings that can be written by this transition. This must be a superset of the key set of the dictionary returned by this transition. | \ No newline at end of file +ParameterDescription`implementation` + callable; + required + + The function implementing this transition. This function always has two parameters: `settings` and `attr`. The `settings` param is a dictionary whose set of keys is defined by the inputs parameter. So, for each build setting `--//foo=bar`, if `inputs` contains `//foo`, `settings` will have an entry `settings['//foo']='bar'`. + +The `attr` param is a reference to `ctx.attr`. This gives the implementation function access to the rule's attributes to make attribute-parameterized transitions possible. + +This function must return a `dict` from build setting identifier to build setting value; this represents the configuration transition: for each entry in the returned `dict`, the transition updates that setting to the new value. All other settings are unchanged. This function can also return a `list` of `dict` s or a `dict` of `dict` s in the case of a split transition. + + +`inputs`[sequence](../core/list.html) of [string](../core/string.html) s; + required + + List of build settings that can be read by this transition. This becomes the key set of the settings parameter of the implementation function parameter. + `outputs`[sequence](../core/list.html) of [string](../core/string.html) s; + required + + List of build settings that can be written by this transition. This must be a superset of the key set of the dictionary returned by this transition. diff --git a/rules/lib/builtins/wasm_exec_result.mdx b/rules/lib/builtins/wasm_exec_result.mdx index 7d2c4ae..f3e1642 100644 --- a/rules/lib/builtins/wasm_exec_result.mdx +++ b/rules/lib/builtins/wasm_exec_result.mdx @@ -1,8 +1,9 @@ --- -title: 'wasm_exec_result' +title: 'wasm\_exec\_result' --- + The result of executing a WebAssembly function with `repository_ctx.execute_wasm()`. It contains the function's return value and output buffer. @@ -12,9 +13,9 @@ and the `error_message` field will be set. ## Members -* [error\_message](#error_message) -* [output](#output) -* [return\_code](#return_code) +- [error\_message](#error_message) +- [output](#output) +- [return\_code](#return_code) ## error\_message @@ -22,7 +23,9 @@ and the `error_message` field will be set. string wasm_exec_result.error_message ``` -Contains an error message if execution failed before the function returned. + Contains an error message if execution failed before the function returned. + + ## output @@ -30,7 +33,9 @@ Contains an error message if execution failed before the function returned. string wasm_exec_result.output ``` -The content of the output buffer returned by the WebAssembly function. + The content of the output buffer returned by the WebAssembly function. + + ## return\_code @@ -38,5 +43,5 @@ The content of the output buffer returned by the WebAssembly function. long wasm_exec_result.return_code ``` -The return value of the WebAssembly function, or a negative value if execution -was terminated before the function returned. \ No newline at end of file + The return value of the WebAssembly function, or a negative value if execution +was terminated before the function returned. diff --git a/rules/lib/builtins/wasm_module.mdx b/rules/lib/builtins/wasm_module.mdx index c0e6fa1..bfcf852 100644 --- a/rules/lib/builtins/wasm_module.mdx +++ b/rules/lib/builtins/wasm_module.mdx @@ -1,13 +1,14 @@ --- -title: 'wasm_module' +title: 'wasm\_module' --- + A WebAssembly module loaded by `repository_ctx.load_wasm()`. ## Members -* [path](#path) +- [path](#path) ## path @@ -15,4 +16,4 @@ A WebAssembly module loaded by `repository_ctx.load_wasm()`. unknown wasm_module.path ``` -The path this WebAssembly module was loaded from. \ No newline at end of file + The path this WebAssembly module was loaded from. diff --git a/rules/lib/core.mdx b/rules/lib/core.mdx index fa6f884..91481d5 100644 --- a/rules/lib/core.mdx +++ b/rules/lib/core.mdx @@ -1,19 +1,19 @@ --- -title: 'core' +title: 'Core Starlark data types' --- This section lists the data types of the [Starlark core language](https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions). With some exceptions, these type names are not valid Starlark symbols; instances of them may be acquired through different means. -* [bool](./rules/lib/core/bool) -* [builtin\_function\_or\_method](./rules/lib/core/builtin_function_or_method) -* [dict](./rules/lib/core/dict) -* [float](./rules/lib/core/float) -* [function](./rules/lib/core/function) -* [int](./rules/lib/core/int) -* [json](./rules/lib/core/json) -* [list](./rules/lib/core/list) -* [range](./rules/lib/core/range) -* [set](./rules/lib/core/set) -* [string](./rules/lib/core/string) -* [tuple](./rules/lib/core/tuple) \ No newline at end of file +- [bool](/rules/lib/core/bool) +- [builtin\_function\_or\_method](/rules/lib/core/builtin_function_or_method) +- [dict](/rules/lib/core/dict) +- [float](/rules/lib/core/float) +- [function](/rules/lib/core/function) +- [int](/rules/lib/core/int) +- [json](/rules/lib/core/json) +- [list](/rules/lib/core/list) +- [range](/rules/lib/core/range) +- [set](/rules/lib/core/set) +- [string](/rules/lib/core/string) +- [tuple](/rules/lib/core/tuple) diff --git a/rules/lib/core/bool.mdx b/rules/lib/core/bool.mdx index 1d30674..5d7ec2e 100644 --- a/rules/lib/core/bool.mdx +++ b/rules/lib/core/bool.mdx @@ -3,4 +3,5 @@ title: 'bool' --- -A type to represent booleans. There are only two possible values: True and False. Any value can be converted to a boolean using the [bool](../globals/all.html#bool) function. \ No newline at end of file + +A type to represent booleans. There are only two possible values: True and False. Any value can be converted to a boolean using the [bool](../globals/all.html#bool) function. diff --git a/rules/lib/core/builtin_function_or_method.mdx b/rules/lib/core/builtin_function_or_method.mdx index f930792..d1fa73c 100644 --- a/rules/lib/core/builtin_function_or_method.mdx +++ b/rules/lib/core/builtin_function_or_method.mdx @@ -1,6 +1,7 @@ --- -title: 'builtin_function_or_method' +title: 'builtin\_function\_or\_method' --- -The type of a built-in function, defined by Java code. \ No newline at end of file + +The type of a built-in function, defined by Java code. diff --git a/rules/lib/core/dict.mdx b/rules/lib/core/dict.mdx index f514c82..7060b75 100644 --- a/rules/lib/core/dict.mdx +++ b/rules/lib/core/dict.mdx @@ -3,47 +3,58 @@ title: 'dict' --- -dict is a built-in type representing an associative mapping or *dictionary*. A dictionary supports indexing using `d[k]` and key membership testing using `k in d`; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to `d[k]` or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key. + +dict is a built-in type representing an associative mapping or _dictionary_. A dictionary supports indexing using `d[k]` and key membership testing using `k in d`; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to `d[k]` or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key. ``` -d = \{0: "x", 2: "z", 1: "y"\} +d = {0: "x", 2: "z", 1: "y"} [k for k in d] # [0, 2, 1] d.pop(2) d[0], d[2] = "a", "b" 0 in d, "a" in d # (True, False) [(k, v) for k, v in d.items()] # [(0, "a"), (1, "y"), (2, "b")] + ``` There are four ways to construct a dictionary: -1. A dictionary expression `\{k: v, ...\}` yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value.- A dictionary comprehension `\{k: v for vars in seq\}` yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value. +1. A dictionary expression `{k: v, ...}` yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value. + +2. A dictionary comprehension `{k: v for vars in seq}` yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value. + + + ``` + {k: v for k, v in (("a", 0), ("b", 1), ("a", 2))} # {"a": 2, "b": 1} + {i: 2*i for i in range(3)} # {0: 0, 1: 2, 2: 4} + + ``` + +3. A call to the built-in [dict](../globals/all.html#dict) function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted. + +4. The union expression `x | y` yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key `k` in common, the right hand side dictionary's value of the key (in other words, `y[k]`) wins. The `|=` variant of the union operator modifies a dictionary in-place. Example: - ``` - \{k: v for k, v in (("a", 0), ("b", 1), ("a", 2))\} # \{"a": 2, "b": 1\} - \{i: 2*i for i in range(3)\} # \{0: 0, 1: 2, 2: 4\} - ``` - - A call to the built-in [dict](../globals/all.html#dict) function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted.- The union expression `x | y` yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key `k` in common, the right hand side dictionary's value of the key (in other words, `y[k]`) wins. The `|=` variant of the union operator modifies a dictionary in-place. Example: - ``` - d = \{"foo": "FOO", "bar": "BAR"\} | \{"foo": "FOO2", "baz": "BAZ"\} - # d == \{"foo": "FOO2", "bar": "BAR", "baz": "BAZ"\} - d = \{"a": 1, "b": 2\} - d |= \{"b": 3, "c": 4\} - # d == \{"a": 1, "b": 3, "c": 4\} - ``` + ``` + d = {"foo": "FOO", "bar": "BAR"} | {"foo": "FOO2", "baz": "BAZ"} + # d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"} + d = {"a": 1, "b": 2} + d |= {"b": 3, "c": 4} + # d == {"a": 1, "b": 3, "c": 4} + ``` + ## Members -* [clear](#clear) -* [get](#get) -* [items](#items) -* [keys](#keys) -* [pop](#pop) -* [popitem](#popitem) -* [setdefault](#setdefault) -* [update](#update) -* [values](#values) +- [clear](#clear) +- [get](#get) +- [items](#items) +- [keys](#keys) +- [pop](#pop) +- [popitem](#popitem) +- [setdefault](#setdefault) +- [update](#update) +- [values](#values) ## clear @@ -51,7 +62,9 @@ There are four ways to construct a dictionary: None dict.clear() ``` -Remove all items from the dictionary. + Remove all items from the dictionary. + + ## get @@ -59,14 +72,20 @@ Remove all items from the dictionary. unknown dict.get(key, default=None) ``` -Returns the value for `key` if `key` is in the dictionary, else `default`. If `default` is not given, it defaults to `None`, so that this method never throws an error. + Returns the value for `key` if `key` is in the dictionary, else `default`. If `default` is not given, it defaults to `None`, so that this method never throws an error. + ### Parameters -| Parameter | Description | -| --- | --- | -| `key` | required | -| `default` | default is `None` The default value to use (instead of None) if the key is not found. | +ParameterDescription`key` + required + + The key to look for. + `default` + default is `None` + + The default value to use (instead of None) if the key is not found. + ## items @@ -74,10 +93,10 @@ Returns the value for `key` if `key` is in the dictionary, else `default`. If `d list dict.items() ``` -Returns the list of key-value tuples: + Returns the list of key-value tuples: ``` -\{2: "a", 4: "b", 1: "c"\}.items() == [(2, "a"), (4, "b"), (1, "c")] +{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")] ``` ## keys @@ -86,10 +105,10 @@ Returns the list of key-value tuples: list dict.keys() ``` -Returns the list of keys: + Returns the list of keys: ``` -\{2: "a", 4: "b", 1: "c"\}.keys() == [2, 4, 1] +{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1] ``` ## pop @@ -98,14 +117,20 @@ Returns the list of keys: unknown dict.pop(key, default=unbound) ``` -Removes a `key` from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified `default` value; if no default value was specified, fail instead. + Removes a `key` from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified `default` value; if no default value was specified, fail instead. + ### Parameters -| Parameter | Description | -| --- | --- | -| `key` | required The key. | -| `default` | default is `unbound` a default value if the key is absent. | +ParameterDescription`key` + required + + The key. + `default` + default is `unbound` + + a default value if the key is absent. + ## popitem @@ -113,7 +138,9 @@ Removes a `key` from the dict, and returns the associated value. If no entry wit tuple dict.popitem() ``` -Remove and return the first `(key, value)` pair from the dictionary. `popitem` is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the `popitem` call fails. + Remove and return the first `(key, value)` pair from the dictionary. `popitem` is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the `popitem` call fails. + + ## setdefault @@ -121,14 +148,20 @@ Remove and return the first `(key, value)` pair from the dictionary. `popitem` i unknown dict.setdefault(key, default=None) ``` -If `key` is in the dictionary, return its value. If not, insert key with a value of `default` and return `default`. `default` defaults to `None`. + If `key` is in the dictionary, return its value. If not, insert key with a value of `default` and return `default`. `default` defaults to `None`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `key` | required The key. | -| `default` | default is `None` a default value if the key is absent. | +ParameterDescription`key` + required + + The key. + `default` + default is `None` + + a default value if the key is absent. + ## update @@ -136,17 +169,23 @@ If `key` is in the dictionary, return its value. If not, insert key with a value None dict.update(pairs=[], **kwargs) ``` -Updates the dictionary first with the optional positional argument, `pairs`, then with the optional keyword arguments + Updates the dictionary first with the optional positional argument, `pairs`, then with the optional keyword arguments If the positional argument is present, it must be a dict, iterable, or None. If it is a dict, then its key/value pairs are inserted into this dict. If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2), each of which is treated as a key/value pair to be inserted. Each keyword argument `name=value` causes the name/value pair to be inserted into this dict. + ### Parameters -| Parameter | Description | -| --- | --- | -| `pairs` | default is `[]` Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value. | -| `kwargs` | required Dictionary of additional entries. | +ParameterDescription`pairs` + default is `[]` + + Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value. + `kwargs` + required + + Dictionary of additional entries. + ## values @@ -154,8 +193,8 @@ Each keyword argument `name=value` causes the name/value pair to be inserted int list dict.values() ``` -Returns the list of values: + Returns the list of values: ``` -\{2: "a", 4: "b", 1: "c"\}.values() == ["a", "b", "c"] -``` \ No newline at end of file +{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"] +``` diff --git a/rules/lib/core/float.mdx b/rules/lib/core/float.mdx index e307157..bcc063f 100644 --- a/rules/lib/core/float.mdx +++ b/rules/lib/core/float.mdx @@ -3,4 +3,5 @@ title: 'float' --- -The type of floating-point numbers in Starlark. \ No newline at end of file + +The type of floating-point numbers in Starlark. diff --git a/rules/lib/core/function.mdx b/rules/lib/core/function.mdx index 5775b15..c0af505 100644 --- a/rules/lib/core/function.mdx +++ b/rules/lib/core/function.mdx @@ -3,4 +3,5 @@ title: 'function' --- -The type of functions declared in Starlark. \ No newline at end of file + +The type of functions declared in Starlark. diff --git a/rules/lib/core/int.mdx b/rules/lib/core/int.mdx index 294e908..90cb450 100644 --- a/rules/lib/core/int.mdx +++ b/rules/lib/core/int.mdx @@ -3,7 +3,8 @@ title: 'int' --- -The type of integers in Starlark. Starlark integers may be of any magnitude; arithmetic is exact. Examples of integer expressions: + +The type of integers in Starlark. Starlark integers may be of any magnitude; arithmetic is exact. Examples of integer expressions: ``` 153 @@ -13,4 +14,5 @@ The type of integers in Starlark. Starlark integers may be of any magnitude; ari 100 / -7 100 % -7 # -5 (unlike in some other languages) int("18") -``` \ No newline at end of file + +``` diff --git a/rules/lib/core/json.mdx b/rules/lib/core/json.mdx index 1b3c2e0..e38d880 100644 --- a/rules/lib/core/json.mdx +++ b/rules/lib/core/json.mdx @@ -3,14 +3,15 @@ title: 'json' --- + Module json is a Starlark module of JSON-related functions. ## Members -* [decode](#decode) -* [encode](#encode) -* [encode\_indent](#encode_indent) -* [indent](#indent) +- [decode](#decode) +- [encode](#encode) +- [encode\_indent](#encode_indent) +- [indent](#indent) ## decode @@ -18,20 +19,33 @@ Module json is a Starlark module of JSON-related functions. unknown json.decode(x, default=unbound) ``` -The decode function has one required positional parameter: a JSON string. + The decode function has one required positional parameter: a JSON string. It returns the Starlark value that the string denotes. -* `"null"`, `"true"` and `"false"` are parsed as `None`, `True`, and `False`.* Numbers are parsed as int, or as a float if they contain a decimal point or an exponent. Although JSON has no syntax for non-finite values, very large values may be decoded as infinity.* a JSON object is parsed as a new unfrozen Starlark dict. If the same key string occurs more than once in the object, the last value for the key is kept.* a JSON array is parsed as new unfrozen Starlark list. +- `"null"`, `"true"` and `"false"` are parsed as `None`, `True`, and `False`. + +- Numbers are parsed as int, or as a float if they contain a decimal point or an exponent. Although JSON has no syntax for non-finite values, very large values may be decoded as infinity. + +- a JSON object is parsed as a new unfrozen Starlark dict. If the same key string occurs more than once in the object, the last value for the key is kept. + +- a JSON array is parsed as new unfrozen Starlark list. + If `x` is not a valid JSON encoding and the optional `default` parameter is specified (including specified as `None`), this function returns the `default` value. -If `x` is not a valid JSON encoding and the optional `default` parameter is *not* specified, this function fails. +If `x` is not a valid JSON encoding and the optional `default` parameter is _not_ specified, this function fails. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | [string](../core/string.mdx); required JSON string to decode. | -| `default` | default is `unbound` If specified, the value to return when `x` cannot be decoded. | +ParameterDescription`x`[string](../core/string.html); + required + + JSON string to decode. + `default` + default is `unbound` + + If specified, the value to return when `x` cannot be decoded. + ## encode @@ -41,16 +55,30 @@ string json.encode(x) The encode function accepts one required positional argument, which it converts to JSON by cases: -* None, True, and False are converted to 'null', 'true', and 'false', respectively.* An int, no matter how large, is encoded as a decimal integer. Some decoders may not be able to decode very large integers.* A float is encoded using a decimal point or an exponent or both, even if its numeric value is an integer. It is an error to encode a non-finite floating-point value.* A string value is encoded as a JSON string literal that denotes the value. Each unpaired surrogate is replaced by U+FFFD.* A dict is encoded as a JSON object, in lexicographical key order. It is an error if any key is not a string.* A list or tuple is encoded as a JSON array.* A struct-like value is encoded as a JSON object, in field name order. +- None, True, and False are converted to 'null', 'true', and 'false', respectively. + +- An int, no matter how large, is encoded as a decimal integer. Some decoders may not be able to decode very large integers. + +- A float is encoded using a decimal point or an exponent or both, even if its numeric value is an integer. It is an error to encode a non-finite floating-point value. + +- A string value is encoded as a JSON string literal that denotes the value. Each unpaired surrogate is replaced by U+FFFD. + +- A dict is encoded as a JSON object, in lexicographical key order. It is an error if any key is not a string. + +- A list or tuple is encoded as a JSON array. + +- A struct-like value is encoded as a JSON object, in field name order. + An application-defined type may define its own JSON encoding. Encoding any other value yields an error. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required | +ParameterDescription`x` + required ## encode\_indent @@ -58,15 +86,19 @@ Encoding any other value yields an error. string json.encode_indent(x, *, prefix='', indent='\t') ``` -The encode\_indent function is equivalent to `json.indent(json.encode(x), ...)`. See `indent` for description of formatting parameters. + The encode\_indent function is equivalent to `json.indent(json.encode(x), ...)`. See `indent` for description of formatting parameters. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required | -| `prefix` | [string](../core/string.mdx); default is `''` | -| `indent` | [string](../core/string.mdx); default is `'\t'` | +ParameterDescription`x` + required + +`prefix`[string](../core/string.html); + default is `''` + +`indent`[string](../core/string.html); + default is `'\t'` ## indent @@ -74,17 +106,22 @@ The encode\_indent function is equivalent to `json.indent(json.encode(x), ...)`. string json.indent(s, *, prefix='', indent='\t') ``` -The indent function returns the indented form of a valid JSON-encoded string. + The indent function returns the indented form of a valid JSON-encoded string. Each array element or object field appears on a new line, beginning with the prefix string followed by one or more copies of the indent string, according to its nesting depth. The function accepts one required positional parameter, the JSON string, and two optional keyword-only string parameters, prefix and indent, that specify a prefix of each new line, and the unit of indentation. If the input is not valid, the function may fail or return invalid output. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `s` | [string](../core/string.mdx); required | -| `prefix` | [string](../core/string.mdx); default is `''` | -| `indent` | [string](../core/string.mdx); default is `'\t'` | \ No newline at end of file +ParameterDescription`s`[string](../core/string.html); + required + +`prefix`[string](../core/string.html); + default is `''` + +`indent`[string](../core/string.html); + default is `'\t'` diff --git a/rules/lib/core/list.mdx b/rules/lib/core/list.mdx index 9c0263b..043e173 100644 --- a/rules/lib/core/list.mdx +++ b/rules/lib/core/list.mdx @@ -3,19 +3,20 @@ title: 'list' --- -The built-in list type. Example list expressions: + +The built-in list type. Example list expressions: ``` x = [1, 2, 3] ``` -Accessing elements is possible using indexing (starts from `0`): +Accessing elements is possible using indexing (starts from `0`): ``` e = x[1] # e == 2 ``` -Lists support the `+` operator to concatenate two lists. Example: +Lists support the `+` operator to concatenate two lists. Example: ``` x = [1, 2] + [3, 4] # x == [1, 2, 3, 4] @@ -35,13 +36,13 @@ Lists are mutable, as in Python. ## Members -* [append](#append) -* [clear](#clear) -* [extend](#extend) -* [index](#index) -* [insert](#insert) -* [pop](#pop) -* [remove](#remove) +- [append](#append) +- [clear](#clear) +- [extend](#extend) +- [index](#index) +- [insert](#insert) +- [pop](#pop) +- [remove](#remove) ## append @@ -49,13 +50,16 @@ Lists are mutable, as in Python. None list.append(item) ``` -Adds an item to the end of the list. + Adds an item to the end of the list. + ### Parameters -| Parameter | Description | -| --- | --- | -| `item` | required | +ParameterDescription`item` + required + + Item to add at the end. + ## clear @@ -63,7 +67,9 @@ Adds an item to the end of the list. None list.clear() ``` -Removes all the elements of the list. + Removes all the elements of the list. + + ## extend @@ -71,13 +77,17 @@ Removes all the elements of the list. None list.extend(items) ``` -Adds all items to the end of the list. + Adds all items to the end of the list. + ### Parameters -| Parameter | Description | -| --- | --- | -| `items` | iterable; required | +ParameterDescription`items` + iterable; + required + + Items to add at the end. + ## index @@ -85,15 +95,24 @@ Adds all items to the end of the list. int list.index(x, start=unbound, end=unbound) ``` -Returns the index in the list of the first item whose value is x. It is an error if there is no such item. + Returns the index in the list of the first item whose value is x. It is an error if there is no such item. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required | -| `start` | [int](../core/int.mdx); default is `unbound` The start index of the list portion to inspect. | -| `end` | [int](../core/int.mdx); default is `unbound` The end index of the list portion to inspect. | +ParameterDescription`x` + required + + The object to search. + `start`[int](../core/int.html); + default is `unbound` + + The start index of the list portion to inspect. + `end`[int](../core/int.html); + default is `unbound` + + The end index of the list portion to inspect. + ## insert @@ -101,14 +120,20 @@ Returns the index in the list of the first item whose value is x. It is an error None list.insert(index, item) ``` -Inserts an item at a given position. + Inserts an item at a given position. + ### Parameters -| Parameter | Description | -| --- | --- | -| `index` | [int](../core/int.mdx); required The index of the given position. | -| `item` | required The item. | +ParameterDescription`index`[int](../core/int.html); + required + + The index of the given position. + `item` + required + + The item. + ## pop @@ -116,13 +141,16 @@ Inserts an item at a given position. unknown list.pop(i=-1) ``` -Removes the item at the given position in the list, and returns it. If no `index` is specified, it removes and returns the last item in the list. + Removes the item at the given position in the list, and returns it. If no `index` is specified, it removes and returns the last item in the list. + ### Parameters -| Parameter | Description | -| --- | --- | -| `i` | [int](../core/int.mdx); default is `-1` The index of the item. | +ParameterDescription`i`[int](../core/int.html); + default is `-1` + + The index of the item. + ## remove @@ -130,10 +158,12 @@ Removes the item at the given position in the list, and returns it. If no `index None list.remove(x) ``` -Removes the first item from the list whose value is x. It is an error if there is no such item. + Removes the first item from the list whose value is x. It is an error if there is no such item. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required The object to remove. | \ No newline at end of file +ParameterDescription`x` + required + + The object to remove. diff --git a/rules/lib/core/range.mdx b/rules/lib/core/range.mdx index bbcff5a..5f5ccba 100644 --- a/rules/lib/core/range.mdx +++ b/rules/lib/core/range.mdx @@ -3,13 +3,14 @@ title: 'range' --- -A language built-in type to support ranges. Example of range literal: + +A language built-in type to support ranges. Example of range literal: ``` x = range(1, 10, 3) ``` -Accessing elements is possible using indexing (starts from `0`): +Accessing elements is possible using indexing (starts from `0`): ``` e = x[1] # e == 2 @@ -23,4 +24,4 @@ range(10)[::2] # range(0, 10, 2) range(10)[3:0:-1] # range(3, 0, -1) ``` -Ranges are immutable, as in Python 3. \ No newline at end of file +Ranges are immutable, as in Python 3. diff --git a/rules/lib/core/set.mdx b/rules/lib/core/set.mdx index 337a7cb..14ba6df 100644 --- a/rules/lib/core/set.mdx +++ b/rules/lib/core/set.mdx @@ -3,8 +3,9 @@ title: 'set' --- + The built-in set type. A set is a mutable collection of unique values – the set's -*elements*. The [type name](../globals/all#type) of a set is `"set"`. +_elements_. The [type name](../globals/all#type) of a set is `"set"`. Sets provide constant-time operations to insert, remove, or check for the presence of a value. Sets are implemented using a hash table, and therefore, just like keys of a @@ -23,6 +24,7 @@ set: s = set(["a", "b", "c"]) "a" in s # True "z" in s # False + ``` A set is iterable, and thus may be used as the operand of a `for` loop, a list @@ -37,6 +39,7 @@ s.add("x") len(s) # prints 3 for e in s: print e # prints "z", "y", "x" + ``` A set used in Boolean context is true if and only if it is non-empty. @@ -46,13 +49,14 @@ s = set() "non-empty" if s else "empty" # "empty" t = set(["x", "y"]) "non-empty" if t else "empty" # "non-empty" + ``` Sets may be compared for equality or inequality using `==` and `!=`. A set `s` is equal to `t` if and only if `t` is a set containing the same -elements; iteration order is not significant. In particular, a set is *not* equal to the list +elements; iteration order is not significant. In particular, a set is _not_ equal to the list of its elements. Sets are not ordered with respect to other sets, and an attempt to compare two sets -using `<`, `<=`, `>`, `>=`, or to sort a +using `<`, `<=`, `>`, `>=`, or to sort a sequence of sets, will fail. ``` @@ -60,6 +64,7 @@ set() == set() # True set() != [] # True set([1, 2]) == set([2, 1]) # True set([1, 2]) != [1, 2] # True + ``` The `|` operation on two sets returns the union of the two sets: a set containing the @@ -67,6 +72,7 @@ elements found in either one or both of the original sets. ``` set([1, 2]) | set([3, 2]) # set([1, 2, 3]) + ``` The `&` operation on two sets returns the intersection of the two sets: a set @@ -75,6 +81,7 @@ containing only the elements found in both of the original sets. ``` set([1, 2]) & set([2, 3]) # set([2]) set([1, 2]) & set([3, 4]) # set() + ``` The `-` operation on two sets returns the difference of the two sets: a set containing @@ -83,6 +90,7 @@ the elements found in the left-hand side set but not the right-hand side set. ``` set([1, 2]) - set([2, 3]) # set([1]) set([1, 2]) - set([3, 4]) # set([1, 2]) + ``` The `^` operation on two sets returns the symmetric difference of the two sets: a set @@ -91,6 +99,7 @@ containing the elements found in exactly one of the two original sets, but not i ``` set([1, 2]) ^ set([2, 3]) # set([1, 3]) set([1, 2]) ^ set([3, 4]) # set([1, 2, 3, 4]) + ``` In each of the above operations, the elements of the resulting set retain their order from the @@ -106,6 +115,7 @@ s |= set([2, 3, 4]) # s now equals set([1, 2, 3, 4]) s &= set([0, 1, 2, 3]) # s now equals set([1, 2, 3]) s -= set([0, 1]) # s now equals set([2, 3]) s ^= set([3, 4]) # s now equals set([2, 4]) + ``` Like all mutable values in Starlark, a set can be frozen, and once frozen, all subsequent @@ -113,22 +123,22 @@ operations that attempt to update it will fail. ## Members -* [add](#add) -* [clear](#clear) -* [difference](#difference) -* [difference\_update](#difference_update) -* [discard](#discard) -* [intersection](#intersection) -* [intersection\_update](#intersection_update) -* [isdisjoint](#isdisjoint) -* [issubset](#issubset) -* [issuperset](#issuperset) -* [pop](#pop) -* [remove](#remove) -* [symmetric\_difference](#symmetric_difference) -* [symmetric\_difference\_update](#symmetric_difference_update) -* [union](#union) -* [update](#update) +- [add](#add) +- [clear](#clear) +- [difference](#difference) +- [difference\_update](#difference_update) +- [discard](#discard) +- [intersection](#intersection) +- [intersection\_update](#intersection_update) +- [isdisjoint](#isdisjoint) +- [issubset](#issubset) +- [issuperset](#issuperset) +- [pop](#pop) +- [remove](#remove) +- [symmetric\_difference](#symmetric_difference) +- [symmetric\_difference\_update](#symmetric_difference_update) +- [union](#union) +- [update](#update) ## add @@ -136,7 +146,7 @@ operations that attempt to update it will fail. None set.add(element) ``` -Adds an element to the set. + Adds an element to the set. It is permissible to `add` a value already present in the set; this leaves the set unchanged. @@ -144,11 +154,15 @@ unchanged. If you need to add multiple elements to a set, see [`update`](#update) or the `|=` augmented assignment operation. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `element` | required Element to add. | +ParameterDescription`element` + required + + Element to add. + ## clear @@ -156,7 +170,9 @@ the `|=` augmented assignment operation. None set.clear() ``` -Removes all the elements of the set. + Removes all the elements of the set. + + ## difference @@ -164,7 +180,7 @@ Removes all the elements of the set. set set.difference(*others) ``` -Returns a new mutable set containing the difference of this set with others. + Returns a new mutable set containing the difference of this set with others. If `s` and `t` are sets, `s.difference(t)` is equivalent to `s - t`; however, note that the `-` operation requires both sides to be sets, @@ -178,13 +194,16 @@ For example, ``` set([1, 2, 3]).difference([2]) # set([1, 3]) set([1, 2, 3]).difference([0, 1], [3, 4]) # set([2]) + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `others` | required Collections of hashable elements. | +ParameterDescription`others` + required + + Collections of hashable elements. + ## difference\_update @@ -192,7 +211,7 @@ set([1, 2, 3]).difference([0, 1], [3, 4]) # set([2]) None set.difference_update(*others) ``` -Removes any elements found in any others from this set. + Removes any elements found in any others from this set. If `s` and `t` are sets, `s.difference_update(t)` is equivalent to `s -= t`; however, note that the `-=` augmented assignment requires both @@ -207,13 +226,16 @@ For example, s = set([1, 2, 3, 4]) s.difference_update([2]) # None; s is set([1, 3, 4]) s.difference_update([0, 1], [4, 5]) # None; s is set([3]) + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `others` | required Collections of hashable elements. | +ParameterDescription`others` + required + + Collections of hashable elements. + ## discard @@ -221,7 +243,7 @@ s.difference_update([0, 1], [4, 5]) # None; s is set([3]) None set.discard(element) ``` -Removes an element from the set if it is present. + Removes an element from the set if it is present. It is permissible to `discard` a value not present in the set; this leaves the set unchanged. If you want to fail on an attempt to remove a non-present element, use @@ -235,13 +257,16 @@ For example, s = set(["x", "y"]) s.discard("y") # None; s == set(["x"]) s.discard("y") # None; s == set(["x"]) + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `element` | required Element to discard. Must be hashable. | +ParameterDescription`element` + required + + Element to discard. Must be hashable. + ## intersection @@ -249,7 +274,7 @@ s.discard("y") # None; s == set(["x"]) set set.intersection(*others) ``` -Returns a new mutable set containing the intersection of this set with others. + Returns a new mutable set containing the intersection of this set with others. If `s` and `t` are sets, `s.intersection(t)` is equivalent to `s & t`; however, note that the `&` operation requires both sides to @@ -263,13 +288,16 @@ For example, ``` set([1, 2]).intersection([2, 3]) # set([2]) set([1, 2, 3]).intersection([0, 1], [1, 2]) # set([1]) + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `others` | required Collections of hashable elements. | +ParameterDescription`others` + required + + Collections of hashable elements. + ## intersection\_update @@ -277,7 +305,7 @@ set([1, 2, 3]).intersection([0, 1], [1, 2]) # set([1]) None set.intersection_update(*others) ``` -Removes any elements not found in all others from this set. + Removes any elements not found in all others from this set. If `s` and `t` are sets, `s.intersection_update(t)` is equivalent to `s &= t`; however, note that the `&=` augmented @@ -293,13 +321,16 @@ For example, s = set([1, 2, 3, 4]) s.intersection_update([0, 1, 2]) # None; s is set([1, 2]) s.intersection_update([0, 1], [1, 2]) # None; s is set([1]) + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `others` | required Collections of hashable elements. | +ParameterDescription`others` + required + + Collections of hashable elements. + ## isdisjoint @@ -307,7 +338,7 @@ s.intersection_update([0, 1], [1, 2]) # None; s is set([1]) bool set.isdisjoint(other) ``` -Returns true if this set has no elements in common with another. + Returns true if this set has no elements in common with another. For example, @@ -315,13 +346,16 @@ For example, set([1, 2]).isdisjoint([3, 4]) # True set().isdisjoint(set()) # True set([1, 2]).isdisjoint([2, 3]) # False + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `other` | required A collection of hashable elements. | +ParameterDescription`other` + required + + A collection of hashable elements. + ## issubset @@ -329,7 +363,7 @@ set([1, 2]).isdisjoint([2, 3]) # False bool set.issubset(other) ``` -Returns true of this set is a subset of another. + Returns true of this set is a subset of another. Note that a set is always considered to be a subset of itself. @@ -339,13 +373,16 @@ For example, set([1, 2]).issubset([1, 2, 3]) # True set([1, 2]).issubset([1, 2]) # True set([1, 2]).issubset([2, 3]) # False + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `other` | required A collection of hashable elements. | +ParameterDescription`other` + required + + A collection of hashable elements. + ## issuperset @@ -353,7 +390,7 @@ set([1, 2]).issubset([2, 3]) # False bool set.issuperset(other) ``` -Returns true of this set is a superset of another. + Returns true of this set is a superset of another. Note that a set is always considered to be a superset of itself. @@ -363,13 +400,16 @@ For example, set([1, 2, 3]).issuperset([1, 2]) # True set([1, 2, 3]).issuperset([1, 2, 3]) # True set([1, 2, 3]).issuperset([2, 3, 4]) # False + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `other` | required A collection of hashable elements. | +ParameterDescription`other` + required + + A collection of hashable elements. + ## pop @@ -377,7 +417,7 @@ set([1, 2, 3]).issuperset([2, 3, 4]) # False unknown set.pop() ``` -Removes and returns the first element of the set (in iteration order, which is the order in which + Removes and returns the first element of the set (in iteration order, which is the order in which elements were first added to the set). Fails if the set is empty. @@ -390,6 +430,7 @@ s.pop() # 3; s == set([1, 2]) s.pop() # 1; s == set([2]) s.pop() # 2; s == set() s.pop() # error: empty set + ``` ## remove @@ -398,7 +439,7 @@ s.pop() # error: empty set None set.remove(element) ``` -Removes an element, which must be present in the set, from the set. + Removes an element, which must be present in the set, from the set. `remove` fails if the element was not present in the set. If you don't want to fail on an attempt to remove a non-present element, use [`discard`](#discard) instead. @@ -406,11 +447,15 @@ If you need to remove multiple elements from a set, see [`difference_update`](#difference_update) or the `-=` augmented assignment operation. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `element` | required Element to remove. Must be an element of the set (and hashable). | +ParameterDescription`element` + required + + Element to remove. Must be an element of the set (and hashable). + ## symmetric\_difference @@ -418,7 +463,7 @@ assignment operation. set set.symmetric_difference(other) ``` -Returns a new mutable set containing the symmetric difference of this set with another collection of + Returns a new mutable set containing the symmetric difference of this set with another collection of hashable elements. If `s` and `t` are sets, `s.symmetric_difference(t)` is @@ -430,13 +475,16 @@ For example, ``` set([1, 2]).symmetric_difference([2, 3]) # set([1, 3]) + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `other` | required A collection of hashable elements. | +ParameterDescription`other` + required + + A collection of hashable elements. + ## symmetric\_difference\_update @@ -444,11 +492,11 @@ set([1, 2]).symmetric_difference([2, 3]) # set([1, 3]) None set.symmetric_difference_update(other) ``` -Returns a new mutable set containing the symmetric difference of this set with another collection of + Returns a new mutable set containing the symmetric difference of this set with another collection of hashable elements. If `s` and `t` are sets, `s.symmetric_difference_update(t)` is -equivalent to `s ^= t`; however, note that the` ^=` augmented assignment requires both +equivalent to \`s ^= t `; however, note that the ` ^=\` augmented assignment requires both sides to be sets, while the `symmetric_difference_update` method also accepts a sequence or a dict. @@ -457,13 +505,16 @@ For example, ``` s = set([1, 2]) s.symmetric_difference_update([2, 3]) # None; s == set([1, 3]) + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `other` | required A collection of hashable elements. | +ParameterDescription`other` + required + + A collection of hashable elements. + ## union @@ -471,7 +522,7 @@ s.symmetric_difference_update([2, 3]) # None; s == set([1, 3]) set set.union(*others) ``` -Returns a new mutable set containing the union of this set with others. + Returns a new mutable set containing the union of this set with others. If `s` and `t` are sets, `s.union(t)` is equivalent to `s | t`; however, note that the `|` operation requires both sides to be sets, @@ -484,14 +535,17 @@ For example, ``` set([1, 2]).union([2, 3]) # set([1, 2, 3]) -set([1, 2]).union([2, 3], \{3: "a", 4: "b"\}) # set([1, 2, 3, 4]) +set([1, 2]).union([2, 3], {3: "a", 4: "b"}) # set([1, 2, 3, 4]) + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `others` | required Collections of hashable elements. | +ParameterDescription`others` + required + + Collections of hashable elements. + ## update @@ -499,7 +553,7 @@ set([1, 2]).union([2, 3], \{3: "a", 4: "b"\}) # set([1, 2, 3, 4]) None set.update(*others) ``` -Adds the elements found in others to this set. + Adds the elements found in others to this set. For example, @@ -507,6 +561,7 @@ For example, s = set() s.update([1, 2]) # None; s is set([1, 2]) s.update([2, 3], [3, 4]) # None; s is set([1, 2, 3, 4]) + ``` If `s` and `t` are sets, `s.update(t)` is equivalent to @@ -516,8 +571,11 @@ to be sets, while the `update` method also accepts sequences and dicts. It is permissible to call `update` without any arguments; this leaves the set unchanged. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `others` | required Collections of hashable elements. | \ No newline at end of file +ParameterDescription`others` + required + + Collections of hashable elements. diff --git a/rules/lib/core/string.mdx b/rules/lib/core/string.mdx index 90ddd78..5ff78dc 100644 --- a/rules/lib/core/string.mdx +++ b/rules/lib/core/string.mdx @@ -3,7 +3,8 @@ title: 'string' --- -A language built-in type to support strings. Examples of string literals: + +A language built-in type to support strings. Examples of string literals: ``` a = 'abc\ndef' @@ -17,9 +18,10 @@ z = "hello"[:4] # "hell" # Slice steps can be used, too: s = "hello"[::2] # "hlo" t = "hello"[3:0:-1] # "lle" + ``` -Strings are not directly iterable, use the `.elems()` method to iterate over their characters. Examples: +Strings are not directly iterable, use the `.elems()` method to iterate over their characters. Examples: ``` "bc" in "abcd" # evaluates to True @@ -30,38 +32,38 @@ Implicit concatenation of strings is not allowed; use the `+` operator instead. ## Members -* [capitalize](#capitalize) -* [count](#count) -* [elems](#elems) -* [endswith](#endswith) -* [find](#find) -* [format](#format) -* [index](#index) -* [isalnum](#isalnum) -* [isalpha](#isalpha) -* [isdigit](#isdigit) -* [islower](#islower) -* [isspace](#isspace) -* [istitle](#istitle) -* [isupper](#isupper) -* [join](#join) -* [lower](#lower) -* [lstrip](#lstrip) -* [partition](#partition) -* [removeprefix](#removeprefix) -* [removesuffix](#removesuffix) -* [replace](#replace) -* [rfind](#rfind) -* [rindex](#rindex) -* [rpartition](#rpartition) -* [rsplit](#rsplit) -* [rstrip](#rstrip) -* [split](#split) -* [splitlines](#splitlines) -* [startswith](#startswith) -* [strip](#strip) -* [title](#title) -* [upper](#upper) +- [capitalize](#capitalize) +- [count](#count) +- [elems](#elems) +- [endswith](#endswith) +- [find](#find) +- [format](#format) +- [index](#index) +- [isalnum](#isalnum) +- [isalpha](#isalpha) +- [isdigit](#isdigit) +- [islower](#islower) +- [isspace](#isspace) +- [istitle](#istitle) +- [isupper](#isupper) +- [join](#join) +- [lower](#lower) +- [lstrip](#lstrip) +- [partition](#partition) +- [removeprefix](#removeprefix) +- [removesuffix](#removesuffix) +- [replace](#replace) +- [rfind](#rfind) +- [rindex](#rindex) +- [rpartition](#rpartition) +- [rsplit](#rsplit) +- [rstrip](#rstrip) +- [split](#split) +- [splitlines](#splitlines) +- [startswith](#startswith) +- [strip](#strip) +- [title](#title) +- [upper](#upper) ## capitalize @@ -69,7 +71,9 @@ Implicit concatenation of strings is not allowed; use the `+` operator instead. string string.capitalize() ``` -Returns a copy of the string with its first character (if any) capitalized and the rest lowercased. This method does not support non-ascii characters. + Returns a copy of the string with its first character (if any) capitalized and the rest lowercased. This method does not support non-ascii characters. + + ## count @@ -77,15 +81,24 @@ Returns a copy of the string with its first character (if any) capitalized and t int string.count(sub, start=0, end=None) ``` -Returns the number of (non-overlapping) occurrences of substring `sub` in string, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + Returns the number of (non-overlapping) occurrences of substring `sub` in string, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sub` | [string](../core/string.mdx); required | -| `start` | [int](../core/int.mdx); or `None`; default is `0` | -| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | +ParameterDescription`sub`[string](../core/string.html); + required + + The substring to count. + `start`[int](../core/int.html); or `None`; + default is `0` + + Restrict to search from this position. + `end`[int](../core/int.html); or `None`; + default is `None` + + optional position before which to restrict to search. + ## elems @@ -93,7 +106,9 @@ Returns the number of (non-overlapping) occurrences of substring `sub` in string sequence string.elems() ``` -Returns an iterable value containing successive 1-element substrings of the string. Equivalent to `[s[i] for i in range(len(s))]`, except that the returned value might not be a list. + Returns an iterable value containing successive 1-element substrings of the string. Equivalent to `[s[i] for i in range(len(s))]`, except that the returned value might not be a list. + + ## endswith @@ -101,15 +116,24 @@ Returns an iterable value containing successive 1-element substrings of the stri bool string.endswith(sub, start=0, end=None) ``` -Returns True if the string ends with `sub`, otherwise False, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + Returns True if the string ends with `sub`, otherwise False, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sub` | [string](../core/string.mdx); or [tuple](../core/tuple.mdx) of [string](../core/string.mdx)s; required The suffix (or tuple of alternative suffixes) to match. | -| `start` | [int](../core/int.mdx); or `None`; default is `0` Test beginning at this position. | -| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position at which to stop comparing. | +ParameterDescription`sub`[string](../core/string.html); or [tuple](../core/tuple.html) of [string](../core/string.html) s; + required + + The suffix (or tuple of alternative suffixes) to match. + `start`[int](../core/int.html); or `None`; + default is `0` + + Test beginning at this position. + `end`[int](../core/int.html); or `None`; + default is `None` + + optional position at which to stop comparing. + ## find @@ -117,15 +141,24 @@ Returns True if the string ends with `sub`, otherwise False, optionally restrict int string.find(sub, start=0, end=None) ``` -Returns the first index where `sub` is found, or -1 if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + Returns the first index where `sub` is found, or -1 if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sub` | [string](../core/string.mdx); required The substring to find. | -| `start` | [int](../core/int.mdx); or `None`; default is `0` Restrict to search from this position. | -| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | +ParameterDescription`sub`[string](../core/string.html); + required + + The substring to find. + `start`[int](../core/int.html); or `None`; + default is `0` + + Restrict to search from this position. + `end`[int](../core/int.html); or `None`; + default is `None` + + optional position before which to restrict to search. + ## format @@ -133,23 +166,28 @@ Returns the first index where `sub` is found, or -1 if no such index exists, opt string string.format(*args, **kwargs) ``` -Perform string interpolation. Format strings contain replacement fields surrounded by curly braces `\{\}`. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output.If you need to include a brace character in the literal text, it can be escaped by doubling: ``A replacement field can be either a name, a number, or empty. Values are converted to strings using the [str](../globals/all.html#str) function. + Perform string interpolation. Format strings contain replacement fields surrounded by curly braces `{}`. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output.If you need to include a brace character in the literal text, it can be escaped by doubling: `{{` and `}}` A replacement field can be either a name, a number, or empty. Values are converted to strings using the [str](../globals/all.html#str) function. ``` # Access in order: -"\{\} < \{\}".format(4, 5) == "4 < 5" +"{} < {}".format(4, 5) == "4 < 5" # Access by position: -"\{1\}, \{0\}".format(2, 1) == "1, 2" +"{1}, {0}".format(2, 1) == "1, 2" # Access by name: -"x\{key\}x".format(key = 2) == "x2x" +"x{key}x".format(key = 2) == "x2x" ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `args` | default is `()` List of arguments. | -| `kwargs` | default is `\{\}` Dictionary of arguments. | +ParameterDescription`args` + default is `()` + + List of arguments. + `kwargs` + default is `{}` + + Dictionary of arguments. + ## index @@ -157,15 +195,24 @@ Perform string interpolation. Format strings contain replacement fields surround int string.index(sub, start=0, end=None) ``` -Returns the first index where `sub` is found, or raises an error if no such index exists, optionally restricting to `[start:end]``start` being inclusive and `end` being exclusive. + Returns the first index where `sub` is found, or raises an error if no such index exists, optionally restricting to `[start:end]` `start` being inclusive and `end` being exclusive. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sub` | [string](../core/string.mdx); required The substring to find. | -| `start` | [int](../core/int.mdx); or `None`; default is `0` Restrict to search from this position. | -| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | +ParameterDescription`sub`[string](../core/string.html); + required + + The substring to find. + `start`[int](../core/int.html); or `None`; + default is `0` + + Restrict to search from this position. + `end`[int](../core/int.html); or `None`; + default is `None` + + optional position before which to restrict to search. + ## isalnum @@ -173,7 +220,9 @@ Returns the first index where `sub` is found, or raises an error if no such inde bool string.isalnum() ``` -Returns True if all characters in the string are alphanumeric ([a-zA-Z0-9]) and there is at least one character. + Returns True if all characters in the string are alphanumeric (\[a-zA-Z0-9\]) and there is at least one character. + + ## isalpha @@ -181,7 +230,9 @@ Returns True if all characters in the string are alphanumeric ([a-zA-Z0-9]) and bool string.isalpha() ``` -Returns True if all characters in the string are alphabetic ([a-zA-Z]) and there is at least one character. + Returns True if all characters in the string are alphabetic (\[a-zA-Z\]) and there is at least one character. + + ## isdigit @@ -189,7 +240,9 @@ Returns True if all characters in the string are alphabetic ([a-zA-Z]) and there bool string.isdigit() ``` -Returns True if all characters in the string are digits ([0-9]) and there is at least one character. + Returns True if all characters in the string are digits (\[0-9\]) and there is at least one character. + + ## islower @@ -197,7 +250,9 @@ Returns True if all characters in the string are digits ([0-9]) and there is at bool string.islower() ``` -Returns True if all cased characters in the string are lowercase and there is at least one character. + Returns True if all cased characters in the string are lowercase and there is at least one character. + + ## isspace @@ -205,7 +260,9 @@ Returns True if all cased characters in the string are lowercase and there is at bool string.isspace() ``` -Returns True if all characters are white space characters and the string contains at least one character. + Returns True if all characters are white space characters and the string contains at least one character. + + ## istitle @@ -213,7 +270,9 @@ Returns True if all characters are white space characters and the string contain bool string.istitle() ``` -Returns True if the string is in title case and it contains at least one character. This means that every uppercase character must follow an uncased one (e.g. whitespace) and every lowercase character must follow a cased one (e.g. uppercase or lowercase). + Returns True if the string is in title case and it contains at least one character. This means that every uppercase character must follow an uncased one (e.g. whitespace) and every lowercase character must follow a cased one (e.g. uppercase or lowercase). + + ## isupper @@ -221,7 +280,9 @@ Returns True if the string is in title case and it contains at least one charact bool string.isupper() ``` -Returns True if all cased characters in the string are uppercase and there is at least one character. + Returns True if all cased characters in the string are uppercase and there is at least one character. + + ## join @@ -229,7 +290,7 @@ Returns True if all cased characters in the string are uppercase and there is at string string.join(elements) ``` -Returns a string in which the string elements of the argument have been joined by this string as a separator. Example: + Returns a string in which the string elements of the argument have been joined by this string as a separator. Example: ``` "|".join(["a", "b", "c"]) == "a|b|c" @@ -237,9 +298,12 @@ Returns a string in which the string elements of the argument have been joined b ### Parameters -| Parameter | Description | -| --- | --- | -| `elements` | iterable of [string](../core/string.mdx)s; required | +ParameterDescription`elements` + iterable of [string](../core/string.html) s; + required + + The objects to join. + ## lower @@ -247,7 +311,9 @@ Returns a string in which the string elements of the argument have been joined b string string.lower() ``` -Returns the lower case version of this string. + Returns the lower case version of this string. + + ## lstrip @@ -255,7 +321,7 @@ Returns the lower case version of this string. string string.lstrip(chars=None) ``` -Returns a copy of the string where leading characters that appear in `chars` are removed. Note that `chars` is not a prefix: all combinations of its value are removed: + Returns a copy of the string where leading characters that appear in `chars` are removed. Note that `chars` is not a prefix: all combinations of its value are removed: ``` "abcba".lstrip("ba") == "cba" @@ -263,9 +329,11 @@ Returns a copy of the string where leading characters that appear in `chars` are ### Parameters -| Parameter | Description | -| --- | --- | -| `chars` | [string](../core/string.mdx); or `None`; default is `None` The characters to remove, or all whitespace if None. | +ParameterDescription`chars`[string](../core/string.html); or `None`; + default is `None` + + The characters to remove, or all whitespace if None. + ## partition @@ -273,13 +341,16 @@ Returns a copy of the string where leading characters that appear in `chars` are tuple string.partition(sep) ``` -Splits the input string at the first occurrence of the separator `sep` and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, partition returns (self, '', ''). + Splits the input string at the first occurrence of the separator `sep` and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, partition returns (self, '', ''). + ### Parameters -| Parameter | Description | -| --- | --- | -| `sep` | [string](../core/string.mdx); required The string to split on. | +ParameterDescription`sep`[string](../core/string.html); + required + + The string to split on. + ## removeprefix @@ -287,13 +358,16 @@ Splits the input string at the first occurrence of the separator `sep` and retur string string.removeprefix(prefix) ``` -If the string starts with `prefix`, returns a new string with the prefix removed. Otherwise, returns the string. + If the string starts with `prefix`, returns a new string with the prefix removed. Otherwise, returns the string. + ### Parameters -| Parameter | Description | -| --- | --- | -| `prefix` | [string](../core/string.mdx); required The prefix to remove if present. | +ParameterDescription`prefix`[string](../core/string.html); + required + + The prefix to remove if present. + ## removesuffix @@ -301,13 +375,16 @@ If the string starts with `prefix`, returns a new string with the prefix removed string string.removesuffix(suffix) ``` -If the string ends with `suffix`, returns a new string with the suffix removed. Otherwise, returns the string. + If the string ends with `suffix`, returns a new string with the suffix removed. Otherwise, returns the string. + ### Parameters -| Parameter | Description | -| --- | --- | -| `suffix` | [string](../core/string.mdx); required The suffix to remove if present. | +ParameterDescription`suffix`[string](../core/string.html); + required + + The suffix to remove if present. + ## replace @@ -315,15 +392,24 @@ If the string ends with `suffix`, returns a new string with the suffix removed. string string.replace(old, new, count=-1) ``` -Returns a copy of the string in which the occurrences of `old` have been replaced with `new`, optionally restricting the number of replacements to `count`. + Returns a copy of the string in which the occurrences of `old` have been replaced with `new`, optionally restricting the number of replacements to `count`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `old` | [string](../core/string.mdx); required The string to be replaced. | -| `new` | [string](../core/string.mdx); required The string to replace with. | -| `count` | [int](../core/int.mdx); default is `-1` The maximum number of replacements. If omitted, or if the value is negative, there is no limit. | +ParameterDescription`old`[string](../core/string.html); + required + + The string to be replaced. + `new`[string](../core/string.html); + required + + The string to replace with. + `count`[int](../core/int.html); + default is `-1` + + The maximum number of replacements. If omitted, or if the value is negative, there is no limit. + ## rfind @@ -331,15 +417,24 @@ Returns a copy of the string in which the occurrences of `old` have been replace int string.rfind(sub, start=0, end=None) ``` -Returns the last index where `sub` is found, or -1 if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + Returns the last index where `sub` is found, or -1 if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sub` | [string](../core/string.mdx); required The substring to find. | -| `start` | [int](../core/int.mdx); or `None`; default is `0` Restrict to search from this position. | -| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | +ParameterDescription`sub`[string](../core/string.html); + required + + The substring to find. + `start`[int](../core/int.html); or `None`; + default is `0` + + Restrict to search from this position. + `end`[int](../core/int.html); or `None`; + default is `None` + + optional position before which to restrict to search. + ## rindex @@ -347,15 +442,24 @@ Returns the last index where `sub` is found, or -1 if no such index exists, opti int string.rindex(sub, start=0, end=None) ``` -Returns the last index where `sub` is found, or raises an error if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + Returns the last index where `sub` is found, or raises an error if no such index exists, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sub` | [string](../core/string.mdx); required The substring to find. | -| `start` | [int](../core/int.mdx); or `None`; default is `0` Restrict to search from this position. | -| `end` | [int](../core/int.mdx); or `None`; default is `None` optional position before which to restrict to search. | +ParameterDescription`sub`[string](../core/string.html); + required + + The substring to find. + `start`[int](../core/int.html); or `None`; + default is `0` + + Restrict to search from this position. + `end`[int](../core/int.html); or `None`; + default is `None` + + optional position before which to restrict to search. + ## rpartition @@ -363,13 +467,16 @@ Returns the last index where `sub` is found, or raises an error if no such index tuple string.rpartition(sep) ``` -Splits the input string at the last occurrence of the separator `sep` and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, rpartition returns ('', '', self). + Splits the input string at the last occurrence of the separator `sep` and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, rpartition returns ('', '', self). + ### Parameters -| Parameter | Description | -| --- | --- | -| `sep` | [string](../core/string.mdx); required The string to split on. | +ParameterDescription`sep`[string](../core/string.html); + required + + The string to split on. + ## rsplit @@ -377,14 +484,20 @@ Splits the input string at the last occurrence of the separator `sep` and return list string.rsplit(sep, maxsplit=unbound) ``` -Returns a list of all the words in the string, using `sep` as the separator, optionally limiting the number of splits to `maxsplit`. Except for splitting from the right, this method behaves like split(). + Returns a list of all the words in the string, using `sep` as the separator, optionally limiting the number of splits to `maxsplit`. Except for splitting from the right, this method behaves like split(). + ### Parameters -| Parameter | Description | -| --- | --- | -| `sep` | [string](../core/string.mdx); required The string to split on. | -| `maxsplit` | [int](../core/int.mdx); default is `unbound` The maximum number of splits. | +ParameterDescription`sep`[string](../core/string.html); + required + + The string to split on. + `maxsplit`[int](../core/int.html); + default is `unbound` + + The maximum number of splits. + ## rstrip @@ -392,7 +505,7 @@ Returns a list of all the words in the string, using `sep` as the separator, opt string string.rstrip(chars=None) ``` -Returns a copy of the string where trailing characters that appear in `chars` are removed. Note that `chars` is not a suffix: all combinations of its value are removed: + Returns a copy of the string where trailing characters that appear in `chars` are removed. Note that `chars` is not a suffix: all combinations of its value are removed: ``` "abcbaa".rstrip("ab") == "abc" @@ -400,9 +513,11 @@ Returns a copy of the string where trailing characters that appear in `chars` ar ### Parameters -| Parameter | Description | -| --- | --- | -| `chars` | [string](../core/string.mdx); or `None`; default is `None` The characters to remove, or all whitespace if None. | +ParameterDescription`chars`[string](../core/string.html); or `None`; + default is `None` + + The characters to remove, or all whitespace if None. + ## split @@ -410,14 +525,20 @@ Returns a copy of the string where trailing characters that appear in `chars` ar list string.split(sep, maxsplit=unbound) ``` -Returns a list of all the words in the string, using `sep` as the separator, optionally limiting the number of splits to `maxsplit`. + Returns a list of all the words in the string, using `sep` as the separator, optionally limiting the number of splits to `maxsplit`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sep` | [string](../core/string.mdx); required The string to split on. | -| `maxsplit` | [int](../core/int.mdx); default is `unbound` The maximum number of splits. | +ParameterDescription`sep`[string](../core/string.html); + required + + The string to split on. + `maxsplit`[int](../core/int.html); + default is `unbound` + + The maximum number of splits. + ## splitlines @@ -425,13 +546,16 @@ Returns a list of all the words in the string, using `sep` as the separator, opt sequence string.splitlines(keepends=False) ``` -Splits the string at line boundaries ('\n', '\r\n', '\r') and returns the result as a new mutable list. + Splits the string at line boundaries ('\\n', '\\r\\n', '\\r') and returns the result as a new mutable list. + ### Parameters -| Parameter | Description | -| --- | --- | -| `keepends` | [bool](../core/bool.mdx); default is `False` Whether the line breaks should be included in the resulting list. | +ParameterDescription`keepends`[bool](../core/bool.html); + default is `False` + + Whether the line breaks should be included in the resulting list. + ## startswith @@ -439,15 +563,24 @@ Splits the string at line boundaries ('\n', '\r\n', '\r') and returns the result bool string.startswith(sub, start=0, end=None) ``` -Returns True if the string starts with `sub`, otherwise False, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + Returns True if the string starts with `sub`, otherwise False, optionally restricting to `[start:end]`, `start` being inclusive and `end` being exclusive. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sub` | [string](../core/string.mdx); or [tuple](../core/tuple.mdx) of [string](../core/string.mdx)s; required The prefix (or tuple of alternative prefixes) to match. | -| `start` | [int](../core/int.mdx); or `None`; default is `0` Test beginning at this position. | -| `end` | [int](../core/int.mdx); or `None`; default is `None` Stop comparing at this position. | +ParameterDescription`sub`[string](../core/string.html); or [tuple](../core/tuple.html) of [string](../core/string.html) s; + required + + The prefix (or tuple of alternative prefixes) to match. + `start`[int](../core/int.html); or `None`; + default is `0` + + Test beginning at this position. + `end`[int](../core/int.html); or `None`; + default is `None` + + Stop comparing at this position. + ## strip @@ -455,7 +588,7 @@ Returns True if the string starts with `sub`, otherwise False, optionally restri string string.strip(chars=None) ``` -Returns a copy of the string where leading or trailing characters that appear in `chars` are removed. Note that `chars` is neither a prefix nor a suffix: all combinations of its value are removed: + Returns a copy of the string where leading or trailing characters that appear in `chars` are removed. Note that `chars` is neither a prefix nor a suffix: all combinations of its value are removed: ``` "aabcbcbaa".strip("ab") == "cbc" @@ -463,9 +596,11 @@ Returns a copy of the string where leading or trailing characters that appear in ### Parameters -| Parameter | Description | -| --- | --- | -| `chars` | [string](../core/string.mdx); or `None`; default is `None` The characters to remove, or all whitespace if None. | +ParameterDescription`chars`[string](../core/string.html); or `None`; + default is `None` + + The characters to remove, or all whitespace if None. + ## title @@ -473,7 +608,9 @@ Returns a copy of the string where leading or trailing characters that appear in string string.title() ``` -Converts the input string into title case, i.e. every word starts with an uppercase letter while the remaining letters are lowercase. In this context, a word means strictly a sequence of letters. This method does not support supplementary Unicode characters. + Converts the input string into title case, i.e. every word starts with an uppercase letter while the remaining letters are lowercase. In this context, a word means strictly a sequence of letters. This method does not support supplementary Unicode characters. + + ## upper @@ -481,4 +618,4 @@ Converts the input string into title case, i.e. every word starts with an upperc string string.upper() ``` -Returns the upper case version of this string. \ No newline at end of file + Returns the upper case version of this string. diff --git a/rules/lib/core/tuple.mdx b/rules/lib/core/tuple.mdx index bac6886..83e21c1 100644 --- a/rules/lib/core/tuple.mdx +++ b/rules/lib/core/tuple.mdx @@ -3,19 +3,20 @@ title: 'tuple' --- -The built-in tuple type. Example tuple expressions: + +The built-in tuple type. Example tuple expressions: ``` x = (1, 2, 3) ``` -Accessing elements is possible using indexing (starts from `0`): +Accessing elements is possible using indexing (starts from `0`): ``` e = x[1] # e == 2 ``` -Lists support the `+` operator to concatenate two tuples. Example: +Lists support the `+` operator to concatenate two tuples. Example: ``` x = (1, 2) + (3, 4) # x == (1, 2, 3, 4) @@ -31,4 +32,4 @@ Similar to lists, tuples support slice operations: ('a', 'b', 'c', 'd')[3:0:-1] # ('d', 'c', 'b') ``` -Tuples are immutable, therefore `x[1] = "a"` is not supported. \ No newline at end of file +Tuples are immutable, therefore `x[1] = "a"` is not supported. diff --git a/rules/lib/fragments.mdx b/rules/lib/fragments.mdx index 729bb53..c156efe 100644 --- a/rules/lib/fragments.mdx +++ b/rules/lib/fragments.mdx @@ -1,20 +1,20 @@ --- -title: 'fragments' +title: 'Configuration Fragments' --- -Configuration fragments give rules access to language-specific parts of [configuration](builtins/configuration.mdx). +Configuration fragments give rules access to language-specific parts of [configuration](builtins/configuration.html). Rule implementations can get them using `ctx.fragments.[fragment name]` -* [apple](./rules/lib/fragments/apple) -* [bazel\_android](./rules/lib/fragments/bazel_android) -* [bazel\_py](./rules/lib/fragments/bazel_py) -* [coverage](./rules/lib/fragments/coverage) -* [cpp](./rules/lib/fragments/cpp) -* [j2objc](./rules/lib/fragments/j2objc) -* [java](./rules/lib/fragments/java) -* [objc](./rules/lib/fragments/objc) -* [platform](./rules/lib/fragments/platform) -* [proto](./rules/lib/fragments/proto) -* [py](./rules/lib/fragments/py) \ No newline at end of file +- [apple](/rules/lib/fragments/apple) +- [bazel\_android](/rules/lib/fragments/bazel_android) +- [bazel\_py](/rules/lib/fragments/bazel_py) +- [coverage](/rules/lib/fragments/coverage) +- [cpp](/rules/lib/fragments/cpp) +- [j2objc](/rules/lib/fragments/j2objc) +- [java](/rules/lib/fragments/java) +- [objc](/rules/lib/fragments/objc) +- [platform](/rules/lib/fragments/platform) +- [proto](/rules/lib/fragments/proto) +- [py](/rules/lib/fragments/py) diff --git a/rules/lib/fragments/apple.mdx b/rules/lib/fragments/apple.mdx index 61b7b02..5aab773 100644 --- a/rules/lib/fragments/apple.mdx +++ b/rules/lib/fragments/apple.mdx @@ -3,13 +3,14 @@ title: 'apple' --- + A configuration fragment for Apple platforms. ## Members -* [multi\_arch\_platform](#multi_arch_platform) -* [single\_arch\_cpu](#single_arch_cpu) -* [single\_arch\_platform](#single_arch_platform) +- [multi\_arch\_platform](#multi_arch_platform) +- [single\_arch\_cpu](#single_arch_cpu) +- [single\_arch\_platform](#single_arch_platform) ## multi\_arch\_platform @@ -17,13 +18,16 @@ A configuration fragment for Apple platforms. apple_platform apple.multi_arch_platform(platform_type) ``` -The platform of the current configuration for the given platform type. This should only be invoked in a context where multiple architectures may be supported; consider [single\_arch\_platform](#single_arch_platform) for other cases. + The platform of the current configuration for the given platform type. This should only be invoked in a context where multiple architectures may be supported; consider [single\_arch\_platform](#single_arch_platform) for other cases. + ### Parameters -| Parameter | Description | -| --- | --- | -| `platform_type` | [string](../core/string.mdx); required The apple platform type. | +ParameterDescription`platform_type`[string](../core/string.html); + required + + The apple platform type. + ## single\_arch\_cpu @@ -31,7 +35,9 @@ The platform of the current configuration for the given platform type. This shou string apple.single_arch_cpu ``` -The single "effective" architecture for this configuration (e.g., `i386` or `arm64`) in the context of rule logic that is only concerned with a single architecture (such as `objc_library`, which registers single-architecture compile actions). + The single "effective" architecture for this configuration (e.g., `i386` or `arm64`) in the context of rule logic that is only concerned with a single architecture (such as `objc_library`, which registers single-architecture compile actions). + + ## single\_arch\_platform @@ -39,4 +45,4 @@ The single "effective" architecture for this configuration (e.g., `i386` or `arm apple_platform apple.single_arch_platform ``` -The platform of the current configuration. This should only be invoked in a context where only a single architecture may be supported; consider [multi\_arch\_platform](#multi_arch_platform) for other cases. \ No newline at end of file + The platform of the current configuration. This should only be invoked in a context where only a single architecture may be supported; consider [multi\_arch\_platform](#multi_arch_platform) for other cases. diff --git a/rules/lib/fragments/bazel_android.mdx b/rules/lib/fragments/bazel_android.mdx index a1655f7..44b9b69 100644 --- a/rules/lib/fragments/bazel_android.mdx +++ b/rules/lib/fragments/bazel_android.mdx @@ -1,11 +1,12 @@ --- -title: 'bazel_android' +title: 'bazel\_android' --- + ## Members -* [merge\_android\_manifest\_permissions](#merge_android_manifest_permissions) +- [merge\_android\_manifest\_permissions](#merge_android_manifest_permissions) ## merge\_android\_manifest\_permissions @@ -13,4 +14,4 @@ title: 'bazel_android' bool bazel_android.merge_android_manifest_permissions ``` -The value of --merge\_android\_manifest\_permissions flag. \ No newline at end of file + The value of --merge\_android\_manifest\_permissions flag. diff --git a/rules/lib/fragments/bazel_py.mdx b/rules/lib/fragments/bazel_py.mdx index 394f74a..d2f9d86 100644 --- a/rules/lib/fragments/bazel_py.mdx +++ b/rules/lib/fragments/bazel_py.mdx @@ -1,12 +1,13 @@ --- -title: 'bazel_py' +title: 'bazel\_py' --- + ## Members -* [python\_import\_all\_repositories](#python_import_all_repositories) -* [python\_path](#python_path) +- [python\_import\_all\_repositories](#python_import_all_repositories) +- [python\_path](#python_path) ## python\_import\_all\_repositories @@ -14,7 +15,9 @@ title: 'bazel_py' bool bazel_py.python_import_all_repositories ``` -The value of the --experimental\_python\_import\_all\_repositories flag. + The value of the --experimental\_python\_import\_all\_repositories flag. + + ## python\_path @@ -22,4 +25,4 @@ The value of the --experimental\_python\_import\_all\_repositories flag. string bazel_py.python_path ``` -The value of the --python\_path flag. \ No newline at end of file + The value of the --python\_path flag. diff --git a/rules/lib/fragments/coverage.mdx b/rules/lib/fragments/coverage.mdx index 357c29f..072d74b 100644 --- a/rules/lib/fragments/coverage.mdx +++ b/rules/lib/fragments/coverage.mdx @@ -3,11 +3,12 @@ title: 'coverage' --- + A configuration fragment representing the coverage configuration. ## Members -* [output\_generator](#output_generator) +- [output\_generator](#output_generator) ## output\_generator @@ -15,15 +16,15 @@ A configuration fragment representing the coverage configuration. Label coverage.output_generator ``` -Returns the label pointed to by the [`--coverage_output_generator`](https://bazel.build/reference/command-line-reference#flag--coverage_output_generator) option if coverage collection is enabled, otherwise returns `None`. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): + Returns the label pointed to by the [`--coverage_output_generator`](https://bazel.build/reference/command-line-reference#flag--coverage_output_generator) option if coverage collection is enabled, otherwise returns `None`. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): ``` -attr.label( - default = configuration_field( - fragment = "coverage", - name = "output_generator" - ) +attr.label( + default = configuration_field( + fragment = "coverage", + name = "output_generator" + ) ) ``` -May return `None`. \ No newline at end of file + May return `None`. diff --git a/rules/lib/fragments/cpp.mdx b/rules/lib/fragments/cpp.mdx index f516b69..c4c7a6c 100644 --- a/rules/lib/fragments/cpp.mdx +++ b/rules/lib/fragments/cpp.mdx @@ -3,19 +3,20 @@ title: 'cpp' --- + A configuration fragment for C++. ## Members -* [apple\_generate\_dsym](#apple_generate_dsym) -* [conlyopts](#conlyopts) -* [copts](#copts) -* [custom\_malloc](#custom_malloc) -* [cxxopts](#cxxopts) -* [linkopts](#linkopts) -* [objc\_generate\_linkmap](#objc_generate_linkmap) -* [objc\_should\_strip\_binary](#objc_should_strip_binary) -* [objccopts](#objccopts) +- [apple\_generate\_dsym](#apple_generate_dsym) +- [conlyopts](#conlyopts) +- [copts](#copts) +- [custom\_malloc](#custom_malloc) +- [cxxopts](#cxxopts) +- [linkopts](#linkopts) +- [objc\_generate\_linkmap](#objc_generate_linkmap) +- [objc\_should\_strip\_binary](#objc_should_strip_binary) +- [objccopts](#objccopts) ## apple\_generate\_dsym @@ -23,7 +24,9 @@ A configuration fragment for C++. bool cpp.apple_generate_dsym ``` -Whether to generate Apple debug symbol(.dSYM) artifacts. + Whether to generate Apple debug symbol(.dSYM) artifacts. + + ## conlyopts @@ -31,7 +34,9 @@ Whether to generate Apple debug symbol(.dSYM) artifacts. list cpp.conlyopts ``` -The flags passed to Bazel by [`--conlyopt`](./docs/user-manual#flag--conlyopt) option. + The flags passed to Bazel by [`--conlyopt`](/docs/user-manual#flag--conlyopt) option. + + ## copts @@ -39,7 +44,9 @@ The flags passed to Bazel by [`--conlyopt`](./docs/user-manual#flag--conlyopt) o list cpp.copts ``` -The flags passed to Bazel by [`--copt`](./docs/user-manual#flag--copt) option. + The flags passed to Bazel by [`--copt`](/docs/user-manual#flag--copt) option. + + ## custom\_malloc @@ -47,18 +54,20 @@ The flags passed to Bazel by [`--copt`](./docs/user-manual#flag--copt) option. Label cpp.custom_malloc ``` -Returns label pointed to by [`--custom_malloc`](./docs/user-manual#flag--custom_malloc) option. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): + Returns label pointed to by [`--custom_malloc`](/docs/user-manual#flag--custom_malloc) option. Can be accessed with [`configuration_field`](../globals/bzl.html#configuration_field): ``` -attr.label( - default = configuration_field( - fragment = "cpp", - name = "custom_malloc" - ) +attr.label( + default = configuration_field( + fragment = "cpp", + name = "custom_malloc" + ) ) ``` -May return `None`. + May return `None`. + + ## cxxopts @@ -66,7 +75,9 @@ May return `None`. list cpp.cxxopts ``` -The flags passed to Bazel by [`--cxxopt`](./docs/user-manual#flag--cxxopt) option. + The flags passed to Bazel by [`--cxxopt`](/docs/user-manual#flag--cxxopt) option. + + ## linkopts @@ -74,7 +85,9 @@ The flags passed to Bazel by [`--cxxopt`](./docs/user-manual#flag--cxxopt) optio list cpp.linkopts ``` -The flags passed to Bazel by [`--linkopt`](./docs/user-manual#flag--linkopt) option. + The flags passed to Bazel by [`--linkopt`](/docs/user-manual#flag--linkopt) option. + + ## objc\_generate\_linkmap @@ -82,7 +95,9 @@ The flags passed to Bazel by [`--linkopt`](./docs/user-manual#flag--linkopt) opt bool cpp.objc_generate_linkmap ``` -(Apple-only) Whether to generate linkmap artifacts. + (Apple-only) Whether to generate linkmap artifacts. + + ## objc\_should\_strip\_binary @@ -90,7 +105,9 @@ bool cpp.objc_generate_linkmap bool cpp.objc_should_strip_binary ``` -(Apple-only) whether to perform symbol and dead-code strippings on linked binaries. + (Apple-only) whether to perform symbol and dead-code strippings on linked binaries. + + ## objccopts @@ -98,4 +115,4 @@ bool cpp.objc_should_strip_binary list cpp.objccopts ``` -The flags passed to Bazel by [`--objccopt`](./docs/user-manual#flag--objccopt) option. \ No newline at end of file + The flags passed to Bazel by [`--objccopt`](/docs/user-manual#flag--objccopt) option. diff --git a/rules/lib/fragments/j2objc.mdx b/rules/lib/fragments/j2objc.mdx index 05923d9..4553e0d 100644 --- a/rules/lib/fragments/j2objc.mdx +++ b/rules/lib/fragments/j2objc.mdx @@ -3,11 +3,12 @@ title: 'j2objc' --- + A configuration fragment for j2Objc. ## Members -* [translation\_flags](#translation_flags) +- [translation\_flags](#translation_flags) ## translation\_flags @@ -15,4 +16,4 @@ A configuration fragment for j2Objc. list j2objc.translation_flags ``` -The list of flags to be used when the j2objc compiler is invoked. \ No newline at end of file + The list of flags to be used when the j2objc compiler is invoked. diff --git a/rules/lib/fragments/java.mdx b/rules/lib/fragments/java.mdx index a42a07b..d11a6d1 100644 --- a/rules/lib/fragments/java.mdx +++ b/rules/lib/fragments/java.mdx @@ -3,24 +3,25 @@ title: 'java' --- + A java compiler configuration. ## Members -* [bytecode\_optimization\_pass\_actions](#bytecode_optimization_pass_actions) -* [bytecode\_optimizer\_mnemonic](#bytecode_optimizer_mnemonic) -* [default\_javac\_flags](#default_javac_flags) -* [default\_javac\_flags\_depset](#default_javac_flags_depset) -* [default\_jvm\_opts](#default_jvm_opts) -* [disallow\_java\_import\_exports](#disallow_java_import_exports) -* [multi\_release\_deploy\_jars](#multi_release_deploy_jars) -* [one\_version\_enforcement\_level](#one_version_enforcement_level) -* [plugins](#plugins) -* [run\_android\_lint](#run_android_lint) -* [split\_bytecode\_optimization\_pass](#split_bytecode_optimization_pass) -* [strict\_java\_deps](#strict_java_deps) -* [use\_header\_compilation\_direct\_deps](#use_header_compilation_direct_deps) -* [use\_ijars](#use_ijars) +- [bytecode\_optimization\_pass\_actions](#bytecode_optimization_pass_actions) +- [bytecode\_optimizer\_mnemonic](#bytecode_optimizer_mnemonic) +- [default\_javac\_flags](#default_javac_flags) +- [default\_javac\_flags\_depset](#default_javac_flags_depset) +- [default\_jvm\_opts](#default_jvm_opts) +- [disallow\_java\_import\_exports](#disallow_java_import_exports) +- [multi\_release\_deploy\_jars](#multi_release_deploy_jars) +- [one\_version\_enforcement\_level](#one_version_enforcement_level) +- [plugins](#plugins) +- [run\_android\_lint](#run_android_lint) +- [split\_bytecode\_optimization\_pass](#split_bytecode_optimization_pass) +- [strict\_java\_deps](#strict_java_deps) +- [use\_header\_compilation\_direct\_deps](#use_header_compilation_direct_deps) +- [use\_ijars](#use_ijars) ## bytecode\_optimization\_pass\_actions @@ -28,7 +29,9 @@ A java compiler configuration. int java.bytecode_optimization_pass_actions ``` -This specifies the number of actions to divide the OPTIMIZATION stage of the bytecode optimizer into. Note that if split\_bytecode\_optimization\_pass is set, this will only change behavior if it is > 2. + This specifies the number of actions to divide the OPTIMIZATION stage of the bytecode optimizer into. Note that if split\_bytecode\_optimization\_pass is set, this will only change behavior if it is > 2. + + ## bytecode\_optimizer\_mnemonic @@ -36,7 +39,9 @@ This specifies the number of actions to divide the OPTIMIZATION stage of the byt string java.bytecode_optimizer_mnemonic ``` -The mnemonic for the bytecode optimizer. + The mnemonic for the bytecode optimizer. + + ## default\_javac\_flags @@ -44,7 +49,9 @@ The mnemonic for the bytecode optimizer. list java.default_javac_flags ``` -The default flags for the Java compiler. + The default flags for the Java compiler. + + ## default\_javac\_flags\_depset @@ -52,7 +59,9 @@ The default flags for the Java compiler. depset java.default_javac_flags_depset ``` -The default flags for the Java compiler. + The default flags for the Java compiler. + + ## default\_jvm\_opts @@ -60,7 +69,9 @@ The default flags for the Java compiler. list java.default_jvm_opts ``` -Additional options to pass to the Java VM for each java\_binary target + Additional options to pass to the Java VM for each java\_binary target + + ## disallow\_java\_import\_exports @@ -68,7 +79,9 @@ Additional options to pass to the Java VM for each java\_binary target bool java.disallow_java_import_exports() ``` -Returns true if java\_import exports are not allowed. + Returns true if java\_import exports are not allowed. + + ## multi\_release\_deploy\_jars @@ -76,7 +89,9 @@ Returns true if java\_import exports are not allowed. bool java.multi_release_deploy_jars ``` -The value of the --incompatible\_multi\_release\_deploy\_jars flag. + The value of the --incompatible\_multi\_release\_deploy\_jars flag. + + ## one\_version\_enforcement\_level @@ -84,7 +99,9 @@ The value of the --incompatible\_multi\_release\_deploy\_jars flag. string java.one_version_enforcement_level ``` -The value of the --experimental\_one\_version\_enforcement flag. + The value of the --experimental\_one\_version\_enforcement flag. + + ## plugins @@ -92,7 +109,9 @@ The value of the --experimental\_one\_version\_enforcement flag. list java.plugins ``` -A list containing the labels provided with --plugins, if any. + A list containing the labels provided with --plugins, if any. + + ## run\_android\_lint @@ -100,7 +119,9 @@ A list containing the labels provided with --plugins, if any. bool java.run_android_lint ``` -The value of the --experimental\_run\_android\_lint\_on\_java\_rules flag. + The value of the --experimental\_run\_android\_lint\_on\_java\_rules flag. + + ## split\_bytecode\_optimization\_pass @@ -108,7 +129,9 @@ The value of the --experimental\_run\_android\_lint\_on\_java\_rules flag. bool java.split_bytecode_optimization_pass ``` -Returns whether the OPTIMIZATION stage of the bytecode optimizer will be split across two actions. + Returns whether the OPTIMIZATION stage of the bytecode optimizer will be split across two actions. + + ## strict\_java\_deps @@ -116,7 +139,9 @@ Returns whether the OPTIMIZATION stage of the bytecode optimizer will be split a string java.strict_java_deps ``` -The value of the strict\_java\_deps flag. + The value of the strict\_java\_deps flag. + + ## use\_header\_compilation\_direct\_deps @@ -124,7 +149,9 @@ The value of the strict\_java\_deps flag. bool java.use_header_compilation_direct_deps() ``` -Returns true if Java header compilation should use separate outputs for direct deps. + Returns true if Java header compilation should use separate outputs for direct deps. + + ## use\_ijars @@ -132,4 +159,4 @@ Returns true if Java header compilation should use separate outputs for direct d bool java.use_ijars() ``` -Returns true iff Java compilation should use ijars. \ No newline at end of file + Returns true iff Java compilation should use ijars. diff --git a/rules/lib/fragments/objc.mdx b/rules/lib/fragments/objc.mdx index ef26650..bf75be1 100644 --- a/rules/lib/fragments/objc.mdx +++ b/rules/lib/fragments/objc.mdx @@ -3,20 +3,21 @@ title: 'objc' --- + A configuration fragment for Objective-C. ## Members -* [alwayslink\_by\_default](#alwayslink_by_default) -* [builtin\_objc\_strip\_action](#builtin_objc_strip_action) -* [copts\_for\_current\_compilation\_mode](#copts_for_current_compilation_mode) -* [disallow\_sdk\_frameworks\_attributes](#disallow_sdk_frameworks_attributes) -* [ios\_simulator\_device](#ios_simulator_device) -* [ios\_simulator\_version](#ios_simulator_version) -* [run\_memleaks](#run_memleaks) -* [signing\_certificate\_name](#signing_certificate_name) -* [strip\_executable\_safely](#strip_executable_safely) -* [uses\_device\_debug\_entitlements](#uses_device_debug_entitlements) +- [alwayslink\_by\_default](#alwayslink_by_default) +- [builtin\_objc\_strip\_action](#builtin_objc_strip_action) +- [copts\_for\_current\_compilation\_mode](#copts_for_current_compilation_mode) +- [disallow\_sdk\_frameworks\_attributes](#disallow_sdk_frameworks_attributes) +- [ios\_simulator\_device](#ios_simulator_device) +- [ios\_simulator\_version](#ios_simulator_version) +- [run\_memleaks](#run_memleaks) +- [signing\_certificate\_name](#signing_certificate_name) +- [strip\_executable\_safely](#strip_executable_safely) +- [uses\_device\_debug\_entitlements](#uses_device_debug_entitlements) ## alwayslink\_by\_default @@ -24,7 +25,9 @@ A configuration fragment for Objective-C. bool objc.alwayslink_by_default ``` -Returns whether objc\_library and objc\_import should default to alwayslink=True. + Returns whether objc\_library and objc\_import should default to alwayslink=True. + + ## builtin\_objc\_strip\_action @@ -32,7 +35,9 @@ Returns whether objc\_library and objc\_import should default to alwayslink=True bool objc.builtin_objc_strip_action ``` -Returns whether to emit a strip action as part of objc linking. + Returns whether to emit a strip action as part of objc linking. + + ## copts\_for\_current\_compilation\_mode @@ -40,7 +45,9 @@ Returns whether to emit a strip action as part of objc linking. list objc.copts_for_current_compilation_mode ``` -Returns a list of default options to use for compiling Objective-C in the current mode. + Returns a list of default options to use for compiling Objective-C in the current mode. + + ## disallow\_sdk\_frameworks\_attributes @@ -48,7 +55,9 @@ Returns a list of default options to use for compiling Objective-C in the curren bool objc.disallow_sdk_frameworks_attributes ``` -Returns whether sdk\_frameworks and weak\_sdk\_frameworks are disallowed attributes. + Returns whether sdk\_frameworks and weak\_sdk\_frameworks are disallowed attributes. + + ## ios\_simulator\_device @@ -56,8 +65,10 @@ Returns whether sdk\_frameworks and weak\_sdk\_frameworks are disallowed attribu string objc.ios_simulator_device ``` -The type of device (e.g. 'iPhone 6') to use when running on the simulator. -May return `None`. + The type of device (e.g. 'iPhone 6') to use when running on the simulator. + May return `None`. + + ## ios\_simulator\_version @@ -65,8 +76,10 @@ May return `None`. DottedVersion objc.ios_simulator_version ``` -The SDK version of the iOS simulator to use when running on the simulator. -May return `None`. + The SDK version of the iOS simulator to use when running on the simulator. + May return `None`. + + ## run\_memleaks @@ -74,7 +87,9 @@ May return `None`. bool objc.run_memleaks ``` -Returns a boolean indicating whether memleaks should be run during tests or not. + Returns a boolean indicating whether memleaks should be run during tests or not. + + ## signing\_certificate\_name @@ -82,8 +97,10 @@ Returns a boolean indicating whether memleaks should be run during tests or not. string objc.signing_certificate_name ``` -Returns the flag-supplied certificate name to be used in signing, or None if no such certificate was specified. -May return `None`. + Returns the flag-supplied certificate name to be used in signing, or None if no such certificate was specified. + May return `None`. + + ## strip\_executable\_safely @@ -91,7 +108,9 @@ May return `None`. bool objc.strip_executable_safely ``` -Returns whether executable strip action should use flag -x, which does not break dynamic symbol resolution. + Returns whether executable strip action should use flag -x, which does not break dynamic symbol resolution. + + ## uses\_device\_debug\_entitlements @@ -99,4 +118,4 @@ Returns whether executable strip action should use flag -x, which does not break bool objc.uses_device_debug_entitlements ``` -Returns whether device debug entitlements should be included when signing an application. \ No newline at end of file + Returns whether device debug entitlements should be included when signing an application. diff --git a/rules/lib/fragments/platform.mdx b/rules/lib/fragments/platform.mdx index 704068e..d6a525d 100644 --- a/rules/lib/fragments/platform.mdx +++ b/rules/lib/fragments/platform.mdx @@ -3,12 +3,13 @@ title: 'platform' --- + The platform configuration. ## Members -* [host\_platform](#host_platform) -* [platform](#platform) +- [host\_platform](#host_platform) +- [platform](#platform) ## host\_platform @@ -16,7 +17,9 @@ The platform configuration. Label platform.host_platform ``` -The current host platform + The current host platform + + ## platform @@ -24,4 +27,4 @@ The current host platform Label platform.platform ``` -The current target platform \ No newline at end of file + The current target platform diff --git a/rules/lib/fragments/proto.mdx b/rules/lib/fragments/proto.mdx index 22ffd17..e1eb8a5 100644 --- a/rules/lib/fragments/proto.mdx +++ b/rules/lib/fragments/proto.mdx @@ -3,4 +3,5 @@ title: 'proto' --- -A configuration fragment representing protocol buffers. \ No newline at end of file + +A configuration fragment representing protocol buffers. diff --git a/rules/lib/fragments/py.mdx b/rules/lib/fragments/py.mdx index c51900c..a23c187 100644 --- a/rules/lib/fragments/py.mdx +++ b/rules/lib/fragments/py.mdx @@ -3,17 +3,18 @@ title: 'py' --- + A configuration fragment for Python. ## Members -* [build\_python\_zip](#build_python_zip) -* [default\_python\_version](#default_python_version) -* [default\_to\_explicit\_init\_py](#default_to_explicit_init_py) -* [disable\_py2](#disable_py2) -* [disallow\_native\_rules](#disallow_native_rules) -* [include\_label\_in\_linkstamp](#include_label_in_linkstamp) -* [use\_toolchains](#use_toolchains) +- [build\_python\_zip](#build_python_zip) +- [default\_python\_version](#default_python_version) +- [default\_to\_explicit\_init\_py](#default_to_explicit_init_py) +- [disable\_py2](#disable_py2) +- [disallow\_native\_rules](#disallow_native_rules) +- [include\_label\_in\_linkstamp](#include_label_in_linkstamp) +- [use\_toolchains](#use_toolchains) ## build\_python\_zip @@ -21,7 +22,9 @@ A configuration fragment for Python. bool py.build_python_zip ``` -The effective value of --build\_python\_zip + The effective value of --build\_python\_zip + + ## default\_python\_version @@ -29,7 +32,9 @@ The effective value of --build\_python\_zip string py.default_python_version ``` -No-op: PY3 is the default Python version. + No-op: PY3 is the default Python version. + + ## default\_to\_explicit\_init\_py @@ -37,7 +42,9 @@ No-op: PY3 is the default Python version. bool py.default_to_explicit_init_py ``` -The value from the --incompatible\_default\_to\_explicit\_init\_py flag + The value from the --incompatible\_default\_to\_explicit\_init\_py flag + + ## disable\_py2 @@ -45,7 +52,9 @@ The value from the --incompatible\_default\_to\_explicit\_init\_py flag bool py.disable_py2 ``` -No-op: PY2 is no longer supported. + No-op: PY2 is no longer supported. + + ## disallow\_native\_rules @@ -53,7 +62,9 @@ No-op: PY2 is no longer supported. bool py.disallow_native_rules ``` -The value of the --incompatible\_python\_disallow\_native\_rules flag. + The value of the --incompatible\_python\_disallow\_native\_rules flag. + + ## include\_label\_in\_linkstamp @@ -61,7 +72,9 @@ The value of the --incompatible\_python\_disallow\_native\_rules flag. bool py.include_label_in_linkstamp ``` -Whether the build label is included in unstamped builds. + Whether the build label is included in unstamped builds. + + ## use\_toolchains @@ -69,4 +82,4 @@ Whether the build label is included in unstamped builds. bool py.use_toolchains ``` -No-op: Python toolchains are always used. \ No newline at end of file + No-op: Python toolchains are always used. diff --git a/rules/lib/globals.mdx b/rules/lib/globals.mdx index f74bca9..13ced52 100644 --- a/rules/lib/globals.mdx +++ b/rules/lib/globals.mdx @@ -1,13 +1,13 @@ --- -title: 'globals' +title: 'Global functions' --- This section lists the global functions available in Starlark. The list of available functions differs depending on the file type (whether a BUILD file, or a .bzl file, etc). -* [.bzl files](./rules/lib/globals/bzl) -* [All Bazel files](./rules/lib/globals/all) -* [BUILD files](./rules/lib/globals/build) -* [MODULE.bazel files](./rules/lib/globals/module) -* [REPO.bazel files](./rules/lib/globals/repo) -* [VENDOR.bazel files](./rules/lib/globals/vendor) \ No newline at end of file +- [.bzl files](/rules/lib/globals/bzl) +- [All Bazel files](/rules/lib/globals/all) +- [BUILD files](/rules/lib/globals/build) +- [MODULE.bazel files](/rules/lib/globals/module) +- [REPO.bazel files](/rules/lib/globals/repo) +- [VENDOR.bazel files](/rules/lib/globals/vendor) diff --git a/rules/lib/globals/all.mdx b/rules/lib/globals/all.mdx index 6711ea1..01641e9 100644 --- a/rules/lib/globals/all.mdx +++ b/rules/lib/globals/all.mdx @@ -1,39 +1,40 @@ --- -title: 'all' +title: 'All Bazel files' --- + Methods available in all Bazel files, including .bzl files, BUILD, MODULE.bazel, VENDOR.bazel, and WORKSPACE. ## Members -* [abs](#abs) -* [all](#all) -* [any](#any) -* [bool](#bool) -* [dict](#dict) -* [dir](#dir) -* [enumerate](#enumerate) -* [fail](#fail) -* [float](#float) -* [getattr](#getattr) -* [hasattr](#hasattr) -* [hash](#hash) -* [int](#int) -* [len](#len) -* [list](#list) -* [max](#max) -* [min](#min) -* [print](#print) -* [range](#range) -* [repr](#repr) -* [reversed](#reversed) -* [set](#set) -* [sorted](#sorted) -* [str](#str) -* [tuple](#tuple) -* [type](#type) -* [zip](#zip) +- [abs](#abs) +- [all](#all) +- [any](#any) +- [bool](#bool) +- [dict](#dict) +- [dir](#dir) +- [enumerate](#enumerate) +- [fail](#fail) +- [float](#float) +- [getattr](#getattr) +- [hasattr](#hasattr) +- [hash](#hash) +- [int](#int) +- [len](#len) +- [list](#list) +- [max](#max) +- [min](#min) +- [print](#print) +- [range](#range) +- [repr](#repr) +- [reversed](#reversed) +- [set](#set) +- [sorted](#sorted) +- [str](#str) +- [tuple](#tuple) +- [type](#type) +- [zip](#zip) ## abs @@ -41,7 +42,7 @@ Methods available in all Bazel files, including .bzl files, BUILD, MODULE.bazel, unknown abs(x) ``` -Returns the absolute value of a number (a non-negative number with the same magnitude). + Returns the absolute value of a number (a non-negative number with the same magnitude). ``` abs(-2.3) == 2.3 @@ -49,9 +50,11 @@ abs(-2.3) == 2.3 ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | [int](../core/int.mdx); or [float](../core/float.mdx); required A number (int or float) | +ParameterDescription`x`[int](../core/int.html); or [float](../core/float.html); + required + + A number (int or float) + ## all @@ -59,7 +62,7 @@ abs(-2.3) == 2.3 bool all(elements) ``` -Returns true if all elements evaluate to True or if the collection is empty. Elements are converted to boolean using the [bool](#bool) function. + Returns true if all elements evaluate to True or if the collection is empty. Elements are converted to boolean using the [bool](#bool) function. ``` all(["hello", 3, True]) == True @@ -68,9 +71,12 @@ all([-1, 0, 1]) == False ### Parameters -| Parameter | Description | -| --- | --- | -| `elements` | iterable; required A collection of elements. | +ParameterDescription`elements` + iterable; + required + + A collection of elements. + ## any @@ -78,7 +84,7 @@ all([-1, 0, 1]) == False bool any(elements) ``` -Returns true if at least one element evaluates to True. Elements are converted to boolean using the [bool](#bool) function. + Returns true if at least one element evaluates to True. Elements are converted to boolean using the [bool](#bool) function. ``` any([-1, 0, 1]) == True @@ -87,9 +93,12 @@ any([False, 0, ""]) == False ### Parameters -| Parameter | Description | -| --- | --- | -| `elements` | iterable; required A collection of elements. | +ParameterDescription`elements` + iterable; + required + + A collection of elements. + ## bool @@ -97,13 +106,16 @@ any([False, 0, ""]) == False bool bool(x=False) ``` -Constructor for the bool type. It returns `False` if the object is `None`, `False`, an empty string (`""`), the number `0`, or an empty collection (e.g. `()`, `[]`). Otherwise, it returns `True`. + Constructor for the bool type. It returns `False` if the object is `None`, `False`, an empty string ( `""`), the number `0`, or an empty collection (e.g. `()`, `[]`). Otherwise, it returns `True`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | default is `False` The variable to convert. | +ParameterDescription`x` + default is `False` + + The variable to convert. + ## dict @@ -111,14 +123,20 @@ Constructor for the bool type. It returns `False` if the object is `None`, `Fals dict dict(pairs=[], **kwargs) ``` -Creates a [dictionary](../core/dict.mdx) from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument. + Creates a [dictionary](../core/dict.html) from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument. + ### Parameters -| Parameter | Description | -| --- | --- | -| `pairs` | default is `[]` A dict, or an iterable whose elements are each of length 2 (key, value). | -| `kwargs` | required Dictionary of additional entries. | +ParameterDescription`pairs` + default is `[]` + + A dict, or an iterable whose elements are each of length 2 (key, value). + `kwargs` + required + + Dictionary of additional entries. + ## dir @@ -126,13 +144,16 @@ Creates a [dictionary](../core/dict.mdx) from an optional positional argument an list dir(x) ``` -Returns a list of strings: the names of the attributes and methods of the parameter object. + Returns a list of strings: the names of the attributes and methods of the parameter object. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required The object to check. | +ParameterDescription`x` + required + + The object to check. + ## enumerate @@ -140,7 +161,7 @@ Returns a list of strings: the names of the attributes and methods of the parame list enumerate(list, start=0) ``` -Returns a list of pairs (two-element tuples), with the index (int) and the item from the input sequence. + Returns a list of pairs (two-element tuples), with the index (int) and the item from the input sequence. ``` enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)] @@ -148,10 +169,15 @@ enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)] ### Parameters -| Parameter | Description | -| --- | --- | -| `list` | required input sequence. | -| `start` | [int](../core/int.mdx); default is `0` start index. | +ParameterDescription`list` + required + + input sequence. + `start`[int](../core/int.html); + default is `0` + + start index. + ## fail @@ -159,16 +185,28 @@ enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)] None fail(*args, msg=None, attr=None, sep=" ") ``` -Causes execution to fail with an error. + Causes execution to fail with an error. + ### Parameters -| Parameter | Description | -| --- | --- | -| `msg` | default is `None` Deprecated: use positional arguments instead. This argument acts like an implicit leading positional argument. | -| `attr` | [string](../core/string.mdx); or `None`; default is `None` Deprecated. Causes an optional prefix containing this string to be added to the error message. | -| `sep` | [string](../core/string.mdx); default is `" "` The separator string between the objects, default is space (" "). | -| `args` | required A list of values, formatted with debugPrint (which is equivalent to str by default) and joined with sep (defaults to " "), that appear in the error message. | +ParameterDescription`msg` + default is `None` + + Deprecated: use positional arguments instead. This argument acts like an implicit leading positional argument. + `attr`[string](../core/string.html); or `None`; + default is `None` + + Deprecated. Causes an optional prefix containing this string to be added to the error message. + `sep`[string](../core/string.html); + default is `" "` + + The separator string between the objects, default is space (" "). + `args` + required + + A list of values, formatted with debugPrint (which is equivalent to str by default) and joined with sep (defaults to " "), that appear in the error message. + ## float @@ -176,17 +214,23 @@ Causes execution to fail with an error. float float(x=unbound) ``` -Returns x as a float value. + Returns x as a float value. -* If `x` is already a float, `float` returns it unchanged.* If `x` is a bool, `float` returns 1.0 for True and 0.0 for False.* If `x` is an int, `float` returns the nearest finite floating-point value to x, or an error if the magnitude is too large.* If `x` is a string, it must be a valid floating-point literal, or be equal (ignoring case) to `NaN`, `Inf`, or `Infinity`, optionally preceded by a `+` or `-` sign. +- If `x` is already a float, `float` returns it unchanged. +- If `x` is a bool, `float` returns 1.0 for True and 0.0 for False. +- If `x` is an int, `float` returns the nearest finite floating-point value to x, or an error if the magnitude is too large. +- If `x` is a string, it must be a valid floating-point literal, or be equal (ignoring case) to `NaN`, `Inf`, or `Infinity`, optionally preceded by a `+` or `-` sign. Any other value causes an error. With no argument, `float()` returns 0.0. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | [string](../core/string.mdx); or [bool](../core/bool.mdx); or [int](../core/int.mdx); or [float](../core/float.mdx); default is `unbound` The value to convert. | +ParameterDescription`x`[string](../core/string.html); or [bool](../core/bool.html); or [int](../core/int.html); or [float](../core/float.html); + default is `unbound` + + The value to convert. + ## getattr @@ -194,7 +238,7 @@ Any other value causes an error. With no argument, `float()` returns 0.0. unknown getattr(x, name, default=unbound) ``` -Returns the struct's field of the given name if it exists. If not, it either returns `default` (if specified) or raises an error. `getattr(x, "foobar")` is equivalent to `x.foobar`. + Returns the struct's field of the given name if it exists. If not, it either returns `default` (if specified) or raises an error. `getattr(x, "foobar")` is equivalent to `x.foobar`. ``` getattr(ctx.attr, "myattr") @@ -203,11 +247,19 @@ getattr(ctx.attr, "myattr", "mydefault") ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required The struct whose attribute is accessed. | -| `name` | [string](../core/string.mdx); required The name of the struct attribute. | -| `default` | default is `unbound` The default value to return in case the struct doesn't have an attribute of the given name. | +ParameterDescription`x` + required + + The struct whose attribute is accessed. + `name`[string](../core/string.html); + required + + The name of the struct attribute. + `default` + default is `unbound` + + The default value to return in case the struct doesn't have an attribute of the given name. + ## hasattr @@ -215,7 +267,7 @@ getattr(ctx.attr, "myattr", "mydefault") bool hasattr(x, name) ``` -Returns True if the object `x` has an attribute or method of the given `name`, otherwise False. Example: + Returns True if the object `x` has an attribute or method of the given `name`, otherwise False. Example: ``` hasattr(ctx.attr, "myattr") @@ -223,10 +275,15 @@ hasattr(ctx.attr, "myattr") ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required | -| `name` | [string](../core/string.mdx); required The name of the attribute. | +ParameterDescription`x` + required + + The object to check. + `name`[string](../core/string.html); + required + + The name of the attribute. + ## hash @@ -234,19 +291,22 @@ hasattr(ctx.attr, "myattr") int hash(value) ``` -Return a hash value for a string. This is computed deterministically using the same algorithm as Java's `String.hashCode()`, namely: + Return a hash value for a string. This is computed deterministically using the same algorithm as Java's `String.hashCode()`, namely: ``` s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1] ``` -Hashing of values besides strings is not currently supported. + Hashing of values besides strings is not currently supported. + ### Parameters -| Parameter | Description | -| --- | --- | -| `value` | [string](../core/string.mdx); required String value to hash. | +ParameterDescription`value`[string](../core/string.html); + required + + String value to hash. + ## int @@ -254,9 +314,12 @@ Hashing of values besides strings is not currently supported. int int(x, base=unbound) ``` -Returns x as an int value. + Returns x as an int value. -* If `x` is already an int, `int` returns it unchanged.* If `x` is a bool, `int` returns 1 for True and 0 for False.* If `x` is a string, it must have the format `<sign><prefix><digits>`. `<sign>` is either `"+"`, `"-"`, or empty (interpreted as positive). `<digits>` are a sequence of digits from 0 up to `base` - 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where `base` is 2/8/16, `<prefix>` is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the `base` is any other value besides these bases or the special value 0, the prefix must be empty. In the case where `base` is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If `base` is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type.* If `x` is a float, `int` returns the integer value of the float, rounding towards zero. It is an error if x is non-finite (NaN or infinity). +- If `x` is already an int, `int` returns it unchanged. +- If `x` is a bool, `int` returns 1 for True and 0 for False. +- If `x` is a string, it must have the format `<sign><prefix><digits>`. `<sign>` is either `"+"`, `"-"`, or empty (interpreted as positive). `<digits>` are a sequence of digits from 0 up to `base` \- 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where `base` is 2/8/16, `<prefix>` is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the `base` is any other value besides these bases or the special value 0, the prefix must be empty. In the case where `base` is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If `base` is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type. +- If `x` is a float, `int` returns the integer value of the float, rounding towards zero. It is an error if x is non-finite (NaN or infinity). This function fails if `x` is any other type, or if the value is a string not satisfying the above format. Unlike Python's `int` function, this function does not allow zero arguments, and does not allow extraneous whitespace for string arguments. @@ -272,14 +335,20 @@ int("10", 0) == 10 int("-0x10", 0) == -16 int("-0x10", 0) == -16 int("123.456") == 123 + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | [string](../core/string.mdx); or [bool](../core/bool.mdx); or [int](../core/int.mdx); or [float](../core/float.mdx); required The string to convert. | -| `base` | [int](../core/int.mdx); default is `unbound` The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if `x` were an integer literal. This parameter must not be supplied if the value is not a string. | +ParameterDescription`x`[string](../core/string.html); or [bool](../core/bool.html); or [int](../core/int.html); or [float](../core/float.html); + required + + The string to convert. + `base`[int](../core/int.html); + default is `unbound` + + The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if `x` were an integer literal. This parameter must not be supplied if the value is not a string. + ## len @@ -287,13 +356,17 @@ int("123.456") == 123 int len(x) ``` -Returns the length of a string, sequence (such as a list or tuple), dict, set, or other iterable. + Returns the length of a string, sequence (such as a list or tuple), dict, set, or other iterable. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | iterable; or [string](../core/string.mdx); required The value whose length to report. | +ParameterDescription`x` + iterable; or [string](../core/string.html); + required + + The value whose length to report. + ## list @@ -301,19 +374,22 @@ Returns the length of a string, sequence (such as a list or tuple), dict, set, o list list(x=[]) ``` -Returns a new list with the same elements as the given iterable value. + Returns a new list with the same elements as the given iterable value. ``` list([1, 2]) == [1, 2] list((2, 3, 2)) == [2, 3, 2] -list(\{5: "a", 2: "b", 4: "c"\}) == [5, 2, 4] +list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4] ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | iterable; default is `[]` The object to convert. | +ParameterDescription`x` + iterable; + default is `[]` + + The object to convert. + ## max @@ -321,21 +397,28 @@ list(\{5: "a", 2: "b", 4: "c"\}) == [5, 2, 4] unknown max(*args, key=None) ``` -Returns the largest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable.It is an error if elements are not comparable (for example int with string), or if no arguments are given. + Returns the largest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable.It is an error if elements are not comparable (for example int with string), or if no arguments are given. ``` max(2, 5, 4) == 5 max([5, 6, 3]) == 6 max("two", "three", "four", key = len) =="three" # the longest max([1, -1, -2, 2], key = abs) == -2 # the first encountered with maximal key value + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `key` | callable; or `None`; default is `None` An optional function applied to each element before comparison. | -| `args` | required The elements to be checked. | +ParameterDescription`key` + callable; or `None`; + default is `None` + + An optional function applied to each element before comparison. + `args` + required + + The elements to be checked. + ## min @@ -343,21 +426,28 @@ max([1, -1, -2, 2], key = abs) == -2 # the first encountered with maximal key v unknown min(*args, key=None) ``` -Returns the smallest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable. It is an error if elements are not comparable (for example int with string), or if no arguments are given. + Returns the smallest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable. It is an error if elements are not comparable (for example int with string), or if no arguments are given. ``` min(2, 5, 4) == 2 min([5, 6, 3]) == 3 min("six", "three", "four", key = len) == "six" # the shortest min([2, -2, -1, 1], key = abs) == -1 # the first encountered with minimal key value + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `key` | callable; or `None`; default is `None` An optional function applied to each element before comparison. | -| `args` | required The elements to be checked. | +ParameterDescription`key` + callable; or `None`; + default is `None` + + An optional function applied to each element before comparison. + `args` + required + + The elements to be checked. + ## print @@ -365,16 +455,22 @@ min([2, -2, -1, 1], key = abs) == -1 # the first encountered with minimal key v None print(*args, sep=" ") ``` -Prints `args` as debug output. It will be prefixed with the string `"DEBUG"` and the location (file and line number) of this call. The exact way in which the arguments are converted to strings is unspecified and may change at any time. In particular, it may be different from (and more detailed than) the formatting done by [`str()`](#str) and [`repr()`](#repr). + Prints `args` as debug output. It will be prefixed with the string `"DEBUG"` and the location (file and line number) of this call. The exact way in which the arguments are converted to strings is unspecified and may change at any time. In particular, it may be different from (and more detailed than) the formatting done by [`str()`](#str) and [`repr()`](#repr). Using `print` in production code is discouraged due to the spam it creates for users. For deprecations, prefer a hard error using [`fail()`](#fail) whenever possible. + ### Parameters -| Parameter | Description | -| --- | --- | -| `sep` | [string](../core/string.mdx); default is `" "` The separator string between the objects, default is space (" "). | -| `args` | required The objects to print. | +ParameterDescription`sep`[string](../core/string.html); + default is `" "` + + The separator string between the objects, default is space (" "). + `args` + required + + The objects to print. + ## range @@ -382,7 +478,7 @@ Using `print` in production code is discouraged due to the spam it creates for u sequence range(start_or_stop, stop=unbound, step=1) ``` -Creates a list where items go from `start` to `stop`, using a `step` increment. If a single argument is provided, items will range from 0 to that element. + Creates a list where items go from `start` to `stop`, using a `step` increment. If a single argument is provided, items will range from 0 to that element. ``` range(4) == [0, 1, 2, 3] @@ -392,11 +488,19 @@ range(3, 0, -1) == [3, 2, 1] ### Parameters -| Parameter | Description | -| --- | --- | -| `start_or_stop` | [int](../core/int.mdx); required Value of the start element if stop is provided, otherwise value of stop and the actual start is 0 | -| `stop` | [int](../core/int.mdx); default is `unbound` optional index of the first item *not* to be included in the resulting list; generation of the list stops before `stop` is reached. | -| `step` | [int](../core/int.mdx); default is `1` The increment (default is 1). It may be negative. | +ParameterDescription`start_or_stop`[int](../core/int.html); + required + + Value of the start element if stop is provided, otherwise value of stop and the actual start is 0 + `stop`[int](../core/int.html); + default is `unbound` + + optional index of the first item _not_ to be included in the resulting list; generation of the list stops before `stop` is reached. + `step`[int](../core/int.html); + default is `1` + + The increment (default is 1). It may be negative. + ## repr @@ -404,7 +508,7 @@ range(3, 0, -1) == [3, 2, 1] string repr(x) ``` -Converts any object to a string representation. This is useful for debugging. + Converts any object to a string representation. This is useful for debugging. ``` repr("ab") == '"ab"' @@ -412,9 +516,11 @@ repr("ab") == '"ab"' ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required | +ParameterDescription`x` + required + + The object to convert. + ## reversed @@ -422,7 +528,7 @@ repr("ab") == '"ab"' list reversed(sequence) ``` -Returns a new, unfrozen list that contains the elements of the original iterable sequence in reversed order. + Returns a new, unfrozen list that contains the elements of the original iterable sequence in reversed order. ``` reversed([3, 5, 4]) == [4, 5, 3] @@ -430,9 +536,12 @@ reversed([3, 5, 4]) == [4, 5, 3] ### Parameters -| Parameter | Description | -| --- | --- | -| `sequence` | iterable; required The iterable sequence (e.g. list) to be reversed. | +ParameterDescription`sequence` + iterable; + required + + The iterable sequence (e.g. list) to be reversed. + ## set @@ -440,7 +549,7 @@ reversed([3, 5, 4]) == [4, 5, 3] set set(elements=[]) ``` -Creates a new [set](../core/set.mdx) containing the unique elements of a given + Creates a new [set](../core/set.html) containing the unique elements of a given iterable, preserving iteration order. If called with no argument, `set()` returns a new empty set. @@ -450,14 +559,18 @@ For example, ``` set() # an empty set set([3, 1, 1, 2]) # set([3, 1, 2]), a set of three elements -set(\{"k1": "v1", "k2": "v2"\}) # set(["k1", "k2"]), a set of two elements +set({"k1": "v1", "k2": "v2"}) # set(["k1", "k2"]), a set of two elements + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `elements` | iterable; default is `[]` An iterable of hashable values. | +ParameterDescription`elements` + iterable; + default is `[]` + + An iterable of hashable values. + ## sorted @@ -465,22 +578,33 @@ set(\{"k1": "v1", "k2": "v2"\}) # set(["k1", "k2"]), a set of two elements list sorted(iterable, key=None, *, reverse=False) ``` -Returns a new sorted list containing all the elements of the supplied iterable sequence. An error may occur if any pair of elements x, y may not be compared using x < y. The elements are sorted into ascending order, unless the reverse argument is True, in which case the order is descending. -Sorting is stable: elements that compare equal retain their original relative order. + Returns a new sorted list containing all the elements of the supplied iterable sequence. An error may occur if any pair of elements x, y may not be compared using x < y. The elements are sorted into ascending order, unless the reverse argument is True, in which case the order is descending. + Sorting is stable: elements that compare equal retain their original relative order. ``` sorted([3, 5, 4]) == [3, 4, 5] sorted([3, 5, 4], reverse = True) == [5, 4, 3] sorted(["two", "three", "four"], key = len) == ["two", "four", "three"] # sort by length + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `iterable` | iterable; required The iterable sequence to sort. | -| `key` | callable; or `None`; default is `None` An optional function applied to each element before comparison. | -| `reverse` | [bool](../core/bool.mdx); default is `False` Return results in descending order. | +ParameterDescription`iterable` + iterable; + required + + The iterable sequence to sort. + `key` + callable; or `None`; + default is `None` + + An optional function applied to each element before comparison. + `reverse`[bool](../core/bool.html); + default is `False` + + Return results in descending order. + ## str @@ -488,7 +612,7 @@ sorted(["two", "three", "four"], key = len) == ["two", "four", "three"] # sort string str(x) ``` -Converts any object to string. This is useful for debugging. + Converts any object to string. This is useful for debugging. ``` str("ab") == "ab" @@ -497,9 +621,11 @@ str(8) == "8" ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required The object to convert. | +ParameterDescription`x` + required + + The object to convert. + ## tuple @@ -507,19 +633,22 @@ str(8) == "8" tuple tuple(x=()) ``` -Returns a tuple with the same elements as the given iterable value. + Returns a tuple with the same elements as the given iterable value. ``` tuple([1, 2]) == (1, 2) tuple((2, 3, 2)) == (2, 3, 2) -tuple(\{5: "a", 2: "b", 4: "c"\}) == (5, 2, 4) +tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4) ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | iterable; default is `()` The object to convert. | +ParameterDescription`x` + iterable; + default is `()` + + The object to convert. + ## type @@ -527,7 +656,7 @@ tuple(\{5: "a", 2: "b", 4: "c"\}) == (5, 2, 4) string type(x) ``` -Returns the type name of its argument. This is useful for debugging and type-checking. Examples: + Returns the type name of its argument. This is useful for debugging and type-checking. Examples: ``` type(2) == "int" @@ -543,9 +672,11 @@ if type(x) == type([]): # if x is a list ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | required The object to check type of. | +ParameterDescription`x` + required + + The object to check type of. + ## zip @@ -553,7 +684,7 @@ if type(x) == type([]): # if x is a list list zip(*args) ``` -Returns a `list` of `tuple`s, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The list has the size of the shortest input. With a single iterable argument, it returns a list of 1-tuples. With no arguments, it returns an empty list. Examples: + Returns a `list` of `tuple` s, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The list has the size of the shortest input. With a single iterable argument, it returns a list of 1-tuples. With no arguments, it returns an empty list. Examples: ``` zip() # == [] @@ -564,6 +695,7 @@ zip([1, 2], [3, 4, 5]) # == [(1, 3), (2, 4)] ### Parameters -| Parameter | Description | -| --- | --- | -| `args` | required lists to zip. | \ No newline at end of file +ParameterDescription`args` + required + + lists to zip. diff --git a/rules/lib/globals/build.mdx b/rules/lib/globals/build.mdx index 70ef741..bf2f768 100644 --- a/rules/lib/globals/build.mdx +++ b/rules/lib/globals/build.mdx @@ -1,28 +1,29 @@ --- -title: 'build' +title: 'BUILD files' --- -Methods available in BUILD files. See also the Build Encyclopedia for extra [functions](./reference/be/functions) and build rules, which can also be used in BUILD files. + +Methods available in BUILD files. See also the Build Encyclopedia for extra [functions](/reference/be/functions) and build rules, which can also be used in BUILD files. ## Members -* [depset](#depset) -* [existing\_rule](#existing_rule) -* [existing\_rules](#existing_rules) -* [exports\_files](#exports_files) -* [glob](#glob) -* [module\_name](#module_name) -* [module\_version](#module_version) -* [package](#package) -* [package\_default\_visibility](#package_default_visibility) -* [package\_group](#package_group) -* [package\_name](#package_name) -* [package\_relative\_label](#package_relative_label) -* [repo\_name](#repo_name) -* [repository\_name](#repository_name) -* [select](#select) -* [subpackages](#subpackages) +- [depset](#depset) +- [existing\_rule](#existing_rule) +- [existing\_rules](#existing_rules) +- [exports\_files](#exports_files) +- [glob](#glob) +- [module\_name](#module_name) +- [module\_version](#module_version) +- [package](#package) +- [package\_default\_visibility](#package_default_visibility) +- [package\_group](#package_group) +- [package\_name](#package_name) +- [package\_relative\_label](#package_relative_label) +- [repo\_name](#repo_name) +- [repository\_name](#repository_name) +- [select](#select) +- [subpackages](#subpackages) ## depset @@ -30,7 +31,7 @@ Methods available in BUILD files. See also the Build Encyclopedia for extra [fun depset depset(direct=None, order="default", *, transitive=None) ``` -Creates a [depset](../builtins/depset.mdx). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. + Creates a [depset](../builtins/depset.html). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression [`type(x)`](../globals/all#type). @@ -38,15 +39,24 @@ Because a hash-based set is used to eliminate duplicates during iteration, all e In addition, elements must currently be immutable, though this restriction will be relaxed in future. -The order of the created depset should be *compatible* with the order of its `transitive` depsets. `"default"` order is compatible with any other order, all other orders are only compatible with themselves. +The order of the created depset should be _compatible_ with the order of its `transitive` depsets. `"default"` order is compatible with any other order, all other orders are only compatible with themselves. + ### Parameters -| Parameter | Description | -| --- | --- | -| `direct` | [sequence](../core/list.mdx); or `None`; default is `None` A list of *direct* elements of a depset. | -| `order` | [string](../core/string.mdx); default is `"default"` The traversal strategy for the new depset. See [here](../builtins/depset.mdx) for the possible values. | -| `transitive` | [sequence](../core/list.mdx) of [depset](../builtins/depset.mdx)s; or `None`; default is `None` A list of depsets whose elements will become indirect elements of the depset. | +ParameterDescription`direct`[sequence](../core/list.html); or `None`; + default is `None` + + A list of _direct_ elements of a depset. + `order`[string](../core/string.html); + default is `"default"` + + The traversal strategy for the new depset. See [here](../builtins/depset.html) for the possible values. + `transitive`[sequence](../core/list.html) of [depset](../builtins/depset.html) s; or `None`; + default is `None` + + A list of depsets whose elements will become indirect elements of the depset. + ## existing\_rule @@ -54,27 +64,30 @@ The order of the created depset should be *compatible* with the order of its `tr unknown existing_rule(name) ``` -Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or `None` if no rule instance of that name exists. + Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or `None` if no rule instance of that name exists. -Here, an *immutable dict-like object* means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. +Here, an _immutable dict-like object_ means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's `name` and `kind` (for example, `'cc_binary'`). The values of the result represent attribute values as follows: -* Attributes of type str, int, and bool are represented as is. -* Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. -* Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. -* `select` values are returned with their contents transformed as described above. -* Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). +- Attributes of type str, int, and bool are represented as is. +- Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. +- Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. +- `select` values are returned with their contents transformed as described above. +- Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by `ctx.attr.foo`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required The name of the target. | +ParameterDescription`name`[string](../core/string.html); + required + + The name of the target. + ## existing\_rules @@ -82,27 +95,38 @@ If possible, use this function only in [implementation functions of rule finaliz unknown existing_rules() ``` -Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by `existing_rule(name)`. + Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by `existing_rule(name)`. -Here, an *immutable dict-like object* means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. +Here, an _immutable dict-like object_ means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. + + ## exports\_files ``` None exports_files(srcs, visibility=None, licenses=None) ``` -Specifies a list of files belonging to this package that are exported to other packages. + Specifies a list of files belonging to this package that are exported to other packages. + ### Parameters -| Parameter | Description | -| --- | --- | -| `srcs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The list of files to export. | -| `visibility` | [sequence](../core/list.mdx); or `None`; default is `None` A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. | -| `licenses` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Licenses to be specified. | +ParameterDescription`srcs`[sequence](../core/list.html) of [string](../core/string.html) s; + required + + The list of files to export. + `visibility`[sequence](../core/list.html); or `None`; + default is `None` + + A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. + `licenses`[sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Licenses to be specified. + ## glob @@ -110,21 +134,33 @@ Specifies a list of files belonging to this package that are exported to other p sequence glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound) ``` -Glob returns a new, mutable, sorted list of every file in the current package that: + Glob returns a new, mutable, sorted list of every file in the current package that: -* Matches at least one pattern in `include`. -* Does not match any of the patterns in `exclude` (default `[]`). +- Matches at least one pattern in `include`. +- Does not match any of the patterns in `exclude` (default `[]`). If the `exclude_directories` argument is enabled (set to `1`), files of type directory will be omitted from the results (default `1`). + ### Parameters -| Parameter | Description | -| --- | --- | -| `include` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to include. | -| `exclude` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to exclude. | -| `exclude_directories` | [int](../core/int.mdx); default is `1` A flag whether to exclude directories or not. | -| `allow_empty` | default is `unbound` Whether we allow glob patterns to match nothing. If `allow\_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). | +ParameterDescription`include`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + The list of glob patterns to include. + `exclude`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + The list of glob patterns to exclude. + `exclude_directories`[int](../core/int.html); + default is `1` + + A flag whether to exclude directories or not. + `allow_empty` + default is `unbound` + + Whether we allow glob patterns to match nothing. If \`allow\_empty\` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the \`exclude\` patterns are excluded). + ## module\_name @@ -132,8 +168,10 @@ If the `exclude_directories` argument is enabled (set to `1`), files of type dir string module_name() ``` -The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the `module.name` field seen in `module_ctx.modules`. -May return `None`. + The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the `module.name` field seen in `module_ctx.modules`. + May return `None`. + + ## module\_version @@ -141,8 +179,10 @@ May return `None`. string module_version() ``` -The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the `module.version` field seen in `module_ctx.modules`. -May return `None`. + The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the `module.version` field seen in `module_ctx.modules`. + May return `None`. + + ## package @@ -150,13 +190,16 @@ May return `None`. unknown package(**kwargs) ``` -Declares metadata that applies to every rule in the package. It must be called at most once within a package (BUILD file). If called, it should be the first call in the BUILD file, right after the `load()` statements. + Declares metadata that applies to every rule in the package. It must be called at most once within a package (BUILD file). If called, it should be the first call in the BUILD file, right after the `load()` statements. + ### Parameters -| Parameter | Description | -| --- | --- | -| `kwargs` | required See the [`package()`](./reference/be/functions#package) function in the Build Encyclopedia for applicable arguments. | +ParameterDescription`kwargs` + required + + See the [`package()`](/reference/be/functions#package) function in the Build Encyclopedia for applicable arguments. + ## package\_default\_visibility @@ -164,7 +207,9 @@ Declares metadata that applies to every rule in the package. It must be called a List package_default_visibility() ``` -Returns the default visibility of the package being evaluated. This is the value of the `default_visibility` parameter of `package()`, extended to include the package itself. + Returns the default visibility of the package being evaluated. This is the value of the `default_visibility` parameter of `package()`, extended to include the package itself. + + ## package\_group @@ -172,15 +217,24 @@ Returns the default visibility of the package being evaluated. This is the value None package_group(*, name, packages=[], includes=[]) ``` -This function defines a set of packages and assigns a label to the group. The label can be referenced in `visibility` attributes. + This function defines a set of packages and assigns a label to the group. The label can be referenced in `visibility` attributes. + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required The unique name for this rule. | -| `packages` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A complete enumeration of packages in this group. | -| `includes` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Other package groups that are included in this one. | +ParameterDescription`name`[string](../core/string.html); + required + + The unique name for this rule. + `packages`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + A complete enumeration of packages in this group. + `includes`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Other package groups that are included in this one. + ## package\_name @@ -188,7 +242,9 @@ This function defines a set of packages and assigns a label to the group. The la string package_name() ``` -The name of the package being evaluated, without the repository name. For example, in the BUILD file `some/package/BUILD`, its value will be `some/package`. If the BUILD file calls a function defined in a .bzl file, `package_name()` will match the caller BUILD file package. The value will always be an empty string for the root package. + The name of the package being evaluated, without the repository name. For example, in the BUILD file `some/package/BUILD`, its value will be `some/package`. If the BUILD file calls a function defined in a .bzl file, `package_name()` will match the caller BUILD file package. The value will always be an empty string for the root package. + + ## package\_relative\_label @@ -196,19 +252,22 @@ The name of the package being evaluated, without the repository name. For exampl Label package_relative_label(input) ``` -Converts the input string into a [Label](../builtins/Label.mdx) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. + Converts the input string into a [Label](../builtins/Label.html) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. The result of this function is the same `Label` value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file. -*Usage note:* The difference between this function and [Label()](../builtins/Label.html#Label) is that `Label()` uses the context of the package of the `.bzl` file that called it, not the package of the `BUILD` file. Use `Label()` when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use `package_relative_label()` when you need to normalize a label string supplied by the BUILD file to a `Label` object. (There is no way to convert a string to a `Label` in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) +_Usage note:_ The difference between this function and [Label()](../builtins/Label.html#Label) is that `Label()` uses the context of the package of the `.bzl` file that called it, not the package of the `BUILD` file. Use `Label()` when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use `package_relative_label()` when you need to normalize a label string supplied by the BUILD file to a `Label` object. (There is no way to convert a string to a `Label` in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) + ### Parameters -| Parameter | Description | -| --- | --- | -| `input` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); required The input label string or Label object. If a Label object is passed, it's returned as is. | +ParameterDescription`input`[string](../core/string.html); or [Label](../builtins/Label.html); + required + + The input label string or Label object. If a Label object is passed, it's returned as is. + ## repo\_name @@ -216,7 +275,9 @@ The result of this function is the same `Label` value as would be produced by pa string repo_name() ``` -The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. + The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. + + ## repository\_name @@ -224,10 +285,13 @@ The canonical name of the repository containing the package currently being eval string repository_name() ``` -**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` + **Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` + **Deprecated.** Prefer to use [`repo_name`](#repo_name) instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise. -The canonical name of the repository containing the package currently being evaluated, with a single at-sign (`@`) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza `local_repository(name='local', path=...)` it will be set to `@local`. In packages in the main repository, it will be set to `@`. +The canonical name of the repository containing the package currently being evaluated, with a single at-sign ( `@`) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza `local_repository(name='local', path=...)` it will be set to `@local`. In packages in the main repository, it will be set to `@`. + + ## select @@ -235,14 +299,20 @@ The canonical name of the repository containing the package currently being eval unknown select(x, no_match_error='') ``` -`select()` is the helper function that makes a rule attribute [configurable](./reference/be/common-definitions#configurable-attributes). See [build encyclopedia](./reference/be/functions#select) for details. + `select()` is the helper function that makes a rule attribute [configurable](/reference/be/common-definitions#configurable-attributes). See [build encyclopedia](/reference/be/functions#select) for details. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | [dict](../core/dict.mdx); required | -| `no_match_error` | [string](../core/string.mdx); default is `''` Optional custom error to report if no condition matches. | +ParameterDescription`x`[dict](../core/dict.html); + required + + A dict that maps configuration conditions to values. Each key is a [Label](../builtins/Label.html) or a label string that identifies a config\_setting or constraint\_value instance. See the [documentation on macros](https://bazel.build/extending/legacy-macros#label-resolution) for when to use a Label instead of a string. If `--incompatible_resolve_select_keys_eagerly` is enabled, the keys are resolved to `Label` objects relative to the package of the file that contains this call to `select`. + `no_match_error`[string](../core/string.html); + default is `''` + + Optional custom error to report if no condition matches. + ## subpackages @@ -250,12 +320,20 @@ unknown select(x, no_match_error='') sequence subpackages(*, include, exclude=[], allow_empty=False) ``` -Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel\_skylib.subpackages module rather than calling this function directly. + Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel\_skylib.subpackages module rather than calling this function directly. + ### Parameters -| Parameter | Description | -| --- | --- | -| `include` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The list of glob patterns to include in subpackages scan. | -| `exclude` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to exclude from subpackages scan. | -| `allow_empty` | [bool](../core/bool.mdx); default is `False` Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. | \ No newline at end of file +ParameterDescription`include`[sequence](../core/list.html) of [string](../core/string.html) s; + required + + The list of glob patterns to include in subpackages scan. + `exclude`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + The list of glob patterns to exclude from subpackages scan. + `allow_empty`[bool](../core/bool.html); + default is `False` + + Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. diff --git a/rules/lib/globals/bzl.mdx b/rules/lib/globals/bzl.mdx index c98ebee..1878dd1 100644 --- a/rules/lib/globals/bzl.mdx +++ b/rules/lib/globals/bzl.mdx @@ -1,28 +1,29 @@ --- -title: 'bzl' +title: '.bzl files' --- + Global methods available in all .bzl files. ## Members -* [analysis\_test\_transition](#analysis_test_transition) -* [aspect](#aspect) -* [configuration\_field](#configuration_field) -* [depset](#depset) -* [exec\_group](#exec_group) -* [exec\_transition](#exec_transition) -* [macro](#macro) -* [materializer\_rule](#materializer_rule) -* [module\_extension](#module_extension) -* [provider](#provider) -* [repository\_rule](#repository_rule) -* [rule](#rule) -* [select](#select) -* [subrule](#subrule) -* [tag\_class](#tag_class) -* [visibility](#visibility) +- [analysis\_test\_transition](#analysis_test_transition) +- [aspect](#aspect) +- [configuration\_field](#configuration_field) +- [depset](#depset) +- [exec\_group](#exec_group) +- [exec\_transition](#exec_transition) +- [macro](#macro) +- [materializer\_rule](#materializer_rule) +- [module\_extension](#module_extension) +- [provider](#provider) +- [repository\_rule](#repository_rule) +- [rule](#rule) +- [select](#select) +- [subrule](#subrule) +- [tag\_class](#tag_class) +- [visibility](#visibility) ## analysis\_test\_transition @@ -30,45 +31,129 @@ Global methods available in all .bzl files. transition analysis_test_transition(*, settings) ``` -Creates a configuration transition to be applied on an analysis-test rule's dependencies. This transition may only be applied on attributes of rules with `analysis_test = True`. Such rules are restricted in capabilities (for example, the size of their dependency tree is limited), so transitions created using this function are limited in potential scope as compared to transitions created using [`transition()`](../builtins/transition.mdx). +Creates a configuration transition to be applied on an analysis-test rule's dependencies. This transition may only be applied on attributes of rules with `analysis_test = True`. Such rules are restricted in capabilities (for example, the size of their dependency tree is limited), so transitions created using this function are limited in potential scope as compared to transitions created using [`transition()`](../builtins/transition.html). This function is primarily designed to facilitate the [Analysis Test Framework](https://bazel.build/rules/testing) core library. See its documentation (or its implementation) for best practices. + ### Parameters -| Parameter | Description | -| --- | --- | -| `settings` | [dict](../core/dict.mdx); required A dictionary containing information about configuration settings which should be set by this configuration transition. Keys are build setting labels and values are their new post-transition values. All other settings are unchanged. Use this to declare specific configuration settings that an analysis test requires to be set in order to pass. | +ParameterDescription`settings`[dict](../core/dict.html); + required + + A dictionary containing information about configuration settings which should be set by this configuration transition. Keys are build setting labels and values are their new post-transition values. All other settings are unchanged. Use this to declare specific configuration settings that an analysis test requires to be set in order to pass. + ## aspect ``` -Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs=\{\}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], propagation_predicate=None, fragments=[], host_fragments=[], toolchains=[], doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[]) +Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], propagation_predicate=None, fragments=[], host_fragments=[], toolchains=[], doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[]) ``` -Creates a new aspect. The result of this function must be stored in a global value. Please see the [introduction to Aspects](https://bazel.build/extending/aspects) for more details. + Creates a new aspect. The result of this function must be stored in a global value. Please see the [introduction to Aspects](https://bazel.build/extending/aspects) for more details. + ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | [function](../core/function.mdx); required A Starlark function that implements this aspect, with exactly two parameters: [Target](../builtins/Target.mdx) (the target to which the aspect is applied) and [ctx](../builtins/ctx.mdx) (the rule context which the target is created from). Attributes of the target are available via the `ctx.rule` field. This function is evaluated during the analysis phase for each application of an aspect to a target. | -| `attr_aspects` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or [function](../core/function.mdx); default is `[]` Accepts a list of attribute names or [Experimental] a function that returns the list of attribute names. The aspect propagates along dependencies specified in the attributes of a target with these names. Common values here include `deps` and `exports`. The list can also contain a single string `"*"` to propagate along all dependencies of a target. | -| `toolchains_aspects` | [sequence](../core/list.mdx); or [function](../core/function.mdx); default is `[]` Accepts a list of toolchain types or [Experimental] a function that returns the list of toolchain types. The aspect propagates to target toolchains which match these toolchain types. | -| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary declaring all the attributes of the aspect. It maps from an attribute name to an attribute object, like `attr.label` or `attr.string` (see [`attr`](../toplevel/attr.mdx) module). Aspect attributes are available to implementation function as fields of `ctx` parameter. Implicit attributes starting with `_` must have default values, and have type `label` or `label_list`. Explicit attributes must have type `string`, and must use the `values` restriction. Explicit attributes restrict the aspect to only be used with rules that have attributes of the same name, type, and valid values according to the restriction. Declared attributes will convert `None` to the default value. | -| `required_providers` | [sequence](../core/list.mdx); default is `[]` This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its required providers. The value must be a list containing either individual providers or lists of providers but not both. For example, `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]` is a valid value while `[FooInfo, BarInfo, [BazInfo, QuxInfo]]` is not valid. An unnested list of providers will automatically be converted to a list containing one list of providers. That is, `[FooInfo, BarInfo]` will automatically be converted to `[[FooInfo, BarInfo]]`. To make some rule (e.g. `some_rule`) targets visible to an aspect, `some_rule` must advertise all providers from at least one of the required providers lists. For example, if the `required_providers` of an aspect are `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]`, this aspect can see `some_rule` targets if and only if `some_rule` provides `FooInfo`, *or* `BarInfo`, *or* both `BazInfo` *and* `QuxInfo`. | -| `required_aspect_providers` | [sequence](../core/list.mdx); default is `[]` This attribute allows this aspect to inspect other aspects. The value must be a list containing either individual providers or lists of providers but not both. For example, `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]` is a valid value while `[FooInfo, BarInfo, [BazInfo, QuxInfo]]` is not valid. An unnested list of providers will automatically be converted to a list containing one list of providers. That is, `[FooInfo, BarInfo]` will automatically be converted to `[[FooInfo, BarInfo]]`. To make another aspect (e.g. `other_aspect`) visible to this aspect, `other_aspect` must provide all providers from at least one of the lists. In the example of `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]`, this aspect can see `other_aspect` if and only if `other_aspect` provides `FooInfo`, *or* `BarInfo`, *or* both `BazInfo` *and* `QuxInfo`. | -| `provides` | [sequence](../core/list.mdx); default is `[]` A list of providers that the implementation function must return. It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here. Each element of the list is an `*Info` object returned by [`provider()`](../globals/bzl.html#provider). When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The [`required_providers`](../globals/bzl.html#aspect.required_providers) field of an [aspect](../globals/bzl.html#aspect) does, however, require that providers are specified here. | -| `requires` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` List of aspects required to be propagated before this aspect. | -| `propagation_predicate` | [function](../core/function.mdx); or `None`; default is `None` Experimental: a function that returns a boolean value indicating whether the aspect should be propagated to a target. | -| `fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the aspect requires in target configuration. | -| `host_fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the aspect requires in host configuration. | -| `toolchains` | [sequence](../core/list.mdx); default is `[]` If set, the set of toolchains this aspect requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the aspect implementation via `ctx.toolchain`. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the aspect that can be extracted by documentation generating tools. | -| `apply_to_generating_rules` | [bool](../core/bool.mdx); default is `False` If true, the aspect will, when applied to an output file, instead apply to the output file's generating rule. For example, suppose an aspect propagates transitively through attribute `deps` and it is applied to target `alpha`. Suppose `alpha` has `deps = [':beta\_output']`, where `beta\_output` is a declared output of a target `beta`. Suppose `beta` has a target `charlie` as one of its `deps`. If `apply\_to\_generating\_rules=True` for the aspect, then the aspect will propagate through `alpha`, `beta`, and `charlie`. If False, then the aspect will propagate only to `alpha`. False by default. | -| `exec_compatible_with` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A list of constraints on the execution platform that apply to all instances of this aspect. | -| `exec_groups` | [dict](../core/dict.mdx); or `None`; default is `None` Dict of execution group name (string) to [`exec_group`s](../globals/bzl.html#exec_group). If set, allows aspects to run actions on multiple execution platforms within a single instance. See [execution groups documentation](./reference/exec-groups) for more info. | -| `subrules` | [sequence](../core/list.mdx) of [Subrule](../builtins/Subrule.mdx)s; default is `[]` Experimental: list of subrules used by this aspect. | +ParameterDescription`implementation`[function](../core/function.html); + required + + A Starlark function that implements this aspect, with exactly two parameters: [Target](../builtins/Target.html) (the target to which the aspect is applied) and [ctx](../builtins/ctx.html) (the rule context which the target is created from). Attributes of the target are available via the `ctx.rule` field. This function is evaluated during the analysis phase for each application of an aspect to a target. + `attr_aspects`[sequence](../core/list.html) of [string](../core/string.html) s; or [function](../core/function.html); + default is `[]` + + Accepts a list of attribute names or \[Experimental\] a function that returns the list of attribute names. The aspect propagates along dependencies specified in the attributes of a target with these names. Common values here include `deps` and `exports`. The list can also contain a single string `"*"` to propagate along all dependencies of a target. + `toolchains_aspects`[sequence](../core/list.html); or [function](../core/function.html); + default is `[]` + + Accepts a list of toolchain types or \[Experimental\] a function that returns the list of toolchain types. The aspect propagates to target toolchains which match these toolchain types. + `attrs`[dict](../core/dict.html); + default is `{}` + + A dictionary declaring all the attributes of the aspect. It maps from an attribute name to an attribute object, like `attr.label` or `attr.string` (see [`attr`](../toplevel/attr.html) module). Aspect attributes are available to implementation function as fields of `ctx` parameter. + +Implicit attributes starting with `_` must have default values, and have type `label` or `label_list`. + +Explicit attributes must have type `string`, and must use the `values` restriction. Explicit attributes restrict the aspect to only be used with rules that have attributes of the same name, type, and valid values according to the restriction. + +Declared attributes will convert `None` to the default value. + +`required_providers`[sequence](../core/list.html); + default is `[]` + + This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its required providers. The value must be a list containing either individual providers or lists of providers but not both. For example, `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]` is a valid value while `[FooInfo, BarInfo, [BazInfo, QuxInfo]]` is not valid. + +An unnested list of providers will automatically be converted to a list containing one list of providers. That is, `[FooInfo, BarInfo]` will automatically be converted to `[[FooInfo, BarInfo]]`. + +To make some rule (e.g. `some_rule`) targets visible to an aspect, `some_rule` must advertise all providers from at least one of the required providers lists. For example, if the `required_providers` of an aspect are `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]`, this aspect can see `some_rule` targets if and only if `some_rule` provides `FooInfo`, _or_ `BarInfo`, _or_ both `BazInfo` _and_ `QuxInfo`. + + +`required_aspect_providers`[sequence](../core/list.html); + default is `[]` + + This attribute allows this aspect to inspect other aspects. The value must be a list containing either individual providers or lists of providers but not both. For example, `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]` is a valid value while `[FooInfo, BarInfo, [BazInfo, QuxInfo]]` is not valid. + +An unnested list of providers will automatically be converted to a list containing one list of providers. That is, `[FooInfo, BarInfo]` will automatically be converted to `[[FooInfo, BarInfo]]`. + +To make another aspect (e.g. `other_aspect`) visible to this aspect, `other_aspect` must provide all providers from at least one of the lists. In the example of `[[FooInfo], [BarInfo], [BazInfo, QuxInfo]]`, this aspect can see `other_aspect` if and only if `other_aspect` provides `FooInfo`, _or_ `BarInfo`, _or_ both `BazInfo` _and_ `QuxInfo`. + + +`provides`[sequence](../core/list.html); + default is `[]` + + A list of providers that the implementation function must return. + +It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here. + +Each element of the list is an `*Info` object returned by [`provider()`](../globals/bzl.html#provider). When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The [`required_providers`](../globals/bzl.html#aspect.required_providers) field of an [aspect](../globals/bzl.html#aspect) does, however, require that providers are specified here. + + +`requires`[sequence](../core/list.html) of [Aspect](../builtins/Aspect.html) s; + default is `[]` + + List of aspects required to be propagated before this aspect. + `propagation_predicate`[function](../core/function.html); or `None`; + default is `None` + + Experimental: a function that returns a boolean value indicating whether the aspect should be propagated to a target. + `fragments`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + List of names of configuration fragments that the aspect requires in target configuration. + `host_fragments`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + List of names of configuration fragments that the aspect requires in host configuration. + `toolchains`[sequence](../core/list.html); + default is `[]` + + If set, the set of toolchains this aspect requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the aspect implementation via `ctx.toolchain`. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the aspect that can be extracted by documentation generating tools. + `apply_to_generating_rules`[bool](../core/bool.html); + default is `False` + + If true, the aspect will, when applied to an output file, instead apply to the output file's generating rule. + +For example, suppose an aspect propagates transitively through attribute \`deps\` and it is applied to target \`alpha\`. Suppose \`alpha\` has \`deps = \[':beta\_output'\]\`, where \`beta\_output\` is a declared output of a target \`beta\`. Suppose \`beta\` has a target \`charlie\` as one of its \`deps\`. If \`apply\_to\_generating\_rules=True\` for the aspect, then the aspect will propagate through \`alpha\`, \`beta\`, and \`charlie\`. If False, then the aspect will propagate only to \`alpha\`. + +False by default. + +`exec_compatible_with`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + A list of constraints on the execution platform that apply to all instances of this aspect. + `exec_groups`[dict](../core/dict.html); or `None`; + default is `None` + + Dict of execution group name (string) to [`exec_group` s](../globals/bzl.html#exec_group). If set, allows aspects to run actions on multiple execution platforms within a single instance. See [execution groups documentation](/reference/exec-groups) for more info. + `subrules`[sequence](../core/list.html) of [Subrule](../builtins/Subrule.html) s; + default is `[]` + + Experimental: list of subrules used by this aspect. + ## configuration\_field @@ -76,17 +161,17 @@ Creates a new aspect. The result of this function must be stored in a global val LateBoundDefault configuration_field(fragment, name) ``` -References a late-bound default value for an attribute of type [label](../toplevel/attr.html#label). A value is 'late-bound' if it requires the configuration to be built before determining the value. Any attribute using this as a value must [be private](https://bazel.build/extending/rules#private-attributes). + References a late-bound default value for an attribute of type [label](../toplevel/attr.html#label). A value is 'late-bound' if it requires the configuration to be built before determining the value. Any attribute using this as a value must [be private](https://bazel.build/extending/rules#private-attributes). Example usage: -Defining a rule attribute: +Defining a rule attribute: ``` '_foo': attr.label(default=configuration_field(fragment='java', name='toolchain')) ``` -Accessing in rule implementation: +Accessing in rule implementation: ``` def _rule_impl(ctx): @@ -96,10 +181,15 @@ Accessing in rule implementation: ### Parameters -| Parameter | Description | -| --- | --- | -| `fragment` | [string](../core/string.mdx); required | -| `name` | [string](../core/string.mdx); required | +ParameterDescription`fragment`[string](../core/string.html); + required + + The name of a configuration fragment which contains the late-bound value. + `name`[string](../core/string.html); + required + + The name of the value to obtain from the configuration fragment. + ## depset @@ -107,7 +197,7 @@ Accessing in rule implementation: depset depset(direct=None, order="default", *, transitive=None) ``` -Creates a [depset](../builtins/depset.mdx). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. + Creates a [depset](../builtins/depset.html). The `direct` parameter is a list of direct elements of the depset, and `transitive` parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the `order` parameter. See the [Depsets overview](https://bazel.build/extending/depsets) for more information. All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression [`type(x)`](../globals/all#type). @@ -115,15 +205,24 @@ Because a hash-based set is used to eliminate duplicates during iteration, all e In addition, elements must currently be immutable, though this restriction will be relaxed in future. -The order of the created depset should be *compatible* with the order of its `transitive` depsets. `"default"` order is compatible with any other order, all other orders are only compatible with themselves. +The order of the created depset should be _compatible_ with the order of its `transitive` depsets. `"default"` order is compatible with any other order, all other orders are only compatible with themselves. + ### Parameters -| Parameter | Description | -| --- | --- | -| `direct` | [sequence](../core/list.mdx); or `None`; default is `None` A list of *direct* elements of a depset. | -| `order` | [string](../core/string.mdx); default is `"default"` The traversal strategy for the new depset. See [here](../builtins/depset.mdx) for the possible values. | -| `transitive` | [sequence](../core/list.mdx) of [depset](../builtins/depset.mdx)s; or `None`; default is `None` A list of depsets whose elements will become indirect elements of the depset. | +ParameterDescription`direct`[sequence](../core/list.html); or `None`; + default is `None` + + A list of _direct_ elements of a depset. + `order`[string](../core/string.html); + default is `"default"` + + The traversal strategy for the new depset. See [here](../builtins/depset.html) for the possible values. + `transitive`[sequence](../core/list.html) of [depset](../builtins/depset.html) s; or `None`; + default is `None` + + A list of depsets whose elements will become indirect elements of the depset. + ## exec\_group @@ -131,14 +230,20 @@ The order of the created depset should be *compatible* with the order of its `tr exec_group exec_group(*, toolchains=[], exec_compatible_with=[]) ``` -Creates an [execution group](./reference/exec-groups) which can be used to create actions for a specific execution platform during rule implementation. + Creates an [execution group](/reference/exec-groups) which can be used to create actions for a specific execution platform during rule implementation. + ### Parameters -| Parameter | Description | -| --- | --- | -| `toolchains` | [sequence](../core/list.mdx); default is `[]` The set of toolchains this execution group requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. | -| `exec_compatible_with` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A list of constraints on the execution platform. | +ParameterDescription`toolchains`[sequence](../core/list.html); + default is `[]` + + The set of toolchains this execution group requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. + `exec_compatible_with`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + A list of constraints on the execution platform. + ## exec\_transition @@ -146,77 +251,284 @@ Creates an [execution group](./reference/exec-groups) which can be used to creat transition exec_transition(*, implementation, inputs, outputs) ``` -A specialized version of [`transition()`](../builtins/transition.mdx) used to define the exec transition. See its documentation (or its implementation) for best practices. Only usable from the Bazel builtins. + A specialized version of [`transition()`](../builtins/transition.html) used to define the exec transition. See its documentation (or its implementation) for best practices. Only usable from the Bazel builtins. + ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | callable; required | -| `inputs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required | -| `outputs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required | +ParameterDescription`implementation` + callable; + required + +`inputs`[sequence](../core/list.html) of [string](../core/string.html) s; + required + +`outputs`[sequence](../core/list.html) of [string](../core/string.html) s; + required ## macro ``` -macro macro(*, implementation, attrs=\{\}, inherit_attrs=None, finalizer=False, doc=None) +macro macro(*, implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None) ``` -Defines a symbolic macro, which may be called in `BUILD` files or macros (legacy or + Defines a symbolic macro, which may be called in `BUILD` files or macros (legacy or symbolic) to define targets – possibly multiple ones. The value returned by `macro(...)` must be assigned to a global variable in a .bzl file; the name of the global variable will be the macro symbol's name. -See [Macros](./extending/macros) for a comprehensive guide on how to use symbolic +See [Macros](/extending/macros) for a comprehensive guide on how to use symbolic macros. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | [function](../core/function.mdx); required The Starlark function implementing this macro. The values of the macro's attributes are passed to the implementation function as keyword arguments. The implementation function must have at least two named parameters, `name` and `visibility`, and if the macro inherits attributes (see `inherit_attrs` below), it must have a `**kwargs` residual keyword parameter. By convention, the implementation function should have a named parameter for any attribute that the macro needs to examine, modify, or pass to non-"main" targets, while the "bulk" inherited attributes which will be passed to the "main" target unchanged are passed as `**kwargs`. The implementation function must not return a value. Instead, the implementation function *declares targets* by calling rule or macro symbols. The name of any target or inner symbolic macro declared by a symbolic macro (including by any Starlark function that the macro's implementation function transitively calls) must either equal `name` (this is referred to as the "main" target) or start with `name`, followed by a separator chracter (`"_"`, `"-"`, or `"."`) and a string suffix. (Targets violating this naming scheme are allowed to be declared, but cannot be built, configured, or depended upon.) By default, targets declared by a symbolic macro (including by any Starlark function that the macro's implementation function transitively calls) are visible only in the package containing the .bzl file defining the macro. To declare targets visible externally, *including to the caller of the symbolic macro*, the implementation function must set `visibility` appropriately – typically, by passing `visibility = visibility` to the rule or macro symbol being called. The following APIs are unavailable within a macro implementation function and any Starlark function it transitively calls: * [`package()`, `licenses()`* `environment_group()`* [`native.glob()`](../toplevel/native#glob) – instead, you may pass a glob into the macro via a label list attribute* [`native.subpackages()`](../toplevel/native#subpackages)* (allowed in rule finalizers only, see `finalizer` below) [`native.existing_rules()`](../toplevel/native#existing_rules), [`native.existing_rule()`](../toplevel/native#existing_rule)* (for `WORKSPACE` threads) [`workspace()`](../globals/workspace#workspace), [`register_toolchains()`](../globals/workspace#register_toolchains), [`bind()`](../globals/workspace#register_execution_platforms](/reference/be/functions#package) | -| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary of the attributes this macro supports, analogous to [rule.attrs](#rule.attrs). Keys are attribute names, and values are either attribute objects like `attr.label_list(...)` (see the [attr](../toplevel/attr.mdx) module), or `None`. A `None` entry means that the macro does not have an attribute by that name, even if it would have otherwise inherited one via `inherit_attrs` (see below). The special `name` attribute is predeclared and must not be included in the dictionary. The `visibility` attribute name is reserved and must not be included in the dictionary. Attributes whose names start with `_` are private -- they cannot be passed at the call site of the rule. Such attributes can be assigned a default value (as in `attr.label(default="//pkg:foo")`) to create an implicit dependency on a label. To limit memory usage, there is a cap on the number of attributes that may be declared. | -| `inherit_attrs` | [rule](../builtins/rule.mdx); or [macro](../builtins/macro.mdx); or [string](../core/string.mdx); or `None`; default is `None` A rule symbol, macro symbol, or the name of a built-in common attribute list (see below) from which the macro should inherit attributes. If `inherit_attrs` is set to the string `"common"`, the macro will inherit [common rule attribute definitions](./reference/be/common-definitions#common-attributes) used by all Starlark rules. Note that if the return value of `rule()` or `macro()` was not assigned to a global variable in a .bzl file, then such a value has not been registered as a rule or macro symbol, and therefore cannot be used for `inherit_attrs`. The inheritance mechanism works as follows: 1. The special `name` and `visibility` attributes are never inherited;- Hidden attributes (ones whose name starts with `"_"`) are never inherited;- Attributes whose names are already defined in the `attrs` dictionary are never inherited (the entry in `attrs` takes precedence; note that an entry may be set to `None` to ensure that no attribute by that name gets defined on the macro);- All other attributes are inherited from the rule or macro and effectively merged into the `attrs` dict. When a non-mandatory attribute is inherited, the default value of the attribute is overridden to be `None`, regardless of what it was specified in the original rule or macro. This ensures that when the macro forwards the attribute's value to an instance of the wrapped rule or macro – such as by passing in the unmodified `**kwargs` – a value that was absent from the outer macro's call will also be absent in the inner rule or macro's call (since passing `None` to an attribute is treated the same as omitting the attribute). This is important because omitting an attribute has subtly different semantics from passing its apparent default value. In particular, omitted attributes are not shown in some `bazel query` output formats, and computed defaults only execute when the value is omitted. If the macro needs to examine or modify an inherited attribute – for example, to add a value to an inherited `tags` attribute – you must make sure to handle the `None` case in the macro's implementation function. For example, the following macro inherits all attributes from `native.cc_library`, except for `cxxopts` (which is removed from the attribute list) and `copts` (which is given a new definition). It also takes care to checks for the default `None` value of the inherited `tags` attribute before appending an additional tag. ``` def _my_cc_library_impl(name, visibility, tags, **kwargs): # Append a tag; tags attr was inherited from native.cc_library, and # therefore is None unless explicitly set by the caller of my_cc_library() my_tags = (tags or []) + ["my_custom_tag"] native.cc_library( name = name, visibility = visibility, tags = my_tags, **kwargs ) my_cc_library = macro( implementation = _my_cc_library_impl, inherit_attrs = native.cc_library, attrs = \{ "cxxopts": None, "copts": attr.string_list(default = ["-D_FOO"]), \}, ) ``` If `inherit_attrs` is set, the macro's implementation function *must* have a `**kwargs` residual keyword parameter. By convention, a macro should pass inherited, non-overridden attributes unchanged to the "main" rule or macro symbol which the macro is wrapping. Typically, most inherited attributes will not have a parameter in the implementation function's parameter list, and will simply be passed via `**kwargs`. It can be convenient for the implementation function to have explicit parameters for some inherited attributes (most commonly, `tags` and `testonly`) if the macro needs to pass those attributes to both "main" and non-"main" targets – but if the macro also needs to examine or manipulate those attributes, you must take care to handle the `None` default value of non-mandatory inherited attributes. | -| `finalizer` | [bool](../core/bool.mdx); default is `False` Whether this macro is a rule finalizer, which is a macro that, regardless of its position in a `BUILD` file, is evaluated at the end of package loading, after all non-finalizer targets have been defined. Unlike ordinary symbolic macros, rule finalizers may call [`native.existing_rule()`](../toplevel/native#existing_rule) and [`native.existing_rules()`](../toplevel/native#existing_rules) to query the set of *non-finalizer* rule targets defined in the current package. Note that `native.existing_rule()` and `native.existing_rules()` cannot access the targets defined by any rule finalizer, including this one. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the macro that can be extracted by documentation generating tools. | +ParameterDescription`implementation`[function](../core/function.html); + required + + The Starlark function implementing this macro. The values of the macro's attributes are passed to +the implementation function as keyword arguments. The implementation function must have at least two +named parameters, `name` and `visibility`, and if the macro inherits +attributes (see `inherit_attrs` below), it must have a `**kwargs` residual +keyword parameter. + +By convention, the implementation function should have a named parameter for any attribute that +the macro needs to examine, modify, or pass to non-"main" targets, while the "bulk" inherited +attributes which will be passed to the "main" target unchanged are passed as `**kwargs`. + +The implementation function must not return a value. Instead, the implementation function +_declares targets_ by calling rule or macro symbols. + +The name of any target or inner symbolic macro declared by a symbolic macro (including by any +Starlark function that the macro's implementation function transitively calls) must either equal +`name` (this is referred to as the "main" target) or start with `name`, +followed by a separator chracter ( `"_"`, `"-"`, or `"."`) and a +string suffix. (Targets violating this naming scheme are allowed to be declared, but cannot be +built, configured, or depended upon.) + +By default, targets declared by a symbolic macro (including by any Starlark function that the +macro's implementation function transitively calls) are visible only in the package containing the +.bzl file defining the macro. To declare targets visible externally, _including to the caller of_ +_the symbolic macro_, the implementation function must set `visibility` appropriately +– typically, by passing `visibility = visibility` to the rule or macro symbol being +called. + +The following APIs are unavailable within a macro implementation function and any Starlark +function it transitively calls: + +- [`package()`, `licenses()`](/reference/be/functions#package) +- [`environment_group()`](/reference/be/functions#package) +- [`native.glob()`](../toplevel/native#glob) – instead, you may pass + a glob into the macro via a label list attribute + +- [`native.subpackages()`](../toplevel/native#subpackages) +- (allowed in rule finalizers only, see `finalizer` below) + [`native.existing_rules()`](../toplevel/native#existing_rules), + [`native.existing_rule()`](../toplevel/native#existing_rule) +- (for `WORKSPACE` threads) + [`workspace()`](../globals/workspace#workspace), + [`register_toolchains()`](../globals/workspace#register_toolchains), + [`bind()`](../globals/workspace#register_execution_platforms><code>register_execution_platforms()</code></a>, + <a href=), repository rule instantiation + + +`attrs`[dict](../core/dict.html); + default is `{}` + + A dictionary of the attributes this macro supports, analogous to +[rule.attrs](#rule.attrs). Keys are attribute names, and values are either attribute +objects like `attr.label_list(...)` (see the [attr](../toplevel/attr.html) +module), or `None`. A `None` entry means that the macro does not have an +attribute by that name, even if it would have otherwise inherited one via `inherit_attrs` +(see below). + +The special `name` attribute is predeclared and must not be included in the +dictionary. The `visibility` attribute name is reserved and must not be included in the +dictionary. + +Attributes whose names start with `_` are private -- they cannot be passed at the call +site of the rule. Such attributes can be assigned a default value (as in +`attr.label(default="//pkg:foo")`) to create an implicit dependency on a label. + +To limit memory usage, there is a cap on the number of attributes that may be declared. + + + +`inherit_attrs`[rule](../builtins/rule.html); or [macro](../builtins/macro.html); or [string](../core/string.html); or `None`; + default is `None` + + A rule symbol, macro symbol, or the name of a built-in common attribute list (see below) from which +the macro should inherit attributes. + +If `inherit_attrs` is set to the string `"common"`, the macro will inherit +[common rule attribute definitions](/reference/be/common-definitions#common-attributes) +used by all Starlark rules. + +Note that if the return value of `rule()` or `macro()` was not assigned to +a global variable in a .bzl file, then such a value has not been registered as a rule or macro +symbol, and therefore cannot be used for `inherit_attrs`. + +The inheritance mechanism works as follows: + +1. The special `name` and `visibility` attributes are never inherited; + +2. Hidden attributes (ones whose name starts with `"_"`) are never inherited; + +3. Attributes whose names are already defined in the `attrs` dictionary are never + inherited (the entry in `attrs` takes precedence; note that an entry may be set to + `None` to ensure that no attribute by that name gets defined on the macro); + +4. All other attributes are inherited from the rule or macro and effectively merged into the + `attrs` dict. + + +When a non-mandatory attribute is inherited, the default value of the attribute is overridden +to be `None`, regardless of what it was specified in the original rule or macro. This +ensures that when the macro forwards the attribute's value to an instance of the wrapped rule or +macro – such as by passing in the unmodified `**kwargs` – a value that was +absent from the outer macro's call will also be absent in the inner rule or macro's call (since +passing `None` to an attribute is treated the same as omitting the attribute). +This is important because omitting an attribute has subtly different semantics from passing +its apparent default value. In particular, omitted attributes are not shown in some `bazel +query` output formats, and computed defaults only execute when the value is omitted. If the +macro needs to examine or modify an inherited attribute – for example, to add a value to an +inherited `tags` attribute – you must make sure to handle the `None` +case in the macro's implementation function. + +For example, the following macro inherits all attributes from `native.cc_library`, +except for `cxxopts` (which is removed from the attribute list) and `copts` +(which is given a new definition). It also takes care to checks for the default `None` +value of the inherited `tags` attribute before appending an additional tag. + +``` +def _my_cc_library_impl(name, visibility, tags, **kwargs): + # Append a tag; tags attr was inherited from native.cc_library, and + # therefore is None unless explicitly set by the caller of my_cc_library() + my_tags = (tags or []) + ["my_custom_tag"] + native.cc_library( + name = name, + visibility = visibility, + tags = my_tags, + **kwargs + ) + +my_cc_library = macro( + implementation = _my_cc_library_impl, + inherit_attrs = native.cc_library, + attrs = { + "cxxopts": None, + "copts": attr.string_list(default = ["-D_FOO"]), + }, +) + +``` + +If `inherit_attrs` is set, the macro's implementation function _must_ have a +`**kwargs` residual keyword parameter. + +By convention, a macro should pass inherited, non-overridden attributes unchanged to the "main" +rule or macro symbol which the macro is wrapping. Typically, most inherited attributes will not have +a parameter in the implementation function's parameter list, and will simply be passed via +`**kwargs`. It can be convenient for the implementation function to have explicit +parameters for some inherited attributes (most commonly, `tags` and +`testonly`) if the macro needs to pass those attributes to both "main" and non-"main" +targets – but if the macro also needs to examine or manipulate those attributes, you must take +care to handle the `None` default value of non-mandatory inherited attributes. + + + +`finalizer`[bool](../core/bool.html); + default is `False` + + Whether this macro is a rule finalizer, which is a macro that, regardless of its position in a +`BUILD` file, is evaluated at the end of package loading, after all non-finalizer targets +have been defined. + +Unlike ordinary symbolic macros, rule finalizers may call +[`native.existing_rule()`](../toplevel/native#existing_rule) and +[`native.existing_rules()`](../toplevel/native#existing_rules) to query the +set of _non-finalizer_ rule targets defined in the current package. Note that +`native.existing_rule()` and `native.existing_rules()` cannot access the +targets defined by any rule finalizer, including this one. + + + +`doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the macro that can be extracted by documentation generating tools. + ## materializer\_rule ``` -callable materializer_rule(*, implementation, attrs=\{\}, doc=None) +callable materializer_rule(*, implementation, attrs={}, doc=None) ``` -Creates a new materializer rule, which can be called from a BUILD file or a macro to create materializer targets. + Creates a new materializer rule, which can be called from a BUILD file or a macro to create materializer targets. Materializer targets are used to dynamically select dependencies at analysis time. Targets which depend on a materializer target will see the materialized dependencies, rather than the materializer target itself. + ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | [function](../core/function.mdx); required The Starlark function implementing this materializer rule. It must have exactly one parameter: [ctx](../builtins/ctx.mdx). This function is called during the analysis phase for each instance of the rule. Materializer rules return exactly one and only one MaterializedDepsInfo provider which specifies the dependencies to materialize in place of any instance of this rule in the attributes of another target. | -| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see [`attr`](../toplevel/attr.mdx) module). Attributes starting with `_` are private, and can be used to add an implicit dependency on a label. The attribute `name` is implicitly added and must not be specified. Attributes `visibility`, `deprecation`, `tags`, `testonly`, and `features` are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. Declared attributes will convert `None` to the default value. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the rule that can be extracted by documentation generating tools. | +ParameterDescription`implementation`[function](../core/function.html); + required + + The Starlark function implementing this materializer rule. It must have exactly one parameter: [ctx](../builtins/ctx.html). This function is called during the analysis phase for each instance of the rule. Materializer rules return exactly one and only one MaterializedDepsInfo provider which specifies the dependencies to materialize in place of any instance of this rule in the attributes of another target. + `attrs`[dict](../core/dict.html); + default is `{}` + + A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see +[`attr`](../toplevel/attr.html) module). Attributes starting with `_` are private, and can be used to add an implicit dependency on a label. The attribute `name` is implicitly added and must not be specified. Attributes `visibility`, `deprecation`, `tags`, `testonly`, and `features` are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. + +Declared attributes will convert `None` to the default value. + +`doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the rule that can be extracted by documentation generating tools. + ## module\_extension ``` -unknown module_extension(implementation, *, tag_classes=\{\}, doc=None, environ=[], os_dependent=False, arch_dependent=False) +unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False) ``` -Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with `use_extension`. + Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with `use_extension`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | callable; required The function that implements this module extension. Must take a single parameter, `module_ctx`. The function is called once at the beginning of a build to determine the set of available repos. | -| `tag_classes` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the tag classes used by the extension. It maps from the name of the tag class to a `tag_class` object. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the module extension that can be extracted by documentation generating tools. | -| `environ` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated. | -| `os_dependent` | [bool](../core/bool.mdx); default is `False` Indicates whether this extension is OS-dependent or not | -| `arch_dependent` | [bool](../core/bool.mdx); default is `False` Indicates whether this extension is architecture-dependent or not | +ParameterDescription`implementation` + callable; + required + + The function that implements this module extension. Must take a single parameter, `module_ctx`. The function is called once at the beginning of a build to determine the set of available repos. + `tag_classes`[dict](../core/dict.html); + default is `{}` + + A dictionary to declare all the tag classes used by the extension. It maps from the name of the tag class to a `tag_class` object. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the module extension that can be extracted by documentation generating tools. + `environ`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated. + `os_dependent`[bool](../core/bool.html); + default is `False` + + Indicates whether this extension is OS-dependent or not + `arch_dependent`[bool](../core/bool.html); + default is `False` + + Indicates whether this extension is architecture-dependent or not + ## provider @@ -224,7 +536,7 @@ Creates a new module extension. Store it in a global value, so that it can be ex unknown provider(doc=None, *, fields=None, init=None) ``` -Defines a provider symbol. The resulting value of this function must be stored in a global value to be usable in a rule or aspect implementation. Providers can be instantiated by calling the resulting value as a function, or used directly as an index key for retrieving an instance of that provider from a target. Example: + Defines a provider symbol. The resulting value of this function must be stored in a global value to be usable in a rule or aspect implementation. Providers can be instantiated by calling the resulting value as a function, or used directly as an index key for retrieving an instance of that provider from a target. Example: ``` MyInfo = provider() @@ -239,17 +551,81 @@ def _my_library_impl(ctx): See [Rules (Providers)](https://bazel.build/extending/rules#providers) for a comprehensive guide on how to use providers. -Returns a [`Provider`](../builtins/Provider.mdx) callable value if `init` is not specified. +Returns a [`Provider`](../builtins/Provider.html) callable value if `init` is not specified. + +If `init` is specified, returns a tuple of 2 elements: a [`Provider`](../builtins/Provider.html) callable value and a _raw constructor_ callable value. See [Rules (Custom initialization of custom providers)](https://bazel.build/extending/rules#custom_initialization_of_providers) and the discussion of the `init` parameter below for details. -If `init` is specified, returns a tuple of 2 elements: a [`Provider`](../builtins/Provider.mdx) callable value and a *raw constructor* callable value. See [Rules (Custom initialization of custom providers)](https://bazel.build/extending/rules#custom_initialization_of_providers) and the discussion of the `init` parameter below for details. ### Parameters -| Parameter | Description | -| --- | --- | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` | -| `fields` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or [dict](../core/dict.mdx); or `None`; default is `None` If specified, restricts the set of allowed fields. Possible values are: * list of fields: ``` provider(fields = ['a', 'b']) ``` * dictionary field name -> documentation: ``` provider( fields = \{ 'a' : 'Documentation for a', 'b' : 'Documentation for b' \}) ``` All fields are optional. | -| `init` | callable; or `None`; default is `None` | +ParameterDescription`doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the provider that can be extracted by documentation generating tools. + `fields`[sequence](../core/list.html) of [string](../core/string.html) s; or [dict](../core/dict.html); or `None`; + default is `None` + + If specified, restricts the set of allowed fields. + +Possible values are: + +- list of fields: + + + + ``` + provider(fields = ['a', 'b']) + ``` + +- dictionary field name -> documentation: + + + + ``` + provider( + fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' }) + ``` + + +All fields are optional. + `init` + callable; or `None`; + default is `None` + + An optional callback for preprocessing and validating the provider's field values during instantiation. If `init` is specified, `provider()` returns a tuple of 2 elements: the normal provider symbol and a _raw constructor_. + +A precise description follows; see [Rules (Custom initialization of providers)](https://bazel.build/extending/rules#custom_initialization_of_providers) for an intuitive discussion and use cases. + +Let `P` be the provider symbol created by calling `provider()`. Conceptually, an instance of `P` is generated by calling a default constructor function `c(*args, **kwargs)`, which does the following: + +- If `args` is non-empty, an error occurs. +- If the `fields` parameter was specified when `provider()` was called, and if `kwargs` contains any key that was not listed in `fields`, an error occurs. +- Otherwise, `c` returns a new instance that has, for each `k: v` entry in `kwargs`, a field named `k` with value `v`. + +In the case where an `init` callback is _not_ given, a call to the symbol `P` itself acts as a call to the default constructor function `c`; in other words, `P(*args, **kwargs)` returns `c(*args, **kwargs)`. For example, + +``` +MyInfo = provider() +m = MyInfo(foo = 1) +``` + +will straightforwardly make it so that `m` is a `MyInfo` instance with `m.foo == 1`. + +But in the case where `init` is specified, the call `P(*args, **kwargs)` will perform the following steps instead: + +1. The callback is invoked as `init(*args, **kwargs)`, that is, with the exact same positional and keyword arguments as were passed to `P`. +2. The return value of `init` is expected to be a dictionary, `d`, whose keys are field name strings. If it is not, an error occurs. +3. A new instance of `P` is generated as if by calling the default constructor with `d`'s entries as keyword arguments, as in `c(**d)`. + +NB: the above steps imply that an error occurs if `*args` or `**kwargs` does not match `init`'s signature, or the evaluation of `init`'s body fails (perhaps intentionally via a call to [`fail()`](../globals/all.html#fail)), or if the return value of `init` is not a dictionary with the expected schema. + +In this way, the `init` callback generalizes normal provider construction by allowing positional arguments and arbitrary logic for preprocessing and validation. It does _not_ enable circumventing the list of allowed `fields`. + +When `init` is specified, the return value of `provider()` becomes a tuple `(P, r)`, where `r` is the _raw constructor_. In fact, the behavior of `r` is exactly that of the default constructor function `c` discussed above. Typically, `r` is bound to a variable whose name is prefixed with an underscore, so that only the current .bzl file has direct access to it: + +``` +MyInfo, _new_myinfo = provider(init = ...) +``` ## repository\_rule @@ -257,58 +633,211 @@ If `init` is specified, returns a tuple of 2 elements: a [`Provider`](../builtin callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None) ``` -Creates a new repository rule. Store it in a global value, so that it can be loaded and called from a [`module_extension()`](#module_extension) implementation function, or used by [`use_repo_rule()`](../globals/module.html#use_repo_rule). + Creates a new repository rule. Store it in a global value, so that it can be loaded and called from a [`module_extension()`](#module_extension) implementation function, or used by [`use_repo_rule()`](../globals/module.html#use_repo_rule). + + ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | callable; required | -| `attrs` | [dict](../core/dict.mdx); or `None`; default is `None` | -| `local` | [bool](../core/bool.mdx); default is `False` Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch. | -| `environ` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` **Deprecated**. This parameter has been deprecated. Migrate to `repository_ctx.getenv` instead. Provides a list of environment variable that this repository rule depends on. If an environment variable in that list change, the repository will be refetched. | -| `configure` | [bool](../core/bool.mdx); default is `False` Indicate that the repository inspects the system for configuration purpose | -| `remotable` | [bool](../core/bool.mdx); default is `False` **Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_repo_remote_exec` Compatible with remote execution | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` | +ParameterDescription`implementation` + callable; + required + + the function that implements this rule. Must have a single parameter, `repository_ctx`. The function is called during the loading phase for each instance of the rule. + `attrs`[dict](../core/dict.html); or `None`; + default is `None` + + A dictionary to declare all the attributes of the repository rule. It maps from an attribute name to an attribute object (see +[`attr`](../toplevel/attr.html) module). Attributes starting with `_` are private, and can be used to add an implicit dependency on a label to a file (a repository rule cannot depend on a generated artifact). The attribute `name` is implicitly added and must not be specified. + +Declared attributes will convert `None` to the default value. + +`local`[bool](../core/bool.html); + default is `False` + + Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch. + `environ`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + +**Deprecated**. This parameter has been deprecated. Migrate to `repository_ctx.getenv` instead. + +Provides a list of environment variable that this repository rule depends on. If an environment variable in that list change, the repository will be refetched. + `configure`[bool](../core/bool.html); + default is `False` + + Indicate that the repository inspects the system for configuration purpose + `remotable`[bool](../core/bool.html); + default is `False` + +**Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_repo_remote_exec` + +Compatible with remote execution + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the repository rule that can be extracted by documentation generating tools. + ## rule ``` -callable rule(implementation, *, test=unbound, attrs=\{\}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[]) +callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[]) ``` -Creates a new rule, which can be called from a BUILD file or a macro to create targets. + Creates a new rule, which can be called from a BUILD file or a macro to create targets. Rules must be assigned to global variables in a .bzl file; the name of the global variable is the rule's name. Test rules are required to have a name ending in `_test`, while all other rules must not have this suffix. (This restriction applies only to rules, not to their targets.) + ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | [function](../core/function.mdx); required the Starlark function implementing this rule, must have exactly one parameter: [ctx](../builtins/ctx.mdx). The function is called during the analysis phase for each instance of the rule. It can access the attributes provided by the user. It must create actions to generate all the declared outputs. | -| `test` | [bool](../core/bool.mdx); default is `unbound` Whether this rule is a test rule, that is, whether it may be the subject of a `bazel test` command. All test rules are automatically considered [executable](#rule.executable); it is unnecessary (and discouraged) to explicitly set `executable = True` for a test rule. The value defaults to `False`. See the [Rules page](https://bazel.build/extending/rules#executable_rules_and_test_rules) for more information. | -| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see [`attr`](../toplevel/attr.mdx) module). Attributes starting with `_` are private, and can be used to add an implicit dependency on a label. The attribute `name` is implicitly added and must not be specified. Attributes `visibility`, `deprecation`, `tags`, `testonly`, and `features` are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. Declared attributes will convert `None` to the default value. | -| `outputs` | [dict](../core/dict.mdx); or `None`; or [function](../core/function.mdx); default is `None` **Deprecated**. This parameter is deprecated and will be removed soon. Please do not depend on it. It is *disabled* with `--incompatible_no_rule_outputs_param`. Use this flag to verify your code is compatible with its imminent removal. This parameter has been deprecated. Migrate rules to use `OutputGroupInfo` or `attr.output` instead. A schema for defining predeclared outputs. Unlike [`output`](../toplevel/attr.html#output) and [`output_list`](../toplevel/attr.html#output_list) attributes, the user does not specify the labels for these files. See the [Rules page](https://bazel.build/extending/rules#files) for more on predeclared outputs. The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass `outputs = _my_func` with the definition `def _my_func(srcs, deps): ...`, the function has access to the attributes `srcs` and `deps`. Whether the dictionary is specified directly or via a function, it is interpreted as follows. Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's [`File`](../builtins/File.mdx) in [`ctx.outputs`](../builtins/ctx.html#outputs). The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form `"%\{ATTR\}"` with a string formed from the value of the attribute `ATTR`: * String-typed attributes are substituted verbatim.* Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label `"//pkg:a/b.c"` becomes `"a/b"`.* Output-typed attributes become the part of the label after the package, including the file extension (for the above example, `"a/b.c"`).* All list-typed attributes (for example, `attr.label_list`) used in placeholders are required to have *exactly one element*. Their conversion is the same as their non-list version (`attr.label`).* Other attribute types may not appear in placeholders.* The special non-attribute placeholders `%\{dirname\}` and `%\{basename\}` expand to those parts of the rule's label, excluding its package. For example, in `"//pkg:a/b.c"`, the dirname is `a` and the basename is `b.c`. In practice, the most common substitution placeholder is `"%\{name\}"`. For example, for a target named "foo", the outputs dict `\{"bin": "%\{name\}.exe"\}` predeclares an output named `foo.exe` that is accessible in the implementation function as `ctx.outputs.bin`. | -| `executable` | [bool](../core/bool.mdx); default is `unbound` | -| `output_to_genfiles` | [bool](../core/bool.mdx); default is `False` If true, the files will be generated in the genfiles directory instead of the bin directory. Unless you need it for compatibility with existing rules (e.g. when generating header files for C++), do not set this flag. | -| `fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the rule requires in target configuration. | -| `host_fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the rule requires in host configuration. | -| `_skylark_testable` | [bool](../core/bool.mdx); default is `False` *(Experimental)* If true, this rule will expose its actions for inspection by rules that depend on it via an `Actions` provider. The provider is also available to the rule itself by calling [ctx.created\_actions()](../builtins/ctx.html#created_actions). This should only be used for testing the analysis-time behavior of Starlark rules. This flag may be removed in the future. | -| `toolchains` | [sequence](../core/list.mdx); default is `[]` If set, the set of toolchains this rule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the rule implementation via `ctx.toolchain`. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the rule that can be extracted by documentation generating tools. | -| `provides` | [sequence](../core/list.mdx); default is `[]` A list of providers that the implementation function must return. It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here. Each element of the list is an `*Info` object returned by [`provider()`](../globals/bzl.html#provider). When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The [`required_providers`](../globals/bzl.html#aspect.required_providers) field of an [aspect](../globals/bzl.html#aspect) does, however, require that providers are specified here. | -| `dependency_resolution_rule` | [bool](../core/bool.mdx); default is `False` If set, the rule can be a dependency through attributes also marked as available in materializers. Every attribute of rules with this flag set must be marked as available in materializers also. This is so that rules so marked cannot depend on rules that are not so marked. | -| `exec_compatible_with` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A list of constraints on the execution platform that apply to all targets of this rule type. | -| `analysis_test` | [bool](../core/bool.mdx); default is `False` If true, then this rule is treated as an analysis test. Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See [Testing](https://bazel.build/rules/testing#testing-rules) for guidance. If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using [analysis\_test\_transition](#analysis_test_transition) on its attributes, but opts into some restrictions: * Targets of this rule are limited in the number of transitive dependencies they may have.* The rule is considered a test rule (as if `test=True` were set). This supersedes the value of `test` * The rule implementation function may not register actions. Instead, it must register a pass/fail result via providing [AnalysisTestResultInfo](../providers/AnalysisTestResultInfo.mdx). | -| `build_setting` | [BuildSetting](../builtins/BuildSetting.mdx); or `None`; default is `None` If set, describes what kind of [`build setting`](./rules/config#user-defined-build-settings) this rule is. See the [`config`](../toplevel/config.mdx) module. If this is set, a mandatory attribute named "build\_setting\_default" is automatically added to this rule, with a type corresponding to the value passed in here. | -| `cfg` | default is `None` If set, points to the configuration transition the rule will apply to its own configuration before analysis. | -| `exec_groups` | [dict](../core/dict.mdx); or `None`; default is `None` Dict of execution group name (string) to [`exec_group`s](../globals/bzl.html#exec_group). If set, allows rules to run actions on multiple execution platforms within a single target. See [execution groups documentation](./reference/exec-groups) for more info. | -| `initializer` | default is `None` Experimental: the Stalark function initializing the attributes of the rule. The function is called at load time for each instance of the rule. It's called with `name` and the values of public attributes defined by the rule (not with generic attributes, for example `tags`). It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning `None` as value results in using the default value specified in the attribute definition. Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning `None`). Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases. It's a good practice to use `**kwargs` for attributes that are not handled. In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about. | -| `parent` | default is `None` Experimental: the Stalark rule that is extended. When set the public attributes are merged as well as advertised providers. The rule matches `executable` and `test` from the parent. Values of `fragments`, `toolchains`, `exec_compatible_with`, and `exec_groups` are merged. Legacy or deprecated parameters may not be set. Incoming configuration transition `cfg` of parent is applied after thisrule's incoming configuration. | -| `extendable` | [bool](../core/bool.mdx); or [Label](../builtins/Label.mdx); or [string](../core/string.mdx); or `None`; default is `None` Experimental: A label of an allowlist defining which rules can extending this rule. It can be set also to True/False to always allow/disallow extending. Bazel defaults to always allowing extensions. | -| `subrules` | [sequence](../core/list.mdx) of [Subrule](../builtins/Subrule.mdx)s; default is `[]` Experimental: List of subrules used by this rule. | +ParameterDescription`implementation`[function](../core/function.html); + required + + the Starlark function implementing this rule, must have exactly one parameter: [ctx](../builtins/ctx.html). The function is called during the analysis phase for each instance of the rule. It can access the attributes provided by the user. It must create actions to generate all the declared outputs. + `test`[bool](../core/bool.html); + default is `unbound` + + Whether this rule is a test rule, that is, whether it may be the subject of a `bazel test` command. All test rules are automatically considered [executable](#rule.executable); it is unnecessary (and discouraged) to explicitly set `executable = True` for a test rule. The value defaults to `False`. See the [Rules page](https://bazel.build/extending/rules#executable_rules_and_test_rules) for more information. + `attrs`[dict](../core/dict.html); + default is `{}` + + A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see +[`attr`](../toplevel/attr.html) module). Attributes starting with `_` are private, and can be used to add an implicit dependency on a label. The attribute `name` is implicitly added and must not be specified. Attributes `visibility`, `deprecation`, `tags`, `testonly`, and `features` are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared. + +Declared attributes will convert `None` to the default value. + +`outputs`[dict](../core/dict.html); or `None`; or [function](../core/function.html); + default is `None` + +**Deprecated**. This parameter is deprecated and will be removed soon. Please do not depend on it. It is _disabled_ with `--incompatible_no_rule_outputs_param`. Use this flag to verify your code is compatible with its imminent removal. + +This parameter has been deprecated. Migrate rules to use `OutputGroupInfo` or `attr.output` instead. + +A schema for defining predeclared outputs. Unlike [`output`](../toplevel/attr.html#output) and [`output_list`](../toplevel/attr.html#output_list) attributes, the user does not specify the labels for these files. See the [Rules page](https://bazel.build/extending/rules#files) for more on predeclared outputs. + +The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass `outputs = _my_func` with the definition `def _my_func(srcs, deps): ...`, the function has access to the attributes `srcs` and `deps`. Whether the dictionary is specified directly or via a function, it is interpreted as follows. + +Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's [`File`](../builtins/File.html) in [`ctx.outputs`](../builtins/ctx.html#outputs). The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form `"%{ATTR}"` with a string formed from the value of the attribute `ATTR`: + +- String-typed attributes are substituted verbatim. +- Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label `"//pkg:a/b.c"` becomes `"a/b"`. +- Output-typed attributes become the part of the label after the package, including the file extension (for the above example, `"a/b.c"`). +- All list-typed attributes (for example, `attr.label_list`) used in placeholders are required to have _exactly one element_. Their conversion is the same as their non-list version ( `attr.label`). +- Other attribute types may not appear in placeholders. +- The special non-attribute placeholders `%{dirname}` and `%{basename}` expand to those parts of the rule's label, excluding its package. For example, in `"//pkg:a/b.c"`, the dirname is `a` and the basename is `b.c`. + +In practice, the most common substitution placeholder is `"%{name}"`. For example, for a target named "foo", the outputs dict `{"bin": "%{name}.exe"}` predeclares an output named `foo.exe` that is accessible in the implementation function as `ctx.outputs.bin`. + + +`executable`[bool](../core/bool.html); + default is `unbound` + + Whether this rule is considered executable, that is, whether it may be the subject of a `bazel run` command. It defaults to `False`. See the [Rules page](https://bazel.build/extending/rules#executable_rules_and_test_rules) for more information. + `output_to_genfiles`[bool](../core/bool.html); + default is `False` + + If true, the files will be generated in the genfiles directory instead of the bin directory. Unless you need it for compatibility with existing rules (e.g. when generating header files for C++), do not set this flag. + `fragments`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + List of names of configuration fragments that the rule requires in target configuration. + `host_fragments`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + List of names of configuration fragments that the rule requires in host configuration. + `_skylark_testable`[bool](../core/bool.html); + default is `False` + +_(Experimental)_ + +If true, this rule will expose its actions for inspection by rules that depend on it via an `Actions` provider. The provider is also available to the rule itself by calling [ctx.created\_actions()](../builtins/ctx.html#created_actions). + +This should only be used for testing the analysis-time behavior of Starlark rules. This flag may be removed in the future. + `toolchains`[sequence](../core/list.html); + default is `[]` + + If set, the set of toolchains this rule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the rule implementation via `ctx.toolchain`. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the rule that can be extracted by documentation generating tools. + `provides`[sequence](../core/list.html); + default is `[]` + + A list of providers that the implementation function must return. + +It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here. + +Each element of the list is an `*Info` object returned by [`provider()`](../globals/bzl.html#provider). When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The [`required_providers`](../globals/bzl.html#aspect.required_providers) field of an [aspect](../globals/bzl.html#aspect) does, however, require that providers are specified here. + + +`dependency_resolution_rule`[bool](../core/bool.html); + default is `False` + + If set, the rule can be a dependency through attributes also marked as available in materializers. Every attribute of rules with this flag set must be marked as available in materializers also. This is so that rules so marked cannot depend on rules that are not so marked. + `exec_compatible_with`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + A list of constraints on the execution platform that apply to all targets of this rule type. + `analysis_test`[bool](../core/bool.html); + default is `False` + + If true, then this rule is treated as an analysis test. + +Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See [Testing](https://bazel.build/rules/testing#testing-rules) for guidance. + +If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using [analysis\_test\_transition](#analysis_test_transition) on its attributes, but opts into some restrictions: + +- Targets of this rule are limited in the number of transitive dependencies they may have. +- The rule is considered a test rule (as if `test=True` were set). This supersedes the value of `test` +- The rule implementation function may not register actions. Instead, it must register a pass/fail result via providing [AnalysisTestResultInfo](../providers/AnalysisTestResultInfo.html). + +`build_setting`[BuildSetting](../builtins/BuildSetting.html); or `None`; + default is `None` + + If set, describes what kind of [`build setting`](/rules/config#user-defined-build-settings) this rule is. See the [`config`](../toplevel/config.html) module. If this is set, a mandatory attribute named "build\_setting\_default" is automatically added to this rule, with a type corresponding to the value passed in here. + `cfg` + default is `None` + + If set, points to the configuration transition the rule will apply to its own configuration before analysis. + `exec_groups`[dict](../core/dict.html); or `None`; + default is `None` + + Dict of execution group name (string) to [`exec_group` s](../globals/bzl.html#exec_group). If set, allows rules to run actions on multiple execution platforms within a single target. See [execution groups documentation](/reference/exec-groups) for more info. + `initializer` + default is `None` + + Experimental: the Stalark function initializing the attributes of the rule. + +The function is called at load time for each instance of the rule. It's called with `name` and the values of public attributes defined by the rule (not with generic attributes, for example `tags`). + +It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning `None` as value results in using the default value specified in the attribute definition. + +Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning `None`). + +Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases. + +It's a good practice to use `**kwargs` for attributes that are not handled. + +In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about. + + +`parent` + default is `None` + + Experimental: the Stalark rule that is extended. When set the public attributes are merged as well as advertised providers. The rule matches `executable` and `test` from the parent. Values of `fragments`, `toolchains`, `exec_compatible_with`, and `exec_groups` are merged. Legacy or deprecated parameters may not be set. Incoming configuration transition `cfg` of parent is applied after thisrule's incoming configuration. + `extendable`[bool](../core/bool.html); or [Label](../builtins/Label.html); or [string](../core/string.html); or `None`; + default is `None` + + Experimental: A label of an allowlist defining which rules can extending this rule. It can be set also to True/False to always allow/disallow extending. Bazel defaults to always allowing extensions. + `subrules`[sequence](../core/list.html) of [Subrule](../builtins/Subrule.html) s; + default is `[]` + + Experimental: List of subrules used by this rule. + ## select @@ -316,47 +845,86 @@ Test rules are required to have a name ending in `_test`, while all other rules unknown select(x, no_match_error='') ``` -`select()` is the helper function that makes a rule attribute [configurable](./reference/be/common-definitions#configurable-attributes). See [build encyclopedia](./reference/be/functions#select) for details. + `select()` is the helper function that makes a rule attribute [configurable](/reference/be/common-definitions#configurable-attributes). See [build encyclopedia](/reference/be/functions#select) for details. + ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | [dict](../core/dict.mdx); required A dict that maps configuration conditions to values. Each key is a [Label](../builtins/Label.mdx) or a label string that identifies a config\_setting or constraint\_value instance. See the [documentation on macros](https://bazel.build/extending/legacy-macros#label-resolution) for when to use a Label instead of a string. If `--incompatible_resolve_select_keys_eagerly` is enabled, the keys are resolved to `Label` objects relative to the package of the file that contains this call to `select`. | -| `no_match_error` | [string](../core/string.mdx); default is `''` Optional custom error to report if no condition matches. | +ParameterDescription`x`[dict](../core/dict.html); + required + + A dict that maps configuration conditions to values. Each key is a [Label](../builtins/Label.html) or a label string that identifies a config\_setting or constraint\_value instance. See the [documentation on macros](https://bazel.build/extending/legacy-macros#label-resolution) for when to use a Label instead of a string. If `--incompatible_resolve_select_keys_eagerly` is enabled, the keys are resolved to `Label` objects relative to the package of the file that contains this call to `select`. + `no_match_error`[string](../core/string.html); + default is `''` + + Optional custom error to report if no condition matches. + ## subrule ``` -Subrule subrule(*, implementation, attrs=\{\}, toolchains=[], fragments=[], subrules=[]) +Subrule subrule(*, implementation, attrs={}, toolchains=[], fragments=[], subrules=[]) ``` -Constructs a new instance of a subrule. The result of this function must be stored in a global variable before it can be used. + Constructs a new instance of a subrule. The result of this function must be stored in a global variable before it can be used. + ### Parameters -| Parameter | Description | -| --- | --- | -| `implementation` | [function](../core/function.mdx); required The Starlark function implementing this subrule | -| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the (private) attributes of the subrule. Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be: * `FilesToRunProvider` for label attributes with `executable=True` * `File` for label attributes with `allow_single_file=True` * `Target` for all other label attributes * `[Target]` for all label-list attributes | -| `toolchains` | [sequence](../core/list.mdx); default is `[]` If set, the set of toolchains this subrule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the subrule implementation via `ctx.toolchains`. Note that AEGs need to be enabled on the consuming rule(s) if this parameter is set. In case you haven't migrated to AEGs yet, see https://bazel.build/extending/auto-exec-groups#migration-aegs. | -| `fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of names of configuration fragments that the subrule requires in target configuration. | -| `subrules` | [sequence](../core/list.mdx) of [Subrule](../builtins/Subrule.mdx)s; default is `[]` List of other subrules needed by this subrule. | +ParameterDescription`implementation`[function](../core/function.html); + required + + The Starlark function implementing this subrule + `attrs`[dict](../core/dict.html); + default is `{}` + + A dictionary to declare all the (private) attributes of the subrule. + +Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be: + +- `FilesToRunProvider` for label attributes with `executable=True` +- `File` for label attributes with `allow_single_file=True` +- `Target` for all other label attributes +- `[Target]` for all label-list attributes + +`toolchains`[sequence](../core/list.html); + default is `[]` + + If set, the set of toolchains this subrule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the subrule implementation via `ctx.toolchains`. Note that AEGs need to be enabled on the consuming rule(s) if this parameter is set. In case you haven't migrated to AEGs yet, see https://bazel.build/extending/auto-exec-groups#migration-aegs. + `fragments`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + List of names of configuration fragments that the subrule requires in target configuration. + `subrules`[sequence](../core/list.html) of [Subrule](../builtins/Subrule.html) s; + default is `[]` + + List of other subrules needed by this subrule. + ## tag\_class ``` -tag_class tag_class(attrs=\{\}, *, doc=None) +tag_class tag_class(attrs={}, *, doc=None) ``` -Creates a new tag\_class object, which defines an attribute schema for a class of tags, which are data objects usable by a module extension. + Creates a new tag\_class object, which defines an attribute schema for a class of tags, which are data objects usable by a module extension. + ### Parameters -| Parameter | Description | -| --- | --- | -| `attrs` | [dict](../core/dict.mdx); default is `\{\}` A dictionary to declare all the attributes of this tag class. It maps from an attribute name to an attribute object (see [attr](../toplevel/attr.mdx) module). Note that unlike [`rule()`](../globals/bzl.html#rule), [`aspect()`](../globals/bzl.html#aspect) and [`repository_rule()`](../globals/bzl.html#repository_rule), declared attributes will not convert `None` to the default value. For the default to be used, the attribute must be omitted entirely by the caller. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the tag class that can be extracted by documentation generating tools. | +ParameterDescription`attrs`[dict](../core/dict.html); + default is `{}` + + A dictionary to declare all the attributes of this tag class. It maps from an attribute name to an attribute object (see [attr](../toplevel/attr.html) module). + +Note that unlike [`rule()`](../globals/bzl.html#rule), [`aspect()`](../globals/bzl.html#aspect) and [`repository_rule()`](../globals/bzl.html#repository_rule), +declared attributes will not convert `None` to the default value. For the default to be used, the attribute must be omitted entirely by the caller. + +`doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the tag class that can be extracted by documentation generating tools. + ## visibility @@ -372,8 +940,22 @@ The load visibility of a module governs whether or not other BUILD and .bzl file If the flag `--check_bzl_visibility` is set to false, load visibility violations will emit warnings but not fail the build. + ### Parameters -| Parameter | Description | -| --- | --- | -| `value` | required A list of package specification strings, or a single package specification string. Package specifications follow the same format as for `package_group`, except that negative package specifications are not permitted. That is, a specification may have the forms: * `"//foo"`: the package `//foo`* `"//foo/..."`: the package `//foo` and all of its subpackages.* `"public"` or `"private"`: all packages or no packages, respectively The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository. If `value` is a list of strings, the set of packages granted visibility to this module is the union of the packages represented by each specification. (An empty list has the same effect as `private`.) If `value` is a single string, it is treated as if it were the singleton list `[value]`. Note that the flags `--incompatible_package_group_has_public_syntax` and `--incompatible_fix_package_group_reporoot_syntax` have no effect on this argument. The `"public"` and `"private"` values are always available, and `"//..."` is always interpreted as "all packages in the current repository". | \ No newline at end of file +ParameterDescription`value` + required + + A list of package specification strings, or a single package specification string. + +Package specifications follow the same format as for `package_group`, except that negative package specifications are not permitted. That is, a specification may have the forms: + +- `"//foo"`: the package `//foo` +- `"//foo/..."`: the package `//foo` and all of its subpackages. +- `"public"` or `"private"`: all packages or no packages, respectively + +The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository. + +If `value` is a list of strings, the set of packages granted visibility to this module is the union of the packages represented by each specification. (An empty list has the same effect as `private`.) If `value` is a single string, it is treated as if it were the singleton list `[value]`. + +Note that the flags `--incompatible_package_group_has_public_syntax` and `--incompatible_fix_package_group_reporoot_syntax` have no effect on this argument. The `"public"` and `"private"` values are always available, and `"//..."` is always interpreted as "all packages in the current repository". diff --git a/rules/lib/globals/module.mdx b/rules/lib/globals/module.mdx index b4b9eaf..ecda6b1 100644 --- a/rules/lib/globals/module.mdx +++ b/rules/lib/globals/module.mdx @@ -1,28 +1,29 @@ --- -title: 'module' +title: 'MODULE.bazel files' --- + Methods available in MODULE.bazel files. ## Members -* [archive\_override](#archive_override) -* [bazel\_dep](#bazel_dep) -* [flag\_alias](#flag_alias) -* [git\_override](#git_override) -* [include](#include) -* [inject\_repo](#inject_repo) -* [local\_path\_override](#local_path_override) -* [module](#module) -* [multiple\_version\_override](#multiple_version_override) -* [override\_repo](#override_repo) -* [register\_execution\_platforms](#register_execution_platforms) -* [register\_toolchains](#register_toolchains) -* [single\_version\_override](#single_version_override) -* [use\_extension](#use_extension) -* [use\_repo](#use_repo) -* [use\_repo\_rule](#use_repo_rule) +- [archive\_override](#archive_override) +- [bazel\_dep](#bazel_dep) +- [flag\_alias](#flag_alias) +- [git\_override](#git_override) +- [include](#include) +- [inject\_repo](#inject_repo) +- [local\_path\_override](#local_path_override) +- [module](#module) +- [multiple\_version\_override](#multiple_version_override) +- [override\_repo](#override_repo) +- [register\_execution\_platforms](#register_execution_platforms) +- [register\_toolchains](#register_toolchains) +- [single\_version\_override](#single_version_override) +- [use\_extension](#use_extension) +- [use\_repo](#use_repo) +- [use\_repo\_rule](#use_repo_rule) ## archive\_override @@ -30,19 +31,27 @@ Methods available in MODULE.bazel files. None archive_override(*, module_name, **kwargs) ``` -Specifies that this dependency should come from an archive file (zip, gzip, etc) at a + Specifies that this dependency should come from an archive file (zip, gzip, etc) at a certain location, instead of from a registry. Effectively, this dependency will be backed by an [`http_archive`](../repo/http#http_archive) rule. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + ### Parameters -| Parameter | Description | -| --- | --- | -| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | -| `kwargs` | required All other arguments are forwarded to the underlying `http_archive` repo rule. Note that the `name` attribute shouldn't be specified; use `module_name` instead. | +ParameterDescription`module_name`[string](../core/string.html); + required + + The name of the Bazel module dependency to apply this override to. + `kwargs` + required + + All other arguments are forwarded to the underlying `http_archive` repo +rule. Note that the `name` attribute shouldn't be specified; use +`module_name` instead. + ## bazel\_dep @@ -50,17 +59,37 @@ used as a dependency by others, its own overrides are ignored. None bazel_dep(*, name, version='', max_compatibility_level=-1, repo_name='', dev_dependency=False) ``` -Declares a direct dependency on another Bazel module. + Declares a direct dependency on another Bazel module. + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required The name of the module to be added as a direct dependency. | -| `version` | [string](../core/string.mdx); default is `''` The version of the module to be added as a direct dependency. | -| `max_compatibility_level` | [int](../core/int.mdx); default is `-1` The maximum `compatibility_level` supported for the module to be added as a direct dependency. The version of the module implies the minimum compatibility\_level supported, as well as the maximum if this attribute is not specified. | -| `repo_name` | [string](../core/string.mdx); or `None`; default is `''` The name of the external repo representing this dependency. This is by default the name of the module. Can be set to `None` to make this dependency a "*nodep*" dependency: in this case, this `bazel_dep` specification is only honored if the target module already exists in the dependency graph by some other means. | -| `dev_dependency` | [bool](../core/bool.mdx); default is `False` If true, this dependency will be ignored if the current module is not the root module or `--ignore_dev_dependency` is enabled. | +ParameterDescription`name`[string](../core/string.html); + required + + The name of the module to be added as a direct dependency. + `version`[string](../core/string.html); + default is `''` + + The version of the module to be added as a direct dependency. + `max_compatibility_level`[int](../core/int.html); + default is `-1` + + The maximum `compatibility_level` supported for the module to be added as a direct dependency. The version of the module implies the minimum compatibility\_level supported, as well as the maximum if this attribute is not specified. + `repo_name`[string](../core/string.html); or `None`; + default is `''` + + The name of the external repo representing this dependency. This is by default the +name of the module. Can be set to `None` to make this dependency a +" _nodep_" dependency: in this case, this `bazel_dep` specification +is only honored if the target module already exists in the dependency graph by some +other means. + + `dev_dependency`[bool](../core/bool.html); + default is `False` + + If true, this dependency will be ignored if the current module is not the root module or `--ignore_dev_dependency` is enabled. + ## flag\_alias @@ -68,15 +97,22 @@ Declares a direct dependency on another Bazel module. None flag_alias(name, starlark_flag) ``` -Maps a command-line flag --foo to a Starlark flag --@repo//defs:foo. Bazel translates all -instances of $ bazel build //target --foo to $ bazel build //target --@repo//defs:foo. + Maps a command-line flag --foo to a Starlark flag --@repo//defs:foo. Bazel translates all + instances of $ bazel build //target --foo to $ bazel build //target --@repo//defs:foo. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required The name of the flag. | -| `starlark_flag` | [string](../core/string.mdx); required The label of the Starlark flag to alias to. | +ParameterDescription`name`[string](../core/string.html); + required + + The name of the flag. + `starlark_flag`[string](../core/string.html); + required + + The label of the Starlark flag to alias to. + ## git\_override @@ -84,19 +120,27 @@ instances of $ bazel build //target --foo to $ bazel build //target --@repo//def None git_override(*, module_name, **kwargs) ``` -Specifies that this dependency should come from a certain commit in a Git repository, + Specifies that this dependency should come from a certain commit in a Git repository, instead of from a registry. Effectively, this dependency will be backed by a [`git_repository`](../repo/git#git_repository) rule. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + ### Parameters -| Parameter | Description | -| --- | --- | -| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | -| `kwargs` | required All other arguments are forwarded to the underlying `git_repository` repo rule. Note that the `name` attribute shouldn't be specified; use `module_name` instead. | +ParameterDescription`module_name`[string](../core/string.html); + required + + The name of the Bazel module dependency to apply this override to. + `kwargs` + required + + All other arguments are forwarded to the underlying `git_repository` +repo rule. Note that the `name` attribute shouldn't be specified; use +`module_name` instead. + ## include @@ -104,7 +148,7 @@ used as a dependency by others, its own overrides are ignored. None include(label) ``` -Includes the contents of another MODULE.bazel-like file. Effectively, `include()` behaves as if the included file is textually placed at the location of the `include()` call, except that variable bindings (such as those used for `use_extension`) are only ever visible in the file they occur in, not in any included or including files. + Includes the contents of another MODULE.bazel-like file. Effectively, `include()` behaves as if the included file is textually placed at the location of the `include()` call, except that variable bindings (such as those used for `use_extension`) are only ever visible in the file they occur in, not in any included or including files. Only the root module may use `include()`; it is an error if a `bazel_dep`'s MODULE file uses `include()`. @@ -112,11 +156,13 @@ Only files in the main repo may be included. `include()` allows you to segment the root module file into multiple parts, to avoid having an enormous MODULE.bazel file or to better manage access control for individual semantic segments. + ### Parameters -| Parameter | Description | -| --- | --- | -| `label` | [string](../core/string.mdx); required The label pointing to the file to include. The label must point to a file in the main repo; in other words, it **must **start with double slashes (`//`). The name of the file must end with `.MODULE.bazel` and must not start with `.`.**** | +ParameterDescription`label`[string](../core/string.html); + required + + The label pointing to the file to include. The label must point to a file in the main repo; in other words, it **must start with double slashes ( `//`). The name of the file must end with `.MODULE.bazel` and must not start with `.`.** ## inject\_repo @@ -124,20 +170,38 @@ Only files in the main repo may be included. None inject_repo(extension_proxy, *args, **kwargs) ``` -Injects one or more new repos into the given module extension. + Injects one or more new repos into the given module extension. This is ignored if the current module is not the root module or `--ignore_dev_dependency` is enabled. Use [`override_repo`](#override_repo) instead to override an existing repo. + ### Parameters -| Parameter | Description | -| --- | --- | -| `extension_proxy` | module\_extension\_proxy; required A module extension proxy object returned by a `use_extension` call. | -| `args` | required The repos visible to the current module that should be injected into the extension under the same name. | -| `kwargs` | required The new repos to inject into the extension, where the values are the names of repos in the scope of the current module and the keys are the name they will be visible under in the extension. Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., `inject_repo(extension_proxy, **\{"foo.2": "foo"\})`. | +ParameterDescription`extension_proxy` + module\_extension\_proxy; + required + + A module extension proxy object returned by a `use_extension` call. + `args` + required + + The repos visible to the current module that should be injected into the +extension under the same name. + `kwargs` + required + + The new repos to inject into the extension, where the values are the names of +repos in the scope of the current module and the keys are the name they will be +visible under in the extension. + +Keys that are not valid identifiers can be specified via a literal dict +passed as extra keyword arguments, e.g., +`inject_repo(extension_proxy, **{"foo.2": "foo"})`. + + ## local\_path\_override @@ -145,19 +209,25 @@ existing repo. None local_path_override(*, module_name, path) ``` -Specifies that this dependency should come from a certain directory on local disk, + Specifies that this dependency should come from a certain directory on local disk, instead of from a registry. Effectively, this dependency will be backed by a [`local_repository`](../repo/local#local_repository) rule. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + ### Parameters -| Parameter | Description | -| --- | --- | -| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | -| `path` | [string](../core/string.mdx); required The path to the directory where this module is. | +ParameterDescription`module_name`[string](../core/string.html); + required + + The name of the Bazel module dependency to apply this override to. + `path`[string](../core/string.html); + required + + The path to the directory where this module is. + ## module @@ -165,19 +235,35 @@ used as a dependency by others, its own overrides are ignored. None module(*, name='', version='', compatibility_level=0, repo_name='', bazel_compatibility=[]) ``` -Declares certain properties of the Bazel module represented by the current Bazel repo. These properties are either essential metadata of the module (such as the name and version), or affect behavior of the current module and its dependents. + Declares certain properties of the Bazel module represented by the current Bazel repo. These properties are either essential metadata of the module (such as the name and version), or affect behavior of the current module and its dependents. It should be called at most once, and if called, it must be the very first directive in the MODULE.bazel file. It can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); default is `''` The name of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). A valid module name must: 1) only contain lowercase letters (a-z), digits (0-9), dots (.), hyphens (-), and underscores (\_); 2) begin with a lowercase letter; 3) end with a lowercase letter or digit. | -| `version` | [string](../core/string.mdx); default is `''` The version of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). The version must be in a relaxed SemVer format; see [the documentation](./external/module#version_format) for more details. | -| `compatibility_level` | [int](../core/int.mdx); default is `0` The compatibility level of the module; this should be changed every time a major incompatible change is introduced. This is essentially the "major version" of the module in terms of SemVer, except that it's not embedded in the version string itself, but exists as a separate field. Modules with different compatibility levels participate in version resolution as if they're modules with different names, but the final dependency graph cannot contain multiple modules with the same name but different compatibility levels (unless `multiple_version_override` is in effect). See [the documentation](./external/module#compatibility_level) for more details. | -| `repo_name` | [string](../core/string.mdx); default is `''` The name of the repository representing this module, as seen by the module itself. By default, the name of the repo is the name of the module. This can be specified to ease migration for projects that have been using a repo name for itself that differs from its module name. | -| `bazel_compatibility` | Iterable of [string](../core/string.mdx)s; default is `[]` A list of bazel versions that allows users to declare which Bazel versions are compatible with this module. It does NOT affect dependency resolution, but bzlmod will use this information to check if your current Bazel version is compatible. The format of this value is a string of some constraint values separated by comma. Three constraints are supported: <=X.X.X: The Bazel version must be equal or older than X.X.X. Used when there is a known incompatible change in a newer version. >=X.X.X: The Bazel version must be equal or newer than X.X.X.Used when you depend on some features that are only available since X.X.X. -X.X.X: The Bazel version X.X.X is not compatible. Used when there is a bug in X.X.X that breaks you, but fixed in later versions. | +ParameterDescription`name`[string](../core/string.html); + default is `''` + + The name of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). A valid module name must: 1) only contain lowercase letters (a-z), digits (0-9), dots (.), hyphens (-), and underscores (\_); 2) begin with a lowercase letter; 3) end with a lowercase letter or digit. + `version`[string](../core/string.html); + default is `''` + + The version of the module. Can be omitted only if this module is the root module (as in, if it's not going to be depended on by another module). The version must be in a relaxed SemVer format; see [the documentation](/external/module#version_format) for more details. + `compatibility_level`[int](../core/int.html); + default is `0` + + The compatibility level of the module; this should be changed every time a major incompatible change is introduced. This is essentially the "major version" of the module in terms of SemVer, except that it's not embedded in the version string itself, but exists as a separate field. Modules with different compatibility levels participate in version resolution as if they're modules with different names, but the final dependency graph cannot contain multiple modules with the same name but different compatibility levels (unless `multiple_version_override` is in effect). See [the documentation](/external/module#compatibility_level) for more details. + `repo_name`[string](../core/string.html); + default is `''` + + The name of the repository representing this module, as seen by the module itself. By default, the name of the repo is the name of the module. This can be specified to ease migration for projects that have been using a repo name for itself that differs from its module name. + `bazel_compatibility` + Iterable of [string](../core/string.html) s; + default is `[]` + + A list of bazel versions that allows users to declare which Bazel versions are compatible with this module. It does NOT affect dependency resolution, but bzlmod will use this information to check if your current Bazel version is compatible. The format of this value is a string of some constraint values separated by comma. Three constraints are supported: <=X.X.X: The Bazel version must be equal or older than X.X.X. Used when there is a known incompatible change in a newer version. >=X.X.X: The Bazel version must be equal or newer than X.X.X.Used when you depend on some features that are only available since X.X.X. -X.X.X: The Bazel version X.X.X is not compatible. Used when there is a bug in X.X.X that breaks you, but fixed in later versions. + ## multiple\_version\_override @@ -185,15 +271,25 @@ It should be called at most once, and if called, it must be the very first direc None multiple_version_override(*, module_name, versions, registry='') ``` -Specifies that a dependency should still come from a registry, but multiple versions of it should be allowed to coexist. See [the documentation](./external/module#multiple-version_override) for more details. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + Specifies that a dependency should still come from a registry, but multiple versions of it should be allowed to coexist. See [the documentation](/external/module#multiple-version_override) for more details. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + ### Parameters -| Parameter | Description | -| --- | --- | -| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | -| `versions` | Iterable of [string](../core/string.mdx)s; required Explicitly specifies the versions allowed to coexist. These versions must already be present in the dependency graph pre-selection. Dependencies on this module will be "upgraded" to the nearest higher allowed version at the same compatibility level, whereas dependencies that have a higher version than any allowed versions at the same compatibility level will cause an error. | -| `registry` | [string](../core/string.mdx); default is `''` Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. | +ParameterDescription`module_name`[string](../core/string.html); + required + + The name of the Bazel module dependency to apply this override to. + `versions` + Iterable of [string](../core/string.html) s; + required + + Explicitly specifies the versions allowed to coexist. These versions must already be present in the dependency graph pre-selection. Dependencies on this module will be "upgraded" to the nearest higher allowed version at the same compatibility level, whereas dependencies that have a higher version than any allowed versions at the same compatibility level will cause an error. + `registry`[string](../core/string.html); + default is `''` + + Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. + ## override\_repo @@ -201,19 +297,38 @@ Specifies that a dependency should still come from a registry, but multiple vers None override_repo(extension_proxy, *args, **kwargs) ``` -Overrides one or more repos defined by the given module extension with the given repos + Overrides one or more repos defined by the given module extension with the given repos visible to the current module. This is ignored if the current module is not the root -module or `--ignore\_dev\_dependency` is enabled. +module or \`--ignore\_dev\_dependency\` is enabled. Use [`inject_repo`](#inject_repo) instead to add a new repo. + + ### Parameters -| Parameter | Description | -| --- | --- | -| `extension_proxy` | module\_extension\_proxy; required A module extension proxy object returned by a `use_extension` call. | -| `args` | required The repos in the extension that should be overridden with the repos of the same name in the current module. | -| `kwargs` | required The overrides to apply to the repos generated by the extension, where the values are the names of repos in the scope of the current module and the keys are the names of the repos they will override in the extension. Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., `override_repo(extension_proxy, **\{"foo.2": "foo"\})`. | +ParameterDescription`extension_proxy` + module\_extension\_proxy; + required + + A module extension proxy object returned by a `use_extension` call. + `args` + required + + The repos in the extension that should be overridden with the repos of the same +name in the current module. + `kwargs` + required + + The overrides to apply to the repos generated by the extension, where the values +are the names of repos in the scope of the current module and the keys are the +names of the repos they will override in the extension. + +Keys that are not valid identifiers can be specified via a literal dict +passed as extra keyword arguments, e.g., +`override_repo(extension_proxy, **{"foo.2": "foo"})`. + + ## register\_execution\_platforms @@ -221,14 +336,20 @@ Use [`inject_repo`](#inject_repo) instead to add a new repo. None register_execution_platforms(*platform_labels, dev_dependency=False) ``` -Specifies already-defined execution platforms to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](./docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by name. + Specifies already-defined execution platforms to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](/docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by name. + ### Parameters -| Parameter | Description | -| --- | --- | -| `dev_dependency` | [bool](../core/bool.mdx); default is `False` If true, the execution platforms will not be registered if the current module is not the root module or `--ignore\_dev\_dependency` is enabled. | -| `platform_labels` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The target patterns to register. | +ParameterDescription`dev_dependency`[bool](../core/bool.html); + default is `False` + + If true, the execution platforms will not be registered if the current module is not the root module or \`--ignore\_dev\_dependency\` is enabled. + `platform_labels`[sequence](../core/list.html) of [string](../core/string.html) s; + required + + The target patterns to register. + ## register\_toolchains @@ -236,14 +357,20 @@ Specifies already-defined execution platforms to be registered when this module None register_toolchains(*toolchain_labels, dev_dependency=False) ``` -Specifies already-defined toolchains to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](./docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by target name (not the name of the toolchain implementation). + Specifies already-defined toolchains to be registered when this module is selected. Should be absolute [target patterns](https://bazel.build/reference/glossary#target-pattern) (ie. beginning with either `@` or `//`). See [toolchain resolution](/docs/toolchains) for more information. Patterns that expand to multiple targets, such as `:all`, will be registered in lexicographical order by target name (not the name of the toolchain implementation). + ### Parameters -| Parameter | Description | -| --- | --- | -| `dev_dependency` | [bool](../core/bool.mdx); default is `False` If true, the toolchains will not be registered if the current module is not the root module or `--ignore\_dev\_dependency` is enabled. | -| `toolchain_labels` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The target patterns to register. | +ParameterDescription`dev_dependency`[bool](../core/bool.html); + default is `False` + + If true, the toolchains will not be registered if the current module is not the root module or \`--ignore\_dev\_dependency\` is enabled. + `toolchain_labels`[sequence](../core/list.html) of [string](../core/string.html) s; + required + + The target patterns to register. + ## single\_version\_override @@ -251,18 +378,46 @@ Specifies already-defined toolchains to be registered when this module is select None single_version_override(*, module_name, version='', registry='', patches=[], patch_cmds=[], patch_strip=0) ``` -Specifies that a dependency should still come from a registry, but its version should be pinned, or its registry overridden, or a list of patches applied. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + Specifies that a dependency should still come from a registry, but its version should be pinned, or its registry overridden, or a list of patches applied. This directive only takes effect in the root module; in other words, if a module is used as a dependency by others, its own overrides are ignored. + ### Parameters -| Parameter | Description | -| --- | --- | -| `module_name` | [string](../core/string.mdx); required The name of the Bazel module dependency to apply this override to. | -| `version` | [string](../core/string.mdx); default is `''` Overrides the declared version of this module in the dependency graph. In other words, this module will be "pinned" to this override version. This attribute can be omitted if all one wants to override is the registry or the patches. | -| `registry` | [string](../core/string.mdx); default is `''` Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. | -| `patches` | Iterable of [string](../core/string.mdx)s; default is `[]` A list of labels pointing to patch files to apply for this module. The patch files must exist in the source tree of the top level project. They are applied in the list order. If a patch makes changes to the MODULE.bazel file, these changes will only be effective if the patch file is provided by the root module. | -| `patch_cmds` | Iterable of [string](../core/string.mdx)s; default is `[]` Sequence of Bash commands to be applied on Linux/Macos after patches are applied. Changes to the MODULE.bazel file will not be effective. | -| `patch_strip` | [int](../core/int.mdx); default is `0` Same as the --strip argument of Unix patch. | +ParameterDescription`module_name`[string](../core/string.html); + required + + The name of the Bazel module dependency to apply this override to. + `version`[string](../core/string.html); + default is `''` + + Overrides the declared version of this module in the dependency graph. In other words, this module will be "pinned" to this override version. This attribute can be omitted if all one wants to override is the registry or the patches. + `registry`[string](../core/string.html); + default is `''` + + Overrides the registry for this module; instead of finding this module from the default list of registries, the given registry should be used. + `patches` + Iterable of [string](../core/string.html) s; + default is `[]` + + A list of labels pointing to patch files to apply for this module. The patch files must exist in the source tree of the top level project. They are applied in the list order. + +If a patch makes changes to the MODULE.bazel file, these changes will only be effective if the patch file is provided by the root module. + + +`patch_cmds` + Iterable of [string](../core/string.html) s; + default is `[]` + + Sequence of Bash commands to be applied on Linux/Macos after patches are applied. + +Changes to the MODULE.bazel file will not be effective. + + +`patch_strip`[int](../core/int.html); + default is `0` + + Same as the --strip argument of Unix patch. + ## use\_extension @@ -270,16 +425,32 @@ Specifies that a dependency should still come from a registry, but its version s module_extension_proxy use_extension(extension_bzl_file, extension_name, *, dev_dependency=False, isolate=False) ``` -Returns a proxy object representing a module extension; its methods can be invoked to create module extension tags. + Returns a proxy object representing a module extension; its methods can be invoked to create module extension tags. + ### Parameters -| Parameter | Description | -| --- | --- | -| `extension_bzl_file` | [string](../core/string.mdx); required A label to the Starlark file defining the module extension. | -| `extension_name` | [string](../core/string.mdx); required The name of the module extension to use. A symbol with this name must be exported by the Starlark file. | -| `dev_dependency` | [bool](../core/bool.mdx); default is `False` If true, this usage of the module extension will be ignored if the current module is not the root module or `--ignore\_dev\_dependency` is enabled. | -| `isolate` | [bool](../core/bool.mdx); default is `False` **Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_isolated_extension_usages` If true, this usage of the module extension will be isolated from all other usages, both in this and other modules. Tags created for this usage do not affect other usages and the repositories generated by the extension for this usage will be distinct from all other repositories generated by the extension. This parameter is currently experimental and only available with the flag `--experimental_isolated_extension_usages`. | +ParameterDescription`extension_bzl_file`[string](../core/string.html); + required + + A label to the Starlark file defining the module extension. + `extension_name`[string](../core/string.html); + required + + The name of the module extension to use. A symbol with this name must be exported by the Starlark file. + `dev_dependency`[bool](../core/bool.html); + default is `False` + + If true, this usage of the module extension will be ignored if the current module is not the root module or \`--ignore\_dev\_dependency\` is enabled. + `isolate`[bool](../core/bool.html); + default is `False` + +**Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_isolated_extension_usages` + +If true, this usage of the module extension will be isolated from all other usages, both in this and other modules. Tags created for this usage do not affect other usages and the repositories generated by the extension for this usage will be distinct from all other repositories generated by the extension. + +This parameter is currently experimental and only available with the flag `--experimental_isolated_extension_usages`. + ## use\_repo @@ -287,15 +458,33 @@ Returns a proxy object representing a module extension; its methods can be invok None use_repo(extension_proxy, *args, **kwargs) ``` -Imports one or more repos generated by the given module extension into the scope of the current module. + Imports one or more repos generated by the given module extension into the scope of the current module. + ### Parameters -| Parameter | Description | -| --- | --- | -| `extension_proxy` | module\_extension\_proxy; required | -| `args` | required The names of the repos to import. | -| `kwargs` | required Specifies certain repos to import into the scope of the current module with different names. The keys should be the name to use in the current scope, whereas the values should be the original names exported by the module extension. Keys that are not valid identifiers can be specified via a literal dict passed as extra keyword arguments, e.g., `use_repo(extension_proxy, **\{"foo.2": "foo"\})`. | +ParameterDescription`extension_proxy` + module\_extension\_proxy; + required + + A module extension proxy object returned by a `use_extension` call. + `args` + required + + The names of the repos to import. + `kwargs` + required + + Specifies certain repos to import into the scope of the current module with +different names. The keys should be the name to use in the current scope, +whereas the values should be the original names exported by the module +extension. + +Keys that are not valid identifiers can be specified via a literal dict +passed as extra keyword arguments, e.g., +`use_repo(extension_proxy, **{"foo.2": "foo"})`. + + ## use\_repo\_rule @@ -303,11 +492,16 @@ Imports one or more repos generated by the given module extension into the scope repo_rule_proxy use_repo_rule(repo_rule_bzl_file, repo_rule_name) ``` -Returns a proxy value that can be directly invoked in the MODULE.bazel file as a repository rule, one or more times. Repos created in such a way are only visible to the current module, under the name declared using the `name` attribute on the proxy. The implicit Boolean `dev_dependency` attribute can also be used on the proxy to denote that a certain repo is only to be created when the current module is the root module. + Returns a proxy value that can be directly invoked in the MODULE.bazel file as a repository rule, one or more times. Repos created in such a way are only visible to the current module, under the name declared using the `name` attribute on the proxy. The implicit Boolean `dev_dependency` attribute can also be used on the proxy to denote that a certain repo is only to be created when the current module is the root module. + ### Parameters -| Parameter | Description | -| --- | --- | -| `repo_rule_bzl_file` | [string](../core/string.mdx); required A label to the Starlark file defining the repo rule. | -| `repo_rule_name` | [string](../core/string.mdx); required The name of the repo rule to use. A symbol with this name must be exported by the Starlark file. | \ No newline at end of file +ParameterDescription`repo_rule_bzl_file`[string](../core/string.html); + required + + A label to the Starlark file defining the repo rule. + `repo_rule_name`[string](../core/string.html); + required + + The name of the repo rule to use. A symbol with this name must be exported by the Starlark file. diff --git a/rules/lib/globals/repo.mdx b/rules/lib/globals/repo.mdx index afe8793..342518e 100644 --- a/rules/lib/globals/repo.mdx +++ b/rules/lib/globals/repo.mdx @@ -1,14 +1,15 @@ --- -title: 'repo' +title: 'REPO.bazel files' --- + Methods available in REPO.bazel files. ## Members -* [ignore\_directories](#ignore_directories) -* [repo](#repo) +- [ignore\_directories](#ignore_directories) +- [repo](#repo) ## ignore\_directories @@ -16,15 +17,15 @@ Methods available in REPO.bazel files. None ignore_directories(dirs) ``` -The list of directories to ignore in this repository. + The list of directories to ignore in this repository. This function takes a list of strings and a directory is ignored if any of the given strings matches its repository-relative path according to the semantics of the `glob()` function. This function can be used to ignore directories that are implementation details of source control systems, output files of other build systems, etc. + ### Parameters -| Parameter | Description | -| --- | --- | -| `dirs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required | +ParameterDescription`dirs`[sequence](../core/list.html) of [string](../core/string.html) s; + required ## repo @@ -32,10 +33,12 @@ This function takes a list of strings and a directory is ignored if any of the g None repo(**kwargs) ``` -Declares metadata that applies to every rule in the repository. It must be called at most once per REPO.bazel file. If called, it must be the first call in the REPO.bazel file. + Declares metadata that applies to every rule in the repository. It must be called at most once per REPO.bazel file. If called, it must be the first call in the REPO.bazel file. + ### Parameters -| Parameter | Description | -| --- | --- | -| `kwargs` | required The `repo()` function accepts exactly the same arguments as the [`package()`](./reference/be/functions#package) function in BUILD files. | \ No newline at end of file +ParameterDescription`kwargs` + required + + The `repo()` function accepts exactly the same arguments as the [`package()`](/reference/be/functions#package) function in BUILD files. diff --git a/rules/lib/globals/vendor.mdx b/rules/lib/globals/vendor.mdx index 2178490..06ea2cd 100644 --- a/rules/lib/globals/vendor.mdx +++ b/rules/lib/globals/vendor.mdx @@ -1,14 +1,15 @@ --- -title: 'vendor' +title: 'VENDOR.bazel files' --- + Methods available in VENDOR.bazel files. ## Members -* [ignore](#ignore) -* [pin](#pin) +- [ignore](#ignore) +- [pin](#pin) ## ignore @@ -16,13 +17,16 @@ Methods available in VENDOR.bazel files. None ignore(*args) ``` -Ignore this repo from vendoring. Bazel will never vendor it or use the corresponding directory (if exists) while building in vendor mode. + Ignore this repo from vendoring. Bazel will never vendor it or use the corresponding directory (if exists) while building in vendor mode. + ### Parameters -| Parameter | Description | -| --- | --- | -| `args` | required The canonical repo names of the repos to ignore. | +ParameterDescription`args` + required + + The canonical repo names of the repos to ignore. + ## pin @@ -30,10 +34,12 @@ Ignore this repo from vendoring. Bazel will never vendor it or use the correspon None pin(*args) ``` -Pin the contents of this repo under the vendor directory. Bazel will not update this repo while vendoring, and will use the vendored source as if there is a --override\_repository flag when building in vendor mode + Pin the contents of this repo under the vendor directory. Bazel will not update this repo while vendoring, and will use the vendored source as if there is a --override\_repository flag when building in vendor mode + ### Parameters -| Parameter | Description | -| --- | --- | -| `args` | required The canonical repo names of the repos to pin. | \ No newline at end of file +ParameterDescription`args` + required + + The canonical repo names of the repos to pin. diff --git a/rules/lib/overview.mdx b/rules/lib/overview.mdx index c5e801e..54378f1 100644 --- a/rules/lib/overview.mdx +++ b/rules/lib/overview.mdx @@ -1,150 +1,151 @@ --- -title: 'overview' +title: 'One-Page Overview' --- -## [Global functions](./rules/lib/globals) -* [.bzl files](./rules/lib/globals/bzl) -* [All Bazel files](./rules/lib/globals/all) -* [BUILD files](./rules/lib/globals/build) -* [MODULE.bazel files](./rules/lib/globals/module) -* [REPO.bazel files](./rules/lib/globals/repo) -* [VENDOR.bazel files](./rules/lib/globals/vendor) +## [Global functions](/rules/lib/globals) -## [Configuration Fragments](./rules/lib/fragments) +- [.bzl files](/rules/lib/globals/bzl) +- [All Bazel files](/rules/lib/globals/all) +- [BUILD files](/rules/lib/globals/build) +- [MODULE.bazel files](/rules/lib/globals/module) +- [REPO.bazel files](/rules/lib/globals/repo) +- [VENDOR.bazel files](/rules/lib/globals/vendor) -* [apple](./rules/lib/fragments/apple) -* [bazel\_android](./rules/lib/fragments/bazel_android) -* [bazel\_py](./rules/lib/fragments/bazel_py) -* [coverage](./rules/lib/fragments/coverage) -* [cpp](./rules/lib/fragments/cpp) -* [j2objc](./rules/lib/fragments/j2objc) -* [java](./rules/lib/fragments/java) -* [objc](./rules/lib/fragments/objc) -* [platform](./rules/lib/fragments/platform) -* [proto](./rules/lib/fragments/proto) -* [py](./rules/lib/fragments/py) +## [Configuration Fragments](/rules/lib/fragments) -## [Providers](./rules/lib/providers) +- [apple](/rules/lib/fragments/apple) +- [bazel\_android](/rules/lib/fragments/bazel_android) +- [bazel\_py](/rules/lib/fragments/bazel_py) +- [coverage](/rules/lib/fragments/coverage) +- [cpp](/rules/lib/fragments/cpp) +- [j2objc](/rules/lib/fragments/j2objc) +- [java](/rules/lib/fragments/java) +- [objc](/rules/lib/fragments/objc) +- [platform](/rules/lib/fragments/platform) +- [proto](/rules/lib/fragments/proto) +- [py](/rules/lib/fragments/py) -* [AnalysisTestResultInfo](./rules/lib/providers/AnalysisTestResultInfo) -* [CcInfo](./rules/lib/providers/CcInfo) -* [CcToolchainConfigInfo](./rules/lib/providers/CcToolchainConfigInfo) -* [CcToolchainInfo](./rules/lib/providers/CcToolchainInfo) -* [ConstraintCollection](./rules/lib/providers/ConstraintCollection) -* [ConstraintSettingInfo](./rules/lib/providers/ConstraintSettingInfo) -* [ConstraintValueInfo](./rules/lib/providers/ConstraintValueInfo) -* [DebugPackageInfo](./rules/lib/providers/DebugPackageInfo) -* [DefaultInfo](./rules/lib/providers/DefaultInfo) -* [ExecutionInfo](./rules/lib/providers/ExecutionInfo) -* [FeatureFlagInfo](./rules/lib/providers/FeatureFlagInfo) -* [file\_provider](./rules/lib/providers/file_provider) -* [FilesToRunProvider](./rules/lib/providers/FilesToRunProvider) -* [IncompatiblePlatformProvider](./rules/lib/providers/IncompatiblePlatformProvider) -* [InstrumentedFilesInfo](./rules/lib/providers/InstrumentedFilesInfo) -* [java\_compilation\_info](./rules/lib/providers/java_compilation_info) -* [java\_output\_jars](./rules/lib/providers/java_output_jars) -* [JavaRuntimeInfo](./rules/lib/providers/JavaRuntimeInfo) -* [JavaToolchainInfo](./rules/lib/providers/JavaToolchainInfo) -* [MaterializedDepsInfo](./rules/lib/providers/MaterializedDepsInfo) -* [ObjcProvider](./rules/lib/providers/ObjcProvider) -* [OutputGroupInfo](./rules/lib/providers/OutputGroupInfo) -* [PackageSpecificationInfo](./rules/lib/providers/PackageSpecificationInfo) -* [PlatformInfo](./rules/lib/providers/PlatformInfo) -* [RunEnvironmentInfo](./rules/lib/providers/RunEnvironmentInfo) -* [TemplateVariableInfo](./rules/lib/providers/TemplateVariableInfo) -* [ToolchainInfo](./rules/lib/providers/ToolchainInfo) -* [ToolchainTypeInfo](./rules/lib/providers/ToolchainTypeInfo) +## [Providers](/rules/lib/providers) -## [Built-in Types](./rules/lib/builtins) +- [AnalysisTestResultInfo](/rules/lib/providers/AnalysisTestResultInfo) +- [CcInfo](/rules/lib/providers/CcInfo) +- [CcToolchainConfigInfo](/rules/lib/providers/CcToolchainConfigInfo) +- [CcToolchainInfo](/rules/lib/providers/CcToolchainInfo) +- [ConstraintCollection](/rules/lib/providers/ConstraintCollection) +- [ConstraintSettingInfo](/rules/lib/providers/ConstraintSettingInfo) +- [ConstraintValueInfo](/rules/lib/providers/ConstraintValueInfo) +- [DebugPackageInfo](/rules/lib/providers/DebugPackageInfo) +- [DefaultInfo](/rules/lib/providers/DefaultInfo) +- [ExecutionInfo](/rules/lib/providers/ExecutionInfo) +- [FeatureFlagInfo](/rules/lib/providers/FeatureFlagInfo) +- [file\_provider](/rules/lib/providers/file_provider) +- [FilesToRunProvider](/rules/lib/providers/FilesToRunProvider) +- [IncompatiblePlatformProvider](/rules/lib/providers/IncompatiblePlatformProvider) +- [InstrumentedFilesInfo](/rules/lib/providers/InstrumentedFilesInfo) +- [java\_compilation\_info](/rules/lib/providers/java_compilation_info) +- [java\_output\_jars](/rules/lib/providers/java_output_jars) +- [JavaRuntimeInfo](/rules/lib/providers/JavaRuntimeInfo) +- [JavaToolchainInfo](/rules/lib/providers/JavaToolchainInfo) +- [MaterializedDepsInfo](/rules/lib/providers/MaterializedDepsInfo) +- [ObjcProvider](/rules/lib/providers/ObjcProvider) +- [OutputGroupInfo](/rules/lib/providers/OutputGroupInfo) +- [PackageSpecificationInfo](/rules/lib/providers/PackageSpecificationInfo) +- [PlatformInfo](/rules/lib/providers/PlatformInfo) +- [RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo) +- [TemplateVariableInfo](/rules/lib/providers/TemplateVariableInfo) +- [ToolchainInfo](/rules/lib/providers/ToolchainInfo) +- [ToolchainTypeInfo](/rules/lib/providers/ToolchainTypeInfo) -* [Action](./rules/lib/builtins/Action) -* [actions](./rules/lib/builtins/actions) -* [apple\_platform](./rules/lib/builtins/apple_platform) -* [Args](./rules/lib/builtins/Args) -* [Aspect](./rules/lib/builtins/Aspect) -* [Attribute](./rules/lib/builtins/Attribute) -* [bazel\_module](./rules/lib/builtins/bazel_module) -* [bazel\_module\_tags](./rules/lib/builtins/bazel_module_tags) -* [BuildSetting](./rules/lib/builtins/BuildSetting) -* [CcCompilationOutputs](./rules/lib/builtins/CcCompilationOutputs) -* [CcLinkingOutputs](./rules/lib/builtins/CcLinkingOutputs) -* [CompilationContext](./rules/lib/builtins/CompilationContext) -* [configuration](./rules/lib/builtins/configuration) -* [ctx](./rules/lib/builtins/ctx) -* [depset](./rules/lib/builtins/depset) -* [DirectoryExpander](./rules/lib/builtins/DirectoryExpander) -* [DottedVersion](./rules/lib/builtins/DottedVersion) -* [exec\_result](./rules/lib/builtins/exec_result) -* [ExecGroupCollection](./rules/lib/builtins/ExecGroupCollection) -* [ExecGroupContext](./rules/lib/builtins/ExecGroupContext) -* [ExecTransitionFactory](./rules/lib/builtins/ExecTransitionFactory) -* [ExpandedDirectory](./rules/lib/builtins/ExpandedDirectory) -* [extension\_metadata](./rules/lib/builtins/extension_metadata) -* [FeatureConfiguration](./rules/lib/builtins/FeatureConfiguration) -* [File](./rules/lib/builtins/File) -* [fragments](./rules/lib/builtins/fragments) -* [java\_annotation\_processing](./rules/lib/builtins/java_annotation_processing) -* [Label](./rules/lib/builtins/Label) -* [LateBoundDefault](./rules/lib/builtins/LateBoundDefault) -* [LibraryToLink](./rules/lib/builtins/LibraryToLink) -* [License](./rules/lib/builtins/License) -* [LinkerInput](./rules/lib/builtins/LinkerInput) -* [LinkingContext](./rules/lib/builtins/LinkingContext) -* [macro](./rules/lib/builtins/macro) -* [mapped\_root](./rules/lib/builtins/mapped_root) -* [module\_ctx](./rules/lib/builtins/module_ctx) -* [path](./rules/lib/builtins/path) -* [propagation\_ctx](./rules/lib/builtins/propagation_ctx) -* [Provider](./rules/lib/builtins/Provider) -* [repo\_metadata](./rules/lib/builtins/repo_metadata) -* [repository\_ctx](./rules/lib/builtins/repository_ctx) -* [repository\_os](./rules/lib/builtins/repository_os) -* [repository\_rule](./rules/lib/builtins/repository_rule) -* [root](./rules/lib/builtins/root) -* [rule](./rules/lib/builtins/rule) -* [rule\_attributes](./rules/lib/builtins/rule_attributes) -* [runfiles](./rules/lib/builtins/runfiles) -* [struct](./rules/lib/builtins/struct) -* [Subrule](./rules/lib/builtins/Subrule) -* [subrule\_ctx](./rules/lib/builtins/subrule_ctx) -* [SymlinkEntry](./rules/lib/builtins/SymlinkEntry) -* [tag\_class](./rules/lib/builtins/tag_class) -* [Target](./rules/lib/builtins/Target) -* [template\_ctx](./rules/lib/builtins/template_ctx) -* [TemplateDict](./rules/lib/builtins/TemplateDict) -* [toolchain\_type](./rules/lib/builtins/toolchain_type) -* [ToolchainContext](./rules/lib/builtins/ToolchainContext) -* [transition](./rules/lib/builtins/transition) -* [wasm\_exec\_result](./rules/lib/builtins/wasm_exec_result) -* [wasm\_module](./rules/lib/builtins/wasm_module) +## [Built-in Types](/rules/lib/builtins) -## [Top-level Modules](./rules/lib/toplevel) +- [Action](/rules/lib/builtins/Action) +- [actions](/rules/lib/builtins/actions) +- [apple\_platform](/rules/lib/builtins/apple_platform) +- [Args](/rules/lib/builtins/Args) +- [Aspect](/rules/lib/builtins/Aspect) +- [Attribute](/rules/lib/builtins/Attribute) +- [bazel\_module](/rules/lib/builtins/bazel_module) +- [bazel\_module\_tags](/rules/lib/builtins/bazel_module_tags) +- [BuildSetting](/rules/lib/builtins/BuildSetting) +- [CcCompilationOutputs](/rules/lib/builtins/CcCompilationOutputs) +- [CcLinkingOutputs](/rules/lib/builtins/CcLinkingOutputs) +- [CompilationContext](/rules/lib/builtins/CompilationContext) +- [configuration](/rules/lib/builtins/configuration) +- [ctx](/rules/lib/builtins/ctx) +- [depset](/rules/lib/builtins/depset) +- [DirectoryExpander](/rules/lib/builtins/DirectoryExpander) +- [DottedVersion](/rules/lib/builtins/DottedVersion) +- [exec\_result](/rules/lib/builtins/exec_result) +- [ExecGroupCollection](/rules/lib/builtins/ExecGroupCollection) +- [ExecGroupContext](/rules/lib/builtins/ExecGroupContext) +- [ExecTransitionFactory](/rules/lib/builtins/ExecTransitionFactory) +- [ExpandedDirectory](/rules/lib/builtins/ExpandedDirectory) +- [extension\_metadata](/rules/lib/builtins/extension_metadata) +- [FeatureConfiguration](/rules/lib/builtins/FeatureConfiguration) +- [File](/rules/lib/builtins/File) +- [fragments](/rules/lib/builtins/fragments) +- [java\_annotation\_processing](/rules/lib/builtins/java_annotation_processing) +- [Label](/rules/lib/builtins/Label) +- [LateBoundDefault](/rules/lib/builtins/LateBoundDefault) +- [LibraryToLink](/rules/lib/builtins/LibraryToLink) +- [License](/rules/lib/builtins/License) +- [LinkerInput](/rules/lib/builtins/LinkerInput) +- [LinkingContext](/rules/lib/builtins/LinkingContext) +- [macro](/rules/lib/builtins/macro) +- [mapped\_root](/rules/lib/builtins/mapped_root) +- [module\_ctx](/rules/lib/builtins/module_ctx) +- [path](/rules/lib/builtins/path) +- [propagation\_ctx](/rules/lib/builtins/propagation_ctx) +- [Provider](/rules/lib/builtins/Provider) +- [repo\_metadata](/rules/lib/builtins/repo_metadata) +- [repository\_ctx](/rules/lib/builtins/repository_ctx) +- [repository\_os](/rules/lib/builtins/repository_os) +- [repository\_rule](/rules/lib/builtins/repository_rule) +- [root](/rules/lib/builtins/root) +- [rule](/rules/lib/builtins/rule) +- [rule\_attributes](/rules/lib/builtins/rule_attributes) +- [runfiles](/rules/lib/builtins/runfiles) +- [struct](/rules/lib/builtins/struct) +- [Subrule](/rules/lib/builtins/Subrule) +- [subrule\_ctx](/rules/lib/builtins/subrule_ctx) +- [SymlinkEntry](/rules/lib/builtins/SymlinkEntry) +- [tag\_class](/rules/lib/builtins/tag_class) +- [Target](/rules/lib/builtins/Target) +- [template\_ctx](/rules/lib/builtins/template_ctx) +- [TemplateDict](/rules/lib/builtins/TemplateDict) +- [toolchain\_type](/rules/lib/builtins/toolchain_type) +- [ToolchainContext](/rules/lib/builtins/ToolchainContext) +- [transition](/rules/lib/builtins/transition) +- [wasm\_exec\_result](/rules/lib/builtins/wasm_exec_result) +- [wasm\_module](/rules/lib/builtins/wasm_module) -* [apple\_common](./rules/lib/toplevel/apple_common) -* [attr](./rules/lib/toplevel/attr) -* [cc\_common](./rules/lib/toplevel/cc_common) -* [config](./rules/lib/toplevel/config) -* [config\_common](./rules/lib/toplevel/config_common) -* [coverage\_common](./rules/lib/toplevel/coverage_common) -* [java\_common](./rules/lib/toplevel/java_common) -* [native](./rules/lib/toplevel/native) -* [platform\_common](./rules/lib/toplevel/platform_common) -* [proto](./rules/lib/toplevel/proto) -* [testing](./rules/lib/toplevel/testing) +## [Top-level Modules](/rules/lib/toplevel) -## [Core Starlark data types](./rules/lib/core) +- [apple\_common](/rules/lib/toplevel/apple_common) +- [attr](/rules/lib/toplevel/attr) +- [cc\_common](/rules/lib/toplevel/cc_common) +- [config](/rules/lib/toplevel/config) +- [config\_common](/rules/lib/toplevel/config_common) +- [coverage\_common](/rules/lib/toplevel/coverage_common) +- [java\_common](/rules/lib/toplevel/java_common) +- [native](/rules/lib/toplevel/native) +- [platform\_common](/rules/lib/toplevel/platform_common) +- [proto](/rules/lib/toplevel/proto) +- [testing](/rules/lib/toplevel/testing) -* [bool](./rules/lib/core/bool) -* [builtin\_function\_or\_method](./rules/lib/core/builtin_function_or_method) -* [dict](./rules/lib/core/dict) -* [float](./rules/lib/core/float) -* [function](./rules/lib/core/function) -* [int](./rules/lib/core/int) -* [json](./rules/lib/core/json) -* [list](./rules/lib/core/list) -* [range](./rules/lib/core/range) -* [set](./rules/lib/core/set) -* [string](./rules/lib/core/string) -* [tuple](./rules/lib/core/tuple) \ No newline at end of file +## [Core Starlark data types](/rules/lib/core) + +- [bool](/rules/lib/core/bool) +- [builtin\_function\_or\_method](/rules/lib/core/builtin_function_or_method) +- [dict](/rules/lib/core/dict) +- [float](/rules/lib/core/float) +- [function](/rules/lib/core/function) +- [int](/rules/lib/core/int) +- [json](/rules/lib/core/json) +- [list](/rules/lib/core/list) +- [range](/rules/lib/core/range) +- [set](/rules/lib/core/set) +- [string](/rules/lib/core/string) +- [tuple](/rules/lib/core/tuple) diff --git a/rules/lib/providers.mdx b/rules/lib/providers.mdx index 228eaf6..73a1b4c 100644 --- a/rules/lib/providers.mdx +++ b/rules/lib/providers.mdx @@ -1,35 +1,35 @@ --- -title: 'providers' +title: 'Providers' --- This section lists providers available on built-in rules. See the [Rules page](https://bazel.build/extending/rules#providers) for more on providers. These symbols are available only in .bzl files. -* [AnalysisTestResultInfo](./rules/lib/providers/AnalysisTestResultInfo) -* [CcInfo](./rules/lib/providers/CcInfo) -* [CcToolchainConfigInfo](./rules/lib/providers/CcToolchainConfigInfo) -* [CcToolchainInfo](./rules/lib/providers/CcToolchainInfo) -* [ConstraintCollection](./rules/lib/providers/ConstraintCollection) -* [ConstraintSettingInfo](./rules/lib/providers/ConstraintSettingInfo) -* [ConstraintValueInfo](./rules/lib/providers/ConstraintValueInfo) -* [DebugPackageInfo](./rules/lib/providers/DebugPackageInfo) -* [DefaultInfo](./rules/lib/providers/DefaultInfo) -* [ExecutionInfo](./rules/lib/providers/ExecutionInfo) -* [FeatureFlagInfo](./rules/lib/providers/FeatureFlagInfo) -* [file\_provider](./rules/lib/providers/file_provider) -* [FilesToRunProvider](./rules/lib/providers/FilesToRunProvider) -* [IncompatiblePlatformProvider](./rules/lib/providers/IncompatiblePlatformProvider) -* [InstrumentedFilesInfo](./rules/lib/providers/InstrumentedFilesInfo) -* [java\_compilation\_info](./rules/lib/providers/java_compilation_info) -* [java\_output\_jars](./rules/lib/providers/java_output_jars) -* [JavaRuntimeInfo](./rules/lib/providers/JavaRuntimeInfo) -* [JavaToolchainInfo](./rules/lib/providers/JavaToolchainInfo) -* [MaterializedDepsInfo](./rules/lib/providers/MaterializedDepsInfo) -* [ObjcProvider](./rules/lib/providers/ObjcProvider) -* [OutputGroupInfo](./rules/lib/providers/OutputGroupInfo) -* [PackageSpecificationInfo](./rules/lib/providers/PackageSpecificationInfo) -* [PlatformInfo](./rules/lib/providers/PlatformInfo) -* [RunEnvironmentInfo](./rules/lib/providers/RunEnvironmentInfo) -* [TemplateVariableInfo](./rules/lib/providers/TemplateVariableInfo) -* [ToolchainInfo](./rules/lib/providers/ToolchainInfo) -* [ToolchainTypeInfo](./rules/lib/providers/ToolchainTypeInfo) \ No newline at end of file +- [AnalysisTestResultInfo](/rules/lib/providers/AnalysisTestResultInfo) +- [CcInfo](/rules/lib/providers/CcInfo) +- [CcToolchainConfigInfo](/rules/lib/providers/CcToolchainConfigInfo) +- [CcToolchainInfo](/rules/lib/providers/CcToolchainInfo) +- [ConstraintCollection](/rules/lib/providers/ConstraintCollection) +- [ConstraintSettingInfo](/rules/lib/providers/ConstraintSettingInfo) +- [ConstraintValueInfo](/rules/lib/providers/ConstraintValueInfo) +- [DebugPackageInfo](/rules/lib/providers/DebugPackageInfo) +- [DefaultInfo](/rules/lib/providers/DefaultInfo) +- [ExecutionInfo](/rules/lib/providers/ExecutionInfo) +- [FeatureFlagInfo](/rules/lib/providers/FeatureFlagInfo) +- [file\_provider](/rules/lib/providers/file_provider) +- [FilesToRunProvider](/rules/lib/providers/FilesToRunProvider) +- [IncompatiblePlatformProvider](/rules/lib/providers/IncompatiblePlatformProvider) +- [InstrumentedFilesInfo](/rules/lib/providers/InstrumentedFilesInfo) +- [java\_compilation\_info](/rules/lib/providers/java_compilation_info) +- [java\_output\_jars](/rules/lib/providers/java_output_jars) +- [JavaRuntimeInfo](/rules/lib/providers/JavaRuntimeInfo) +- [JavaToolchainInfo](/rules/lib/providers/JavaToolchainInfo) +- [MaterializedDepsInfo](/rules/lib/providers/MaterializedDepsInfo) +- [ObjcProvider](/rules/lib/providers/ObjcProvider) +- [OutputGroupInfo](/rules/lib/providers/OutputGroupInfo) +- [PackageSpecificationInfo](/rules/lib/providers/PackageSpecificationInfo) +- [PlatformInfo](/rules/lib/providers/PlatformInfo) +- [RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo) +- [TemplateVariableInfo](/rules/lib/providers/TemplateVariableInfo) +- [ToolchainInfo](/rules/lib/providers/ToolchainInfo) +- [ToolchainTypeInfo](/rules/lib/providers/ToolchainTypeInfo) diff --git a/rules/lib/providers/AnalysisTestResultInfo.mdx b/rules/lib/providers/AnalysisTestResultInfo.mdx index ccd82c6..3752f9d 100644 --- a/rules/lib/providers/AnalysisTestResultInfo.mdx +++ b/rules/lib/providers/AnalysisTestResultInfo.mdx @@ -3,13 +3,14 @@ title: 'AnalysisTestResultInfo' --- + Encapsulates the result of analyis-phase testing. Build targets which return an instance of this provider signal to the build system that it should generate a 'stub' test executable which generates the equivalent test result. Analysis test rules (rules created with `analysis_test=True` **must** return an instance of this provider, and non-analysis-phase test rules **cannot** return this provider. ## Members -* [AnalysisTestResultInfo](#AnalysisTestResultInfo) -* [message](#message) -* [success](#success) +- [AnalysisTestResultInfo](#AnalysisTestResultInfo) +- [message](#message) +- [success](#success) ## AnalysisTestResultInfo @@ -17,14 +18,20 @@ Encapsulates the result of analyis-phase testing. Build targets which return an AnalysisTestResultInfo AnalysisTestResultInfo(success, message) ``` -The `AnalysisTestResultInfo` constructor. + The `AnalysisTestResultInfo` constructor. + ### Parameters -| Parameter | Description | -| --- | --- | -| `success` | [bool](../core/bool.mdx); required If true, then the analysis-phase test represented by this target should pass. If false, the test should fail. | -| `message` | [string](../core/string.mdx); required A descriptive message containing information about the test and its success/failure. | +ParameterDescription`success`[bool](../core/bool.html); + required + + If true, then the analysis-phase test represented by this target should pass. If false, the test should fail. + `message`[string](../core/string.html); + required + + A descriptive message containing information about the test and its success/failure. + ## message @@ -32,7 +39,9 @@ The `AnalysisTestResultInfo` constructor. string AnalysisTestResultInfo.message ``` -A descriptive message containing information about the test and its success/failure. + A descriptive message containing information about the test and its success/failure. + + ## success @@ -40,4 +49,4 @@ A descriptive message containing information about the test and its success/fail bool AnalysisTestResultInfo.success ``` -If true, then the analysis-phase test represented by this target passed. If false, the test failed. \ No newline at end of file + If true, then the analysis-phase test represented by this target passed. If false, the test failed. diff --git a/rules/lib/providers/CcInfo.mdx b/rules/lib/providers/CcInfo.mdx index 7067e5a..b3aefff 100644 --- a/rules/lib/providers/CcInfo.mdx +++ b/rules/lib/providers/CcInfo.mdx @@ -3,13 +3,14 @@ title: 'CcInfo' --- + A provider for compilation and linking of C++. This is also a marking provider telling C++ rules that they can depend on the rule with this provider. If it is not intended for the rule to be depended on by C++, the rule should wrap the CcInfo in some other provider. ## Members -* [CcInfo](#CcInfo) -* [compilation\_context](#compilation_context) -* [linking\_context](#linking_context) +- [CcInfo](#CcInfo) +- [compilation\_context](#compilation_context) +- [linking\_context](#linking_context) ## CcInfo @@ -17,15 +18,24 @@ A provider for compilation and linking of C++. This is also a marking provider t CcInfo CcInfo(*, compilation_context=None, linking_context=None, debug_context=None) ``` -The `CcInfo` constructor. + The `CcInfo` constructor. + ### Parameters -| Parameter | Description | -| --- | --- | -| `compilation_context` | [CompilationContext](../builtins/CompilationContext.mdx); or `None`; default is `None` The `CompilationContext`. | -| `linking_context` | [struct](../builtins/struct.mdx); or `None`; default is `None` The `LinkingContext`. | -| `debug_context` | [struct](../builtins/struct.mdx); or `None`; default is `None` The `DebugContext`. | +ParameterDescription`compilation_context`[CompilationContext](../builtins/CompilationContext.html); or `None`; + default is `None` + + The `CompilationContext`. + `linking_context`[struct](../builtins/struct.html); or `None`; + default is `None` + + The `LinkingContext`. + `debug_context`[struct](../builtins/struct.html); or `None`; + default is `None` + + The `DebugContext`. + ## compilation\_context @@ -33,7 +43,7 @@ The `CcInfo` constructor. CompilationContext CcInfo.compilation_context ``` -Returns the `CompilationContext` + Returns the `CompilationContext` ## linking\_context @@ -41,4 +51,4 @@ Returns the `CompilationContext` struct CcInfo.linking_context ``` -Returns the `LinkingContext` \ No newline at end of file + Returns the `LinkingContext` diff --git a/rules/lib/providers/CcToolchainConfigInfo.mdx b/rules/lib/providers/CcToolchainConfigInfo.mdx index fe5e9c2..c792657 100644 --- a/rules/lib/providers/CcToolchainConfigInfo.mdx +++ b/rules/lib/providers/CcToolchainConfigInfo.mdx @@ -3,4 +3,5 @@ title: 'CcToolchainConfigInfo' --- -Additional layer of configurability for C++ rules. Encapsulates platform-dependent specifics of C++ actions through features and action configs. It is used to configure the C++ toolchain, and later on for command line construction. Replaces the functionality of CROSSTOOL file. \ No newline at end of file + +Additional layer of configurability for C++ rules. Encapsulates platform-dependent specifics of C++ actions through features and action configs. It is used to configure the C++ toolchain, and later on for command line construction. Replaces the functionality of CROSSTOOL file. diff --git a/rules/lib/providers/CcToolchainInfo.mdx b/rules/lib/providers/CcToolchainInfo.mdx index 34452d8..5b3a05b 100644 --- a/rules/lib/providers/CcToolchainInfo.mdx +++ b/rules/lib/providers/CcToolchainInfo.mdx @@ -3,29 +3,30 @@ title: 'CcToolchainInfo' --- + Information about the C++ compiler being used. ## Members -* [all\_files](#all_files) -* [ar\_executable](#ar_executable) -* [built\_in\_include\_directories](#built_in_include_directories) -* [compiler](#compiler) -* [compiler\_executable](#compiler_executable) -* [cpu](#cpu) -* [dynamic\_runtime\_lib](#dynamic_runtime_lib) -* [gcov\_executable](#gcov_executable) -* [ld\_executable](#ld_executable) -* [libc](#libc) -* [needs\_pic\_for\_dynamic\_libraries](#needs_pic_for_dynamic_libraries) -* [nm\_executable](#nm_executable) -* [objcopy\_executable](#objcopy_executable) -* [objdump\_executable](#objdump_executable) -* [preprocessor\_executable](#preprocessor_executable) -* [static\_runtime\_lib](#static_runtime_lib) -* [strip\_executable](#strip_executable) -* [sysroot](#sysroot) -* [target\_gnu\_system\_name](#target_gnu_system_name) +- [all\_files](#all_files) +- [ar\_executable](#ar_executable) +- [built\_in\_include\_directories](#built_in_include_directories) +- [compiler](#compiler) +- [compiler\_executable](#compiler_executable) +- [cpu](#cpu) +- [dynamic\_runtime\_lib](#dynamic_runtime_lib) +- [gcov\_executable](#gcov_executable) +- [ld\_executable](#ld_executable) +- [libc](#libc) +- [needs\_pic\_for\_dynamic\_libraries](#needs_pic_for_dynamic_libraries) +- [nm\_executable](#nm_executable) +- [objcopy\_executable](#objcopy_executable) +- [objdump\_executable](#objdump_executable) +- [preprocessor\_executable](#preprocessor_executable) +- [static\_runtime\_lib](#static_runtime_lib) +- [strip\_executable](#strip_executable) +- [sysroot](#sysroot) +- [target\_gnu\_system\_name](#target_gnu_system_name) ## all\_files @@ -33,7 +34,9 @@ Information about the C++ compiler being used. None CcToolchainInfo.all_files ``` -Returns all toolchain files (so they can be passed to actions using this toolchain as inputs). + Returns all toolchain files (so they can be passed to actions using this toolchain as inputs). + + ## ar\_executable @@ -41,7 +44,9 @@ Returns all toolchain files (so they can be passed to actions using this toolcha None CcToolchainInfo.ar_executable ``` -The path to the ar binary. + The path to the ar binary. + + ## built\_in\_include\_directories @@ -49,7 +54,9 @@ The path to the ar binary. None CcToolchainInfo.built_in_include_directories ``` -Returns the list of built-in directories of the compiler. + Returns the list of built-in directories of the compiler. + + ## compiler @@ -57,7 +64,9 @@ Returns the list of built-in directories of the compiler. None CcToolchainInfo.compiler ``` -C++ compiler. + C++ compiler. + + ## compiler\_executable @@ -65,7 +74,9 @@ C++ compiler. None CcToolchainInfo.compiler_executable ``` -The path to the compiler binary. + The path to the compiler binary. + + ## cpu @@ -73,7 +84,9 @@ The path to the compiler binary. None CcToolchainInfo.cpu ``` -Target CPU of the C++ toolchain. + Target CPU of the C++ toolchain. + + ## dynamic\_runtime\_lib @@ -81,13 +94,16 @@ Target CPU of the C++ toolchain. None CcToolchainInfo.dynamic_runtime_lib(*, feature_configuration) ``` -Returns the files from `dynamic\_runtime\_lib` attribute (so they can be passed to actions using this toolchain as inputs). The caller can check whether the feature\_configuration enables `static\_link\_cpp\_runtimes` feature (if not, neither `static\_runtime\_lib` nor `dynamic\_runtime\_lib` have to be used), and use `static\_runtime\_lib` if static linking mode is active. + Returns the files from \`dynamic\_runtime\_lib\` attribute (so they can be passed to actions using this toolchain as inputs). The caller can check whether the feature\_configuration enables \`static\_link\_cpp\_runtimes\` feature (if not, neither \`static\_runtime\_lib\` nor \`dynamic\_runtime\_lib\` have to be used), and use \`static\_runtime\_lib\` if static linking mode is active. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | required Feature configuration to be queried. | +ParameterDescription`feature_configuration` + required + + Feature configuration to be queried. + ## gcov\_executable @@ -95,7 +111,9 @@ Returns the files from `dynamic\_runtime\_lib` attribute (so they can be passed None CcToolchainInfo.gcov_executable ``` -The path to the gcov binary. + The path to the gcov binary. + + ## ld\_executable @@ -103,7 +121,9 @@ The path to the gcov binary. None CcToolchainInfo.ld_executable ``` -The path to the ld binary. + The path to the ld binary. + + ## libc @@ -111,7 +131,9 @@ The path to the ld binary. None CcToolchainInfo.libc ``` -libc version string. + libc version string. + + ## needs\_pic\_for\_dynamic\_libraries @@ -119,13 +141,16 @@ libc version string. None CcToolchainInfo.needs_pic_for_dynamic_libraries(*, feature_configuration) ``` -Returns true if this rule's compilations should apply -fPIC, false otherwise. Determines if we should apply -fPIC for this rule's C++ compilations depending on the C++ toolchain and presence of `--force\_pic` Bazel option. + Returns true if this rule's compilations should apply -fPIC, false otherwise. Determines if we should apply -fPIC for this rule's C++ compilations depending on the C++ toolchain and presence of \`--force\_pic\` Bazel option. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | required Feature configuration to be queried. | +ParameterDescription`feature_configuration` + required + + Feature configuration to be queried. + ## nm\_executable @@ -133,7 +158,9 @@ Returns true if this rule's compilations should apply -fPIC, false otherwise. De None CcToolchainInfo.nm_executable ``` -The path to the nm binary. + The path to the nm binary. + + ## objcopy\_executable @@ -141,7 +168,9 @@ The path to the nm binary. None CcToolchainInfo.objcopy_executable ``` -The path to the objcopy binary. + The path to the objcopy binary. + + ## objdump\_executable @@ -149,7 +178,9 @@ The path to the objcopy binary. None CcToolchainInfo.objdump_executable ``` -The path to the objdump binary. + The path to the objdump binary. + + ## preprocessor\_executable @@ -157,7 +188,9 @@ The path to the objdump binary. None CcToolchainInfo.preprocessor_executable ``` -The path to the preprocessor binary. + The path to the preprocessor binary. + + ## static\_runtime\_lib @@ -165,13 +198,16 @@ The path to the preprocessor binary. None CcToolchainInfo.static_runtime_lib(*, feature_configuration) ``` -Returns the files from `static\_runtime\_lib` attribute (so they can be passed to actions using this toolchain as inputs). The caller should check whether the feature\_configuration enables `static\_link\_cpp\_runtimes` feature (if not, neither `static\_runtime\_lib` nor `dynamic\_runtime\_lib` should be used), and use `dynamic\_runtime\_lib` if dynamic linking mode is active. + Returns the files from \`static\_runtime\_lib\` attribute (so they can be passed to actions using this toolchain as inputs). The caller should check whether the feature\_configuration enables \`static\_link\_cpp\_runtimes\` feature (if not, neither \`static\_runtime\_lib\` nor \`dynamic\_runtime\_lib\` should be used), and use \`dynamic\_runtime\_lib\` if dynamic linking mode is active. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | required Feature configuration to be queried. | +ParameterDescription`feature_configuration` + required + + Feature configuration to be queried. + ## strip\_executable @@ -179,7 +215,9 @@ Returns the files from `static\_runtime\_lib` attribute (so they can be passed t None CcToolchainInfo.strip_executable ``` -The path to the strip binary. + The path to the strip binary. + + ## sysroot @@ -187,7 +225,9 @@ The path to the strip binary. None CcToolchainInfo.sysroot ``` -Returns the sysroot to be used. If the toolchain compiler does not support different sysroots, or the sysroot is the same as the default sysroot, then this method returns `None`. + Returns the sysroot to be used. If the toolchain compiler does not support different sysroots, or the sysroot is the same as the default sysroot, then this method returns `None`. + + ## target\_gnu\_system\_name @@ -195,4 +235,4 @@ Returns the sysroot to be used. If the toolchain compiler does not support diffe None CcToolchainInfo.target_gnu_system_name ``` -The GNU System Name. \ No newline at end of file + The GNU System Name. diff --git a/rules/lib/providers/ConstraintCollection.mdx b/rules/lib/providers/ConstraintCollection.mdx index 01eecb9..40e1485 100644 --- a/rules/lib/providers/ConstraintCollection.mdx +++ b/rules/lib/providers/ConstraintCollection.mdx @@ -3,5 +3,7 @@ title: 'ConstraintCollection' --- -Provides access to data about a collection of ConstraintValueInfo providers. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* \ No newline at end of file + +Provides access to data about a collection of ConstraintValueInfo providers. + +_Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`_ diff --git a/rules/lib/providers/ConstraintSettingInfo.mdx b/rules/lib/providers/ConstraintSettingInfo.mdx index df75d99..b48dc40 100644 --- a/rules/lib/providers/ConstraintSettingInfo.mdx +++ b/rules/lib/providers/ConstraintSettingInfo.mdx @@ -3,12 +3,14 @@ title: 'ConstraintSettingInfo' --- -A specific constraint setting that may be used to define a platform. See [Defining Constraints and Platforms](./docs/platforms#constraints-platforms) for more information. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* + +A specific constraint setting that may be used to define a platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. + +_Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`_ ## Members -* [has\_default\_constraint\_value](#has_default_constraint_value) +- [has\_default\_constraint\_value](#has_default_constraint_value) ## has\_default\_constraint\_value @@ -16,4 +18,4 @@ A specific constraint setting that may be used to define a platform. See [Defini bool ConstraintSettingInfo.has_default_constraint_value ``` -Whether there is a default constraint\_value for this setting. \ No newline at end of file + Whether there is a default constraint\_value for this setting. diff --git a/rules/lib/providers/ConstraintValueInfo.mdx b/rules/lib/providers/ConstraintValueInfo.mdx index fc5ffc3..dbb9ab1 100644 --- a/rules/lib/providers/ConstraintValueInfo.mdx +++ b/rules/lib/providers/ConstraintValueInfo.mdx @@ -3,5 +3,7 @@ title: 'ConstraintValueInfo' --- -A value for a constraint setting that can be used to define a platform. See [Defining Constraints and Platforms](./docs/platforms#constraints-platforms) for more information. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* \ No newline at end of file + +A value for a constraint setting that can be used to define a platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. + +_Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`_ diff --git a/rules/lib/providers/DebugPackageInfo.mdx b/rules/lib/providers/DebugPackageInfo.mdx index 576e4c0..7955cb9 100644 --- a/rules/lib/providers/DebugPackageInfo.mdx +++ b/rules/lib/providers/DebugPackageInfo.mdx @@ -3,15 +3,16 @@ title: 'DebugPackageInfo' --- -A provider for the binary file and its associated .dwp files, if fission is enabled.If Fission (\{@url https://gcc.gnu.org/wiki/DebugFission\}) is not enabled, the dwp file will be null. + +A provider for the binary file and its associated .dwp files, if fission is enabled.If Fission ({@url https://gcc.gnu.org/wiki/DebugFission}) is not enabled, the dwp file will be null. ## Members -* [DebugPackageInfo](#DebugPackageInfo) -* [dwp\_file](#dwp_file) -* [stripped\_file](#stripped_file) -* [target\_label](#target_label) -* [unstripped\_file](#unstripped_file) +- [DebugPackageInfo](#DebugPackageInfo) +- [dwp\_file](#dwp_file) +- [stripped\_file](#stripped_file) +- [target\_label](#target_label) +- [unstripped\_file](#unstripped_file) ## DebugPackageInfo @@ -19,16 +20,28 @@ A provider for the binary file and its associated .dwp files, if fission is enab DebugPackageInfo DebugPackageInfo(*, target_label, stripped_file=None, unstripped_file, dwp_file=None) ``` -The `DebugPackageInfo` constructor. + The `DebugPackageInfo` constructor. + ### Parameters -| Parameter | Description | -| --- | --- | -| `target_label` | [Label](../builtins/Label.mdx); required The label for the \*\_binary target | -| `stripped_file` | [File](../builtins/File.mdx); or `None`; default is `None` The stripped file (the explicit ".stripped" target) | -| `unstripped_file` | [File](../builtins/File.mdx); required The unstripped file (the default executable target). | -| `dwp_file` | [File](../builtins/File.mdx); or `None`; default is `None` The .dwp file (for fission builds) or null if --fission=no. | +ParameterDescription`target_label`[Label](../builtins/Label.html); + required + + The label for the \*\_binary target + `stripped_file`[File](../builtins/File.html); or `None`; + default is `None` + + The stripped file (the explicit ".stripped" target) + `unstripped_file`[File](../builtins/File.html); + required + + The unstripped file (the default executable target). + `dwp_file`[File](../builtins/File.html); or `None`; + default is `None` + + The .dwp file (for fission builds) or null if --fission=no. + ## dwp\_file @@ -36,8 +49,10 @@ The `DebugPackageInfo` constructor. File DebugPackageInfo.dwp_file ``` -Returns the .dwp file (for fission builds) or null if --fission=no. -May return `None`. + Returns the .dwp file (for fission builds) or null if --fission=no. + May return `None`. + + ## stripped\_file @@ -45,8 +60,10 @@ May return `None`. File DebugPackageInfo.stripped_file ``` -Returns the stripped file (the explicit ".stripped" target). -May return `None`. + Returns the stripped file (the explicit ".stripped" target). + May return `None`. + + ## target\_label @@ -54,7 +71,9 @@ May return `None`. Label DebugPackageInfo.target_label ``` -Returns the label for the \*\_binary target + Returns the label for the \*\_binary target + + ## unstripped\_file @@ -62,4 +81,4 @@ Returns the label for the \*\_binary target File DebugPackageInfo.unstripped_file ``` -Returns the unstripped file (the default executable target) \ No newline at end of file + Returns the unstripped file (the default executable target) diff --git a/rules/lib/providers/DefaultInfo.mdx b/rules/lib/providers/DefaultInfo.mdx index 99c287a..04378da 100644 --- a/rules/lib/providers/DefaultInfo.mdx +++ b/rules/lib/providers/DefaultInfo.mdx @@ -3,17 +3,18 @@ title: 'DefaultInfo' --- + A provider that gives general information about a target's direct and transitive files. Every rule type has this provider, even if it is not returned explicitly by the rule's implementation function. See the [rules](https://bazel.build/extending/rules) page for extensive guides on how to use this provider. ## Members -* [DefaultInfo](#DefaultInfo) -* [data\_runfiles](#data_runfiles) -* [default\_runfiles](#default_runfiles) -* [files](#files) -* [files\_to\_run](#files_to_run) +- [DefaultInfo](#DefaultInfo) +- [data\_runfiles](#data_runfiles) +- [default\_runfiles](#default_runfiles) +- [files](#files) +- [files\_to\_run](#files_to_run) ## DefaultInfo @@ -21,17 +22,37 @@ See the [rules](https://bazel.build/extending/rules) page for extensive guides o DefaultInfo DefaultInfo(*, files=None, runfiles=None, data_runfiles=None, default_runfiles=None, executable=None) ``` -The `DefaultInfo` constructor. + The `DefaultInfo` constructor. + ### Parameters -| Parameter | Description | -| --- | --- | -| `files` | [depset](../builtins/depset.mdx); or `None`; default is `None` A [`depset`](../builtins/depset.mdx) of [`File`](../builtins/File.mdx) objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. | -| `runfiles` | [runfiles](../builtins/runfiles.mdx); or `None`; default is `None` [`runfiles`](../builtins/runfiles.mdx) descriptor describing the files that this target needs when run (e.g. via the `run` command or as a tool dependency for an action). | -| `data_runfiles` | [runfiles](../builtins/runfiles.mdx); or `None`; default is `None` **It is recommended that you avoid using this parameter (see ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid))** runfiles descriptor describing the runfiles this target needs to run when it is a dependency via the `data` attribute. | -| `default_runfiles` | [runfiles](../builtins/runfiles.mdx); or `None`; default is `None` **It is recommended that you avoid using this parameter (see ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid))** runfiles descriptor describing the runfiles this target needs to run when it is a dependency via any attribute other than the `data` attribute. | -| `executable` | [File](../builtins/File.mdx); or `None`; default is `None` If this rule is marked [`executable`](../globals/bzl.html#rule.executable) or [`test`](../globals/bzl.html#rule.test), this is a [`File`](../builtins/File.mdx) object representing the file that should be executed to run the target. By default it is the predeclared output `ctx.outputs.executable` but it is recommended to pass another file (either predeclared or not) explicitly. | +ParameterDescription`files`[depset](../builtins/depset.html); or `None`; + default is `None` + + A [`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. + `runfiles`[runfiles](../builtins/runfiles.html); or `None`; + default is `None` + +[`runfiles`](../builtins/runfiles.html) descriptor describing the files that this target needs when run (e.g. via the `run` command or as a tool dependency for an action). + + `data_runfiles`[runfiles](../builtins/runfiles.html); or `None`; + default is `None` + +**It is recommended that you avoid using this parameter (see ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid))** + + runfiles descriptor describing the runfiles this target needs to run when it is a dependency via the `data` attribute. + `default_runfiles`[runfiles](../builtins/runfiles.html); or `None`; + default is `None` + +**It is recommended that you avoid using this parameter (see ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid))** + + runfiles descriptor describing the runfiles this target needs to run when it is a dependency via any attribute other than the `data` attribute. + `executable`[File](../builtins/File.html); or `None`; + default is `None` + + If this rule is marked [`executable`](../globals/bzl.html#rule.executable) or [`test`](../globals/bzl.html#rule.test), this is a [`File`](../builtins/File.html) object representing the file that should be executed to run the target. By default it is the predeclared output `ctx.outputs.executable` but it is recommended to pass another file (either predeclared or not) explicitly. + ## data\_runfiles @@ -39,8 +60,10 @@ The `DefaultInfo` constructor. runfiles DefaultInfo.data_runfiles ``` -runfiles descriptor describing the files that this target needs when run in the condition that it is a `data` dependency attribute. Under most circumstances, use the `default_runfiles` parameter instead. See ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid) for details. -May return `None`. + runfiles descriptor describing the files that this target needs when run in the condition that it is a `data` dependency attribute. Under most circumstances, use the `default_runfiles` parameter instead. See ["runfiles features to avoid"](https://bazel.build/extending/rules#runfiles_features_to_avoid) for details. + May return `None`. + + ## default\_runfiles @@ -48,8 +71,10 @@ May return `None`. runfiles DefaultInfo.default_runfiles ``` -runfiles descriptor describing the files that this target needs when run (via the `run` command or as a tool dependency). -May return `None`. + runfiles descriptor describing the files that this target needs when run (via the `run` command or as a tool dependency). + May return `None`. + + ## files @@ -57,8 +82,10 @@ May return `None`. depset DefaultInfo.files ``` -A [`depset`](../builtins/depset.mdx) of [`File`](../builtins/File.mdx) objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. -May return `None`. + A [`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing the default outputs to build when this target is specified on the bazel command line. By default it is all predeclared outputs. + May return `None`. + + ## files\_to\_run @@ -66,5 +93,5 @@ May return `None`. FilesToRunProvider DefaultInfo.files_to_run ``` -A [`FilesToRunProvider`](../providers/FilesToRunProvider.mdx) object containing information about the executable and runfiles of the target. -May return `None`. \ No newline at end of file + A [`FilesToRunProvider`](../providers/FilesToRunProvider.html) object containing information about the executable and runfiles of the target. + May return `None`. diff --git a/rules/lib/providers/ExecutionInfo.mdx b/rules/lib/providers/ExecutionInfo.mdx index 4f05a00..f390dae 100644 --- a/rules/lib/providers/ExecutionInfo.mdx +++ b/rules/lib/providers/ExecutionInfo.mdx @@ -3,28 +3,35 @@ title: 'ExecutionInfo' --- + Use this provider to specify special environment requirements needed to run tests. ## Members -* [ExecutionInfo](#ExecutionInfo) -* [exec\_group](#exec_group) -* [requirements](#requirements) +- [ExecutionInfo](#ExecutionInfo) +- [exec\_group](#exec_group) +- [requirements](#requirements) ## ExecutionInfo ``` -ExecutionInfo ExecutionInfo(requirements=\{\}, exec_group='test') +ExecutionInfo ExecutionInfo(requirements={}, exec_group='test') ``` -Creates an instance. + Creates an instance. + ### Parameters -| Parameter | Description | -| --- | --- | -| `requirements` | [dict](../core/dict.mdx); default is `\{\}` A dict indicating special execution requirements, such as hardware platforms. | -| `exec_group` | [string](../core/string.mdx); default is `'test'` The name of the exec group that is used to execute the test. | +ParameterDescription`requirements`[dict](../core/dict.html); + default is `{}` + + A dict indicating special execution requirements, such as hardware platforms. + `exec_group`[string](../core/string.html); + default is `'test'` + + The name of the exec group that is used to execute the test. + ## exec\_group @@ -32,7 +39,9 @@ Creates an instance. string ExecutionInfo.exec_group ``` -The name of the exec group that is used to execute the test. + The name of the exec group that is used to execute the test. + + ## requirements @@ -40,4 +49,4 @@ The name of the exec group that is used to execute the test. dict ExecutionInfo.requirements ``` -A dict indicating special execution requirements, such as hardware platforms. \ No newline at end of file + A dict indicating special execution requirements, such as hardware platforms. diff --git a/rules/lib/providers/FeatureFlagInfo.mdx b/rules/lib/providers/FeatureFlagInfo.mdx index 074c211..990e14c 100644 --- a/rules/lib/providers/FeatureFlagInfo.mdx +++ b/rules/lib/providers/FeatureFlagInfo.mdx @@ -3,13 +3,14 @@ title: 'FeatureFlagInfo' --- + A provider used to access information about config\_feature\_flag rules. ## Members -* [error](#error) -* [is\_valid\_value](#is_valid_value) -* [value](#value) +- [error](#error) +- [is\_valid\_value](#is_valid_value) +- [value](#value) ## error @@ -17,8 +18,10 @@ A provider used to access information about config\_feature\_flag rules. string FeatureFlagInfo.error ``` -If non-None, this error was generated when trying to compute current value of flag. -May return `None`. + If non-None, this error was generated when trying to compute current value of flag. + May return `None`. + + ## is\_valid\_value @@ -26,13 +29,16 @@ May return `None`. bool FeatureFlagInfo.is_valid_value(value) ``` -The value of the flag in the configuration used by the flag rule. + The value of the flag in the configuration used by the flag rule. + ### Parameters -| Parameter | Description | -| --- | --- | -| `value` | [string](../core/string.mdx); required String, the value to check for validity for this flag. | +ParameterDescription`value`[string](../core/string.html); + required + + String, the value to check for validity for this flag. + ## value @@ -40,5 +46,5 @@ The value of the flag in the configuration used by the flag rule. string FeatureFlagInfo.value ``` -The current value of the flag in the flag's current configuration. None if there is an error. -May return `None`. \ No newline at end of file + The current value of the flag in the flag's current configuration. None if there is an error. + May return `None`. diff --git a/rules/lib/providers/FilesToRunProvider.mdx b/rules/lib/providers/FilesToRunProvider.mdx index 1f57856..ae33b40 100644 --- a/rules/lib/providers/FilesToRunProvider.mdx +++ b/rules/lib/providers/FilesToRunProvider.mdx @@ -3,13 +3,14 @@ title: 'FilesToRunProvider' --- + Contains information about executables produced by a target and the files needed to run it. This provider can not be created directly, it is an implicit output of executable targets accessible via [`DefaultInfo.files_to_run`](../providers/DefaultInfo.html#files_to_run). ## Members -* [executable](#executable) -* [repo\_mapping\_manifest](#repo_mapping_manifest) -* [runfiles\_manifest](#runfiles_manifest) +- [executable](#executable) +- [repo\_mapping\_manifest](#repo_mapping_manifest) +- [runfiles\_manifest](#runfiles_manifest) ## executable @@ -17,8 +18,10 @@ Contains information about executables produced by a target and the files needed File FilesToRunProvider.executable ``` -The main executable or None if it does not exist. -May return `None`. + The main executable or None if it does not exist. + May return `None`. + + ## repo\_mapping\_manifest @@ -26,8 +29,10 @@ May return `None`. File FilesToRunProvider.repo_mapping_manifest ``` -The repo mapping manifest or None if it does not exist. -May return `None`. + The repo mapping manifest or None if it does not exist. + May return `None`. + + ## runfiles\_manifest @@ -35,5 +40,5 @@ May return `None`. File FilesToRunProvider.runfiles_manifest ``` -The runfiles manifest or None if it does not exist. -May return `None`. \ No newline at end of file + The runfiles manifest or None if it does not exist. + May return `None`. diff --git a/rules/lib/providers/IncompatiblePlatformProvider.mdx b/rules/lib/providers/IncompatiblePlatformProvider.mdx index 8c27379..e71c7e3 100644 --- a/rules/lib/providers/IncompatiblePlatformProvider.mdx +++ b/rules/lib/providers/IncompatiblePlatformProvider.mdx @@ -3,4 +3,5 @@ title: 'IncompatiblePlatformProvider' --- -A provider for targets that are incompatible with the target platform. See [Detecting incompatible targets using `bazel cquery`](./docs/platforms#detecting-incompatible-targets-using-bazel-cquery) for more information. \ No newline at end of file + +A provider for targets that are incompatible with the target platform. See [Detecting incompatible targets using `bazel cquery`](/docs/platforms#detecting-incompatible-targets-using-bazel-cquery) for more information. diff --git a/rules/lib/providers/InstrumentedFilesInfo.mdx b/rules/lib/providers/InstrumentedFilesInfo.mdx index 597a63b..88bd009 100644 --- a/rules/lib/providers/InstrumentedFilesInfo.mdx +++ b/rules/lib/providers/InstrumentedFilesInfo.mdx @@ -3,12 +3,13 @@ title: 'InstrumentedFilesInfo' --- + Contains information about source files and instrumentation metadata files for rule targets matched by [`--instrumentation_filter`](https://bazel.build/reference/command-line-reference#flag--instrumentation_filter) for purposes of [code coverage data collection](https://bazel.build/extending/rules#code_coverage). When coverage data collection is enabled, a manifest containing the combined paths in [`instrumented_files`](#instrumented_files) and [`metadata_files`](#metadata_files) are passed to the test action as inputs, with the manifest's path noted in the environment variable `COVERAGE_MANIFEST`. The metadata files, but not the source files, are also passed to the test action as inputs. When `InstrumentedFilesInfo` is returned by an [aspect](https://bazel.build/extending/aspects)'s implementation function, any `InstrumentedFilesInfo` from the base rule target is ignored. ## Members -* [instrumented\_files](#instrumented_files) -* [metadata\_files](#metadata_files) +- [instrumented\_files](#instrumented_files) +- [metadata\_files](#metadata_files) ## instrumented\_files @@ -16,7 +17,9 @@ Contains information about source files and instrumentation metadata files for r depset InstrumentedFilesInfo.instrumented_files ``` -[`depset`](../builtins/depset.mdx) of [`File`](../builtins/File.mdx) objects representing instrumented source files for this target and its dependencies. + [`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing instrumented source files for this target and its dependencies. + + ## metadata\_files @@ -24,4 +27,4 @@ depset InstrumentedFilesInfo.instrumented_files depset InstrumentedFilesInfo.metadata_files ``` -[`depset`](../builtins/depset.mdx) of [`File`](../builtins/File.mdx) objects representing coverage metadata files for this target and its dependencies. These files contain additional information required to generate LCOV-format coverage output after the code is executed, e.g. the `.gcno` files generated when `gcc` is run with `-ftest-coverage`. \ No newline at end of file + [`depset`](../builtins/depset.html) of [`File`](../builtins/File.html) objects representing coverage metadata files for this target and its dependencies. These files contain additional information required to generate LCOV-format coverage output after the code is executed, e.g. the `.gcno` files generated when `gcc` is run with `-ftest-coverage`. diff --git a/rules/lib/providers/JavaRuntimeInfo.mdx b/rules/lib/providers/JavaRuntimeInfo.mdx index f332acf..9db1822 100644 --- a/rules/lib/providers/JavaRuntimeInfo.mdx +++ b/rules/lib/providers/JavaRuntimeInfo.mdx @@ -3,21 +3,22 @@ title: 'JavaRuntimeInfo' --- + Information about the Java runtime being used. ## Members -* [default\_cds](#default_cds) -* [files](#files) -* [hermetic\_files](#hermetic_files) -* [hermetic\_static\_libs](#hermetic_static_libs) -* [java\_executable\_exec\_path](#java_executable_exec_path) -* [java\_executable\_runfiles\_path](#java_executable_runfiles_path) -* [java\_home](#java_home) -* [java\_home\_runfiles\_path](#java_home_runfiles_path) -* [lib\_ct\_sym](#lib_ct_sym) -* [lib\_modules](#lib_modules) -* [version](#version) +- [default\_cds](#default_cds) +- [files](#files) +- [hermetic\_files](#hermetic_files) +- [hermetic\_static\_libs](#hermetic_static_libs) +- [java\_executable\_exec\_path](#java_executable_exec_path) +- [java\_executable\_runfiles\_path](#java_executable_runfiles_path) +- [java\_home](#java_home) +- [java\_home\_runfiles\_path](#java_home_runfiles_path) +- [lib\_ct\_sym](#lib_ct_sym) +- [lib\_modules](#lib_modules) +- [version](#version) ## default\_cds @@ -25,8 +26,10 @@ Information about the Java runtime being used. File JavaRuntimeInfo.default_cds ``` -Returns the JDK default CDS archive. -May return `None`. + Returns the JDK default CDS archive. + May return `None`. + + ## files @@ -34,7 +37,9 @@ May return `None`. depset JavaRuntimeInfo.files ``` -Returns the files in the Java runtime. + Returns the files in the Java runtime. + + ## hermetic\_files @@ -42,7 +47,9 @@ Returns the files in the Java runtime. depset JavaRuntimeInfo.hermetic_files ``` -Returns the files in the Java runtime needed for hermetic deployments. + Returns the files in the Java runtime needed for hermetic deployments. + + ## hermetic\_static\_libs @@ -50,7 +57,9 @@ Returns the files in the Java runtime needed for hermetic deployments. sequence JavaRuntimeInfo.hermetic_static_libs ``` -Returns the JDK static libraries. + Returns the JDK static libraries. + + ## java\_executable\_exec\_path @@ -58,7 +67,9 @@ Returns the JDK static libraries. string JavaRuntimeInfo.java_executable_exec_path ``` -Returns the execpath of the Java executable. + Returns the execpath of the Java executable. + + ## java\_executable\_runfiles\_path @@ -66,7 +77,9 @@ Returns the execpath of the Java executable. string JavaRuntimeInfo.java_executable_runfiles_path ``` -Returns the path of the Java executable in runfiles trees. This should only be used when one needs to access the JVM during the execution of a binary or a test built by Bazel. In particular, when one needs to invoke the JVM during an action, java\_executable\_exec\_path should be used instead. + Returns the path of the Java executable in runfiles trees. This should only be used when one needs to access the JVM during the execution of a binary or a test built by Bazel. In particular, when one needs to invoke the JVM during an action, java\_executable\_exec\_path should be used instead. + + ## java\_home @@ -74,7 +87,9 @@ Returns the path of the Java executable in runfiles trees. This should only be u string JavaRuntimeInfo.java_home ``` -Returns the execpath of the root of the Java installation. + Returns the execpath of the root of the Java installation. + + ## java\_home\_runfiles\_path @@ -82,7 +97,9 @@ Returns the execpath of the root of the Java installation. string JavaRuntimeInfo.java_home_runfiles_path ``` -Returns the path of the Java installation in runfiles trees. This should only be used when one needs to access the JDK during the execution of a binary or a test built by Bazel. In particular, when one needs the JDK during an action, java\_home should be used instead. + Returns the path of the Java installation in runfiles trees. This should only be used when one needs to access the JDK during the execution of a binary or a test built by Bazel. In particular, when one needs the JDK during an action, java\_home should be used instead. + + ## lib\_ct\_sym @@ -90,8 +107,10 @@ Returns the path of the Java installation in runfiles trees. This should only be File JavaRuntimeInfo.lib_ct_sym ``` -Returns the lib/ct.sym file. -May return `None`. + Returns the lib/ct.sym file. + May return `None`. + + ## lib\_modules @@ -99,8 +118,10 @@ May return `None`. File JavaRuntimeInfo.lib_modules ``` -Returns the lib/modules file. -May return `None`. + Returns the lib/modules file. + May return `None`. + + ## version @@ -108,4 +129,4 @@ May return `None`. int JavaRuntimeInfo.version ``` -The Java feature version of the runtime. This is 0 if the version is unknown. \ No newline at end of file + The Java feature version of the runtime. This is 0 if the version is unknown. diff --git a/rules/lib/providers/JavaToolchainInfo.mdx b/rules/lib/providers/JavaToolchainInfo.mdx index b878ff1..f1b0c8c 100644 --- a/rules/lib/providers/JavaToolchainInfo.mdx +++ b/rules/lib/providers/JavaToolchainInfo.mdx @@ -3,21 +3,22 @@ title: 'JavaToolchainInfo' --- + Provides access to information about the Java toolchain rule. Accessible as a 'java\_toolchain' field on a Target struct. ## Members -* [bootclasspath](#bootclasspath) -* [ijar](#ijar) -* [jacocorunner](#jacocorunner) -* [java\_runtime](#java_runtime) -* [jvm\_opt](#jvm_opt) -* [label](#label) -* [proguard\_allowlister](#proguard_allowlister) -* [single\_jar](#single_jar) -* [source\_version](#source_version) -* [target\_version](#target_version) -* [tools](#tools) +- [bootclasspath](#bootclasspath) +- [ijar](#ijar) +- [jacocorunner](#jacocorunner) +- [java\_runtime](#java_runtime) +- [jvm\_opt](#jvm_opt) +- [label](#label) +- [proguard\_allowlister](#proguard_allowlister) +- [single\_jar](#single_jar) +- [source\_version](#source_version) +- [target\_version](#target_version) +- [tools](#tools) ## bootclasspath @@ -25,7 +26,9 @@ Provides access to information about the Java toolchain rule. Accessible as a 'j depset JavaToolchainInfo.bootclasspath ``` -The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. + The Java target bootclasspath entries. Corresponds to javac's -bootclasspath flag. + + ## ijar @@ -33,7 +36,9 @@ The Java target bootclasspath entries. Corresponds to javac's -bootclasspath fla FilesToRunProvider JavaToolchainInfo.ijar ``` -A FilesToRunProvider representing the ijar executable. + A FilesToRunProvider representing the ijar executable. + + ## jacocorunner @@ -41,8 +46,10 @@ A FilesToRunProvider representing the ijar executable. FilesToRunProvider JavaToolchainInfo.jacocorunner ``` -The jacocorunner used by the toolchain. -May return `None`. + The jacocorunner used by the toolchain. + May return `None`. + + ## java\_runtime @@ -50,7 +57,9 @@ May return `None`. JavaRuntimeInfo JavaToolchainInfo.java_runtime ``` -The java runtime information. + The java runtime information. + + ## jvm\_opt @@ -58,7 +67,9 @@ The java runtime information. depset JavaToolchainInfo.jvm_opt ``` -The default options for the JVM running the java compiler and associated tools. + The default options for the JVM running the java compiler and associated tools. + + ## label @@ -66,7 +77,9 @@ The default options for the JVM running the java compiler and associated tools. Label JavaToolchainInfo.label ``` -The toolchain label. + The toolchain label. + + ## proguard\_allowlister @@ -74,8 +87,10 @@ The toolchain label. FilesToRunProvider JavaToolchainInfo.proguard_allowlister ``` -Return the binary to validate proguard configuration -May return `None`. + Return the binary to validate proguard configuration + May return `None`. + + ## single\_jar @@ -83,7 +98,9 @@ May return `None`. FilesToRunProvider JavaToolchainInfo.single_jar ``` -The SingleJar deploy jar. + The SingleJar deploy jar. + + ## source\_version @@ -91,7 +108,9 @@ The SingleJar deploy jar. string JavaToolchainInfo.source_version ``` -The java source version. + The java source version. + + ## target\_version @@ -99,7 +118,9 @@ The java source version. string JavaToolchainInfo.target_version ``` -The java target version. + The java target version. + + ## tools @@ -107,4 +128,4 @@ The java target version. depset JavaToolchainInfo.tools ``` -The compilation tools. \ No newline at end of file + The compilation tools. diff --git a/rules/lib/providers/MaterializedDepsInfo.mdx b/rules/lib/providers/MaterializedDepsInfo.mdx index ce6c00c..82b3ee0 100644 --- a/rules/lib/providers/MaterializedDepsInfo.mdx +++ b/rules/lib/providers/MaterializedDepsInfo.mdx @@ -3,11 +3,12 @@ title: 'MaterializedDepsInfo' --- + The provider returned from materializer rules to materialize dependencies. ## Members -* [deps](#deps) +- [deps](#deps) ## deps @@ -15,4 +16,4 @@ The provider returned from materializer rules to materialize dependencies. list MaterializedDepsInfo.deps ``` -The list of dependencies. These may be ConfiguredTarget or DormantDependency objects. \ No newline at end of file + The list of dependencies. These may be ConfiguredTarget or DormantDependency objects. diff --git a/rules/lib/providers/ObjcProvider.mdx b/rules/lib/providers/ObjcProvider.mdx index 1bb39cf..eaa724d 100644 --- a/rules/lib/providers/ObjcProvider.mdx +++ b/rules/lib/providers/ObjcProvider.mdx @@ -3,17 +3,18 @@ title: 'ObjcProvider' --- + A provider for compilation and linking of objc. ## Members -* [direct\_module\_maps](#direct_module_maps) -* [direct\_sources](#direct_sources) -* [j2objc\_library](#j2objc_library) -* [module\_map](#module_map) -* [source](#source) -* [strict\_include](#strict_include) -* [umbrella\_header](#umbrella_header) +- [direct\_module\_maps](#direct_module_maps) +- [direct\_sources](#direct_sources) +- [j2objc\_library](#j2objc_library) +- [module\_map](#module_map) +- [source](#source) +- [strict\_include](#strict_include) +- [umbrella\_header](#umbrella_header) ## direct\_module\_maps @@ -21,7 +22,9 @@ A provider for compilation and linking of objc. sequence ObjcProvider.direct_module_maps ``` -Module map files from this target directly (no transitive module maps). Used to enforce proper use of private header files and for Swift compilation. + Module map files from this target directly (no transitive module maps). Used to enforce proper use of private header files and for Swift compilation. + + ## direct\_sources @@ -29,7 +32,9 @@ Module map files from this target directly (no transitive module maps). Used to sequence ObjcProvider.direct_sources ``` -All direct source files from this target (no transitive files), including any headers in the 'srcs' attribute. + All direct source files from this target (no transitive files), including any headers in the 'srcs' attribute. + + ## j2objc\_library @@ -37,7 +42,9 @@ All direct source files from this target (no transitive files), including any he depset ObjcProvider.j2objc_library ``` -Static libraries that are built from J2ObjC-translated Java code. + Static libraries that are built from J2ObjC-translated Java code. + + ## module\_map @@ -45,7 +52,9 @@ Static libraries that are built from J2ObjC-translated Java code. depset ObjcProvider.module_map ``` -Clang module maps, used to enforce proper use of private header files. + Clang module maps, used to enforce proper use of private header files. + + ## source @@ -53,7 +62,9 @@ Clang module maps, used to enforce proper use of private header files. depset ObjcProvider.source ``` -All transitive source files. + All transitive source files. + + ## strict\_include @@ -61,7 +72,9 @@ All transitive source files. depset ObjcProvider.strict_include ``` -Non-propagated include search paths specified with '-I' on the command line. Also known as header search paths (and distinct from *user* header search paths). + Non-propagated include search paths specified with '-I' on the command line. Also known as header search paths (and distinct from _user_ header search paths). + + ## umbrella\_header @@ -69,4 +82,4 @@ Non-propagated include search paths specified with '-I' on the command line. Als depset ObjcProvider.umbrella_header ``` -Clang umbrella header. Public headers are #included in umbrella headers to be compatible with J2ObjC segmented headers. \ No newline at end of file + Clang umbrella header. Public headers are #included in umbrella headers to be compatible with J2ObjC segmented headers. diff --git a/rules/lib/providers/OutputGroupInfo.mdx b/rules/lib/providers/OutputGroupInfo.mdx index b520695..da47a70 100644 --- a/rules/lib/providers/OutputGroupInfo.mdx +++ b/rules/lib/providers/OutputGroupInfo.mdx @@ -3,12 +3,14 @@ title: 'OutputGroupInfo' --- -A provider that indicates what output groups a rule has. + +A provider that indicates what output groups a rule has. + See [Requesting output files](https://bazel.build/extending/rules#requesting_output_files) for more information. ## Members -* [OutputGroupInfo](#OutputGroupInfo) +- [OutputGroupInfo](#OutputGroupInfo) ## OutputGroupInfo @@ -16,16 +18,18 @@ See [Requesting output files](https://bazel.build/extending/rules#requesting_out OutputGroupInfo OutputGroupInfo(**kwargs) ``` -Instantiate this provider with + Instantiate this provider with ``` -OutputGroupInfo(group1 = \<files\>, group2 = \<files\>...) +OutputGroupInfo(group1 = <files>, group2 = <files>...) ``` -See [Requesting output files](https://bazel.build/extending/rules#requesting_output_files) for more information. +See [Requesting output files](https://bazel.build/extending/rules#requesting_output_files) for more information. + ### Parameters -| Parameter | Description | -| --- | --- | -| `kwargs` | default is `\{\}` | \ No newline at end of file +ParameterDescription`kwargs` + default is `{}` + + Dictionary of arguments. diff --git a/rules/lib/providers/PackageSpecificationInfo.mdx b/rules/lib/providers/PackageSpecificationInfo.mdx index c2562bc..6684874 100644 --- a/rules/lib/providers/PackageSpecificationInfo.mdx +++ b/rules/lib/providers/PackageSpecificationInfo.mdx @@ -3,11 +3,12 @@ title: 'PackageSpecificationInfo' --- + Information about transitive package specifications used in package groups. ## Members -* [contains](#contains) +- [contains](#contains) ## contains @@ -15,10 +16,12 @@ Information about transitive package specifications used in package groups. bool PackageSpecificationInfo.contains(target) ``` -Checks if a target exists in a package group. + Checks if a target exists in a package group. + ### Parameters -| Parameter | Description | -| --- | --- | -| `target` | [Label](../builtins/Label.mdx); or [string](../core/string.mdx); required A target which is checked if it exists inside the package group. | \ No newline at end of file +ParameterDescription`target`[Label](../builtins/Label.html); or [string](../core/string.html); + required + + A target which is checked if it exists inside the package group. diff --git a/rules/lib/providers/PlatformInfo.mdx b/rules/lib/providers/PlatformInfo.mdx index 1fe60f9..ecbfa9a 100644 --- a/rules/lib/providers/PlatformInfo.mdx +++ b/rules/lib/providers/PlatformInfo.mdx @@ -3,5 +3,7 @@ title: 'PlatformInfo' --- -Provides access to data about a specific platform. See [Defining Constraints and Platforms](./docs/platforms#constraints-platforms) for more information. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* \ No newline at end of file + +Provides access to data about a specific platform. See [Defining Constraints and Platforms](/docs/platforms#constraints-platforms) for more information. + +_Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`_ diff --git a/rules/lib/providers/RunEnvironmentInfo.mdx b/rules/lib/providers/RunEnvironmentInfo.mdx index ae66c64..2645399 100644 --- a/rules/lib/providers/RunEnvironmentInfo.mdx +++ b/rules/lib/providers/RunEnvironmentInfo.mdx @@ -3,12 +3,13 @@ title: 'RunEnvironmentInfo' --- + A provider that can be returned from executable rules to control the environment in which their executable is executed. ## Members -* [environment](#environment) -* [inherited\_environment](#inherited_environment) +- [environment](#environment) +- [inherited\_environment](#inherited_environment) ## environment @@ -16,7 +17,9 @@ A provider that can be returned from executable rules to control the environment dict RunEnvironmentInfo.environment ``` -A map of string keys and values that represent environment variables and their values. These will be made available when the target that returns this provider is executed, either as a test or via the run command. + A map of string keys and values that represent environment variables and their values. These will be made available when the target that returns this provider is executed, either as a test or via the run command. + + ## inherited\_environment @@ -24,4 +27,4 @@ A map of string keys and values that represent environment variables and their v List RunEnvironmentInfo.inherited_environment ``` -A sequence of names of environment variables. These variables are made available with their current value taken from the shell environment when the target that returns this provider is executed, either as a test or via the run command. If a variable is contained in both `environment` and `inherited_environment`, the value inherited from the shell environment will take precedence if set. This is most useful for test rules, which run with a hermetic environment under `bazel test` and can use this mechanism to non-hermetically include a variable from the outer environment. By contrast, `bazel run` already forwards the outer environment. Note, though, that it may be surprising for an otherwise hermetic test to hardcode a non-hermetic dependency on the environment, and that this may even accidentally expose sensitive information. Prefer setting the test environment explicitly with the `--test_env` flag, and even then prefer to avoid using this flag and instead populate the environment explicitly. \ No newline at end of file + A sequence of names of environment variables. These variables are made available with their current value taken from the shell environment when the target that returns this provider is executed, either as a test or via the run command. If a variable is contained in both `environment` and `inherited_environment`, the value inherited from the shell environment will take precedence if set. This is most useful for test rules, which run with a hermetic environment under `bazel test` and can use this mechanism to non-hermetically include a variable from the outer environment. By contrast, `bazel run` already forwards the outer environment. Note, though, that it may be surprising for an otherwise hermetic test to hardcode a non-hermetic dependency on the environment, and that this may even accidentally expose sensitive information. Prefer setting the test environment explicitly with the `--test_env` flag, and even then prefer to avoid using this flag and instead populate the environment explicitly. diff --git a/rules/lib/providers/TemplateVariableInfo.mdx b/rules/lib/providers/TemplateVariableInfo.mdx index 06f69ff..6bbc45a 100644 --- a/rules/lib/providers/TemplateVariableInfo.mdx +++ b/rules/lib/providers/TemplateVariableInfo.mdx @@ -3,15 +3,16 @@ title: 'TemplateVariableInfo' --- + Encapsulates template variables, that is, variables that can be referenced by strings like `$(VARIABLE)` in BUILD files and expanded by `ctx.expand_make_variables` and implicitly in certain attributes of built-in rules. `TemplateVariableInfo` can be created by calling its eponymous constructor with a string-to-string dict as an argument that specifies the variables provided. -Example: `platform_common.TemplateVariableInfo(\{'FOO': 'bar'\})` +Example: `platform_common.TemplateVariableInfo({'FOO': 'bar'})` ## Members -* [variables](#variables) +- [variables](#variables) ## variables @@ -19,4 +20,4 @@ Example: `platform_common.TemplateVariableInfo(\{'FOO': 'bar'\})` dict TemplateVariableInfo.variables ``` -Returns the make variables defined by this target as a dictionary with string keys and string values \ No newline at end of file + Returns the make variables defined by this target as a dictionary with string keys and string values diff --git a/rules/lib/providers/ToolchainInfo.mdx b/rules/lib/providers/ToolchainInfo.mdx index 061d64e..15aa195 100644 --- a/rules/lib/providers/ToolchainInfo.mdx +++ b/rules/lib/providers/ToolchainInfo.mdx @@ -3,4 +3,5 @@ title: 'ToolchainInfo' --- -Provider returned by [toolchain rules](./docs/toolchains#defining-toolchains) to share data with [rules which depend on toolchains](./docs/toolchains#writing-rules-that-use-toolchains). Read about [toolchains](./docs/toolchains) for more information. \ No newline at end of file + +Provider returned by [toolchain rules](/docs/toolchains#defining-toolchains) to share data with [rules which depend on toolchains](/docs/toolchains#writing-rules-that-use-toolchains). Read about [toolchains](/docs/toolchains) for more information. diff --git a/rules/lib/providers/ToolchainTypeInfo.mdx b/rules/lib/providers/ToolchainTypeInfo.mdx index 5f8c4fb..16f206f 100644 --- a/rules/lib/providers/ToolchainTypeInfo.mdx +++ b/rules/lib/providers/ToolchainTypeInfo.mdx @@ -3,12 +3,14 @@ title: 'ToolchainTypeInfo' --- -Provides access to data about a specific toolchain type. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* + +Provides access to data about a specific toolchain type. + +_Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`_ ## Members -* [type\_label](#type_label) +- [type\_label](#type_label) ## type\_label @@ -16,4 +18,4 @@ Provides access to data about a specific toolchain type. Label ToolchainTypeInfo.type_label ``` -The label uniquely identifying this toolchain type. \ No newline at end of file + The label uniquely identifying this toolchain type. diff --git a/rules/lib/providers/file_provider.mdx b/rules/lib/providers/file_provider.mdx index af1169e..24cc8e5 100644 --- a/rules/lib/providers/file_provider.mdx +++ b/rules/lib/providers/file_provider.mdx @@ -1,6 +1,7 @@ --- -title: 'file_provider' +title: 'file\_provider' --- -An interface for rules that provide files. \ No newline at end of file + +An interface for rules that provide files. diff --git a/rules/lib/providers/java_compilation_info.mdx b/rules/lib/providers/java_compilation_info.mdx index 85b677e..25f4ec7 100644 --- a/rules/lib/providers/java_compilation_info.mdx +++ b/rules/lib/providers/java_compilation_info.mdx @@ -1,16 +1,17 @@ --- -title: 'java_compilation_info' +title: 'java\_compilation\_info' --- + Provides access to compilation information for Java rules. ## Members -* [boot\_classpath](#boot_classpath) -* [compilation\_classpath](#compilation_classpath) -* [javac\_options](#javac_options) -* [runtime\_classpath](#runtime_classpath) +- [boot\_classpath](#boot_classpath) +- [compilation\_classpath](#compilation_classpath) +- [javac\_options](#javac_options) +- [runtime\_classpath](#runtime_classpath) ## boot\_classpath @@ -18,7 +19,9 @@ Provides access to compilation information for Java rules. list java_compilation_info.boot_classpath ``` -Boot classpath for this Java target. + Boot classpath for this Java target. + + ## compilation\_classpath @@ -26,7 +29,9 @@ Boot classpath for this Java target. depset java_compilation_info.compilation_classpath ``` -Compilation classpath for this Java target. + Compilation classpath for this Java target. + + ## javac\_options @@ -34,7 +39,9 @@ Compilation classpath for this Java target. depset java_compilation_info.javac_options ``` -A depset of options to java compiler. To get the exact list of options passed to javac in the correct order, use the tokenize\_javacopts utility in rules\_java + A depset of options to java compiler. To get the exact list of options passed to javac in the correct order, use the tokenize\_javacopts utility in rules\_java + + ## runtime\_classpath @@ -42,4 +49,4 @@ A depset of options to java compiler. To get the exact list of options passed to depset java_compilation_info.runtime_classpath ``` -Run-time classpath for this Java target. \ No newline at end of file + Run-time classpath for this Java target. diff --git a/rules/lib/providers/java_output_jars.mdx b/rules/lib/providers/java_output_jars.mdx index 85471a5..426a683 100644 --- a/rules/lib/providers/java_output_jars.mdx +++ b/rules/lib/providers/java_output_jars.mdx @@ -1,15 +1,16 @@ --- -title: 'java_output_jars' +title: 'java\_output\_jars' --- + Information about outputs of a Java rule. Deprecated: use java\_info.java\_outputs. ## Members -* [jars](#jars) -* [jdeps](#jdeps) -* [native\_headers](#native_headers) +- [jars](#jars) +- [jdeps](#jdeps) +- [native\_headers](#native_headers) ## jars @@ -17,7 +18,9 @@ Information about outputs of a Java rule. Deprecated: use java\_info.java\_outpu list java_output_jars.jars ``` -Returns information about outputs of this Java/Java-like target. Deprecated: Use java\_info.java\_outputs. + Returns information about outputs of this Java/Java-like target. Deprecated: Use java\_info.java\_outputs. + + ## jdeps @@ -25,8 +28,10 @@ Returns information about outputs of this Java/Java-like target. Deprecated: Use File java_output_jars.jdeps ``` -A manifest proto file. The protobuf file containing the manifest generated from JavaBuilder. This function returns a value when exactly one manifest proto file is present in the outputs. Deprecated: Use java\_info.java\_outputs[i].jdeps. -May return `None`. + A manifest proto file. The protobuf file containing the manifest generated from JavaBuilder. This function returns a value when exactly one manifest proto file is present in the outputs. Deprecated: Use java\_info.java\_outputs\[i\].jdeps. + May return `None`. + + ## native\_headers @@ -34,5 +39,5 @@ May return `None`. File java_output_jars.native_headers ``` -A jar containing CC header files supporting native method implementation. This function returns a value when exactly one native headers jar file is present in the outputs. Deprecated: Use java\_info.java\_outputs[i].native\_headers\_jar. -May return `None`. \ No newline at end of file + A jar containing CC header files supporting native method implementation. This function returns a value when exactly one native headers jar file is present in the outputs. Deprecated: Use java\_info.java\_outputs\[i\].native\_headers\_jar. + May return `None`. diff --git a/rules/lib/repo/cache.mdx b/rules/lib/repo/cache.mdx new file mode 100644 index 0000000..873044c --- /dev/null +++ b/rules/lib/repo/cache.mdx @@ -0,0 +1,79 @@ +--- +title: 'cache repository rules' +--- + + + +The following functions can be loaded from +`@bazel_tools//tools/build_defs/repo:cache.bzl`. +// Generated with Stardoc: http://skydoc.bazel.build + +Returns the default canonical id to use for downloads. + +<a id="get_default_canonical_id"></a> + +## get_default_canonical_id + +``` +load("@bazel//tools/build_defs/repo:cache.bzl", "get_default_canonical_id") + +get_default_canonical_id(<a href="#get_default_canonical_id-repository_ctx">repository_ctx</a>, <a href="#get_default_canonical_id-urls">urls</a>) +``` + +Returns the default canonical id to use for downloads. + +Returns `""` (empty string) when Bazel is run with +`--repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0`. + +e.g. +```python +load("@bazel_tools//tools/build_defs/repo:cache.bzl", "get_default_canonical_id") +# ... + repository_ctx.download_and_extract( + url = urls, + integrity = integrity + canonical_id = get_default_canonical_id(repository_ctx, urls), + ), +``` + + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="get_default_canonical_id-repository_ctx"> +<td><code>repository_ctx</code></td> +<td> + +required. + +<p> + +The repository context of the repository rule calling this utility +function. + +</p> +</td> +</tr> +<tr id="get_default_canonical_id-urls"> +<td><code>urls</code></td> +<td> + +required. + +<p> + +A list of URLs matching what is passed to `repository_ctx.download` and +`repository_ctx.download_and_extract`. + +</p> +</td> +</tr> +</tbody> +</table> + + diff --git a/rules/lib/repo/git.mdx b/rules/lib/repo/git.mdx new file mode 100644 index 0000000..e91ef9c --- /dev/null +++ b/rules/lib/repo/git.mdx @@ -0,0 +1,760 @@ +--- +title: 'git repository rules' +--- + + + +The following functions can be loaded from +`@bazel_tools//tools/build_defs/repo:git.bzl`. +// Generated with Stardoc: http://skydoc.bazel.build + +Rules for cloning external git repositories. + +<a id="git_repository"></a> + +## git_repository + +``` +load("@bazel//tools/build_defs/repo:git.bzl", "git_repository") + +git_repository(<a href="#git_repository-name">name</a>, <a href="#git_repository-branch">branch</a>, <a href="#git_repository-build_file">build_file</a>, <a href="#git_repository-build_file_content">build_file_content</a>, <a href="#git_repository-commit">commit</a>, <a href="#git_repository-init_submodules">init_submodules</a>, <a href="#git_repository-patch_args">patch_args</a>, + <a href="#git_repository-patch_cmds">patch_cmds</a>, <a href="#git_repository-patch_cmds_win">patch_cmds_win</a>, <a href="#git_repository-patch_strip">patch_strip</a>, <a href="#git_repository-patch_tool">patch_tool</a>, <a href="#git_repository-patches">patches</a>, + <a href="#git_repository-recursive_init_submodules">recursive_init_submodules</a>, <a href="#git_repository-remote">remote</a>, <a href="#git_repository-remote_module_file_integrity">remote_module_file_integrity</a>, + <a href="#git_repository-remote_module_file_urls">remote_module_file_urls</a>, <a href="#git_repository-repo_mapping">repo_mapping</a>, <a href="#git_repository-shallow_since">shallow_since</a>, <a href="#git_repository-sparse_checkout_file">sparse_checkout_file</a>, + <a href="#git_repository-sparse_checkout_patterns">sparse_checkout_patterns</a>, <a href="#git_repository-strip_prefix">strip_prefix</a>, <a href="#git_repository-tag">tag</a>, <a href="#git_repository-verbose">verbose</a>, <a href="#git_repository-workspace_file">workspace_file</a>, + <a href="#git_repository-workspace_file_content">workspace_file_content</a>) +``` + +Clone an external git repository. + +Clones a Git repository, checks out the specified tag, or commit, and +makes its targets available for binding. Also determine the id of the +commit actually checked out and its date, and return a dict with parameters +that provide a reproducible version of this rule (which a tag not necessarily +is). + +Bazel will first try to perform a shallow fetch of only the specified commit. +If that fails (usually due to missing server support), it will fall back to a +full fetch of the repository. + +Prefer [`http_archive`](/rules/lib/repo/http#http_archive) to `git_repository`. +The reasons are: + +* Git repository rules depend on system `git(1)` whereas the HTTP downloader is built + into Bazel and has no system dependencies. +* `http_archive` supports a list of `urls` as mirrors, and `git_repository` supports only + a single `remote`. +* `http_archive` works with the [repository cache](/run/build#repository-cache), but not + `git_repository`. See + [#5116](https://github.com/bazelbuild/bazel/issues/5116) for more information. + +**ATTRIBUTES** + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="git_repository-name"> +<td><code>name</code></td> +<td> + +<a href="https://bazel.build/concepts/labels#target-names">Name</a>; required + +<p> + +A unique name for this repository. + +</p> +</td> +</tr> +<tr id="git_repository-branch"> +<td><code>branch</code></td> +<td> + +String; optional + +<p> + +branch in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified. + +</p> +</td> +</tr> +<tr id="git_repository-build_file"> +<td><code>build_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +The file to use as the BUILD file for this repository. This attribute is an absolute label (use '@//' for the main repo). The file does not need to be named BUILD, but can be (something like BUILD.new-repo-name may work well for distinguishing it from the repository's actual BUILD files). + +</p> +</td> +</tr> +<tr id="git_repository-build_file_content"> +<td><code>build_file_content</code></td> +<td> + +String; optional + +<p> + +The content for the BUILD file for this repository. + +</p> +</td> +</tr> +<tr id="git_repository-commit"> +<td><code>commit</code></td> +<td> + +String; optional + +<p> + +specific commit to be checked out. Precisely one of branch, tag, or commit must be specified. + +</p> +</td> +</tr> +<tr id="git_repository-init_submodules"> +<td><code>init_submodules</code></td> +<td> + +Boolean; optional + +<p> + +Whether to clone submodules in the repository. + +</p> +</td> +</tr> +<tr id="git_repository-patch_args"> +<td><code>patch_args</code></td> +<td> + +List of strings; optional + +<p> + +The arguments given to the patch tool. Defaults to -p0 (see the `patch_strip` attribute), however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch_tool attribute is not specified, `patch` will be used. + +</p> +</td> +</tr> +<tr id="git_repository-patch_cmds"> +<td><code>patch_cmds</code></td> +<td> + +List of strings; optional + +<p> + +Sequence of Bash commands to be applied on Linux/Macos after patches are applied. + +</p> +</td> +</tr> +<tr id="git_repository-patch_cmds_win"> +<td><code>patch_cmds_win</code></td> +<td> + +List of strings; optional + +<p> + +Sequence of Powershell commands to be applied on Windows after patches are applied. If this attribute is not set, patch_cmds will be executed on Windows, which requires Bash binary to exist. + +</p> +</td> +</tr> +<tr id="git_repository-patch_strip"> +<td><code>patch_strip</code></td> +<td> + +Integer; optional + +<p> + +When set to `N`, this is equivalent to inserting `-pN` to the beginning of `patch_args`. + +</p> +</td> +</tr> +<tr id="git_repository-patch_tool"> +<td><code>patch_tool</code></td> +<td> + +String; optional + +<p> + +The patch(1) utility to use. If this is specified, Bazel will use the specified patch tool instead of the Bazel-native patch implementation. + +</p> +</td> +</tr> +<tr id="git_repository-patches"> +<td><code>patches</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">List of labels</a>; optional + +<p> + +A list of files that are to be applied as patches after extracting the archive. By default, it uses the Bazel-native patch implementation which doesn't support fuzz match and binary patch, but Bazel will fall back to use patch command line tool if `patch_tool` attribute is specified or there are arguments other than `-p` in `patch_args` attribute. + +</p> +</td> +</tr> +<tr id="git_repository-recursive_init_submodules"> +<td><code>recursive_init_submodules</code></td> +<td> + +Boolean; optional + +<p> + +Whether to clone submodules recursively in the repository. + +</p> +</td> +</tr> +<tr id="git_repository-remote"> +<td><code>remote</code></td> +<td> + +String; required + +<p> + +The URI of the remote Git repository + +</p> +</td> +</tr> +<tr id="git_repository-remote_module_file_integrity"> +<td><code>remote_module_file_integrity</code></td> +<td> + +String; optional + +<p> + +For internal use only. + +</p> +</td> +</tr> +<tr id="git_repository-remote_module_file_urls"> +<td><code>remote_module_file_urls</code></td> +<td> + +List of strings; optional + +<p> + +For internal use only. + +</p> +</td> +</tr> +<tr id="git_repository-repo_mapping"> +<td><code>repo_mapping</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. + +For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). + +This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). + +</p> +</td> +</tr> +<tr id="git_repository-shallow_since"> +<td><code>shallow_since</code></td> +<td> + +String; optional + +<p> + +an optional date, not after the specified commit; the argument is not allowed if a tag or branch is specified (which can always be cloned with --depth=1). Setting such a date close to the specified commit may allow for a shallow clone of the repository even if the server does not support shallow fetches of arbitrary commits. Due to bugs in git's --shallow-since implementation, using this attribute is not recommended as it may result in fetch failures. + +</p> +</td> +</tr> +<tr id="git_repository-sparse_checkout_file"> +<td><code>sparse_checkout_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +File containing .gitignore-style patterns for a sparse checkout of files in this repository. Either `sparse_checkout_patterns` or `sparse_checkout_file` may be specified, or neither, but not both. + +</p> +</td> +</tr> +<tr id="git_repository-sparse_checkout_patterns"> +<td><code>sparse_checkout_patterns</code></td> +<td> + +List of strings; optional + +<p> + +Sequence of patterns for a sparse checkout of files in this repository. + +</p> +</td> +</tr> +<tr id="git_repository-strip_prefix"> +<td><code>strip_prefix</code></td> +<td> + +String; optional + +<p> + +A directory prefix to strip from the extracted files. + +</p> +</td> +</tr> +<tr id="git_repository-tag"> +<td><code>tag</code></td> +<td> + +String; optional + +<p> + +tag in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified. + +</p> +</td> +</tr> +<tr id="git_repository-verbose"> +<td><code>verbose</code></td> +<td> + +Boolean; optional + +</td> +</tr> +<tr id="git_repository-workspace_file"> +<td><code>workspace_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +No-op attribute; do not use. + +</p> +</td> +</tr> +<tr id="git_repository-workspace_file_content"> +<td><code>workspace_file_content</code></td> +<td> + +String; optional + +<p> + +No-op attribute; do not use. + +</p> +</td> +</tr> +</tbody> +</table> + + +<a id="new_git_repository"></a> + +## new_git_repository + +``` +load("@bazel//tools/build_defs/repo:git.bzl", "new_git_repository") + +new_git_repository(<a href="#new_git_repository-name">name</a>, <a href="#new_git_repository-branch">branch</a>, <a href="#new_git_repository-build_file">build_file</a>, <a href="#new_git_repository-build_file_content">build_file_content</a>, <a href="#new_git_repository-commit">commit</a>, <a href="#new_git_repository-init_submodules">init_submodules</a>, + <a href="#new_git_repository-patch_args">patch_args</a>, <a href="#new_git_repository-patch_cmds">patch_cmds</a>, <a href="#new_git_repository-patch_cmds_win">patch_cmds_win</a>, <a href="#new_git_repository-patch_strip">patch_strip</a>, <a href="#new_git_repository-patch_tool">patch_tool</a>, <a href="#new_git_repository-patches">patches</a>, + <a href="#new_git_repository-recursive_init_submodules">recursive_init_submodules</a>, <a href="#new_git_repository-remote">remote</a>, <a href="#new_git_repository-remote_module_file_integrity">remote_module_file_integrity</a>, + <a href="#new_git_repository-remote_module_file_urls">remote_module_file_urls</a>, <a href="#new_git_repository-repo_mapping">repo_mapping</a>, <a href="#new_git_repository-shallow_since">shallow_since</a>, <a href="#new_git_repository-sparse_checkout_file">sparse_checkout_file</a>, + <a href="#new_git_repository-sparse_checkout_patterns">sparse_checkout_patterns</a>, <a href="#new_git_repository-strip_prefix">strip_prefix</a>, <a href="#new_git_repository-tag">tag</a>, <a href="#new_git_repository-verbose">verbose</a>, <a href="#new_git_repository-workspace_file">workspace_file</a>, + <a href="#new_git_repository-workspace_file_content">workspace_file_content</a>) +``` + +Clone an external git repository. + +Clones a Git repository, checks out the specified tag, or commit, and +makes its targets available for binding. Also determine the id of the +commit actually checked out and its date, and return a dict with parameters +that provide a reproducible version of this rule (which a tag not necessarily +is). + +Bazel will first try to perform a shallow fetch of only the specified commit. +If that fails (usually due to missing server support), it will fall back to a +full fetch of the repository. + +Prefer [`http_archive`](/rules/lib/repo/http#http_archive) to `git_repository`. +The reasons are: + +* Git repository rules depend on system `git(1)` whereas the HTTP downloader is built + into Bazel and has no system dependencies. +* `http_archive` supports a list of `urls` as mirrors, and `git_repository` supports only + a single `remote`. +* `http_archive` works with the [repository cache](/run/build#repository-cache), but not + `git_repository`. See + [#5116](https://github.com/bazelbuild/bazel/issues/5116) for more information. + +**ATTRIBUTES** + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="new_git_repository-name"> +<td><code>name</code></td> +<td> + +<a href="https://bazel.build/concepts/labels#target-names">Name</a>; required + +<p> + +A unique name for this repository. + +</p> +</td> +</tr> +<tr id="new_git_repository-branch"> +<td><code>branch</code></td> +<td> + +String; optional + +<p> + +branch in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified. + +</p> +</td> +</tr> +<tr id="new_git_repository-build_file"> +<td><code>build_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +The file to use as the BUILD file for this repository. This attribute is an absolute label (use '@//' for the main repo). The file does not need to be named BUILD, but can be (something like BUILD.new-repo-name may work well for distinguishing it from the repository's actual BUILD files). + +</p> +</td> +</tr> +<tr id="new_git_repository-build_file_content"> +<td><code>build_file_content</code></td> +<td> + +String; optional + +<p> + +The content for the BUILD file for this repository. + +</p> +</td> +</tr> +<tr id="new_git_repository-commit"> +<td><code>commit</code></td> +<td> + +String; optional + +<p> + +specific commit to be checked out. Precisely one of branch, tag, or commit must be specified. + +</p> +</td> +</tr> +<tr id="new_git_repository-init_submodules"> +<td><code>init_submodules</code></td> +<td> + +Boolean; optional + +<p> + +Whether to clone submodules in the repository. + +</p> +</td> +</tr> +<tr id="new_git_repository-patch_args"> +<td><code>patch_args</code></td> +<td> + +List of strings; optional + +<p> + +The arguments given to the patch tool. Defaults to -p0 (see the `patch_strip` attribute), however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch_tool attribute is not specified, `patch` will be used. + +</p> +</td> +</tr> +<tr id="new_git_repository-patch_cmds"> +<td><code>patch_cmds</code></td> +<td> + +List of strings; optional + +<p> + +Sequence of Bash commands to be applied on Linux/Macos after patches are applied. + +</p> +</td> +</tr> +<tr id="new_git_repository-patch_cmds_win"> +<td><code>patch_cmds_win</code></td> +<td> + +List of strings; optional + +<p> + +Sequence of Powershell commands to be applied on Windows after patches are applied. If this attribute is not set, patch_cmds will be executed on Windows, which requires Bash binary to exist. + +</p> +</td> +</tr> +<tr id="new_git_repository-patch_strip"> +<td><code>patch_strip</code></td> +<td> + +Integer; optional + +<p> + +When set to `N`, this is equivalent to inserting `-pN` to the beginning of `patch_args`. + +</p> +</td> +</tr> +<tr id="new_git_repository-patch_tool"> +<td><code>patch_tool</code></td> +<td> + +String; optional + +<p> + +The patch(1) utility to use. If this is specified, Bazel will use the specified patch tool instead of the Bazel-native patch implementation. + +</p> +</td> +</tr> +<tr id="new_git_repository-patches"> +<td><code>patches</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">List of labels</a>; optional + +<p> + +A list of files that are to be applied as patches after extracting the archive. By default, it uses the Bazel-native patch implementation which doesn't support fuzz match and binary patch, but Bazel will fall back to use patch command line tool if `patch_tool` attribute is specified or there are arguments other than `-p` in `patch_args` attribute. + +</p> +</td> +</tr> +<tr id="new_git_repository-recursive_init_submodules"> +<td><code>recursive_init_submodules</code></td> +<td> + +Boolean; optional + +<p> + +Whether to clone submodules recursively in the repository. + +</p> +</td> +</tr> +<tr id="new_git_repository-remote"> +<td><code>remote</code></td> +<td> + +String; required + +<p> + +The URI of the remote Git repository + +</p> +</td> +</tr> +<tr id="new_git_repository-remote_module_file_integrity"> +<td><code>remote_module_file_integrity</code></td> +<td> + +String; optional + +<p> + +For internal use only. + +</p> +</td> +</tr> +<tr id="new_git_repository-remote_module_file_urls"> +<td><code>remote_module_file_urls</code></td> +<td> + +List of strings; optional + +<p> + +For internal use only. + +</p> +</td> +</tr> +<tr id="new_git_repository-repo_mapping"> +<td><code>repo_mapping</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. + +For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). + +This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). + +</p> +</td> +</tr> +<tr id="new_git_repository-shallow_since"> +<td><code>shallow_since</code></td> +<td> + +String; optional + +<p> + +an optional date, not after the specified commit; the argument is not allowed if a tag or branch is specified (which can always be cloned with --depth=1). Setting such a date close to the specified commit may allow for a shallow clone of the repository even if the server does not support shallow fetches of arbitrary commits. Due to bugs in git's --shallow-since implementation, using this attribute is not recommended as it may result in fetch failures. + +</p> +</td> +</tr> +<tr id="new_git_repository-sparse_checkout_file"> +<td><code>sparse_checkout_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +File containing .gitignore-style patterns for a sparse checkout of files in this repository. Either `sparse_checkout_patterns` or `sparse_checkout_file` may be specified, or neither, but not both. + +</p> +</td> +</tr> +<tr id="new_git_repository-sparse_checkout_patterns"> +<td><code>sparse_checkout_patterns</code></td> +<td> + +List of strings; optional + +<p> + +Sequence of patterns for a sparse checkout of files in this repository. + +</p> +</td> +</tr> +<tr id="new_git_repository-strip_prefix"> +<td><code>strip_prefix</code></td> +<td> + +String; optional + +<p> + +A directory prefix to strip from the extracted files. + +</p> +</td> +</tr> +<tr id="new_git_repository-tag"> +<td><code>tag</code></td> +<td> + +String; optional + +<p> + +tag in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified. + +</p> +</td> +</tr> +<tr id="new_git_repository-verbose"> +<td><code>verbose</code></td> +<td> + +Boolean; optional + +</td> +</tr> +<tr id="new_git_repository-workspace_file"> +<td><code>workspace_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +No-op attribute; do not use. + +</p> +</td> +</tr> +<tr id="new_git_repository-workspace_file_content"> +<td><code>workspace_file_content</code></td> +<td> + +String; optional + +<p> + +No-op attribute; do not use. + +</p> +</td> +</tr> +</tbody> +</table> + + diff --git a/rules/lib/repo/http.mdx b/rules/lib/repo/http.mdx new file mode 100644 index 0000000..5b06f10 --- /dev/null +++ b/rules/lib/repo/http.mdx @@ -0,0 +1,1104 @@ +--- +title: 'http repository rules' +--- + + + +The following functions can be loaded from +`@bazel_tools//tools/build_defs/repo:http.bzl`. +// Generated with Stardoc: http://skydoc.bazel.build + +Rules for downloading files and archives over HTTP. + +### Setup + +To use these rules in a module extension, load them in your .bzl file and then call them from your +extension's implementation function. For example, to use `http_archive`: + +```python +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + +def _my_extension_impl(mctx): + http_archive(name = "foo", urls = [...]) + +my_extension = module_extension(implementation = _my_extension_impl) +``` + +Alternatively, you can directly call these repo rules in your MODULE.bazel file with +`use_repo_rule`: + +```python +http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") +http_archive(name = "foo", urls = [...]) +``` + +<a id="http_archive"></a> + +## http_archive + +``` +load("@bazel//tools/build_defs/repo:http.bzl", "http_archive") + +http_archive(<a href="#http_archive-name">name</a>, <a href="#http_archive-add_prefix">add_prefix</a>, <a href="#http_archive-auth_patterns">auth_patterns</a>, <a href="#http_archive-build_file">build_file</a>, <a href="#http_archive-build_file_content">build_file_content</a>, <a href="#http_archive-canonical_id">canonical_id</a>, <a href="#http_archive-files">files</a>, + <a href="#http_archive-integrity">integrity</a>, <a href="#http_archive-netrc">netrc</a>, <a href="#http_archive-patch_args">patch_args</a>, <a href="#http_archive-patch_cmds">patch_cmds</a>, <a href="#http_archive-patch_cmds_win">patch_cmds_win</a>, <a href="#http_archive-patch_strip">patch_strip</a>, <a href="#http_archive-patch_tool">patch_tool</a>, + <a href="#http_archive-patches">patches</a>, <a href="#http_archive-remote_file_integrity">remote_file_integrity</a>, <a href="#http_archive-remote_file_urls">remote_file_urls</a>, <a href="#http_archive-remote_module_file_integrity">remote_module_file_integrity</a>, + <a href="#http_archive-remote_module_file_urls">remote_module_file_urls</a>, <a href="#http_archive-remote_patch_strip">remote_patch_strip</a>, <a href="#http_archive-remote_patches">remote_patches</a>, <a href="#http_archive-repo_mapping">repo_mapping</a>, <a href="#http_archive-sha256">sha256</a>, + <a href="#http_archive-strip_prefix">strip_prefix</a>, <a href="#http_archive-type">type</a>, <a href="#http_archive-url">url</a>, <a href="#http_archive-urls">urls</a>, <a href="#http_archive-workspace_file">workspace_file</a>, <a href="#http_archive-workspace_file_content">workspace_file_content</a>) +``` + +Downloads a Bazel repository as a compressed archive file, decompresses it, +and makes its targets available for binding. + +It supports the following file extensions: `"zip"`, `"jar"`, `"war"`, `"aar"`, `"tar"`, +`"tar.gz"`, `"tgz"`, `"tar.xz"`, `"txz"`, `"tar.zst"`, `"tzst"`, `tar.bz2`, `"ar"`, +or `"deb"`. + +Examples: + Suppose the current repository contains the source code for a chat program, + rooted at the directory `~/chat-app`. It needs to depend on an SSL library + which is available from http://example.com/openssl.zip. This `.zip` file + contains the following directory structure: + + ``` + WORKSPACE + src/ + openssl.cc + openssl.h + ``` + + In the local repository, the user creates a `openssl.BUILD` file which + contains the following target definition: + + ```python + cc_library( + name = "openssl-lib", + srcs = ["src/openssl.cc"], + hdrs = ["src/openssl.h"], + ) + ``` + + Targets in the `~/chat-app` repository can depend on this target if the + following lines are added to `~/chat-app/WORKSPACE`: + + ```python + load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + + http_archive( + name = "my_ssl", + url = "http://example.com/openssl.zip", + sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + build_file = "@//:openssl.BUILD", + ) + ``` + + Then targets would specify `@my_ssl//:openssl-lib` as a dependency. + +**ATTRIBUTES** + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="http_archive-name"> +<td><code>name</code></td> +<td> + +<a href="https://bazel.build/concepts/labels#target-names">Name</a>; required + +<p> + +A unique name for this repository. + +</p> +</td> +</tr> +<tr id="http_archive-add_prefix"> +<td><code>add_prefix</code></td> +<td> + +String; optional + +<p> + +Destination directory relative to the repository directory. + +The archive will be unpacked into this directory, after applying `strip_prefix` +(if any) to the file paths within the archive. For example, file +`foo-1.2.3/src/foo.h` will be unpacked to `bar/src/foo.h` if `add_prefix = "bar"` +and `strip_prefix = "foo-1.2.3"`. + +</p> +</td> +</tr> +<tr id="http_archive-auth_patterns"> +<td><code>auth_patterns</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +An optional dict mapping host names to custom authorization patterns. + +If a URL's host name is present in this dict the value will be used as a pattern when +generating the authorization header for the http request. This enables the use of custom +authorization schemes used in a lot of common cloud storage providers. + +The pattern currently supports 2 tokens: <code><login></code> and +<code><password></code>, which are replaced with their equivalent value +in the netrc file for the same host name. After formatting, the result is set +as the value for the <code>Authorization</code> field of the HTTP request. + +Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token: + +``` +auth_patterns = { + "storage.cloudprovider.com": "Bearer <password>" +} +``` + +netrc: + +``` +machine storage.cloudprovider.com + password RANDOM-TOKEN +``` + +The final HTTP request would have the following header: + +``` +Authorization: Bearer RANDOM-TOKEN +``` + +</p> +</td> +</tr> +<tr id="http_archive-build_file"> +<td><code>build_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +The file to use as the BUILD file for this repository.This attribute is an absolute label (use '@//' for the main repo). The file does not need to be named BUILD, but can be (something like BUILD.new-repo-name may work well for distinguishing it from the repository's actual BUILD files. Either build_file or build_file_content can be specified, but not both. + +</p> +</td> +</tr> +<tr id="http_archive-build_file_content"> +<td><code>build_file_content</code></td> +<td> + +String; optional + +<p> + +The content for the BUILD file for this repository. Either build_file or build_file_content can be specified, but not both. + +</p> +</td> +</tr> +<tr id="http_archive-canonical_id"> +<td><code>canonical_id</code></td> +<td> + +String; optional + +<p> + +A canonical ID of the file downloaded. + +If specified and non-empty, Bazel will not take the file from cache, unless it +was added to the cache by a request with the same canonical ID. + +If unspecified or empty, Bazel by default uses the URLs of the file as the +canonical ID. This helps catch the common mistake of updating the URLs without +also updating the hash, resulting in builds that succeed locally but fail on +machines without the file in the cache. This behavior can be disabled with +--repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0. + +</p> +</td> +</tr> +<tr id="http_archive-files"> +<td><code>files</code></td> +<td> + +Dictionary: String -> Label; optional + +<p> + +A map of relative paths (key) to a file label (value) that overlaid on the repo as +a symlink. This is useful when you want to add REPO.bazel or BUILD.bazel files atop an existing +repository. Files are symlinked after remote files are downloaded and patches (`remote_patches`, +`patches`) are applied. Existing files will be overwritten. + +</p> +</td> +</tr> +<tr id="http_archive-integrity"> +<td><code>integrity</code></td> +<td> + +String; optional + +<p> + +Expected checksum in Subresource Integrity format of the file downloaded. + +This must match the checksum of the file downloaded. _It is a security risk +to omit the checksum as remote files can change._ At best omitting this +field will make your build non-hermetic. It is optional to make development +easier but either this attribute or `sha256` should be set before shipping. + +</p> +</td> +</tr> +<tr id="http_archive-netrc"> +<td><code>netrc</code></td> +<td> + +String; optional + +<p> + +Location of the .netrc file to use for authentication + +</p> +</td> +</tr> +<tr id="http_archive-patch_args"> +<td><code>patch_args</code></td> +<td> + +List of strings; optional + +<p> + +The arguments given to the patch tool. Defaults to -p0 (see the `patch_strip` attribute), however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch_tool attribute is not specified, `patch` will be used. This only affects patch files in the `patches` attribute. + +</p> +</td> +</tr> +<tr id="http_archive-patch_cmds"> +<td><code>patch_cmds</code></td> +<td> + +List of strings; optional + +<p> + +Sequence of Bash commands to be applied on Linux/Macos after patches are applied. + +</p> +</td> +</tr> +<tr id="http_archive-patch_cmds_win"> +<td><code>patch_cmds_win</code></td> +<td> + +List of strings; optional + +<p> + +Sequence of Powershell commands to be applied on Windows after patches are applied. If this attribute is not set, patch_cmds will be executed on Windows, which requires Bash binary to exist. + +</p> +</td> +</tr> +<tr id="http_archive-patch_strip"> +<td><code>patch_strip</code></td> +<td> + +Integer; optional + +<p> + +When set to `N`, this is equivalent to inserting `-pN` to the beginning of `patch_args`. + +</p> +</td> +</tr> +<tr id="http_archive-patch_tool"> +<td><code>patch_tool</code></td> +<td> + +String; optional + +<p> + +The patch(1) utility to use. If this is specified, Bazel will use the specified patch tool instead of the Bazel-native patch implementation. + +</p> +</td> +</tr> +<tr id="http_archive-patches"> +<td><code>patches</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">List of labels</a>; optional + +<p> + +A list of files that are to be applied as patches after extracting the archive. By default, it uses the Bazel-native patch implementation which doesn't support fuzz match and binary patch, but Bazel will fall back to use patch command line tool if `patch_tool` attribute is specified or there are arguments other than `-p` in `patch_args` attribute. + +</p> +</td> +</tr> +<tr id="http_archive-remote_file_integrity"> +<td><code>remote_file_integrity</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +A map of file relative paths (key) to its integrity value (value). These relative paths should map to the files (key) in the `remote_file_urls` attribute. + +</p> +</td> +</tr> +<tr id="http_archive-remote_file_urls"> +<td><code>remote_file_urls</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a>; optional + +<p> + +A map of relative paths (key) to a list of URLs (value) that are to be downloaded +and made available as overlaid files on the repo. This is useful when you want to add REPO.bazel or +BUILD.bazel files atop an existing repository. The files are downloaded before `files` are +symlinked and patches (`remote_patches`, `patches`) are applied. The list of URLs should all be +possible mirrors of the same file. The URLs are tried in order until one succeeds. Existing files +will be overwritten. + +</p> +</td> +</tr> +<tr id="http_archive-remote_module_file_integrity"> +<td><code>remote_module_file_integrity</code></td> +<td> + +String; optional + +<p> + +For internal use only. + +</p> +</td> +</tr> +<tr id="http_archive-remote_module_file_urls"> +<td><code>remote_module_file_urls</code></td> +<td> + +List of strings; optional + +<p> + +For internal use only. + +</p> +</td> +</tr> +<tr id="http_archive-remote_patch_strip"> +<td><code>remote_patch_strip</code></td> +<td> + +Integer; optional + +<p> + +The number of leading slashes to be stripped from the file name in the remote patches. + +</p> +</td> +</tr> +<tr id="http_archive-remote_patches"> +<td><code>remote_patches</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +A map of patch file URL to its integrity value, they are applied after extracting the archive and before applying patch files from the `patches` attribute. It uses the Bazel-native patch implementation, you can specify the patch strip number with `remote_patch_strip` + +</p> +</td> +</tr> +<tr id="http_archive-repo_mapping"> +<td><code>repo_mapping</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. + +For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). + +This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). + +</p> +</td> +</tr> +<tr id="http_archive-sha256"> +<td><code>sha256</code></td> +<td> + +String; optional + +<p> + +The expected SHA-256 of the file downloaded. + +This must match the SHA-256 of the file downloaded. _It is a security risk +to omit the SHA-256 as remote files can change._ At best omitting this +field will make your build non-hermetic. It is optional to make development +easier but either this attribute or `integrity` should be set before shipping. + +</p> +</td> +</tr> +<tr id="http_archive-strip_prefix"> +<td><code>strip_prefix</code></td> +<td> + +String; optional + +<p> + +A directory prefix to strip from the extracted files. + +Many archives contain a top-level directory that contains all of the useful +files in archive. Instead of needing to specify this prefix over and over +in the `build_file`, this field can be used to strip it from all of the +extracted files. + +For example, suppose you are using `foo-lib-latest.zip`, which contains the +directory `foo-lib-1.2.3/` under which there is a `WORKSPACE` file and are +`src/`, `lib/`, and `test/` directories that contain the actual code you +wish to build. Specify `strip_prefix = "foo-lib-1.2.3"` to use the +`foo-lib-1.2.3` directory as your top-level directory. + +Note that if there are files outside of this directory, they will be +discarded and inaccessible (e.g., a top-level license file). This includes +files/directories that start with the prefix but are not in the directory +(e.g., `foo-lib-1.2.3.release-notes`). If the specified prefix does not +match a directory in the archive, Bazel will return an error. + +</p> +</td> +</tr> +<tr id="http_archive-type"> +<td><code>type</code></td> +<td> + +String; optional + +<p> + +The archive type of the downloaded file. + +By default, the archive type is determined from the file extension of the +URL. If the file has no extension, you can explicitly specify one of the +following: `"zip"`, `"jar"`, `"war"`, `"aar"`, `"tar"`, `"tar.gz"`, `"tgz"`, +`"tar.xz"`, `"txz"`, `"tar.zst"`, `"tzst"`, `"tar.bz2"`, `"ar"`, or `"deb"`. + +</p> +</td> +</tr> +<tr id="http_archive-url"> +<td><code>url</code></td> +<td> + +String; optional + +<p> + +A URL to a file that will be made available to Bazel. + +This must be a file, http or https URL. Redirections are followed. +Authentication is not supported. + +More flexibility can be achieved by the urls parameter that allows +to specify alternative URLs to fetch from. + +</p> +</td> +</tr> +<tr id="http_archive-urls"> +<td><code>urls</code></td> +<td> + +List of strings; optional + +<p> + +A list of URLs to a file that will be made available to Bazel. + +Each entry must be a file, http or https URL. Redirections are followed. +Authentication is not supported. + +URLs are tried in order until one succeeds, so you should list local mirrors first. +If all downloads fail, the rule will fail. + +</p> +</td> +</tr> +<tr id="http_archive-workspace_file"> +<td><code>workspace_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +No-op attribute; do not use. + +</p> +</td> +</tr> +<tr id="http_archive-workspace_file_content"> +<td><code>workspace_file_content</code></td> +<td> + +String; optional + +<p> + +No-op attribute; do not use. + +</p> +</td> +</tr> +</tbody> +</table> + +**ENVIRONMENT VARIABLES** + +This repository rule depends on the following environment variables: + +* `BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID` + + +<a id="http_file"></a> + +## http_file + +``` +load("@bazel//tools/build_defs/repo:http.bzl", "http_file") + +http_file(<a href="#http_file-name">name</a>, <a href="#http_file-auth_patterns">auth_patterns</a>, <a href="#http_file-canonical_id">canonical_id</a>, <a href="#http_file-downloaded_file_path">downloaded_file_path</a>, <a href="#http_file-executable">executable</a>, <a href="#http_file-integrity">integrity</a>, <a href="#http_file-netrc">netrc</a>, + <a href="#http_file-repo_mapping">repo_mapping</a>, <a href="#http_file-sha256">sha256</a>, <a href="#http_file-url">url</a>, <a href="#http_file-urls">urls</a>) +``` + +Downloads a file from a URL and makes it available to be used as a file +group. + +Examples: + Suppose you need to have a debian package for your custom rules. This package + is available from http://example.com/package.deb. Then you can add to your + WORKSPACE file: + + ```python + load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") + + http_file( + name = "my_deb", + url = "http://example.com/package.deb", + sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + ) + ``` + + Targets would specify `@my_deb//file` as a dependency to depend on this file. + +**ATTRIBUTES** + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="http_file-name"> +<td><code>name</code></td> +<td> + +<a href="https://bazel.build/concepts/labels#target-names">Name</a>; required + +<p> + +A unique name for this repository. + +</p> +</td> +</tr> +<tr id="http_file-auth_patterns"> +<td><code>auth_patterns</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +An optional dict mapping host names to custom authorization patterns. + +If a URL's host name is present in this dict the value will be used as a pattern when +generating the authorization header for the http request. This enables the use of custom +authorization schemes used in a lot of common cloud storage providers. + +The pattern currently supports 2 tokens: <code><login></code> and +<code><password></code>, which are replaced with their equivalent value +in the netrc file for the same host name. After formatting, the result is set +as the value for the <code>Authorization</code> field of the HTTP request. + +Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token: + +``` +auth_patterns = { + "storage.cloudprovider.com": "Bearer <password>" +} +``` + +netrc: + +``` +machine storage.cloudprovider.com + password RANDOM-TOKEN +``` + +The final HTTP request would have the following header: + +``` +Authorization: Bearer RANDOM-TOKEN +``` + +</p> +</td> +</tr> +<tr id="http_file-canonical_id"> +<td><code>canonical_id</code></td> +<td> + +String; optional + +<p> + +A canonical ID of the file downloaded. + +If specified and non-empty, Bazel will not take the file from cache, unless it +was added to the cache by a request with the same canonical ID. + +If unspecified or empty, Bazel by default uses the URLs of the file as the +canonical ID. This helps catch the common mistake of updating the URLs without +also updating the hash, resulting in builds that succeed locally but fail on +machines without the file in the cache. This behavior can be disabled with +--repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0. + +</p> +</td> +</tr> +<tr id="http_file-downloaded_file_path"> +<td><code>downloaded_file_path</code></td> +<td> + +String; optional + +<p> + +Path assigned to the file downloaded + +</p> +</td> +</tr> +<tr id="http_file-executable"> +<td><code>executable</code></td> +<td> + +Boolean; optional + +<p> + +If the downloaded file should be made executable. + +</p> +</td> +</tr> +<tr id="http_file-integrity"> +<td><code>integrity</code></td> +<td> + +String; optional + +<p> + +Expected checksum in Subresource Integrity format of the file downloaded. + +This must match the checksum of the file downloaded. _It is a security risk +to omit the checksum as remote files can change._ At best omitting this +field will make your build non-hermetic. It is optional to make development +easier but either this attribute or `sha256` should be set before shipping. + +</p> +</td> +</tr> +<tr id="http_file-netrc"> +<td><code>netrc</code></td> +<td> + +String; optional + +<p> + +Location of the .netrc file to use for authentication + +</p> +</td> +</tr> +<tr id="http_file-repo_mapping"> +<td><code>repo_mapping</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. + +For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). + +This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). + +</p> +</td> +</tr> +<tr id="http_file-sha256"> +<td><code>sha256</code></td> +<td> + +String; optional + +<p> + +The expected SHA-256 of the file downloaded. + +This must match the SHA-256 of the file downloaded. _It is a security risk +to omit the SHA-256 as remote files can change._ At best omitting this +field will make your build non-hermetic. It is optional to make development +easier but should be set before shipping. + +</p> +</td> +</tr> +<tr id="http_file-url"> +<td><code>url</code></td> +<td> + +String; optional + +<p> + +A URL to a file that will be made available to Bazel. + +This must be a file, http or https URL. Redirections are followed. +Authentication is not supported. + +More flexibility can be achieved by the urls parameter that allows +to specify alternative URLs to fetch from. + +</p> +</td> +</tr> +<tr id="http_file-urls"> +<td><code>urls</code></td> +<td> + +List of strings; optional + +<p> + +A list of URLs to a file that will be made available to Bazel. + +Each entry must be a file, http or https URL. Redirections are followed. +Authentication is not supported. + +URLs are tried in order until one succeeds, so you should list local mirrors first. +If all downloads fail, the rule will fail. + +</p> +</td> +</tr> +</tbody> +</table> + +**ENVIRONMENT VARIABLES** + +This repository rule depends on the following environment variables: + +* `BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID` + + +<a id="http_jar"></a> + +## http_jar + +``` +load("@bazel//tools/build_defs/repo:http.bzl", "http_jar") + +http_jar(<a href="#http_jar-name">name</a>, <a href="#http_jar-auth_patterns">auth_patterns</a>, <a href="#http_jar-canonical_id">canonical_id</a>, <a href="#http_jar-downloaded_file_name">downloaded_file_name</a>, <a href="#http_jar-integrity">integrity</a>, <a href="#http_jar-netrc">netrc</a>, <a href="#http_jar-repo_mapping">repo_mapping</a>, + <a href="#http_jar-sha256">sha256</a>, <a href="#http_jar-url">url</a>, <a href="#http_jar-urls">urls</a>) +``` + +Downloads a jar from a URL and makes it available as java_import + +Downloaded files must have a .jar extension. + +Examples: + Suppose the current repository contains the source code for a chat program, rooted at the + directory `~/chat-app`. It needs to depend on an SSL library which is available from + `http://example.com/openssl-0.2.jar`. + + Targets in the `~/chat-app` repository can depend on this target if the following lines are + added to `~/chat-app/WORKSPACE`: + + ```python + load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_jar") + + http_jar( + name = "my_ssl", + url = "http://example.com/openssl-0.2.jar", + sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + ) + ``` + + Targets would specify `@my_ssl//jar` as a dependency to depend on this jar. + + You may also reference files on the current system (localhost) by using "file:///path/to/file" + if you are on Unix-based systems. If you're on Windows, use "file:///c:/path/to/file". In both + examples, note the three slashes (`/`) -- the first two slashes belong to `file://` and the third + one belongs to the absolute path to the file. + +**ATTRIBUTES** + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="http_jar-name"> +<td><code>name</code></td> +<td> + +<a href="https://bazel.build/concepts/labels#target-names">Name</a>; required + +<p> + +A unique name for this repository. + +</p> +</td> +</tr> +<tr id="http_jar-auth_patterns"> +<td><code>auth_patterns</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +An optional dict mapping host names to custom authorization patterns. + +If a URL's host name is present in this dict the value will be used as a pattern when +generating the authorization header for the http request. This enables the use of custom +authorization schemes used in a lot of common cloud storage providers. + +The pattern currently supports 2 tokens: <code><login></code> and +<code><password></code>, which are replaced with their equivalent value +in the netrc file for the same host name. After formatting, the result is set +as the value for the <code>Authorization</code> field of the HTTP request. + +Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token: + +``` +auth_patterns = { + "storage.cloudprovider.com": "Bearer <password>" +} +``` + +netrc: + +``` +machine storage.cloudprovider.com + password RANDOM-TOKEN +``` + +The final HTTP request would have the following header: + +``` +Authorization: Bearer RANDOM-TOKEN +``` + +</p> +</td> +</tr> +<tr id="http_jar-canonical_id"> +<td><code>canonical_id</code></td> +<td> + +String; optional + +<p> + +A canonical ID of the file downloaded. + +If specified and non-empty, Bazel will not take the file from cache, unless it +was added to the cache by a request with the same canonical ID. + +If unspecified or empty, Bazel by default uses the URLs of the file as the +canonical ID. This helps catch the common mistake of updating the URLs without +also updating the hash, resulting in builds that succeed locally but fail on +machines without the file in the cache. This behavior can be disabled with +--repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0. + +</p> +</td> +</tr> +<tr id="http_jar-downloaded_file_name"> +<td><code>downloaded_file_name</code></td> +<td> + +String; optional + +<p> + +Filename assigned to the jar downloaded + +</p> +</td> +</tr> +<tr id="http_jar-integrity"> +<td><code>integrity</code></td> +<td> + +String; optional + +<p> + +Expected checksum in Subresource Integrity format of the file downloaded. + +This must match the checksum of the file downloaded. _It is a security risk +to omit the checksum as remote files can change._ At best omitting this +field will make your build non-hermetic. It is optional to make development +easier but either this attribute or `sha256` should be set before shipping. + +</p> +</td> +</tr> +<tr id="http_jar-netrc"> +<td><code>netrc</code></td> +<td> + +String; optional + +<p> + +Location of the .netrc file to use for authentication + +</p> +</td> +</tr> +<tr id="http_jar-repo_mapping"> +<td><code>repo_mapping</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. + +For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). + +This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). + +</p> +</td> +</tr> +<tr id="http_jar-sha256"> +<td><code>sha256</code></td> +<td> + +String; optional + +<p> + +The expected SHA-256 of the file downloaded. + +This must match the SHA-256 of the file downloaded. _It is a security risk +to omit the SHA-256 as remote files can change._ At best omitting this +field will make your build non-hermetic. It is optional to make development +easier but either this attribute or `integrity` should be set before shipping. + +</p> +</td> +</tr> +<tr id="http_jar-url"> +<td><code>url</code></td> +<td> + +String; optional + +<p> + +A URL to a file that will be made available to Bazel. + +This must be a file, http or https URL. Redirections are followed. +Authentication is not supported. + +More flexibility can be achieved by the urls parameter that allows +to specify alternative URLs to fetch from. + +The URL must end in `.jar`. + +</p> +</td> +</tr> +<tr id="http_jar-urls"> +<td><code>urls</code></td> +<td> + +List of strings; optional + +<p> + +A list of URLs to a file that will be made available to Bazel. + +Each entry must be a file, http or https URL. Redirections are followed. +Authentication is not supported. + +URLs are tried in order until one succeeds, so you should list local mirrors first. +If all downloads fail, the rule will fail. + +All URLs must end in `.jar`. + +</p> +</td> +</tr> +</tbody> +</table> + +**ENVIRONMENT VARIABLES** + +This repository rule depends on the following environment variables: + +* `BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID` + + diff --git a/rules/lib/repo/index.mdx b/rules/lib/repo/index.mdx new file mode 100644 index 0000000..35fb615 --- /dev/null +++ b/rules/lib/repo/index.mdx @@ -0,0 +1,12 @@ +--- +title: 'Repository Rules' +--- + + +* [Rules related to git](git) +* [Rules related to http](http) +* [Rules related to local directories](local) + +# Generic functions for repository rule authors + +* [Utility functions on patching](utils) diff --git a/rules/lib/repo/local.mdx b/rules/lib/repo/local.mdx new file mode 100644 index 0000000..211e727 --- /dev/null +++ b/rules/lib/repo/local.mdx @@ -0,0 +1,204 @@ +--- +title: 'local repository rules' +--- + + + +The following functions can be loaded from +`@bazel_tools//tools/build_defs/repo:local.bzl`. +// Generated with Stardoc: http://skydoc.bazel.build + +Rules for making directories in the local filesystem available as repos. + +### Setup + +To use these rules in a module extension, load them in your .bzl file and then call them from your +extension's implementation function. For example, to use `local_repository`: + +```python +load("@bazel_tools//tools/build_defs/repo:local.bzl", "local_repository") + +def _my_extension_impl(mctx): + local_repository(name = "foo", path = "foo") + +my_extension = module_extension(implementation = _my_extension_impl) +``` + +Alternatively, you can directly call these repo rules in your MODULE.bazel file with +`use_repo_rule`: + +```python +local_repository = use_repo_rule("@bazel_tools//tools/build_defs/repo:local.bzl", "local_repository") +local_repository(name = "foo", path = "foo") +``` + +<a id="local_repository"></a> + +## local_repository + +``` +load("@bazel//tools/build_defs/repo:local.bzl", "local_repository") + +local_repository(<a href="#local_repository-name">name</a>, <a href="#local_repository-path">path</a>, <a href="#local_repository-repo_mapping">repo_mapping</a>) +``` + +Makes a local directory that already contains Bazel files available as a repo. This directory should contain Bazel BUILD files and a repo boundary file already. If it doesn't contain these files, consider using [`new_local_repository`](#new_local_repository) instead. + +**ATTRIBUTES** + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="local_repository-name"> +<td><code>name</code></td> +<td> + +<a href="https://bazel.build/concepts/labels#target-names">Name</a>; required + +<p> + +A unique name for this repository. + +</p> +</td> +</tr> +<tr id="local_repository-path"> +<td><code>path</code></td> +<td> + +String; required + +<p> + +The path to the directory to make available as a repo. + +The path can be either absolute, or relative to the workspace root. + +</p> +</td> +</tr> +<tr id="local_repository-repo_mapping"> +<td><code>repo_mapping</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. + +For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). + +This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). + +</p> +</td> +</tr> +</tbody> +</table> + + +<a id="new_local_repository"></a> + +## new_local_repository + +``` +load("@bazel//tools/build_defs/repo:local.bzl", "new_local_repository") + +new_local_repository(<a href="#new_local_repository-name">name</a>, <a href="#new_local_repository-build_file">build_file</a>, <a href="#new_local_repository-build_file_content">build_file_content</a>, <a href="#new_local_repository-path">path</a>, <a href="#new_local_repository-repo_mapping">repo_mapping</a>) +``` + +Makes a local directory that doesn't contain Bazel files available as a repo. This directory need not contain Bazel BUILD files or a repo boundary file; they will be created by this repo rule. If the directory already contains Bazel files, consider using [`local_repository`](#local_repository) instead. + +**ATTRIBUTES** + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="new_local_repository-name"> +<td><code>name</code></td> +<td> + +<a href="https://bazel.build/concepts/labels#target-names">Name</a>; required + +<p> + +A unique name for this repository. + +</p> +</td> +</tr> +<tr id="new_local_repository-build_file"> +<td><code>build_file</code></td> +<td> + +<a href="https://bazel.build/concepts/labels">Label</a>; optional + +<p> + +A file to use as a BUILD file for this repo. + +Exactly one of `build_file` and `build_file_content` must be specified. + +The file addressed by this label does not need to be named BUILD, but can be. Something like `BUILD.new-repo-name` may work well to distinguish it from actual BUILD files. + +</p> +</td> +</tr> +<tr id="new_local_repository-build_file_content"> +<td><code>build_file_content</code></td> +<td> + +String; optional + +<p> + +The content of the BUILD file to be created for this repo. + +Exactly one of `build_file` and `build_file_content` must be specified. + +</p> +</td> +</tr> +<tr id="new_local_repository-path"> +<td><code>path</code></td> +<td> + +String; required + +<p> + +The path to the directory to make available as a repo. + +The path can be either absolute, or relative to the workspace root. + +</p> +</td> +</tr> +<tr id="new_local_repository-repo_mapping"> +<td><code>repo_mapping</code></td> +<td> + +<a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a>; optional + +<p> + +In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. + +For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). + +This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). + +</p> +</td> +</tr> +</tbody> +</table> + + diff --git a/rules/lib/repo/utils.mdx b/rules/lib/repo/utils.mdx new file mode 100644 index 0000000..1860b74 --- /dev/null +++ b/rules/lib/repo/utils.mdx @@ -0,0 +1,747 @@ +--- +title: 'utils repository rules' +--- + + + +The following functions can be loaded from +`@bazel_tools//tools/build_defs/repo:utils.bzl`. +// Generated with Stardoc: http://skydoc.bazel.build + +Utils for manipulating external repositories, once fetched. + +### Setup + +These utilities are intended to be used by other repository rules. They +can be loaded as follows. + +```python +load( + "@bazel_tools//tools/build_defs/repo:utils.bzl", + "workspace_and_buildfile", + "patch", + "update_attrs", +) +``` + +<a id="download_remote_files"></a> + +## download_remote_files + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "download_remote_files") + +download_remote_files(<a href="#download_remote_files-ctx">ctx</a>, <a href="#download_remote_files-auth">auth</a>) +``` + +Utility function for downloading remote files. + +This rule is intended to be used in the implementation function of +a repository rule. It assumes the parameters `remote_file_urls` and +`remote_file_integrity` to be present in `ctx.attr`. + +Existing files will be overwritten. + + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="download_remote_files-ctx"> +<td><code>ctx</code></td> +<td> + +required. + +<p> + +The repository context of the repository rule calling this utility +function. + +</p> +</td> +</tr> +<tr id="download_remote_files-auth"> +<td><code>auth</code></td> +<td> + +optional. +default is <code>None</code> + +<p> + +An optional dict specifying authentication information for some of the URLs. + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +dict mapping file paths to a download info. + + + +<a id="get_auth"></a> + +## get_auth + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "get_auth") + +get_auth(<a href="#get_auth-ctx">ctx</a>, <a href="#get_auth-urls">urls</a>) +``` + +Utility function to obtain the correct auth dict for a list of urls from .netrc file. + +Support optional netrc and auth_patterns attributes if available. + + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="get_auth-ctx"> +<td><code>ctx</code></td> +<td> + +required. + +<p> + +The repository context of the repository rule calling this utility +function. + +</p> +</td> +</tr> +<tr id="get_auth-urls"> +<td><code>urls</code></td> +<td> + +required. + +<p> + +the list of urls to read + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +the auth dict which can be passed to repository_ctx.download + + + +<a id="maybe"></a> + +## maybe + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "maybe") + +maybe(<a href="#maybe-repo_rule">repo_rule</a>, <a href="#maybe-name">name</a>, <a href="#maybe-kwargs">**kwargs</a>) +``` + +Utility function for only adding a repository if it's not already present. + +This is to implement safe repositories.bzl macro documented in +https://bazel.build/rules/deploying#dependencies. + + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="maybe-repo_rule"> +<td><code>repo_rule</code></td> +<td> + +required. + +<p> + +repository rule function. + +</p> +</td> +</tr> +<tr id="maybe-name"> +<td><code>name</code></td> +<td> + +required. + +<p> + +name of the repository to create. + +</p> +</td> +</tr> +<tr id="maybe-kwargs"> +<td><code>kwargs</code></td> +<td> + +optional. + +<p> + +remaining arguments that are passed to the repo_rule function. + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +Nothing, defines the repository when needed as a side-effect. + + + +<a id="parse_netrc"></a> + +## parse_netrc + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "parse_netrc") + +parse_netrc(<a href="#parse_netrc-contents">contents</a>, <a href="#parse_netrc-filename">filename</a>) +``` + +Utility function to parse at least a basic .netrc file. + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="parse_netrc-contents"> +<td><code>contents</code></td> +<td> + +required. + +<p> + +input for the parser. + +</p> +</td> +</tr> +<tr id="parse_netrc-filename"> +<td><code>filename</code></td> +<td> + +optional. +default is <code>"a .netrc file"</code> + +<p> + +filename to use in error messages, if any. + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +dict mapping a machine names to a dict with the information provided +about them + + + +<a id="patch"></a> + +## patch + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "patch") + +patch(<a href="#patch-ctx">ctx</a>, <a href="#patch-patches">patches</a>, <a href="#patch-patch_cmds">patch_cmds</a>, <a href="#patch-patch_cmds_win">patch_cmds_win</a>, <a href="#patch-patch_tool">patch_tool</a>, <a href="#patch-patch_args">patch_args</a>, <a href="#patch-auth">auth</a>) +``` + +Implementation of patching an already extracted repository. + +This rule is intended to be used in the implementation function of +a repository rule. If the parameters `patches`, `patch_tool`, +`patch_args`, `patch_cmds` and `patch_cmds_win` are not specified +then they are taken from `ctx.attr`. + + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="patch-ctx"> +<td><code>ctx</code></td> +<td> + +required. + +<p> + +The repository context of the repository rule calling this utility +function. + +</p> +</td> +</tr> +<tr id="patch-patches"> +<td><code>patches</code></td> +<td> + +optional. +default is <code>None</code> + +<p> + +The patch files to apply. List of strings, Labels, or paths. + +</p> +</td> +</tr> +<tr id="patch-patch_cmds"> +<td><code>patch_cmds</code></td> +<td> + +optional. +default is <code>None</code> + +<p> + +Bash commands to run for patching, passed one at a +time to bash -c. List of strings + +</p> +</td> +</tr> +<tr id="patch-patch_cmds_win"> +<td><code>patch_cmds_win</code></td> +<td> + +optional. +default is <code>None</code> + +<p> + +Powershell commands to run for patching, passed +one at a time to powershell /c. List of strings. If the +boolean value of this parameter is false, patch_cmds will be +used and this parameter will be ignored. + +</p> +</td> +</tr> +<tr id="patch-patch_tool"> +<td><code>patch_tool</code></td> +<td> + +optional. +default is <code>None</code> + +<p> + +Path of the patch tool to execute for applying +patches. String. + +</p> +</td> +</tr> +<tr id="patch-patch_args"> +<td><code>patch_args</code></td> +<td> + +optional. +default is <code>None</code> + +<p> + +Arguments to pass to the patch tool. List of strings. + +</p> +</td> +</tr> +<tr id="patch-auth"> +<td><code>auth</code></td> +<td> + +optional. +default is <code>None</code> + +<p> + +An optional dict specifying authentication information for some of the URLs. + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +dict mapping remote patch URLs to a download info. + + + +<a id="read_netrc"></a> + +## read_netrc + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "read_netrc") + +read_netrc(<a href="#read_netrc-ctx">ctx</a>, <a href="#read_netrc-filename">filename</a>) +``` + +Utility function to parse at least a basic .netrc file. + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="read_netrc-ctx"> +<td><code>ctx</code></td> +<td> + +required. + +<p> + +The repository context of the repository rule calling this utility +function. + +</p> +</td> +</tr> +<tr id="read_netrc-filename"> +<td><code>filename</code></td> +<td> + +required. + +<p> + +the name of the .netrc file to read + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +dict mapping a machine names to a dict with the information provided +about them + + + +<a id="read_user_netrc"></a> + +## read_user_netrc + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "read_user_netrc") + +read_user_netrc(<a href="#read_user_netrc-ctx">ctx</a>) +``` + +Read user's default netrc file. + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="read_user_netrc-ctx"> +<td><code>ctx</code></td> +<td> + +required. + +<p> + +The repository context of the repository rule calling this utility function. + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +dict mapping a machine names to a dict with the information provided about them. + + + +<a id="symlink_files"></a> + +## symlink_files + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "symlink_files") + +symlink_files(<a href="#symlink_files-ctx">ctx</a>) +``` + +Utility function for symlinking local files. + +This is intended to be used in the implementation function of a repository rule. It assumes the +parameter `files` is present in `ctx.attr`. + +Existing files will be overwritten. + + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="symlink_files-ctx"> +<td><code>ctx</code></td> +<td> + +required. + +<p> + +The repository context of the repository rule calling this utility +function. + +</p> +</td> +</tr> +</tbody> +</table> + + +<a id="update_attrs"></a> + +## update_attrs + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "update_attrs") + +update_attrs(<a href="#update_attrs-orig">orig</a>, <a href="#update_attrs-keys">keys</a>, <a href="#update_attrs-override">override</a>) +``` + +Utility function for altering and adding the specified attributes to a particular repository rule invocation. + + This is used to make a rule reproducible. + + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="update_attrs-orig"> +<td><code>orig</code></td> +<td> + +required. + +<p> + +dict of actually set attributes (either explicitly or implicitly) +by a particular rule invocation + +</p> +</td> +</tr> +<tr id="update_attrs-keys"> +<td><code>keys</code></td> +<td> + +required. + +<p> + +complete set of attributes defined on this rule + +</p> +</td> +</tr> +<tr id="update_attrs-override"> +<td><code>override</code></td> +<td> + +required. + +<p> + +dict of attributes to override or add to orig + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +dict of attributes with the keys from override inserted/updated + + + +<a id="use_netrc"></a> + +## use_netrc + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "use_netrc") + +use_netrc(<a href="#use_netrc-netrc">netrc</a>, <a href="#use_netrc-urls">urls</a>, <a href="#use_netrc-patterns">patterns</a>) +``` + +Compute an auth dict from a parsed netrc file and a list of URLs. + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="use_netrc-netrc"> +<td><code>netrc</code></td> +<td> + +required. + +<p> + +a netrc file already parsed to a dict, e.g., as obtained from +read_netrc + +</p> +</td> +</tr> +<tr id="use_netrc-urls"> +<td><code>urls</code></td> +<td> + +required. + +<p> + +a list of URLs. + +</p> +</td> +</tr> +<tr id="use_netrc-patterns"> +<td><code>patterns</code></td> +<td> + +required. + +<p> + +optional dict of url to authorization patterns + +</p> +</td> +</tr> +</tbody> +</table> + +### Returns + +dict suitable as auth argument for ctx.download; more precisely, the dict +will map all URLs where the netrc file provides login and password to a +dict containing the corresponding login, password and optional authorization pattern, +as well as the mapping of "type" to "basic" or "pattern". + + + +<a id="workspace_and_buildfile"></a> + +## workspace_and_buildfile + +``` +load("@bazel//tools/build_defs/repo:utils.bzl", "workspace_and_buildfile") + +workspace_and_buildfile(<a href="#workspace_and_buildfile-ctx">ctx</a>) +``` + +Utility function for writing a BUILD file. + +This rule is intended to be used in the implementation function of a +repository rule. +It assumes the parameters `name`, `build_file`, and `build_file_content` to +be present in `ctx.attr`; the latter two possibly with value None. + + +### Parameters + +<table class="params-table"> +<colgroup> +<col class="col-param" /> +<col class="col-description" /> +</colgroup> +<tbody> +<tr id="workspace_and_buildfile-ctx"> +<td><code>ctx</code></td> +<td> + +required. + +<p> + +The repository context of the repository rule calling this utility +function. + +</p> +</td> +</tr> +</tbody> +</table> + + diff --git a/rules/lib/toplevel.mdx b/rules/lib/toplevel.mdx index 19d0d0e..6f38710 100644 --- a/rules/lib/toplevel.mdx +++ b/rules/lib/toplevel.mdx @@ -1,18 +1,18 @@ --- -title: 'toplevel' +title: 'Top-level Modules' --- This section lists top-level modules. These symbols are available only in .bzl files. -* [apple\_common](./rules/lib/toplevel/apple_common) -* [attr](./rules/lib/toplevel/attr) -* [cc\_common](./rules/lib/toplevel/cc_common) -* [config](./rules/lib/toplevel/config) -* [config\_common](./rules/lib/toplevel/config_common) -* [coverage\_common](./rules/lib/toplevel/coverage_common) -* [java\_common](./rules/lib/toplevel/java_common) -* [native](./rules/lib/toplevel/native) -* [platform\_common](./rules/lib/toplevel/platform_common) -* [proto](./rules/lib/toplevel/proto) -* [testing](./rules/lib/toplevel/testing) \ No newline at end of file +- [apple\_common](/rules/lib/toplevel/apple_common) +- [attr](/rules/lib/toplevel/attr) +- [cc\_common](/rules/lib/toplevel/cc_common) +- [config](/rules/lib/toplevel/config) +- [config\_common](/rules/lib/toplevel/config_common) +- [coverage\_common](/rules/lib/toplevel/coverage_common) +- [java\_common](/rules/lib/toplevel/java_common) +- [native](/rules/lib/toplevel/native) +- [platform\_common](/rules/lib/toplevel/platform_common) +- [proto](/rules/lib/toplevel/proto) +- [testing](/rules/lib/toplevel/testing) diff --git a/rules/lib/toplevel/apple_common.mdx b/rules/lib/toplevel/apple_common.mdx index b3355fc..60a7a74 100644 --- a/rules/lib/toplevel/apple_common.mdx +++ b/rules/lib/toplevel/apple_common.mdx @@ -1,20 +1,21 @@ --- -title: 'apple_common' +title: 'apple\_common' --- + Functions for Starlark to access internals of the apple rule implementations. ## Members -* [apple\_host\_system\_env](#apple_host_system_env) -* [apple\_toolchain](#apple_toolchain) -* [dotted\_version](#dotted_version) -* [platform](#platform) -* [platform\_type](#platform_type) -* [target\_apple\_env](#target_apple_env) -* [XcodeProperties](#XcodeProperties) -* [XcodeVersionConfig](#XcodeVersionConfig) +- [apple\_host\_system\_env](#apple_host_system_env) +- [apple\_toolchain](#apple_toolchain) +- [dotted\_version](#dotted_version) +- [platform](#platform) +- [platform\_type](#platform_type) +- [target\_apple\_env](#target_apple_env) +- [XcodeProperties](#XcodeProperties) +- [XcodeVersionConfig](#XcodeVersionConfig) ## apple\_host\_system\_env @@ -22,13 +23,16 @@ Functions for Starlark to access internals of the apple rule implementations. dict apple_common.apple_host_system_env(xcode_config) ``` -Returns a [dict](../core/dict.mdx) of environment variables that should be set for actions that need to run build tools on an Apple host system, such as the version of Xcode that should be used. The keys are variable names and the values are their corresponding values. + Returns a [dict](../core/dict.html) of environment variables that should be set for actions that need to run build tools on an Apple host system, such as the version of Xcode that should be used. The keys are variable names and the values are their corresponding values. + ### Parameters -| Parameter | Description | -| --- | --- | -| `xcode_config` | required A provider containing information about the Xcode configuration. | +ParameterDescription`xcode_config` + required + + A provider containing information about the Xcode configuration. + ## apple\_toolchain @@ -36,7 +40,9 @@ Returns a [dict](../core/dict.mdx) of environment variables that should be set f unknown apple_common.apple_toolchain() ``` -Utilities for resolving items from the apple toolchain. + Utilities for resolving items from the apple toolchain. + + ## dotted\_version @@ -44,13 +50,16 @@ Utilities for resolving items from the apple toolchain. DottedVersion apple_common.dotted_version(version) ``` -Creates a new [DottedVersion](../builtins/DottedVersion.mdx) instance. + Creates a new [DottedVersion](../builtins/DottedVersion.html) instance. + ### Parameters -| Parameter | Description | -| --- | --- | -| `version` | [string](../core/string.mdx); required The string representation of the DottedVersion. | +ParameterDescription`version`[string](../core/string.html); + required + + The string representation of the DottedVersion. + ## platform @@ -58,33 +67,35 @@ Creates a new [DottedVersion](../builtins/DottedVersion.mdx) instance. struct apple_common.platform ``` -An enum-like struct that contains the following fields corresponding to Apple platforms: + An enum-like struct that contains the following fields corresponding to Apple platforms: -* `ios_device` -* `ios_simulator` -* `macos` -* `tvos_device` -* `tvos_simulator` -* `visionos_device` -* `visionos_simulator` -* `watchos_device` -* `watchos_simulator` +- `ios_device` +- `ios_simulator` +- `macos` +- `tvos_device` +- `tvos_simulator` +- `visionos_device` +- `visionos_simulator` +- `watchos_device` +- `watchos_simulator` These values can be passed to methods that expect a platform, like [XcodeVersionConfig.sdk\_version\_for\_platform](../providers/XcodeVersionConfig.html#sdk_version_for_platform). + + ## platform\_type ``` struct apple_common.platform_type ``` -An enum-like struct that contains the following fields corresponding to Apple platform types: + An enum-like struct that contains the following fields corresponding to Apple platform types: -* `ios` -* `macos` -* `tvos` -* `visionos` -* `watchos` +- `ios` +- `macos` +- `tvos` +- `visionos` +- `watchos` These values can be passed to methods that expect a platform type, like the 'apple' configuration fragment's [multi\_arch\_platform](../fragments/apple.html#multi_arch_platform) method. @@ -92,6 +103,7 @@ Example: ``` ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios) + ``` ## target\_apple\_env @@ -100,14 +112,20 @@ ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios) dict apple_common.target_apple_env(xcode_config, platform) ``` -Returns a `dict` of environment variables that should be set for actions that build targets of the given Apple platform type. For example, this dictionary contains variables that denote the platform name and SDK version with which to build. The keys are variable names and the values are their corresponding values. + Returns a `dict` of environment variables that should be set for actions that build targets of the given Apple platform type. For example, this dictionary contains variables that denote the platform name and SDK version with which to build. The keys are variable names and the values are their corresponding values. + ### Parameters -| Parameter | Description | -| --- | --- | -| `xcode_config` | required | -| `platform` | required | +ParameterDescription`xcode_config` + required + + A provider containing information about the Xcode configuration. + `platform` + required + + The apple platform. + ## XcodeProperties @@ -115,13 +133,14 @@ Returns a `dict` of environment variables that should be set for actions that bu Provider apple_common.XcodeProperties ``` -The constructor/key for the `XcodeVersionProperties` provider. + The constructor/key for the `XcodeVersionProperties` provider. -If a target propagates the `XcodeVersionProperties` provider, use this as the key with which to retrieve it. Example: +If a target propagates the `XcodeVersionProperties` provider, use this as the key with which to retrieve it. Example: ``` dep = ctx.attr.deps[0] p = dep[apple_common.XcodeVersionProperties] + ``` ## XcodeVersionConfig @@ -130,4 +149,4 @@ p = dep[apple_common.XcodeVersionProperties] Provider apple_common.XcodeVersionConfig ``` -The constructor/key for the `XcodeVersionConfig` provider. \ No newline at end of file + The constructor/key for the `XcodeVersionConfig` provider. diff --git a/rules/lib/toplevel/attr.mdx b/rules/lib/toplevel/attr.mdx index 2e37d9b..4592343 100644 --- a/rules/lib/toplevel/attr.mdx +++ b/rules/lib/toplevel/attr.mdx @@ -3,6 +3,7 @@ title: 'attr' --- + This is a top-level module for defining the attribute schemas of a rule or aspect. Each function returns an object representing the schema of a single attribute. These objects are used as the values of the `attrs` dictionary argument of [`rule()`](../globals/bzl.html#rule), [`aspect()`](../globals/bzl.html#aspect), [`repository_rule()`](../globals/bzl.html#repository_rule) and [`tag_class()`](../globals/bzl.html#tag_class). See the Rules page for more on [defining](https://bazel.build/extending/rules#attributes) @@ -10,19 +11,19 @@ and [using](https://bazel.build/extending/rules#implementation_function) attribu ## Members -* [bool](#bool) -* [int](#int) -* [int\_list](#int_list) -* [label](#label) -* [label\_keyed\_string\_dict](#label_keyed_string_dict) -* [label\_list](#label_list) -* [output](#output) -* [output\_list](#output_list) -* [string](#string) -* [string\_dict](#string_dict) -* [string\_keyed\_label\_dict](#string_keyed_label_dict) -* [string\_list](#string_list) -* [string\_list\_dict](#string_list_dict) +- [bool](#bool) +- [int](#int) +- [int\_list](#int_list) +- [label](#label) +- [label\_keyed\_string\_dict](#label_keyed_string_dict) +- [label\_list](#label_list) +- [output](#output) +- [output\_list](#output_list) +- [string](#string) +- [string\_dict](#string_dict) +- [string\_keyed\_label\_dict](#string_keyed_label_dict) +- [string\_list](#string_list) +- [string\_list\_dict](#string_list_dict) ## bool @@ -30,16 +31,34 @@ and [using](https://bazel.build/extending/rules#implementation_function) attribu Attribute attr.bool(*, configurable=unbound, default=False, doc=None, mandatory=False) ``` -Creates a schema for a boolean attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`bool`](../core/bool.mdx). + Creates a schema for a boolean attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`bool`](../core/bool.html). + ### Parameters -| Parameter | Description | -| --- | --- | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [bool](../core/bool.mdx); default is `False` A default value to use if no value for this attribute is given when instantiating the rule. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +ParameterDescription`configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[bool](../core/bool.html); + default is `False` + + A default value to use if no value for this attribute is given when instantiating the rule. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + ## int @@ -47,17 +66,38 @@ Creates a schema for a boolean attribute. The corresponding [`ctx.attr`](../buil Attribute attr.int(*, configurable=unbound, default=0, doc=None, mandatory=False, values=[]) ``` -Creates a schema for an integer attribute. The value must be in the signed 32-bit range. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`int`](../core/int.mdx). + Creates a schema for an integer attribute. The value must be in the signed 32-bit range. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [`int`](../core/int.html). + ### Parameters -| Parameter | Description | -| --- | --- | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [int](../core/int.mdx); default is `0` A default value to use if no value for this attribute is given when instantiating the rule. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | -| `values` | [sequence](../core/list.mdx) of [int](../core/int.mdx)s; default is `[]` The list of allowed values for the attribute. An error is raised if any other value is given. | +ParameterDescription`configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[int](../core/int.html); + default is `0` + + A default value to use if no value for this attribute is given when instantiating the rule. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + `values`[sequence](../core/list.html) of [int](../core/int.html) s; + default is `[]` + + The list of allowed values for the attribute. An error is raised if any other value is given. + ## int\_list @@ -65,17 +105,38 @@ Creates a schema for an integer attribute. The value must be in the signed 32-bi Attribute attr.int_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None) ``` -Creates a schema for a list-of-integers attribute. Each element must be in the signed 32-bit range. + Creates a schema for a list-of-integers attribute. Each element must be in the signed 32-bit range. + ### Parameters -| Parameter | Description | -| --- | --- | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | -| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [sequence](../core/list.mdx) of [int](../core/int.mdx)s; default is `[]` A default value to use if no value for this attribute is given when instantiating the rule. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +ParameterDescription`mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + `allow_empty`[bool](../core/bool.html); + default is `True` + + True if the attribute can be empty. + `configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[sequence](../core/list.html) of [int](../core/int.html) s; + default is `[]` + + A default value to use if no value for this attribute is given when instantiating the rule. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + ## label @@ -85,61 +146,167 @@ Attribute attr.label(*, configurable=unbound, default=None, materializer=None, d Creates a schema for a label attribute. This is a dependency attribute. -This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.mdx)s. This allows you to access the providers of the current target's dependencies. +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html) s. This allows you to access the providers of the current target's dependencies. In addition to ordinary source files, this kind of attribute is often used to refer to a tool -- for example, a compiler. Such tools are considered to be dependencies, just like source files. To avoid requiring users to specify the tool's label every time they use the rule in their BUILD files, you can hard-code the label of a canonical tool as the `default` value of this attribute. If you also want to prevent users from overriding this default, you can make the attribute private by giving it a name that starts with an underscore. See the [Rules](https://bazel.build/extending/rules#private-attributes) page for more information. + ### Parameters -| Parameter | Description | -| --- | --- | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [Label](../builtins/Label.mdx); or [string](../core/string.mdx); or [LateBoundDefault](../builtins/LateBoundDefault.mdx); or NativeComputedDefault; or [function](../core/function.mdx); or `None`; default is `None` A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the [`Label`](../builtins/Label.html#Label) function to specify a default value, for example, `attr.label(default = "//a:b")`. | -| `materializer` | [function](../core/function.mdx); default is `None` **Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_dormant_deps` If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` | -| `executable` | [bool](../core/bool.mdx); default is `False` True if the dependency has to be executable. This means the label must refer to an executable file, or to a rule that outputs an executable file. Access the label with `ctx.executable.\<attribute_name\>`. | -| `allow_files` | [bool](../core/bool.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). | -| `allow_single_file` | default is `None` This is similar to `allow_files`, with the restriction that the label must correspond to a single [File](../builtins/File.mdx). Access it through `ctx.file.\<attribute_name\>`. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | -| `skip_validations` | [bool](../core/bool.mdx); default is `False` If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. | -| `providers` | [sequence](../core/list.mdx); default is `[]` The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. | -| `for_dependency_resolution` | default is `unbound` If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. | -| `allow_rules` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. | -| `cfg` | default is `None` [Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. This parameter is required if `executable` is True to guard against accidentally building host tools in the target configuration. `"target"` has no semantic effect, so don't set it when `executable` is False unless it really helps clarify your intentions. | -| `aspects` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` Aspects that should be applied to the dependency or dependencies specified by this attribute. | -| `flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Deprecated, will be removed. | +ParameterDescription`configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[Label](../builtins/Label.html); or [string](../core/string.html); or [LateBoundDefault](../builtins/LateBoundDefault.html); or NativeComputedDefault; or [function](../core/function.html); or `None`; + default is `None` + + A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the [`Label`](../builtins/Label.html#Label) function to specify a default value, for example, `attr.label(default = "//a:b")`. + `materializer`[function](../core/function.html); + default is `None` + +**Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_dormant_deps` + +If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `executable`[bool](../core/bool.html); + default is `False` + + True if the dependency has to be executable. This means the label must refer to an executable file, or to a rule that outputs an executable file. Access the label with `ctx.executable.<attribute_name>`. + `allow_files`[bool](../core/bool.html); or [sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). + `allow_single_file` + default is `None` + + This is similar to `allow_files`, with the restriction that the label must correspond to a single [File](../builtins/File.html). Access it through `ctx.file.<attribute_name>`. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + `skip_validations`[bool](../core/bool.html); + default is `False` + + If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. + `providers`[sequence](../core/list.html); + default is `[]` + + The providers that must be given by any dependency appearing in this attribute. + +The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. + + +`for_dependency_resolution` + default is `unbound` + + If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. + `allow_rules`[sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. + `cfg` + default is `None` + +[Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. This parameter is required if `executable` is True to guard against accidentally building host tools in the target configuration. `"target"` has no semantic effect, so don't set it when `executable` is False unless it really helps clarify your intentions. + `aspects`[sequence](../core/list.html) of [Aspect](../builtins/Aspect.html) s; + default is `[]` + + Aspects that should be applied to the dependency or dependencies specified by this attribute. + `flags`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Deprecated, will be removed. + ## label\_keyed\_string\_dict ``` -Attribute attr.label_keyed_string_dict(allow_empty=True, *, configurable=unbound, default=\{\}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[]) +Attribute attr.label_keyed_string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[]) ``` Creates a schema for an attribute holding a dictionary, where the keys are labels and the values are strings. This is a dependency attribute. -This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html) s. This allows you to access the providers of the current target's dependencies. -At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.mdx)s. This allows you to access the providers of the current target's dependencies. ### Parameters -| Parameter | Description | -| --- | --- | -| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [dict](../core/dict.mdx); or [function](../core/function.mdx); default is `\{\}` A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.label_keyed_string_dict(default = \{"//a:b": "value", "//a:c": "string"\})`. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `allow_files` | [bool](../core/bool.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). | -| `allow_rules` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. | -| `providers` | [sequence](../core/list.mdx); default is `[]` The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. | -| `for_dependency_resolution` | default is `unbound` If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. | -| `flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Deprecated, will be removed. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | -| `skip_validations` | [bool](../core/bool.mdx); default is `False` If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. | -| `cfg` | default is `None` [Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. | -| `aspects` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` Aspects that should be applied to the dependency or dependencies specified by this attribute. | +ParameterDescription`allow_empty`[bool](../core/bool.html); + default is `True` + + True if the attribute can be empty. + `configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[dict](../core/dict.html); or [function](../core/function.html); + default is `{}` + + A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"})`. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `allow_files`[bool](../core/bool.html); or [sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). + `allow_rules`[sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. + `providers`[sequence](../core/list.html); + default is `[]` + + The providers that must be given by any dependency appearing in this attribute. + +The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. + + +`for_dependency_resolution` + default is `unbound` + + If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. + `flags`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Deprecated, will be removed. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + `skip_validations`[bool](../core/bool.html); + default is `False` + + If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. + `cfg` + default is `None` + +[Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. + `aspects`[sequence](../core/list.html) of [Aspect](../builtins/Aspect.html) s; + default is `[]` + + Aspects that should be applied to the dependency or dependencies specified by this attribute. + ## label\_list @@ -147,30 +314,84 @@ At analysis time (within the rule's implementation function), when retrieving th Attribute attr.label_list(allow_empty=True, *, configurable=unbound, default=[], materializer=None, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[]) ``` -Creates a schema for a list-of-labels attribute. This is a dependency attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [list](../core/list.mdx) of [`Target`s](../builtins/Target.mdx). +Creates a schema for a list-of-labels attribute. This is a dependency attribute. The corresponding [`ctx.attr`](../builtins/ctx.html#attr) attribute will be of type [list](../core/list.html) of [`Target` s](../builtins/Target.html). + +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html) s. This allows you to access the providers of the current target's dependencies. -At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.mdx)s. This allows you to access the providers of the current target's dependencies. ### Parameters -| Parameter | Description | -| --- | --- | -| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [sequence](../core/list.mdx) of [Label](../builtins/Label.mdx)s; or [function](../core/function.mdx); default is `[]` A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.label_list(default = ["//a:b", "//a:c"])`. | -| `materializer` | [function](../core/function.mdx); default is `None` **Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_dormant_deps` If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` | -| `allow_files` | [bool](../core/bool.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). | -| `allow_rules` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. | -| `providers` | [sequence](../core/list.mdx); default is `[]` The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. | -| `for_dependency_resolution` | default is `unbound` If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. | -| `flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Deprecated, will be removed. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | -| `skip_validations` | [bool](../core/bool.mdx); default is `False` If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. | -| `cfg` | default is `None` [Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. | -| `aspects` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` Aspects that should be applied to the dependency or dependencies specified by this attribute. | +ParameterDescription`allow_empty`[bool](../core/bool.html); + default is `True` + + True if the attribute can be empty. + `configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[sequence](../core/list.html) of [Label](../builtins/Label.html) s; or [function](../core/function.html); + default is `[]` + + A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.label_list(default = ["//a:b", "//a:c"])`. + `materializer`[function](../core/function.html); + default is `None` + +**Experimental**. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--experimental_dormant_deps` + +If set, the attribute materializes dormant dependencies from the transitive closure. The value of this parameter must be a functon that gets access to the values of the attributes of the rule that either are not dependencies or are marked as available for dependency resolution. It must return either a dormant dependency or a list of them depending on the type of the attribute + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `allow_files`[bool](../core/bool.html); or [sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). + `allow_rules`[sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. + `providers`[sequence](../core/list.html); + default is `[]` + + The providers that must be given by any dependency appearing in this attribute. + +The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. + + +`for_dependency_resolution` + default is `unbound` + + If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. + `flags`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Deprecated, will be removed. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + `skip_validations`[bool](../core/bool.html); + default is `False` + + If true, validation actions of transitive dependencies from this attribute will not run. This is a temporary mitigation and WILL be removed in the future. + `cfg` + default is `None` + +[Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. + `aspects`[sequence](../core/list.html) of [Aspect](../builtins/Aspect.html) s; + default is `[]` + + Aspects that should be applied to the dependency or dependencies specified by this attribute. + ## output @@ -180,16 +401,22 @@ Attribute attr.output(*, doc=None, mandatory=False) Creates a schema for an output (label) attribute. -This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time, the corresponding [`File`](../builtins/File.html) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). -At analysis time, the corresponding [`File`](../builtins/File.mdx) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). ### Parameters -| Parameter | Description | -| --- | --- | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +ParameterDescription`doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + ## output\_list @@ -197,19 +424,28 @@ At analysis time, the corresponding [`File`](../builtins/File.mdx) can be retrie Attribute attr.output_list(allow_empty=True, *, doc=None, mandatory=False) ``` -Creates a schema for a list-of-outputs attribute. + Creates a schema for a list-of-outputs attribute. + +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. -This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +At analysis time, the corresponding [`File`](../builtins/File.html) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). -At analysis time, the corresponding [`File`](../builtins/File.mdx) can be retrieved using [`ctx.outputs`](../builtins/ctx.html#outputs). ### Parameters -| Parameter | Description | -| --- | --- | -| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +ParameterDescription`allow_empty`[bool](../core/bool.html); + default is `True` + + True if the attribute can be empty. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + ## string @@ -217,64 +453,152 @@ At analysis time, the corresponding [`File`](../builtins/File.mdx) can be retrie Attribute attr.string(*, configurable=unbound, default='', doc=None, mandatory=False, values=[]) ``` -Creates a schema for a [string](../core/string.html#attr) attribute. + Creates a schema for a [string](../core/string.html#attr) attribute. + ### Parameters -| Parameter | Description | -| --- | --- | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [string](../core/string.mdx); or NativeComputedDefault; default is `''` A default value to use if no value for this attribute is given when instantiating the rule. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | -| `values` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of allowed values for the attribute. An error is raised if any other value is given. | +ParameterDescription`configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[string](../core/string.html); or NativeComputedDefault; + default is `''` + + A default value to use if no value for this attribute is given when instantiating the rule. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + `values`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + The list of allowed values for the attribute. An error is raised if any other value is given. + ## string\_dict ``` -Attribute attr.string_dict(allow_empty=True, *, configurable=unbound, default=\{\}, doc=None, mandatory=False) +Attribute attr.string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False) ``` -Creates a schema for an attribute holding a dictionary, where the keys and values are strings. + Creates a schema for an attribute holding a dictionary, where the keys and values are strings. + ### Parameters -| Parameter | Description | -| --- | --- | -| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [dict](../core/dict.mdx); default is `\{\}` A default value to use if no value for this attribute is given when instantiating the rule. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | +ParameterDescription`allow_empty`[bool](../core/bool.html); + default is `True` + + True if the attribute can be empty. + `configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[dict](../core/dict.html); + default is `{}` + + A default value to use if no value for this attribute is given when instantiating the rule. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + ## string\_keyed\_label\_dict ``` -Attribute attr.string_keyed_label_dict(allow_empty=True, *, configurable=unbound, default=\{\}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, cfg=None, aspects=[]) +Attribute attr.string_keyed_label_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, cfg=None, aspects=[]) ``` Creates a schema for an attribute whose value is a dictionary where the keys are strings and the values are labels. This is a dependency attribute. -This attribute contains unique [`Label`](../builtins/Label.mdx) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. +This attribute contains unique [`Label`](../builtins/Label.html) values. If a string is supplied in place of a `Label`, it will be converted using the [label constructor](../builtins/Label.html#Label). The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package. + +At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.html) s. This allows you to access the providers of the current target's dependencies. -At analysis time (within the rule's implementation function), when retrieving the attribute value from `ctx.attr`, labels are replaced by the corresponding [`Target`](../builtins/Target.mdx)s. This allows you to access the providers of the current target's dependencies. ### Parameters -| Parameter | Description | -| --- | --- | -| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [dict](../core/dict.mdx); or [function](../core/function.mdx); default is `\{\}` A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.string_keyed_label_dict(default = \{"foo": "//a:b", "bar": "//a:c"\})`. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `allow_files` | [bool](../core/bool.mdx); or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). | -| `allow_rules` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. | -| `providers` | [sequence](../core/list.mdx); default is `[]` The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. | -| `for_dependency_resolution` | default is `unbound` If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. | -| `flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Deprecated, will be removed. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | -| `cfg` | default is `None` [Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. | -| `aspects` | [sequence](../core/list.mdx) of [Aspect](../builtins/Aspect.mdx)s; default is `[]` Aspects that should be applied to the dependency or dependencies specified by this attribute. | +ParameterDescription`allow_empty`[bool](../core/bool.html); + default is `True` + + True if the attribute can be empty. + `configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[dict](../core/dict.html); or [function](../core/function.html); + default is `{}` + + A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the [`Label`](../builtins/Label.html#Label) function to specify default values, for example, `attr.string_keyed_label_dict(default = {"foo": "//a:b", "bar": "//a:c"})`. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `allow_files`[bool](../core/bool.html); or [sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Whether `File` targets are allowed. Can be `True`, `False` (default), or a list of file extensions that are allowed (for example, `[".cc", ".cpp"]`). + `allow_rules`[sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. + `providers`[sequence](../core/list.html); + default is `[]` + + The providers that must be given by any dependency appearing in this attribute. + +The format of this argument is a list of lists of providers -- `*Info` objects returned by [`provider()`](../globals/bzl.html#provider) (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element (i.e. `[A, B]` means `[[A, B]]`). It is NOT required that the rule of the dependency advertises those providers in its `provides` parameter, however, it is considered best practice. + + +`for_dependency_resolution` + default is `unbound` + + If this is set, the attribute is available for materializers. Only rules marked with the flag of the same name are allowed to be referenced through such attributes. + `flags`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Deprecated, will be removed. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + `cfg` + default is `None` + +[Configuration](https://bazel.build/extending/rules#configurations) of the attribute. It can be either `"exec"`, which indicates that the dependency is built for the `execution platform`, or `"target"`, which indicates that the dependency is build for the `target platform`. A typical example of the difference is when building mobile apps, where the `target platform` is `Android` or `iOS` while the `execution platform` is `Linux`, `macOS`, or `Windows`. + `aspects`[sequence](../core/list.html) of [Aspect](../builtins/Aspect.html) s; + default is `[]` + + Aspects that should be applied to the dependency or dependencies specified by this attribute. + ## string\_list @@ -282,32 +606,73 @@ At analysis time (within the rule's implementation function), when retrieving th Attribute attr.string_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None) ``` -Creates a schema for a list-of-strings attribute. + Creates a schema for a list-of-strings attribute. + ### Parameters -| Parameter | Description | -| --- | --- | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | -| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or NativeComputedDefault; default is `[]` A default value to use if no value for this attribute is given when instantiating the rule. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | +ParameterDescription`mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). + `allow_empty`[bool](../core/bool.html); + default is `True` + + True if the attribute can be empty. + `configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[sequence](../core/list.html) of [string](../core/string.html) s; or NativeComputedDefault; + default is `[]` + + A default value to use if no value for this attribute is given when instantiating the rule. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + ## string\_list\_dict ``` -Attribute attr.string_list_dict(allow_empty=True, *, configurable=unbound, default=\{\}, doc=None, mandatory=False) +Attribute attr.string_list_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False) ``` -Creates a schema for an attribute holding a dictionary, where the keys are strings and the values are lists of strings. + Creates a schema for an attribute holding a dictionary, where the keys are strings and the values are lists of strings. + ### Parameters -| Parameter | Description | -| --- | --- | -| `allow_empty` | [bool](../core/bool.mdx); default is `True` True if the attribute can be empty. | -| `configurable` | [bool](../core/bool.mdx); or unbound; default is `unbound` This argument can only be specified for an attribute of a symbolic macro. If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. | -| `default` | [dict](../core/dict.mdx); default is `\{\}` A default value to use if no value for this attribute is given when instantiating the rule. | -| `doc` | [string](../core/string.mdx); or `None`; default is `None` A description of the attribute that can be extracted by documentation generating tools. | -| `mandatory` | [bool](../core/bool.mdx); default is `False` If true, the value must be specified explicitly (even if it has a `default`). | \ No newline at end of file +ParameterDescription`allow_empty`[bool](../core/bool.html); + default is `True` + + True if the attribute can be empty. + `configurable`[bool](../core/bool.html); or unbound; + default is `unbound` + + This argument can only be specified for an attribute of a symbolic macro. + +If `configurable` is explicitly set to `False`, the symbolic macro attribute is non-configurable - in other words, it cannot take a `select()` value. If the `configurable` is either unbound or explicitly set to `True`, the attribute is configurable and can take a `select()` value. + +For an attribute of a rule or aspect, `configurable` must be left unbound. Most Starlark rule attributes are always configurable, with the exception of `attr.output()`, `attr.output_list()`, and `attr.license()` rule attributes, which are always non-configurable. + + +`default`[dict](../core/dict.html); + default is `{}` + + A default value to use if no value for this attribute is given when instantiating the rule. + `doc`[string](../core/string.html); or `None`; + default is `None` + + A description of the attribute that can be extracted by documentation generating tools. + `mandatory`[bool](../core/bool.html); + default is `False` + + If true, the value must be specified explicitly (even if it has a `default`). diff --git a/rules/lib/toplevel/cc_common.mdx b/rules/lib/toplevel/cc_common.mdx index af85221..b16795a 100644 --- a/rules/lib/toplevel/cc_common.mdx +++ b/rules/lib/toplevel/cc_common.mdx @@ -1,36 +1,37 @@ --- -title: 'cc_common' +title: 'cc\_common' --- + Utilities for C++ compilation, linking, and command line generation. ## Members -* [action\_is\_enabled](#action_is_enabled) -* [CcToolchainInfo](#CcToolchainInfo) -* [compile](#compile) -* [configure\_features](#configure_features) -* [create\_cc\_toolchain\_config\_info](#create_cc_toolchain_config_info) -* [create\_compilation\_context](#create_compilation_context) -* [create\_compilation\_outputs](#create_compilation_outputs) -* [create\_compile\_variables](#create_compile_variables) -* [create\_library\_to\_link](#create_library_to_link) -* [create\_link\_variables](#create_link_variables) -* [create\_linker\_input](#create_linker_input) -* [create\_linking\_context](#create_linking_context) -* [create\_linking\_context\_from\_compilation\_outputs](#create_linking_context_from_compilation_outputs) -* [create\_lto\_compilation\_context](#create_lto_compilation_context) -* [do\_not\_use\_tools\_cpp\_compiler\_present](#do_not_use_tools_cpp_compiler_present) -* [get\_environment\_variables](#get_environment_variables) -* [get\_execution\_requirements](#get_execution_requirements) -* [get\_memory\_inefficient\_command\_line](#get_memory_inefficient_command_line) -* [get\_tool\_for\_action](#get_tool_for_action) -* [is\_enabled](#is_enabled) -* [link](#link) -* [merge\_cc\_infos](#merge_cc_infos) -* [merge\_compilation\_contexts](#merge_compilation_contexts) -* [merge\_compilation\_outputs](#merge_compilation_outputs) +- [action\_is\_enabled](#action_is_enabled) +- [CcToolchainInfo](#CcToolchainInfo) +- [compile](#compile) +- [configure\_features](#configure_features) +- [create\_cc\_toolchain\_config\_info](#create_cc_toolchain_config_info) +- [create\_compilation\_context](#create_compilation_context) +- [create\_compilation\_outputs](#create_compilation_outputs) +- [create\_compile\_variables](#create_compile_variables) +- [create\_library\_to\_link](#create_library_to_link) +- [create\_link\_variables](#create_link_variables) +- [create\_linker\_input](#create_linker_input) +- [create\_linking\_context](#create_linking_context) +- [create\_linking\_context\_from\_compilation\_outputs](#create_linking_context_from_compilation_outputs) +- [create\_lto\_compilation\_context](#create_lto_compilation_context) +- [do\_not\_use\_tools\_cpp\_compiler\_present](#do_not_use_tools_cpp_compiler_present) +- [get\_environment\_variables](#get_environment_variables) +- [get\_execution\_requirements](#get_execution_requirements) +- [get\_memory\_inefficient\_command\_line](#get_memory_inefficient_command_line) +- [get\_tool\_for\_action](#get_tool_for_action) +- [is\_enabled](#is_enabled) +- [link](#link) +- [merge\_cc\_infos](#merge_cc_infos) +- [merge\_compilation\_contexts](#merge_compilation_contexts) +- [merge\_compilation\_outputs](#merge_compilation_outputs) ## action\_is\_enabled @@ -38,14 +39,20 @@ Utilities for C++ compilation, linking, and command line generation. bool cc_common.action_is_enabled(*, feature_configuration, action_name) ``` -Returns True if given action\_config is enabled in the feature configuration. + Returns True if given action\_config is enabled in the feature configuration. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | -| `action_name` | [string](../core/string.mdx); required Name of the action\_config. | +ParameterDescription`feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + + Feature configuration to be queried. + `action_name`[string](../core/string.html); + required + + Name of the action\_config. + ## CcToolchainInfo @@ -53,7 +60,9 @@ Returns True if given action\_config is enabled in the feature configuration. Provider cc_common.CcToolchainInfo ``` -The key used to retrieve the provider that contains information about the C++ toolchain being used + The key used to retrieve the provider that contains information about the C++ toolchain being used + + ## compile @@ -61,35 +70,105 @@ The key used to retrieve the provider that contains information about the C++ to tuple cc_common.compile(*, actions, feature_configuration, cc_toolchain, srcs=[], public_hdrs=[], private_hdrs=[], includes=[], quote_includes=[], system_includes=[], framework_includes=[], defines=[], local_defines=[], include_prefix='', strip_include_prefix='', user_compile_flags=[], conly_flags=[], cxx_flags=[], compilation_contexts=[], name, disallow_pic_outputs=False, disallow_nopic_outputs=False, additional_inputs=[], module_interfaces=unbound) ``` -Should be used for C++ compilation. Returns tuple of (`CompilationContext`, `CcCompilationOutputs`). + Should be used for C++ compilation. Returns tuple of ( `CompilationContext`, `CcCompilationOutputs`). + ### Parameters -| Parameter | Description | -| --- | --- | -| `actions` | [actions](../builtins/actions.mdx); required `actions` object. | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required `feature_configuration` to be queried. | -| `cc_toolchain` | Info; required `CcToolchainInfo` provider to be used. | -| `srcs` | [sequence](../core/list.mdx); default is `[]` The list of source files to be compiled. | -| `public_hdrs` | [sequence](../core/list.mdx); default is `[]` List of headers needed for compilation of srcs and may be included by dependent rules transitively. | -| `private_hdrs` | [sequence](../core/list.mdx); default is `[]` List of headers needed for compilation of srcs and NOT to be included by dependent rules. | -| `includes` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `[]` Search paths for header files referenced both by angle bracket and quotes. Usually passed with -I. Propagated to dependents transitively. | -| `quote_includes` | [sequence](../core/list.mdx); default is `[]` Search paths for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. Propagated to dependents transitively. | -| `system_includes` | [sequence](../core/list.mdx); default is `[]` Search paths for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. Propagated to dependents transitively. | -| `framework_includes` | [sequence](../core/list.mdx); default is `[]` Search paths for header files from Apple frameworks. They can be either relative to the exec root or absolute. Usually passed with -F. Propagated to dependents transitively. | -| `defines` | [sequence](../core/list.mdx); default is `[]` Set of defines needed to compile this target. Each define is a string. Propagated to dependents transitively. | -| `local_defines` | [sequence](../core/list.mdx); default is `[]` Set of defines needed to compile this target. Each define is a string. Not propagated to dependents transitively. | -| `include_prefix` | [string](../core/string.mdx); default is `''` The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the strip\_include\_prefix attribute is removed before this prefix is added. | -| `strip_include_prefix` | [string](../core/string.mdx); default is `''` The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the include\_prefix attribute is added after this prefix is stripped. | -| `user_compile_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of compilation options. | -| `conly_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of compilation options for C compiles. | -| `cxx_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of compilation options for C++ compiles. | -| `compilation_contexts` | [sequence](../core/list.mdx); default is `[]` Headers from dependencies used for compilation. | -| `name` | [string](../core/string.mdx); required This is used for naming the output artifacts of actions created by this method. See also the `main\_output` arg. | -| `disallow_pic_outputs` | [bool](../core/bool.mdx); default is `False` Whether PIC outputs should be created. | -| `disallow_nopic_outputs` | [bool](../core/bool.mdx); default is `False` Whether NOPIC outputs should be created. | -| `additional_inputs` | [sequence](../core/list.mdx); default is `[]` List of additional files needed for compilation of srcs | -| `module_interfaces` | [sequence](../core/list.mdx); default is `unbound` The list of module interfaces source files to be compiled. Note: this is an experimental feature, only enabled with --experimental\_cpp\_modules | +ParameterDescription`actions`[actions](../builtins/actions.html); + required + +`actions` object. + `feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + +`feature_configuration` to be queried. + `cc_toolchain` + Info; + required + +`CcToolchainInfo` provider to be used. + `srcs`[sequence](../core/list.html); + default is `[]` + + The list of source files to be compiled. + `public_hdrs`[sequence](../core/list.html); + default is `[]` + + List of headers needed for compilation of srcs and may be included by dependent rules transitively. + `private_hdrs`[sequence](../core/list.html); + default is `[]` + + List of headers needed for compilation of srcs and NOT to be included by dependent rules. + `includes`[sequence](../core/list.html); or [depset](../builtins/depset.html); + default is `[]` + + Search paths for header files referenced both by angle bracket and quotes. Usually passed with -I. Propagated to dependents transitively. + `quote_includes`[sequence](../core/list.html); + default is `[]` + + Search paths for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. Propagated to dependents transitively. + `system_includes`[sequence](../core/list.html); + default is `[]` + + Search paths for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. Propagated to dependents transitively. + `framework_includes`[sequence](../core/list.html); + default is `[]` + + Search paths for header files from Apple frameworks. They can be either relative to the exec root or absolute. Usually passed with -F. Propagated to dependents transitively. + `defines`[sequence](../core/list.html); + default is `[]` + + Set of defines needed to compile this target. Each define is a string. Propagated to dependents transitively. + `local_defines`[sequence](../core/list.html); + default is `[]` + + Set of defines needed to compile this target. Each define is a string. Not propagated to dependents transitively. + `include_prefix`[string](../core/string.html); + default is `''` + + The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the strip\_include\_prefix attribute is removed before this prefix is added. + `strip_include_prefix`[string](../core/string.html); + default is `''` + + The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the include\_prefix attribute is added after this prefix is stripped. + `user_compile_flags`[sequence](../core/list.html); + default is `[]` + + Additional list of compilation options. + `conly_flags`[sequence](../core/list.html); + default is `[]` + + Additional list of compilation options for C compiles. + `cxx_flags`[sequence](../core/list.html); + default is `[]` + + Additional list of compilation options for C++ compiles. + `compilation_contexts`[sequence](../core/list.html); + default is `[]` + + Headers from dependencies used for compilation. + `name`[string](../core/string.html); + required + + This is used for naming the output artifacts of actions created by this method. See also the \`main\_output\` arg. + `disallow_pic_outputs`[bool](../core/bool.html); + default is `False` + + Whether PIC outputs should be created. + `disallow_nopic_outputs`[bool](../core/bool.html); + default is `False` + + Whether NOPIC outputs should be created. + `additional_inputs`[sequence](../core/list.html); + default is `[]` + + List of additional files needed for compilation of srcs + `module_interfaces`[sequence](../core/list.html); + default is `unbound` + + The list of module interfaces source files to be compiled. Note: this is an experimental feature, only enabled with --experimental\_cpp\_modules + ## configure\_features @@ -97,17 +176,33 @@ Should be used for C++ compilation. Returns tuple of (`CompilationContext`, `CcC FeatureConfiguration cc_common.configure_features(*, ctx, cc_toolchain, language=None, requested_features=[], unsupported_features=[]) ``` -Creates a feature\_configuration instance. Requires the cpp configuration fragment. + Creates a feature\_configuration instance. Requires the cpp configuration fragment. + ### Parameters -| Parameter | Description | -| --- | --- | -| `ctx` | [ctx](../builtins/ctx.mdx); required The rule context. | -| `cc_toolchain` | Info; required cc\_toolchain for which we configure features. | -| `language` | [string](../core/string.mdx); or `None`; default is `None` The language to configure for: either c++ or objc (default c++) | -| `requested_features` | [sequence](../core/list.mdx); default is `[]` List of features to be enabled. | -| `unsupported_features` | [sequence](../core/list.mdx); default is `[]` List of features that are unsupported by the current rule. | +ParameterDescription`ctx`[ctx](../builtins/ctx.html); + required + + The rule context. + `cc_toolchain` + Info; + required + + cc\_toolchain for which we configure features. + `language`[string](../core/string.html); or `None`; + default is `None` + + The language to configure for: either c++ or objc (default c++) + `requested_features`[sequence](../core/list.html); + default is `[]` + + List of features to be enabled. + `unsupported_features`[sequence](../core/list.html); + default is `[]` + + List of features that are unsupported by the current rule. + ## create\_cc\_toolchain\_config\_info @@ -115,28 +210,137 @@ Creates a feature\_configuration instance. Requires the cpp configuration fragme None cc_common.create_cc_toolchain_config_info(*, ctx, features=[], action_configs=[], artifact_name_patterns=[], cxx_builtin_include_directories=[], toolchain_identifier, host_system_name=None, target_system_name=None, target_cpu=None, target_libc=None, compiler, abi_version=None, abi_libc_version=None, tool_paths=[], make_variables=[], builtin_sysroot=None) ``` -Creates a `CcToolchainConfigInfo` provider + Creates a `CcToolchainConfigInfo` provider + ### Parameters -| Parameter | Description | -| --- | --- | -| `ctx` | [ctx](../builtins/ctx.mdx); required The rule context. | -| `features` | [sequence](../core/list.mdx); default is `[]` Contains all flag specifications for one feature. Arguments: `name`: The feature's name. It is possible to introduce a feature without a change to Bazel by adding a 'feature' section to the toolchain and adding the corresponding string as feature in the `BUILD` file. `enabled`: If 'True', this feature is enabled unless a rule type explicitly marks it as unsupported. `flag_sets`: A FlagSet list. If the given feature is enabled, the flag sets will be applied for the actions are specified for. `env_sets`: an EnvSet list. If the given feature is enabled, the env sets will be applied for the actions they are specified for. `requires`: A list of feature sets defining when this feature is supported by the toolchain. The feature is supported if any of the feature sets fully apply, that is, when all features of a feature set are enabled. If `requires` is omitted, the feature is supported independently of which other features are enabled. Use this for example to filter flags depending on the build mode enabled (opt / fastbuild / dbg). `implies`: A string list of features or action configs that are automatically enabled when this feature is enabled. If any of the implied features or action configs cannot be enabled, this feature will (silently) not be enabled either. `provides`: A list of names this feature conflicts with. A feature cannot be enabled if:- `provides` contains the name of a different feature or action config that we want to enable.- `provides` contains the same value as a 'provides' in a different feature or action config that we want to enable. Use this in order to ensure that incompatible features cannot be accidentally activated at the same time, leading to hard to diagnose compiler errors. | -| `action_configs` | [sequence](../core/list.mdx); default is `[]` An action config corresponds to a Bazel action, and allows selection of a tool based on activated features. Action config activation occurs by the same semantics as features: a feature can 'require' or 'imply' an action config in the same way that it would another feature. Arguments: `action_name`: The name of the Bazel action that this config applies to, e.g. 'c-compile' or 'c-module-compile'. `enabled`: If 'True', this action is enabled unless a rule type explicitly marks it as unsupported. `tools`: The tool applied to the action will be the first tool with a feature set that matches the feature configuration. An error will be thrown if no tool matches a provided feature configuration - for that reason, it's a good idea to provide a default tool with an empty feature set. `flag_sets`: If the given action config is enabled, the flag sets will be applied to the corresponding action. `implies`: A list of features or action configs that are automatically enabled when this action config is enabled. If any of the implied features or action configs cannot be enabled, this action config will (silently) not be enabled either. | -| `artifact_name_patterns` | [sequence](../core/list.mdx); default is `[]` The name for an artifact of a given category of input or output artifacts to an action. Arguments: `category_name`: The category of artifacts that this selection applies to. This field is compared against a list of categories defined in Bazel. Example categories include "linked\_output" or the artifact for this selection. Together with the extension it is used to create an artifact name based on the target name. `extension`: The extension for creating the artifact for this selection. Together with the prefix it is used to create an artifact name based on the target name. | -| `cxx_builtin_include_directories` | [sequence](../core/list.mdx); default is `[]` Built-in include directories for C++ compilation. These should be the exact paths used by the compiler, and are generally relative to the exec root. The paths used by the compiler can be determined by 'gcc -E -xc++ - -v'. We currently use the C++ paths also for C compilation, which is safe as long as there are no name clashes between C++ and C header files. Relative paths are resolved relative to the configuration file directory. If the compiler has --sysroot support, then these paths should use %sysroot% rather than the include path, and specify the sysroot attribute in order to give blaze the information necessary to make the correct replacements. | -| `toolchain_identifier` | [string](../core/string.mdx); required The unique identifier of the toolchain within the crosstool release. It must be possible to use this as a directory name in a path. It has to match the following regex: [a-zA-Z\_][\.\- \w]\* | -| `host_system_name` | [string](../core/string.mdx); or `None`; default is `None` Ignored. | -| `target_system_name` | [string](../core/string.mdx); or `None`; default is `None` Deprecated. The GNU System Name. The string is exposed to CcToolchainInfo.target\_gnu\_system\_name. | -| `target_cpu` | [string](../core/string.mdx); or `None`; default is `None` Deprecated: Use cpu based constraints instead. If the string is "k8", `target\_cpu` will be omitted from the filename of raw FDO profile data. | -| `target_libc` | [string](../core/string.mdx); or `None`; default is `None` Deprecated: Use OS based constraints instead. The libc version string (e.g. "glibc-2.2.2"). If the string is "macosx", platform is assumed to be MacOS. Otherwise, Linux. The string is exposed to CcToolchainInfo.libc. | -| `compiler` | [string](../core/string.mdx); required The compiler string (e.g. "gcc"). The current toolchain's compiler is exposed to `@bazel\_tools//tools/cpp:compiler (compiler\_flag)` as a flag value. Targets that require compiler-specific flags can use the config\_settings in https://github.com/bazelbuild/rules\_cc/blob/main/cc/compiler/BUILD in select() statements or create custom config\_setting if the existing settings don't suffice. | -| `abi_version` | [string](../core/string.mdx); or `None`; default is `None` The abi in use, which is a gcc version. E.g.: "gcc-3.4". The string is set to C++ toolchain variable ABI. | -| `abi_libc_version` | [string](../core/string.mdx); or `None`; default is `None` The glibc version used by the abi we're using. The string is set to C++ toolchain variable ABI\_LIBC\_VERSION. | -| `tool_paths` | [sequence](../core/list.mdx); default is `[]` Tool locations. Arguments: `name`: Name of the tool. `path`: Location of the tool; Can be absolute path (in case of non hermetic toolchain), or path relative to the cc\_toolchain's package. | -| `make_variables` | [sequence](../core/list.mdx); default is `[]` A make variable that is made accessible to rules. | -| `builtin_sysroot` | [string](../core/string.mdx); or `None`; default is `None` The built-in sysroot. If this attribute is not present, Bazel does not allow using a different sysroot, i.e. through the --grte\_top option. | +ParameterDescription`ctx`[ctx](../builtins/ctx.html); + required + + The rule context. + `features`[sequence](../core/list.html); + default is `[]` + + Contains all flag specifications for one feature. + +Arguments: + +`name`: The feature's name. It is possible to introduce a feature without a change to Bazel by adding a 'feature' section to the toolchain and adding the corresponding string as feature in the `BUILD` file. + +`enabled`: If 'True', this feature is enabled unless a rule type explicitly marks it as unsupported. + +`flag_sets`: A FlagSet list. If the given feature is enabled, the flag sets will be applied for the actions are specified for. + +`env_sets`: an EnvSet list. If the given feature is enabled, the env sets will be applied for the actions they are specified for. + +`requires`: A list of feature sets defining when this feature is supported by the toolchain. The feature is supported if any of the feature sets fully apply, that is, when all features of a feature set are enabled. If `requires` is omitted, the feature is supported independently of which other features are enabled. Use this for example to filter flags depending on the build mode enabled (opt / fastbuild / dbg). + +`implies`: A string list of features or action configs that are automatically enabled when this feature is enabled. If any of the implied features or action configs cannot be enabled, this feature will (silently) not be enabled either. + +`provides`: A list of names this feature conflicts with. + +A feature cannot be enabled if: + +\- `provides` contains the name of a different feature or action config that we want to enable. + +\- `provides` contains the same value as a 'provides' in a different feature or action config that we want to enable. Use this in order to ensure that incompatible features cannot be accidentally activated at the same time, leading to hard to diagnose compiler errors. + `action_configs`[sequence](../core/list.html); + default is `[]` + + An action config corresponds to a Bazel action, and allows selection of a tool based on activated features. Action config activation occurs by the same semantics as features: a feature can 'require' or 'imply' an action config in the same way that it would another feature. + +Arguments: + +`action_name`: The name of the Bazel action that this config applies to, e.g. 'c-compile' or 'c-module-compile'. + +`enabled`: If 'True', this action is enabled unless a rule type explicitly marks it as unsupported. + +`tools`: The tool applied to the action will be the first tool with a feature set that matches the feature configuration. An error will be thrown if no tool matches a provided feature configuration - for that reason, it's a good idea to provide a default tool with an empty feature set. + +`flag_sets`: If the given action config is enabled, the flag sets will be applied to the corresponding action. + +`implies`: A list of features or action configs that are automatically enabled when this action config is enabled. If any of the implied features or action configs cannot be enabled, this action config will (silently) not be enabled either. + +`artifact_name_patterns`[sequence](../core/list.html); + default is `[]` + + The name for an artifact of a given category of input or output artifacts to an action. + +Arguments: + +`category_name`: The category of artifacts that this selection applies to. This field is compared against a list of categories defined in Bazel. Example categories include "linked\_output" or the artifact for this selection. Together with the extension it is used to create an artifact name based on the target name. + +`extension`: The extension for creating the artifact for this selection. Together with the prefix it is used to create an artifact name based on the target name. + +`cxx_builtin_include_directories`[sequence](../core/list.html); + default is `[]` + +Built-in include directories for C++ compilation. These should be the exact paths used by the compiler, and are generally relative to the exec root. + +The paths used by the compiler can be determined by 'gcc -E -xc++ - -v'. + +We currently use the C++ paths also for C compilation, which is safe as long as there are no name clashes between C++ and C header files. + +Relative paths are resolved relative to the configuration file directory. + +If the compiler has --sysroot support, then these paths should use %sysroot% rather than the include path, and specify the sysroot attribute in order to give blaze the information necessary to make the correct replacements. + +`toolchain_identifier`[string](../core/string.html); + required + +The unique identifier of the toolchain within the crosstool release. It must be possible to use this as a directory name in a path. + +It has to match the following regex: \[a-zA-Z\_\]\[\\.\\- \\w\]\* + +`host_system_name`[string](../core/string.html); or `None`; + default is `None` + + Ignored. + `target_system_name`[string](../core/string.html); or `None`; + default is `None` + + Deprecated. The GNU System Name. The string is exposed to CcToolchainInfo.target\_gnu\_system\_name. + `target_cpu`[string](../core/string.html); or `None`; + default is `None` + + Deprecated: Use cpu based constraints instead. If the string is "k8", \`target\_cpu\` will be omitted from the filename of raw FDO profile data. + `target_libc`[string](../core/string.html); or `None`; + default is `None` + + Deprecated: Use OS based constraints instead. The libc version string (e.g. "glibc-2.2.2"). If the string is "macosx", platform is assumed to be MacOS. Otherwise, Linux. The string is exposed to CcToolchainInfo.libc. + `compiler`[string](../core/string.html); + required + + The compiler string (e.g. "gcc"). The current toolchain's compiler is exposed to \`@bazel\_tools//tools/cpp:compiler (compiler\_flag)\` as a flag value. Targets that require compiler-specific flags can use the config\_settings in https://github.com/bazelbuild/rules\_cc/blob/main/cc/compiler/BUILD in select() statements or create custom config\_setting if the existing settings don't suffice. + `abi_version`[string](../core/string.html); or `None`; + default is `None` + + The abi in use, which is a gcc version. E.g.: "gcc-3.4". The string is set to C++ toolchain variable ABI. + `abi_libc_version`[string](../core/string.html); or `None`; + default is `None` + + The glibc version used by the abi we're using. The string is set to C++ toolchain variable ABI\_LIBC\_VERSION. + `tool_paths`[sequence](../core/list.html); + default is `[]` + + Tool locations. + +Arguments: + +`name`: Name of the tool. + +`path`: Location of the tool; Can be absolute path (in case of non hermetic toolchain), or path relative to the cc\_toolchain's package. + +`make_variables`[sequence](../core/list.html); + default is `[]` + + A make variable that is made accessible to rules. + `builtin_sysroot`[string](../core/string.html); or `None`; + default is `None` + + The built-in sysroot. If this attribute is not present, Bazel does not allow using a different sysroot, i.e. through the --grte\_top option. + ## create\_compilation\_context @@ -144,19 +348,40 @@ Creates a `CcToolchainConfigInfo` provider CompilationContext cc_common.create_compilation_context(*, headers=unbound, system_includes=unbound, includes=unbound, quote_includes=unbound, framework_includes=unbound, defines=unbound, local_defines=unbound) ``` -Creates a `CompilationContext`. + Creates a `CompilationContext`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `headers` | default is `unbound` Set of headers needed to compile this target | -| `system_includes` | default is `unbound` Set of search paths for header files referenced by angle brackets, i.e. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem | -| `includes` | default is `unbound` Set of search paths for header files referenced both by angle bracket and quotes.Usually passed with -I | -| `quote_includes` | default is `unbound` Set of search paths for header files referenced by quotes, i.e. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote | -| `framework_includes` | default is `unbound` Set of framework search paths for header files (Apple platform only) | -| `defines` | default is `unbound` Set of defines needed to compile this target. Each define is a string. Propagated transitively to dependents. | -| `local_defines` | default is `unbound` Set of defines needed to compile this target. Each define is a string. Not propagated transitively to dependents. | +ParameterDescription`headers` + default is `unbound` + + Set of headers needed to compile this target + `system_includes` + default is `unbound` + + Set of search paths for header files referenced by angle brackets, i.e. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem + `includes` + default is `unbound` + + Set of search paths for header files referenced both by angle bracket and quotes.Usually passed with -I + `quote_includes` + default is `unbound` + + Set of search paths for header files referenced by quotes, i.e. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote + `framework_includes` + default is `unbound` + + Set of framework search paths for header files (Apple platform only) + `defines` + default is `unbound` + + Set of defines needed to compile this target. Each define is a string. Propagated transitively to dependents. + `local_defines` + default is `unbound` + + Set of defines needed to compile this target. Each define is a string. Not propagated transitively to dependents. + ## create\_compilation\_outputs @@ -164,14 +389,20 @@ Creates a `CompilationContext`. CcCompilationOutputs cc_common.create_compilation_outputs(*, objects=None, pic_objects=None) ``` -Create compilation outputs object. + Create compilation outputs object. + ### Parameters -| Parameter | Description | -| --- | --- | -| `objects` | [depset](../builtins/depset.mdx); or `None`; default is `None` List of object files. | -| `pic_objects` | [depset](../builtins/depset.mdx); or `None`; default is `None` List of pic object files. | +ParameterDescription`objects`[depset](../builtins/depset.html); or `None`; + default is `None` + + List of object files. + `pic_objects`[depset](../builtins/depset.html); or `None`; + default is `None` + + List of pic object files. + ## create\_compile\_variables @@ -179,28 +410,77 @@ Create compilation outputs object. Variables cc_common.create_compile_variables(*, cc_toolchain, feature_configuration, source_file=None, output_file=None, user_compile_flags=None, include_directories=None, quote_include_directories=None, system_include_directories=None, framework_include_directories=None, preprocessor_defines=None, thinlto_index=None, thinlto_input_bitcode_file=None, thinlto_output_object_file=None, use_pic=False, add_legacy_cxx_options=False, variables_extension=unbound) ``` -Returns variables used for compilation actions. + Returns variables used for compilation actions. + ### Parameters -| Parameter | Description | -| --- | --- | -| `cc_toolchain` | Info; required cc\_toolchain for which we are creating build variables. | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | -| `source_file` | [File](../builtins/File.mdx); or [string](../core/string.mdx); or `None`; default is `None` Optional source file path for the compilation. Please prefer passing source\_file here over appending it to the end of the command line generated from cc\_common.get\_memory\_inefficient\_command\_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. | -| `output_file` | [File](../builtins/File.mdx); or [string](../core/string.mdx); or `None`; default is `None` Optional output file path of the compilation. Please prefer passing output\_file here over appending it to the end of the command line generated from cc\_common.get\_memory\_inefficient\_command\_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. | -| `user_compile_flags` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` List of additional compilation flags (copts). | -| `include_directories` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of include directories. | -| `quote_include_directories` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of quote include directories. | -| `system_include_directories` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of system include directories. | -| `framework_include_directories` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of framework include directories. | -| `preprocessor_defines` | [depset](../builtins/depset.mdx); or `None`; default is `None` Depset of preprocessor defines. | -| `thinlto_index` | [string](../core/string.mdx); or `None`; default is `None` LTO index file path. | -| `thinlto_input_bitcode_file` | [string](../core/string.mdx); or `None`; default is `None` Bitcode file that is input to LTO backend. | -| `thinlto_output_object_file` | [string](../core/string.mdx); or `None`; default is `None` Object file that is output by LTO backend. | -| `use_pic` | [bool](../core/bool.mdx); default is `False` When true the compilation will generate position independent code. | -| `add_legacy_cxx_options` | [bool](../core/bool.mdx); default is `False` Unused. | -| `variables_extension` | [dict](../core/dict.mdx); default is `unbound` A dictionary of additional variables used by compile actions. | +ParameterDescription`cc_toolchain` + Info; + required + + cc\_toolchain for which we are creating build variables. + `feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + + Feature configuration to be queried. + `source_file`[File](../builtins/File.html); or [string](../core/string.html); or `None`; + default is `None` + + Optional source file path for the compilation. Please prefer passing source\_file here over appending it to the end of the command line generated from cc\_common.get\_memory\_inefficient\_command\_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. + `output_file`[File](../builtins/File.html); or [string](../core/string.html); or `None`; + default is `None` + + Optional output file path of the compilation. Please prefer passing output\_file here over appending it to the end of the command line generated from cc\_common.get\_memory\_inefficient\_command\_line, as then it's in the power of the toolchain author to properly specify and position compiler flags. + `user_compile_flags`[sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + List of additional compilation flags (copts). + `include_directories`[depset](../builtins/depset.html); or `None`; + default is `None` + + Depset of include directories. + `quote_include_directories`[depset](../builtins/depset.html); or `None`; + default is `None` + + Depset of quote include directories. + `system_include_directories`[depset](../builtins/depset.html); or `None`; + default is `None` + + Depset of system include directories. + `framework_include_directories`[depset](../builtins/depset.html); or `None`; + default is `None` + + Depset of framework include directories. + `preprocessor_defines`[depset](../builtins/depset.html); or `None`; + default is `None` + + Depset of preprocessor defines. + `thinlto_index`[string](../core/string.html); or `None`; + default is `None` + + LTO index file path. + `thinlto_input_bitcode_file`[string](../core/string.html); or `None`; + default is `None` + + Bitcode file that is input to LTO backend. + `thinlto_output_object_file`[string](../core/string.html); or `None`; + default is `None` + + Object file that is output by LTO backend. + `use_pic`[bool](../core/bool.html); + default is `False` + + When true the compilation will generate position independent code. + `add_legacy_cxx_options`[bool](../core/bool.html); + default is `False` + + Unused. + `variables_extension`[dict](../core/dict.html); + default is `unbound` + + A dictionary of additional variables used by compile actions. + ## create\_library\_to\_link @@ -208,25 +488,59 @@ Returns variables used for compilation actions. LibraryToLink cc_common.create_library_to_link(*, actions, feature_configuration=None, cc_toolchain=None, static_library=None, pic_static_library=None, dynamic_library=None, interface_library=None, pic_objects=unbound, objects=unbound, alwayslink=False, dynamic_library_symlink_path='', interface_library_symlink_path='') ``` -Creates `LibraryToLink` - + Creates `LibraryToLink` ### Parameters -| Parameter | Description | -| --- | --- | -| `actions` | required `actions` object. | -| `feature_configuration` | default is `None` `feature_configuration` to be queried. | -| `cc_toolchain` | default is `None` `CcToolchainInfo` provider to be used. | -| `static_library` | [File](../builtins/File.mdx); or `None`; default is `None` `File` of static library to be linked. | -| `pic_static_library` | [File](../builtins/File.mdx); or `None`; default is `None` `File` of pic static library to be linked. | -| `dynamic_library` | [File](../builtins/File.mdx); or `None`; default is `None` `File` of dynamic library to be linked. Always used for runtime and used for linking if `interface_library` is not passed. | -| `interface_library` | [File](../builtins/File.mdx); or `None`; default is `None` `File` of interface library to be linked. | -| `pic_objects` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `unbound` Experimental, do not use | -| `objects` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `unbound` Experimental, do not use | -| `alwayslink` | [bool](../core/bool.mdx); default is `False` Whether to link the static library/objects in the --whole\_archive block. | -| `dynamic_library_symlink_path` | [string](../core/string.mdx); default is `''` Override the default path of the dynamic library link in the solib directory. Empty string to use the default. | -| `interface_library_symlink_path` | [string](../core/string.mdx); default is `''` Override the default path of the interface library link in the solib directory. Empty string to use the default. | +ParameterDescription`actions` + required + +`actions` object. + `feature_configuration` + default is `None` + +`feature_configuration` to be queried. + `cc_toolchain` + default is `None` + +`CcToolchainInfo` provider to be used. + `static_library`[File](../builtins/File.html); or `None`; + default is `None` + +`File` of static library to be linked. + `pic_static_library`[File](../builtins/File.html); or `None`; + default is `None` + +`File` of pic static library to be linked. + `dynamic_library`[File](../builtins/File.html); or `None`; + default is `None` + +`File` of dynamic library to be linked. Always used for runtime and used for linking if `interface_library` is not passed. + `interface_library`[File](../builtins/File.html); or `None`; + default is `None` + +`File` of interface library to be linked. + `pic_objects`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `unbound` + + Experimental, do not use + `objects`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `unbound` + + Experimental, do not use + `alwayslink`[bool](../core/bool.html); + default is `False` + + Whether to link the static library/objects in the --whole\_archive block. + `dynamic_library_symlink_path`[string](../core/string.html); + default is `''` + + Override the default path of the dynamic library link in the solib directory. Empty string to use the default. + `interface_library_symlink_path`[string](../core/string.html); + default is `''` + + Override the default path of the interface library link in the solib directory. Empty string to use the default. + ## create\_link\_variables @@ -234,24 +548,61 @@ Creates `LibraryToLink` Variables cc_common.create_link_variables(*, cc_toolchain, feature_configuration, library_search_directories=[], runtime_library_search_directories=[], user_link_flags=[], output_file=None, param_file=None, is_using_linker=True, is_linking_dynamic_library=False, must_keep_debug=True, use_test_only_flags=False, is_static_linking_mode=True) ``` -Returns link variables used for linking actions. + Returns link variables used for linking actions. + ### Parameters -| Parameter | Description | -| --- | --- | -| `cc_toolchain` | Info; required cc\_toolchain for which we are creating build variables. | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | -| `library_search_directories` | [depset](../builtins/depset.mdx); default is `[]` Depset of directories where linker will look for libraries at link time. | -| `runtime_library_search_directories` | [depset](../builtins/depset.mdx); default is `[]` Depset of directories where loader will look for libraries at runtime. | -| `user_link_flags` | [sequence](../core/list.mdx); default is `[]` List of additional link flags (linkopts). | -| `output_file` | default is `None` Optional output file path. | -| `param_file` | default is `None` Optional param file path. | -| `is_using_linker` | [bool](../core/bool.mdx); default is `True` True when using linker, False when archiver. Caller is responsible for keeping this in sync with action name used (is\_using\_linker = True for linking executable or dynamic library, is\_using\_linker = False for archiving static library). | -| `is_linking_dynamic_library` | [bool](../core/bool.mdx); default is `False` True when creating dynamic library, False when executable or static library. Caller is responsible for keeping this in sync with action name used. This field will be removed once b/65151735 is fixed. | -| `must_keep_debug` | [bool](../core/bool.mdx); default is `True` When set to False, bazel will expose 'strip\_debug\_symbols' variable, which is usually used to use the linker to strip debug symbols from the output file. | -| `use_test_only_flags` | [bool](../core/bool.mdx); default is `False` When set to true, 'is\_cc\_test' variable will be set. | -| `is_static_linking_mode` | [bool](../core/bool.mdx); default is `True` Unused. | +ParameterDescription`cc_toolchain` + Info; + required + + cc\_toolchain for which we are creating build variables. + `feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + + Feature configuration to be queried. + `library_search_directories`[depset](../builtins/depset.html); + default is `[]` + + Depset of directories where linker will look for libraries at link time. + `runtime_library_search_directories`[depset](../builtins/depset.html); + default is `[]` + + Depset of directories where loader will look for libraries at runtime. + `user_link_flags`[sequence](../core/list.html); + default is `[]` + + List of additional link flags (linkopts). + `output_file` + default is `None` + + Optional output file path. + `param_file` + default is `None` + + Optional param file path. + `is_using_linker`[bool](../core/bool.html); + default is `True` + + True when using linker, False when archiver. Caller is responsible for keeping this in sync with action name used (is\_using\_linker = True for linking executable or dynamic library, is\_using\_linker = False for archiving static library). + `is_linking_dynamic_library`[bool](../core/bool.html); + default is `False` + + True when creating dynamic library, False when executable or static library. Caller is responsible for keeping this in sync with action name used. This field will be removed once b/65151735 is fixed. + `must_keep_debug`[bool](../core/bool.html); + default is `True` + + When set to False, bazel will expose 'strip\_debug\_symbols' variable, which is usually used to use the linker to strip debug symbols from the output file. + `use_test_only_flags`[bool](../core/bool.html); + default is `False` + + When set to true, 'is\_cc\_test' variable will be set. + `is_static_linking_mode`[bool](../core/bool.html); + default is `True` + + Unused. + ## create\_linker\_input @@ -259,16 +610,28 @@ Returns link variables used for linking actions. LinkerInput cc_common.create_linker_input(*, owner, libraries=None, user_link_flags=None, additional_inputs=None) ``` -Creates a `LinkerInput`. + Creates a `LinkerInput`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `owner` | [Label](../builtins/Label.mdx); required The label of the target that produced all files used in this input. | -| `libraries` | `None`; or [depset](../builtins/depset.mdx); default is `None` List of `LibraryToLink`. | -| `user_link_flags` | `None`; or [depset](../builtins/depset.mdx) of [string](../core/string.mdx)s; or [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `None` User link flags passed as strings. Accepts either [String], [[String]] or depset(String). The latter is discouraged as it's only kept for compatibility purposes, the depset is flattened. If you want to propagate user\_link\_flags via unflattened depsets() wrap them in a LinkerInput so that they are not flattened till the end. | -| `additional_inputs` | `None`; or [depset](../builtins/depset.mdx); default is `None` For additional inputs to the linking action, e.g.: linking scripts. | +ParameterDescription`owner`[Label](../builtins/Label.html); + required + + The label of the target that produced all files used in this input. + `libraries``None`; or [depset](../builtins/depset.html); + default is `None` + + List of `LibraryToLink`. + `user_link_flags``None`; or [depset](../builtins/depset.html) of [string](../core/string.html) s; or [sequence](../core/list.html) of [string](../core/string.html) s; + default is `None` + + User link flags passed as strings. Accepts either \[String\], \[\[String\]\] or depset(String). The latter is discouraged as it's only kept for compatibility purposes, the depset is flattened. If you want to propagate user\_link\_flags via unflattened depsets() wrap them in a LinkerInput so that they are not flattened till the end. + `additional_inputs``None`; or [depset](../builtins/depset.html); + default is `None` + + For additional inputs to the linking action, e.g.: linking scripts. + ## create\_linking\_context @@ -276,13 +639,16 @@ Creates a `LinkerInput`. LinkingContext cc_common.create_linking_context(*, linker_inputs) ``` -Creates a `LinkingContext`. + Creates a `LinkingContext`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `linker_inputs` | [depset](../builtins/depset.mdx); required Depset of `LinkerInput`. | +ParameterDescription`linker_inputs`[depset](../builtins/depset.html); + required + + Depset of `LinkerInput`. + ## create\_linking\_context\_from\_compilation\_outputs @@ -290,39 +656,82 @@ Creates a `LinkingContext`. tuple cc_common.create_linking_context_from_compilation_outputs(*, actions, name, feature_configuration, cc_toolchain, language='c++', disallow_static_libraries=False, disallow_dynamic_library=False, compilation_outputs, linking_contexts=[], user_link_flags=[], alwayslink=False, additional_inputs=[], variables_extension=unbound) ``` -Should be used for creating library rules that can propagate information downstream in order to be linked later by a top level rule that does transitive linking to create an executable or a dynamic library. Returns tuple of (`CcLinkingContext`, `CcLinkingOutputs`). + Should be used for creating library rules that can propagate information downstream in order to be linked later by a top level rule that does transitive linking to create an executable or a dynamic library. Returns tuple of ( `CcLinkingContext`, `CcLinkingOutputs`). + ### Parameters -| Parameter | Description | -| --- | --- | -| `actions` | [actions](../builtins/actions.mdx); required `actions` object. | -| `name` | [string](../core/string.mdx); required This is used for naming the output artifacts of actions created by this method. | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required `feature_configuration` to be queried. | -| `cc_toolchain` | Info; required `CcToolchainInfo` provider to be used. | -| `language` | [string](../core/string.mdx); default is `'c++'` Only C++ supported for now. Do not use this parameter. | -| `disallow_static_libraries` | [bool](../core/bool.mdx); default is `False` Whether static libraries should be created. | -| `disallow_dynamic_library` | [bool](../core/bool.mdx); default is `False` Whether a dynamic library should be created. | -| `compilation_outputs` | [CcCompilationOutputs](../builtins/CcCompilationOutputs.mdx); required Compilation outputs containing object files to link. | -| `linking_contexts` | [sequence](../core/list.mdx); default is `[]` Libraries from dependencies. These libraries will be linked into the output artifact of the link() call, be it a binary or a library. | -| `user_link_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of linking options. | -| `alwayslink` | [bool](../core/bool.mdx); default is `False` Whether this library should always be linked. | -| `additional_inputs` | [sequence](../core/list.mdx); default is `[]` For additional inputs to the linking action, e.g.: linking scripts. | -| `variables_extension` | [dict](../core/dict.mdx); default is `unbound` Additional variables to pass to the toolchain configuration when creating link command line. | +ParameterDescription`actions`[actions](../builtins/actions.html); + required + +`actions` object. + `name`[string](../core/string.html); + required + + This is used for naming the output artifacts of actions created by this method. + `feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + +`feature_configuration` to be queried. + `cc_toolchain` + Info; + required + +`CcToolchainInfo` provider to be used. + `language`[string](../core/string.html); + default is `'c++'` + + Only C++ supported for now. Do not use this parameter. + `disallow_static_libraries`[bool](../core/bool.html); + default is `False` + + Whether static libraries should be created. + `disallow_dynamic_library`[bool](../core/bool.html); + default is `False` + + Whether a dynamic library should be created. + `compilation_outputs`[CcCompilationOutputs](../builtins/CcCompilationOutputs.html); + required + + Compilation outputs containing object files to link. + `linking_contexts`[sequence](../core/list.html); + default is `[]` + + Libraries from dependencies. These libraries will be linked into the output artifact of the link() call, be it a binary or a library. + `user_link_flags`[sequence](../core/list.html); + default is `[]` + + Additional list of linking options. + `alwayslink`[bool](../core/bool.html); + default is `False` + + Whether this library should always be linked. + `additional_inputs`[sequence](../core/list.html); + default is `[]` + + For additional inputs to the linking action, e.g.: linking scripts. + `variables_extension`[dict](../core/dict.html); + default is `unbound` + + Additional variables to pass to the toolchain configuration when creating link command line. + ## create\_lto\_compilation\_context ``` -LtoCompilationContext cc_common.create_lto_compilation_context(*, objects=\{\}) +LtoCompilationContext cc_common.create_lto_compilation_context(*, objects={}) ``` -Create LTO compilation context + Create LTO compilation context + ### Parameters -| Parameter | Description | -| --- | --- | -| `objects` | [dict](../core/dict.mdx); default is `\{\}` map of full object to index object | +ParameterDescription`objects`[dict](../core/dict.html); + default is `{}` + + map of full object to index object + ## do\_not\_use\_tools\_cpp\_compiler\_present @@ -330,7 +739,9 @@ Create LTO compilation context None cc_common.do_not_use_tools_cpp_compiler_present ``` -Do not use this field, its only purpose is to help with migration from config\_setting.values\{'compiler') to config\_settings.flag\_values\{'@bazel\_tools//tools/cpp:compiler'\} + Do not use this field, its only purpose is to help with migration from config\_setting.values{'compiler') to config\_settings.flag\_values{'@bazel\_tools//tools/cpp:compiler'} + + ## get\_environment\_variables @@ -338,15 +749,25 @@ Do not use this field, its only purpose is to help with migration from config\_s dict cc_common.get_environment_variables(*, feature_configuration, action_name, variables) ``` -Returns environment variables to be set for given action. + Returns environment variables to be set for given action. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | -| `action_name` | [string](../core/string.mdx); required Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) | -| `variables` | Variables; required Build variables to be used for template expansion. | +ParameterDescription`feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + + Feature configuration to be queried. + `action_name`[string](../core/string.html); + required + + Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) + `variables` + Variables; + required + + Build variables to be used for template expansion. + ## get\_execution\_requirements @@ -354,14 +775,20 @@ Returns environment variables to be set for given action. sequence cc_common.get_execution_requirements(*, feature_configuration, action_name) ``` -Returns execution requirements for given action. + Returns execution requirements for given action. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | -| `action_name` | [string](../core/string.mdx); required Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) | +ParameterDescription`feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + + Feature configuration to be queried. + `action_name`[string](../core/string.html); + required + + Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) + ## get\_memory\_inefficient\_command\_line @@ -369,15 +796,25 @@ Returns execution requirements for given action. sequence cc_common.get_memory_inefficient_command_line(*, feature_configuration, action_name, variables) ``` -Returns flattened command line flags for given action, using given variables for expansion. Flattens nested sets and ideally should not be used, or at least should not outlive analysis. Work on memory efficient function returning Args is ongoing. + Returns flattened command line flags for given action, using given variables for expansion. Flattens nested sets and ideally should not be used, or at least should not outlive analysis. Work on memory efficient function returning Args is ongoing. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | -| `action_name` | [string](../core/string.mdx); required Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) | -| `variables` | Variables; required Build variables to be used for template expansions. | +ParameterDescription`feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + + Feature configuration to be queried. + `action_name`[string](../core/string.html); + required + + Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) + `variables` + Variables; + required + + Build variables to be used for template expansions. + ## get\_tool\_for\_action @@ -385,14 +822,20 @@ Returns flattened command line flags for given action, using given variables for string cc_common.get_tool_for_action(*, feature_configuration, action_name) ``` -Returns tool path for given action. + Returns tool path for given action. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | -| `action_name` | [string](../core/string.mdx); required Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) | +ParameterDescription`feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + + Feature configuration to be queried. + `action_name`[string](../core/string.html); + required + + Name of the action. Has to be one of the names in @bazel\_tools//tools/build\_defs/cc:action\_names.bzl (https://github.com/bazelbuild/bazel/blob/master/tools/build\_defs/cc/action\_names.bzl) + ## is\_enabled @@ -400,41 +843,90 @@ Returns tool path for given action. bool cc_common.is_enabled(*, feature_configuration, feature_name) ``` -Returns True if given feature is enabled in the feature configuration. + Returns True if given feature is enabled in the feature configuration. + ### Parameters -| Parameter | Description | -| --- | --- | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required Feature configuration to be queried. | -| `feature_name` | [string](../core/string.mdx); required Name of the feature. | +ParameterDescription`feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + + Feature configuration to be queried. + `feature_name`[string](../core/string.html); + required + + Name of the feature. + ## link ``` -CcLinkingOutputs cc_common.link(*, actions, name, feature_configuration, cc_toolchain, language='c++', output_type='executable', link_deps_statically=True, compilation_outputs=None, linking_contexts=[], user_link_flags=[], stamp=0, additional_inputs=[], additional_outputs=[], variables_extension=\{\}) +CcLinkingOutputs cc_common.link(*, actions, name, feature_configuration, cc_toolchain, language='c++', output_type='executable', link_deps_statically=True, compilation_outputs=None, linking_contexts=[], user_link_flags=[], stamp=0, additional_inputs=[], additional_outputs=[], variables_extension={}) ``` -Should be used for C++ transitive linking. + Should be used for C++ transitive linking. + ### Parameters -| Parameter | Description | -| --- | --- | -| `actions` | [actions](../builtins/actions.mdx); required `actions` object. | -| `name` | [string](../core/string.mdx); required This is used for naming the output artifacts of actions created by this method. | -| `feature_configuration` | [FeatureConfiguration](../builtins/FeatureConfiguration.mdx); required `feature_configuration` to be queried. | -| `cc_toolchain` | Info; required `CcToolchainInfo` provider to be used. | -| `language` | [string](../core/string.mdx); default is `'c++'` Only C++ supported for now. Do not use this parameter. | -| `output_type` | [string](../core/string.mdx); default is `'executable'` Can be either 'executable' or 'dynamic\_library'. | -| `link_deps_statically` | [bool](../core/bool.mdx); default is `True` True to link dependencies statically, False dynamically. | -| `compilation_outputs` | [CcCompilationOutputs](../builtins/CcCompilationOutputs.mdx); or `None`; default is `None` Compilation outputs containing object files to link. | -| `linking_contexts` | [sequence](../core/list.mdx); default is `[]` Linking contexts from dependencies to be linked into the linking context generated by this rule. | -| `user_link_flags` | [sequence](../core/list.mdx); default is `[]` Additional list of linker options. | -| `stamp` | [int](../core/int.mdx); default is `0` Whether to include build information in the linked executable, if output\_type is 'executable'. If 1, build information is always included. If 0 (the default build information is always excluded. If -1, uses the default behavior, which may be overridden by the --[no]stamp flag. This should be unset (or set to 0) when generating the executable output for test rules. | -| `additional_inputs` | [sequence](../core/list.mdx); or [depset](../builtins/depset.mdx); default is `[]` For additional inputs to the linking action, e.g.: linking scripts. | -| `additional_outputs` | [sequence](../core/list.mdx); default is `[]` For additional outputs to the linking action, e.g.: map files. | -| `variables_extension` | [dict](../core/dict.mdx); default is `\{\}` Additional variables to pass to the toolchain configuration when create link command line. | +ParameterDescription`actions`[actions](../builtins/actions.html); + required + +`actions` object. + `name`[string](../core/string.html); + required + + This is used for naming the output artifacts of actions created by this method. + `feature_configuration`[FeatureConfiguration](../builtins/FeatureConfiguration.html); + required + +`feature_configuration` to be queried. + `cc_toolchain` + Info; + required + +`CcToolchainInfo` provider to be used. + `language`[string](../core/string.html); + default is `'c++'` + + Only C++ supported for now. Do not use this parameter. + `output_type`[string](../core/string.html); + default is `'executable'` + + Can be either 'executable' or 'dynamic\_library'. + `link_deps_statically`[bool](../core/bool.html); + default is `True` + + True to link dependencies statically, False dynamically. + `compilation_outputs`[CcCompilationOutputs](../builtins/CcCompilationOutputs.html); or `None`; + default is `None` + + Compilation outputs containing object files to link. + `linking_contexts`[sequence](../core/list.html); + default is `[]` + + Linking contexts from dependencies to be linked into the linking context generated by this rule. + `user_link_flags`[sequence](../core/list.html); + default is `[]` + + Additional list of linker options. + `stamp`[int](../core/int.html); + default is `0` + + Whether to include build information in the linked executable, if output\_type is 'executable'. If 1, build information is always included. If 0 (the default build information is always excluded. If -1, uses the default behavior, which may be overridden by the --\[no\]stamp flag. This should be unset (or set to 0) when generating the executable output for test rules. + `additional_inputs`[sequence](../core/list.html); or [depset](../builtins/depset.html); + default is `[]` + + For additional inputs to the linking action, e.g.: linking scripts. + `additional_outputs`[sequence](../core/list.html); + default is `[]` + + For additional outputs to the linking action, e.g.: map files. + `variables_extension`[dict](../core/dict.html); + default is `{}` + + Additional variables to pass to the toolchain configuration when create link command line. + ## merge\_cc\_infos @@ -442,14 +934,20 @@ Should be used for C++ transitive linking. unknown cc_common.merge_cc_infos(*, direct_cc_infos=[], cc_infos=[]) ``` -Merges multiple `CcInfo`s into one. + Merges multiple `CcInfo` s into one. + ### Parameters -| Parameter | Description | -| --- | --- | -| `direct_cc_infos` | [sequence](../core/list.mdx); default is `[]` List of `CcInfo`s to be merged, whose headers will be exported by the direct fields in the returned provider. | -| `cc_infos` | [sequence](../core/list.mdx); default is `[]` List of `CcInfo`s to be merged, whose headers will not be exported by the direct fields in the returned provider. | +ParameterDescription`direct_cc_infos`[sequence](../core/list.html); + default is `[]` + + List of `CcInfo` s to be merged, whose headers will be exported by the direct fields in the returned provider. + `cc_infos`[sequence](../core/list.html); + default is `[]` + + List of `CcInfo` s to be merged, whose headers will not be exported by the direct fields in the returned provider. + ## merge\_compilation\_contexts @@ -457,13 +955,16 @@ Merges multiple `CcInfo`s into one. CompilationContext cc_common.merge_compilation_contexts(*, compilation_contexts=[]) ``` -Merges multiple `CompilationContexts`s into one. + Merges multiple `CompilationContexts` s into one. + ### Parameters -| Parameter | Description | -| --- | --- | -| `compilation_contexts` | [sequence](../core/list.mdx); default is `[]` List of `CompilationContexts`s to be merged. The headers of each context will be exported by the direct fields in the returned provider. | +ParameterDescription`compilation_contexts`[sequence](../core/list.html); + default is `[]` + + List of `CompilationContexts` s to be merged. The headers of each context will be exported by the direct fields in the returned provider. + ## merge\_compilation\_outputs @@ -471,10 +972,10 @@ Merges multiple `CompilationContexts`s into one. CcCompilationOutputs cc_common.merge_compilation_outputs(*, compilation_outputs=[]) ``` -Merge compilation outputs. + Merge compilation outputs. + ### Parameters -| Parameter | Description | -| --- | --- | -| `compilation_outputs` | [sequence](../core/list.mdx); default is `[]` | \ No newline at end of file +ParameterDescription`compilation_outputs`[sequence](../core/list.html); + default is `[]` diff --git a/rules/lib/toplevel/config.mdx b/rules/lib/toplevel/config.mdx index 2b9b218..6cfef86 100644 --- a/rules/lib/toplevel/config.mdx +++ b/rules/lib/toplevel/config.mdx @@ -3,9 +3,10 @@ title: 'config' --- + This is a top-level module for creating configuration transitions and build setting descriptors which describe what kind of build setting (if any) a rule is. -ex: the following rule is marked as a build setting by setting the `build_setting` parameter of the `rule()` function. Specifically it is a build setting of type `int` and is a `flag` which means this build setting is callable on the command line. +ex: the following rule is marked as a build setting by setting the `build_setting` parameter of the `rule()` function. Specifically it is a build setting of type `int` and is a `flag` which means this build setting is callable on the command line. ``` my_rule = rule( @@ -17,14 +18,14 @@ ex: the following rule is marked as a build setting by setting the `build_settin ## Members -* [bool](#bool) -* [exec](#exec) -* [int](#int) -* [none](#none) -* [string](#string) -* [string\_list](#string_list) -* [string\_set](#string_set) -* [target](#target) +- [bool](#bool) +- [exec](#exec) +- [int](#int) +- [none](#none) +- [string](#string) +- [string\_list](#string_list) +- [string\_set](#string_set) +- [target](#target) ## bool @@ -32,13 +33,16 @@ ex: the following rule is marked as a build setting by setting the `build_settin BuildSetting config.bool(*, flag=False) ``` -A bool-typed build setting + A bool-typed build setting + ### Parameters -| Parameter | Description | -| --- | --- | -| `flag` | [bool](../core/bool.mdx); default is `False` | +ParameterDescription`flag`[bool](../core/bool.html); + default is `False` + + Whether or not this build setting is callable on the command line. + ## exec @@ -46,13 +50,16 @@ A bool-typed build setting ExecTransitionFactory config.exec(exec_group=None) ``` -Creates an execution transition. + Creates an execution transition. + ### Parameters -| Parameter | Description | -| --- | --- | -| `exec_group` | [string](../core/string.mdx); or `None`; default is `None` The name of the exec group whose execution platform this transition will use. If not provided, this exec transition will use the target's default execution platform. | +ParameterDescription`exec_group`[string](../core/string.html); or `None`; + default is `None` + + The name of the exec group whose execution platform this transition will use. If not provided, this exec transition will use the target's default execution platform. + ## int @@ -60,13 +67,16 @@ Creates an execution transition. BuildSetting config.int(*, flag=False) ``` -An integer-typed build setting + An integer-typed build setting + ### Parameters -| Parameter | Description | -| --- | --- | -| `flag` | [bool](../core/bool.mdx); default is `False` Whether or not this build setting is callable on the command line. | +ParameterDescription`flag`[bool](../core/bool.html); + default is `False` + + Whether or not this build setting is callable on the command line. + ## none @@ -74,7 +84,9 @@ An integer-typed build setting transition config.none() ``` -Creates a transition which removes all configuration, unsetting all flags. Intended for the case where a dependency is data-only and contains no code that needs to be built, but should only be analyzed once. + Creates a transition which removes all configuration, unsetting all flags. Intended for the case where a dependency is data-only and contains no code that needs to be built, but should only be analyzed once. + + ## string @@ -82,14 +94,20 @@ Creates a transition which removes all configuration, unsetting all flags. Inten BuildSetting config.string(*, flag=False, allow_multiple=False) ``` -A string-typed build setting + A string-typed build setting + ### Parameters -| Parameter | Description | -| --- | --- | -| `flag` | [bool](../core/bool.mdx); default is `False` Whether or not this build setting is callable on the command line. | -| `allow_multiple` | [bool](../core/bool.mdx); default is `False` Deprecated, use a `string_list` setting with `repeatable = True` instead. If set, this flag is allowed to be set multiple times on the command line. The Value of the flag as accessed in transitions and build setting implementation function will be a list of strings. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. | +ParameterDescription`flag`[bool](../core/bool.html); + default is `False` + + Whether or not this build setting is callable on the command line. + `allow_multiple`[bool](../core/bool.html); + default is `False` + + Deprecated, use a `string_list` setting with `repeatable = True` instead. If set, this flag is allowed to be set multiple times on the command line. The Value of the flag as accessed in transitions and build setting implementation function will be a list of strings. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. + ## string\_list @@ -97,14 +115,20 @@ A string-typed build setting BuildSetting config.string_list(*, flag=False, repeatable=False) ``` -A string list-typed build setting. On the command line pass a list using comma-separated value like `--//my/setting=foo,bar`. + A string list-typed build setting. On the command line pass a list using comma-separated value like `--//my/setting=foo,bar`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `flag` | [bool](../core/bool.mdx); default is `False` Whether or not this build setting is callable on the command line. | -| `repeatable` | [bool](../core/bool.mdx); default is `False` If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the list value. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. | +ParameterDescription`flag`[bool](../core/bool.html); + default is `False` + + Whether or not this build setting is callable on the command line. + `repeatable`[bool](../core/bool.html); + default is `False` + + If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the list value. Insertion order and repeated values are both maintained. This list can be post-processed in the build setting implementation function if different behavior is desired. + ## string\_set @@ -112,16 +136,22 @@ A string list-typed build setting. On the command line pass a list using comma-s BuildSetting config.string_set(*, flag=False, repeatable=False) ``` -A string set-typed build setting. The value of this setting will be a [set](https://bazel.build/rules/lib/core/set) of strings in Starlark. On the command line, pass a set using a comma-separated value like `--//my/setting=foo,bar`. + A string set-typed build setting. The value of this setting will be a [set](https://bazel.build/rules/lib/core/set) of strings in Starlark. On the command line, pass a set using a comma-separated value like `--//my/setting=foo,bar`. Unlike with a `string_list`, the order of the elements doesn't matter and only a single instance of each element is maintained. This is recommended over `string_list` for flags where these properties are not needed as it can improve build performance by avoiding unnecessary configurations forking. + ### Parameters -| Parameter | Description | -| --- | --- | -| `flag` | [bool](../core/bool.mdx); default is `False` Whether or not this build setting is callable on the command line. | -| `repeatable` | [bool](../core/bool.mdx); default is `False` If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the set value. Only a single instance of repeated values is maintained and the insertion order does not matter. | +ParameterDescription`flag`[bool](../core/bool.html); + default is `False` + + Whether or not this build setting is callable on the command line. + `repeatable`[bool](../core/bool.html); + default is `False` + + If set, instead of expecting a comma-separated value, this flag is allowed to be set multiple times on the command line with each individual value treated as a single string to add to the set value. Only a single instance of repeated values is maintained and the insertion order does not matter. + ## target @@ -129,4 +159,4 @@ Unlike with a `string_list`, the order of the elements doesn't matter and only a transition config.target() ``` -Creates a target transition. This is a no-op transition intended for the case where a transition object is needed, but doesn't want to actually change anything. Equivalent to `cfg = "target"` in `attr.label()`. \ No newline at end of file + Creates a target transition. This is a no-op transition intended for the case where a transition object is needed, but doesn't want to actually change anything. Equivalent to `cfg = "target"` in `attr.label()`. diff --git a/rules/lib/toplevel/config_common.mdx b/rules/lib/toplevel/config_common.mdx index 071e28f..eda97b5 100644 --- a/rules/lib/toplevel/config_common.mdx +++ b/rules/lib/toplevel/config_common.mdx @@ -1,14 +1,15 @@ --- -title: 'config_common' +title: 'config\_common' --- + Functions for Starlark to interact with Blaze's configurability APIs. ## Members -* [FeatureFlagInfo](#FeatureFlagInfo) -* [toolchain\_type](#toolchain_type) +- [FeatureFlagInfo](#FeatureFlagInfo) +- [toolchain\_type](#toolchain_type) ## FeatureFlagInfo @@ -16,7 +17,9 @@ Functions for Starlark to interact with Blaze's configurability APIs. Provider config_common.FeatureFlagInfo ``` -The key used to retrieve the provider containing config\_feature\_flag's value. + The key used to retrieve the provider containing config\_feature\_flag's value. + + ## toolchain\_type @@ -24,11 +27,16 @@ The key used to retrieve the provider containing config\_feature\_flag's value. toolchain_type config_common.toolchain_type(name, *, mandatory=True) ``` -Declare a rule's dependency on a toolchain type. + Declare a rule's dependency on a toolchain type. + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); required The toolchain type that is required. | -| `mandatory` | [bool](../core/bool.mdx); default is `True` Whether the toolchain type is mandatory or optional. | \ No newline at end of file +ParameterDescription`name`[string](../core/string.html); or [Label](../builtins/Label.html); + required + + The toolchain type that is required. + `mandatory`[bool](../core/bool.html); + default is `True` + + Whether the toolchain type is mandatory or optional. diff --git a/rules/lib/toplevel/coverage_common.mdx b/rules/lib/toplevel/coverage_common.mdx index 372b7e2..e951e39 100644 --- a/rules/lib/toplevel/coverage_common.mdx +++ b/rules/lib/toplevel/coverage_common.mdx @@ -1,13 +1,14 @@ --- -title: 'coverage_common' +title: 'coverage\_common' --- + Helper functions to access coverage-related infrastructure. ## Members -* [instrumented\_files\_info](#instrumented_files_info) +- [instrumented\_files\_info](#instrumented_files_info) ## instrumented\_files\_info @@ -15,15 +16,30 @@ Helper functions to access coverage-related infrastructure. InstrumentedFilesInfo coverage_common.instrumented_files_info(ctx, *, source_attributes=[], dependency_attributes=[], extensions=None, metadata_files=[], baseline_coverage_files=None) ``` -Creates a new [InstrumentedFilesInfo](../providers/InstrumentedFilesInfo.mdx) instance. Use this provider to communicate coverage-related attributes of the current build rule. + Creates a new [InstrumentedFilesInfo](../providers/InstrumentedFilesInfo.html) instance. Use this provider to communicate coverage-related attributes of the current build rule. + ### Parameters -| Parameter | Description | -| --- | --- | -| `ctx` | [ctx](../builtins/ctx.mdx); required The rule context. | -| `source_attributes` | [sequence](../core/list.mdx); default is `[]` A list of attribute names which contain source files processed by this rule. | -| `dependency_attributes` | [sequence](../core/list.mdx); default is `[]` A list of attribute names which might provide runtime dependencies (either code dependencies or runfiles). | -| `extensions` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` File extensions used to filter files from source\_attributes. For example, 'js'. If not provided (or None), then all files from source\_attributes will be added to instrumented files, if an empty list is provided, then no files from source attributes will be added. | -| `metadata_files` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` Additional files required to generate coverage LCOV files after code execution. e.g. .gcno files for C++. | -| `baseline_coverage_files` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; or `None`; default is `None` | \ No newline at end of file +ParameterDescription`ctx`[ctx](../builtins/ctx.html); + required + + The rule context. + `source_attributes`[sequence](../core/list.html); + default is `[]` + + A list of attribute names which contain source files processed by this rule. + `dependency_attributes`[sequence](../core/list.html); + default is `[]` + + A list of attribute names which might provide runtime dependencies (either code dependencies or runfiles). + `extensions`[sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + File extensions used to filter files from source\_attributes. For example, 'js'. If not provided (or None), then all files from source\_attributes will be added to instrumented files, if an empty list is provided, then no files from source attributes will be added. + `metadata_files`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + + Additional files required to generate coverage LCOV files after code execution. e.g. .gcno files for C++. + `baseline_coverage_files`[sequence](../core/list.html) of [File](../builtins/File.html) s; or `None`; + default is `None` diff --git a/rules/lib/toplevel/java_common.mdx b/rules/lib/toplevel/java_common.mdx index 20f3f17..f3dae10 100644 --- a/rules/lib/toplevel/java_common.mdx +++ b/rules/lib/toplevel/java_common.mdx @@ -1,20 +1,21 @@ --- -title: 'java_common' +title: 'java\_common' --- + Utilities for Java compilation support in Starlark. ## Members -* [BootClassPathInfo](#BootClassPathInfo) -* [compile](#compile) -* [JavaRuntimeInfo](#JavaRuntimeInfo) -* [JavaToolchainInfo](#JavaToolchainInfo) -* [merge](#merge) -* [pack\_sources](#pack_sources) -* [run\_ijar](#run_ijar) -* [stamp\_jar](#stamp_jar) +- [BootClassPathInfo](#BootClassPathInfo) +- [compile](#compile) +- [JavaRuntimeInfo](#JavaRuntimeInfo) +- [JavaToolchainInfo](#JavaToolchainInfo) +- [merge](#merge) +- [pack\_sources](#pack_sources) +- [run\_ijar](#run_ijar) +- [stamp\_jar](#stamp_jar) ## BootClassPathInfo @@ -22,7 +23,9 @@ Utilities for Java compilation support in Starlark. Provider java_common.BootClassPathInfo ``` -The provider used to supply bootclasspath information + The provider used to supply bootclasspath information + + ## compile @@ -30,38 +33,111 @@ The provider used to supply bootclasspath information struct java_common.compile(ctx, *, source_jars=[], source_files=[], output, output_source_jar=None, javac_opts=[], deps=[], runtime_deps=[], exports=[], plugins=[], exported_plugins=[], native_libraries=[], annotation_processor_additional_inputs=[], annotation_processor_additional_outputs=[], strict_deps='ERROR', java_toolchain, bootclasspath=None, sourcepath=[], resources=[], resource_jars=[], classpath_resources=[], neverlink=False, enable_annotation_processing=True, enable_compile_jar_action=True, add_exports=[], add_opens=[]) ``` -Compiles Java source files/jars from the implementation of a Starlark rule and returns a provider that represents the results of the compilation and can be added to the set of providers emitted by this rule. + Compiles Java source files/jars from the implementation of a Starlark rule and returns a provider that represents the results of the compilation and can be added to the set of providers emitted by this rule. + ### Parameters -| Parameter | Description | -| --- | --- | -| `ctx` | [ctx](../builtins/ctx.mdx); required The rule context. | -| `source_jars` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of the jars to be compiled. At least one of source\_jars or source\_files should be specified. | -| `source_files` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of the Java source files to be compiled. At least one of source\_jars or source\_files should be specified. | -| `output` | [File](../builtins/File.mdx); required | -| `output_source_jar` | [File](../builtins/File.mdx); or `None`; default is `None` The output source jar. Defaults to `\{output\_jar\}-src.jar` if unset. | -| `javac_opts` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A list of the desired javac options. | -| `deps` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of dependencies. | -| `runtime_deps` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of runtime dependencies. | -| `exports` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of exports. | -| `plugins` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; or [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of plugins. | -| `exported_plugins` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; or [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; default is `[]` A list of exported plugins. | -| `native_libraries` | [sequence](../core/list.mdx) of [CcInfo](../providers/CcInfo.mdx)s; default is `[]` CC native library dependencies that are needed for this library. | -| `annotation_processor_additional_inputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of inputs that the Java compilation action will take in addition to the Java sources for annotation processing. | -| `annotation_processor_additional_outputs` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of outputs that the Java compilation action will output in addition to the class jar from annotation processing. | -| `strict_deps` | [string](../core/string.mdx); default is `'ERROR'` A string that specifies how to handle strict deps. Possible values: 'OFF', 'ERROR', 'WARN' and 'DEFAULT'. For more details see [`--strict_java_deps flag`](./docs/user-manual#flag--strict_java_deps). By default 'ERROR'. | -| `java_toolchain` | Info; required A JavaToolchainInfo to be used for this compilation. Mandatory. | -| `bootclasspath` | default is `None` A BootClassPathInfo to be used for this compilation. If present, overrides the bootclasspath associated with the provided java\_toolchain. | -| `sourcepath` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` | -| `resources` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` | -| `resource_jars` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` | -| `classpath_resources` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` | -| `neverlink` | [bool](../core/bool.mdx); default is `False` | -| `enable_annotation_processing` | [bool](../core/bool.mdx); default is `True` Disables annotation processing in this compilation, causing any annotation processors provided in plugins or in exported\_plugins of deps to be ignored. | -| `enable_compile_jar_action` | [bool](../core/bool.mdx); default is `True` Enables header compilation or ijar creation. If set to False, it forces use of the full class jar in the compilation classpaths of any dependants. Doing so is intended for use by non-library targets such as binaries that do not have dependants. | -| `add_exports` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Allow this library to access the given /. | -| `add_opens` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Allow this library to reflectively access the given /. | +ParameterDescription`ctx`[ctx](../builtins/ctx.html); + required + + The rule context. + `source_jars`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + + A list of the jars to be compiled. At least one of source\_jars or source\_files should be specified. + `source_files`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + + A list of the Java source files to be compiled. At least one of source\_jars or source\_files should be specified. + `output`[File](../builtins/File.html); + required + +`output_source_jar`[File](../builtins/File.html); or `None`; + default is `None` + + The output source jar. Defaults to \`{output\_jar}-src.jar\` if unset. + `javac_opts`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + A list of the desired javac options. + `deps`[sequence](../core/list.html) of [struct](../builtins/struct.html) s; + default is `[]` + + A list of dependencies. + `runtime_deps`[sequence](../core/list.html) of [struct](../builtins/struct.html) s; + default is `[]` + + A list of runtime dependencies. + `exports`[sequence](../core/list.html) of [struct](../builtins/struct.html) s; + default is `[]` + + A list of exports. + `plugins`[sequence](../core/list.html) of [struct](../builtins/struct.html) s; or [sequence](../core/list.html) of [struct](../builtins/struct.html) s; + default is `[]` + + A list of plugins. + `exported_plugins`[sequence](../core/list.html) of [struct](../builtins/struct.html) s; or [sequence](../core/list.html) of [struct](../builtins/struct.html) s; + default is `[]` + + A list of exported plugins. + `native_libraries`[sequence](../core/list.html) of [CcInfo](../providers/CcInfo.html) s; + default is `[]` + + CC native library dependencies that are needed for this library. + `annotation_processor_additional_inputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + + A list of inputs that the Java compilation action will take in addition to the Java sources for annotation processing. + `annotation_processor_additional_outputs`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + + A list of outputs that the Java compilation action will output in addition to the class jar from annotation processing. + `strict_deps`[string](../core/string.html); + default is `'ERROR'` + + A string that specifies how to handle strict deps. Possible values: 'OFF', 'ERROR', 'WARN' and 'DEFAULT'. For more details see [`--strict_java_deps flag`](/docs/user-manual#flag--strict_java_deps) `. By default 'ERROR'. + ``java_toolchain` + Info; + required + + A JavaToolchainInfo to be used for this compilation. Mandatory. + `bootclasspath` + default is `None` + + A BootClassPathInfo to be used for this compilation. If present, overrides the bootclasspath associated with the provided java\_toolchain. + `sourcepath`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + +`resources`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + +`resource_jars`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + +`classpath_resources`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + +`neverlink`[bool](../core/bool.html); + default is `False` + +`enable_annotation_processing`[bool](../core/bool.html); + default is `True` + + Disables annotation processing in this compilation, causing any annotation processors provided in plugins or in exported\_plugins of deps to be ignored. + `enable_compile_jar_action`[bool](../core/bool.html); + default is `True` + + Enables header compilation or ijar creation. If set to False, it forces use of the full class jar in the compilation classpaths of any dependants. Doing so is intended for use by non-library targets such as binaries that do not have dependants. + `add_exports`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Allow this library to access the given /. + `add_opens`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Allow this library to reflectively access the given /. + ## JavaRuntimeInfo @@ -69,7 +145,9 @@ Compiles Java source files/jars from the implementation of a Starlark rule and r Provider java_common.JavaRuntimeInfo ``` -The key used to retrieve the provider that contains information about the Java runtime being used. + The key used to retrieve the provider that contains information about the Java runtime being used. + + ## JavaToolchainInfo @@ -77,7 +155,9 @@ The key used to retrieve the provider that contains information about the Java r Provider java_common.JavaToolchainInfo ``` -The key used to retrieve the provider that contains information about the Java toolchain being used. + The key used to retrieve the provider that contains information about the Java toolchain being used. + + ## merge @@ -85,13 +165,16 @@ The key used to retrieve the provider that contains information about the Java t struct java_common.merge(providers) ``` -Merges the given providers into a single JavaInfo. + Merges the given providers into a single JavaInfo. + ### Parameters -| Parameter | Description | -| --- | --- | -| `providers` | [sequence](../core/list.mdx) of [struct](../builtins/struct.mdx)s; required The list of providers to merge. | +ParameterDescription`providers`[sequence](../core/list.html) of [struct](../builtins/struct.html) s; + required + + The list of providers to merge. + ## pack\_sources @@ -99,21 +182,37 @@ Merges the given providers into a single JavaInfo. File java_common.pack_sources(actions, *, output_source_jar=None, sources=[], source_jars=[], java_toolchain) ``` -Packs sources and source jars into a single source jar file. The return value is typically passed to + Packs sources and source jars into a single source jar file. The return value is typically passed to `JavaInfo#source_jar` .At least one of parameters output\_jar or output\_source\_jar is required. + ### Parameters -| Parameter | Description | -| --- | --- | -| `actions` | [actions](../builtins/actions.mdx); required ctx.actions | -| `output_source_jar` | [File](../builtins/File.mdx); or `None`; default is `None` The output source jar. | -| `sources` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of Java source files to be packed into the source jar. | -| `source_jars` | [sequence](../core/list.mdx) of [File](../builtins/File.mdx)s; default is `[]` A list of source jars to be packed into the source jar. | -| `java_toolchain` | Info; required A JavaToolchainInfo to used to find the ijar tool. | +ParameterDescription`actions`[actions](../builtins/actions.html); + required + + ctx.actions + `output_source_jar`[File](../builtins/File.html); or `None`; + default is `None` + + The output source jar. + `sources`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + + A list of Java source files to be packed into the source jar. + `source_jars`[sequence](../core/list.html) of [File](../builtins/File.html) s; + default is `[]` + + A list of source jars to be packed into the source jar. + `java_toolchain` + Info; + required + + A JavaToolchainInfo to used to find the ijar tool. + ## run\_ijar @@ -121,16 +220,29 @@ Packs sources and source jars into a single source jar file. The return value is File java_common.run_ijar(actions, *, jar, target_label=None, java_toolchain) ``` -Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding of dependent jars during any recompiles consisting only of simple changes to method implementations. The return value is typically passed to `JavaInfo#compile_jar`. + Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding of dependent jars during any recompiles consisting only of simple changes to method implementations. The return value is typically passed to `JavaInfo#compile_jar`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `actions` | [actions](../builtins/actions.mdx); required ctx.actions | -| `jar` | [File](../builtins/File.mdx); required The jar to run ijar on. | -| `target_label` | [Label](../builtins/Label.mdx); or `None`; default is `None` A target label to stamp the jar with. Used for `add_dep` support. Typically, you would pass `ctx.label` to stamp the jar with the current rule's label. | -| `java_toolchain` | Info; required A JavaToolchainInfo to used to find the ijar tool. | +ParameterDescription`actions`[actions](../builtins/actions.html); + required + + ctx.actions + `jar`[File](../builtins/File.html); + required + + The jar to run ijar on. + `target_label`[Label](../builtins/Label.html); or `None`; + default is `None` + + A target label to stamp the jar with. Used for `add_dep` support. Typically, you would pass `ctx.label` to stamp the jar with the current rule's label. + `java_toolchain` + Info; + required + + A JavaToolchainInfo to used to find the ijar tool. + ## stamp\_jar @@ -138,13 +250,25 @@ Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuild File java_common.stamp_jar(actions, *, jar, target_label, java_toolchain) ``` -Stamps a jar with a target label for `add_dep` support. The return value is typically passed to `JavaInfo#compile_jar`. Prefer to use `run_ijar` when possible. + Stamps a jar with a target label for `add_dep` support. The return value is typically passed to `JavaInfo#compile_jar`. Prefer to use `run_ijar` when possible. + ### Parameters -| Parameter | Description | -| --- | --- | -| `actions` | [actions](../builtins/actions.mdx); required ctx.actions | -| `jar` | [File](../builtins/File.mdx); required The jar to run stamp\_jar on. | -| `target_label` | [Label](../builtins/Label.mdx); required A target label to stamp the jar with. Used for `add_dep` support. Typically, you would pass `ctx.label` to stamp the jar with the current rule's label. | -| `java_toolchain` | Info; required A JavaToolchainInfo to used to find the stamp\_jar tool. | \ No newline at end of file +ParameterDescription`actions`[actions](../builtins/actions.html); + required + + ctx.actions + `jar`[File](../builtins/File.html); + required + + The jar to run stamp\_jar on. + `target_label`[Label](../builtins/Label.html); + required + + A target label to stamp the jar with. Used for `add_dep` support. Typically, you would pass `ctx.label` to stamp the jar with the current rule's label. + `java_toolchain` + Info; + required + + A JavaToolchainInfo to used to find the stamp\_jar tool. diff --git a/rules/lib/toplevel/native.mdx b/rules/lib/toplevel/native.mdx index 8a11ae4..922f466 100644 --- a/rules/lib/toplevel/native.mdx +++ b/rules/lib/toplevel/native.mdx @@ -3,24 +3,26 @@ title: 'native' --- -A built-in module to support native rules and other package helper functions. All native rules appear as functions in this module, e.g. `native.cc_library`. Note that the native module is only available in the loading phase (i.e. for macros, not for rule implementations). Attributes will ignore `None` values, and treat them as if the attribute was unset. + +A built-in module to support native rules and other package helper functions. All native rules appear as functions in this module, e.g. `native.cc_library`. Note that the native module is only available in the loading phase (i.e. for macros, not for rule implementations). Attributes will ignore `None` values, and treat them as if the attribute was unset. + The following functions are also available: ## Members -* [existing\_rule](#existing_rule) -* [existing\_rules](#existing_rules) -* [exports\_files](#exports_files) -* [glob](#glob) -* [module\_name](#module_name) -* [module\_version](#module_version) -* [package\_default\_visibility](#package_default_visibility) -* [package\_group](#package_group) -* [package\_name](#package_name) -* [package\_relative\_label](#package_relative_label) -* [repo\_name](#repo_name) -* [repository\_name](#repository_name) -* [subpackages](#subpackages) +- [existing\_rule](#existing_rule) +- [existing\_rules](#existing_rules) +- [exports\_files](#exports_files) +- [glob](#glob) +- [module\_name](#module_name) +- [module\_version](#module_version) +- [package\_default\_visibility](#package_default_visibility) +- [package\_group](#package_group) +- [package\_name](#package_name) +- [package\_relative\_label](#package_relative_label) +- [repo\_name](#repo_name) +- [repository\_name](#repository_name) +- [subpackages](#subpackages) ## existing\_rule @@ -28,27 +30,30 @@ The following functions are also available: unknown native.existing_rule(name) ``` -Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or `None` if no rule instance of that name exists. + Returns an immutable dict-like object that describes the attributes of a rule instantiated in this thread's package, or `None` if no rule instance of that name exists. -Here, an *immutable dict-like object* means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. +Here, an _immutable dict-like object_ means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's `name` and `kind` (for example, `'cc_binary'`). The values of the result represent attribute values as follows: -* Attributes of type str, int, and bool are represented as is. -* Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. -* Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. -* `select` values are returned with their contents transformed as described above. -* Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). +- Attributes of type str, int, and bool are represented as is. +- Labels are converted to strings of the form `':foo'` for targets in the same package or `'//pkg:name'` for targets in a different package. +- Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion. +- `select` values are returned with their contents transformed as described above. +- Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.). If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by `ctx.attr.foo`. + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required | +ParameterDescription`name`[string](../core/string.html); + required + + The name of the target. + ## existing\_rules @@ -56,27 +61,38 @@ If possible, use this function only in [implementation functions of rule finaliz unknown native.existing_rules() ``` -Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by `existing_rule(name)`. + Returns an immutable dict-like object describing the rules so far instantiated in this thread's package. Each entry of the dict-like object maps the name of the rule instance to the result that would be returned by `existing_rule(name)`. -Here, an *immutable dict-like object* means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. +Here, an _immutable dict-like object_ means a deeply immutable object `x` supporting dict-like iteration, `len(x)`, `name in x`, `x[name]`, `x.get(name)`, `x.items()`, `x.keys()`, and `x.values()`. If possible, use this function only in [implementation functions of rule finalizer symbolic macros](https://bazel.build/extending/macros#finalizers). Use of this function in other contexts is not recommened, and will be disabled in a future Bazel release; it makes `BUILD` files brittle and order-dependent. + + ## exports\_files ``` None native.exports_files(srcs, visibility=None, licenses=None) ``` -Specifies a list of files belonging to this package that are exported to other packages. + Specifies a list of files belonging to this package that are exported to other packages. + ### Parameters -| Parameter | Description | -| --- | --- | -| `srcs` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required The list of files to export. | -| `visibility` | [sequence](../core/list.mdx); or `None`; default is `None` A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. | -| `licenses` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; or `None`; default is `None` Licenses to be specified. | +ParameterDescription`srcs`[sequence](../core/list.html) of [string](../core/string.html) s; + required + + The list of files to export. + `visibility`[sequence](../core/list.html); or `None`; + default is `None` + + A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. + `licenses`[sequence](../core/list.html) of [string](../core/string.html) s; or `None`; + default is `None` + + Licenses to be specified. + ## glob @@ -84,21 +100,33 @@ Specifies a list of files belonging to this package that are exported to other p sequence native.glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound) ``` -Glob returns a new, mutable, sorted list of every file in the current package that: + Glob returns a new, mutable, sorted list of every file in the current package that: -* Matches at least one pattern in `include`. -* Does not match any of the patterns in `exclude` (default `[]`). +- Matches at least one pattern in `include`. +- Does not match any of the patterns in `exclude` (default `[]`). If the `exclude_directories` argument is enabled (set to `1`), files of type directory will be omitted from the results (default `1`). + ### Parameters -| Parameter | Description | -| --- | --- | -| `include` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to include. | -| `exclude` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to exclude. | -| `exclude_directories` | [int](../core/int.mdx); default is `1` A flag whether to exclude directories or not. | -| `allow_empty` | default is `unbound` Whether we allow glob patterns to match nothing. If `allow\_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). | +ParameterDescription`include`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + The list of glob patterns to include. + `exclude`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + The list of glob patterns to exclude. + `exclude_directories`[int](../core/int.html); + default is `1` + + A flag whether to exclude directories or not. + `allow_empty` + default is `unbound` + + Whether we allow glob patterns to match nothing. If \`allow\_empty\` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the \`exclude\` patterns are excluded). + ## module\_name @@ -106,8 +134,10 @@ If the `exclude_directories` argument is enabled (set to `1`), files of type dir string native.module_name() ``` -The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the `module.name` field seen in `module_ctx.modules`. -May return `None`. + The name of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the name of the module hosting the extension. It's the same as the `module.name` field seen in `module_ctx.modules`. + May return `None`. + + ## module\_version @@ -115,8 +145,10 @@ May return `None`. string native.module_version() ``` -The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the `module.version` field seen in `module_ctx.modules`. -May return `None`. + The version of the Bazel module associated with the repo this package is in. If this package is from a repo defined in WORKSPACE instead of MODULE.bazel, this is empty. For repos generated by module extensions, this is the version of the module hosting the extension. It's the same as the `module.version` field seen in `module_ctx.modules`. + May return `None`. + + ## package\_default\_visibility @@ -124,7 +156,9 @@ May return `None`. List native.package_default_visibility() ``` -Returns the default visibility of the package being evaluated. This is the value of the `default_visibility` parameter of `package()`, extended to include the package itself. + Returns the default visibility of the package being evaluated. This is the value of the `default_visibility` parameter of `package()`, extended to include the package itself. + + ## package\_group @@ -132,15 +166,24 @@ Returns the default visibility of the package being evaluated. This is the value None native.package_group(*, name, packages=[], includes=[]) ``` -This function defines a set of packages and assigns a label to the group. The label can be referenced in `visibility` attributes. + This function defines a set of packages and assigns a label to the group. The label can be referenced in `visibility` attributes. + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required The unique name for this rule. | -| `packages` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A complete enumeration of packages in this group. | -| `includes` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` Other package groups that are included in this one. | +ParameterDescription`name`[string](../core/string.html); + required + + The unique name for this rule. + `packages`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + A complete enumeration of packages in this group. + `includes`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + Other package groups that are included in this one. + ## package\_name @@ -148,7 +191,9 @@ This function defines a set of packages and assigns a label to the group. The la string native.package_name() ``` -The name of the package being evaluated, without the repository name. For example, in the BUILD file `some/package/BUILD`, its value will be `some/package`. If the BUILD file calls a function defined in a .bzl file, `package_name()` will match the caller BUILD file package. The value will always be an empty string for the root package. + The name of the package being evaluated, without the repository name. For example, in the BUILD file `some/package/BUILD`, its value will be `some/package`. If the BUILD file calls a function defined in a .bzl file, `package_name()` will match the caller BUILD file package. The value will always be an empty string for the root package. + + ## package\_relative\_label @@ -156,19 +201,22 @@ The name of the package being evaluated, without the repository name. For exampl Label native.package_relative_label(input) ``` -Converts the input string into a [Label](../builtins/Label.mdx) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. + Converts the input string into a [Label](../builtins/Label.html) object, in the context of the package currently being initialized (that is, the `BUILD` file for which the current macro is executing). If the input is already a `Label`, it is returned unchanged. This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function. The result of this function is the same `Label` value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file. -*Usage note:* The difference between this function and [Label()](../builtins/Label.html#Label) is that `Label()` uses the context of the package of the `.bzl` file that called it, not the package of the `BUILD` file. Use `Label()` when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use `package_relative_label()` when you need to normalize a label string supplied by the BUILD file to a `Label` object. (There is no way to convert a string to a `Label` in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) +_Usage note:_ The difference between this function and [Label()](../builtins/Label.html#Label) is that `Label()` uses the context of the package of the `.bzl` file that called it, not the package of the `BUILD` file. Use `Label()` when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use `package_relative_label()` when you need to normalize a label string supplied by the BUILD file to a `Label` object. (There is no way to convert a string to a `Label` in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.) + ### Parameters -| Parameter | Description | -| --- | --- | -| `input` | [string](../core/string.mdx); or [Label](../builtins/Label.mdx); required The input label string or Label object. If a Label object is passed, it's returned as is. | +ParameterDescription`input`[string](../core/string.html); or [Label](../builtins/Label.html); + required + + The input label string or Label object. If a Label object is passed, it's returned as is. + ## repo\_name @@ -176,7 +224,9 @@ The result of this function is the same `Label` value as would be produced by pa string native.repo_name() ``` -The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. + The canonical name of the repository containing the package currently being evaluated, with no leading at-signs. + + ## repository\_name @@ -184,10 +234,13 @@ The canonical name of the repository containing the package currently being eval string native.repository_name() ``` -**Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` + **Experimental**. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting `--+incompatible_enable_deprecated_label_apis` + **Deprecated.** Prefer to use [`repo_name`](#repo_name) instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise. -The canonical name of the repository containing the package currently being evaluated, with a single at-sign (`@`) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza `local_repository(name='local', path=...)` it will be set to `@local`. In packages in the main repository, it will be set to `@`. +The canonical name of the repository containing the package currently being evaluated, with a single at-sign ( `@`) prefixed. For example, in packages that are called into existence by the WORKSPACE stanza `local_repository(name='local', path=...)` it will be set to `@local`. In packages in the main repository, it will be set to `@`. + + ## subpackages @@ -195,12 +248,20 @@ The canonical name of the repository containing the package currently being eval sequence native.subpackages(*, include, exclude=[], allow_empty=False) ``` -Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel\_skylib.subpackages module rather than calling this function directly. + Returns a new mutable list of every direct subpackage of the current package, regardless of file-system directory depth. List returned is sorted and contains the names of subpackages relative to the current package. It is advised to prefer using the methods in bazel\_skylib.subpackages module rather than calling this function directly. + ### Parameters -| Parameter | Description | -| --- | --- | -| `include` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; required | -| `exclude` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` The list of glob patterns to exclude from subpackages scan. | -| `allow_empty` | [bool](../core/bool.mdx); default is `False` Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. | \ No newline at end of file +ParameterDescription`include`[sequence](../core/list.html) of [string](../core/string.html) s; + required + + The list of glob patterns to include in subpackages scan. + `exclude`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + The list of glob patterns to exclude from subpackages scan. + `allow_empty`[bool](../core/bool.html); + default is `False` + + Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. diff --git a/rules/lib/toplevel/platform_common.mdx b/rules/lib/toplevel/platform_common.mdx index 42c5234..2534821 100644 --- a/rules/lib/toplevel/platform_common.mdx +++ b/rules/lib/toplevel/platform_common.mdx @@ -1,17 +1,18 @@ --- -title: 'platform_common' +title: 'platform\_common' --- + Functions for Starlark to interact with the platform APIs. ## Members -* [ConstraintSettingInfo](#ConstraintSettingInfo) -* [ConstraintValueInfo](#ConstraintValueInfo) -* [PlatformInfo](#PlatformInfo) -* [TemplateVariableInfo](#TemplateVariableInfo) -* [ToolchainInfo](#ToolchainInfo) +- [ConstraintSettingInfo](#ConstraintSettingInfo) +- [ConstraintValueInfo](#ConstraintValueInfo) +- [PlatformInfo](#PlatformInfo) +- [TemplateVariableInfo](#TemplateVariableInfo) +- [ToolchainInfo](#ToolchainInfo) ## ConstraintSettingInfo @@ -19,8 +20,9 @@ Functions for Starlark to interact with the platform APIs. Provider platform_common.ConstraintSettingInfo ``` -The constructor/key for the [ConstraintSettingInfo](../providers/ConstraintSettingInfo.mdx) provider. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* + The constructor/key for the [ConstraintSettingInfo](../providers/ConstraintSettingInfo.html) provider. + +_Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`_ ## ConstraintValueInfo @@ -28,8 +30,9 @@ The constructor/key for the [ConstraintSettingInfo](../providers/ConstraintSetti Provider platform_common.ConstraintValueInfo ``` -The constructor/key for the [ConstraintValueInfo](../providers/ConstraintValueInfo.mdx) provider. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* + The constructor/key for the [ConstraintValueInfo](../providers/ConstraintValueInfo.html) provider. + +_Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`_ ## PlatformInfo @@ -37,8 +40,9 @@ The constructor/key for the [ConstraintValueInfo](../providers/ConstraintValueIn Provider platform_common.PlatformInfo ``` -The constructor/key for the [PlatformInfo](../providers/PlatformInfo.mdx) provider. -*Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`* + The constructor/key for the [PlatformInfo](../providers/PlatformInfo.html) provider. + +_Note: This API is experimental and may change at any time. It is disabled by default, but may be enabled with `--experimental_platforms_api`_ ## TemplateVariableInfo @@ -46,7 +50,9 @@ The constructor/key for the [PlatformInfo](../providers/PlatformInfo.mdx) provid Provider platform_common.TemplateVariableInfo ``` -The constructor/key for the [TemplateVariableInfo](../providers/TemplateVariableInfo.mdx) provider. + The constructor/key for the [TemplateVariableInfo](../providers/TemplateVariableInfo.html) provider. + + ## ToolchainInfo @@ -54,4 +60,4 @@ The constructor/key for the [TemplateVariableInfo](../providers/TemplateVariable Provider platform_common.ToolchainInfo ``` -The constructor/key for the [ToolchainInfo](../providers/ToolchainInfo.mdx) provider. \ No newline at end of file + The constructor/key for the [ToolchainInfo](../providers/ToolchainInfo.html) provider. diff --git a/rules/lib/toplevel/proto.mdx b/rules/lib/toplevel/proto.mdx index e13cd3c..f430a9d 100644 --- a/rules/lib/toplevel/proto.mdx +++ b/rules/lib/toplevel/proto.mdx @@ -3,11 +3,12 @@ title: 'proto' --- + A module for protocol message processing. ## Members -* [encode\_text](#encode_text) +- [encode\_text](#encode_text) ## encode\_text @@ -15,7 +16,7 @@ A module for protocol message processing. string proto.encode_text(x) ``` -Returns the struct argument's encoding as a text-format protocol message. + Returns the struct argument's encoding as a text-format protocol message. The data structure must be recursively composed of strings, ints, floats, or bools, or structs, sequences, and dicts of these types. A struct is converted to a message. Fields are emitted in name order. @@ -27,7 +28,7 @@ Its elements must not be sequences or dicts. A dict is converted to a repeated field of messages with fields named 'key' and 'value'. Entries are emitted in iteration (insertion) order. The dict's keys must be strings or ints, and its values must not be sequences or dicts. -Examples: +Examples: ``` proto.encode_text(struct(field=123)) @@ -45,38 +46,39 @@ proto.encode_text(struct(field='text', ignored_field=None)) # field: "text" proto.encode_text(struct(field=struct(inner_field='text', ignored_field=None))) -# field \{ +# field { # inner_field: "text" -# \} +# } proto.encode_text(struct(field=[struct(inner_field=1), struct(inner_field=2)])) -# field \{ +# field { # inner_field: 1 -# \} -# field \{ +# } +# field { # inner_field: 2 -# \} +# } proto.encode_text(struct(field=struct(inner_field=struct(inner_inner_field='text')))) -# field \{ -# inner_field \{ +# field { +# inner_field { # inner_inner_field: "text" -# \} -# \} +# } +# } -proto.encode_text(struct(foo=\{4: 3, 2: 1\})) -# foo: \{ +proto.encode_text(struct(foo={4: 3, 2: 1})) +# foo: { # key: 4 # value: 3 -# \} -# foo: \{ +# } +# foo: { # key: 2 # value: 1 -# \} +# } + ``` ### Parameters -| Parameter | Description | -| --- | --- | -| `x` | structure; or NativeInfo; required | \ No newline at end of file +ParameterDescription`x` + structure; or NativeInfo; + required diff --git a/rules/lib/toplevel/testing.mdx b/rules/lib/toplevel/testing.mdx index df36391..b3daf55 100644 --- a/rules/lib/toplevel/testing.mdx +++ b/rules/lib/toplevel/testing.mdx @@ -3,34 +3,53 @@ title: 'testing' --- + Helper methods for Starlark to access testing infrastructure. ## Members -* [analysis\_test](#analysis_test) -* [ExecutionInfo](#ExecutionInfo) -* [TestEnvironment](#TestEnvironment) +- [analysis\_test](#analysis_test) +- [ExecutionInfo](#ExecutionInfo) +- [TestEnvironment](#TestEnvironment) ## analysis\_test ``` -None testing.analysis_test(name, implementation, attrs=\{\}, fragments=[], toolchains=[], attr_values=\{\}) +None testing.analysis_test(name, implementation, attrs={}, fragments=[], toolchains=[], attr_values={}) ``` -Creates a new analysis test target. + Creates a new analysis test target. The number of transitive dependencies of the test are limited. The limit is controlled by `--analysis_testing_deps_limit` flag. + ### Parameters -| Parameter | Description | -| --- | --- | -| `name` | [string](../core/string.mdx); required Name of the target. It should be a Starlark identifier, matching pattern '[A-Za-z\_][A-Za-z0-9\_]\*'. | -| `implementation` | [function](../core/function.mdx); required The Starlark function implementing this analysis test. It must have exactly one parameter: [ctx](../builtins/ctx.mdx). The function is called during the analysis phase. It can access the attributes declared by `attrs` and populated via `attr_values`. The implementation function may not register actions. Instead, it must register a pass/fail result via providing [AnalysisTestResultInfo](../providers/AnalysisTestResultInfo.mdx). | -| `attrs` | [dict](../core/dict.mdx); default is `\{\}` Dictionary declaring the attributes. See the [rule](../globals/bzl.html#rule) call. Attributes are allowed to use configuration transitions defined using [analysis\_test\_transition](../globals/bzl.html#analysis_test_transition). | -| `fragments` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` List of configuration fragments that are available to the implementation of the analysis test. | -| `toolchains` | [sequence](../core/list.mdx); default is `[]` The set of toolchains the test requires. See the [rule](../globals/bzl.html#rule) call. | -| `attr_values` | [dict](../core/dict.mdx) of [string](../core/string.mdx)s; default is `\{\}` Dictionary of attribute values to pass to the implementation. | +ParameterDescription`name`[string](../core/string.html); + required + + Name of the target. It should be a Starlark identifier, matching pattern '\[A-Za-z\_\]\[A-Za-z0-9\_\]\*'. + `implementation`[function](../core/function.html); + required + + The Starlark function implementing this analysis test. It must have exactly one parameter: [ctx](../builtins/ctx.html). The function is called during the analysis phase. It can access the attributes declared by `attrs` and populated via `attr_values`. The implementation function may not register actions. Instead, it must register a pass/fail result via providing [AnalysisTestResultInfo](../providers/AnalysisTestResultInfo.html). + `attrs`[dict](../core/dict.html); + default is `{}` + + Dictionary declaring the attributes. See the [rule](../globals/bzl.html#rule) call. Attributes are allowed to use configuration transitions defined using [analysis\_test\_transition](../globals/bzl.html#analysis_test_transition). + `fragments`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + List of configuration fragments that are available to the implementation of the analysis test. + `toolchains`[sequence](../core/list.html); + default is `[]` + + The set of toolchains the test requires. See the [rule](../globals/bzl.html#rule) call. + `attr_values`[dict](../core/dict.html) of [string](../core/string.html) s; + default is `{}` + + Dictionary of attribute values to pass to the implementation. + ## ExecutionInfo @@ -38,7 +57,9 @@ The number of transitive dependencies of the test are limited. The limit is cont ExecutionInfo testing.ExecutionInfo ``` -[testing.ExecutionInfo](../providers/ExecutionInfo.mdx) provider key/constructor + [testing.ExecutionInfo](../providers/ExecutionInfo.html) provider key/constructor + + ## TestEnvironment @@ -46,11 +67,16 @@ ExecutionInfo testing.ExecutionInfo RunEnvironmentInfo testing.TestEnvironment(environment, inherited_environment=[]) ``` -**Deprecated: Use RunEnvironmentInfo instead.** Creates a new test environment provider. Use this provider to specify extra environment variables to be made available during test execution. + **Deprecated: Use RunEnvironmentInfo instead.** Creates a new test environment provider. Use this provider to specify extra environment variables to be made available during test execution. + ### Parameters -| Parameter | Description | -| --- | --- | -| `environment` | [dict](../core/dict.mdx); required A map of string keys and values that represent environment variables and their values. These will be made available during the test execution. | -| `inherited_environment` | [sequence](../core/list.mdx) of [string](../core/string.mdx)s; default is `[]` A sequence of names of environment variables. These variables are made available during the test execution with their current value taken from the shell environment. If a variable is contained in both `environment` and `inherited_environment`, the value inherited from the shell environment will take precedence if set. | \ No newline at end of file +ParameterDescription`environment`[dict](../core/dict.html); + required + + A map of string keys and values that represent environment variables and their values. These will be made available during the test execution. + `inherited_environment`[sequence](../core/list.html) of [string](../core/string.html) s; + default is `[]` + + A sequence of names of environment variables. These variables are made available during the test execution with their current value taken from the shell environment. If a variable is contained in both `environment` and `inherited_environment`, the value inherited from the shell environment will take precedence if set. diff --git a/rules/macro-tutorial.mdx b/rules/macro-tutorial.mdx deleted file mode 100644 index 2b3d8e4..0000000 --- a/rules/macro-tutorial.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: 'Creating a Symbolic Macro' ---- - - - -IMPORTANT: This tutorial is for [*symbolic macros*](/extending/macros) – the new -macro system introduced in Bazel 8. If you need to support older Bazel versions, -you will want to write a [legacy macro](/extending/legacy-macros) instead; take -a look at [Creating a Legacy Macro](legacy-macro-tutorial). - -Imagine that you need to run a tool as part of your build. For example, you -may want to generate or preprocess a source file, or compress a binary. In this -tutorial, you are going to create a symbolic macro that resizes an image. - -Macros are suitable for simple tasks. If you want to do anything more -complicated, for example add support for a new programming language, consider -creating a [rule](/extending/rules). Rules give you more control and flexibility. - -The easiest way to create a macro that resizes an image is to use a `genrule`: - -```starlark -genrule( - name = "logo_miniature", - srcs = ["logo.png"], - outs = ["small_logo.png"], - cmd = "convert $< -resize 100x100 $@", -) - -cc_binary( - name = "my_app", - srcs = ["my_app.cc"], - data = [":logo_miniature"], -) -``` - -If you need to resize more images, you may want to reuse the code. To do that, -define an *implementation function* and a *macro declaration* in a separate -`.bzl` file, and call the file `miniature.bzl`: - -```starlark -# Implementation function -def _miniature_impl(name, visibility, src, size, **kwargs): - native.genrule( - name = name, - visibility = visibility, - srcs = [src], - outs = [name + "_small_" + src.name], - cmd = "convert $< -resize " + size + " $@", - **kwargs, - ) - -# Macro declaration -miniature = macro( - doc = """Create a miniature of the src image. - - The generated file name will be prefixed with `name + "_small_"`. - """, - implementation = _miniature_impl, - # Inherit most of genrule's attributes (such as tags and testonly) - inherit_attrs = native.genrule, - attrs = { - "src": attr.label( - doc = "Image file", - allow_single_file = True, - # Non-configurable because our genrule's output filename is - # suffixed with src's name. (We want to suffix the output file with - # srcs's name because some tools that operate on image files expect - # the files to have the right file extension.) - configurable = False, - ), - "size": attr.string( - doc = "Output size in WxH format", - default = "100x100", - ), - # Do not allow callers of miniature() to set srcs, cmd, or outs - - # _miniature_impl overrides their values when calling native.genrule() - "srcs": None, - "cmd": None, - "outs": None, - }, -) -``` - -A few remarks: - - * Symbolic macro implementation functions must have `name` and `visibility` - parameters. They should used for the macro's main target. - - * To document the behavior of a symbolic macro, use `doc` parameters for - `macro()` and its attributes. - - * To call a `genrule`, or any other native rule, use `native.`. - - * Use `**kwargs` to forward the extra inherited arguments to the underlying - `genrule` (it works just like in - [Python](https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments)). - This is useful so that a user can set standard attributes like `tags` or - `testonly`. - -Now, use the macro from the `BUILD` file: - -```starlark -load("//path/to:miniature.bzl", "miniature") - -miniature( - name = "logo_miniature", - src = "image.png", -) - -cc_binary( - name = "my_app", - srcs = ["my_app.cc"], - data = [":logo_miniature"], -) -``` diff --git a/rules/performance.mdx b/rules/performance.mdx deleted file mode 100644 index dff0ccc..0000000 --- a/rules/performance.mdx +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: 'Optimizing Performance' ---- - - - -When writing rules, the most common performance pitfall is to traverse or copy -data that is accumulated from dependencies. When aggregated over the whole -build, these operations can easily take O(N^2) time or space. To avoid this, it -is crucial to understand how to use depsets effectively. - -This can be hard to get right, so Bazel also provides a memory profiler that -assists you in finding spots where you might have made a mistake. Be warned: -The cost of writing an inefficient rule may not be evident until it is in -widespread use. - -## Use depsets - -Whenever you are rolling up information from rule dependencies you should use -[depsets](lib/depset). Only use plain lists or dicts to publish information -local to the current rule. - -A depset represents information as a nested graph which enables sharing. - -Consider the following graph: - -``` -C -> B -> A -D ---^ -``` - -Each node publishes a single string. With depsets the data looks like this: - -``` -a = depset(direct=['a']) -b = depset(direct=['b'], transitive=[a]) -c = depset(direct=['c'], transitive=[b]) -d = depset(direct=['d'], transitive=[b]) -``` - -Note that each item is only mentioned once. With lists you would get this: - -``` -a = ['a'] -b = ['b', 'a'] -c = ['c', 'b', 'a'] -d = ['d', 'b', 'a'] -``` - -Note that in this case `'a'` is mentioned four times! With larger graphs this -problem will only get worse. - -Here is an example of a rule implementation that uses depsets correctly to -publish transitive information. Note that it is OK to publish rule-local -information using lists if you want since this is not O(N^2). - -``` -MyProvider = provider() - -def _impl(ctx): - my_things = ctx.attr.things - all_things = depset( - direct=my_things, - transitive=[dep[MyProvider].all_things for dep in ctx.attr.deps] - ) - ... - return [MyProvider( - my_things=my_things, # OK, a flat list of rule-local things only - all_things=all_things, # OK, a depset containing dependencies - )] -``` - -See the [depset overview](/extending/depsets) page for more information. - -### Avoid calling `depset.to_list()` - -You can coerce a depset to a flat list using -[`to_list()`](lib/depset#to_list), but doing so usually results in O(N^2) -cost. If at all possible, avoid any flattening of depsets except for debugging -purposes. - -A common misconception is that you can freely flatten depsets if you only do it -at top-level targets, such as an `<xx>_binary` rule, since then the cost is not -accumulated over each level of the build graph. But this is *still* O(N^2) when -you build a set of targets with overlapping dependencies. This happens when -building your tests `//foo/tests/...`, or when importing an IDE project. - -### Reduce the number of calls to `depset` - -Calling `depset` inside a loop is often a mistake. It can lead to depsets with -very deep nesting, which perform poorly. For example: - -```python -x = depset() -for i in inputs: - # Do not do that. - x = depset(transitive = [x, i.deps]) -``` - -This code can be replaced easily. First, collect the transitive depsets and -merge them all at once: - -```python -transitive = [] - -for i in inputs: - transitive.append(i.deps) - -x = depset(transitive = transitive) -``` - -This can sometimes be reduced using a list comprehension: - -```python -x = depset(transitive = [i.deps for i in inputs]) -``` - -## Use ctx.actions.args() for command lines - -When building command lines you should use [ctx.actions.args()](lib/Args). -This defers expansion of any depsets to the execution phase. - -Apart from being strictly faster, this will reduce the memory consumption of -your rules -- sometimes by 90% or more. - -Here are some tricks: - -* Pass depsets and lists directly as arguments, instead of flattening them -yourself. They will get expanded by `ctx.actions.args()` for you. -If you need any transformations on the depset contents, look at -[ctx.actions.args#add](lib/Args#add) to see if anything fits the bill. - -* Are you passing `File#path` as arguments? No need. Any -[File](lib/File) is automatically turned into its -[path](lib/File#path), deferred to expansion time. - -* Avoid constructing strings by concatenating them together. -The best string argument is a constant as its memory will be shared between -all instances of your rule. - -* If the args are too long for the command line an `ctx.actions.args()` object -can be conditionally or unconditionally written to a param file using -[`ctx.actions.args#use_param_file`](lib/Args#use_param_file). This is -done behind the scenes when the action is executed. If you need to explicitly -control the params file you can write it manually using -[`ctx.actions.write`](lib/actions#write). - -Example: - -``` -def _impl(ctx): - ... - args = ctx.actions.args() - file = ctx.declare_file(...) - files = depset(...) - - # Bad, constructs a full string "--foo=<file path>" for each rule instance - args.add("--foo=" + file.path) - - # Good, shares "--foo" among all rule instances, and defers file.path to later - # It will however pass ["--foo", <file path>] to the action command line, - # instead of ["--foo=<file_path>"] - args.add("--foo", file) - - # Use format if you prefer ["--foo=<file path>"] to ["--foo", <file path>] - args.add(file, format="--foo=%s") - - # Bad, makes a giant string of a whole depset - args.add(" ".join(["-I%s" % file.short_path for file in files.to_list()]) - - # Good, only stores a reference to the depset - args.add_all(files, format_each="-I%s", map_each=_to_short_path) - -# Function passed to map_each above -def _to_short_path(f): - return f.short_path -``` - -## Transitive action inputs should be depsets - -When building an action using [ctx.actions.run](lib/actions?#run), do not -forget that the `inputs` field accepts a depset. Use this whenever inputs are -collected from dependencies transitively. - -``` -inputs = depset(...) -ctx.actions.run( - inputs = inputs, # Do *not* turn inputs into a list - ... -) -``` - -## Hanging - -If Bazel appears to be hung, you can hit <kbd>Ctrl-\</kbd> or send -Bazel a `SIGQUIT` signal (`kill -3 $(bazel info server_pid)`) to get a thread -dump in the file `$(bazel info output_base)/server/jvm.out`. - -Since you may not be able to run `bazel info` if bazel is hung, the -`output_base` directory is usually the parent of the `bazel-<workspace>` -symlink in your workspace directory. - -## Performance profiling - -The [JSON trace profile](/advanced/performance/json-trace-profile) can be very -useful to quickly understand what Bazel spent time on during the invocation. - -The [`--experimental_command_profile`](https://bazel.build/reference/command-line-reference#flag--experimental_command_profile) -flag may be used to capture Java Flight Recorder profiles of various kinds -(cpu time, wall time, memory allocations and lock contention). - -The [`--starlark_cpu_profile`](https://bazel.build/reference/command-line-reference#flag--starlark_cpu_profile) -flag may be used to write a pprof profile of CPU usage by all Starlark threads. - -## Memory profiling - -Bazel comes with a built-in memory profiler that can help you check your rule’s -memory use. If there is a problem you can dump the heap to find the -exact line of code that is causing the problem. - -### Enabling memory tracking - -You must pass these two startup flags to *every* Bazel invocation: - - ``` - STARTUP_FLAGS=\ - --host_jvm_args=-javaagent:<path to java-allocation-instrumenter-3.3.4.jar> \ - --host_jvm_args=-DRULE_MEMORY_TRACKER=1 - ``` -Note: You can download the allocation instrumenter jar file from [Maven Central -Repository][allocation-instrumenter-link]. - -[allocation-instrumenter-link]: https://repo1.maven.org/maven2/com/google/code/java-allocation-instrumenter/java-allocation-instrumenter/3.3.4 - -These start the server in memory tracking mode. If you forget these for even -one Bazel invocation the server will restart and you will have to start over. - -### Using the Memory Tracker - -As an example, look at the target `foo` and see what it does. To only -run the analysis and not run the build execution phase, add the -`--nobuild` flag. - -``` -$ bazel $(STARTUP_FLAGS) build --nobuild //foo:foo -``` - -Next, see how much memory the whole Bazel instance consumes: - -``` -$ bazel $(STARTUP_FLAGS) info used-heap-size-after-gc -> 2594MB -``` - -Break it down by rule class by using `bazel dump --rules`: - -``` -$ bazel $(STARTUP_FLAGS) dump --rules -> - -RULE COUNT ACTIONS BYTES EACH -genrule 33,762 33,801 291,538,824 8,635 -config_setting 25,374 0 24,897,336 981 -filegroup 25,369 25,369 97,496,272 3,843 -cc_library 5,372 73,235 182,214,456 33,919 -proto_library 4,140 110,409 186,776,864 45,115 -android_library 2,621 36,921 218,504,848 83,366 -java_library 2,371 12,459 38,841,000 16,381 -_gen_source 719 2,157 9,195,312 12,789 -_check_proto_library_deps 719 668 1,835,288 2,552 -... (more output) -``` - -Look at where the memory is going by producing a `pprof` file -using `bazel dump --skylark_memory`: - -``` -$ bazel $(STARTUP_FLAGS) dump --skylark_memory=$HOME/prof.gz -> Dumping Starlark heap to: /usr/local/google/home/$USER/prof.gz -``` - -Use the `pprof` tool to investigate the heap. A good starting point is -getting a flame graph by using `pprof -flame $HOME/prof.gz`. - -Get `pprof` from [https://github.com/google/pprof](https://github.com/google/pprof). - -Get a text dump of the hottest call sites annotated with lines: - -``` -$ pprof -text -lines $HOME/prof.gz -> - flat flat% sum% cum cum% - 146.11MB 19.64% 19.64% 146.11MB 19.64% android_library <native>:-1 - 113.02MB 15.19% 34.83% 113.02MB 15.19% genrule <native>:-1 - 74.11MB 9.96% 44.80% 74.11MB 9.96% glob <native>:-1 - 55.98MB 7.53% 52.32% 55.98MB 7.53% filegroup <native>:-1 - 53.44MB 7.18% 59.51% 53.44MB 7.18% sh_test <native>:-1 - 26.55MB 3.57% 63.07% 26.55MB 3.57% _generate_foo_files /foo/tc/tc.bzl:491 - 26.01MB 3.50% 66.57% 26.01MB 3.50% _build_foo_impl /foo/build_test.bzl:78 - 22.01MB 2.96% 69.53% 22.01MB 2.96% _build_foo_impl /foo/build_test.bzl:73 - ... (more output) -``` diff --git a/rules/rules-tutorial.mdx b/rules/rules-tutorial.mdx deleted file mode 100644 index 4c6698e..0000000 --- a/rules/rules-tutorial.mdx +++ /dev/null @@ -1,367 +0,0 @@ ---- -title: 'Rules Tutorial' ---- - - - - -[Starlark](https://github.com/bazelbuild/starlark) is a Python-like -configuration language originally developed for use in Bazel and since adopted -by other tools. Bazel's `BUILD` and `.bzl` files are written in a dialect of -Starlark properly known as the "Build Language", though it is often simply -referred to as "Starlark", especially when emphasizing that a feature is -expressed in the Build Language as opposed to being a built-in or "native" part -of Bazel. Bazel augments the core language with numerous build-related functions -such as `glob`, `genrule`, `java_binary`, and so on. - -See the -[Bazel](/start/) and [Starlark](/extending/concepts) documentation for -more details, and the -[Rules SIG template](https://github.com/bazel-contrib/rules-template) as a -starting point for new rulesets. - -## The empty rule - -To create your first rule, create the file `foo.bzl`: - -```python -def _foo_binary_impl(ctx): - pass - -foo_binary = rule( - implementation = _foo_binary_impl, -) -``` - -When you call the [`rule`](lib/globals#rule) function, you -must define a callback function. The logic will go there, but you -can leave the function empty for now. The [`ctx`](lib/ctx) argument -provides information about the target. - -You can load the rule and use it from a `BUILD` file. - -Create a `BUILD` file in the same directory: - -```python -load(":foo.bzl", "foo_binary") - -foo_binary(name = "bin") -``` - -Now, the target can be built: - -``` -$ bazel build bin -INFO: Analyzed target //:bin (2 packages loaded, 17 targets configured). -INFO: Found 1 target... -Target //:bin up-to-date (nothing to build) -``` - -Even though the rule does nothing, it already behaves like other rules: it has a -mandatory name, it supports common attributes like `visibility`, `testonly`, and -`tags`. - -## Evaluation model - -Before going further, it's important to understand how the code is evaluated. - -Update `foo.bzl` with some print statements: - -```python -def _foo_binary_impl(ctx): - print("analyzing", ctx.label) - -foo_binary = rule( - implementation = _foo_binary_impl, -) - -print("bzl file evaluation") -``` - -and BUILD: - -```python -load(":foo.bzl", "foo_binary") - -print("BUILD file") -foo_binary(name = "bin1") -foo_binary(name = "bin2") -``` - -[`ctx.label`](lib/ctx#label) -corresponds to the label of the target being analyzed. The `ctx` object has -many useful fields and methods; you can find an exhaustive list in the -[API reference](lib/ctx). - -Query the code: - -``` -$ bazel query :all -DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation -DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file -//:bin2 -//:bin1 -``` - -Make a few observations: - -* "bzl file evaluation" is printed first. Before evaluating the `BUILD` file, - Bazel evaluates all the files it loads. If multiple `BUILD` files are loading - foo.bzl, you would see only one occurrence of "bzl file evaluation" because - Bazel caches the result of the evaluation. -* The callback function `_foo_binary_impl` is not called. Bazel query loads - `BUILD` files, but doesn't analyze targets. - -To analyze the targets, use the [`cquery`](/query/cquery) ("configured -query") or the `build` command: - -``` -$ bazel build :all -DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin1 -DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin2 -INFO: Analyzed 2 targets (0 packages loaded, 0 targets configured). -INFO: Found 2 targets... -``` - -As you can see, `_foo_binary_impl` is now called twice - once for each target. - -Notice that neither "bzl file evaluation" nor "BUILD file" are printed again, -because the evaluation of `foo.bzl` is cached after the call to `bazel query`. -Bazel only emits `print` statements when they are actually executed. - -## Creating a file - -To make your rule more useful, update it to generate a file. First, declare the -file and give it a name. In this example, create a file with the same name as -the target: - -```python -ctx.actions.declare_file(ctx.label.name) -``` - -If you run `bazel build :all` now, you will get an error: - -``` -The following files have no generating action: -bin2 -``` - -Whenever you declare a file, you have to tell Bazel how to generate it by -creating an action. Use [`ctx.actions.write`](lib/actions#write), -to create a file with the given content. - -```python -def _foo_binary_impl(ctx): - out = ctx.actions.declare_file(ctx.label.name) - ctx.actions.write( - output = out, - content = "Hello\n", - ) -``` - -The code is valid, but it won't do anything: - -``` -$ bazel build bin1 -Target //:bin1 up-to-date (nothing to build) -``` - -The `ctx.actions.write` function registered an action, which taught Bazel -how to generate the file. But Bazel won't create the file until it is -actually requested. So the last thing to do is tell Bazel that the file -is an output of the rule, and not a temporary file used within the rule -implementation. - -```python -def _foo_binary_impl(ctx): - out = ctx.actions.declare_file(ctx.label.name) - ctx.actions.write( - output = out, - content = "Hello!\n", - ) - return [DefaultInfo(files = depset([out]))] -``` - -Look at the `DefaultInfo` and `depset` functions later. For now, -assume that the last line is the way to choose the outputs of a rule. - -Now, run Bazel: - -``` -$ bazel build bin1 -INFO: Found 1 target... -Target //:bin1 up-to-date: - bazel-bin/bin1 - -$ cat bazel-bin/bin1 -Hello! -``` - -You have successfully generated a file! - -## Attributes - -To make the rule more useful, add new attributes using -[the `attr` module](lib/attr) and update the rule definition. - -Add a string attribute called `username`: - -```python -foo_binary = rule( - implementation = _foo_binary_impl, - attrs = { - "username": attr.string(), - }, -) -``` - -Next, set it in the `BUILD` file: - -```python -foo_binary( - name = "bin", - username = "Alice", -) -``` - -To access the value in the callback function, use `ctx.attr.username`. For -example: - -```python -def _foo_binary_impl(ctx): - out = ctx.actions.declare_file(ctx.label.name) - ctx.actions.write( - output = out, - content = "Hello {}!\n".format(ctx.attr.username), - ) - return [DefaultInfo(files = depset([out]))] -``` - -Note that you can make the attribute mandatory or set a default value. Look at -the documentation of [`attr.string`](lib/attr#string). -You may also use other types of attributes, such as [boolean](lib/attr#bool) -or [list of integers](lib/attr#int_list). - -## Dependencies - -Dependency attributes, such as [`attr.label`](lib/attr#label) -and [`attr.label_list`](lib/attr#label_list), -declare a dependency from the target that owns the attribute to the target whose -label appears in the attribute's value. This kind of attribute forms the basis -of the target graph. - -In the `BUILD` file, the target label appears as a string object, such as -`//pkg:name`. In the implementation function, the target will be accessible as a -[`Target`](lib/Target) object. For example, view the files returned -by the target using [`Target.files`](lib/Target#modules.Target.files). - -### Multiple files - -By default, only targets created by rules may appear as dependencies (such as a -`foo_library()` target). If you want the attribute to accept targets that are -input files (such as source files in the repository), you can do it with -`allow_files` and specify the list of accepted file extensions (or `True` to -allow any file extension): - -```python -"srcs": attr.label_list(allow_files = [".java"]), -``` - -The list of files can be accessed with `ctx.files.<attribute name>`. For -example, the list of files in the `srcs` attribute can be accessed through - -```python -ctx.files.srcs -``` - -### Single file - -If you need only one file, use `allow_single_file`: - -```python -"src": attr.label(allow_single_file = [".java"]) -``` - -This file is then accessible under `ctx.file.<attribute name>`: - -```python -ctx.file.src -``` - -## Create a file with a template - -You can create a rule that generates a .cc file based on a template. Also, you -can use `ctx.actions.write` to output a string constructed in the rule -implementation function, but this has two problems. First, as the template gets -bigger, it becomes more memory efficient to put it in a separate file and avoid -constructing large strings during the analysis phase. Second, using a separate -file is more convenient for the user. Instead, use -[`ctx.actions.expand_template`](lib/actions#expand_template), -which performs substitutions on a template file. - -Create a `template` attribute to declare a dependency on the template -file: - -```python -def _hello_world_impl(ctx): - out = ctx.actions.declare_file(ctx.label.name + ".cc") - ctx.actions.expand_template( - output = out, - template = ctx.file.template, - substitutions = {"{NAME}": ctx.attr.username}, - ) - return [DefaultInfo(files = depset([out]))] - -hello_world = rule( - implementation = _hello_world_impl, - attrs = { - "username": attr.string(default = "unknown person"), - "template": attr.label( - allow_single_file = [".cc.tpl"], - mandatory = True, - ), - }, -) -``` - -Users can use the rule like this: - -```python -hello_world( - name = "hello", - username = "Alice", - template = "file.cc.tpl", -) - -cc_binary( - name = "hello_bin", - srcs = [":hello"], -) -``` - -If you don't want to expose the template to the end-user and always use the -same one, you can set a default value and make the attribute private: - -```python - "_template": attr.label( - allow_single_file = True, - default = "file.cc.tpl", - ), -``` - -Attributes that start with an underscore are private and cannot be set in a -`BUILD` file. The template is now an _implicit dependency_: Every `hello_world` -target has a dependency on this file. Don't forget to make this file visible -to other packages by updating the `BUILD` file and using -[`exports_files`](/reference/be/functions#exports_files): - -```python -exports_files(["file.cc.tpl"]) -``` - -## Going further - -* Take a look at the [reference documentation for rules](/extending/rules#contents). -* Get familiar with [depsets](/extending/depsets). -* Check out the [examples repository](https://github.com/bazelbuild/examples/tree/master/rules) - which includes additional examples of rules. diff --git a/rules/testing.mdx b/rules/testing.mdx deleted file mode 100644 index 2996e08..0000000 --- a/rules/testing.mdx +++ /dev/null @@ -1,474 +0,0 @@ ---- -title: 'Testing' ---- - - - -There are several different approaches to testing Starlark code in Bazel. This -page gathers the current best practices and frameworks by use case. - -## Testing rules - -[Skylib](https://github.com/bazelbuild/bazel-skylib) has a test framework called -[`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/lib/unittest.bzl) -for checking the analysis-time behavior of rules, such as their actions and -providers. Such tests are called "analysis tests" and are currently the best -option for testing the inner workings of rules. - -Some caveats: - -* Test assertions occur within the build, not a separate test runner process. - Targets that are created by the test must be named such that they do not - collide with targets from other tests or from the build. An error that - occurs during the test is seen by Bazel as a build breakage rather than a - test failure. - -* It requires a fair amount of boilerplate to set up the rules under test and - the rules containing test assertions. This boilerplate may seem daunting at - first. It helps to [keep in mind](/extending/concepts#evaluation-model) that macros - are evaluated and targets generated during the loading phase, while rule - implementation functions don't run until later, during the analysis phase. - -* Analysis tests are intended to be fairly small and lightweight. Certain - features of the analysis testing framework are restricted to verifying - targets with a maximum number of transitive dependencies (currently 500). - This is due to performance implications of using these features with larger - tests. - -The basic principle is to define a testing rule that depends on the -rule-under-test. This gives the testing rule access to the rule-under-test's -providers. - -The testing rule's implementation function carries out assertions. If there are -any failures, these are not raised immediately by calling `fail()` (which would -trigger an analysis-time build error), but rather by storing the errors in a -generated script that fails at test execution time. - -See below for a minimal toy example, followed by an example that checks actions. - -### Minimal example - -`//mypkg/myrules.bzl`: - -```python -MyInfo = provider(fields = { - "val": "string value", - "out": "output File", -}) - -def _myrule_impl(ctx): - """Rule that just generates a file and returns a provider.""" - out = ctx.actions.declare_file(ctx.label.name + ".out") - ctx.actions.write(out, "abc") - return [MyInfo(val="some value", out=out)] - -myrule = rule( - implementation = _myrule_impl, -) -``` - -`//mypkg/myrules_test.bzl`: - - -```python -load("@bazel_skylib//lib:unittest.bzl", "asserts", "analysistest") -load(":myrules.bzl", "myrule", "MyInfo") - -# ==== Check the provider contents ==== - -def _provider_contents_test_impl(ctx): - env = analysistest.begin(ctx) - - target_under_test = analysistest.target_under_test(env) - # If preferred, could pass these values as "expected" and "actual" keyword - # arguments. - asserts.equals(env, "some value", target_under_test[MyInfo].val) - - # If you forget to return end(), you will get an error about an analysis - # test needing to return an instance of AnalysisTestResultInfo. - return analysistest.end(env) - -# Create the testing rule to wrap the test logic. This must be bound to a global -# variable, not called in a macro's body, since macros get evaluated at loading -# time but the rule gets evaluated later, at analysis time. Since this is a test -# rule, its name must end with "_test". -provider_contents_test = analysistest.make(_provider_contents_test_impl) - -# Macro to setup the test. -def _test_provider_contents(): - # Rule under test. Be sure to tag 'manual', as this target should not be - # built using `:all` except as a dependency of the test. - myrule(name = "provider_contents_subject", tags = ["manual"]) - # Testing rule. - provider_contents_test(name = "provider_contents_test", - target_under_test = ":provider_contents_subject") - # Note the target_under_test attribute is how the test rule depends on - # the real rule target. - -# Entry point from the BUILD file; macro for running each test case's macro and -# declaring a test suite that wraps them together. -def myrules_test_suite(name): - # Call all test functions and wrap their targets in a suite. - _test_provider_contents() - # ... - - native.test_suite( - name = name, - tests = [ - ":provider_contents_test", - # ... - ], - ) -``` - -`//mypkg/BUILD`: - -```python -load(":myrules.bzl", "myrule") -load(":myrules_test.bzl", "myrules_test_suite") - -# Production use of the rule. -myrule( - name = "mytarget", -) - -# Call a macro that defines targets that perform the tests at analysis time, -# and that can be executed with "bazel test" to return the result. -myrules_test_suite(name = "myrules_test") -``` - -The test can be run with `bazel test //mypkg:myrules_test`. - -Aside from the initial `load()` statements, there are two main parts to the -file: - -* The tests themselves, each of which consists of 1) an analysis-time - implementation function for the testing rule, 2) a declaration of the - testing rule via `analysistest.make()`, and 3) a loading-time function - (macro) for declaring the rule-under-test (and its dependencies) and testing - rule. If the assertions do not change between test cases, 1) and 2) may be - shared by multiple test cases. - -* The test suite function, which calls the loading-time functions for each - test, and declares a `test_suite` target bundling all tests together. - -For consistency, follow the recommended naming convention: Let `foo` stand for -the part of the test name that describes what the test is checking -(`provider_contents` in the above example). For example, a JUnit test method -would be named `testFoo`. - -Then: - -* the macro which generates the test and target under test should should be - named `_test_foo` (`_test_provider_contents`) - -* its test rule type should be named `foo_test` (`provider_contents_test`) - -* the label of the target of this rule type should be `foo_test` - (`provider_contents_test`) - -* the implementation function for the testing rule should be named - `_foo_test_impl` (`_provider_contents_test_impl`) - -* the labels of the targets of the rules under test and their dependencies - should be prefixed with `foo_` (`provider_contents_`) - -Note that the labels of all targets can conflict with other labels in the same -BUILD package, so it's helpful to use a unique name for the test. - -### Failure testing - -It may be useful to verify that a rule fails given certain inputs or in certain -state. This can be done using the analysis test framework: - -The test rule created with `analysistest.make` should specify `expect_failure`: - -```python -failure_testing_test = analysistest.make( - _failure_testing_test_impl, - expect_failure = True, -) -``` - -The test rule implementation should make assertions on the nature of the failure -that took place (specifically, the failure message): - -```python -def _failure_testing_test_impl(ctx): - env = analysistest.begin(ctx) - asserts.expect_failure(env, "This rule should never work") - return analysistest.end(env) -``` - -Also make sure that your target under test is specifically tagged 'manual'. -Without this, building all targets in your package using `:all` will result in a -build of the intentionally-failing target and will exhibit a build failure. With -'manual', your target under test will build only if explicitly specified, or as -a dependency of a non-manual target (such as your test rule): - -```python -def _test_failure(): - myrule(name = "this_should_fail", tags = ["manual"]) - - failure_testing_test(name = "failure_testing_test", - target_under_test = ":this_should_fail") - -# Then call _test_failure() in the macro which generates the test suite and add -# ":failure_testing_test" to the suite's test targets. -``` - -### Verifying registered actions - -You may want to write tests which make assertions about the actions that your -rule registers, for example, using `ctx.actions.run()`. This can be done in your -analysis test rule implementation function. An example: - -```python -def _inspect_actions_test_impl(ctx): - env = analysistest.begin(ctx) - - target_under_test = analysistest.target_under_test(env) - actions = analysistest.target_actions(env) - asserts.equals(env, 1, len(actions)) - action_output = actions[0].outputs.to_list()[0] - asserts.equals( - env, target_under_test.label.name + ".out", action_output.basename) - return analysistest.end(env) -``` - -Note that `analysistest.target_actions(env)` returns a list of -[`Action`](lib/Action) objects which represent actions registered by the -target under test. - -### Verifying rule behavior under different flags - -You may want to verify your real rule behaves a certain way given certain build -flags. For example, your rule may behave differently if a user specifies: - -```shell -bazel build //mypkg:real_target -c opt -``` - -versus - -```shell -bazel build //mypkg:real_target -c dbg -``` - -At first glance, this could be done by testing the target under test using the -desired build flags: - -```shell -bazel test //mypkg:myrules_test -c opt -``` - -But then it becomes impossible for your test suite to simultaneously contain a -test which verifies the rule behavior under `-c opt` and another test which -verifies the rule behavior under `-c dbg`. Both tests would not be able to run -in the same build! - -This can be solved by specifying the desired build flags when defining the test -rule: - -```python -myrule_c_opt_test = analysistest.make( - _myrule_c_opt_test_impl, - config_settings = { - "//command_line_option:compilation_mode": "opt", - }, -) -``` - -Normally, a target under test is analyzed given the current build flags. -Specifying `config_settings` overrides the values of the specified command line -options. (Any unspecified options will retain their values from the actual -command line). - -In the specified `config_settings` dictionary, command line flags must be -prefixed with a special placeholder value `//command_line_option:`, as is shown -above. - - -## Validating artifacts - -The main ways to check that your generated files are correct are: - -* You can write a test script in shell, Python, or another language, and - create a target of the appropriate `*_test` rule type. - -* You can use a specialized rule for the kind of test you want to perform. - -### Using a test target - -The most straightforward way to validate an artifact is to write a script and -add a `*_test` target to your BUILD file. The specific artifacts you want to -check should be data dependencies of this target. If your validation logic is -reusable for multiple tests, it should be a script that takes command line -arguments that are controlled by the test target's `args` attribute. Here's an -example that validates that the output of `myrule` from above is `"abc"`. - -`//mypkg/myrule_validator.sh`: - -```shell -if [ "$(cat $1)" = "abc" ]; then - echo "Passed" - exit 0 -else - echo "Failed" - exit 1 -fi -``` - -`//mypkg/BUILD`: - -```python -... - -myrule( - name = "mytarget", -) - -... - -# Needed for each target whose artifacts are to be checked. -sh_test( - name = "validate_mytarget", - srcs = [":myrule_validator.sh"], - args = ["$(location :mytarget.out)"], - data = [":mytarget.out"], -) -``` - -### Using a custom rule - -A more complicated alternative is to write the shell script as a template that -gets instantiated by a new rule. This involves more indirection and Starlark -logic, but leads to cleaner BUILD files. As a side-benefit, any argument -preprocessing can be done in Starlark instead of the script, and the script is -slightly more self-documenting since it uses symbolic placeholders (for -substitutions) instead of numeric ones (for arguments). - -`//mypkg/myrule_validator.sh.template`: - -```shell -if [ "$(cat %TARGET%)" = "abc" ]; then - echo "Passed" - exit 0 -else - echo "Failed" - exit 1 -fi -``` - -`//mypkg/myrule_validation.bzl`: - -```python -def _myrule_validation_test_impl(ctx): - """Rule for instantiating myrule_validator.sh.template for a given target.""" - exe = ctx.outputs.executable - target = ctx.file.target - ctx.actions.expand_template(output = exe, - template = ctx.file._script, - is_executable = True, - substitutions = { - "%TARGET%": target.short_path, - }) - # This is needed to make sure the output file of myrule is visible to the - # resulting instantiated script. - return [DefaultInfo(runfiles=ctx.runfiles(files=[target]))] - -myrule_validation_test = rule( - implementation = _myrule_validation_test_impl, - attrs = {"target": attr.label(allow_single_file=True), - # You need an implicit dependency in order to access the template. - # A target could potentially override this attribute to modify - # the test logic. - "_script": attr.label(allow_single_file=True, - default=Label("//mypkg:myrule_validator"))}, - test = True, -) -``` - -`//mypkg/BUILD`: - -```python -... - -myrule( - name = "mytarget", -) - -... - -# Needed just once, to expose the template. Could have also used export_files(), -# and made the _script attribute set allow_files=True. -filegroup( - name = "myrule_validator", - srcs = [":myrule_validator.sh.template"], -) - -# Needed for each target whose artifacts are to be checked. Notice that you no -# longer have to specify the output file name in a data attribute, or its -# $(location) expansion in an args attribute, or the label for the script -# (unless you want to override it). -myrule_validation_test( - name = "validate_mytarget", - target = ":mytarget", -) -``` - -Alternatively, instead of using a template expansion action, you could have -inlined the template into the .bzl file as a string and expanded it during the -analysis phase using the `str.format` method or `%`-formatting. - -## Testing Starlark utilities - -[Skylib](https://github.com/bazelbuild/bazel-skylib)'s -[`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/lib/unittest.bzl) -framework can be used to test utility functions (that is, functions that are -neither macros nor rule implementations). Instead of using `unittest.bzl`'s -`analysistest` library, `unittest` may be used. For such test suites, the -convenience function `unittest.suite()` can be used to reduce boilerplate. - -`//mypkg/myhelpers.bzl`: - -```python -def myhelper(): - return "abc" -``` - -`//mypkg/myhelpers_test.bzl`: - - -```python -load("@bazel_skylib//lib:unittest.bzl", "asserts", "unittest") -load(":myhelpers.bzl", "myhelper") - -def _myhelper_test_impl(ctx): - env = unittest.begin(ctx) - asserts.equals(env, "abc", myhelper()) - return unittest.end(env) - -myhelper_test = unittest.make(_myhelper_test_impl) - -# No need for a test_myhelper() setup function. - -def myhelpers_test_suite(name): - # unittest.suite() takes care of instantiating the testing rules and creating - # a test_suite. - unittest.suite( - name, - myhelper_test, - # ... - ) -``` - -`//mypkg/BUILD`: - -```python -load(":myhelpers_test.bzl", "myhelpers_test_suite") - -myhelpers_test_suite(name = "myhelpers_tests") -``` - -For more examples, see Skylib's own [tests](https://github.com/bazelbuild/bazel-skylib/blob/main/tests/BUILD). diff --git a/rules/verbs-tutorial.mdx b/rules/verbs-tutorial.mdx deleted file mode 100644 index db7757e..0000000 --- a/rules/verbs-tutorial.mdx +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: 'Using Macros to Create Custom Verbs' ---- - - - -Day-to-day interaction with Bazel happens primarily through a few commands: -`build`, `test`, and `run`. At times, though, these can feel limited: you may -want to push packages to a repository, publish documentation for end-users, or -deploy an application with Kubernetes. But Bazel doesn't have a `publish` or -`deploy` command – where do these actions fit in? - -## The bazel run command - -Bazel's focus on hermeticity, reproducibility, and incrementality means the -`build` and `test` commands aren't helpful for the above tasks. These actions -may run in a sandbox, with limited network access, and aren't guaranteed to be -re-run with every `bazel build`. - -Instead, rely on `bazel run`: the workhorse for tasks that you *want* to have -side effects. Bazel users are accustomed to rules that create executables, and -rule authors can follow a common set of patterns to extend this to -"custom verbs". - -### In the wild: rules_k8s -For example, consider [`rules_k8s`](https://github.com/bazelbuild/rules_k8s), -the Kubernetes rules for Bazel. Suppose you have the following target: - -```python -# BUILD file in //application/k8s -k8s_object( - name = "staging", - kind = "deployment", - cluster = "testing", - template = "deployment.yaml", -) -``` - -The [`k8s_object` rule](https://github.com/bazelbuild/rules_k8s#usage) builds a -standard Kubernetes YAML file when `bazel build` is used on the `staging` -target. However, the additional targets are also created by the `k8s_object` -macro with names like `staging.apply` and `:staging.delete`. These build -scripts to perform those actions, and when executed with `bazel run -staging.apply`, these behave like our own `bazel k8s-apply` or `bazel -k8s-delete` commands. - -### Another example: ts_api_guardian_test - -This pattern can also be seen in the Angular project. The -[`ts_api_guardian_test` macro](https://github.com/angular/angular/blob/16ac611a8410e6bcef8ffc779f488ca4fa102155/tools/ts-api-guardian/index.bzl#L22) -produces two targets. The first is a standard `nodejs_test` target which compares -some generated output against a "golden" file (that is, a file containing the -expected output). This can be built and run with a normal `bazel -test` invocation. In `angular-cli`, you can run [one such -target](https://github.com/angular/angular-cli/blob/e1269cb520871ee29b1a4eec6e6c0e4a94f0b5fc/etc/api/BUILD) -with `bazel test //etc/api:angular_devkit_core_api`. - -Over time, this golden file may need to be updated for legitimate reasons. -Updating this manually is tedious and error-prone, so this macro also provides -a `nodejs_binary` target that updates the golden file, instead of comparing -against it. Effectively, the same test script can be written to run in "verify" -or "accept" mode, based on how it's invoked. This follows the same pattern -you've learned already: there is no native `bazel test-accept` command, but the -same effect can be achieved with -`bazel run //etc/api:angular_devkit_core_api.accept`. - -This pattern can be quite powerful, and turns out to be quite common once you -learn to recognize it. - -## Adapting your own rules - -[Macros](/extending/macros) are the heart of this pattern. Macros are used like -rules, but they can create several targets. Typically, they will create a -target with the specified name which performs the primary build action: perhaps -it builds a normal binary, a Docker image, or an archive of source code. In -this pattern, additional targets are created to produce scripts performing side -effects based on the output of the primary target, like publishing the -resulting binary or updating the expected test output. - -To illustrate this, wrap an imaginary rule that generates a website with -[Sphinx](https://www.sphinx-doc.org) with a macro to create an additional -target that allows the user to publish it when ready. Consider the following -existing rule for generating a website with Sphinx: - -```python -_sphinx_site = rule( - implementation = _sphinx_impl, - attrs = {"srcs": attr.label_list(allow_files = [".rst"])}, -) -``` - -Next, consider a rule like the following, which builds a script that, when run, -publishes the generated pages: - -```python -_sphinx_publisher = rule( - implementation = _publish_impl, - attrs = { - "site": attr.label(), - "_publisher": attr.label( - default = "//internal/sphinx:publisher", - executable = True, - ), - }, - executable = True, -) -``` - -Finally, define the following symbolic macro (available in Bazel 8 or newer) to -create targets for both of the above rules together: - -```starlark -def _sphinx_site_impl(name, visibility, srcs, **kwargs): - # This creates the primary target, producing the Sphinx-generated HTML. We - # set `visibility = visibility` to make it visible to callers of the - # macro. - _sphinx_site(name = name, visibility = visibility, srcs = srcs, **kwargs) - # This creates the secondary target, which produces a script for publishing - # the site generated above. We don't want it to be visible to callers of - # our macro, so we omit visibility for it. - _sphinx_publisher(name = "%s.publish" % name, site = name, **kwargs) - -sphinx_site = macro( - implementation = _sphinx_site_impl, - attrs = {"srcs": attr.label_list(allow_files = [".rst"])}, - # Inherit common attributes like tags and testonly - inherit_attrs = "common", -) -``` - -Or, if you need to support Bazel releases older than Bazel 8, you would instead -define a legacy macro: - -```starlark -def sphinx_site(name, srcs = [], **kwargs): - # This creates the primary target, producing the Sphinx-generated HTML. - _sphinx_site(name = name, srcs = srcs, **kwargs) - # This creates the secondary target, which produces a script for publishing - # the site generated above. - _sphinx_publisher(name = "%s.publish" % name, site = name, **kwargs) -``` - -In the `BUILD` files, use the macro as though it just creates the primary -target: - -```python -sphinx_site( - name = "docs", - srcs = ["index.md", "providers.md"], -) -``` - -In this example, a "docs" target is created, just as though the macro were a -standard, single Bazel rule. When built, the rule generates some configuration -and runs Sphinx to produce an HTML site, ready for manual inspection. However, -an additional "docs.publish" target is also created, which builds a script for -publishing the site. Once you check the output of the primary target, you can -use `bazel run :docs.publish` to publish it for public consumption, just like -an imaginary `bazel publish` command. - -It's not immediately obvious what the implementation of the `_sphinx_publisher` -rule might look like. Often, actions like this write a _launcher_ shell script. -This method typically involves using -[`ctx.actions.expand_template`](lib/actions#expand_template) -to write a very simple shell script, in this case invoking the publisher binary -with a path to the output of the primary target. This way, the publisher -implementation can remain generic, the `_sphinx_site` rule can just produce -HTML, and this small script is all that's necessary to combine the two -together. - -In `rules_k8s`, this is indeed what `.apply` does: -[`expand_template`](https://github.com/bazelbuild/rules_k8s/blob/f10e7025df7651f47a76abf1db5ade1ffeb0c6ac/k8s/object.bzl#L213-L241) -writes a very simple Bash script, based on -[`apply.sh.tpl`](https://github.com/bazelbuild/rules_k8s/blob/f10e7025df7651f47a76abf1db5ade1ffeb0c6ac/k8s/apply.sh.tpl), -which runs `kubectl` with the output of the primary target. This script can -then be build and run with `bazel run :staging.apply`, effectively providing a -`k8s-apply` command for `k8s_object` targets. From 4fbd0d27f0832c180ee0ce8ddd534ca78523dc7b Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sun, 12 Oct 2025 17:12:10 -0700 Subject: [PATCH 10/14] Run converter after upstream docs are copied --- .github/workflows/pull-from-bazel-build.yml | 66 +++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/.github/workflows/pull-from-bazel-build.yml b/.github/workflows/pull-from-bazel-build.yml index 4dd1c33..24b4208 100644 --- a/.github/workflows/pull-from-bazel-build.yml +++ b/.github/workflows/pull-from-bazel-build.yml @@ -78,3 +78,69 @@ jobs: - name: Create versioned navigation run: ./docs.json.update.sh + + - name: Set up Go + uses: actions/setup-go@v6 + with: + go-version: '1.25.2' + + - name: Initialize Go module for converter + run: | + cd html2md_converter + go mod init html-to-md-converter + go get github.com/JohannesKaufmann/html-to-markdown + + - name: Build HTML to Markdown converter + run: | + cd html2md_converter + go build -o html-to-md main.go + + - name: Convert reference documentation HTML to Markdown + run: | + # Extract and convert HTML reference docs to Markdown + ./html2md_converter/html-to-md \ + -zip upstream/bazel-bin/src/main/java/com/google/devtools/build/lib/reference-docs.zip \ + -output reference-docs-temp + + - name: Transform reference docs to MDX + run: | + # Process reference/ directory + find reference-docs-temp/reference -name "*.md" -type f | while read -r file; do + # Extract path relative to reference-docs-temp/ + rel_path="${file#reference-docs-temp/}" + output_file="$rel_path" + output_file="${output_file%.md}.mdx" + mkdir -p "$(dirname "$output_file")" + awk -f transform-docs.awk "$file" > "$output_file" + done + + # Copy YAML files + find reference-docs-temp/reference -name "*.yaml" -type f | while read -r file; do + rel_path="${file#reference-docs-temp/}" + output_file="$rel_path" + mkdir -p "$(dirname "$output_file")" + cp "$file" "$output_file" + done + + - name: Transform rules docs to MDX + run: | + # Process rules/ directory + find reference-docs-temp/rules -name "*.md" -type f | while read -r file; do + # Extract path relative to reference-docs-temp/ + rel_path="${file#reference-docs-temp/}" + output_file="$rel_path" + output_file="${output_file%.md}.mdx" + mkdir -p "$(dirname "$output_file")" + awk -f transform-docs.awk "$file" > "$output_file" + done + + # Copy YAML files + find reference-docs-temp/rules -name "*.yaml" -type f | while read -r file; do + rel_path="${file#reference-docs-temp/}" + output_file="$rel_path" + mkdir -p "$(dirname "$output_file")" + cp "$file" "$output_file" + done + + - name: Clean up temporary files + run: rm -rf reference-docs-temp From c10fe20621f2f5cdd484c37a4b91ac3270b80fed Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sun, 12 Oct 2025 17:29:43 -0700 Subject: [PATCH 11/14] remove yaml files --- convert_reference_docs.py | 214 --------------------------- reference/be/_toc.yaml | 33 ----- reference/be/overview.mdx | 2 - rules/lib/_toc.yaml | 297 -------------------------------------- 4 files changed, 546 deletions(-) delete mode 100644 convert_reference_docs.py delete mode 100644 reference/be/_toc.yaml delete mode 100644 rules/lib/_toc.yaml diff --git a/convert_reference_docs.py b/convert_reference_docs.py deleted file mode 100644 index e94fad9..0000000 --- a/convert_reference_docs.py +++ /dev/null @@ -1,214 +0,0 @@ -#!/usr/bin/env python3 -import sys -import zipfile -import shutil -import re -from pathlib import Path -import markdownify - -def strip_devsite_templates(html_text: str) -> str: - """Remove DevSite template tags `{% … %}` and `{{ … }}` (multiline).""" - html_text = re.sub(r"\{\%.*?\%\}", "", html_text, flags=re.DOTALL) - html_text = re.sub(r"\{\{.*?\}\}", "", html_text) - return html_text - -def html_to_markdown(html_text: str) -> str: - """Convert HTML to Markdown (approximate).""" - return markdownify.markdownify(html_text, heading_style="ATX") - -def sanitize_for_mdx(md_text: str) -> str: - """ - Sanitize Markdown to MDX-safe: - - Drop first heading (to avoid duplicate title) - - Escape bad `{…}` expressions - - Convert `<https://…>` to Markdown links - - Rewrite .html → .mdx - - Fix leading slash links - - Strip styles, normalize IDs - - Escape leftover tags / braces - - Patch problematic sequences like `)><code>…()` in anchors - """ - out_lines = [] - seen_ids = {} - skip_first_heading = True - - for ln in md_text.splitlines(): - # Skip first top-level heading (if any) - if skip_first_heading and re.match(r"^#\s+.+", ln): - skip_first_heading = False - continue - - # Remove leftover template constructs - if "{%" in ln: - ln = re.sub(r"\{\%.*?\%\}", "", ln) - if "{{" in ln: - ln = re.sub(r"\{\{.*?\}\}", "", ln) - - # **FIX: Clean up broken markdown link syntax with embedded HTML** - # Pattern: [text](url>junk..., more text](final-url) - # This happens when anchor tags are nested or malformed in original HTML - # Strategy: If a markdown link URL contains '>' followed by junk and then another '](', - # remove everything from '>' to the next '](' - - # First pass: Remove complex broken link portions with multiple issues - ln = re.sub( - r'\]\(([^)>]+)>[^\]]*\]\(', - r'](\1](', - ln - ) - - # Second pass: Clean up any remaining unescaped HTML tags within markdown links - # This handles cases where <a>, <code>, etc. appear inside ](...) - def fix_markdown_link_html(match): - url = match.group(1) - # If URL contains unescaped < or HTML-like content, truncate at first > - if '>' in url and '<' in url: - url = url.split('>')[0] - # Escape any remaining angle brackets - url = url.replace('<', '\\<').replace('>', '\\>') - return '](' + url + ')' - - ln = re.sub(r'\]\(([^)]+)\)', fix_markdown_link_html, ln) - - # **FIX: Escape problematic HTML sequences EARLY** - # Pattern 1: stuff>\<code\>stuff()\</code\>\</a\>, <a href= - ln = re.sub( - r'>\\\<code\\\>([^<]+)\\\</code\\\>\\\</a\\\>,\s*\<a\s+href=', - lambda m: r'>`' + m.group(1) + r'()`</a>, <a href=', - ln - ) - - # Pattern 2: Any remaining >\<code\> patterns - ln = re.sub(r'>\\\<code\\\>', r'>`<code>', ln) - ln = re.sub(r'\\\</code\\\>\\\</a\\\>', r'</code>`</a>', ln) - - # Pattern 3: Bare href= without quotes (from malformed links) - ln = re.sub(r'<a\s+href=\)', r'<a href="#">', ln) - ln = re.sub(r'href=\s*\)', r'href="#">', ln) - - # Escape `{…}` with colon inside - ln = re.sub( - r"\{([^}]*?:[^}]*)\}", - lambda m: r"\{" + m.group(1) + r"\}", - ln, - ) - - # Escape unescaped `{` or `}` - ln = re.sub(r"(?<!\\)\{", r"\{", ln) - ln = re.sub(r"(?<!\\)\}", r"\}", ln) - - # Rewrite .html links to .mdx - ln = re.sub(r"\(([^)]+)\.html\)", r"(\1.mdx)", ln) - ln = re.sub(r'href="([^"]+)\.html"', r'href="\1.mdx"', ln) - - # Convert raw angle-bracket URLs into Markdown links - ln = re.sub(r"<(https?://[^>]+)>", r"[\1](\1)", ln) - - # **FIX: Escape comparison operators that look like HTML tags** - # Replace <= and >= with HTML entities or escaped versions - # Do this BEFORE other tag escaping to avoid confusion - ln = re.sub(r'<=', r'<=', ln) - ln = re.sub(r'>=', r'>=', ln) - - # **FIX: Escape #include <header.h> patterns** - # Pattern: #include <path/to/file.h> where the angle brackets look like HTML - ln = re.sub(r'#include\s+<([^>]+)>', r'#include <\1>', ln) - - # **FIX: Handle escaped tags more carefully** - # Only escape tags that aren't already in code blocks or properly formed - # Skip escaping if we're in a code context - if not ('`' in ln and ln.count('`') % 2 == 0): - ln = re.sub(r"<([^ >]+)>", r"\<\1\>", ln) - - # Fix leading slash links: [text](/path) → relative - ln = re.sub(r"\[([^\]]+)\]\(/([^)]+)\)", r"[\1](./\2)", ln) - ln = re.sub(r'href="/([^"]+)"', r'href="./\1"', ln) - - # Strip inline style attributes - ln = re.sub(r'style="[^"]*"', "", ln) - - # Normalize id="section-foo" - ln = re.sub(r'id="section-([A-Za-z0-9_-]+)"', r'id="\1"', ln) - - # Escape known custom tags - ln = re.sub(r"<(workspace|symlink_path|attribute_name)([^>]*)>", r"\<\1\2\>", ln) - ln = re.sub(r"</(workspace|symlink_path|attribute_name)>", r"\</\1\>", ln) - - # **FIX: More careful handling of </code> - only escape if not in inline code** - # Count backticks to see if we're in code context - backtick_count = ln.count('`') - if backtick_count % 2 == 1: # Odd number means we're inside code - pass # Don't escape - else: - ln = ln.replace("</code>", r"\</code>") - - # **FIX: Patch problematic `)><code>` sequences inside anchor context** - ln = re.sub( - r"\)\>\<code\>([^<]+)\</code\>", - lambda m: r") `<code>" + m.group(1) + r"</code>`", - ln - ) - # Also patch anchor boundary syntax - ln = re.sub(r"</a>,\s*<a href=", r"\</a\>, \<a href=", ln) - - # **FIX: Clean up malformed href attributes** - # Pattern: href=)/some/path - should be removed or fixed - ln = re.sub(r'href=\)/[^"\s)]+', r'href="#"', ln) - - # Deduplicate heading IDs - m = re.match(r'^(#+)\s*(.*)\s*\{#([A-Za-z0-9_-]+)\}', ln) - if m: - hashes, text, hid = m.groups() - cnt = seen_ids.get(hid, 0) - if cnt > 0: - newhid = f"{hid}-{cnt+1}" - ln = f"{hashes} {text} {{#{newhid}}}" - seen_ids[hid] = cnt + 1 - - out_lines.append(ln) - - return "\n".join(out_lines) - -def make_frontmatter(title: str) -> str: - safe = title.replace("'", "\\'") - return f"---\ntitle: '{safe}'\n---\n\n" - -def convert_html_file(html_path: Path, mdx_path: Path) -> None: - html_text = html_path.read_text(encoding="utf-8", errors="ignore") - cleaned = strip_devsite_templates(html_text) - md = html_to_markdown(cleaned) - sanitized = sanitize_for_mdx(md) - title = html_path.stem - front = make_frontmatter(title) - mdx_path.parent.mkdir(parents=True, exist_ok=True) - mdx_path.write_text(front + sanitized, encoding="utf-8") - print(f"Wrote {mdx_path}") - -def process_zip(zip_path: Path) -> None: - tmp = Path("_tmp_unzip_convert") - if tmp.exists(): - shutil.rmtree(tmp) - tmp.mkdir() - with zipfile.ZipFile(zip_path, "r") as z: - z.extractall(tmp) - - for html_path in tmp.rglob("*.html"): - rel = html_path.relative_to(tmp) - mdx_out = Path(rel).with_suffix(".mdx") - convert_html_file(html_path, mdx_out) - - shutil.rmtree(tmp) - -def main(): - if len(sys.argv) != 2: - print("Usage: python3 converter.py <reference-docs.zip>") - sys.exit(1) - zipf = Path(sys.argv[1]) - if not zipf.is_file(): - print(f"Error: {zipf} not found") - sys.exit(1) - process_zip(zipf) - print("Conversion done.") - -if __name__ == "__main__": - main() \ No newline at end of file diff --git a/reference/be/_toc.yaml b/reference/be/_toc.yaml deleted file mode 100644 index b1cb8b0..0000000 --- a/reference/be/_toc.yaml +++ /dev/null @@ -1,33 +0,0 @@ -toc: -- title: Build encyclopedia - section: - - title: Overview - path: /reference/be/overview - - title: Common definitions - path: /reference/be/common-definitions - - title: Make variables - path: /reference/be/make-variables - - title: Functions - path: /reference/be/functions - - title: Core rules - section: - - title: Extra Actions - path: /reference/be/extra-actions - - title: General - path: /reference/be/general - - title: Platforms and Toolchains - path: /reference/be/platforms-and-toolchains - - title: Language Specific rules - section: - - title: C / C++ - path: /reference/be/c-cpp - - title: Java - path: /reference/be/java - - title: Objective-C - path: /reference/be/objective-c - - title: Protocol Buffer - path: /reference/be/protocol-buffer - - title: Python - path: /reference/be/python - - title: Shell - path: /reference/be/shell diff --git a/reference/be/overview.mdx b/reference/be/overview.mdx index b57c03a..f4aadf5 100644 --- a/reference/be/overview.mdx +++ b/reference/be/overview.mdx @@ -2,8 +2,6 @@ title: 'Bazel BUILD Encyclopedia of Functions' --- - - ## Concepts and terminology - [Common definitions](/reference/be/common-definitions) - [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization) diff --git a/rules/lib/_toc.yaml b/rules/lib/_toc.yaml deleted file mode 100644 index 81f8c15..0000000 --- a/rules/lib/_toc.yaml +++ /dev/null @@ -1,297 +0,0 @@ -toc: -- title: Build API - section: - - title: Overview - path: /rules/lib/overview - - title: "Global functions" - section: - - title: Overview - path: /rules/lib/globals - - title: .bzl files - path: /rules/lib/globals/bzl - - title: All Bazel files - path: /rules/lib/globals/all - - title: BUILD files - path: /rules/lib/globals/build - - title: MODULE.bazel files - path: /rules/lib/globals/module - - title: REPO.bazel files - path: /rules/lib/globals/repo - - title: VENDOR.bazel files - path: /rules/lib/globals/vendor - - title: "Configuration Fragments" - section: - - title: Overview - path: /rules/lib/fragments - - title: apple - path: /rules/lib/fragments/apple - - title: bazel_android - path: /rules/lib/fragments/bazel_android - - title: bazel_py - path: /rules/lib/fragments/bazel_py - - title: coverage - path: /rules/lib/fragments/coverage - - title: cpp - path: /rules/lib/fragments/cpp - - title: j2objc - path: /rules/lib/fragments/j2objc - - title: java - path: /rules/lib/fragments/java - - title: objc - path: /rules/lib/fragments/objc - - title: platform - path: /rules/lib/fragments/platform - - title: proto - path: /rules/lib/fragments/proto - - title: py - path: /rules/lib/fragments/py - - title: "Providers" - section: - - title: Overview - path: /rules/lib/providers - - title: AnalysisTestResultInfo - path: /rules/lib/providers/AnalysisTestResultInfo - - title: CcInfo - path: /rules/lib/providers/CcInfo - - title: CcToolchainConfigInfo - path: /rules/lib/providers/CcToolchainConfigInfo - - title: CcToolchainInfo - path: /rules/lib/providers/CcToolchainInfo - - title: ConstraintCollection - path: /rules/lib/providers/ConstraintCollection - - title: ConstraintSettingInfo - path: /rules/lib/providers/ConstraintSettingInfo - - title: ConstraintValueInfo - path: /rules/lib/providers/ConstraintValueInfo - - title: DebugPackageInfo - path: /rules/lib/providers/DebugPackageInfo - - title: DefaultInfo - path: /rules/lib/providers/DefaultInfo - - title: ExecutionInfo - path: /rules/lib/providers/ExecutionInfo - - title: FeatureFlagInfo - path: /rules/lib/providers/FeatureFlagInfo - - title: file_provider - path: /rules/lib/providers/file_provider - - title: FilesToRunProvider - path: /rules/lib/providers/FilesToRunProvider - - title: IncompatiblePlatformProvider - path: /rules/lib/providers/IncompatiblePlatformProvider - - title: InstrumentedFilesInfo - path: /rules/lib/providers/InstrumentedFilesInfo - - title: java_compilation_info - path: /rules/lib/providers/java_compilation_info - - title: java_output_jars - path: /rules/lib/providers/java_output_jars - - title: JavaRuntimeInfo - path: /rules/lib/providers/JavaRuntimeInfo - - title: JavaToolchainInfo - path: /rules/lib/providers/JavaToolchainInfo - - title: MaterializedDepsInfo - path: /rules/lib/providers/MaterializedDepsInfo - - title: ObjcProvider - path: /rules/lib/providers/ObjcProvider - - title: OutputGroupInfo - path: /rules/lib/providers/OutputGroupInfo - - title: PackageSpecificationInfo - path: /rules/lib/providers/PackageSpecificationInfo - - title: PlatformInfo - path: /rules/lib/providers/PlatformInfo - - title: RunEnvironmentInfo - path: /rules/lib/providers/RunEnvironmentInfo - - title: TemplateVariableInfo - path: /rules/lib/providers/TemplateVariableInfo - - title: ToolchainInfo - path: /rules/lib/providers/ToolchainInfo - - title: ToolchainTypeInfo - path: /rules/lib/providers/ToolchainTypeInfo - - title: "Built-in Types" - section: - - title: Overview - path: /rules/lib/builtins - - title: Action - path: /rules/lib/builtins/Action - - title: actions - path: /rules/lib/builtins/actions - - title: apple_platform - path: /rules/lib/builtins/apple_platform - - title: Args - path: /rules/lib/builtins/Args - - title: Aspect - path: /rules/lib/builtins/Aspect - - title: Attribute - path: /rules/lib/builtins/Attribute - - title: bazel_module - path: /rules/lib/builtins/bazel_module - - title: bazel_module_tags - path: /rules/lib/builtins/bazel_module_tags - - title: BuildSetting - path: /rules/lib/builtins/BuildSetting - - title: CcCompilationOutputs - path: /rules/lib/builtins/CcCompilationOutputs - - title: CcLinkingOutputs - path: /rules/lib/builtins/CcLinkingOutputs - - title: CompilationContext - path: /rules/lib/builtins/CompilationContext - - title: configuration - path: /rules/lib/builtins/configuration - - title: ctx - path: /rules/lib/builtins/ctx - - title: depset - path: /rules/lib/builtins/depset - - title: DirectoryExpander - path: /rules/lib/builtins/DirectoryExpander - - title: DottedVersion - path: /rules/lib/builtins/DottedVersion - - title: exec_result - path: /rules/lib/builtins/exec_result - - title: ExecGroupCollection - path: /rules/lib/builtins/ExecGroupCollection - - title: ExecGroupContext - path: /rules/lib/builtins/ExecGroupContext - - title: ExecTransitionFactory - path: /rules/lib/builtins/ExecTransitionFactory - - title: ExpandedDirectory - path: /rules/lib/builtins/ExpandedDirectory - - title: extension_metadata - path: /rules/lib/builtins/extension_metadata - - title: FeatureConfiguration - path: /rules/lib/builtins/FeatureConfiguration - - title: File - path: /rules/lib/builtins/File - - title: fragments - path: /rules/lib/builtins/fragments - - title: java_annotation_processing - path: /rules/lib/builtins/java_annotation_processing - - title: Label - path: /rules/lib/builtins/Label - - title: LateBoundDefault - path: /rules/lib/builtins/LateBoundDefault - - title: LibraryToLink - path: /rules/lib/builtins/LibraryToLink - - title: License - path: /rules/lib/builtins/License - - title: LinkerInput - path: /rules/lib/builtins/LinkerInput - - title: LinkingContext - path: /rules/lib/builtins/LinkingContext - - title: macro - path: /rules/lib/builtins/macro - - title: mapped_root - path: /rules/lib/builtins/mapped_root - - title: module_ctx - path: /rules/lib/builtins/module_ctx - - title: path - path: /rules/lib/builtins/path - - title: propagation_ctx - path: /rules/lib/builtins/propagation_ctx - - title: Provider - path: /rules/lib/builtins/Provider - - title: repo_metadata - path: /rules/lib/builtins/repo_metadata - - title: repository_ctx - path: /rules/lib/builtins/repository_ctx - - title: repository_os - path: /rules/lib/builtins/repository_os - - title: repository_rule - path: /rules/lib/builtins/repository_rule - - title: root - path: /rules/lib/builtins/root - - title: rule - path: /rules/lib/builtins/rule - - title: rule_attributes - path: /rules/lib/builtins/rule_attributes - - title: runfiles - path: /rules/lib/builtins/runfiles - - title: struct - path: /rules/lib/builtins/struct - - title: Subrule - path: /rules/lib/builtins/Subrule - - title: subrule_ctx - path: /rules/lib/builtins/subrule_ctx - - title: SymlinkEntry - path: /rules/lib/builtins/SymlinkEntry - - title: tag_class - path: /rules/lib/builtins/tag_class - - title: Target - path: /rules/lib/builtins/Target - - title: template_ctx - path: /rules/lib/builtins/template_ctx - - title: TemplateDict - path: /rules/lib/builtins/TemplateDict - - title: toolchain_type - path: /rules/lib/builtins/toolchain_type - - title: ToolchainContext - path: /rules/lib/builtins/ToolchainContext - - title: transition - path: /rules/lib/builtins/transition - - title: wasm_exec_result - path: /rules/lib/builtins/wasm_exec_result - - title: wasm_module - path: /rules/lib/builtins/wasm_module - - title: "Top-level Modules" - section: - - title: Overview - path: /rules/lib/toplevel - - title: apple_common - path: /rules/lib/toplevel/apple_common - - title: attr - path: /rules/lib/toplevel/attr - - title: cc_common - path: /rules/lib/toplevel/cc_common - - title: config - path: /rules/lib/toplevel/config - - title: config_common - path: /rules/lib/toplevel/config_common - - title: coverage_common - path: /rules/lib/toplevel/coverage_common - - title: java_common - path: /rules/lib/toplevel/java_common - - title: native - path: /rules/lib/toplevel/native - - title: platform_common - path: /rules/lib/toplevel/platform_common - - title: proto - path: /rules/lib/toplevel/proto - - title: testing - path: /rules/lib/toplevel/testing - - title: "Core Starlark data types" - section: - - title: Overview - path: /rules/lib/core - - title: bool - path: /rules/lib/core/bool - - title: builtin_function_or_method - path: /rules/lib/core/builtin_function_or_method - - title: dict - path: /rules/lib/core/dict - - title: float - path: /rules/lib/core/float - - title: function - path: /rules/lib/core/function - - title: int - path: /rules/lib/core/int - - title: json - path: /rules/lib/core/json - - title: list - path: /rules/lib/core/list - - title: range - path: /rules/lib/core/range - - title: set - path: /rules/lib/core/set - - title: string - path: /rules/lib/core/string - - title: tuple - path: /rules/lib/core/tuple - - title: "Repository rules" - section: - - title: Overview - path: /rules/lib/repo/index - - title: git - path: /rules/lib/repo/git - - title: http - path: /rules/lib/repo/http - - title: local - path: /rules/lib/repo/local - - title: utils - path: /rules/lib/repo/utils From 37cdd1812b60a9166424b5875a32650c6a8ff454 Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sun, 12 Oct 2025 19:11:12 -0700 Subject: [PATCH 12/14] fix missing links --- .github/workflows/pull-from-bazel-build.yml | 51 +- configure/best-practices.mdx | 1 + copy-upstream-docs.sh | 73 +- docs.json | 255 +++---- html2md_converter/main.go | 5 - html_mdx_converter_test.sh | 96 +-- install/ide.mdx | 3 +- process-reference-docs.sh | 155 ----- reference/be/overview.mdx | 2 + reference/glossary.mdx | 715 ++++++++++++++++++++ reference/skyframe.mdx | 198 ++++++ release/index.mdx | 4 +- rules/bzl-style.mdx | 212 ++++++ rules/challenges.mdx | 223 ++++++ rules/deploying.mdx | 223 ++++++ rules/errors/read-only-variable.mdx | 30 + rules/faq.mdx | 80 +++ rules/index.mdx | 85 +++ rules/legacy-macro-tutorial.mdx | 98 +++ rules/macro-tutorial.mdx | 116 ++++ rules/performance.mdx | 302 +++++++++ rules/rules-tutorial.mdx | 367 ++++++++++ rules/testing.mdx | 474 +++++++++++++ rules/verbs-tutorial.mdx | 177 +++++ 24 files changed, 3486 insertions(+), 459 deletions(-) delete mode 100755 process-reference-docs.sh create mode 100644 reference/glossary.mdx create mode 100644 reference/skyframe.mdx create mode 100644 rules/bzl-style.mdx create mode 100644 rules/challenges.mdx create mode 100644 rules/deploying.mdx create mode 100644 rules/errors/read-only-variable.mdx create mode 100644 rules/faq.mdx create mode 100644 rules/index.mdx create mode 100644 rules/legacy-macro-tutorial.mdx create mode 100644 rules/macro-tutorial.mdx create mode 100644 rules/performance.mdx create mode 100644 rules/rules-tutorial.mdx create mode 100644 rules/testing.mdx create mode 100644 rules/verbs-tutorial.mdx diff --git a/.github/workflows/pull-from-bazel-build.yml b/.github/workflows/pull-from-bazel-build.yml index 24b4208..e3838be 100644 --- a/.github/workflows/pull-from-bazel-build.yml +++ b/.github/workflows/pull-from-bazel-build.yml @@ -73,12 +73,6 @@ jobs: - name: Clean up mdx files run: ./cleanup-mdx.sh - - name: Transform upstream docs to mdx - run: ./copy-upstream-docs.sh - - - name: Create versioned navigation - run: ./docs.json.update.sh - - name: Set up Go uses: actions/setup-go@v6 with: @@ -102,45 +96,12 @@ jobs: -zip upstream/bazel-bin/src/main/java/com/google/devtools/build/lib/reference-docs.zip \ -output reference-docs-temp - - name: Transform reference docs to MDX - run: | - # Process reference/ directory - find reference-docs-temp/reference -name "*.md" -type f | while read -r file; do - # Extract path relative to reference-docs-temp/ - rel_path="${file#reference-docs-temp/}" - output_file="$rel_path" - output_file="${output_file%.md}.mdx" - mkdir -p "$(dirname "$output_file")" - awk -f transform-docs.awk "$file" > "$output_file" - done - - # Copy YAML files - find reference-docs-temp/reference -name "*.yaml" -type f | while read -r file; do - rel_path="${file#reference-docs-temp/}" - output_file="$rel_path" - mkdir -p "$(dirname "$output_file")" - cp "$file" "$output_file" - done - - - name: Transform rules docs to MDX - run: | - # Process rules/ directory - find reference-docs-temp/rules -name "*.md" -type f | while read -r file; do - # Extract path relative to reference-docs-temp/ - rel_path="${file#reference-docs-temp/}" - output_file="$rel_path" - output_file="${output_file%.md}.mdx" - mkdir -p "$(dirname "$output_file")" - awk -f transform-docs.awk "$file" > "$output_file" - done - - # Copy YAML files - find reference-docs-temp/rules -name "*.yaml" -type f | while read -r file; do - rel_path="${file#reference-docs-temp/}" - output_file="$rel_path" - mkdir -p "$(dirname "$output_file")" - cp "$file" "$output_file" - done + - name: Transform upstream docs to mdx + run: ./copy-upstream-docs.sh + - name: Create versioned navigation + run: ./docs.json.update.sh + - name: Clean up temporary files run: rm -rf reference-docs-temp + diff --git a/configure/best-practices.mdx b/configure/best-practices.mdx index 00b4391..431b686 100644 --- a/configure/best-practices.mdx +++ b/configure/best-practices.mdx @@ -80,6 +80,7 @@ and add `user.bazelrc` to your `.gitignore`. The open-source [bazelrc-preset.bzl](https://github.com/bazel-contrib/bazelrc-preset.bzl) + generates a custom bazelrc file that matches your Bazel version and provides a preset of recommended flags. diff --git a/copy-upstream-docs.sh b/copy-upstream-docs.sh index a47108e..3a23a22 100755 --- a/copy-upstream-docs.sh +++ b/copy-upstream-docs.sh @@ -6,8 +6,15 @@ set -o errexit -o nounset -o pipefail -SOURCE_DIR="upstream/site/en" -DEST_DIR="${1:-.}" # Use first argument or current directory as default +# Primary upstream directory +UPSTREAM_SITE="upstream/site/en" + +# Reference docs directory +REFERENCE_DOCS="reference-docs-temp" + +# Destination directory (default to current directory) +DEST_DIR="${1:-.}" + # Files that live in this repo, not fetched from upstream LOCAL_FILES=" index.mdx @@ -43,6 +50,7 @@ query/language.mdx query/quickstart.mdx reference/flag-cheatsheet.mdx reference/test-encyclopedia.mdx +reference/be/be-nav.mdx release/rolling.mdx remote/ci.mdx remote/dynamic.mdx @@ -53,53 +61,56 @@ start/go.mdx tutorials/ccp-toolchain-config.mdx " -# Check if source directory exists -if [ ! -d "$SOURCE_DIR" ]; then - echo "Error: Source directory '$SOURCE_DIR' not found" +# Verify that at least one source exists +if [ ! -d "$UPSTREAM_SITE" ] && [ ! -d "$REFERENCE_DOCS" ]; then + echo "Error: neither source directory exists: '$UPSTREAM_SITE' or '$REFERENCE_DOCS'" exit 1 fi -# Create destination directory if it doesn't exist if [ ! -d "$DEST_DIR" ]; then echo "Creating destination directory: $DEST_DIR" mkdir -p "$DEST_DIR" fi -echo "Finding all .md files in $SOURCE_DIR and copying to $DEST_DIR..." - -# Find all .md files and copy them -find "$SOURCE_DIR" -name "*.md" -type f | while read -r source_file; do - # Get relative path from upstream/site/en - relative_path="${source_file#$SOURCE_DIR/}" - - # Convert .md to .mdx - target_file="${relative_path%.md}.mdx" - - # Create target directory if it doesn't exist - target_dir=$(dirname "$DEST_DIR/$target_file") - if [ "$target_dir" != "$DEST_DIR" ]; then - mkdir -p "$target_dir" +echo "Will search in '$UPSTREAM_SITE' and '$REFERENCE_DOCS' (if exists) to copy .md → .mdx to $DEST_DIR" + +transform_docs() { + local SOURCE_DIR="$1" + if [ ! -d "$SOURCE_DIR" ]; then + echo "Warning: source directory '$SOURCE_DIR' not found, skipping" + return fi - + + find "$SOURCE_DIR" -name "*.md" -type f | while read -r source_file; do + # Derive the relative path inside the source tree + relative_path="${source_file#$SOURCE_DIR/}" + target_file="${relative_path%.md}.mdx" + target_dir=$(dirname "$DEST_DIR/$target_file") + + mkdir -p "$target_dir" + # Check if this file is in the BROKEN_FILES list - if echo "$BROKEN_FILES" | grep -q "^$target_file$"; then - echo "Skipping broken file: $target_file" - continue - fi - + if echo "$BROKEN_FILES" | grep -q "^$target_file$"; then + echo "Skipping broken file: $target_file" + continue + fi + # Transform and copy the file echo "Transforming and copying $source_file to $DEST_DIR/$target_file" awk -f transform-docs.awk "$source_file" > "$DEST_DIR/$target_file" -done + done +} -echo "Successfully copied all .md files to .mdx files in $DEST_DIR" +# Copy from both sources +transform_docs "$UPSTREAM_SITE" +transform_docs "$REFERENCE_DOCS" -# Convert community YAML files to MDX echo "Converting community YAML files to MDX..." ./convert-community-to-mdx.sh "$DEST_DIR/community/experts" ./convert-community-to-mdx.sh "$DEST_DIR/community/partners" -# Copy community images to destination community/images/ -# We don't need to do this for images under a docs/ folder, so many other images already work +echo "Copying community images..." mkdir -p "$DEST_DIR/community/images" cp upstream/site/en/community/images/* "$DEST_DIR/community/images/" + +echo "Done copying docs." diff --git a/docs.json b/docs.json index 42a4f12..145b9de 100644 --- a/docs.json +++ b/docs.json @@ -166,10 +166,19 @@ { "group": "Build encyclopedia", "pages": [ - "reference/be/overview", + "reference/be/c-cpp", "reference/be/common-definitions", + "reference/be/extra-actions", + "reference/be/functions", + "reference/be/general", + "reference/be/java", "reference/be/make-variables", - "reference/be/functions" + "reference/be/objective-c", + "reference/be/overview", + "reference/be/platforms-and-toolchains", + "reference/be/protocol-buffers", + "reference/be/python", + "reference/be/shell" ] }, { @@ -178,12 +187,6 @@ "reference/command-line-reference" ] }, - { - "group": "Query Language", - "pages": [ - "query/language" - ] - }, { "group": "Glossary", "pages": [ @@ -191,9 +194,9 @@ ] }, { - "group": "Flag cheatsheet", + "group": "Skyframe", "pages": [ - "reference/flag-cheatsheet" + "reference/skyframe" ] } ] @@ -1648,23 +1651,23 @@ { "group": "Why Bazel?", "pages": [ - "7.6.1/about/intro", - "7.6.1/about/why", - "7.6.1/about/vision", - "7.6.1/about/roadmap", - "7.6.1/about/faq" + "7.6.2/about/intro", + "7.6.2/about/why", + "7.6.2/about/vision", + "7.6.2/about/roadmap", + "7.6.2/about/faq" ] }, { "group": "Build system basics", "pages": [ - "7.6.1/basics", - "7.6.1/basics/build-systems", - "7.6.1/basics/task-based-builds", - "7.6.1/basics/artifact-based-builds", - "7.6.1/basics/distributed-builds", - "7.6.1/basics/dependencies", - "7.6.1/basics/hermeticity" + "7.6.2/basics", + "7.6.2/basics/build-systems", + "7.6.2/basics/task-based-builds", + "7.6.2/basics/artifact-based-builds", + "7.6.2/basics/distributed-builds", + "7.6.2/basics/dependencies", + "7.6.2/basics/hermeticity" ] } ] @@ -1675,37 +1678,37 @@ { "group": "Install", "pages": [ - "7.6.1/install", - "7.6.1/install/bazelisk", - "7.6.1/install/os-x", - "7.6.1/install/windows", - "7.6.1/install/ubuntu", - "7.6.1/install/suse", - "7.6.1/install/docker-container", - "7.6.1/install/compile-source", - "7.6.1/install/completion", - "7.6.1/install/ide" + "7.6.2/install", + "7.6.2/install/bazelisk", + "7.6.2/install/os-x", + "7.6.2/install/windows", + "7.6.2/install/ubuntu", + "7.6.2/install/suse", + "7.6.2/install/docker-container", + "7.6.2/install/compile-source", + "7.6.2/install/completion", + "7.6.2/install/ide" ] }, { "group": "First build tutorials", "pages": [ - "7.6.1/start/cpp", - "7.6.1/start/java", - "7.6.1/start/android-app", - "7.6.1/start/ios-app" + "7.6.2/start/cpp", + "7.6.2/start/java", + "7.6.2/start/android-app", + "7.6.2/start/ios-app" ] }, { "group": "Concepts", "pages": [ - "7.6.1/concepts/build-ref", - "7.6.1/concepts/labels", - "7.6.1/concepts/build-files", - "7.6.1/concepts/dependencies", - "7.6.1/concepts/visibility", - "7.6.1/concepts/platforms", - "7.6.1/concepts/hermeticity" + "7.6.2/concepts/build-ref", + "7.6.2/concepts/labels", + "7.6.2/concepts/build-files", + "7.6.2/concepts/dependencies", + "7.6.2/concepts/visibility", + "7.6.2/concepts/platforms", + "7.6.2/concepts/hermeticity" ] } ] @@ -1716,72 +1719,72 @@ { "group": "Releases", "pages": [ - "7.6.1/release", - "7.6.1/release/rolling", - "7.6.1/release/backward-compatibility", - "7.6.1/release/rule-compatibility" + "7.6.2/release", + "7.6.2/release/rolling", + "7.6.2/release/backward-compatibility", + "7.6.2/release/rule-compatibility" ] }, { "group": "Basics", "pages": [ - "7.6.1/build/style-guide", - "7.6.1/build/share-variables", - "7.6.1/community/recommended-rules", - "7.6.1/run/build" + "7.6.2/build/style-guide", + "7.6.2/build/share-variables", + "7.6.2/community/recommended-rules", + "7.6.2/run/build" ] }, { "group": "Advanced", "pages": [ - "7.6.1/configure/attributes", - "7.6.1/configure/integrate-cpp", - "7.6.1/configure/coverage", - "7.6.1/configure/best-practices", - "7.6.1/configure/windows", - "7.6.1/advanced/performance/build-performance-metrics", - "7.6.1/advanced/performance/build-performance-breakdown", - "7.6.1/advanced/performance/json-trace-profile", - "7.6.1/advanced/performance/memory", - "7.6.1/advanced/performance/iteration-speed" + "7.6.2/configure/attributes", + "7.6.2/configure/integrate-cpp", + "7.6.2/configure/coverage", + "7.6.2/configure/best-practices", + "7.6.2/configure/windows", + "7.6.2/advanced/performance/build-performance-metrics", + "7.6.2/advanced/performance/build-performance-breakdown", + "7.6.2/advanced/performance/json-trace-profile", + "7.6.2/advanced/performance/memory", + "7.6.2/advanced/performance/iteration-speed" ] }, { "group": "Remote Execution", "pages": [ - "7.6.1/remote/rbe", - "7.6.1/remote/rules", - "7.6.1/remote/ci", - "7.6.1/remote/dynamic", - "7.6.1/remote/caching", - "7.6.1/remote/sandbox", - "7.6.1/remote/workspace", - "7.6.1/remote/cache-remote", - "7.6.1/remote/cache-local", - "7.6.1/remote/output-directories", - "7.6.1/remote/persistent", - "7.6.1/remote/multiplex", - "7.6.1/remote/creating", - "7.6.1/remote/bep", - "7.6.1/remote/bep-examples", - "7.6.1/remote/bep-glossary" + "7.6.2/remote/rbe", + "7.6.2/remote/rules", + "7.6.2/remote/ci", + "7.6.2/remote/dynamic", + "7.6.2/remote/caching", + "7.6.2/remote/sandbox", + "7.6.2/remote/workspace", + "7.6.2/remote/cache-remote", + "7.6.2/remote/cache-local", + "7.6.2/remote/output-directories", + "7.6.2/remote/persistent", + "7.6.2/remote/multiplex", + "7.6.2/remote/creating", + "7.6.2/remote/bep", + "7.6.2/remote/bep-examples", + "7.6.2/remote/bep-glossary" ] }, { "group": "Tutorials", "pages": [ - "7.6.1/tutorials/cpp-use-cases", - "7.6.1/tutorials/ccp-toolchain-config", - "7.6.1/tutorials/cpp-dependency", - "7.6.1/tutorials/cpp-labels" + "7.6.2/tutorials/cpp-use-cases", + "7.6.2/tutorials/ccp-toolchain-config", + "7.6.2/tutorials/cpp-dependency", + "7.6.2/tutorials/cpp-labels" ] }, { "group": "Migrate", "pages": [ - "7.6.1/migrate", - "7.6.1/migrate/maven", - "7.6.1/migrate/xcode" + "7.6.2/migrate", + "7.6.2/migrate/maven", + "7.6.2/migrate/xcode" ] } ] @@ -1792,34 +1795,34 @@ { "group": "Build encyclopedia", "pages": [ - "7.6.1/reference/be/overview", - "7.6.1/reference/be/common-definitions", - "7.6.1/reference/be/make-variables", - "7.6.1/reference/be/functions" + "7.6.2/reference/be/overview", + "7.6.2/reference/be/common-definitions", + "7.6.2/reference/be/make-variables", + "7.6.2/reference/be/functions" ] }, { "group": "Command line reference", "pages": [ - "7.6.1/reference/command-line-reference" + "7.6.2/reference/command-line-reference" ] }, { "group": "Query Language", "pages": [ - "7.6.1/query/language" + "7.6.2/query/language" ] }, { "group": "Glossary", "pages": [ - "7.6.1/reference/glossary" + "7.6.2/reference/glossary" ] }, { "group": "Flag cheatsheet", "pages": [ - "7.6.1/reference/flag-cheatsheet" + "7.6.2/reference/flag-cheatsheet" ] } ] @@ -1830,35 +1833,35 @@ { "group": "Concepts", "pages": [ - "7.6.1/extending/concepts" + "7.6.2/extending/concepts" ] }, { "group": "Writing rules", "pages": [ - "7.6.1/rules/rules-tutorial", - "7.6.1/rules/macro-tutorial", - "7.6.1/rules/legacy-macro-tutorial", - "7.6.1/rules/verbs-tutorial", - "7.6.1/rules/language", - "7.6.1/rules/bzl-style", - "7.6.1/rules/challenges", - "7.6.1/rules/windows" + "7.6.2/rules/rules-tutorial", + "7.6.2/rules/macro-tutorial", + "7.6.2/rules/legacy-macro-tutorial", + "7.6.2/rules/verbs-tutorial", + "7.6.2/rules/language", + "7.6.2/rules/bzl-style", + "7.6.2/rules/challenges", + "7.6.2/rules/windows" ] }, { "group": "Distributing rules", "pages": [ - "7.6.1/rules/testing", - "7.6.1/rules/performance", - "7.6.1/rules/deploying" + "7.6.2/rules/testing", + "7.6.2/rules/performance", + "7.6.2/rules/deploying" ] }, { "group": "APIs", "pages": [ - "7.6.1/rules/lib/overview", - "7.6.1/rules/lib/globals" + "7.6.2/rules/lib/overview", + "7.6.2/rules/lib/globals" ] } ] @@ -1869,36 +1872,36 @@ { "group": "Contributing", "pages": [ - "7.6.1/contribute", - "7.6.1/contribute/policy", - "7.6.1/contribute/patch-acceptance", - "7.6.1/contribute/maintainers-guide", - "7.6.1/contribute/codebase", - "7.6.1/contribute/search", - "7.6.1/contribute/statemachine-guide", - "7.6.1/contribute/docs", - "7.6.1/contribute/docs-style-guide", - "7.6.1/contribute/design-documents", - "7.6.1/contribute/release-notes" + "7.6.2/contribute", + "7.6.2/contribute/policy", + "7.6.2/contribute/patch-acceptance", + "7.6.2/contribute/maintainers-guide", + "7.6.2/contribute/codebase", + "7.6.2/contribute/search", + "7.6.2/contribute/statemachine-guide", + "7.6.2/contribute/docs", + "7.6.2/contribute/docs-style-guide", + "7.6.2/contribute/design-documents", + "7.6.2/contribute/release-notes" ] }, { "group": "Programs", "pages": [ - "7.6.1/community/update", - "7.6.1/community/sig", - "7.6.1/community/experts", - "7.6.1/community/partners", - "7.6.1/community/users", - "7.6.1/community/recommended-rules", - "7.6.1/community/remote-execution-services" + "7.6.2/community/update", + "7.6.2/community/sig", + "7.6.2/community/experts", + "7.6.2/community/partners", + "7.6.2/community/users", + "7.6.2/community/recommended-rules", + "7.6.2/community/remote-execution-services" ] }, { "group": "Getting help", "pages": [ - "7.6.1/help", - "7.6.1/contribute/policy" + "7.6.2/help", + "7.6.2/contribute/policy" ] } ] diff --git a/html2md_converter/main.go b/html2md_converter/main.go index 7245367..be47dd1 100644 --- a/html2md_converter/main.go +++ b/html2md_converter/main.go @@ -63,11 +63,6 @@ func processZipFile(f *zip.File, outputDir string, converter *md.Converter) erro return copyMarkdownFile(f, outputDir) } - // Handle YAML/YML files - copy them as-is - if isYAMLFile(f.Name) { - return copyYAMLFile(f, outputDir) - } - // Only process HTML files if !isHTMLFile(f.Name) { fmt.Printf("Skipping file: %s\n", f.Name) diff --git a/html_mdx_converter_test.sh b/html_mdx_converter_test.sh index fb668f7..bab286d 100755 --- a/html_mdx_converter_test.sh +++ b/html_mdx_converter_test.sh @@ -84,97 +84,5 @@ else fi # Run AWK transformation -echo -e "\n${BLUE}=== Running AWK transformation (MD -> MDX) ===${NC}" - -if [ ! -f "transform-docs.awk" ]; then - echo -e "${RED}Error: transform-docs.awk not found in current directory${NC}" - echo "Skipping AWK transformation step" -else - echo "Transforming to root-level reference/ and rules/ directories..." - echo "(This matches the GitHub workflow output structure)" - echo "" - - # Clean up any existing output directories - rm -rf reference rules - - echo "Transforming reference/ directory..." - find "$OUTPUT_DIR/reference" -name "*.md" -type f 2>/dev/null | while read -r file; do - # Extract path relative to reference-docs-temp/ - rel_path="${file#$OUTPUT_DIR/}" - output_file="$rel_path" - output_file="${output_file%.md}.mdx" - - # Create directory structure - mkdir -p "$(dirname "$output_file")" - - # Transform file - awk -f transform-docs.awk "$file" > "$output_file" - echo " ✓ $rel_path -> $output_file" - done - - # Copy YAML files from reference/ - find "$OUTPUT_DIR/reference" -name "*.yaml" -type f 2>/dev/null | while read -r file; do - rel_path="${file#$OUTPUT_DIR/}" - output_file="$rel_path" - mkdir -p "$(dirname "$output_file")" - cp "$file" "$output_file" - echo " ✓ Copied $rel_path" - done - - echo "" - echo "Transforming rules/ directory..." - find "$OUTPUT_DIR/rules" -name "*.md" -type f 2>/dev/null | while read -r file; do - # Extract path relative to reference-docs-temp/ - rel_path="${file#$OUTPUT_DIR/}" - output_file="$rel_path" - output_file="${output_file%.md}.mdx" - - mkdir -p "$(dirname "$output_file")" - awk -f transform-docs.awk "$file" > "$output_file" - echo " ✓ $rel_path -> $output_file" - done - - # Copy YAML files from rules/ - find "$OUTPUT_DIR/rules" -name "*.yaml" -type f 2>/dev/null | while read -r file; do - rel_path="${file#$OUTPUT_DIR/}" - output_file="$rel_path" - mkdir -p "$(dirname "$output_file")" - cp "$file" "$output_file" - echo " ✓ Copied $rel_path" - done - - echo -e "\n${GREEN}✓${NC} AWK transformation complete!" - - # Show MDX output - echo -e "\n${BLUE}=== MDX Output Directories (Root Level) ===${NC}" - echo "Output directories:" - echo " - reference/" - echo " - rules/" - echo "" - echo "Directory structure:" - echo "" - echo "reference/:" - tree -L 3 reference 2>/dev/null || find reference -type f | head -20 - echo "" - echo "rules/:" - tree -L 3 rules 2>/dev/null || find rules -type f | head -20 - - echo -e "\n${BLUE}=== Sample MDX file (after AWK) ===${NC}" - SAMPLE_MDX=$(find reference -name "*.mdx" -type f 2>/dev/null | head -1) - if [ -z "$SAMPLE_MDX" ]; then - SAMPLE_MDX=$(find rules -name "*.mdx" -type f 2>/dev/null | head -1) - fi - if [ -n "$SAMPLE_MDX" ]; then - echo "File: $SAMPLE_MDX" - echo "---" - head -40 "$SAMPLE_MDX" - echo "..." - fi -fi - -echo -e "\n${GREEN}✓${NC} Test complete!" -echo -e "\nOutput directories:" -echo " - Markdown (HTML->MD): $OUTPUT_DIR" -if [ -d "reference" ] && [ -d "rules" ]; then - echo " - MDX (MD->MDX): reference/ and rules/ (at repo root)" -fi \ No newline at end of file +./copy-upstream-docs.sh +rm -rf "$OUTPUT_DIR" \ No newline at end of file diff --git a/install/ide.mdx b/install/ide.mdx index 4988feb..aa6210b 100644 --- a/install/ide.mdx +++ b/install/ide.mdx @@ -64,7 +64,8 @@ Features: through code, inspect variables, and so on) Find [the plugin on the Visual Studio -marketplace](https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel). +marketplace](https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel) +or the [OpenVSX marketplace](https://open-vsx.org/extension/BazelBuild/vscode-bazel). The plugin is [open source](https://github.com/bazelbuild/vscode-bazel). See also: [Autocomplete for Source Code](#autocomplete-for-source-code) diff --git a/process-reference-docs.sh b/process-reference-docs.sh deleted file mode 100755 index 4550598..0000000 --- a/process-reference-docs.sh +++ /dev/null @@ -1,155 +0,0 @@ -#!/bin/bash - -# Script to process Bazel reference documentation from reference-docs.zip -# Usage: ./process-reference-docs.sh <path-to-reference-docs.zip> -# Requirements: pandoc must be installed (brew install pandoc or apt-get install pandoc) - -set -o errexit -o nounset -o pipefail - -if [ $# -ne 1 ]; then - echo "Usage: $0 <path-to-reference-docs.zip>" - exit 1 -fi - -ZIP_FILE="$1" - -if [ ! -f "$ZIP_FILE" ]; then - echo "Error: File '$ZIP_FILE' not found" - exit 1 -fi - -# Check if pandoc is installed -if ! command -v pandoc &> /dev/null; then - echo "Error: pandoc is not installed" - echo "Please install it first:" - echo " - macOS: brew install pandoc" - echo " - Ubuntu/Debian: sudo apt-get install pandoc" - echo " - Other: https://pandoc.org/installing.html" - exit 1 -fi - -echo "Processing reference documentation from $ZIP_FILE..." - -# Create temporary directory for extraction -TEMP_DIR=$(mktemp -d) -trap "rm -rf $TEMP_DIR" EXIT - -# Extract the zip file -echo "Extracting reference-docs.zip..." -unzip -q "$ZIP_FILE" -d "$TEMP_DIR" - -# Check for nested zip files -nested_zips=$(find "$TEMP_DIR" -maxdepth 1 -name "*.zip" -type f) - -if [ -n "$nested_zips" ]; then - echo "" - echo "Error: The zip file contains another zip file inside it:" - for nested_zip in $nested_zips; do - echo " - $(basename "$nested_zip")" - done - echo "" - echo "Please extract the contents properly before running this script." - echo "The zip should contain the documentation files directly, not another zip." - exit 1 -fi - -# Function to convert HTML to MDX using pandoc -html_to_mdx() { - local input_file="$1" - local output_file="$2" - - # Extract title from HTML - local title=$(grep -oP '<title>\K[^<]+' "$input_file" 2>/dev/null || echo "$(basename "${input_file%.html}")") - title=$(echo "$title" | sed "s/'/'\\\''/g") - - # Create temporary markdown file - local temp_md=$(mktemp) - - # Convert HTML to Markdown using pandoc - # Options: - # -f html: input format is HTML - # -t gfm: output format is GitHub Flavored Markdown - # --wrap=preserve: preserve line wrapping - # --extract-media=.: extract images to current directory (if any) - pandoc -f html -t gfm --wrap=preserve "$input_file" -o "$temp_md" 2>/dev/null || { - echo "Warning: pandoc conversion failed for $(basename "$input_file"), using fallback" - # Fallback: just copy the HTML content - cat "$input_file" > "$temp_md" - } - - # Write MDX file with frontmatter - { - echo "---" - echo "title: '$title'" - echo "---" - echo "" - cat "$temp_md" - } > "$output_file" - - rm "$temp_md" -} - -# Process reference/be/ HTML files and convert to MDX -echo "Processing Build Encyclopedia (reference/be/) files..." -if [ -d "$TEMP_DIR/reference/be" ]; then - mkdir -p reference/be - - # Convert HTML files to MDX - for html_file in "$TEMP_DIR/reference/be"/*.html; do - if [ -f "$html_file" ]; then - basename_file=$(basename "$html_file") - mdx_file="reference/be/${basename_file%.html}.mdx" - - echo " Converting $(basename "$html_file") to MDX..." - html_to_mdx "$html_file" "$mdx_file" - echo " Created $mdx_file" - fi - done -else - echo "Warning: No reference/be/ directory found in zip" -fi - -# Process command-line reference -echo "Processing command-line reference..." -if [ -f "$TEMP_DIR/reference/command-line-reference.html" ]; then - mkdir -p reference - - echo " Converting command-line-reference.html to MDX..." - html_to_mdx "$TEMP_DIR/reference/command-line-reference.html" "reference/command-line-reference.mdx" - echo " Created reference/command-line-reference.mdx" -else - echo "Warning: command-line-reference.html not found in zip" -fi - -# Process Starlark library docs -echo "Processing Starlark library documentation..." -if [ -d "$TEMP_DIR/rules/lib" ]; then - mkdir -p rules/lib - - # Convert HTML files to MDX - file_count=0 - find "$TEMP_DIR/rules/lib" -name "*.html" -type f | while read -r html_file; do - relative_path="${html_file#$TEMP_DIR/rules/lib/}" - mdx_file="rules/lib/${relative_path%.html}.mdx" - - # Create directory structure - mkdir -p "$(dirname "$mdx_file")" - - html_to_mdx "$html_file" "$mdx_file" - file_count=$((file_count + 1)) - done - - echo " Converted Starlark library documentation" -else - echo "Warning: No rules/lib/ directory found in zip" -fi - -echo "" -echo "Reference documentation processing complete!" -echo "" -echo "Summary:" -echo " - Build Encyclopedia: reference/be/*.mdx" -echo " - Command-Line Reference: reference/command-line-reference.mdx" -echo " - Starlark Library: rules/lib/**/*.mdx" -echo "" -echo "All files have been converted from HTML to Markdown format." \ No newline at end of file diff --git a/reference/be/overview.mdx b/reference/be/overview.mdx index f4aadf5..b57c03a 100644 --- a/reference/be/overview.mdx +++ b/reference/be/overview.mdx @@ -2,6 +2,8 @@ title: 'Bazel BUILD Encyclopedia of Functions' --- + + ## Concepts and terminology - [Common definitions](/reference/be/common-definitions) - [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization) diff --git a/reference/glossary.mdx b/reference/glossary.mdx new file mode 100644 index 0000000..e526000 --- /dev/null +++ b/reference/glossary.mdx @@ -0,0 +1,715 @@ +--- +title: 'Bazel Glossary' +--- + + + +### Action + +A command to run during the build, for example, a call to a compiler that takes +[artifacts](#artifact) as inputs and produces other artifacts as outputs. +Includes metadata like the command line arguments, action key, environment +variables, and declared input/output artifacts. + +**See also:** [Rules documentation](/extending/rules#actions) + +### Action cache + +An on-disk cache that stores a mapping of executed [actions](#action) to the +outputs they created. The cache key is known as the [action key](#action-key). A +core component for Bazel's incrementality model. The cache is stored in the +output base directory and thus survives Bazel server restarts. + +### Action graph + +An in-memory graph of [actions](#action) and the [artifacts](#artifact) that +these actions read and generate. The graph might include artifacts that exist as +source files (for example, in the file system) as well as generated +intermediate/final artifacts that are not mentioned in `BUILD` files. Produced +during the [analysis phase](#analysis-phase) and used during the [execution +phase](#execution-phase). + +### Action graph query (aquery) + +A [query](#query-concept) tool that can query over build [actions](#action). +This provides the ability to analyze how [build rules](#rule) translate into the +actual work builds do. + +### Action key + +The cache key of an [action](#action). Computed based on action metadata, which +might include the command to be executed in the action, compiler flags, library +locations, or system headers, depending on the action. Enables Bazel to cache or +invalidate individual actions deterministically. + +### Analysis phase + +The second phase of a build. Processes the [target graph](#target-graph) +specified in [`BUILD` files](#build-file) to produce an in-memory [action +graph](#action-graph) that determines the order of actions to run during the +[execution phase](#execution-phase). This is the phase in which rule +implementations are evaluated. + +### Artifact + +A source file or a generated file. Can also be a directory of files, known as +[tree artifacts](#tree-artifact). + +An artifact may be an input to multiple actions, but must only be generated by +at most one action. + +An artifact that corresponds to a [file target](#target) can be addressed by a +label. + +### Aspect + +A mechanism for rules to create additional [actions](#action) in their +dependencies. For example, if target A depends on B, one can apply an aspect on +A that traverses *up* a dependency edge to B, and runs additional actions in B +to generate and collect additional output files. These additional actions are +cached and reused between targets requiring the same aspect. Created with the +`aspect()` Starlark Build API function. Can be used, for example, to generate +metadata for IDEs, and create actions for linting. + +**See also:** [Aspects documentation](/extending/aspects) + +### Aspect-on-aspect + +A composition mechanism whereby aspects can be applied to the results +of other aspects. For example, an aspect that generates information for use by +IDEs can be applied on top of an aspect that generates `.java` files from a +proto. + +For an aspect `A` to apply on top of aspect `B`, the [providers](#provider) that +`B` advertises in its [`provides`](/rules/lib/globals#aspect.provides) attribute +must match what `A` declares it wants in its [`required_aspect_providers`](/rules/lib/globals#aspect.required_aspect_providers) +attribute. + +### Attribute + +A parameter to a [rule](#rule), used to express per-target build information. +Examples include `srcs`, `deps`, and `copts`, which respectively declare a +target's source files, dependencies, and custom compiler options. The particular +attributes available for a given target depend on its rule type. + +### .bazelrc + +Bazel’s configuration file used to change the default values for [startup +flags](#startup-flags) and [command flags](#command-flags), and to define common +groups of options that can then be set together on the Bazel command line using +a `--config` flag. Bazel can combine settings from multiple bazelrc files +(systemwide, per-workspace, per-user, or from a custom location), and a +`bazelrc` file may also import settings from other `bazelrc` files. + +### Blaze + +The Google-internal version of Bazel. Google’s main build system for its +mono-repository. + +### BUILD File + +A `BUILD` file is the main configuration file that tells Bazel what software +outputs to build, what their dependencies are, and how to build them. Bazel +takes a `BUILD` file as input and uses the file to create a graph of dependencies +and to derive the actions that must be completed to build intermediate and final +software outputs. A `BUILD` file marks a directory and any sub-directories not +containing a `BUILD` file as a [package](#package), and can contain +[targets](#target) created by [rules](#rule). The file can also be named +`BUILD.bazel`. + +### BUILD.bazel File + +See [`BUILD` File](#build-file). Takes precedence over a `BUILD` file in the same +directory. + +### .bzl File + +A file that defines rules, [macros](#macro), and constants written in +[Starlark](#starlark). These can then be imported into [`BUILD` +files](#build-file) using the `load()` function. + +// TODO: ### Build event protocol + +// TODO: ### Build flag + +### Build graph + +The dependency graph that Bazel constructs and traverses to perform a build. +Includes nodes like [targets](#target), [configured +targets](#configured-target), [actions](#action), and [artifacts](#artifact). A +build is considered complete when all [artifacts](#artifact) on which a set of +requested targets depend are verified as up-to-date. + +### Build setting + +A Starlark-defined piece of [configuration](#configuration). +[Transitions](#transition) can set build settings to change a subgraph's +configuration. If exposed to the user as a [command-line flag](#command-flags), +also known as a build flag. + +### Clean build + +A build that doesn't use the results of earlier builds. This is generally slower +than an [incremental build](#incremental-build) but commonly considered to be +more [correct](#correctness). Bazel guarantees both clean and incremental builds +are always correct. + +### Client-server model + +The `bazel` command-line client automatically starts a background server on the +local machine to execute Bazel [commands](#command). The server persists across +commands but automatically stops after a period of inactivity (or explicitly via +bazel shutdown). Splitting Bazel into a server and client helps amortize JVM +startup time and supports faster [incremental builds](#incremental-build) +because the [action graph](#action-graph) remains in memory across commands. + +### Command + +Used on the command line to invoke different Bazel functions, like `bazel +build`, `bazel test`, `bazel run`, and `bazel query`. + +### Command flags + +A set of flags specific to a [command](#command). Command flags are specified +*after* the command (`bazel build <command flags>`). Flags can be applicable to +one or more commands. For example, `--configure` is a flag exclusively for the +`bazel sync` command, but `--keep_going` is applicable to `sync`, `build`, +`test` and more. Flags are often used for [configuration](#configuration) +purposes, so changes in flag values can cause Bazel to invalidate in-memory +graphs and restart the [analysis phase](#analysis-phase). + +### Configuration + +Information outside of [rule](#rule) definitions that impacts how rules generate +[actions](#action). Every build has at least one configuration specifying the +target platform, action environment variables, and command-line [build +flags](#command-flags). [Transitions](#transition) may create additional +configurations, such as for host tools or cross-compilation. + +**See also:** [Configurations](/extending/rules#configurations) + +// TODO: ### Configuration fragment + +### Configuration trimming + +The process of only including the pieces of [configuration](#configuration) a +target actually needs. For example, if you build Java binary `//:j` with C++ +dependency `//:c`, it's wasteful to include the value of `--javacopt` in the +configuration of `//:c` because changing `--javacopt` unnecessarily breaks C++ +build cacheability. + +### Configured query (cquery) + +A [query](#query-concept) tool that queries over [configured +targets](#configured-target) (after the [analysis phase](#analysis-phase) +completes). This means `select()` and [build flags](#command-flags) (such as +`--platforms`) are accurately reflected in the results. + +**See also:** [cquery documentation](/query/cquery) + +### Configured target + +The result of evaluating a [target](#target) with a +[configuration](#configuration). The [analysis phase](#analysis-phase) produces +this by combining the build's options with the targets that need to be built. +For example, if `//:foo` builds for two different architectures in the same +build, it has two configured targets: `<//:foo, x86>` and `<//:foo, arm>`. + +### Correctness + +A build is correct when its output faithfully reflects the state of its +transitive inputs. To achieve correct builds, Bazel strives to be +[hermetic](#hermeticity), reproducible, and making [build +analysis](#analysis-phase) and [action execution](#execution-phase) +deterministic. + +### Dependency + +A directed edge between two [targets](#target). A target `//:foo` has a *target +dependency* on target `//:bar` if `//:foo`'s attribute values contain a +reference to `//:bar`. `//:foo` has an *action dependency* on `//:bar` if an +action in `//:foo` depends on an input [artifact](#artifact) created by an +action in `//:bar`. + +In certain contexts, it could also refer to an _external dependency_; see +[modules](#module). + +### Depset + +A data structure for collecting data on transitive dependencies. Optimized so +that merging depsets is time and space efficient, because it’s common to have +very large depsets (hundreds of thousands of files). Implemented to +recursively refer to other depsets for space efficiency reasons. [Rule](#rule) +implementations should not "flatten" depsets by converting them to lists unless +the rule is at the top level of the build graph. Flattening large depsets incurs +huge memory consumption. Also known as *nested sets* in Bazel's internal +implementation. + +**See also:** [Depset documentation](/extending/depsets) + +### Disk cache + +A local on-disk blob store for the remote caching feature. Can be used in +conjunction with an actual remote blob store. + +### Distdir + +A read-only directory containing files that Bazel would otherwise fetch from the +internet using repository rules. Enables builds to run fully offline. + +### Dynamic execution + +An execution strategy that selects between local and remote execution based on +various heuristics, and uses the execution results of the faster successful +method. Certain [actions](#action) are executed faster locally (for example, +linking) and others are faster remotely (for example, highly parallelizable +compilation). A dynamic execution strategy can provide the best possible +incremental and clean build times. + +### Execution phase + +The third phase of a build. Executes the [actions](#action) in the [action +graph](#action-graph) created during the [analysis phase](#analysis-phase). +These actions invoke executables (compilers, scripts) to read and write +[artifacts](#artifact). *Spawn strategies* control how these actions are +executed: locally, remotely, dynamically, sandboxed, docker, and so on. + +### Execution root + +A directory in the [workspace](#workspace)’s [output base](#output-base) +directory where local [actions](#action) are executed in +non-[sandboxed](#sandboxing) builds. The directory contents are mostly symlinks +of input [artifacts](#artifact) from the workspace. The execution root also +contains symlinks to external repositories as other inputs and the `bazel-out` +directory to store outputs. Prepared during the [loading phase](#loading-phase) +by creating a *symlink forest* of the directories that represent the transitive +closure of packages on which a build depends. Accessible with `bazel info +execution_root` on the command line. + +### File + +See [Artifact](#artifact). + +### Hermeticity + +A build is hermetic if there are no external influences on its build and test +operations, which helps to make sure that results are deterministic and +[correct](#correctness). For example, hermetic builds typically disallow network +access to actions, restrict access to declared inputs, use fixed timestamps and +timezones, restrict access to environment variables, and use fixed seeds for +random number generators + +### Incremental build + +An incremental build reuses the results of earlier builds to reduce build time +and resource usage. Dependency checking and caching aim to produce correct +results for this type of build. An incremental build is the opposite of a clean +build. + +// TODO: ### Install base + +### Label + +An identifier for a [target](#target). Generally has the form +`@repo//path/to/package:target`, where `repo` is the (apparent) name of the +[repository](#repository) containing the target, `path/to/package` is the path +to the directory that contains the [`BUILD` file](#build-file) declaring the +target (this directory is also known as the [package](#package)), and `target` +is the name of the target itself. Depending on the situation, parts of this +syntax may be omitted. + +**See also**: [Labels](/concepts/labels) + +### Loading phase + +The first phase of a build where Bazel executes [`BUILD` files](#build-file) to +create [packages](#package). [Macros](#macro) and certain functions like +`glob()` are evaluated in this phase. Interleaved with the second phase of the +build, the [analysis phase](#analysis-phase), to build up a [target +graph](#target-graph). + +### Legacy macro + +A flavor of [macro](#macro) which is declared as an ordinary +[Starlark](#starlark) function, and which runs as a side effect of executing a +`BUILD` file. + +Legacy macros can do anything a function can. This means they can be convenient, +but they can also be harder to read, write, and use. A legacy macro might +unexpectedly mutate its arguments or fail when given a `select()` or ill-typed +argument. + +Contrast with [symbolic macros](#symbolic-macro). + +**See also:** [Legacy macro documentation](/extending/legacy-macros) + +### Macro + +A mechanism to compose multiple [rule](#rule) target declarations together under +a single [Starlark](#starlark) callable. Enables reusing common rule declaration +patterns across `BUILD` files. Expanded to the underlying rule target +declarations during the [loading phase](#loading-phase). + +Comes in two flavors: [symbolic macros](#symbolic-macro) (since Bazel 8) and +[legacy macros](#legacy-macro). + +### Mnemonic + +A short, human-readable string selected by a rule author to quickly understand +what an [action](#action) in the rule is doing. Mnemonics can be used as +identifiers for *spawn strategy* selections. Some examples of action mnemonics +are `Javac` from Java rules, `CppCompile` from C++ rules, and +`AndroidManifestMerger` from Android rules. + +### Module + +A Bazel project that can have multiple versions, each of which can have +dependencies on other modules. This is analogous to familiar concepts in other +dependency management systems, such as a Maven _artifact_, an npm _package_, a +Go _module_, or a Cargo _crate_. Modules form the backbone of Bazel's external +dependency management system. + +Each module is backed by a [repo](#repository) with a `MODULE.bazel` file at its +root. This file contains metadata about the module itself (such as its name and +version), its direct dependencies, and various other data including toolchain +registrations and [module extension](#module-extension) input. + +Module metadata is hosted in Bazel registries. + +**See also:** [Bazel modules](/external/module) + +### Module Extension + +A piece of logic that can be run to generate [repos](#repository) by reading +inputs from across the [module](#module) dependency graph and invoking [repo +rules](#repository-rule). Module extensions have capabilities similar to repo +rules, allowing them to access the internet, perform file I/O, and so on. + +**See also:** [Module extensions](/external/extension) + +### Native rules + +[Rules](#rule) that are built into Bazel and implemented in Java. Such rules +appear in [`.bzl` files](#bzl-file) as functions in the native module (for +example, `native.cc_library` or `native.java_library`). User-defined rules +(non-native) are created using [Starlark](#starlark). + +### Output base + +A [workspace](#workspace)-specific directory to store Bazel output files. Used +to separate outputs from the *workspace*'s source tree (the [main +repo](#repository)). Located in the [output user root](#output-user-root). + +### Output groups + +A group of files that is expected to be built when Bazel finishes building a +target. [Rules](#rule) put their usual outputs in the "default output group" +(e.g the `.jar` file of a `java_library`, `.a` and `.so` for `cc_library` +targets). The default output group is the output group whose +[artifacts](#artifact) are built when a target is requested on the command line. +Rules can define more named output groups that can be explicitly specified in +[`BUILD` files](#build-file) (`filegroup` rule) or the command line +(`--output_groups` flag). + +### Output user root + +A user-specific directory to store Bazel's outputs. The directory name is +derived from the user's system username. Prevents output file collisions if +multiple users are building the same project on the system at the same time. +Contains subdirectories corresponding to build outputs of individual workspaces, +also known as [output bases](#output-base). + +### Package + +The set of [targets](#target) defined by a [`BUILD` file](#build-file). A +package's name is the `BUILD` file's path relative to the [repo](#repository) +root. A package can contain subpackages, or subdirectories containing `BUILD` +files, thus forming a package hierarchy. + +### Package group + +A [target](#target) representing a set of packages. Often used in `visibility` +attribute values. + +### Platform + +A "machine type" involved in a build. This includes the machine Bazel runs on +(the "host" platform), the machines build tools execute on ("exec" platforms), +and the machines targets are built for ("target platforms"). + +### Provider + +A schema describing a unit of information to pass between +[rule targets](#rule-target) along dependency relationships. Typically this +contains information like compiler options, transitive source or output files, +and build metadata. Frequently used in conjunction with [depsets](#depset) to +efficiently store accumulated transitive data. An example of a built-in provider +is `DefaultInfo`. + +Note: The object holding specific data for a given rule target is +referred to as a "provider instance", although sometimes this is conflated with +"provider". + +**See also:** [Provider documentation](/extending/rules#providers) + +### Query (concept) + +The process of analyzing a [build graph](#build-graph) to understand +[target](#target) properties and dependency structures. Bazel supports three +query variants: [query](#query-command), [cquery](#configured-query), and +[aquery](#action-graph-query). + +### query (command) + +A [query](#query-concept) tool that operates over the build's post-[loading +phase](#loading-phase) [target graph](#target-graph). This is relatively fast, +but can't analyze the effects of `select()`, [build flags](#command-flags), +[artifacts](#artifact), or build [actions](#action). + +**See also:** [Query how-to](/query/guide), [Query reference](/query/language) + +### Repository + +A directory tree with a boundary marker file at its root, containing source +files that can be used in a Bazel build. Often shortened to just **repo**. + +A repo boundary marker file can be `MODULE.bazel` (signaling that this repo +represents a Bazel module), `REPO.bazel`, or in legacy contexts, `WORKSPACE` or +`WORKSPACE.bazel`. Any repo boundary marker file will signify the boundary of a +repo; multiple such files can coexist in a directory. + +The *main repo* is the repo in which the current Bazel command is being run. + +*External repos* are defined by specifying [modules](#module) in `MODULE.bazel` +files, or invoking [repo rules](#repository-rule) in [module +extensions](#module-extension). They can be fetched on demand to a predetermined +"magical" location on disk. + +Each repo has a unique, constant *canonical* name, and potentially different +*apparent* names when viewed from other repos. + +**See also**: [External dependencies overview](/external/overview) + +### Repository cache + +A shared content-addressable cache of files downloaded by Bazel for builds, +shareable across [workspaces](#workspace). Enables offline builds after the +initial download. Commonly used to cache files downloaded through [repository +rules](#repository-rule) like `http_archive` and repository rule APIs like +`repository_ctx.download`. Files are cached only if their SHA-256 checksums are +specified for the download. + +### Repository rule + +A schema for repository definitions that tells Bazel how to materialize (or +"fetch") a [repository](#repository). Often shortened to just **repo rule**. +Repo rules are invoked by Bazel internally to define repos backed by +[modules](#module), or can be invoked by [module extensions](#module-extension). +Repo rules can access the internet or perform file I/O; the most common repo +rule is `http_archive` to download an archive containing source files from the +internet. + +**See also:** [Repo rule documentation](/external/repo) + +### Reproducibility + +The property of a build or test that a set of inputs to the build or test will +always produce the same set of outputs every time, regardless of time, method, +or environment. Note that this does not necessarily imply that the outputs are +[correct](#correctness) or the desired outputs. + +### Rule + +A schema for defining [rule targets](#rule-target) in a `BUILD` file, such as +`cc_library`. From the perspective of a `BUILD` file author, a rule consists of +a set of [attributes](#attributes) and black box logic. The logic tells the +rule target how to produce output [artifacts](#artifact) and pass information to +other rule targets. From the perspective of `.bzl` authors, rules are the +primary way to extend Bazel to support new programming languages and +environments. + +Rules are instantiated to produce rule targets in the +[loading phase](#loading-phase). In the [analysis phase](#analysis-phase) rule +targets communicate information to their downstream dependencies in the form of +[providers](#provider), and register [actions](#action) describing how to +generate their output artifacts. These actions are run in the [execution +phase](#execution-phase). + +Note: Historically the term "rule" has been used to refer to a rule target. +This usage was inherited from tools like Make, but causes confusion and should +be avoided for Bazel. + +**See also:** [Rules documentation](/extending/rules) + +### Rule target + +A [target](#target) that is an instance of a rule. Contrasts with file targets +and package groups. Not to be confused with [rule](#rule). + +### Runfiles + +The runtime dependencies of an executable [target](#target). Most commonly, the +executable is the executable output of a test rule, and the runfiles are runtime +data dependencies of the test. Before the invocation of the executable (during +bazel test), Bazel prepares the tree of runfiles alongside the test executable +according to their source directory structure. + +**See also:** [Runfiles documentation](/extending/rules#runfiles) + +### Sandboxing + +A technique to isolate a running [action](#action) inside a restricted and +temporary [execution root](#execution-root), helping to ensure that it doesn’t +read undeclared inputs or write undeclared outputs. Sandboxing greatly improves +[hermeticity](#hermeticity), but usually has a performance cost, and requires +support from the operating system. The performance cost depends on the platform. +On Linux, it's not significant, but on macOS it can make sandboxing unusable. + +### Skyframe + +[Skyframe](/reference/skyframe) is the core parallel, functional, and incremental evaluation framework of Bazel. + +// TODO: ### Spawn strategy + +### Stamping + +A feature to embed additional information into Bazel-built +[artifacts](#artifact). For example, this can be used for source control, build +time and other workspace or environment-related information for release builds. +Enable through the `--workspace_status_command` flag and [rules](/extending/rules) that +support the stamp attribute. + +### Starlark + +The extension language for writing [rules](/extending/rules) and [macros](#macro). A +restricted subset of Python (syntactically and grammatically) aimed for the +purpose of configuration, and for better performance. Uses the [`.bzl` +file](#bzl-file) extension. [`BUILD` files](#build-file) use an even more +restricted version of Starlark (such as no `def` function definitions), formerly +known as Skylark. + +**See also:** [Starlark language documentation](/rules/language) + +// TODO: ### Starlark rules + +// TODO: ### Starlark rule sandwich + +### Startup flags + +The set of flags specified between `bazel` and the [command](#query-command), +for example, bazel `--host_jvm_debug` build. These flags modify the +[configuration](#configuration) of the Bazel server, so any modification to +startup flags causes a server restart. Startup flags are not specific to any +command. + +### Symbolic macro + +A flavor of [macro](#macro) which is declared with a [rule](#rule)-like +[attribute](#attribute) schema, allows hiding internal declared +[targets](#target) from their own package, and enforces a predictable naming +pattern on the targets that the macro declares. Designed to avoid some of the +problems seen in large [legacy macro](#legacy-macro) codebases. + +**See also:** [Symbolic macro documentation](/extending/macros) + +### Target + +An object that is defined in a [`BUILD` file](#build-file) and identified by a +[label](#label). Targets represent the buildable units of a workspace from +the perspective of the end user. + +A target that is declared by instantiating a [rule](#rule) is called a [rule +target](#rule-target). Depending on the rule, these may be runnable (like +`cc_binary`) or testable (like `cc_test`). Rule targets typically depend on +other targets via their [attributes](#attribute) (such as `deps`); these +dependencies form the basis of the [target graph](#target-graph). + +Aside from rule targets, there are also file targets and [package group](#package-group) +targets. File targets correspond to [artifacts](#artifact) that are referenced +within a `BUILD` file. As a special case, the `BUILD` file of any package is +always considered a source file target in that package. + +Targets are discovered during the [loading phase](#loading-phase). During the +[analysis phase](#analysis-phase), targets are associated with [build +configurations](#configuration) to form [configured +targets](#configured-target). + +### Target graph + +An in-memory graph of [targets](#target) and their dependencies. Produced during +the [loading phase](#loading-phase) and used as an input to the [analysis +phase](#analysis-phase). + +### Target pattern + +A way to specify a group of [targets](#target) on the command line. Commonly +used patterns are `:all` (all rule targets), `:*` (all rule + file targets), +`...` (current [package](#package) and all subpackages recursively). Can be used +in combination, for example, `//...:*` means all rule and file targets in all +packages recursively from the root of the [workspace](#workspace). + +### Tests + +Rule [targets](#target) instantiated from test rules, and therefore contains a +test executable. A return code of zero from the completion of the executable +indicates test success. The exact contract between Bazel and tests (such as test +environment variables, test result collection methods) is specified in the [Test +Encyclopedia](/reference/test-encyclopedia). + +### Toolchain + +A set of tools to build outputs for a language. Typically, a toolchain includes +compilers, linkers, interpreters or/and linters. A toolchain can also vary by +platform, that is, a Unix compiler toolchain's components may differ for the +Windows variant, even though the toolchain is for the same language. Selecting +the right toolchain for the platform is known as toolchain resolution. + +### Top-level target + +A build [target](#target) is top-level if it’s requested on the Bazel command +line. For example, if `//:foo` depends on `//:bar`, and `bazel build //:foo` is +called, then for this build, `//:foo` is top-level, and `//:bar` isn’t +top-level, although both targets will need to be built. An important difference +between top-level and non-top-level targets is that [command +flags](#command-flags) set on the Bazel command line (or via +[.bazelrc](#bazelrc)) will set the [configuration](#configuration) for top-level +targets, but might be modified by a [transition](#transition) for non-top-level +targets. + +### Transition + +A mapping of [configuration](#configuration) state from one value to another. +Enables [targets](#target) in the [build graph](#build-graph) to have different +configurations, even if they were instantiated from the same [rule](#rule). A +common usage of transitions is with *split* transitions, where certain parts of +the [target graph](#target-graph) is forked with distinct configurations for +each fork. For example, one can build an Android APK with native binaries +compiled for ARM and x86 using split transitions in a single build. + +**See also:** [User-defined transitions](/extending/config#user-defined-transitions) + +### Tree artifact + +An [artifact](#artifact) that represents a collection of files. Since these +files are not themselves artifacts, an [action](#action) operating on them must +instead register the tree artifact as its input or output. + +### Visibility + +One of two mechanisms for preventing unwanted dependencies in the build system: +*target visibility* for controlling whether a [target](#target) can be depended +upon by other targets; and *load visibility* for controlling whether a `BUILD` +or `.bzl` file may load a given `.bzl` file. Without context, usually +"visibility" refers to target visibility. + +**See also:** [Visibility documentation](/concepts/visibility) + +### Workspace + +The environment shared by all Bazel commands run from the same [main +repository](#repository). + +Note that historically the concepts of "repository" and "workspace" have been +conflated; the term "workspace" has often been used to refer to the main +repository, and sometimes even used as a synonym of "repository". Such usage +should be avoided for clarity. diff --git a/reference/skyframe.mdx b/reference/skyframe.mdx new file mode 100644 index 0000000..ba9149f --- /dev/null +++ b/reference/skyframe.mdx @@ -0,0 +1,198 @@ +--- +title: 'Skyframe' +--- + + + +The parallel evaluation and incrementality model of Bazel. + +## Data model + +The data model consists of the following items: + +* `SkyValue`. Also called nodes. `SkyValues` are immutable objects that + contain all the data built over the course of the build and the inputs of + the build. Examples are: input files, output files, targets and configured + targets. +* `SkyKey`. A short immutable name to reference a `SkyValue`, for example, + `FILECONTENTS:/tmp/foo` or `PACKAGE://foo`. +* `SkyFunction`. Builds nodes based on their keys and dependent nodes. +* Node graph. A data structure containing the dependency relationship between + nodes. +* `Skyframe`. Code name for the incremental evaluation framework Bazel is + based on. + +## Evaluation + +A build is achieved by evaluating the node that represents the build request. + +First, Bazel finds the `SkyFunction` corresponding to the key of the top-level +`SkyKey`. The function then requests the evaluation of the nodes it needs to +evaluate the top-level node, which in turn result in other `SkyFunction` calls, +until the leaf nodes are reached. Leaf nodes are usually ones that represent +input files in the file system. Finally, Bazel ends up with the value of the +top-level `SkyValue`, some side effects (such as output files in the file +system) and a directed acyclic graph of the dependencies between the nodes +involved in the build. + +A `SkyFunction` can request `SkyKeys` in multiple passes if it cannot tell in +advance all of the nodes it needs to do its job. A simple example is evaluating +an input file node that turns out to be a symlink: the function tries to read +the file, realizes that it is a symlink, and thus fetches the file system node +representing the target of the symlink. But that itself can be a symlink, in +which case the original function will need to fetch its target, too. + +The functions are represented in the code by the interface `SkyFunction` and the +services provided to it by an interface called `SkyFunction.Environment`. These +are the things functions can do: + +* Request the evaluation of another node by way of calling `env.getValue`. If + the node is available, its value is returned, otherwise, `null` is returned + and the function itself is expected to return `null`. In the latter case, + the dependent node is evaluated, and then the original node builder is + invoked again, but this time the same `env.getValue` call will return a + non-`null` value. +* Request the evaluation of multiple other nodes by calling `env.getValues()`. + This does essentially the same, except that the dependent nodes are + evaluated in parallel. +* Do computation during their invocation +* Have side effects, for example, writing files to the file system. Care needs + to be taken that two different functions avoid stepping on each other's + toes. In general, write side effects (where data flows outwards from Bazel) + are okay, read side effects (where data flows inwards into Bazel without a + registered dependency) are not, because they are an unregistered dependency + and as such, can cause incorrect incremental builds. + +Well-behaved `SkyFunction` implementations avoid accessing data in any other way +than requesting dependencies (such as by directly reading the file system), +because that results in Bazel not registering the data dependency on the file +that was read, thus resulting in incorrect incremental builds. + +Once a function has enough data to do its job, it should return a non-`null` +value indicating completion. + +This evaluation strategy has a number of benefits: + +* Hermeticity. If functions only request input data by way of depending on + other nodes, Bazel can guarantee that if the input state is the same, the + same data is returned. If all sky functions are deterministic, this means + that the whole build will also be deterministic. +* Correct and perfect incrementality. If all the input data of all functions + is recorded, Bazel can invalidate only the exact set of nodes that need to + be invalidated when the input data changes. +* Parallelism. Since functions can only interact with each other by way of + requesting dependencies, functions that don't depend on each other can be + run in parallel and Bazel can guarantee that the result is the same as if + they were run sequentially. + +## Incrementality + +Since functions can only access input data by depending on other nodes, Bazel +can build up a complete data flow graph from the input files to the output +files, and use this information to only rebuild those nodes that actually need +to be rebuilt: the reverse transitive closure of the set of changed input files. + +In particular, two possible incrementality strategies exist: the bottom-up one +and the top-down one. Which one is optimal depends on how the dependency graph +looks like. + +* During bottom-up invalidation, after a graph is built and the set of changed + inputs is known, all the nodes are invalidated that transitively depend on + changed files. This is optimal if the same top-level node will be built + again. Note that bottom-up invalidation requires running `stat()` on all + input files of the previous build to determine if they were changed. This + can be improved by using `inotify` or a similar mechanism to learn about + changed files. + +* During top-down invalidation, the transitive closure of the top-level node + is checked and only those nodes are kept whose transitive closure is clean. + This is better if the node graph is large, but the next build only needs a + small subset of it: bottom-up invalidation would invalidate the larger graph + of the first build, unlike top-down invalidation, which just walks the small + graph of second build. + +Bazel only does bottom-up invalidation. + +To get further incrementality, Bazel uses _change pruning_: if a node is +invalidated, but upon rebuild, it is discovered that its new value is the same +as its old value, the nodes that were invalidated due to a change in this node +are "resurrected". + +This is useful, for example, if one changes a comment in a C++ file: then the +`.o` file generated from it will be the same, thus, it is unnecessary to call +the linker again. + +## Incremental Linking / Compilation + +The main limitation of this model is that the invalidation of a node is an +all-or-nothing affair: when a dependency changes, the dependent node is always +rebuilt from scratch, even if a better algorithm would exist that would mutate +the old value of the node based on the changes. A few examples where this would +be useful: + +* Incremental linking +* When a single class file changes in a JAR file, it is possible + modify the JAR file in-place instead of building it from scratch again. + +The reason why Bazel does not support these things in a principled way +is twofold: + +* There were limited performance gains. +* Difficulty to validate that the result of the mutation is the same as that + of a clean rebuild would be, and Google values builds that are bit-for-bit + repeatable. + +Until now, it was possible to achieve good enough performance by decomposing an +expensive build step and achieving partial re-evaluation that way. For example, +in an Android app, you can split all the classes into multiple groups and dex +them separately. This way, if classes in a group are unchanged, the dexing does +not have to be redone. + +## Mapping to Bazel concepts + +This is high level summary of the key `SkyFunction` and `SkyValue` +implementations Bazel uses to perform a build: + +* **FileStateValue**. The result of an `lstat()`. For existent files, the + function also computes additional information in order to detect changes to + the file. This is the lowest level node in the Skyframe graph and has no + dependencies. +* **FileValue**. Used by anything that cares about the actual contents or + resolved path of a file. Depends on the corresponding `FileStateValue` and + any symlinks that need to be resolved (such as the `FileValue` for `a/b` + needs the resolved path of `a` and the resolved path of `a/b`). The + distinction between `FileValue` and `FileStateValue` is important because + the latter can be used in cases where the contents of the file are not + actually needed. For example, the file contents are irrelevant when + evaluating file system globs (such as `srcs=glob(["*/*.java"])`). +* **DirectoryListingStateValue**. The result of `readdir()`. Like + `FileStateValue`, this is the lowest level node and has no dependencies. +* **DirectoryListingValue**. Used by anything that cares about the entries of + a directory. Depends on the corresponding `DirectoryListingStateValue`, as + well as the associated `FileValue` of the directory. +* **PackageValue**. Represents the parsed version of a BUILD file. Depends on + the `FileValue` of the associated `BUILD` file, and also transitively on any + `DirectoryListingValue` that is used to resolve the globs in the package + (the data structure representing the contents of a `BUILD` file internally). +* **ConfiguredTargetValue**. Represents a configured target, which is a tuple + of the set of actions generated during the analysis of a target and + information provided to dependent configured targets. Depends on the + `PackageValue` the corresponding target is in, the `ConfiguredTargetValues` + of direct dependencies, and a special node representing the build + configuration. +* **ArtifactValue**. Represents a file in the build, be it a source or an + output artifact. Artifacts are almost equivalent to files, and are used to + refer to files during the actual execution of build steps. Source files + depends on the `FileValue` of the associated node, and output artifacts + depend on the `ActionExecutionValue` of whatever action generates the + artifact. +* **ActionExecutionValue**. Represents the execution of an action. Depends on + the `ArtifactValues` of its input files. The action it executes is contained + within its SkyKey, which is contrary to the concept that SkyKeys should be + small. Note that `ActionExecutionValue` and `ArtifactValue` are unused if + the execution phase does not run. + +As a visual aid, this diagram shows the relationships between +SkyFunction implementations after a build of Bazel itself: + +![A graph of SkyFunction implementation relationships](/reference/skyframe.png) diff --git a/release/index.mdx b/release/index.mdx index 39b31bb..4c01139 100644 --- a/release/index.mdx +++ b/release/index.mdx @@ -15,8 +15,8 @@ information about Bazel's release model. | LTS release | Support stage | Latest version | End of support | | ----------- | ------------- | -------------- | -------------- | | Bazel 9 | Rolling| [Check rolling release page](/release/rolling) | N/A | -| Bazel 8 | Active| [8.4.1](https://github.com/bazelbuild/bazel/releases/tag/8.4.1) | December 2027 | -| Bazel 7 | Maintenance| [7.6.1](https://github.com/bazelbuild/bazel/releases/tag/7.6.1) | Dec 2026 | +| Bazel 8 | Active| [8.4.2](https://github.com/bazelbuild/bazel/releases/tag/8.4.2) | December 2027 | +| Bazel 7 | Maintenance| [7.6.2](https://github.com/bazelbuild/bazel/releases/tag/7.6.2) | Dec 2026 | | Bazel 6 | Maintenance | [6.5.0](https://github.com/bazelbuild/bazel/releases/tag/6.5.0) | Dec 2025 | | Bazel 5 | Deprecated | [5.4.1](https://github.com/bazelbuild/bazel/releases/tag/5.4.1) | Jan 2025 | | Bazel 4 | Deprecated | [4.2.4](https://github.com/bazelbuild/bazel/releases/tag/4.2.4) | Jan 2024 | diff --git a/rules/bzl-style.mdx b/rules/bzl-style.mdx new file mode 100644 index 0000000..941028a --- /dev/null +++ b/rules/bzl-style.mdx @@ -0,0 +1,212 @@ +--- +title: '.bzl style guide' +--- + + + +This page covers basic style guidelines for Starlark and also includes +information on macros and rules. + +[Starlark](/rules/language) is a +language that defines how software is built, and as such it is both a +programming and a configuration language. + +You will use Starlark to write `BUILD` files, macros, and build rules. Macros and +rules are essentially meta-languages - they define how `BUILD` files are written. +`BUILD` files are intended to be simple and repetitive. + +All software is read more often than it is written. This is especially true for +Starlark, as engineers read `BUILD` files to understand dependencies of their +targets and details of their builds. This reading will often happen in passing, +in a hurry, or in parallel to accomplishing some other task. Consequently, +simplicity and readability are very important so that users can parse and +comprehend `BUILD` files quickly. + +When a user opens a `BUILD` file, they quickly want to know the list of targets in +the file; or review the list of sources of that C++ library; or remove a +dependency from that Java binary. Each time you add a layer of abstraction, you +make it harder for a user to do these tasks. + +`BUILD` files are also analyzed and updated by many different tools. Tools may not +be able to edit your `BUILD` file if it uses abstractions. Keeping your `BUILD` +files simple will allow you to get better tooling. As a code base grows, it +becomes more and more frequent to do changes across many `BUILD` files in order to +update a library or do a cleanup. + +Important: Do not create a variable or macro just to avoid some amount of +repetition in `BUILD` files. Your `BUILD` file should be easily readable both by +developers and tools. The +[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) principle doesn't +really apply here. + +## General advice + +* Use [Buildifier](https://github.com/bazelbuild/buildtools/tree/master/buildifier#linter) + as a formatter and linter. +* Follow [testing guidelines](/rules/testing). + +## Style + +### Python style + +When in doubt, follow the +[PEP 8 style guide](https://www.python.org/dev/peps/pep-0008/) where possible. +In particular, use four rather than two spaces for indentation to follow the +Python convention. + +Since +[Starlark is not Python](/rules/language#differences-with-python), +some aspects of Python style do not apply. For example, PEP 8 advises that +comparisons to singletons be done with `is`, which is not an operator in +Starlark. + + +### Docstring + +Document files and functions using [docstrings](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#function-docstring). +Use a docstring at the top of each `.bzl` file, and a docstring for each public +function. + +### Document rules and aspects + +Rules and aspects, along with their attributes, as well as providers and their +fields, should be documented using the `doc` argument. + +### Naming convention + +* Variables and function names use lowercase with words separated by + underscores (`[a-z][a-z0-9_]*`), such as `cc_library`. +* Top-level private values start with one underscore. Bazel enforces that + private values cannot be used from other files. Local variables should not + use the underscore prefix. + +### Line length + +As in `BUILD` files, there is no strict line length limit as labels can be long. +When possible, try to use at most 79 characters per line (following Python's +style guide, [PEP 8](https://www.python.org/dev/peps/pep-0008/)). This guideline +should not be enforced strictly: editors should display more than 80 columns, +automated changes will frequently introduce longer lines, and humans shouldn't +spend time splitting lines that are already readable. + +### Keyword arguments + +In keyword arguments, spaces around the equal sign are preferred: + +```python +def fct(name, srcs): + filtered_srcs = my_filter(source = srcs) + native.cc_library( + name = name, + srcs = filtered_srcs, + testonly = True, + ) +``` + +### Boolean values + +Prefer values `True` and `False` (rather than of `1` and `0`) for boolean values +(such as when using a boolean attribute in a rule). + +### Use print only for debugging + +Do not use the `print()` function in production code; it is only intended for +debugging, and will spam all direct and indirect users of your `.bzl` file. The +only exception is that you may submit code that uses `print()` if it is disabled +by default and can only be enabled by editing the source -- for example, if all +uses of `print()` are guarded by `if DEBUG:` where `DEBUG` is hardcoded to +`False`. Be mindful of whether these statements are useful enough to justify +their impact on readability. + +## Macros + +A macro is a function which instantiates one or more rules during the loading +phase. In general, use rules whenever possible instead of macros. The build +graph seen by the user is not the same as the one used by Bazel during the +build - macros are expanded *before Bazel does any build graph analysis.* + +Because of this, when something goes wrong, the user will need to understand +your macro's implementation to troubleshoot build problems. Additionally, `bazel +query` results can be hard to interpret because targets shown in the results +come from macro expansion. Finally, aspects are not aware of macros, so tooling +depending on aspects (IDEs and others) might fail. + +A safe use for macros is for defining additional targets intended to be +referenced directly at the Bazel CLI or in BUILD files: In that case, only the +*end users* of those targets need to know about them, and any build problems +introduced by macros are never far from their usage. + +For macros that define generated targets (implementation details of the macro +which are not supposed to be referred to at the CLI or depended on by targets +not instantiated by that macro), follow these best practices: + +* A macro should take a `name` argument and define a target with that name. + That target becomes that macro's *main target*. +* Generated targets, that is all other targets defined by a macro, should: + * Have their names prefixed by `<name>` or `_<name>`. For example, using + `name = '%s_bar' % (name)`. + * Have restricted visibility (`//visibility:private`), and + * Have a `manual` tag to avoid expansion in wildcard targets (`:all`, + `...`, `:*`, etc). +* The `name` should only be used to derive names of targets defined by the + macro, and not for anything else. For example, don't use the name to derive + a dependency or input file that is not generated by the macro itself. +* All the targets created in the macro should be coupled in some way to the + main target. +* Conventionally, `name` should be the first argument when defining a macro. +* Keep the parameter names in the macro consistent. If a parameter is passed + as an attribute value to the main target, keep its name the same. If a macro + parameter serves the same purpose as a common rule attribute, such as + `deps`, name as you would the attribute (see below). +* When calling a macro, use only keyword arguments. This is consistent with + rules, and greatly improves readability. + +Engineers often write macros when the Starlark API of relevant rules is +insufficient for their specific use case, regardless of whether the rule is +defined within Bazel in native code, or in Starlark. If you're facing this +problem, ask the rule author if they can extend the API to accomplish your +goals. + +As a rule of thumb, the more macros resemble the rules, the better. + +See also [macros](/extending/macros#conventions). + +## Rules + +* Rules, aspects, and their attributes should use lower_case names ("snake + case"). +* Rule names are nouns that describe the main kind of artifact produced by the + rule, from the point of view of its dependencies (or for leaf rules, the + user). This is not necessarily a file suffix. For instance, a rule that + produces C++ artifacts meant to be used as Python extensions might be called + `py_extension`. For most languages, typical rules include: + * `*_library` - a compilation unit or "module". + * `*_binary` - a target producing an executable or a deployment unit. + * `*_test` - a test target. This can include multiple tests. Expect all + tests in a `*_test` target to be variations on the same theme, for + example, testing a single library. + * `*_import`: a target encapsulating a pre-compiled artifact, such as a + `.jar`, or a `.dll` that is used during compilation. +* Use consistent names and types for attributes. Some generally applicable + attributes include: + * `srcs`: `label_list`, allowing files: source files, typically + human-authored. + * `deps`: `label_list`, typically *not* allowing files: compilation + dependencies. + * `data`: `label_list`, allowing files: data files, such as test data etc. + * `runtime_deps`: `label_list`: runtime dependencies that are not needed + for compilation. +* For any attributes with non-obvious behavior (for example, string templates + with special substitutions, or tools that are invoked with specific + requirements), provide documentation using the `doc` keyword argument to the + attribute's declaration (`attr.label_list()` or similar). +* Rule implementation functions should almost always be private functions + (named with a leading underscore). A common style is to give the + implementation function for `myrule` the name `_myrule_impl`. +* Pass information between your rules using a well-defined + [provider](/extending/rules#providers) interface. Declare and document provider + fields. +* Design your rule with extensibility in mind. Consider that other rules might + want to interact with your rule, access your providers, and reuse the + actions you create. +* Follow [performance guidelines](/rules/performance) in your rules. diff --git a/rules/challenges.mdx b/rules/challenges.mdx new file mode 100644 index 0000000..10ff737 --- /dev/null +++ b/rules/challenges.mdx @@ -0,0 +1,223 @@ +--- +title: 'Challenges of Writing Rules' +--- + + + +This page gives a high-level overview of the specific issues and challenges +of writing efficient Bazel rules. + +## Summary Requirements + +* Assumption: Aim for Correctness, Throughput, Ease of Use & Latency +* Assumption: Large Scale Repositories +* Assumption: BUILD-like Description Language +* Historic: Hard Separation between Loading, Analysis, and Execution is + Outdated, but still affects the API +* Intrinsic: Remote Execution and Caching are Hard +* Intrinsic: Using Change Information for Correct and Fast Incremental Builds + requires Unusual Coding Patterns +* Intrinsic: Avoiding Quadratic Time and Memory Consumption is Hard + +## Assumptions + +Here are some assumptions made about the build system, such as need for +correctness, ease of use, throughput, and large scale repositories. The +following sections address these assumptions and offer guidelines to ensure +rules are written in an effective manner. + +### Aim for correctness, throughput, ease of use & latency + +We assume that the build system needs to be first and foremost correct with +respect to incremental builds. For a given source tree, the output of the +same build should always be the same, regardless of what the output tree looks +like. In the first approximation, this means Bazel needs to know every single +input that goes into a given build step, such that it can rerun that step if any +of the inputs change. There are limits to how correct Bazel can get, as it leaks +some information such as date / time of the build, and ignores certain types of +changes such as changes to file attributes. [Sandboxing](/docs/sandboxing) +helps ensure correctness by preventing reads to undeclared input files. Besides +the intrinsic limits of the system, there are a few known correctness issues, +most of which are related to Fileset or the C++ rules, which are both hard +problems. We have long-term efforts to fix these. + +The second goal of the build system is to have high throughput; we are +permanently pushing the boundaries of what can be done within the current +machine allocation for a remote execution service. If the remote execution +service gets overloaded, nobody can get work done. + +Ease of use comes next. Of multiple correct approaches with the same (or +similar) footprint of the remote execution service, we choose the one that is +easier to use. + +Latency denotes the time it takes from starting a build to getting the intended +result, whether that is a test log from a passing or failing test, or an error +message that a `BUILD` file has a typo. + +Note that these goals often overlap; latency is as much a function of throughput +of the remote execution service as is correctness relevant for ease of use. + +### Large scale repositories + +The build system needs to operate at the scale of large repositories where large +scale means that it does not fit on a single hard drive, so it is impossible to +do a full checkout on virtually all developer machines. A medium-sized build +will need to read and parse tens of thousands of `BUILD` files, and evaluate +hundreds of thousands of globs. While it is theoretically possible to read all +`BUILD` files on a single machine, we have not yet been able to do so within a +reasonable amount of time and memory. As such, it is critical that `BUILD` files +can be loaded and parsed independently. + +### BUILD-like description language + +In this context, we assume a configuration language that is +roughly similar to `BUILD` files in declaration of library and binary rules +and their interdependencies. `BUILD` files can be read and parsed independently, +and we avoid even looking at source files whenever we can (except for +existence). + +## Historic + +There are differences between Bazel versions that cause challenges and some +of these are outlined in the following sections. + +### Hard separation between loading, analysis, and execution is outdated but still affects the API + +Technically, it is sufficient for a rule to know the input and output files of +an action just before the action is sent to remote execution. However, the +original Bazel code base had a strict separation of loading packages, then +analyzing rules using a configuration (command-line flags, essentially), and +only then running any actions. This distinction is still part of the rules API +today, even though the core of Bazel no longer requires it (more details below). + +That means that the rules API requires a declarative description of the rule +interface (what attributes it has, types of attributes). There are some +exceptions where the API allows custom code to run during the loading phase to +compute implicit names of output files and implicit values of attributes. For +example, a java_library rule named 'foo' implicitly generates an output named +'libfoo.jar', which can be referenced from other rules in the build graph. + +Furthermore, the analysis of a rule cannot read any source files or inspect the +output of an action; instead, it needs to generate a partial directed bipartite +graph of build steps and output file names that is only determined from the rule +itself and its dependencies. + +## Intrinsic + +There are some intrinsic properties that make writing rules challenging and +some of the most common ones are described in the following sections. + +### Remote execution and caching are hard + +Remote execution and caching improve build times in large repositories by +roughly two orders of magnitude compared to running the build on a single +machine. However, the scale at which it needs to perform is staggering: Google's +remote execution service is designed to handle a huge number of requests per +second, and the protocol carefully avoids unnecessary roundtrips as well as +unnecessary work on the service side. + +At this time, the protocol requires that the build system knows all inputs to a +given action ahead of time; the build system then computes a unique action +fingerprint, and asks the scheduler for a cache hit. If a cache hit is found, +the scheduler replies with the digests of the output files; the files itself are +addressed by digest later on. However, this imposes restrictions on the Bazel +rules, which need to declare all input files ahead of time. + +### Using change information for correct and fast incremental builds requires unusual coding patterns + +Above, we argued that in order to be correct, Bazel needs to know all the input +files that go into a build step in order to detect whether that build step is +still up-to-date. The same is true for package loading and rule analysis, and we +have designed [Skyframe](/reference/skyframe) to handle this +in general. Skyframe is a graph library and evaluation framework that takes a +goal node (such as 'build //foo with these options'), and breaks it down into +its constituent parts, which are then evaluated and combined to yield this +result. As part of this process, Skyframe reads packages, analyzes rules, and +executes actions. + +At each node, Skyframe tracks exactly which nodes any given node used to compute +its own output, all the way from the goal node down to the input files (which +are also Skyframe nodes). Having this graph explicitly represented in memory +allows the build system to identify exactly which nodes are affected by a given +change to an input file (including creation or deletion of an input file), doing +the minimal amount of work to restore the output tree to its intended state. + +As part of this, each node performs a dependency discovery process. Each +node can declare dependencies, and then use the contents of those dependencies +to declare even further dependencies. In principle, this maps well to a +thread-per-node model. However, medium-sized builds contain hundreds of +thousands of Skyframe nodes, which isn't easily possible with current Java +technology (and for historical reasons, we're currently tied to using Java, so +no lightweight threads and no continuations). + +Instead, Bazel uses a fixed-size thread pool. However, that means that if a node +declares a dependency that isn't available yet, we may have to abort that +evaluation and restart it (possibly in another thread), when the dependency is +available. This, in turn, means that nodes should not do this excessively; a +node that declares N dependencies serially can potentially be restarted N times, +costing O(N^2) time. Instead, we aim for up-front bulk declaration of +dependencies, which sometimes requires reorganizing the code, or even splitting +a node into multiple nodes to limit the number of restarts. + +Note that this technology isn't currently available in the rules API; instead, +the rules API is still defined using the legacy concepts of loading, analysis, +and execution phases. However, a fundamental restriction is that all accesses to +other nodes have to go through the framework so that it can track the +corresponding dependencies. Regardless of the language in which the build system +is implemented or in which the rules are written (they don't have to be the +same), rule authors must not use standard libraries or patterns that bypass +Skyframe. For Java, that means avoiding java.io.File as well as any form of +reflection, and any library that does either. Libraries that support dependency +injection of these low-level interfaces still need to be setup correctly for +Skyframe. + +This strongly suggests to avoid exposing rule authors to a full language runtime +in the first place. The danger of accidental use of such APIs is just too big - +several Bazel bugs in the past were caused by rules using unsafe APIs, even +though the rules were written by the Bazel team or other domain experts. + +### Avoiding quadratic time and memory consumption is hard + +To make matters worse, apart from the requirements imposed by Skyframe, the +historical constraints of using Java, and the outdatedness of the rules API, +accidentally introducing quadratic time or memory consumption is a fundamental +problem in any build system based on library and binary rules. There are two +very common patterns that introduce quadratic memory consumption (and therefore +quadratic time consumption). + +1. Chains of Library Rules - +Consider the case of a chain of library rules A depends on B, depends on C, and +so on. Then, we want to compute some property over the transitive closure of +these rules, such as the Java runtime classpath, or the C++ linker command for +each library. Naively, we might take a standard list implementation; however, +this already introduces quadratic memory consumption: the first library +contains one entry on the classpath, the second two, the third three, and so +on, for a total of 1+2+3+...+N = O(N^2) entries. + +2. Binary Rules Depending on the Same Library Rules - +Consider the case where a set of binaries that depend on the same library +rules — such as if you have a number of test rules that test the same +library code. Let's say out of N rules, half the rules are binary rules, and +the other half library rules. Now consider that each binary makes a copy of +some property computed over the transitive closure of library rules, such as +the Java runtime classpath, or the C++ linker command line. For example, it +could expand the command line string representation of the C++ link action. N/2 +copies of N/2 elements is O(N^2) memory. + +#### Custom collections classes to avoid quadratic complexity + +Bazel is heavily affected by both of these scenarios, so we introduced a set of +custom collection classes that effectively compress the information in memory by +avoiding the copy at each step. Almost all of these data structures have set +semantics, so we called it +[depset](/rules/lib/depset) +(also known as `NestedSet` in the internal implementation). The majority of +changes to reduce Bazel's memory consumption over the past several years were +changes to use depsets instead of whatever was previously used. + +Unfortunately, usage of depsets does not automatically solve all the issues; +in particular, even just iterating over a depset in each rule re-introduces +quadratic time consumption. Internally, NestedSets also has some helper methods +to facilitate interoperability with normal collections classes; unfortunately, +accidentally passing a NestedSet to one of these methods leads to copying +behavior, and reintroduces quadratic memory consumption. diff --git a/rules/deploying.mdx b/rules/deploying.mdx new file mode 100644 index 0000000..3fe2c86 --- /dev/null +++ b/rules/deploying.mdx @@ -0,0 +1,223 @@ +--- +title: 'Deploying Rules' +--- + + + +This page is for rule writers who are planning to make their rules available +to others. + +We recommend you start a new ruleset from the template repository: +https://github.com/bazel-contrib/rules-template +That template follows the recommendations below, and includes API documentation generation +and sets up a CI/CD pipeline to make it trivial to distribute your ruleset. + +## Hosting and naming rules + +New rules should go into their own GitHub repository under your organization. +Start a thread on [GitHub](https://github.com/bazelbuild/bazel/discussions) +if you feel like your rules belong in the [bazelbuild](https://github.com/bazelbuild) +organization. + +Repository names for Bazel rules are standardized on the following format: +`$ORGANIZATION/rules_$NAME`. +See [examples on GitHub](https://github.com/search?q=rules+bazel&type=Repositories). +For consistency, you should follow this same format when publishing your Bazel rules. + +Make sure to use a descriptive GitHub repository description and `README.md` +title, example: + +* Repository name: `bazelbuild/rules_go` +* Repository description: *Go rules for Bazel* +* Repository tags: `golang`, `bazel` +* `README.md` header: *Go rules for [Bazel](https://bazel.build)* +(note the link to https://bazel.build which will guide users who are unfamiliar +with Bazel to the right place) + +Rules can be grouped either by language (such as Scala), runtime platform +(such as Android), or framework (such as Spring). + +## Repository content + +Every rule repository should have a certain layout so that users can quickly +understand new rules. + +For example, when writing new rules for the (make-believe) +`mockascript` language, the rule repository would have the following structure: + +``` +/ + LICENSE + README + MODULE.bazel + mockascript/ + constraints/ + BUILD + runfiles/ + BUILD + runfiles.mocs + BUILD + defs.bzl + tests/ + BUILD + some_test.sh + another_test.py + examples/ + BUILD + bin.mocs + lib.mocs + test.mocs +``` + +### MODULE.bazel + +In the project's `MODULE.bazel`, you should define the name that users will use +to reference your rules. If your rules belong to the +[bazelbuild](https://github.com/bazelbuild) organization, you must use +`rules_<lang>` (such as `rules_mockascript`). Otherwise, you should name your +repository `<org>_rules_<lang>` (such as `build_stack_rules_proto`). Please +start a thread on [GitHub](https://github.com/bazelbuild/bazel/discussions) +if you feel like your rules should follow the convention for rules in the +[bazelbuild](https://github.com/bazelbuild) organization. + +In the following sections, assume the repository belongs to the +[bazelbuild](https://github.com/bazelbuild) organization. + +``` +module(name = "rules_mockascript") +``` + +### README + +At the top level, there should be a `README` that contains a brief description +of your ruleset, and the API users should expect. + +### Rules + +Often times there will be multiple rules provided by your repository. Create a +directory named by the language and provide an entry point - `defs.bzl` file +exporting all rules (also include a `BUILD` file so the directory is a package). +For `rules_mockascript` that means there will be a directory named +`mockascript`, and a `BUILD` file and a `defs.bzl` file inside: + +``` +/ + mockascript/ + BUILD + defs.bzl +``` + +### Constraints + +If your rule defines +[toolchain](/extending/toolchains) rules, +it's possible that you'll need to define custom `constraint_setting`s and/or +`constraint_value`s. Put these into a `//<LANG>/constraints` package. Your +directory structure will look like this: + +``` +/ + mockascript/ + constraints/ + BUILD + BUILD + defs.bzl +``` + +Please read +[github.com/bazelbuild/platforms](https://github.com/bazelbuild/platforms) +for best practices, and to see what constraints are already present, and +consider contributing your constraints there if they are language independent. +Be mindful of introducing custom constraints, all users of your rules will +use them to perform platform specific logic in their `BUILD` files (for example, +using [selects](/reference/be/functions#select)). +With custom constraints, you define a language that the whole Bazel ecosystem +will speak. + +### Runfiles library + +If your rule provides a standard library for accessing runfiles, it should be +in the form of a library target located at `//<LANG>/runfiles` (an abbreviation +of `//<LANG>/runfiles:runfiles`). User targets that need to access their data +dependencies will typically add this target to their `deps` attribute. + +### Repository rules + +#### Dependencies + +Your rules might have external dependencies, which you'll need to specify in +your MODULE.bazel file. + +#### Registering toolchains + +Your rules might also register toolchains, which you can also specify in the +MODULE.bazel file. + +Note that in order to resolve toolchains in the analysis phase Bazel needs to +analyze all `toolchain` targets that are registered. Bazel will not need to +analyze all targets referenced by `toolchain.toolchain` attribute. If in order +to register toolchains you need to perform complex computation in the +repository, consider splitting the repository with `toolchain` targets from the +repository with `<LANG>_toolchain` targets. Former will be always fetched, and +the latter will only be fetched when user actually needs to build `<LANG>` code. + + +#### Release snippet + +In your release announcement provide a snippet that your users can copy-paste +into their `MODULE.bazel` file. This snippet in general will look as follows: + +``` +bazel_dep(name = "rules_<LANG>", version = "<VERSION>") +``` + + +### Tests + +There should be tests that verify that the rules are working as expected. This +can either be in the standard location for the language the rules are for or a +`tests/` directory at the top level. + +### Examples (optional) + +It is useful to users to have an `examples/` directory that shows users a couple +of basic ways that the rules can be used. + +## CI/CD + +Many rulesets use GitHub Actions. See the configuration used in the [rules-template](https://github.com/bazel-contrib/rules-template/tree/main/.github/workflows) repo, which are simplified using a "reusable workflow" hosted in the bazel-contrib +org. `ci.yaml` runs tests on each PR and `main` comit, and `release.yaml` runs anytime you push a tag to the repository. +See comments in the rules-template repo for more information. + +If your repository is under the [bazelbuild organization](https://github.com/bazelbuild), +you can [ask to add](https://github.com/bazelbuild/continuous-integration/issues/new?template=adding-your-project-to-bazel-ci.md&title=Request+to+add+new+project+%5BPROJECT_NAME%5D&labels=new-project) +it to [ci.bazel.build](http://ci.bazel.build). + +## Documentation + +See the [Stardoc documentation](https://github.com/bazelbuild/stardoc) for +instructions on how to comment your rules so that documentation can be generated +automatically. + +The [rules-template docs/ folder](https://github.com/bazel-contrib/rules-template/tree/main/docs) +shows a simple way to ensure the Markdown content in the `docs/` folder is always up-to-date +as Starlark files are updated. + +## FAQs + +### Why can't we add our rule to the main Bazel GitHub repository? + +We want to decouple rules from Bazel releases as much as possible. It's clearer +who owns individual rules, reducing the load on Bazel developers. For our users, +decoupling makes it easier to modify, upgrade, downgrade, and replace rules. +Contributing to rules can be lighter weight than contributing to Bazel - +depending on the rules -, including full submit access to the corresponding +GitHub repository. Getting submit access to Bazel itself is a much more involved +process. + +The downside is a more complicated one-time installation process for our users: +they have to add a dependency on your ruleset in their `MODULE.bazel` file. + +We used to have all of the rules in the Bazel repository (under +`//tools/build_rules` or `//tools/build_defs`). We still have a couple rules +there, but we are working on moving the remaining rules out. diff --git a/rules/errors/read-only-variable.mdx b/rules/errors/read-only-variable.mdx new file mode 100644 index 0000000..2bfde65 --- /dev/null +++ b/rules/errors/read-only-variable.mdx @@ -0,0 +1,30 @@ +--- +title: 'Error: Variable x is read only' +--- + + + +A global variable cannot be reassigned. It will always point to the same object. +However, its content might change, if the value is mutable (for example, the +content of a list). Local variables don't have this restriction. + +```python +a = [1, 2] + +a[1] = 3 + +b = 3 + +b = 4 # forbidden +``` + +`ERROR: /path/ext.bzl:7:1: Variable b is read only` + +You will get a similar error if you try to redefine a function (function +overloading is not supported), for example: + +```python +def foo(x): return x + 1 + +def foo(x, y): return x + y # forbidden +``` diff --git a/rules/faq.mdx b/rules/faq.mdx new file mode 100644 index 0000000..5321f0b --- /dev/null +++ b/rules/faq.mdx @@ -0,0 +1,80 @@ +--- +title: 'Frequently Asked Questions' +--- + + + +These are some common issues and questions with writing extensions. + +## Why is my file not produced / my action never executed? + +Bazel only executes the actions needed to produce the *requested* output files. + +* If the file you want has a label, you can request it directly: + `bazel build //pkg:myfile.txt` + +* If the file is in an output group of the target, you may need to specify that + output group on the command line: + `bazel build //pkg:mytarget --output_groups=foo` + +* If you want the file to be built automatically whenever your target is + mentioned on the command line, add it to your rule's default outputs by + returning a [`DefaultInfo`](lib/globals#DefaultInfo) provider. + +See the [Rules page](/extending/rules#requesting-output-files) for more information. + +## Why is my implementation function not executed? + +Bazel analyzes only the targets that are requested for the build. You should +either name the target on the command line, or something that depends on the +target. + +## A file is missing when my action or binary is executed + +Make sure that 1) the file has been registered as an input to the action or +binary, and 2) the script or tool being executed is accessing the file using the +correct path. + +For actions, you declare inputs by passing them to the `ctx.actions.*` function +that creates the action. The proper path for the file can be obtained using +[`File.path`](lib/File#path). + +For binaries (the executable outputs run by a `bazel run` or `bazel test` +command), you declare inputs by including them in the +[runfiles](/extending/rules#runfiles). Instead of using the `path` field, use +[`File.short_path`](lib/File#short_path), which is file's path relative to +the runfiles directory in which the binary executes. + +## How can I control which files are built by `bazel build //pkg:mytarget`? + +Use the [`DefaultInfo`](lib/globals#DefaultInfo) provider to +[set the default outputs](/extending/rules#requesting-output-files). + +## How can I run a program or do file I/O as part of my build? + +A tool can be declared as a target, just like any other part of your build, and +run during the execution phase to help build other targets. To create an action +that runs a tool, use [`ctx.actions.run`](lib/actions#run) and pass in the +tool as the `executable` parameter. + +During the loading and analysis phases, a tool *cannot* run, nor can you perform +file I/O. This means that tools and file contents (except the contents of BUILD +and .bzl files) cannot affect how the target and action graphs get created. + +## What if I need to access the same structured data both before and during the execution phase? + +You can format the structured data as a .bzl file. You can `load()` the file to +access it during the loading and analysis phases. You can pass it as an input or +runfile to actions and executables that need it during the execution phase. + +## How should I document Starlark code? + +For rules and rule attributes, you can pass a docstring literal (possibly +triple-quoted) to the `doc` parameter of `rule` or `attr.*()`. For helper +functions and macros, use a triple-quoted docstring literal following the format +given [here](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#function-docstring). +Rule implementation functions generally do not need their own docstring. + +Using string literals in the expected places makes it easier for automated +tooling to extract documentation. Feel free to use standard non-string comments +wherever it may help the reader of your code. diff --git a/rules/index.mdx b/rules/index.mdx new file mode 100644 index 0000000..2a6c3eb --- /dev/null +++ b/rules/index.mdx @@ -0,0 +1,85 @@ +--- +title: 'Rules' +--- + + + +The Bazel ecosystem has a growing and evolving set of rules to support popular +languages and packages. Much of Bazel's strength comes from the ability to +[define new rules](/extending/concepts) that can be used by others. + +This page describes the recommended, native, and non-native Bazel rules. + +## Recommended rules + +Here is a selection of recommended rules: + +* [Android](/docs/bazel-and-android) +* [C / C++](/docs/bazel-and-cpp) +* [Docker/OCI](https://github.com/bazel-contrib/rules_oci) +* [Go](https://github.com/bazelbuild/rules_go) +* [Haskell](https://github.com/tweag/rules_haskell) +* [Java](/docs/bazel-and-java) +* [JavaScript / NodeJS](https://github.com/bazelbuild/rules_nodejs) +* [Maven dependency management](https://github.com/bazelbuild/rules_jvm_external) +* [Objective-C](/docs/bazel-and-apple) +* [Package building](https://github.com/bazelbuild/rules_pkg) +* [Protocol Buffers](https://github.com/bazelbuild/rules_proto#protobuf-rules-for-bazel) +* [Python](https://github.com/bazelbuild/rules_python) +* [Rust](https://github.com/bazelbuild/rules_rust) +* [Scala](https://github.com/bazelbuild/rules_scala) +* [Shell](/reference/be/shell) +* [Webtesting](https://github.com/bazelbuild/rules_webtesting) (Webdriver) + +The repository [Skylib](https://github.com/bazelbuild/bazel-skylib) contains +additional functions that can be useful when writing new rules and new +macros. + +The rules above were reviewed and follow our +[requirements for recommended rules](/community/recommended-rules). +Contact the respective rule set's maintainers regarding issues and feature +requests. + +To find more Bazel rules, use a search engine, take a look on +[awesomebazel.com](https://awesomebazel.com/), or search on +[GitHub](https://github.com/search?o=desc&q=bazel+rules&s=stars&type=Repositories). + +## Native rules that do not apply to a specific programming language + +Native rules are shipped with the Bazel binary, they are always available in +BUILD files without a `load` statement. + +* Extra actions + - [`extra_action`](/reference/be/extra-actions#extra_action) + - [`action_listener`](/reference/be/extra-actions#action_listener) +* General + - [`filegroup`](/reference/be/general#filegroup) + - [`genquery`](/reference/be/general#genquery) + - [`test_suite`](/reference/be/general#test_suite) + - [`alias`](/reference/be/general#alias) + - [`config_setting`](/reference/be/general#config_setting) + - [`genrule`](/reference/be/general#genrule) +* Platform + - [`constraint_setting`](/reference/be/platforms-and-toolchains#constraint_setting) + - [`constraint_value`](/reference/be/platforms-and-toolchains#constraint_value) + - [`platform`](/reference/be/platforms-and-toolchains#platform) + - [`toolchain`](/reference/be/platforms-and-toolchains#toolchain) + - [`toolchain_type`](/reference/be/platforms-and-toolchains#toolchain_type) +* Workspace + - [`bind`](/reference/be/workspace#bind) + - [`local_repository`](/reference/be/workspace#local_repository) + - [`new_local_repository`](/reference/be/workspace#new_local_repository) + - [`xcode_config`](/reference/be/objective-c#xcode_config) + - [`xcode_version`](/reference/be/objective-c#xcode_version) + +## Embedded non-native rules + +Bazel also embeds additional rules written in [Starlark](/rules/language). Those can be loaded from +the `@bazel_tools` built-in external repository. + +* Repository rules + - [`git_repository`](/rules/lib/repo/git#git_repository) + - [`http_archive`](/rules/lib/repo/http#http_archive) + - [`http_file`](/rules/lib/repo/http#http_archive) + - [`http_jar`](/rules/lib/repo/http#http_jar) + - [Utility functions on patching](/rules/lib/repo/utils) diff --git a/rules/legacy-macro-tutorial.mdx b/rules/legacy-macro-tutorial.mdx new file mode 100644 index 0000000..28b0fca --- /dev/null +++ b/rules/legacy-macro-tutorial.mdx @@ -0,0 +1,98 @@ +--- +title: 'Creating a Legacy Macro' +--- + + + +IMPORTANT: This tutorial is for [*legacy macros*](/extending/legacy-macros). If +you only need to support Bazel 8 or newer, we recommend using [symbolic +macros](/extending/macros) instead; take a look at [Creating a Symbolic +Macro](macro-tutorial). + +Imagine that you need to run a tool as part of your build. For example, you +may want to generate or preprocess a source file, or compress a binary. In this +tutorial, you are going to create a legacy macro that resizes an image. + +Macros are suitable for simple tasks. If you want to do anything more +complicated, for example add support for a new programming language, consider +creating a [rule](/extending/rules). Rules give you more control and flexibility. + +The easiest way to create a macro that resizes an image is to use a `genrule`: + +```starlark +genrule( + name = "logo_miniature", + srcs = ["logo.png"], + outs = ["small_logo.png"], + cmd = "convert $< -resize 100x100 $@", +) + +cc_binary( + name = "my_app", + srcs = ["my_app.cc"], + data = [":logo_miniature"], +) +``` + +If you need to resize more images, you may want to reuse the code. To do that, +define a function in a separate `.bzl` file, and call the file `miniature.bzl`: + +```starlark +def miniature(name, src, size = "100x100", **kwargs): + """Create a miniature of the src image. + + The generated file is prefixed with 'small_'. + """ + native.genrule( + name = name, + srcs = [src], + # Note that the line below will fail if `src` is not a filename string + outs = ["small_" + src], + cmd = "convert $< -resize " + size + " $@", + **kwargs + ) +``` + +A few remarks: + + * By convention, legacy macros have a `name` argument, just like rules. + + * To document the behavior of a legacy macro, use + [docstring](https://www.python.org/dev/peps/pep-0257/) like in Python. + + * To call a `genrule`, or any other native rule, prefix with `native.`. + + * Use `**kwargs` to forward the extra arguments to the underlying `genrule` + (it works just like in + [Python](https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments)). + This is useful, so that a user can use standard attributes like + `visibility`, or `tags`. + +Now, use the macro from the `BUILD` file: + +```starlark +load("//path/to:miniature.bzl", "miniature") + +miniature( + name = "logo_miniature", + src = "image.png", +) + +cc_binary( + name = "my_app", + srcs = ["my_app.cc"], + data = [":logo_miniature"], +) +``` + +And finally, a **warning note**: the macro assumes that `src` is a filename +string (otherwise, `outs = ["small_" + src]` will fail). So `src = "image.png"` +works; but what happens if the `BUILD` file instead used `src = +"//other/package:image.png"`, or even `src = select(...)`? + +You should make sure to declare such assumptions in your macro's documentation. +Unfortunately, legacy macros, especially large ones, tend to be fragile because +it can be hard to notice and document all such assumptions in your code – and, +of course, some users of the macro won't read the documentation. We recommend, +if possible, instead using [symbolic macros](/extending/macros), which have +built\-in checks on attribute types. diff --git a/rules/macro-tutorial.mdx b/rules/macro-tutorial.mdx new file mode 100644 index 0000000..2b3d8e4 --- /dev/null +++ b/rules/macro-tutorial.mdx @@ -0,0 +1,116 @@ +--- +title: 'Creating a Symbolic Macro' +--- + + + +IMPORTANT: This tutorial is for [*symbolic macros*](/extending/macros) – the new +macro system introduced in Bazel 8. If you need to support older Bazel versions, +you will want to write a [legacy macro](/extending/legacy-macros) instead; take +a look at [Creating a Legacy Macro](legacy-macro-tutorial). + +Imagine that you need to run a tool as part of your build. For example, you +may want to generate or preprocess a source file, or compress a binary. In this +tutorial, you are going to create a symbolic macro that resizes an image. + +Macros are suitable for simple tasks. If you want to do anything more +complicated, for example add support for a new programming language, consider +creating a [rule](/extending/rules). Rules give you more control and flexibility. + +The easiest way to create a macro that resizes an image is to use a `genrule`: + +```starlark +genrule( + name = "logo_miniature", + srcs = ["logo.png"], + outs = ["small_logo.png"], + cmd = "convert $< -resize 100x100 $@", +) + +cc_binary( + name = "my_app", + srcs = ["my_app.cc"], + data = [":logo_miniature"], +) +``` + +If you need to resize more images, you may want to reuse the code. To do that, +define an *implementation function* and a *macro declaration* in a separate +`.bzl` file, and call the file `miniature.bzl`: + +```starlark +# Implementation function +def _miniature_impl(name, visibility, src, size, **kwargs): + native.genrule( + name = name, + visibility = visibility, + srcs = [src], + outs = [name + "_small_" + src.name], + cmd = "convert $< -resize " + size + " $@", + **kwargs, + ) + +# Macro declaration +miniature = macro( + doc = """Create a miniature of the src image. + + The generated file name will be prefixed with `name + "_small_"`. + """, + implementation = _miniature_impl, + # Inherit most of genrule's attributes (such as tags and testonly) + inherit_attrs = native.genrule, + attrs = { + "src": attr.label( + doc = "Image file", + allow_single_file = True, + # Non-configurable because our genrule's output filename is + # suffixed with src's name. (We want to suffix the output file with + # srcs's name because some tools that operate on image files expect + # the files to have the right file extension.) + configurable = False, + ), + "size": attr.string( + doc = "Output size in WxH format", + default = "100x100", + ), + # Do not allow callers of miniature() to set srcs, cmd, or outs - + # _miniature_impl overrides their values when calling native.genrule() + "srcs": None, + "cmd": None, + "outs": None, + }, +) +``` + +A few remarks: + + * Symbolic macro implementation functions must have `name` and `visibility` + parameters. They should used for the macro's main target. + + * To document the behavior of a symbolic macro, use `doc` parameters for + `macro()` and its attributes. + + * To call a `genrule`, or any other native rule, use `native.`. + + * Use `**kwargs` to forward the extra inherited arguments to the underlying + `genrule` (it works just like in + [Python](https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments)). + This is useful so that a user can set standard attributes like `tags` or + `testonly`. + +Now, use the macro from the `BUILD` file: + +```starlark +load("//path/to:miniature.bzl", "miniature") + +miniature( + name = "logo_miniature", + src = "image.png", +) + +cc_binary( + name = "my_app", + srcs = ["my_app.cc"], + data = [":logo_miniature"], +) +``` diff --git a/rules/performance.mdx b/rules/performance.mdx new file mode 100644 index 0000000..dff0ccc --- /dev/null +++ b/rules/performance.mdx @@ -0,0 +1,302 @@ +--- +title: 'Optimizing Performance' +--- + + + +When writing rules, the most common performance pitfall is to traverse or copy +data that is accumulated from dependencies. When aggregated over the whole +build, these operations can easily take O(N^2) time or space. To avoid this, it +is crucial to understand how to use depsets effectively. + +This can be hard to get right, so Bazel also provides a memory profiler that +assists you in finding spots where you might have made a mistake. Be warned: +The cost of writing an inefficient rule may not be evident until it is in +widespread use. + +## Use depsets + +Whenever you are rolling up information from rule dependencies you should use +[depsets](lib/depset). Only use plain lists or dicts to publish information +local to the current rule. + +A depset represents information as a nested graph which enables sharing. + +Consider the following graph: + +``` +C -> B -> A +D ---^ +``` + +Each node publishes a single string. With depsets the data looks like this: + +``` +a = depset(direct=['a']) +b = depset(direct=['b'], transitive=[a]) +c = depset(direct=['c'], transitive=[b]) +d = depset(direct=['d'], transitive=[b]) +``` + +Note that each item is only mentioned once. With lists you would get this: + +``` +a = ['a'] +b = ['b', 'a'] +c = ['c', 'b', 'a'] +d = ['d', 'b', 'a'] +``` + +Note that in this case `'a'` is mentioned four times! With larger graphs this +problem will only get worse. + +Here is an example of a rule implementation that uses depsets correctly to +publish transitive information. Note that it is OK to publish rule-local +information using lists if you want since this is not O(N^2). + +``` +MyProvider = provider() + +def _impl(ctx): + my_things = ctx.attr.things + all_things = depset( + direct=my_things, + transitive=[dep[MyProvider].all_things for dep in ctx.attr.deps] + ) + ... + return [MyProvider( + my_things=my_things, # OK, a flat list of rule-local things only + all_things=all_things, # OK, a depset containing dependencies + )] +``` + +See the [depset overview](/extending/depsets) page for more information. + +### Avoid calling `depset.to_list()` + +You can coerce a depset to a flat list using +[`to_list()`](lib/depset#to_list), but doing so usually results in O(N^2) +cost. If at all possible, avoid any flattening of depsets except for debugging +purposes. + +A common misconception is that you can freely flatten depsets if you only do it +at top-level targets, such as an `<xx>_binary` rule, since then the cost is not +accumulated over each level of the build graph. But this is *still* O(N^2) when +you build a set of targets with overlapping dependencies. This happens when +building your tests `//foo/tests/...`, or when importing an IDE project. + +### Reduce the number of calls to `depset` + +Calling `depset` inside a loop is often a mistake. It can lead to depsets with +very deep nesting, which perform poorly. For example: + +```python +x = depset() +for i in inputs: + # Do not do that. + x = depset(transitive = [x, i.deps]) +``` + +This code can be replaced easily. First, collect the transitive depsets and +merge them all at once: + +```python +transitive = [] + +for i in inputs: + transitive.append(i.deps) + +x = depset(transitive = transitive) +``` + +This can sometimes be reduced using a list comprehension: + +```python +x = depset(transitive = [i.deps for i in inputs]) +``` + +## Use ctx.actions.args() for command lines + +When building command lines you should use [ctx.actions.args()](lib/Args). +This defers expansion of any depsets to the execution phase. + +Apart from being strictly faster, this will reduce the memory consumption of +your rules -- sometimes by 90% or more. + +Here are some tricks: + +* Pass depsets and lists directly as arguments, instead of flattening them +yourself. They will get expanded by `ctx.actions.args()` for you. +If you need any transformations on the depset contents, look at +[ctx.actions.args#add](lib/Args#add) to see if anything fits the bill. + +* Are you passing `File#path` as arguments? No need. Any +[File](lib/File) is automatically turned into its +[path](lib/File#path), deferred to expansion time. + +* Avoid constructing strings by concatenating them together. +The best string argument is a constant as its memory will be shared between +all instances of your rule. + +* If the args are too long for the command line an `ctx.actions.args()` object +can be conditionally or unconditionally written to a param file using +[`ctx.actions.args#use_param_file`](lib/Args#use_param_file). This is +done behind the scenes when the action is executed. If you need to explicitly +control the params file you can write it manually using +[`ctx.actions.write`](lib/actions#write). + +Example: + +``` +def _impl(ctx): + ... + args = ctx.actions.args() + file = ctx.declare_file(...) + files = depset(...) + + # Bad, constructs a full string "--foo=<file path>" for each rule instance + args.add("--foo=" + file.path) + + # Good, shares "--foo" among all rule instances, and defers file.path to later + # It will however pass ["--foo", <file path>] to the action command line, + # instead of ["--foo=<file_path>"] + args.add("--foo", file) + + # Use format if you prefer ["--foo=<file path>"] to ["--foo", <file path>] + args.add(file, format="--foo=%s") + + # Bad, makes a giant string of a whole depset + args.add(" ".join(["-I%s" % file.short_path for file in files.to_list()]) + + # Good, only stores a reference to the depset + args.add_all(files, format_each="-I%s", map_each=_to_short_path) + +# Function passed to map_each above +def _to_short_path(f): + return f.short_path +``` + +## Transitive action inputs should be depsets + +When building an action using [ctx.actions.run](lib/actions?#run), do not +forget that the `inputs` field accepts a depset. Use this whenever inputs are +collected from dependencies transitively. + +``` +inputs = depset(...) +ctx.actions.run( + inputs = inputs, # Do *not* turn inputs into a list + ... +) +``` + +## Hanging + +If Bazel appears to be hung, you can hit <kbd>Ctrl-\</kbd> or send +Bazel a `SIGQUIT` signal (`kill -3 $(bazel info server_pid)`) to get a thread +dump in the file `$(bazel info output_base)/server/jvm.out`. + +Since you may not be able to run `bazel info` if bazel is hung, the +`output_base` directory is usually the parent of the `bazel-<workspace>` +symlink in your workspace directory. + +## Performance profiling + +The [JSON trace profile](/advanced/performance/json-trace-profile) can be very +useful to quickly understand what Bazel spent time on during the invocation. + +The [`--experimental_command_profile`](https://bazel.build/reference/command-line-reference#flag--experimental_command_profile) +flag may be used to capture Java Flight Recorder profiles of various kinds +(cpu time, wall time, memory allocations and lock contention). + +The [`--starlark_cpu_profile`](https://bazel.build/reference/command-line-reference#flag--starlark_cpu_profile) +flag may be used to write a pprof profile of CPU usage by all Starlark threads. + +## Memory profiling + +Bazel comes with a built-in memory profiler that can help you check your rule’s +memory use. If there is a problem you can dump the heap to find the +exact line of code that is causing the problem. + +### Enabling memory tracking + +You must pass these two startup flags to *every* Bazel invocation: + + ``` + STARTUP_FLAGS=\ + --host_jvm_args=-javaagent:<path to java-allocation-instrumenter-3.3.4.jar> \ + --host_jvm_args=-DRULE_MEMORY_TRACKER=1 + ``` +Note: You can download the allocation instrumenter jar file from [Maven Central +Repository][allocation-instrumenter-link]. + +[allocation-instrumenter-link]: https://repo1.maven.org/maven2/com/google/code/java-allocation-instrumenter/java-allocation-instrumenter/3.3.4 + +These start the server in memory tracking mode. If you forget these for even +one Bazel invocation the server will restart and you will have to start over. + +### Using the Memory Tracker + +As an example, look at the target `foo` and see what it does. To only +run the analysis and not run the build execution phase, add the +`--nobuild` flag. + +``` +$ bazel $(STARTUP_FLAGS) build --nobuild //foo:foo +``` + +Next, see how much memory the whole Bazel instance consumes: + +``` +$ bazel $(STARTUP_FLAGS) info used-heap-size-after-gc +> 2594MB +``` + +Break it down by rule class by using `bazel dump --rules`: + +``` +$ bazel $(STARTUP_FLAGS) dump --rules +> + +RULE COUNT ACTIONS BYTES EACH +genrule 33,762 33,801 291,538,824 8,635 +config_setting 25,374 0 24,897,336 981 +filegroup 25,369 25,369 97,496,272 3,843 +cc_library 5,372 73,235 182,214,456 33,919 +proto_library 4,140 110,409 186,776,864 45,115 +android_library 2,621 36,921 218,504,848 83,366 +java_library 2,371 12,459 38,841,000 16,381 +_gen_source 719 2,157 9,195,312 12,789 +_check_proto_library_deps 719 668 1,835,288 2,552 +... (more output) +``` + +Look at where the memory is going by producing a `pprof` file +using `bazel dump --skylark_memory`: + +``` +$ bazel $(STARTUP_FLAGS) dump --skylark_memory=$HOME/prof.gz +> Dumping Starlark heap to: /usr/local/google/home/$USER/prof.gz +``` + +Use the `pprof` tool to investigate the heap. A good starting point is +getting a flame graph by using `pprof -flame $HOME/prof.gz`. + +Get `pprof` from [https://github.com/google/pprof](https://github.com/google/pprof). + +Get a text dump of the hottest call sites annotated with lines: + +``` +$ pprof -text -lines $HOME/prof.gz +> + flat flat% sum% cum cum% + 146.11MB 19.64% 19.64% 146.11MB 19.64% android_library <native>:-1 + 113.02MB 15.19% 34.83% 113.02MB 15.19% genrule <native>:-1 + 74.11MB 9.96% 44.80% 74.11MB 9.96% glob <native>:-1 + 55.98MB 7.53% 52.32% 55.98MB 7.53% filegroup <native>:-1 + 53.44MB 7.18% 59.51% 53.44MB 7.18% sh_test <native>:-1 + 26.55MB 3.57% 63.07% 26.55MB 3.57% _generate_foo_files /foo/tc/tc.bzl:491 + 26.01MB 3.50% 66.57% 26.01MB 3.50% _build_foo_impl /foo/build_test.bzl:78 + 22.01MB 2.96% 69.53% 22.01MB 2.96% _build_foo_impl /foo/build_test.bzl:73 + ... (more output) +``` diff --git a/rules/rules-tutorial.mdx b/rules/rules-tutorial.mdx new file mode 100644 index 0000000..4c6698e --- /dev/null +++ b/rules/rules-tutorial.mdx @@ -0,0 +1,367 @@ +--- +title: 'Rules Tutorial' +--- + + + + +[Starlark](https://github.com/bazelbuild/starlark) is a Python-like +configuration language originally developed for use in Bazel and since adopted +by other tools. Bazel's `BUILD` and `.bzl` files are written in a dialect of +Starlark properly known as the "Build Language", though it is often simply +referred to as "Starlark", especially when emphasizing that a feature is +expressed in the Build Language as opposed to being a built-in or "native" part +of Bazel. Bazel augments the core language with numerous build-related functions +such as `glob`, `genrule`, `java_binary`, and so on. + +See the +[Bazel](/start/) and [Starlark](/extending/concepts) documentation for +more details, and the +[Rules SIG template](https://github.com/bazel-contrib/rules-template) as a +starting point for new rulesets. + +## The empty rule + +To create your first rule, create the file `foo.bzl`: + +```python +def _foo_binary_impl(ctx): + pass + +foo_binary = rule( + implementation = _foo_binary_impl, +) +``` + +When you call the [`rule`](lib/globals#rule) function, you +must define a callback function. The logic will go there, but you +can leave the function empty for now. The [`ctx`](lib/ctx) argument +provides information about the target. + +You can load the rule and use it from a `BUILD` file. + +Create a `BUILD` file in the same directory: + +```python +load(":foo.bzl", "foo_binary") + +foo_binary(name = "bin") +``` + +Now, the target can be built: + +``` +$ bazel build bin +INFO: Analyzed target //:bin (2 packages loaded, 17 targets configured). +INFO: Found 1 target... +Target //:bin up-to-date (nothing to build) +``` + +Even though the rule does nothing, it already behaves like other rules: it has a +mandatory name, it supports common attributes like `visibility`, `testonly`, and +`tags`. + +## Evaluation model + +Before going further, it's important to understand how the code is evaluated. + +Update `foo.bzl` with some print statements: + +```python +def _foo_binary_impl(ctx): + print("analyzing", ctx.label) + +foo_binary = rule( + implementation = _foo_binary_impl, +) + +print("bzl file evaluation") +``` + +and BUILD: + +```python +load(":foo.bzl", "foo_binary") + +print("BUILD file") +foo_binary(name = "bin1") +foo_binary(name = "bin2") +``` + +[`ctx.label`](lib/ctx#label) +corresponds to the label of the target being analyzed. The `ctx` object has +many useful fields and methods; you can find an exhaustive list in the +[API reference](lib/ctx). + +Query the code: + +``` +$ bazel query :all +DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation +DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file +//:bin2 +//:bin1 +``` + +Make a few observations: + +* "bzl file evaluation" is printed first. Before evaluating the `BUILD` file, + Bazel evaluates all the files it loads. If multiple `BUILD` files are loading + foo.bzl, you would see only one occurrence of "bzl file evaluation" because + Bazel caches the result of the evaluation. +* The callback function `_foo_binary_impl` is not called. Bazel query loads + `BUILD` files, but doesn't analyze targets. + +To analyze the targets, use the [`cquery`](/query/cquery) ("configured +query") or the `build` command: + +``` +$ bazel build :all +DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin1 +DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin2 +INFO: Analyzed 2 targets (0 packages loaded, 0 targets configured). +INFO: Found 2 targets... +``` + +As you can see, `_foo_binary_impl` is now called twice - once for each target. + +Notice that neither "bzl file evaluation" nor "BUILD file" are printed again, +because the evaluation of `foo.bzl` is cached after the call to `bazel query`. +Bazel only emits `print` statements when they are actually executed. + +## Creating a file + +To make your rule more useful, update it to generate a file. First, declare the +file and give it a name. In this example, create a file with the same name as +the target: + +```python +ctx.actions.declare_file(ctx.label.name) +``` + +If you run `bazel build :all` now, you will get an error: + +``` +The following files have no generating action: +bin2 +``` + +Whenever you declare a file, you have to tell Bazel how to generate it by +creating an action. Use [`ctx.actions.write`](lib/actions#write), +to create a file with the given content. + +```python +def _foo_binary_impl(ctx): + out = ctx.actions.declare_file(ctx.label.name) + ctx.actions.write( + output = out, + content = "Hello\n", + ) +``` + +The code is valid, but it won't do anything: + +``` +$ bazel build bin1 +Target //:bin1 up-to-date (nothing to build) +``` + +The `ctx.actions.write` function registered an action, which taught Bazel +how to generate the file. But Bazel won't create the file until it is +actually requested. So the last thing to do is tell Bazel that the file +is an output of the rule, and not a temporary file used within the rule +implementation. + +```python +def _foo_binary_impl(ctx): + out = ctx.actions.declare_file(ctx.label.name) + ctx.actions.write( + output = out, + content = "Hello!\n", + ) + return [DefaultInfo(files = depset([out]))] +``` + +Look at the `DefaultInfo` and `depset` functions later. For now, +assume that the last line is the way to choose the outputs of a rule. + +Now, run Bazel: + +``` +$ bazel build bin1 +INFO: Found 1 target... +Target //:bin1 up-to-date: + bazel-bin/bin1 + +$ cat bazel-bin/bin1 +Hello! +``` + +You have successfully generated a file! + +## Attributes + +To make the rule more useful, add new attributes using +[the `attr` module](lib/attr) and update the rule definition. + +Add a string attribute called `username`: + +```python +foo_binary = rule( + implementation = _foo_binary_impl, + attrs = { + "username": attr.string(), + }, +) +``` + +Next, set it in the `BUILD` file: + +```python +foo_binary( + name = "bin", + username = "Alice", +) +``` + +To access the value in the callback function, use `ctx.attr.username`. For +example: + +```python +def _foo_binary_impl(ctx): + out = ctx.actions.declare_file(ctx.label.name) + ctx.actions.write( + output = out, + content = "Hello {}!\n".format(ctx.attr.username), + ) + return [DefaultInfo(files = depset([out]))] +``` + +Note that you can make the attribute mandatory or set a default value. Look at +the documentation of [`attr.string`](lib/attr#string). +You may also use other types of attributes, such as [boolean](lib/attr#bool) +or [list of integers](lib/attr#int_list). + +## Dependencies + +Dependency attributes, such as [`attr.label`](lib/attr#label) +and [`attr.label_list`](lib/attr#label_list), +declare a dependency from the target that owns the attribute to the target whose +label appears in the attribute's value. This kind of attribute forms the basis +of the target graph. + +In the `BUILD` file, the target label appears as a string object, such as +`//pkg:name`. In the implementation function, the target will be accessible as a +[`Target`](lib/Target) object. For example, view the files returned +by the target using [`Target.files`](lib/Target#modules.Target.files). + +### Multiple files + +By default, only targets created by rules may appear as dependencies (such as a +`foo_library()` target). If you want the attribute to accept targets that are +input files (such as source files in the repository), you can do it with +`allow_files` and specify the list of accepted file extensions (or `True` to +allow any file extension): + +```python +"srcs": attr.label_list(allow_files = [".java"]), +``` + +The list of files can be accessed with `ctx.files.<attribute name>`. For +example, the list of files in the `srcs` attribute can be accessed through + +```python +ctx.files.srcs +``` + +### Single file + +If you need only one file, use `allow_single_file`: + +```python +"src": attr.label(allow_single_file = [".java"]) +``` + +This file is then accessible under `ctx.file.<attribute name>`: + +```python +ctx.file.src +``` + +## Create a file with a template + +You can create a rule that generates a .cc file based on a template. Also, you +can use `ctx.actions.write` to output a string constructed in the rule +implementation function, but this has two problems. First, as the template gets +bigger, it becomes more memory efficient to put it in a separate file and avoid +constructing large strings during the analysis phase. Second, using a separate +file is more convenient for the user. Instead, use +[`ctx.actions.expand_template`](lib/actions#expand_template), +which performs substitutions on a template file. + +Create a `template` attribute to declare a dependency on the template +file: + +```python +def _hello_world_impl(ctx): + out = ctx.actions.declare_file(ctx.label.name + ".cc") + ctx.actions.expand_template( + output = out, + template = ctx.file.template, + substitutions = {"{NAME}": ctx.attr.username}, + ) + return [DefaultInfo(files = depset([out]))] + +hello_world = rule( + implementation = _hello_world_impl, + attrs = { + "username": attr.string(default = "unknown person"), + "template": attr.label( + allow_single_file = [".cc.tpl"], + mandatory = True, + ), + }, +) +``` + +Users can use the rule like this: + +```python +hello_world( + name = "hello", + username = "Alice", + template = "file.cc.tpl", +) + +cc_binary( + name = "hello_bin", + srcs = [":hello"], +) +``` + +If you don't want to expose the template to the end-user and always use the +same one, you can set a default value and make the attribute private: + +```python + "_template": attr.label( + allow_single_file = True, + default = "file.cc.tpl", + ), +``` + +Attributes that start with an underscore are private and cannot be set in a +`BUILD` file. The template is now an _implicit dependency_: Every `hello_world` +target has a dependency on this file. Don't forget to make this file visible +to other packages by updating the `BUILD` file and using +[`exports_files`](/reference/be/functions#exports_files): + +```python +exports_files(["file.cc.tpl"]) +``` + +## Going further + +* Take a look at the [reference documentation for rules](/extending/rules#contents). +* Get familiar with [depsets](/extending/depsets). +* Check out the [examples repository](https://github.com/bazelbuild/examples/tree/master/rules) + which includes additional examples of rules. diff --git a/rules/testing.mdx b/rules/testing.mdx new file mode 100644 index 0000000..2996e08 --- /dev/null +++ b/rules/testing.mdx @@ -0,0 +1,474 @@ +--- +title: 'Testing' +--- + + + +There are several different approaches to testing Starlark code in Bazel. This +page gathers the current best practices and frameworks by use case. + +## Testing rules + +[Skylib](https://github.com/bazelbuild/bazel-skylib) has a test framework called +[`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/lib/unittest.bzl) +for checking the analysis-time behavior of rules, such as their actions and +providers. Such tests are called "analysis tests" and are currently the best +option for testing the inner workings of rules. + +Some caveats: + +* Test assertions occur within the build, not a separate test runner process. + Targets that are created by the test must be named such that they do not + collide with targets from other tests or from the build. An error that + occurs during the test is seen by Bazel as a build breakage rather than a + test failure. + +* It requires a fair amount of boilerplate to set up the rules under test and + the rules containing test assertions. This boilerplate may seem daunting at + first. It helps to [keep in mind](/extending/concepts#evaluation-model) that macros + are evaluated and targets generated during the loading phase, while rule + implementation functions don't run until later, during the analysis phase. + +* Analysis tests are intended to be fairly small and lightweight. Certain + features of the analysis testing framework are restricted to verifying + targets with a maximum number of transitive dependencies (currently 500). + This is due to performance implications of using these features with larger + tests. + +The basic principle is to define a testing rule that depends on the +rule-under-test. This gives the testing rule access to the rule-under-test's +providers. + +The testing rule's implementation function carries out assertions. If there are +any failures, these are not raised immediately by calling `fail()` (which would +trigger an analysis-time build error), but rather by storing the errors in a +generated script that fails at test execution time. + +See below for a minimal toy example, followed by an example that checks actions. + +### Minimal example + +`//mypkg/myrules.bzl`: + +```python +MyInfo = provider(fields = { + "val": "string value", + "out": "output File", +}) + +def _myrule_impl(ctx): + """Rule that just generates a file and returns a provider.""" + out = ctx.actions.declare_file(ctx.label.name + ".out") + ctx.actions.write(out, "abc") + return [MyInfo(val="some value", out=out)] + +myrule = rule( + implementation = _myrule_impl, +) +``` + +`//mypkg/myrules_test.bzl`: + + +```python +load("@bazel_skylib//lib:unittest.bzl", "asserts", "analysistest") +load(":myrules.bzl", "myrule", "MyInfo") + +# ==== Check the provider contents ==== + +def _provider_contents_test_impl(ctx): + env = analysistest.begin(ctx) + + target_under_test = analysistest.target_under_test(env) + # If preferred, could pass these values as "expected" and "actual" keyword + # arguments. + asserts.equals(env, "some value", target_under_test[MyInfo].val) + + # If you forget to return end(), you will get an error about an analysis + # test needing to return an instance of AnalysisTestResultInfo. + return analysistest.end(env) + +# Create the testing rule to wrap the test logic. This must be bound to a global +# variable, not called in a macro's body, since macros get evaluated at loading +# time but the rule gets evaluated later, at analysis time. Since this is a test +# rule, its name must end with "_test". +provider_contents_test = analysistest.make(_provider_contents_test_impl) + +# Macro to setup the test. +def _test_provider_contents(): + # Rule under test. Be sure to tag 'manual', as this target should not be + # built using `:all` except as a dependency of the test. + myrule(name = "provider_contents_subject", tags = ["manual"]) + # Testing rule. + provider_contents_test(name = "provider_contents_test", + target_under_test = ":provider_contents_subject") + # Note the target_under_test attribute is how the test rule depends on + # the real rule target. + +# Entry point from the BUILD file; macro for running each test case's macro and +# declaring a test suite that wraps them together. +def myrules_test_suite(name): + # Call all test functions and wrap their targets in a suite. + _test_provider_contents() + # ... + + native.test_suite( + name = name, + tests = [ + ":provider_contents_test", + # ... + ], + ) +``` + +`//mypkg/BUILD`: + +```python +load(":myrules.bzl", "myrule") +load(":myrules_test.bzl", "myrules_test_suite") + +# Production use of the rule. +myrule( + name = "mytarget", +) + +# Call a macro that defines targets that perform the tests at analysis time, +# and that can be executed with "bazel test" to return the result. +myrules_test_suite(name = "myrules_test") +``` + +The test can be run with `bazel test //mypkg:myrules_test`. + +Aside from the initial `load()` statements, there are two main parts to the +file: + +* The tests themselves, each of which consists of 1) an analysis-time + implementation function for the testing rule, 2) a declaration of the + testing rule via `analysistest.make()`, and 3) a loading-time function + (macro) for declaring the rule-under-test (and its dependencies) and testing + rule. If the assertions do not change between test cases, 1) and 2) may be + shared by multiple test cases. + +* The test suite function, which calls the loading-time functions for each + test, and declares a `test_suite` target bundling all tests together. + +For consistency, follow the recommended naming convention: Let `foo` stand for +the part of the test name that describes what the test is checking +(`provider_contents` in the above example). For example, a JUnit test method +would be named `testFoo`. + +Then: + +* the macro which generates the test and target under test should should be + named `_test_foo` (`_test_provider_contents`) + +* its test rule type should be named `foo_test` (`provider_contents_test`) + +* the label of the target of this rule type should be `foo_test` + (`provider_contents_test`) + +* the implementation function for the testing rule should be named + `_foo_test_impl` (`_provider_contents_test_impl`) + +* the labels of the targets of the rules under test and their dependencies + should be prefixed with `foo_` (`provider_contents_`) + +Note that the labels of all targets can conflict with other labels in the same +BUILD package, so it's helpful to use a unique name for the test. + +### Failure testing + +It may be useful to verify that a rule fails given certain inputs or in certain +state. This can be done using the analysis test framework: + +The test rule created with `analysistest.make` should specify `expect_failure`: + +```python +failure_testing_test = analysistest.make( + _failure_testing_test_impl, + expect_failure = True, +) +``` + +The test rule implementation should make assertions on the nature of the failure +that took place (specifically, the failure message): + +```python +def _failure_testing_test_impl(ctx): + env = analysistest.begin(ctx) + asserts.expect_failure(env, "This rule should never work") + return analysistest.end(env) +``` + +Also make sure that your target under test is specifically tagged 'manual'. +Without this, building all targets in your package using `:all` will result in a +build of the intentionally-failing target and will exhibit a build failure. With +'manual', your target under test will build only if explicitly specified, or as +a dependency of a non-manual target (such as your test rule): + +```python +def _test_failure(): + myrule(name = "this_should_fail", tags = ["manual"]) + + failure_testing_test(name = "failure_testing_test", + target_under_test = ":this_should_fail") + +# Then call _test_failure() in the macro which generates the test suite and add +# ":failure_testing_test" to the suite's test targets. +``` + +### Verifying registered actions + +You may want to write tests which make assertions about the actions that your +rule registers, for example, using `ctx.actions.run()`. This can be done in your +analysis test rule implementation function. An example: + +```python +def _inspect_actions_test_impl(ctx): + env = analysistest.begin(ctx) + + target_under_test = analysistest.target_under_test(env) + actions = analysistest.target_actions(env) + asserts.equals(env, 1, len(actions)) + action_output = actions[0].outputs.to_list()[0] + asserts.equals( + env, target_under_test.label.name + ".out", action_output.basename) + return analysistest.end(env) +``` + +Note that `analysistest.target_actions(env)` returns a list of +[`Action`](lib/Action) objects which represent actions registered by the +target under test. + +### Verifying rule behavior under different flags + +You may want to verify your real rule behaves a certain way given certain build +flags. For example, your rule may behave differently if a user specifies: + +```shell +bazel build //mypkg:real_target -c opt +``` + +versus + +```shell +bazel build //mypkg:real_target -c dbg +``` + +At first glance, this could be done by testing the target under test using the +desired build flags: + +```shell +bazel test //mypkg:myrules_test -c opt +``` + +But then it becomes impossible for your test suite to simultaneously contain a +test which verifies the rule behavior under `-c opt` and another test which +verifies the rule behavior under `-c dbg`. Both tests would not be able to run +in the same build! + +This can be solved by specifying the desired build flags when defining the test +rule: + +```python +myrule_c_opt_test = analysistest.make( + _myrule_c_opt_test_impl, + config_settings = { + "//command_line_option:compilation_mode": "opt", + }, +) +``` + +Normally, a target under test is analyzed given the current build flags. +Specifying `config_settings` overrides the values of the specified command line +options. (Any unspecified options will retain their values from the actual +command line). + +In the specified `config_settings` dictionary, command line flags must be +prefixed with a special placeholder value `//command_line_option:`, as is shown +above. + + +## Validating artifacts + +The main ways to check that your generated files are correct are: + +* You can write a test script in shell, Python, or another language, and + create a target of the appropriate `*_test` rule type. + +* You can use a specialized rule for the kind of test you want to perform. + +### Using a test target + +The most straightforward way to validate an artifact is to write a script and +add a `*_test` target to your BUILD file. The specific artifacts you want to +check should be data dependencies of this target. If your validation logic is +reusable for multiple tests, it should be a script that takes command line +arguments that are controlled by the test target's `args` attribute. Here's an +example that validates that the output of `myrule` from above is `"abc"`. + +`//mypkg/myrule_validator.sh`: + +```shell +if [ "$(cat $1)" = "abc" ]; then + echo "Passed" + exit 0 +else + echo "Failed" + exit 1 +fi +``` + +`//mypkg/BUILD`: + +```python +... + +myrule( + name = "mytarget", +) + +... + +# Needed for each target whose artifacts are to be checked. +sh_test( + name = "validate_mytarget", + srcs = [":myrule_validator.sh"], + args = ["$(location :mytarget.out)"], + data = [":mytarget.out"], +) +``` + +### Using a custom rule + +A more complicated alternative is to write the shell script as a template that +gets instantiated by a new rule. This involves more indirection and Starlark +logic, but leads to cleaner BUILD files. As a side-benefit, any argument +preprocessing can be done in Starlark instead of the script, and the script is +slightly more self-documenting since it uses symbolic placeholders (for +substitutions) instead of numeric ones (for arguments). + +`//mypkg/myrule_validator.sh.template`: + +```shell +if [ "$(cat %TARGET%)" = "abc" ]; then + echo "Passed" + exit 0 +else + echo "Failed" + exit 1 +fi +``` + +`//mypkg/myrule_validation.bzl`: + +```python +def _myrule_validation_test_impl(ctx): + """Rule for instantiating myrule_validator.sh.template for a given target.""" + exe = ctx.outputs.executable + target = ctx.file.target + ctx.actions.expand_template(output = exe, + template = ctx.file._script, + is_executable = True, + substitutions = { + "%TARGET%": target.short_path, + }) + # This is needed to make sure the output file of myrule is visible to the + # resulting instantiated script. + return [DefaultInfo(runfiles=ctx.runfiles(files=[target]))] + +myrule_validation_test = rule( + implementation = _myrule_validation_test_impl, + attrs = {"target": attr.label(allow_single_file=True), + # You need an implicit dependency in order to access the template. + # A target could potentially override this attribute to modify + # the test logic. + "_script": attr.label(allow_single_file=True, + default=Label("//mypkg:myrule_validator"))}, + test = True, +) +``` + +`//mypkg/BUILD`: + +```python +... + +myrule( + name = "mytarget", +) + +... + +# Needed just once, to expose the template. Could have also used export_files(), +# and made the _script attribute set allow_files=True. +filegroup( + name = "myrule_validator", + srcs = [":myrule_validator.sh.template"], +) + +# Needed for each target whose artifacts are to be checked. Notice that you no +# longer have to specify the output file name in a data attribute, or its +# $(location) expansion in an args attribute, or the label for the script +# (unless you want to override it). +myrule_validation_test( + name = "validate_mytarget", + target = ":mytarget", +) +``` + +Alternatively, instead of using a template expansion action, you could have +inlined the template into the .bzl file as a string and expanded it during the +analysis phase using the `str.format` method or `%`-formatting. + +## Testing Starlark utilities + +[Skylib](https://github.com/bazelbuild/bazel-skylib)'s +[`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/lib/unittest.bzl) +framework can be used to test utility functions (that is, functions that are +neither macros nor rule implementations). Instead of using `unittest.bzl`'s +`analysistest` library, `unittest` may be used. For such test suites, the +convenience function `unittest.suite()` can be used to reduce boilerplate. + +`//mypkg/myhelpers.bzl`: + +```python +def myhelper(): + return "abc" +``` + +`//mypkg/myhelpers_test.bzl`: + + +```python +load("@bazel_skylib//lib:unittest.bzl", "asserts", "unittest") +load(":myhelpers.bzl", "myhelper") + +def _myhelper_test_impl(ctx): + env = unittest.begin(ctx) + asserts.equals(env, "abc", myhelper()) + return unittest.end(env) + +myhelper_test = unittest.make(_myhelper_test_impl) + +# No need for a test_myhelper() setup function. + +def myhelpers_test_suite(name): + # unittest.suite() takes care of instantiating the testing rules and creating + # a test_suite. + unittest.suite( + name, + myhelper_test, + # ... + ) +``` + +`//mypkg/BUILD`: + +```python +load(":myhelpers_test.bzl", "myhelpers_test_suite") + +myhelpers_test_suite(name = "myhelpers_tests") +``` + +For more examples, see Skylib's own [tests](https://github.com/bazelbuild/bazel-skylib/blob/main/tests/BUILD). diff --git a/rules/verbs-tutorial.mdx b/rules/verbs-tutorial.mdx new file mode 100644 index 0000000..db7757e --- /dev/null +++ b/rules/verbs-tutorial.mdx @@ -0,0 +1,177 @@ +--- +title: 'Using Macros to Create Custom Verbs' +--- + + + +Day-to-day interaction with Bazel happens primarily through a few commands: +`build`, `test`, and `run`. At times, though, these can feel limited: you may +want to push packages to a repository, publish documentation for end-users, or +deploy an application with Kubernetes. But Bazel doesn't have a `publish` or +`deploy` command – where do these actions fit in? + +## The bazel run command + +Bazel's focus on hermeticity, reproducibility, and incrementality means the +`build` and `test` commands aren't helpful for the above tasks. These actions +may run in a sandbox, with limited network access, and aren't guaranteed to be +re-run with every `bazel build`. + +Instead, rely on `bazel run`: the workhorse for tasks that you *want* to have +side effects. Bazel users are accustomed to rules that create executables, and +rule authors can follow a common set of patterns to extend this to +"custom verbs". + +### In the wild: rules_k8s +For example, consider [`rules_k8s`](https://github.com/bazelbuild/rules_k8s), +the Kubernetes rules for Bazel. Suppose you have the following target: + +```python +# BUILD file in //application/k8s +k8s_object( + name = "staging", + kind = "deployment", + cluster = "testing", + template = "deployment.yaml", +) +``` + +The [`k8s_object` rule](https://github.com/bazelbuild/rules_k8s#usage) builds a +standard Kubernetes YAML file when `bazel build` is used on the `staging` +target. However, the additional targets are also created by the `k8s_object` +macro with names like `staging.apply` and `:staging.delete`. These build +scripts to perform those actions, and when executed with `bazel run +staging.apply`, these behave like our own `bazel k8s-apply` or `bazel +k8s-delete` commands. + +### Another example: ts_api_guardian_test + +This pattern can also be seen in the Angular project. The +[`ts_api_guardian_test` macro](https://github.com/angular/angular/blob/16ac611a8410e6bcef8ffc779f488ca4fa102155/tools/ts-api-guardian/index.bzl#L22) +produces two targets. The first is a standard `nodejs_test` target which compares +some generated output against a "golden" file (that is, a file containing the +expected output). This can be built and run with a normal `bazel +test` invocation. In `angular-cli`, you can run [one such +target](https://github.com/angular/angular-cli/blob/e1269cb520871ee29b1a4eec6e6c0e4a94f0b5fc/etc/api/BUILD) +with `bazel test //etc/api:angular_devkit_core_api`. + +Over time, this golden file may need to be updated for legitimate reasons. +Updating this manually is tedious and error-prone, so this macro also provides +a `nodejs_binary` target that updates the golden file, instead of comparing +against it. Effectively, the same test script can be written to run in "verify" +or "accept" mode, based on how it's invoked. This follows the same pattern +you've learned already: there is no native `bazel test-accept` command, but the +same effect can be achieved with +`bazel run //etc/api:angular_devkit_core_api.accept`. + +This pattern can be quite powerful, and turns out to be quite common once you +learn to recognize it. + +## Adapting your own rules + +[Macros](/extending/macros) are the heart of this pattern. Macros are used like +rules, but they can create several targets. Typically, they will create a +target with the specified name which performs the primary build action: perhaps +it builds a normal binary, a Docker image, or an archive of source code. In +this pattern, additional targets are created to produce scripts performing side +effects based on the output of the primary target, like publishing the +resulting binary or updating the expected test output. + +To illustrate this, wrap an imaginary rule that generates a website with +[Sphinx](https://www.sphinx-doc.org) with a macro to create an additional +target that allows the user to publish it when ready. Consider the following +existing rule for generating a website with Sphinx: + +```python +_sphinx_site = rule( + implementation = _sphinx_impl, + attrs = {"srcs": attr.label_list(allow_files = [".rst"])}, +) +``` + +Next, consider a rule like the following, which builds a script that, when run, +publishes the generated pages: + +```python +_sphinx_publisher = rule( + implementation = _publish_impl, + attrs = { + "site": attr.label(), + "_publisher": attr.label( + default = "//internal/sphinx:publisher", + executable = True, + ), + }, + executable = True, +) +``` + +Finally, define the following symbolic macro (available in Bazel 8 or newer) to +create targets for both of the above rules together: + +```starlark +def _sphinx_site_impl(name, visibility, srcs, **kwargs): + # This creates the primary target, producing the Sphinx-generated HTML. We + # set `visibility = visibility` to make it visible to callers of the + # macro. + _sphinx_site(name = name, visibility = visibility, srcs = srcs, **kwargs) + # This creates the secondary target, which produces a script for publishing + # the site generated above. We don't want it to be visible to callers of + # our macro, so we omit visibility for it. + _sphinx_publisher(name = "%s.publish" % name, site = name, **kwargs) + +sphinx_site = macro( + implementation = _sphinx_site_impl, + attrs = {"srcs": attr.label_list(allow_files = [".rst"])}, + # Inherit common attributes like tags and testonly + inherit_attrs = "common", +) +``` + +Or, if you need to support Bazel releases older than Bazel 8, you would instead +define a legacy macro: + +```starlark +def sphinx_site(name, srcs = [], **kwargs): + # This creates the primary target, producing the Sphinx-generated HTML. + _sphinx_site(name = name, srcs = srcs, **kwargs) + # This creates the secondary target, which produces a script for publishing + # the site generated above. + _sphinx_publisher(name = "%s.publish" % name, site = name, **kwargs) +``` + +In the `BUILD` files, use the macro as though it just creates the primary +target: + +```python +sphinx_site( + name = "docs", + srcs = ["index.md", "providers.md"], +) +``` + +In this example, a "docs" target is created, just as though the macro were a +standard, single Bazel rule. When built, the rule generates some configuration +and runs Sphinx to produce an HTML site, ready for manual inspection. However, +an additional "docs.publish" target is also created, which builds a script for +publishing the site. Once you check the output of the primary target, you can +use `bazel run :docs.publish` to publish it for public consumption, just like +an imaginary `bazel publish` command. + +It's not immediately obvious what the implementation of the `_sphinx_publisher` +rule might look like. Often, actions like this write a _launcher_ shell script. +This method typically involves using +[`ctx.actions.expand_template`](lib/actions#expand_template) +to write a very simple shell script, in this case invoking the publisher binary +with a path to the output of the primary target. This way, the publisher +implementation can remain generic, the `_sphinx_site` rule can just produce +HTML, and this small script is all that's necessary to combine the two +together. + +In `rules_k8s`, this is indeed what `.apply` does: +[`expand_template`](https://github.com/bazelbuild/rules_k8s/blob/f10e7025df7651f47a76abf1db5ade1ffeb0c6ac/k8s/object.bzl#L213-L241) +writes a very simple Bash script, based on +[`apply.sh.tpl`](https://github.com/bazelbuild/rules_k8s/blob/f10e7025df7651f47a76abf1db5ade1ffeb0c6ac/k8s/apply.sh.tpl), +which runs `kubectl` with the output of the primary target. This script can +then be build and run with `bazel run :staging.apply`, effectively providing a +`k8s-apply` command for `k8s_object` targets. From 54b7e73f3d2a5aa694a2f5234aa5bbb0b032d903 Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sun, 12 Oct 2025 19:29:01 -0700 Subject: [PATCH 13/14] fix more broken links --- copy-upstream-docs.sh | 3 +++ docs.json | 10 +--------- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/copy-upstream-docs.sh b/copy-upstream-docs.sh index 3a23a22..e45aa66 100755 --- a/copy-upstream-docs.sh +++ b/copy-upstream-docs.sh @@ -50,7 +50,10 @@ query/language.mdx query/quickstart.mdx reference/flag-cheatsheet.mdx reference/test-encyclopedia.mdx +reference/command-line-reference.mdx reference/be/be-nav.mdx +reference/be/functions.mdx +reference/be/platforms-and-toolchains.mdx release/rolling.mdx remote/ci.mdx remote/dynamic.mdx diff --git a/docs.json b/docs.json index 145b9de..89ac54c 100644 --- a/docs.json +++ b/docs.json @@ -169,24 +169,16 @@ "reference/be/c-cpp", "reference/be/common-definitions", "reference/be/extra-actions", - "reference/be/functions", "reference/be/general", "reference/be/java", "reference/be/make-variables", "reference/be/objective-c", "reference/be/overview", - "reference/be/platforms-and-toolchains", - "reference/be/protocol-buffers", + "reference/be/protocol-buffer", "reference/be/python", "reference/be/shell" ] }, - { - "group": "Command line reference", - "pages": [ - "reference/command-line-reference" - ] - }, { "group": "Glossary", "pages": [ From 93ae8aa2c8b2216bb487f0fba254207bd2a9c8db Mon Sep 17 00:00:00 2001 From: Alan Mond <alan.mond@gmail.com> Date: Sun, 12 Oct 2025 19:35:06 -0700 Subject: [PATCH 14/14] cleanup --- CLAUDE.md | 50 ------------------------------------ configure/best-practices.mdx | 1 - html2md_converter/main.go | 2 +- html_mdx_converter_test.sh | 2 +- 4 files changed, 2 insertions(+), 53 deletions(-) delete mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index a6c97c3..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,50 +0,0 @@ -# Mintlify documentation - -## Working relationship -- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so -- ALWAYS ask for clarification rather than making assumptions -- NEVER lie, guess, or make up anything - -## Project context -- Format: MDX files with YAML frontmatter -- Config: docs.json for navigation, theme, settings -- Components: Mintlify components - -## Content strategy -- Document just enough for user success - not too much, not too little -- Prioritize accuracy and usability -- Make content evergreen when possible -- Search for existing content before adding anything new. Avoid duplication unless it is done for a strategic reason -- Check existing patterns for consistency -- Start by making the smallest reasonable changes - -## docs.json - -- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation - -## Frontmatter requirements for pages -- title: Clear, descriptive page title -- description: Concise summary for SEO/navigation - -## Writing standards -- Second-person voice ("you") -- Prerequisites at start of procedural content -- Test all code examples before publishing -- Match style and formatting of existing pages -- Include both basic and advanced use cases -- Language tags on all code blocks -- Alt text on all images -- Relative paths for internal links - -## Git workflow -- NEVER use --no-verify when committing -- Ask how to handle uncommitted changes before starting -- Create a new branch when no clear branch exists for changes -- Commit frequently throughout development -- NEVER skip or disable pre-commit hooks - -## Do not -- Skip frontmatter on any MDX file -- Use absolute URLs for internal links -- Include untested code examples -- Make assumptions - always ask for clarification \ No newline at end of file diff --git a/configure/best-practices.mdx b/configure/best-practices.mdx index 431b686..00b4391 100644 --- a/configure/best-practices.mdx +++ b/configure/best-practices.mdx @@ -80,7 +80,6 @@ and add `user.bazelrc` to your `.gitignore`. The open-source [bazelrc-preset.bzl](https://github.com/bazel-contrib/bazelrc-preset.bzl) - generates a custom bazelrc file that matches your Bazel version and provides a preset of recommended flags. diff --git a/html2md_converter/main.go b/html2md_converter/main.go index be47dd1..7bf9945 100644 --- a/html2md_converter/main.go +++ b/html2md_converter/main.go @@ -166,4 +166,4 @@ func copyFile(f *zip.File, outputDir string, outputPath string) error { func changeExtension(filename, newExt string) string { ext := filepath.Ext(filename) return filename[:len(filename)-len(ext)] + newExt -} \ No newline at end of file +} diff --git a/html_mdx_converter_test.sh b/html_mdx_converter_test.sh index bab286d..e5e4a04 100755 --- a/html_mdx_converter_test.sh +++ b/html_mdx_converter_test.sh @@ -85,4 +85,4 @@ fi # Run AWK transformation ./copy-upstream-docs.sh -rm -rf "$OUTPUT_DIR" \ No newline at end of file +rm -rf "$OUTPUT_DIR"